xonecas.io
64875
Mc

mini-coder / commit ee72662

fix: strengthen RALPH mode prompt to prevent immediate /ralph without tool calls

Codex was outputting /ralph immediately without making any tool calls.
The previous wording described the exit condition first, which the model
treated as something to satisfy right away. The new wording leads with
an explicit prohibition on outputting /ralph before using tools.

Sean2026-03-01 ee72662c8458b0833d8f1528059bc25099d131bd parent 291edb7

4 files changed

plan-code-health.md+169−0
@@ -0,0 +1,169 @@
1+# Code Health Remediation Plan
2+
3+## Goal
4+Address maintainability and reliability issues identified in `code-health.md` with low-risk, incremental refactors that keep behavior stable.
5+
6+## Constraints
7+- Keep `mini-coder-idea.md` and `README.md` unchanged.
8+- Prefer small PR-sized changes with passing tests after each step.
9+- Preserve current CLI behavior while improving structure.
10+
11+## Workstreams
12+
13+### 1) Decompose `src/agent/agent.ts` (High)
14+**Outcome:** `runAgent` remains orchestration entrypoint; responsibilities split into focused modules.
15+
16+**Steps:**
17+1. Add `src/agent/reporter.ts` interface (narrow surface for output/status/tool events).
18+2. Extract session lifecycle + turn loop into `src/agent/session-runner.ts`.
19+3. Extract subagent execution into `src/agent/subagent-runner.ts`.
20+4. Extract snapshot/undo helpers into `src/agent/undo-snapshot.ts`.
21+5. Extract user input processing into `src/agent/input-loop.ts`.
22+6. Keep `agent.ts` as composition/wiring file only.
23+
24+**Checks:**
25+- Add/adjust unit tests around orchestration boundaries.
26+- Ensure no behavior regressions in interrupts, resume, and tool-call flows.
27+
28+---
29+
30+### 2) Decompose `src/cli/output.ts` (High)
31+**Outcome:** Rendering responsibilities isolated and testable.
32+
33+**Target modules:**
34+- `src/cli/spinner.ts`
35+- `src/cli/tool-render.ts`
36+- `src/cli/stream-render.ts`
37+- `src/cli/status-bar.ts`
38+- `src/cli/error-render.ts`
39+- `src/cli/output.ts` as facade
40+
41+**Steps:**
42+1. Extract pure formatting helpers first (no IO).
43+2. Extract spinner lifecycle module.
44+3. Extract stream queue/tick/flush behavior.
45+4. Keep compatibility exports in `output.ts` to avoid broad callsite churn.
46+
47+**Checks:**
48+- Add focused tests for formatting + stream behavior.
49+- Verify terminal rendering remains stable manually.
50+
51+---
52+
53+### 3) Introduce `TerminalIO` abstraction (Medium)
54+**Outcome:** Centralized process/TTY interactions and signal lifecycle.
55+
56+**Steps:**
57+1. Create `src/cli/terminal-io.ts` with methods for stdout/stderr writes, raw mode, signal subscriptions.
58+2. Replace direct `process.*` use in output/input stack with injected `TerminalIO`.
59+3. Centralize signal registration/unregistration in one lifecycle owner.
60+
61+**Checks:**
62+- Add unit tests for signal registration cleanup semantics.
63+- Confirm no stuck raw-mode edge cases.
64+
65+---
66+
67+### 4) Split DB layer by domain (Medium)
68+**Outcome:** Reduced blast radius and clearer data ownership.
69+
70+**Target modules:**
71+- `src/session/db/connection.ts`
72+- `src/session/db/session-repo.ts`
73+- `src/session/db/message-repo.ts`
74+- `src/session/db/settings-repo.ts`
75+- `src/session/db/mcp-repo.ts`
76+- `src/session/db/snapshot-repo.ts`
77+- `src/session/db/index.ts` (facade exports)
78+
79+**Steps:**
80+1. Move code without behavior changes.
81+2. Keep SQL and schema unchanged initially.
82+3. Replace direct `JSON.parse` in message loading with guarded parser:
83+ - skip malformed rows
84+ - emit diagnostic via logger/reporter
85+
86+**Checks:**
87+- Add tests for malformed payload handling.
88+- Validate existing DB tests still pass.
89+
90+---
91+
92+### 5) Shared markdown config loader (Medium)
93+**Outcome:** Remove duplication across agents/skills/custom-commands.
94+
95+**Steps:**
96+1. Create `src/cli/load-markdown-configs.ts` with parameterized layout strategy.
97+2. Migrate:
98+ - `src/cli/agents.ts`
99+ - `src/cli/skills.ts`
100+ - `src/cli/custom-commands.ts`
101+3. Keep precedence rules identical (built-in/user/project).
102+4. Preserve existing frontmatter semantics.
103+
104+**Checks:**
105+- Reuse/expand existing loader tests to cover parity.
106+
107+---
108+
109+### 6) Runtime/UI decoupling via reporter boundary (Medium)
110+**Outcome:** Core runtime no longer depends directly on terminal rendering.
111+
112+**Steps:**
113+1. Define domain events or reporter interface in `src/agent/reporter.ts`.
114+2. Implement CLI reporter adapter in `src/cli/output-reporter.ts`.
115+3. Replace direct output calls in agent runtime with reporter calls.
116+
117+**Checks:**
118+- Add tests using test reporter to assert emitted events.
119+
120+---
121+
122+### 7) Error observability and silent catches (Medium)
123+**Outcome:** Non-fatal failures become diagnosable without crashing.
124+
125+**Steps:**
126+1. Find empty/broad catches in agent/output/loaders.
127+2. Add debug-level diagnostics with contextual metadata.
128+3. Keep user-facing behavior unchanged unless critical.
129+
130+**Checks:**
131+- Validate noisy paths are still quiet at normal verbosity.
132+
133+---
134+
135+### 8) Startup FS sync usage (Low/Deferred)
136+**Outcome:** Optional responsiveness improvement if startup cost grows.
137+
138+**Steps:**
139+1. Measure startup and config-loading time first.
140+2. If needed, move high-volume file scanning to async or cache results with invalidation.
141+
142+---
143+
144+### 9) Test hygiene cleanup (Low)
145+**Outcome:** Cleaner CI output.
146+
147+**Steps:**
148+1. Remove `console.log` skip notices in `src/tools/shell.test.ts`.
149+2. Use test-framework-native skip annotations/helpers.
150+
151+---
152+
153+## Execution Order (recommended)
154+1. Reporter interface (foundation for later decoupling).
155+2. `agent.ts` decomposition.
156+3. `output.ts` decomposition.
157+4. Shared config loader extraction.
158+5. DB module split + safe JSON parsing.
159+6. TerminalIO + centralized signals.
160+7. Silent catch diagnostics.
161+8. Test hygiene and any deferred FS optimization.
162+
163+## Definition of Done
164+- `bun run typecheck && bun run format && bun run lint && bun test` passes.
165+- No behavior regressions in interactive CLI flows.
166+- `agent.ts` and `output.ts` materially reduced in size/responsibility.
167+- Config loader duplication removed.
168+- Message loading resilient to malformed JSON rows.
169+- New abstractions documented in code comments where non-obvious.
src/agent/agent.ts+1−1
@@ -518,7 +518,7 @@ export async function runAgent(opts: AgentOptions): Promise<void> {
518518 const coreContent = planMode
519519 ? `${resolvedText}\n\n<system-message>PLAN MODE ACTIVE: Help the user gather context for the plan -- READ ONLY</system-message>`
520520 : ralphMode
521- ? `${resolvedText}\n\n<system-message>RALPH MODE: You are in an autonomous loop. Output exactly \`/ralph\` as your final message only after you have made all requested changes AND verified tests pass. Passing tests alone does not mean the task is complete — you must first do all the work. Otherwise, keep working.</system-message>`
521+ ? `${resolvedText}\n\n<system-message>RALPH MODE: You are in an autonomous loop. You MUST use tools to complete the task above before outputting \`/ralph\`. Do NOT output \`/ralph\` without first making tool calls and doing the work. Only output \`/ralph\` as your final message once all changes are made and verified.</system-message>`
522522 : resolvedText;
523523
524524 // Build the message content — multi-part when images are present
src/llm-api/turn.test.ts+26−0
@@ -0,0 +1,26 @@
1+import { describe, expect, test } from "bun:test";
2+import { isOpenAIGPT } from "./turn.ts";
3+
4+describe("isOpenAIGPT", () => {
5+ test("matches openai/gpt-* models", () => {
6+ expect(isOpenAIGPT("openai/gpt-4o")).toBe(true);
7+ expect(isOpenAIGPT("openai/gpt-4o-mini")).toBe(true);
8+ expect(isOpenAIGPT("openai/gpt-5.3-codex")).toBe(true);
9+ });
10+
11+ test("matches zen/gpt-* models", () => {
12+ expect(isOpenAIGPT("zen/gpt-5.3-codex")).toBe(true);
13+ expect(isOpenAIGPT("zen/gpt-4o")).toBe(true);
14+ });
15+
16+ test("does not match non-gpt openai models", () => {
17+ expect(isOpenAIGPT("openai/o3")).toBe(false);
18+ expect(isOpenAIGPT("openai/o1-mini")).toBe(false);
19+ });
20+
21+ test("does not match other providers", () => {
22+ expect(isOpenAIGPT("anthropic/claude-sonnet-4-5")).toBe(false);
23+ expect(isOpenAIGPT("google/gemini-2.0-flash")).toBe(false);
24+ expect(isOpenAIGPT("zen/claude-sonnet-4-6")).toBe(false);
25+ });
26+});
src/llm-api/turn.ts+1−1
@@ -67,7 +67,7 @@ function toCoreTool(
6767 * the Responses API and honours the `instructions` provider option as the
6868 * authoritative system prompt (rather than a system-role message in `input`).
6969 */
70-function isOpenAIGPT(modelString: string): boolean {
70+export function isOpenAIGPT(modelString: string): boolean {
7171 const slashIdx = modelString.indexOf("/");
7272 const provider =
7373 slashIdx === -1 ? modelString : modelString.slice(0, slashIdx);