diff --git a/AGENTS.md b/AGENTS.md index 44cf6f7298d2..3e3cfaf360ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -176,8 +176,8 @@ This repo is the Alterspective fork (`origin` = `Alter-Igor/opencode`, `upstream - **Symlinks**: Windows has no symlink privilege here, so repo symlinks check out as text placeholders. The two typecheck-blocking ones (`packages/app/src/custom-elements.d.ts`, `packages/enterprise/src/custom-elements.d.ts`) are replaced with local hardlinks hidden via `git update-index --skip-worktree` (list them: `git ls-files -v | Select-String '^S'`). ~60 asset symlinks (favicons etc.) remain placeholders — harmless for typecheck/TUI, but app/web builds serving those assets need Developer Mode enabled first. - **Small model context protection & delegation** (`packages/opencode/src/plugin/small-model-delegation.ts`): protects models with small context windows (default threshold <= 300,000 tokens, e.g. local models running on RTX 5090 / `coder-svr`) from context exhaustion. Uses a two-tier mechanism: (1) prompt guidance via `experimental.chat.system.transform` directing the primary agent to delegate broad file searches and code exploration to the `explore` subagent; (2) active tool bouncer via `tool.execute.before` blocking direct calls to `grep` and `read` in primary sessions, guiding the model with an exact `task` tool invocation example. Subagents (`parentSessionID` present, max depth 1) run unrestricted with full tool access and return concise syntheses to keep primary context clean. Configurable via `OPENCODE_SMALL_MODEL_THRESHOLD` (number of tokens), `OPENCODE_SMALL_MODEL_DELEGATION` (0 to disable), or `opencode.jsonc` `experimental.small_model_context_threshold`. Supported across Web UI, TUI, CLI, `coder-svr`, and Docker sandbox (`opencode-delegate` env passthrough). Tests: `bun test test/plugin/small-model-delegation.test.ts`. - **Tool-output secret redaction** (#26, fork-only `packages/opencode/src/plugin/secret-redaction.ts`): high-confidence credentials (OpenRouter, OpenAI, Anthropic, Stripe, GitHub, GitLab, npm, Hugging Face, AWS, Azure `AccountKey`, Google, Slack, Synapse `gpapp_`, JWT, opaque `Bearer`, URL passwords, PEM private keys) become `[REDACTED:]` in two places, and in tool parts brought in with `opencode import` (`cli/cmd/import.ts` calls `redactToolPart` before its direct `PartTable` insert, #207). (1) `Session.updatePart` (`session/session.ts`, a three-line hook) redacts every stored copy of a tool part, running, completed or failed: input arguments, output, title, metadata (the shell tool's streamed output) and error text, but not attachments. The `PartUpdated` event is durable, so this is what keeps a key out of the database and out of a shared session, with or without the fork plugins. (2) The Synapse plugin's `tool.execute.after` hook redacts the result object core hands back, including an MCP result's `content` text and embedded resource text (image and blob data untouched). The observer's diagnostics redaction uses the same patterns. Not covered: the model's own text and reasoning; the overflow file that output truncation writes to disk; the experimental v2 core runner, which stores tool results without `updatePart`; and the delegate box, which runs its own opencode build. Known trade-off: a model that reads a file holding a real key sees `[REDACTED:]`, and if it rewrites that file the key is lost. A placeholder such as `postgres://u:${PASS}@` is redacted too. Because stored inputs are redacted, the doom-loop guard in `session/processor.ts` (a two-line hook) compares them with `redactedCopy` of the live input. Each rule runs only when the text holds one of its literal prefixes, which keeps the cost per streamed shell chunk well under a millisecond. After every upstream sync run `bun test test/plugin/secret-redaction.test.ts test/session/secret-redaction-store.test.ts` from `packages/opencode`. -- **Observer MCP failures** (#18, fork-only `packages/opencode/src/plugin/observer.ts` and `synapse.ts`): the session retrospective's `MCP_TOOL_FAILURE` check works with opencode's real MCP tool names (`_`, `mcp/catalog.ts` `toolName`). A tool is MCP when its `tool.execute.after` result has the MCP shape (`content` items), or when it was never announced through the `tool.definition` hook, which core fires only for native and plugin tools (`tool/registry.ts`). An MCP error result never reaches `tool.execute.after` (core throws it, `mcp/catalog.ts`), so a failure is read from the failed tool part's `message.part.updated` event; only calls the observer saw start count, so a fork or compaction replaying old parts is ignored, and a call the user stopped or refused, or a permission rule blocked, is not counted (the error texts in `NOT_A_FAILURE` come from `packages/core/src/v1/permission.ts`, the abort in `packages/opencode/src/session/processor.ts`, an MCP call stopped by its abort signal (the SDK wraps it, e.g. `MCP error -32001: AbortError: The operation was aborted.`, so `operation was aborted` is matched anywhere in the text) and `packages/opencode/src/question/index.ts`; recheck them after an upstream sync). Each retrospective covers the calls since the last one: the session's records are freed when it is written (#209). The text of a successful MCP result is not searched for error words (a log or search tool returns them as data). The old `mcp__` / `mcp` name check stays as a fallback. Not covered: an MCP call made inside code mode's `execute` tool. After every upstream sync run `bun test test/plugin/observer.test.ts` from `packages/opencode`, and recheck those three upstream facts plus the failed part's shape in the `message.part.updated` event (`part.sessionID`, `callID`, `tool`, `state.status`, `state.error`). -- **Learning (rule) store** (#38, #212, #216, #217, fork-only `packages/opencode/src/plugin/observer.ts`, tools in `synapse.ts`): rules live in two JSON files, global `/.local/share/opencode/learnings.json` (honours `OPENCODE_TEST_HOME`) and per project `.system_generated/logs/learnings.json`. A rule recorded in a project is mirrored to the global store by design (owner decision on keeping that, #211). A forgotten rule keeps its row with `deletedAt` (a tombstone), so a later merge cannot bring it back; re-recording it clears the tombstone. A store that cannot be read (bad JSON, not an array, a row without a string `lesson`) is never written over: a record skips it (`savedTo` names only the stores written), a forget changes nothing and says so (`refused`), `synapse_list_rules` shows it as skipped, and prompt injection reads it as empty and writes one `LEARNING_STORE` `skipped_unreadable` diagnostics line (again only after a good read). Writes go through a temp file and a rename, and the temp file is removed if the rename fails. On Windows a rename that fails for a moment with EPERM, EBUSY or EACCES (another handle has the store open) is retried 5 times, waiting 20 ms and doubling each time (about 0.6 s in all), before it fails; do not drop that retry in a cleanup or an upstream sync, or Windows starts losing rules again. Record and forget take a machine-wide `Flock` lock (`learning-store:`, the lock folder sits next to the global store) so a TUI and `opencode serve` cannot drop each other's rule; if the lock is not free within 10 s the write goes ahead under the in-process lock only, with a `lock_failed` diagnostics line. After every upstream sync run `bun test test/plugin/observer.test.ts` from `packages/opencode`. +- **Observer MCP failures** (#18, fork-only `packages/opencode/src/plugin/observer.ts` and `synapse.ts`): the session retrospective's `MCP_TOOL_FAILURE` check works with opencode's real MCP tool names (`_`, `mcp/catalog.ts` `toolName`). A tool is MCP when its `tool.execute.after` result has the MCP shape (`content` items), or when it was never announced through the `tool.definition` hook, which core fires only for native and plugin tools (`tool/registry.ts`). An MCP error result never reaches `tool.execute.after` (core throws it, `mcp/catalog.ts`), so a failure is read from the failed tool part's `message.part.updated` event; only calls the observer saw start count, so a fork or compaction replaying old parts is ignored, and a call the user stopped or refused, or a permission rule blocked, is not counted (the prefixes in `NOT_A_FAILURE` come from `packages/core/src/v1/permission.ts`, the abort in `packages/opencode/src/session/processor.ts` and `packages/opencode/src/question/index.ts`; recheck them after an upstream sync. A separate `ABORTED` regex skips an MCP call stopped by its abort signal: the SDK wraps it, e.g. `MCP error -32001: AbortError: The operation was aborted.`, so `The|This operation was aborted` is matched at the start of the text, optionally after `Error: `, or right after `AbortError: `, and an MCP server's own error that mentions an aborted operation further in still counts, #209). Each retrospective covers the calls since the last one: the session's records are freed when it is written, and a finalize with no calls (a turn with no tool calls, a `session.deleted` right after an idle) writes and sends nothing (#209). Native tool failures are marked `isError` too (`onToolFailed`); only the MCP check reads that flag today, so a future error-rate check would count them. The text of a successful MCP result is not searched for error words (a log or search tool returns them as data). The old `mcp__` / `mcp` name check stays as a fallback. Not covered: an MCP call made inside code mode's `execute` tool. After every upstream sync run `bun test test/plugin/observer.test.ts` from `packages/opencode`, and recheck those three upstream facts plus the failed part's shape in the `message.part.updated` event (`part.sessionID`, `callID`, `tool`, `state.status`, `state.error`). +- **Learning (rule) store** (#38, #212, #216, #217, fork-only `packages/opencode/src/plugin/observer.ts`, tools in `synapse.ts`): rules live in two JSON files, global `/.local/share/opencode/learnings.json` (honours `OPENCODE_TEST_HOME`) and per project `.system_generated/logs/learnings.json`. A rule recorded in a project is mirrored to the global store by design (owner decision on keeping that, #211). A forgotten rule keeps its row with `deletedAt` (a tombstone), so a later merge cannot bring it back; re-recording it clears the tombstone. A store that cannot be read (bad JSON, not an array, a row without a string `lesson`) is never written over: a record skips it (`savedTo` names only the stores written), a forget changes nothing and says so (`refused`), `synapse_list_rules` shows it as skipped, and prompt injection reads it as empty and writes one `LEARNING_STORE` `skipped_unreadable` diagnostics line (again only after a good read). Writes go through a temp file and a rename, and the temp file is removed if the rename fails. A rename that fails for a moment with EPERM or EBUSY, or with EACCES on Windows (another handle has the store open, which Windows reports this way), is retried 5 times, waiting 20 ms and doubling each time (about 0.6 s in all), before it fails; do not drop that retry in a cleanup or an upstream sync, or Windows starts losing rules again. Record and forget take a machine-wide `Flock` lock (`learning-store:`, the lock folder sits next to the global store) so a TUI and `opencode serve` cannot drop each other's rule; if the lock is not free within 10 s the write goes ahead under the in-process lock only, with a `lock_failed` diagnostics line. After every upstream sync run `bun test test/plugin/observer.test.ts` from `packages/opencode`. - **Deleting a session stops its run** (#214, fork-only `packages/opencode/src/session/cancel-tree.ts`, a single call in upstream `packages/opencode/src/server/routes/instance/httpapi/handlers/session.ts` `remove`): `Session.remove` only cancels background jobs (it cannot reach `SessionPrompt`, which depends on it), so a busy session kept calling the model, running tools and publishing events after it was deleted. The HTTP delete handler now calls `cancelSessionTree` (cancel the session's run, then every child session's, waiting for each to stop) before `session.remove`; a session whose status is idle and whose runner is not busy is not cancelled, so a delete does not publish `session.idle` and wake idle listeners (observer retrospective, goal loop). Not covered: `opencode session delete` from the CLI (no run lives in that process), workspace removal (`control-plane/workspace.ts` `remove` calls `session.remove` directly), title and summary side jobs a run started (they can still write to the deleted session), and dropping late writes for a deleted session (all #214). The web app drops late events of a deleted session too: fork-only `packages/app/src/context/global-sync/deleted-sessions.ts`, with one line at the top of the event listener in upstream `packages/app/src/context/server-sync.tsx` (`dropDeletedSessionEvent`, before `session.applyV2`, `session.apply`, `homeSessions.apply` and the directory reducer, because the live app calls the reducer with `sessionContent: false` and the session cache in `server-session.ts` re-creates a session from any of its events), and two hooks in upstream `event-reducer.ts` `applyDirectoryEvent` for its other callers (the early return at the top, the `markSessionDeleted` in `session.deleted`); a `session.created` for a deleted ID brings it back (import keeps IDs). Not covered in the web app: the made-up `session.created` that `indexSession` sends for a moved or forked session (it brings a deleted ID back; low risk, the session cache must still know the session). After an upstream sync check the three hooks and rerun `bun test --conditions=solid src/context/global-sync/deleted-sessions.test.ts src/context/global-sync/event-reducer.test.ts` from `packages/app`. After every upstream sync check the hook is still before `session.remove` and run `bun test test/session/cancel-tree.test.ts` from `packages/opencode`. - **TUI deleted sessions stay deleted** (#176, fork-only `packages/tui/src/context/deleted-sessions.ts`, hooks in upstream `packages/tui/src/context/sync.tsx`): the server deletes a session without stopping a reply that is still running, and publishes message and part events before it writes them. So after `session.deleted` frees a session's entries (#173), late events for it would re-create them, and a `sync()` still fetching would write it back. `sync.tsx` keeps a set of the last 200 deleted session IDs: the event handler returns early for any event of a deleted session (one line at the top of the switch, one `add` in the `session.deleted` case), and `sync()` writes nothing if the session was deleted while it fetched; a session list (bootstrap, `session.refresh()`) or status map fetched before the delete is filtered too. A permission asked by a deleted session's run is ignored too, so `auto` permission mode no longer approves it. Not covered: `opencode import` of a session deleted in the same TUI run (it keeps its old ID and shows empty until restart). An HTTP delete now cancels the run first (#214); this guard still covers the CLI delete, workspace removal and events that race the delete. The `add` hook sits in the `session.deleted` cleanup from #173 (freeing the session's messages, parts, todo, diff, status, permissions and questions), which is itself a fork patch: upstream's case only removes the session from the list. After every upstream sync check that cleanup and the six `deletedSessions` hooks are still in `sync.tsx` (the early return at the top of the event switch, the `add` in `session.deleted`, the `has` check in `sync()`, the `filter` on the bootstrap session list, the `omit` on the bootstrap status map, and the `filter` in `refresh()`) and run `bun test test/cli/cmd/tui/sync-deleted-session-late-events.test.tsx` from `packages/tui`. - **TUI part window** (#215, fork-only `packages/tui/src/context/part-window.ts`, hooks in upstream `packages/tui/src/context/sync.tsx`): in a session sync.tsx has fully synced, a `message.part.updated` for a message the store does not list is dropped (compaction prune touches old tool parts; the server publishes `message.updated` before a message's parts, so an unlisted message there is outside the window). Message IDs are not compared: their 48-bit time wraps (last on 2026-08-14). A part of a session that is not synced, or still loading, is kept as before. `session.deleted` frees every stored part of the session, including orphans. After every upstream sync check the two hooks (the `fullSyncedSessions` + `unlistedMessage` check at the top of the `message.part.updated` case, before `touchPart`, and `freeSessionParts` in the `session.deleted` cleanup) and run `bun test test/cli/cmd/tui/sync-part-window.test.tsx` from `packages/tui`. Not covered: if the live event stream drops during a reply and a synced session misses a `message.updated`, that message's parts are dropped until its next `message.updated` (a finished tool part may stay missing until restart). The fast tier runs all `sync*.test.tsx` files for a `sync.tsx` change (see Fast-cycle delivery). diff --git a/packages/opencode/src/plugin/observer.ts b/packages/opencode/src/plugin/observer.ts index 1302fe42d6c2..0737b1863793 100644 --- a/packages/opencode/src/plugin/observer.ts +++ b/packages/opencode/src/plugin/observer.ts @@ -38,10 +38,12 @@ const NOT_A_FAILURE = [ /** * #209: an MCP call stopped by its abort signal (the user stopped the reply) fails with the SDK's * wrapped text, e.g. `MCP error -32001: AbortError: The operation was aborted.` (Bun) or - * "... This operation was aborted" (Node), so it is matched anywhere in the text, not as a prefix. - * A real timeout reads `MCP error -32001: Request timed out` and still counts. + * "... This operation was aborted" (Node). It is matched at the start of the text (optionally after + * `Error: `) or right after `AbortError: `, not anywhere: an MCP server's own error that happens to + * say "operation was aborted" further in is a real failure. A real timeout reads + * `MCP error -32001: Request timed out` and still counts. */ -const ABORTED = /operation was aborted/i +const ABORTED = /(?:^(?:Error: )?|AbortError: )(?:The|This) operation was aborted/i /** #18: a `message.part.updated` event for a tool part that failed, as the observer needs it. */ export function failedToolFromEvent(event: { @@ -306,6 +308,9 @@ class SessionObserverManager { // arguments in memory for the life of the process. this.trajectories.delete(sessionId) this.sessionStartTimes.delete(sessionId) + // #209: a turn with no tool calls, or a session.deleted right after an idle, has nothing to + // report; it used to write a file and POST a retrospective with 0 calls. + if (records.length === 0) return null const anomalies: SessionAnomaly[] = [] const learnings: string[] = [] diff --git a/packages/opencode/test/plugin/observer.test.ts b/packages/opencode/test/plugin/observer.test.ts index b58ad02da1d6..0dc124cbca4b 100644 --- a/packages/opencode/test/plugin/observer.test.ts +++ b/packages/opencode/test/plugin/observer.test.ts @@ -52,9 +52,11 @@ describe("session retrospective profile", () => { expect(await fs.readdir(ws.path)).not.toContain(".system_generated") expect(sessionObserver.getLatestRetrospectives().some((retro) => retro.sessionId === sessionId)).toBe(false) expect(telemetry).not.toHaveBeenCalled() - // Turning it back on must not replay records held while the profile was disabled. + // Turning it back on must not replay records held while the profile was disabled: there are + // none left, so nothing is written or sent (#209: no empty retrospectives). delete process.env.OPENCODE_DISABLE_SESSION_RETROSPECTIVES - expect((await sessionObserver.finalizeSessionRetrospective(sessionId))?.totalToolCalls).toBe(0) + expect(await sessionObserver.finalizeSessionRetrospective(sessionId)).toBeNull() + expect(telemetry).not.toHaveBeenCalled() } finally { if (previous === undefined) delete process.env.OPENCODE_DISABLE_SESSION_RETROSPECTIVES if (previous !== undefined) process.env.OPENCODE_DISABLE_SESSION_RETROSPECTIVES = previous @@ -779,6 +781,8 @@ describe("MCP tool failures with real remote tool names (#18)", () => { "The user dismissed this question", "MCP error -32001: AbortError: The operation was aborted.", "MCP error -32001: AbortError: This operation was aborted", + "The operation was aborted.", + "Error: This operation was aborted", ] errors.forEach((error, i) => { sessionObserver.onToolBefore(sessionId, `c${i}`, "alterspective-rag_rag_search", {}) @@ -789,6 +793,33 @@ describe("MCP tool failures with real remote tool names (#18)", () => { expect(retro?.anomalies.filter((a) => a.type === "MCP_TOOL_FAILURE")).toEqual([]) }) + test("an MCP server's own error that mentions an aborted operation still counts (#209)", async () => { + sessionObserver.markNativeTool("read") + const sessionId = "obs-209-server-abort-text" + sessionObserver.onToolBefore(sessionId, "c1", "alterspective-rag_rag_search", {}) + sessionObserver.onToolFailed( + sessionId, + "c1", + "alterspective-rag_rag_search", + "MCP error -32603: query failed: the operation was aborted by the database", + ) + const retro = await sessionObserver.finalizeSessionRetrospective(sessionId) + expect(retro?.anomalies.filter((a) => a.type === "MCP_TOOL_FAILURE")).toHaveLength(1) + }) + + test("a turn with no tool calls writes and sends no retrospective (#209)", async () => { + await using ws = await tmpdir() + const sessionId = "obs-209-empty" + expect(await sessionObserver.finalizeSessionRetrospective(sessionId, ws.path)).toBeNull() + // A session.deleted right after an idle: the idle took the records, the delete finds none. + sessionObserver.onToolBefore(sessionId, "c1", "read", {}) + sessionObserver.onToolAfter(sessionId, "c1", "read", "ok") + expect((await sessionObserver.finalizeSessionRetrospective(sessionId, ws.path))?.totalToolCalls).toBe(1) + expect(await sessionObserver.finalizeSessionRetrospective(sessionId, ws.path)).toBeNull() + expect(await fs.readdir(path.join(ws.path, ".system_generated", "retrospectives"))).toHaveLength(1) + expect(telemetry).toHaveBeenCalledTimes(1) + }) + test("a real MCP timeout still counts as a failure (#209)", async () => { sessionObserver.markNativeTool("read") const sessionId = "obs-209-timeout" @@ -837,9 +868,8 @@ describe("MCP tool failures with real remote tool names (#18)", () => { test("a failure for a call the observer never saw start is ignored (a fork or compaction replays old parts)", async () => { const sessionId = "obs-18-replay" sessionObserver.onToolFailed(sessionId, "old-call", "alterspective-rag_rag_search", "Error: old failure") - const retro = await sessionObserver.finalizeSessionRetrospective(sessionId) - expect(retro?.totalToolCalls).toBe(0) - expect(retro?.anomalies.filter((a) => a.type === "MCP_TOOL_FAILURE")).toEqual([]) + // No record was made, so there is nothing to report at all (#209: no empty retrospectives). + expect(await sessionObserver.finalizeSessionRetrospective(sessionId)).toBeNull() }) test("failedToolFromEvent reads only failed tool parts", () => {