mini-coder 0.0.9 → 0.0.11

package/hanging-bug.md

@@ -69,6 +69,7 @@ So this is now proven in your codepath:
 *   When a command times out, `proc.kill("SIGTERM")` only kills the parent process (e.g., `bash`). Any child processes (e.g., `bun`) become orphaned but stay alive, holding the write end of the `stdout`/`stderr` pipes open. 
 *   Because the pipe never closes, `await reader.read()` inside `collectStream()` hangs indefinitely. 
 *   Because `collectStream()` never resolves, the tool execution never finishes, `tool-result` is never yielded, and the stream goes completely silent while the spinner stays stuck on "shell".
+   - **FIXED**
 
 ### Root Cause 2: Hangs spinning on `"thinking"`
 **Proof in code:** `src/llm-api/turn.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.9",
+	"version": "0.0.11",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",

package/codex-lazy-fix.md

@@ -1,76 +0,0 @@
-# Codex Autonomy Issues & Fix Analysis
-
-## Behaviours
-When using `zen/gpt-5.3-codex` as the agent, the model consistently exhibits "lazy" or permission-seeking behaviour. Specifically:
-1. **Initial Compliance**: It starts by reading files or globbing the directory.
-2. **Immediate Stall**: Instead of executing edits or implementing the plan, it outputs a multi-paragraph text explaining what it *plans* to do and ends the turn.
-3. **Permission Seeking**: It explicitly asks the user for permission (e.g., "Reply **'proceed'** and I'll start implementing batch 1").
-4. **Ralph Mode Incompatibility**: In `/ralph` mode, the agent loops continuously. Because it restarts with a fresh context on each loop and stalls after gathering context, it never actually writes any files. It just loops through the same read-and-plan phase until it hits the max iteration limit.
-5. **Model Differences**: Both Claude and Gemini models do not exhibit this behaviour. They are not subjected to the same conversational RLHF that pushes the model to ask the user to double check its work.
-
-## Root Cause Analysis
-An analysis of both OpenAI's open-source `codex-rs` client and `opencode` source code reveals that Codex models (like `gpt-5.3-codex`) are highly RLHF-tuned for safety and collaborative pair-programming. By default, the model prefers to break tasks into chunks and explicitly ask for sign-off.
-
-To override this, the model requires three things which `mini-coder` was failing to provide correctly:
-
-### 1. Dual-Anchored System Prompts (`system` + `instructions`)
-`mini-coder` implemented a check `useInstructions` that placed the system prompt into the `instructions` field of the `/v1/responses` API payload. However, doing so stripped the `system` role message from the conversation context (`input` array).
-
-By looking at `opencode` and `codex-rs`, they both ensure that the context array *also* contains the system prompt:
-- `opencode` maps its environment variables and system instructions to `role: "system"` (or `role: "developer"`) inside `input.messages`, **while also** passing behavioral instructions to the `instructions` field in the API payload.
-- `codex-rs` directly injects `role: "developer"` into the message list (as seen in `codex-rs/core/src/compact.rs` and their memory tracing implementations).
-
-Without the `system` / `developer` message anchored at the start of the `input` array, the AI SDK and the model deprioritized the standalone `instructions` field, allowing the model's base permission-seeking behaviors to take over.
-
-### 2. Explicit "Do Not Ask" Directives
-Both `opencode` and `codex-rs` employ heavy anti-permission prompts.
-- **Opencode** (`session/prompt/codex_header.txt`):
-  > "- Default: do the work without asking questions... Never ask permission questions like 'Should I proceed?' or 'Do you want me to run tests?'; proceed with the most reasonable option and mention what you did."
-- **Codex-RS** (`core/templates/model_instructions/gpt-5.2-codex_instructions_template.md`):
-  > "Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you."
-
-`mini-coder` introduced `CODEX_AUTONOMY` in a previous commit, but because of Issue #1, it was never adequately anchored in the `input` array.
-
-## Evidence & Tests
-We introduced a fetch wrapper interceptor in `src/llm-api/providers.ts` that logs the full outbound API requests to `~/.config/mini-coder/api.log`. 
-
-A test script `test-turn.ts` running a dummy turn showed the exact payload generated by the AI SDK before our fix:
-```json
-    "body": {
-      "model": "gpt-5.3-codex",
-      "input": [
-        {
-          "role": "user",
-          "content": [
-            { "type": "input_text", "text": "hello" }
-          ]
-        }
-      ],
-      "store": false,
-      "instructions": "You are a test agent.",
-      ...
-```
-```json
-    "body": {
-      "model": "gpt-5.3-codex",
-      "input": [
-        {
-          "role": "developer",
-          "content": "You are mini-coder, a small and fast CLI coding agent... [CODEX_AUTONOMY directives]"
-        },
-        {
-          "role": "user",
-          "content": [
-            { "type": "input_text", "text": "hello" }
-          ]
-        }
-      ],
-      "instructions": "You are mini-coder, a small and fast CLI coding agent... [CODEX_AUTONOMY directives]"
-    }
-```
-This perfectly mirrors the behavior seen in `opencode` and `codex-rs`.
-
-## Actions Taken
-1. Added an `api.log` request interceptor in `providers.ts` to capture and inspect the exact JSON payloads sent to the OpenAI/AI SDK endpoints.
-2. Cloned and analyzed both `opencode` and `codex` repos to observe how they communicate with `gpt-5.*` codex endpoints.
-3. Updated `src/llm-api/turn.ts` so `system: systemPrompt` is *always* passed to the AI SDK, guaranteeing a `developer` message anchors the `input` array, even when `instructions` is also used.

package/plan-code-health.md

@@ -1,169 +0,0 @@
-# Code Health Remediation Plan
-
-## Goal
-Address maintainability and reliability issues identified in `code-health.md` with low-risk, incremental refactors that keep behavior stable.
-
-## Constraints
-- Keep `mini-coder-idea.md` and `README.md` unchanged.
-- Prefer small PR-sized changes with passing tests after each step.
-- Preserve current CLI behavior while improving structure.
-
-## Workstreams
-
-### 1) Decompose `src/agent/agent.ts` (High)
-**Outcome:** `runAgent` remains orchestration entrypoint; responsibilities split into focused modules.
-
-**Steps:**
-1. Add `src/agent/reporter.ts` interface (narrow surface for output/status/tool events).
-2. Extract session lifecycle + turn loop into `src/agent/session-runner.ts`.
-3. Extract subagent execution into `src/agent/subagent-runner.ts`.
-4. Extract snapshot/undo helpers into `src/agent/undo-snapshot.ts`.
-5. Extract user input processing into `src/agent/input-loop.ts`.
-6. Keep `agent.ts` as composition/wiring file only.
-
-**Checks:**
-- Add/adjust unit tests around orchestration boundaries.
-- Ensure no behavior regressions in interrupts, resume, and tool-call flows.
-
----
-
-### 2) Decompose `src/cli/output.ts` (High)
-**Outcome:** Rendering responsibilities isolated and testable.
-
-**Target modules:**
-- `src/cli/spinner.ts`
-- `src/cli/tool-render.ts`
-- `src/cli/stream-render.ts`
-- `src/cli/status-bar.ts`
-- `src/cli/error-render.ts`
-- `src/cli/output.ts` as facade
-
-**Steps:**
-1. Extract pure formatting helpers first (no IO).
-2. Extract spinner lifecycle module.
-3. Extract stream queue/tick/flush behavior.
-4. Keep compatibility exports in `output.ts` to avoid broad callsite churn.
-
-**Checks:**
-- Add focused tests for formatting + stream behavior.
-- Verify terminal rendering remains stable manually.
-
----
-
-### 3) Introduce `TerminalIO` abstraction (Medium)
-**Outcome:** Centralized process/TTY interactions and signal lifecycle.
-
-**Steps:**
-1. Create `src/cli/terminal-io.ts` with methods for stdout/stderr writes, raw mode, signal subscriptions.
-2. Replace direct `process.*` use in output/input stack with injected `TerminalIO`.
-3. Centralize signal registration/unregistration in one lifecycle owner.
-
-**Checks:**
-- Add unit tests for signal registration cleanup semantics.
-- Confirm no stuck raw-mode edge cases.
-
----
-
-### 4) Split DB layer by domain (Medium)
-**Outcome:** Reduced blast radius and clearer data ownership.
-
-**Target modules:**
-- `src/session/db/connection.ts`
-- `src/session/db/session-repo.ts`
-- `src/session/db/message-repo.ts`
-- `src/session/db/settings-repo.ts`
-- `src/session/db/mcp-repo.ts`
-- `src/session/db/snapshot-repo.ts`
-- `src/session/db/index.ts` (facade exports)
-
-**Steps:**
-1. Move code without behavior changes.
-2. Keep SQL and schema unchanged initially.
-3. Replace direct `JSON.parse` in message loading with guarded parser:
-   - skip malformed rows
-   - emit diagnostic via logger/reporter
-
-**Checks:**
-- Add tests for malformed payload handling.
-- Validate existing DB tests still pass.
-
----
-
-### 5) Shared markdown config loader (Medium)
-**Outcome:** Remove duplication across agents/skills/custom-commands.
-
-**Steps:**
-1. Create `src/cli/load-markdown-configs.ts` with parameterized layout strategy.
-2. Migrate:
-   - `src/cli/agents.ts`
-   - `src/cli/skills.ts`
-   - `src/cli/custom-commands.ts`
-3. Keep precedence rules identical (built-in/user/project).
-4. Preserve existing frontmatter semantics.
-
-**Checks:**
-- Reuse/expand existing loader tests to cover parity.
-
----
-
-### 6) Runtime/UI decoupling via reporter boundary (Medium)
-**Outcome:** Core runtime no longer depends directly on terminal rendering.
-
-**Steps:**
-1. Define domain events or reporter interface in `src/agent/reporter.ts`.
-2. Implement CLI reporter adapter in `src/cli/output-reporter.ts`.
-3. Replace direct output calls in agent runtime with reporter calls.
-
-**Checks:**
-- Add tests using test reporter to assert emitted events.
-
----
-
-### 7) Error observability and silent catches (Medium)
-**Outcome:** Non-fatal failures become diagnosable without crashing.
-
-**Steps:**
-1. Find empty/broad catches in agent/output/loaders.
-2. Add debug-level diagnostics with contextual metadata.
-3. Keep user-facing behavior unchanged unless critical.
-
-**Checks:**
-- Validate noisy paths are still quiet at normal verbosity.
-
----
-
-### 8) Startup FS sync usage (Low/Deferred)
-**Outcome:** Optional responsiveness improvement if startup cost grows.
-
-**Steps:**
-1. Measure startup and config-loading time first.
-2. If needed, move high-volume file scanning to async or cache results with invalidation.
-
----
-
-### 9) Test hygiene cleanup (Low)
-**Outcome:** Cleaner CI output.
-
-**Steps:**
-1. Remove `console.log` skip notices in `src/tools/shell.test.ts`.
-2. Use test-framework-native skip annotations/helpers.
-
----
-
-## Execution Order (recommended)
-1. Reporter interface (foundation for later decoupling).
-2. `agent.ts` decomposition.
-3. `output.ts` decomposition.
-4. Shared config loader extraction.
-5. DB module split + safe JSON parsing.
-6. TerminalIO + centralized signals.
-7. Silent catch diagnostics.
-8. Test hygiene and any deferred FS optimization.
-
-## Definition of Done
-- `bun run typecheck && bun run format && bun run lint && bun test` passes.
-- No behavior regressions in interactive CLI flows.
-- `agent.ts` and `output.ts` materially reduced in size/responsibility.
-- Config loader duplication removed.
-- Message loading resilient to malformed JSON rows.
-- New abstractions documented in code comments where non-obvious.