@cortexkit/opencode-magic-context 0.44.4 → 0.45.0

package/src/shared/embedding-activity.ts

@@ -0,0 +1,36 @@
+/** Track busy status only for sessions observed by this process; untracked sessions are not assumed busy. */
+const busySessions = new Set<string>();
+
+export function setEmbeddingSessionBusy(sessionId: string, busy: boolean): void {
+    if (busy) busySessions.add(sessionId);
+    else busySessions.delete(sessionId);
+}
+
+export function observeEmbeddingActivity(event: { type: string; properties?: unknown }): void {
+    const props = event.properties as
+        | { sessionID?: string; status?: { type?: string } }
+        | undefined;
+    if (!props || typeof props.sessionID !== "string") return;
+    if (
+        event.type === "session.idle" ||
+        event.type === "session.deleted" ||
+        (event.type === "session.status" && props.status?.type === "idle")
+    ) {
+        setEmbeddingSessionBusy(props.sessionID, false);
+    } else if (event.type === "session.status" && props.status?.type) {
+        setEmbeddingSessionBusy(props.sessionID, true);
+    }
+}
+
+export function isEmbeddingHostBusy(): boolean {
+    return busySessions.size > 0;
+}
+
+/**
+ * Forget every busy session (tests only). A test that starts an agent turn and
+ * never ends it would otherwise leave the whole process busy, and background
+ * embedding in later tests of the same process would stop at once.
+ */
+export function resetEmbeddingActivityForTests(): void {
+    busySessions.clear();
+}

package/src/shared/historian-tool-defaults.json

@@ -0,0 +1,13 @@
+{
+  "ctx_note": "Note ${input.action} ${input.note_ids}: ${input.content} → ${output.truncate(160)}",
+  "ctx_memory": "Memory ${input.action} ${input.category} ${input.ids}: ${input.content} → ${output.truncate(160)}",
+  "todowrite": "Todos (${input.todos.count}): ${input.todos.each(\"${status}: ${content}\")}",
+  "question": "Asked user: ${input.questions[*].question.join(\" / \")} → ${output}",
+  "task": "Task ${input.subagent_type}: ${input.prompt} → ${output.truncate(200)}",
+  "ask": "Asked: ${input.question.truncate(250)} [options: ${input.options.join(\" / \")}] ${input.resolution} → ${output.truncate(300)}",
+  "peer_send": "PM to ${input.agent}${input.agent_id}: ${input.message.truncate(400)}",
+  "board": "Board ${input.verb}: ${input.ops.each(\"${op} ${item}${lane.title} ${state}${lane.status}${props.text} ${lane.items[*].text}\")}",
+  "room": "Room ${input.action} ${input.room_id}: ${input.text.truncate(400)}",
+  "work": "Work ${input.action} ${input.id}: ${input.prompt_file}${input.prompt.truncate(200)}${input.notes.truncate(200)} → ${output.truncate(160)}",
+  "knowhow": "Looked up how-to: ${input.query}${input.id}"
+}

package/src/shared/historian-tool-expansions.ts

@@ -0,0 +1,18 @@
+import defaults from "./historian-tool-defaults.json";
+import { renderToolTemplate, type ToolExpansionMap } from "./historian-tool-template";
+
+export { defaults as DEFAULT_TOOL_EXPANSIONS };
+export function expandToolPart(part: unknown, overrides?: ToolExpansionMap): string | null {
+    if (!part || typeof part !== "object") return null;
+    const p = part as Record<string, unknown>;
+    if (p.type !== "tool" || typeof p.tool !== "string") return null;
+    const template =
+        overrides && Object.hasOwn(overrides, p.tool)
+            ? overrides[p.tool]
+            : Object.hasOwn(defaults, p.tool)
+              ? defaults[p.tool as keyof typeof defaults]
+              : undefined;
+    if (typeof template !== "string") return null;
+    const state = p.state as Record<string, unknown> | undefined;
+    return renderToolTemplate(template, state?.input, state?.output ?? state?.error);
+}

package/src/shared/historian-tool-template.ts

@@ -0,0 +1,248 @@
+/** A deliberately non-executable language for readable, bounded historian tool lines. */
+export type ToolExpansionMap = Record<string, string | false>;
+type Step = { field: string } | { index: number } | { project: string };
+type Expression = {
+    steps: Step[];
+    each?: Template;
+    join?: string;
+    count?: boolean;
+    cap: number;
+};
+type Template = Array<string | Expression>;
+
+class Parser {
+    pos = 0;
+    constructor(private source: string) {}
+    error(): never {
+        throw new Error(`Invalid tool expansion template at character ${this.pos + 1}`);
+    }
+    take(value: string): boolean {
+        if (!this.source.startsWith(value, this.pos)) return false;
+        this.pos += value.length;
+        return true;
+    }
+    field(): string {
+        const match = /^[A-Za-z_][A-Za-z0-9_-]*/.exec(this.source.slice(this.pos));
+        if (!match) return this.error();
+        this.pos += match[0].length;
+        return match[0];
+    }
+    quoted(): string {
+        const start = this.pos;
+        if (!this.take('"')) return this.error();
+        while (this.pos < this.source.length) {
+            if (this.take("\\")) {
+                this.pos++;
+                continue;
+            }
+            if (this.take('"')) {
+                try {
+                    return JSON.parse(this.source.slice(start, this.pos));
+                } catch {
+                    return this.error();
+                }
+            }
+            this.pos++;
+        }
+        return this.error();
+    }
+    integer(): number {
+        const match = /^\d+/.exec(this.source.slice(this.pos));
+        if (!match) return this.error();
+        this.pos += match[0].length;
+        const n = Number(match[0]);
+        if (!Number.isSafeInteger(n)) return this.error();
+        return n;
+    }
+    expression(relative: boolean): Expression {
+        const steps: Step[] = [];
+        if (!(relative && this.take("."))) {
+            const root = this.field();
+            if (!relative && root !== "input" && root !== "output") return this.error();
+            steps.push({ field: root });
+        }
+        while (true) {
+            if (this.take("[")) {
+                if (this.take("*].")) steps.push({ project: this.field() });
+                else {
+                    const index = this.integer();
+                    if (!this.take("]")) return this.error();
+                    steps.push({ index });
+                }
+            } else if (
+                this.source[this.pos] === "." &&
+                !/^\.(each\(|join\(|count(?:\.|\})|truncate\()/.test(this.source.slice(this.pos))
+            ) {
+                this.pos++;
+                steps.push({ field: this.field() });
+                if (this.source[this.pos] === "(") return this.error();
+            } else break;
+        }
+        const expression: Expression = { steps, cap: 300 };
+        if (this.take(".each(")) {
+            if (relative) return this.error();
+            expression.each = parseTemplate(this.quoted(), true);
+            if (!this.take(")")) return this.error();
+        }
+        if (this.take(".join(")) {
+            expression.join = this.quoted();
+            if (!this.take(")")) return this.error();
+        }
+        if (this.take(".count")) {
+            if (expression.each || expression.join !== undefined) return this.error();
+            expression.count = true;
+        }
+        if (this.take(".truncate(")) {
+            expression.cap = this.integer();
+            if (!this.take(")")) return this.error();
+        }
+        if (!this.take("}")) return this.error();
+        return expression;
+    }
+    template(relative: boolean): Template {
+        const nodes: Template = [];
+        while (this.pos < this.source.length) {
+            const next = this.source.indexOf("${", this.pos);
+            if (next < 0) {
+                nodes.push(this.source.slice(this.pos));
+                break;
+            }
+            nodes.push(this.source.slice(this.pos, next));
+            this.pos = next + 2;
+            nodes.push(this.expression(relative));
+        }
+        return nodes;
+    }
+}
+
+function parseTemplate(source: string, relative = false): Template {
+    return new Parser(source).template(relative);
+}
+
+export function toolTemplateError(source: string): string | undefined {
+    try {
+        parseTemplate(source);
+        return undefined;
+    } catch (error) {
+        return (error as Error).message;
+    }
+}
+
+const templates = new Map<string, Template | null>();
+function compiled(source: string): Template | null {
+    if (!templates.has(source)) {
+        // Validation belongs to config loading. Malformed data from an older host
+        // must never interrupt a historian run.
+        try {
+            templates.set(source, parseTemplate(source));
+        } catch {
+            templates.set(source, null);
+        }
+    }
+    return templates.get(source) ?? null;
+}
+
+function oneLine(value: string): string {
+    return value.replace(/[\r\n\u2028\u2029]+/g, " ");
+}
+function truncate(value: string, cap: number): string {
+    const chars = Array.from(oneLine(value));
+    return chars.length > cap ? `${chars.slice(0, cap).join("")}…` : chars.join("");
+}
+function scalar(value: unknown): string {
+    if (value === undefined) return "";
+    return typeof value === "string" ? value : compactJson(value);
+}
+// Sort object keys so the two engines do not depend on their JSON map insertion order.
+function compactJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map((v) => compactJson(v)).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.keys(value)
+            .sort()
+            .map(
+                (key) =>
+                    `${JSON.stringify(key)}:${compactJson((value as Record<string, unknown>)[key])}`,
+            )
+            .join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+function field(value: unknown, key: string): unknown {
+    return value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.hasOwn(value, key)
+        ? (value as Record<string, unknown>)[key]
+        : undefined;
+}
+function render(nodes: Template, root: unknown): string {
+    return nodes
+        .map((node) => {
+            if (typeof node === "string") return node;
+            let value = root;
+            let list = false;
+            for (const step of node.steps) {
+                if ("field" in step)
+                    value =
+                        list && Array.isArray(value)
+                            ? value.map((item) => field(item, step.field))
+                            : field(value, step.field);
+                else if ("index" in step)
+                    value = Array.isArray(value) ? value[step.index] : undefined;
+                else {
+                    value = Array.isArray(value)
+                        ? value.map((item) => field(item, step.project))
+                        : undefined;
+                    list = true;
+                }
+            }
+            if (node.count)
+                return truncate(Array.isArray(value) ? String(value.length) : "", node.cap);
+            if (node.each || list || node.join !== undefined) {
+                if (!Array.isArray(value)) return "";
+                const elements = value
+                    .slice(0, 10)
+                    .map((item) =>
+                        truncate(node.each ? render(node.each, item) : scalar(item), 300),
+                    );
+                if (value.length > 10) elements.push(`… +${value.length - 10} more`);
+                return truncate(elements.join(node.join ?? (node.each ? "; " : ", ")), node.cap);
+            }
+            return truncate(scalar(value), node.cap);
+        })
+        .join("");
+}
+
+export function renderToolTemplate(
+    source: string,
+    input: unknown,
+    output?: unknown,
+): string | null {
+    const nodes = compiled(source);
+    if (!nodes) return null;
+    const text =
+        typeof output === "string" ? output : output === undefined ? "" : compactJson(output);
+    let structured: unknown = output;
+    if (typeof output === "string") {
+        try {
+            const parsed = JSON.parse(output);
+            structured =
+                parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+        } catch {
+            structured = undefined;
+        }
+    }
+    // The bare output placeholder is the original result text, not reserialized JSON.
+    const root = { input, output: structured };
+    const bareOutputNodes = nodes.map((node) =>
+        typeof node !== "string" &&
+        node.steps.length === 1 &&
+        "field" in node.steps[0] &&
+        node.steps[0].field === "output" &&
+        !node.each &&
+        !node.count &&
+        node.join === undefined
+            ? truncate(text ?? "", node.cap)
+            : node,
+    );
+    return truncate(render(bareOutputNodes, root), 1000);
+}

package/src/shared/historian-transient-error.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+
+import { isTransientHistorianPromptError } from "./historian-transient-error";
+
+describe("isTransientHistorianPromptError", () => {
+    it.each([
+        "429 rate limit from provider",
+        "rate_limit_error: slow down",
+        "503 Service Unavailable",
+        "502 Bad Gateway from upstream", // "bad gateway" is not "bad request"
+        "500 Internal Server Error",
+        "Overloaded",
+        "request timeout",
+        "read ECONNRESET",
+        "connect ETIMEDOUT",
+        "503 upstream author-profile service unavailable",
+    ])("retries %p", (message) => {
+        expect(isTransientHistorianPromptError(message)).toBe(true);
+    });
+
+    it.each([
+        "401 unauthorized",
+        "403 Forbidden",
+        "authentication_error: invalid x-api-key",
+        "OAuth token expired; 503",
+        "Authorization header missing (429)",
+        "400 Bad Request",
+        "status 400: malformed",
+        "invalid_request_error: prompt is too long: 250000 tokens > 200000 maximum",
+        "prompt is too long: 250000 tokens",
+        "request id 15003 failed",
+        "model not found",
+    ])("does not retry %p", (message) => {
+        expect(isTransientHistorianPromptError(message)).toBe(false);
+    });
+});

package/src/shared/historian-transient-error.ts

@@ -0,0 +1,22 @@
+/**
+ * Decide whether a failed historian prompt is worth retrying on the same model.
+ *
+ * Provider errors arrive as free text, so this is a keyword test, but every
+ * keyword must stand alone: "auth" must not match "author", and status 500
+ * must not match "250000" inside "prompt is too long: 250000 tokens". A
+ * misread here either retries a request that can never succeed (twice more,
+ * at full cost) or gives up on a provider blip.
+ *
+ * Shared by the OpenCode and Pi historian runners so both classify alike.
+ */
+const NON_TRANSIENT_PATTERN =
+    /(?<![a-z])(?:invalid[ _]request|bad[ _]request|unauthori[sz]ed|forbidden|authentication|authenticate|authorization|o?auth)(?![a-z])|(?:^| )400(?!\d)/;
+
+const TRANSIENT_PATTERN =
+    /(?<!\d)(?:429|500|502|503)(?!\d)|rate[ _]limit|timeout|econnreset|etimedout|overloaded/;
+
+export function isTransientHistorianPromptError(message: string): boolean {
+    const normalized = message.toLowerCase();
+    if (NON_TRANSIENT_PATTERN.test(normalized)) return false;
+    return TRANSIENT_PATTERN.test(normalized);
+}

package/src/shared/jsonc-edit.ts

@@ -256,7 +256,26 @@ export function setJsoncValue(text: string, path: JSONPath, value: unknown): str
         return text.slice(0, node.offset) + serialized + text.slice(node.offset + node.length);
     }
 
-    return applyEdits(text, modify(text, path, value, {}));
+    return applyEdits(
+        text,
+        modify(text, path, value, { formattingOptions: documentFormatting(text) }),
+    );
+}
+
+/**
+ * The line ending and indentation a document already uses, so an inserted
+ * property is laid out like its siblings instead of being written compactly
+ * onto the previous line.
+ */
+function documentFormatting(text: string): {
+    eol: string;
+    insertSpaces: boolean;
+    tabSize: number;
+} {
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const indent = /\n([ \t]+)\S/.exec(text)?.[1];
+    if (indent?.startsWith("\t")) return { eol, insertSpaces: false, tabSize: 1 };
+    return { eol, insertSpaces: true, tabSize: indent ? indent.length : 2 };
 }
 
 function removeObjectProperty(text: string, object: Node, key: string): string {

package/src/shared/logger.test.ts

@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { rmSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { createTestTempDirFromPath } from "./test-temp-dir";
 
 type LoggerScenarioResult = {
     exists: boolean;
@@ -186,7 +187,7 @@ async function runLoggerScenario<T>(
         | "bounded"
         | "oversized",
 ): Promise<T> {
-    const root = mkdtempSync(path.join(os.tmpdir(), "magic-context-logger-test-"));
+    const root = createTestTempDirFromPath(path.join(os.tmpdir(), "magic-context-logger-test-"));
     scenarioRoots.push(root);
     const child = Bun.spawn({
         windowsHide: true,

package/src/shared/logger.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getMagicContextLogPath } from "./data-path";
 import { sanitizeConfigValue, sanitizeDiagnosticText } from "./redaction";
+import { stalePluginBuildDiagnostic } from "./stale-plugin-build";
 
 const isTestEnv = process.env.NODE_ENV === "test";
 
@@ -189,9 +190,43 @@ function scheduleFlush(): void {
     }, FLUSH_INTERVAL_MS);
 }
 
-export function log(message: string, data?: unknown): void {
+// Set inside a worker thread so its lines reach the main thread's log file. The
+// log path depends on which host (OpenCode or Pi) the main thread registered,
+// and only the main thread's buffer and flush timer write that file.
+let lineForwarder: ((line: string) => void) | null = null;
+
+/**
+ * Hand every formatted log line to `forward` instead of this thread's buffer.
+ * Pass null to log locally again.
+ */
+export function setLogLineForwarder(forward: ((line: string) => void) | null): void {
+    lineForwarder = forward;
+}
+
+/** Append a line formatted by `log` on another thread, keeping its timestamp. */
+export function writeForwardedLogLine(line: string): void {
     if (isTestEnv) return;
     try {
+        buffer.push(line);
+        bufferedBytes += Buffer.byteLength(line);
+        boundBuffer();
+        if (buffer.length >= BUFFER_SIZE_LIMIT) flush();
+        else scheduleFlush();
+    } catch {
+        // Intentional: logging must never throw
+    }
+}
+
+export function log(message: string, data?: unknown): void {
+    try {
+        let diagnostic = stalePluginBuildDiagnostic(data);
+        if (diagnostic === undefined) diagnostic = stalePluginBuildDiagnostic(message);
+        if (diagnostic === null) return;
+        if (diagnostic !== undefined) {
+            message = diagnostic;
+            data = undefined;
+        }
+        if (isTestEnv) return;
         const timestamp = new Date().toISOString();
         const serialized =
             data === undefined
@@ -202,6 +237,10 @@ export function log(message: string, data?: unknown): void {
                     )}`
                   : ` ${JSON.stringify(sanitizeConfigValue(data))}`;
         const line = `[${timestamp}] ${sanitizeDiagnosticText(message)}${serialized}\n`;
+        if (lineForwarder) {
+            lineForwarder(line);
+            return;
+        }
         buffer.push(line);
         bufferedBytes += Buffer.byteLength(line);
         boundBuffer();

package/src/shared/model-suggestion-retry.test.ts

@@ -650,3 +650,49 @@ describe("host fetch TimeoutError is a timeout", () => {
         expect(abort).not.toHaveBeenCalled();
     });
 });
+
+test("empty v1 and v2 replies report the provider finish reason", async () => {
+    for (const output of [
+        [{ info: { role: "assistant", finish: "stop" }, parts: [] }],
+        { text: null, tokenLog: { finish_reason: "stop" } },
+    ]) {
+        const client = createClient(mock(async () => ({})));
+        await expect(
+            promptSyncWithValidatedOutputRetry(client, createArgs(), {
+                fetchOutput: async () => output,
+                validateOutput: () => {
+                    throw new Error("map-memories returned no output");
+                },
+            }),
+        ).rejects.toThrow("no output (finish=stop");
+    }
+});
+
+test("DeepSeek unsupported-model 400 preserves provider status and message rather than no output", async () => {
+    const message =
+        "The supported API model names are deepseek-flash, deepseek-v4-pro, but you passed deepseek-v4-flash";
+    const client = createClient(mock(async () => ({})));
+    let caught: unknown;
+    try {
+        await promptSyncWithValidatedOutputRetry(client, createArgs(), {
+            fetchOutput: async () => [
+                {
+                    info: {
+                        role: "assistant",
+                        error: { name: "APIError", data: { statusCode: 400, message } },
+                    },
+                    parts: [],
+                },
+            ],
+            validateOutput: () => {
+                throw new Error("map-memories returned no output");
+            },
+        });
+    } catch (error) {
+        caught = error;
+    }
+    expect((caught as Error).message).toContain(message);
+    expect((caught as Error).message).toContain("status=400");
+    expect((caught as Error).message).not.toContain("no output");
+    expect(getPromptFailureDetail(caught)).toMatchObject({ failureClass: "provider_error" });
+});

package/src/shared/model-suggestion-retry.ts

@@ -1,8 +1,11 @@
 import type { createOpencodeClient } from "@opencode-ai/sdk";
 import { DreamTokenBudgetExceeded } from "../features/magic-context/dreamer/token-budget";
 import { detectOverflow } from "../features/magic-context/overflow-detection";
+import { HiddenCompletionRefusal } from "../hooks/magic-context/compartment-runner-types";
 import { HiddenAgentStepLimit } from "../v2/hooks/hidden-child";
 import {
+    describeAssistantError,
+    describeAssistantSettlement,
     extractLatestAssistantFailure,
     extractLatestAssistantText,
 } from "./assistant-message-extractor";
@@ -114,6 +117,7 @@ export interface ValidatedPromptRetryResult<TOutput, TValidated> {
 export type PromptFailureClass =
     | "provider_timeout"
     | "provider_error"
+    | "local_refusal"
     | "step_limit"
     | "token_budget"
     | "empty_completion"
@@ -130,6 +134,7 @@ export interface PromptFailureDetail {
     providerError: string | null;
     timeoutMs: number | null;
     childSessionId: string | null;
+    refusalReason?: string | null;
 }
 
 const promptFailureDetails = new WeakMap<object, PromptFailureDetail>();
@@ -354,6 +359,7 @@ async function abortChildRun(client: Client, sessionId: string): Promise<void> {
 function isNonRetryable(error: unknown, externalSignal?: AbortSignal): boolean {
     if (
         externalSignal?.aborted ||
+        (error instanceof HiddenCompletionRefusal && error.terminal) ||
         error instanceof HiddenAgentStepLimit ||
         error instanceof DreamTokenBudgetExceeded
     )
@@ -398,6 +404,7 @@ function classifyPromptFailure(
     externalSignal?: AbortSignal,
 ): PromptFailureClass {
     const message = extractMessage(error);
+    if (error instanceof HiddenCompletionRefusal) return "local_refusal";
     if (error instanceof HiddenAgentStepLimit) return "step_limit";
     if (error instanceof DreamTokenBudgetExceeded) return "token_budget";
     if (externalSignal?.aborted || message === "prompt aborted by external signal") {
@@ -440,6 +447,11 @@ function throwWithPromptFailure(
         providerError,
         timeoutMs: failureClass === "provider_timeout" ? timeoutMs : null,
         childSessionId: transport ? (transport.childSessionId ?? null) : args.path.id || null,
+        ...(last?.error instanceof HiddenCompletionRefusal
+            ? {
+                  refusalReason: sanitizeDiagnosticText(last.error.message).slice(0, 500),
+              }
+            : {}),
     });
     throw error;
 }
@@ -659,7 +671,7 @@ async function attemptAndValidate<TOutput, TValidated>(
             const assistantFailure = extractLatestAssistantFailure(output);
             if (assistantFailure) {
                 const error = new Error(
-                    `Host recorded assistant error: ${String(assistantFailure.error)}`,
+                    `Host recorded assistant error: ${describeAssistantError(assistantFailure.error)}`,
                 );
                 Object.assign(error, {
                     name: "DreamerProviderOutputFailureError",
@@ -671,6 +683,9 @@ async function attemptAndValidate<TOutput, TValidated>(
         const validated = await options.validateOutput(output, attempt);
         return { output, validated, attempt };
     } catch (error) {
+        if (error instanceof Error && /no (?:assistant )?output/i.test(error.message)) {
+            error.message += ` (${describeAssistantSettlement(output)})`;
+        }
         throw {
             error,
             failureClass: classifyPromptFailure(error, "validation", signal),