@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/subagent-runner.ts

@@ -0,0 +1,240 @@
+/**
+ * Cross-harness subagent runner abstraction.
+ *
+ * Magic Context spawns the historian
+ * each as a child "session" with its own model/prompt/tools. OpenCode and Pi
+ * have very different APIs for this:
+ *
+ *   - OpenCode: `client.session.create({parentID}) → client.session.prompt() →
+ *     client.session.messages() → client.session.delete()`. The plugin runs
+ *     in-process with the OpenCode server and uses its SDK client directly.
+ *
+ *   - Pi: no in-process child-session API. Instead `pi --print --mode=json`
+ *     spawns a non-interactive subprocess that emits structured JSON events
+ *     and exits when the agent loop finishes. Sessions are JSONL files on
+ *     disk, optionally addressed via `--session <path>`.
+ *
+ * The runner interface below normalizes both into the same shape so the
+ * actual subagent business logic (historian XML parsing)
+ * can stay harness-agnostic. Each harness ships its
+ * own runner implementation; agents take a `SubagentRunner` as a dep instead
+ * of reaching for `client.session.*` directly.
+ *
+ * Step 5a (this commit) defines the contract and ships `PiSubagentRunner`.
+ * Step 5b will refactor the OpenCode-side spawn paths in
+ * `compartment-runner-historian.ts` onto an
+ * `OpenCodeSubagentRunner` so both harnesses
+ * share the agent business logic instead of duplicating it. Until 5b lands,
+ * OpenCode keeps its existing direct `client.session.*` calls untouched —
+ * the runner contract is purely additive on the OpenCode side.
+ */
+
+import type { ModelInput } from "./model-resolution";
+
+/**
+ * Configuration for one subagent invocation.
+ *
+ * Mirrors the union of OpenCode's `session.create` + `session.prompt` body
+ * fields and Pi's `--print` CLI flags, picking the shared subset that the
+ * historian subagent actually uses today.
+ *
+ * Fields:
+ * - `agent`: harness-specific agent name. OpenCode looks this up in its
+ *   agent registry (`HISTORIAN_AGENT`).
+ *   Pi has no concept of "agent name" beyond config, so this is ignored
+ *   on the Pi side and used only by `OpenCodeSubagentRunner`.
+ * - `systemPrompt`: full system prompt for this child run. Replaces (not
+ *   appends to) any harness-default system prompt.
+ * - `userMessage`: the single user-turn prompt. Subagent runs are always
+ *   one-shot — no multi-turn conversation in the child.
+ * - `model`: provider/model identifier in the canonical "provider/model"
+ *   shape (e.g. "anthropic/claude-sonnet-4-7"). Each runner is responsible
+ *   for translating to its harness's native model selection.
+ * - `fallbackModels`: ordered list of models to try if `model` fails. Both
+ *   harnesses retry on transient model failures.
+ * - `timeoutMs`: hard cap on the child run. The runner aborts the child on
+ *   exceeding this and returns `{ ok: false, reason: "timeout" }`.
+ * - `cwd`: working directory for the child. OpenCode uses this for
+ *   `query.directory`; Pi uses it as the spawn cwd so that `--cwd`-aware
+ *   tools see the right project root.
+ * - `signal`: optional AbortSignal so callers can cancel an in-flight run.
+ */
+export interface SubagentRunOptions {
+    agent: string;
+    systemPrompt: string;
+    userMessage: string;
+    model?: string | undefined;
+    fallbackModels?: readonly ModelInput[];
+    timeoutMs?: number | undefined;
+    /** Sampling temperature for the provider request when the harness can enforce it. */
+    temperature?: number | undefined;
+    /** Requested output-token budget for the provider request. */
+    maxOutputTokens?: number | undefined;
+    cwd?: string | undefined;
+    signal?: AbortSignal | undefined;
+    /**
+     * Pi only: explicit thinking level, passed as `--thinking <level>` to the
+     * Pi subprocess. OpenCode ignores this field — thinking/reasoning is
+     * controlled via `variant` in the OpenCode agent config instead.
+     *
+     * Required when the configured historian model supports reasoning
+     * (e.g. github-copilot/gpt-5.4) because Pi's own default resolution may
+     * pick a value the provider rejects. Set to "off" to disable thinking for
+     * speed (local models), or "medium"/"high" for better quality.
+     */
+    thinkingLevel?: string | undefined;
+
+    /**
+     * Optional progress callback. The runner invokes it for milestone events
+     * during the run: spawn, first event received, terminal stop reason
+     * detected, child exit. Used by the historian to write
+     * lifecycle entries to the magic-context.log without polluting the
+     * normal stdout stream.
+     *
+     * Implementations must be non-throwing and fast — they're called on the
+     * runner's hot path. Errors are swallowed.
+     */
+    onProgress?: (event: SubagentProgressEvent) => void;
+
+    /** Optional token accounting metadata. When present, harness runners persist subagent_invocations. */
+    accountingSessionId?: string | undefined;
+    accountingSubagent?: "historian" | "historian_editor" | "compressor" | "recomp" | undefined;
+    accountingTask?: string | null | undefined;
+    accountingParentInvocationId?: number | null | undefined;
+}
+
+/**
+ * Progress events emitted by a runner during a run. Distinct from the final
+ * `SubagentRunResult` — these are mid-run milestones plus (optionally) every
+ * raw event the underlying harness emits, so callers can write a complete
+ * trace to the log when diagnosing hangs.
+ *
+ * Categories:
+ * - `spawned` / `child_exit` / `stderr` — process lifecycle.
+ * - `first_event` — convenience: first event received from the child, useful
+ *   for measuring auth/network warmup time.
+ * - `terminal` — runner detected the final assistant turn (Pi: assistant
+ *   message_end with terminal stopReason and no toolCall; OpenCode: SDK
+ *   `agent_end` equivalent).
+ * - `raw_event` — every parsed event from the harness's structured output
+ *   stream (Pi NDJSON / OpenCode SDK events). Emitted unconditionally so
+ *   debug logs can capture the full timeline. The `event` payload is
+ *   harness-shaped — callers should treat it as `unknown` and log it raw.
+ */
+export type SubagentProgressEvent =
+    | { type: "spawned"; argv: readonly string[]; pid: number | undefined }
+    | { type: "first_event"; eventType: string; ms: number }
+    | {
+          type: "raw_event";
+          eventType: string | undefined;
+          event: unknown;
+          ms: number;
+      }
+    | {
+          type: "terminal";
+          stopReason: string | undefined;
+          textLength: number;
+          hasToolCall: boolean;
+          ms: number;
+      }
+    | { type: "stderr"; chunk: string }
+    | { type: "child_exit"; code: number | null; signal: string | null; ms: number };
+
+/**
+ * Result of one subagent invocation.
+ *
+ * The runner contract is "fail soft": transient errors, timeouts, model
+ * failures, and aborts all surface as `{ ok: false, reason }` with a
+ * machine-readable reason and a human-readable message. Throwing is
+ * reserved for programmer errors (bad arguments, missing dependencies)
+ * that the agent code couldn't have caused.
+ *
+ * Fields:
+ * - `ok`: true iff the child produced a final assistant message.
+ * - `assistantText`: concatenated text content from the final assistant
+ *   message, with leading/trailing whitespace trimmed. Empty assistant text is
+ *   reported as `ok: false, reason: "no_assistant"` so callers can try fallback
+ *   models instead of accepting an unusable success.
+ * - `reason`: failure category, one of:
+ *     - `"invalid_prompt"`: a known zero-tool child was given no system prompt
+ *     - `"timeout"`: hit `timeoutMs` before the child finished
+ *     - `"abort"`: caller's `signal` was triggered
+ *     - `"model_failed"`: every configured model + fallback returned an error
+ *     - `"truncated"`: child stopped because model output hit length limits
+ *     - `"spawn_failed"`: subprocess couldn't start (Pi only — binary missing,
+ *       permission denied, etc.)
+ *     - `"non_zero_exit"`: child exited unsuccessfully before a final answer
+ *     - `"no_assistant"`: child completed without a final assistant message
+ *     - `"parse_failed"`: child emitted output we couldn't parse (Pi only —
+ *       JSON malformed or unexpected event ordering)
+ * - `error`: human-readable detail; safe to log, may include stack info.
+ * - `durationMs`: wall-clock time from runner-call to runner-return.
+ * - `meta`: optional harness-specific debug payload. Currently unused; left
+ *   here so the OpenCode runner can surface the child session ID for log
+ *   correlation when Step 5b lands.
+ */
+export interface CompletedSubagentToolCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+
+export type SubagentRunResult =
+    | {
+          ok: true;
+          assistantText: string;
+          durationMs: number;
+          /**
+           * Number of tool invocations the agent made during the run. Pi reports
+           * this so callers that gate on "did the agent actually investigate vs
+           * just paraphrase" (refresh-primers' grounding gate) work on Pi, whose
+           * facade otherwise surfaces only the final assistant text. OpenCode
+           * leaves it undefined — its callers read tool-call parts straight off
+           * the real session messages.
+           */
+          toolCallCount?: number;
+          /** Completed, non-error tool results preserved by runners that can
+           *  reconstruct invocation/result pairs from their transcript. */
+          completedToolCalls?: CompletedSubagentToolCall[];
+          meta?: Record<string, unknown>;
+      }
+    | {
+          ok: false;
+          reason:
+              | "invalid_prompt"
+              | "timeout"
+              | "abort"
+              | "model_failed"
+              | "truncated"
+              | "spawn_failed"
+              | "non_zero_exit"
+              | "no_assistant"
+              | "parse_failed";
+          error: string;
+          durationMs: number;
+          /** True when the caller should retry the task rather than advance its schedule. */
+          transient?: boolean;
+          meta?: Record<string, unknown>;
+      };
+
+/**
+ * Abstract runner contract.
+ *
+ * Each harness ships a single instance — the OpenCode plugin wires
+ * `OpenCodeSubagentRunner` and the Pi plugin wires `PiSubagentRunner` in
+ * its `extension` boot path. Agent code (the historian)
+ * receives the runner as a dep and never reaches for harness-specific
+ * client APIs directly.
+ */
+export interface SubagentRunner {
+    /** Human-readable harness name, for logging (`"opencode"` or `"pi"`). */
+    readonly harness: string;
+
+    /**
+     * Run one subagent invocation to completion.
+     *
+     * Always resolves with a `SubagentRunResult` — never throws for
+     * runtime/transport/model failures. Throwing is reserved for caller
+     * misuse (e.g. missing required option fields).
+     */
+    run(options: SubagentRunOptions): Promise<SubagentRunResult>;
+}

package/src/shared/summarize-child-stderr.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "bun:test";
+import { summarizeChildStderr } from "./summarize-child-stderr";
+
+function bundledCrashStderr(): { sourceLine: string; stderr: string } {
+    const sourceLine = `263 | ${"FROM cacheInterceptorV${VERSION2} ".repeat(100)}`.slice(0, 3_000);
+    return {
+        sourceLine,
+        stderr: [
+            sourceLine,
+            "^",
+            "SqliteError: database is locked",
+            "    at openDatabase (bundle.js:100:20)",
+            "    at runHistorian (runner.js:12:4)",
+            "    at main (cli.js:2:1)",
+        ].join("\n"),
+    };
+}
+
+describe("summarizeChildStderr", () => {
+    it("keeps an error line and the first two stack frames after bundled source context", () => {
+        const { sourceLine, stderr } = bundledCrashStderr();
+
+        const excerpt = summarizeChildStderr(stderr);
+
+        expect(excerpt).toContain("SqliteError: database is locked");
+        expect(excerpt).toContain("at openDatabase (bundle.js:100:20)");
+        expect(excerpt).toContain("at runHistorian (runner.js:12:4)");
+        expect(excerpt).not.toContain("at main (cli.js:2:1)");
+        expect(excerpt.startsWith(sourceLine)).toBe(false);
+    });
+
+    it("passes through short stderr without an error-shaped line unchanged", () => {
+        const stderr = "auth failure: missing API key";
+
+        expect(summarizeChildStderr(stderr)).toBe(stderr);
+    });
+
+    it("keeps the tail of long chatty stderr when no error line is present", () => {
+        const stderr = `${"head-only\n".repeat(2_000)}${"tail-only\n".repeat(2_000)}`;
+        const excerpt = summarizeChildStderr(stderr);
+
+        expect(stderr.length).toBeGreaterThan(16_000);
+        expect(excerpt).toBe(stderr.slice(-500));
+        expect(excerpt).toContain("tail-only");
+        expect(excerpt).not.toContain("head-only");
+    });
+
+    it("recognizes Node's bracketed error code form", () => {
+        expect(
+            summarizeChildStderr(
+                "Error [ERR_MODULE_NOT_FOUND]: Cannot find package\n    at loader (node:internal/modules:1:1)",
+            ),
+        ).toContain("Error [ERR_MODULE_NOT_FOUND]: Cannot find package");
+    });
+});

package/src/shared/summarize-child-stderr.ts

@@ -0,0 +1,33 @@
+/**
+ * Return the useful part of a child-process diagnostic without allowing a
+ * bundled source line to hide the error that follows it.
+ *
+ * Node prints uncaught exceptions as source context, a caret, and then the
+ * error line and stack. Prefer that error line plus the first two stack frames;
+ * when no recognizable error line exists, the end of stderr is most likely to
+ * contain the actionable failure detail.
+ */
+const MAX_CHILD_STDERR_SUMMARY_LENGTH = 500;
+const CHILD_ERROR_LINE_PATTERN = /^(?:[A-Za-z]*Error|SqliteError|Error)\b[^\n]*/;
+const STACK_FRAME_PATTERN = /^\s*at\b/;
+
+export function summarizeChildStderr(stderr: string): string {
+    const lines = stderr.split(/\r?\n/);
+    const errorLineIndex = lines.findIndex((line) => CHILD_ERROR_LINE_PATTERN.test(line));
+
+    if (errorLineIndex < 0) {
+        return stderr.length > MAX_CHILD_STDERR_SUMMARY_LENGTH
+            ? stderr.slice(-MAX_CHILD_STDERR_SUMMARY_LENGTH)
+            : stderr;
+    }
+
+    const excerptLines = [lines[errorLineIndex]];
+    let stackFrames = 0;
+    for (let index = errorLineIndex + 1; index < lines.length && stackFrames < 2; index += 1) {
+        if (!STACK_FRAME_PATTERN.test(lines[index])) continue;
+        excerptLines.push(lines[index]);
+        stackFrames += 1;
+    }
+
+    return excerptLines.join("\n").slice(0, MAX_CHILD_STDERR_SUMMARY_LENGTH);
+}

package/src/shared/system-directive.ts

@@ -0,0 +1,9 @@
+const SYSTEM_DIRECTIVE_PREFIX = "[SYSTEM DIRECTIVE: MAGIC-CONTEXT";
+
+export function isSystemDirective(text: string): boolean {
+    return text.trimStart().startsWith(SYSTEM_DIRECTIVE_PREFIX);
+}
+
+export function removeSystemReminders(text: string): string {
+    return text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, "").trim();
+}

package/src/shared/tag-owner-id.test.ts

@@ -0,0 +1,33 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test";
+import { contentTagOwnerMessageId } from "./tag-owner-id";
+
+const DIGEST_A = "a".repeat(64);
+const DIGEST_B = "0123456789abcdef".repeat(4);
+
+describe("contentTagOwnerMessageId", () => {
+    it("strips positional text and file suffixes", () => {
+        expect(contentTagOwnerMessageId("pi-msg-1:p0")).toBe("pi-msg-1");
+        expect(contentTagOwnerMessageId("pi-msg-1:p12")).toBe("pi-msg-1");
+        expect(contentTagOwnerMessageId("pi-msg-1:file3")).toBe("pi-msg-1");
+    });
+
+    it("strips a content-derived text suffix", () => {
+        expect(contentTagOwnerMessageId(`pi-msg-1:mc-text-v1:${DIGEST_A}:${DIGEST_B}:o0`)).toBe(
+            "pi-msg-1",
+        );
+        expect(
+            contentTagOwnerMessageId(`m:with:colons:mc-text-v1:${DIGEST_A}:${DIGEST_B}:o7`),
+        ).toBe("m:with:colons");
+    });
+
+    it("leaves an id with no content suffix unchanged", () => {
+        expect(contentTagOwnerMessageId("pi-msg-1")).toBe("pi-msg-1");
+        expect(contentTagOwnerMessageId("pi-msg-1:pfile")).toBe("pi-msg-1:pfile");
+        // A marker without the digest shape is not a content-derived id.
+        expect(contentTagOwnerMessageId("pi-msg-1:mc-text-v1:not-hex")).toBe(
+            "pi-msg-1:mc-text-v1:not-hex",
+        );
+    });
+});

package/src/shared/tag-owner-id.ts

@@ -0,0 +1,29 @@
+/**
+ * Content tag ids name the message that owns them plus a suffix that picks one
+ * part of it. Two suffix families exist:
+ *
+ * - positional: `<messageId>:p<N>` for the Nth text part, `<messageId>:file<N>`
+ *   for the Nth file part;
+ * - content-derived (Pi, after the text of a message drifts):
+ *   `<messageId>:mc-text-v1:<vector digest>:<content digest>:o<occurrence>`.
+ *
+ * Anything that groups tags by message has to strip both, or a content-derived
+ * tag is treated as belonging to a message that does not exist.
+ */
+
+export const TEXT_TAG_IDENTITY_MARKER = ":mc-text-v1:";
+
+const POSITIONAL_CONTENT_SUFFIX = /:(?:p|file)\d+$/;
+const CONTENT_DERIVED_TEXT_SUFFIX = /:mc-text-v1:[0-9a-f]+:[0-9a-f]+:o\d+$/;
+
+/**
+ * The owning message id of a content tag id. An id with neither suffix is
+ * returned unchanged: it already is the message id.
+ */
+export function contentTagOwnerMessageId(contentId: string): string {
+    const positional = POSITIONAL_CONTENT_SUFFIX.exec(contentId);
+    if (positional) return contentId.slice(0, positional.index);
+    const derived = CONTENT_DERIVED_TEXT_SUFFIX.exec(contentId);
+    if (derived) return contentId.slice(0, derived.index);
+    return contentId;
+}