om-memory-system 3.1.1 → 3.2.0-next.11

package/README.md

@@ -122,7 +122,10 @@ import guides, and the [CLI reference](docs/cli.md).
 Pi shows a notice when a new version is out; update with
 `pi update npm:om-memory-system`. On OpenCode v2, run `opencode plugin check`
 and `opencode plugin update om-memory-system`. Restart the agent afterwards.
-Coming from `opencode-mem`? Your memories move over automatically, with a
+To stay on one version, install it with the number, for example
+`pi install npm:om-memory-system@3.1.1` or
+`opencode plugin add om-memory-system@3.1.1`; a pinned install is never
+updated. Coming from `opencode-mem`? Your memories move over automatically, with a
 backup first. See [Updating and upgrading](docs/upgrading.md) and
 [CHANGELOG.md](CHANGELOG.md).
 

package/dist/adapters/opencode/auto-capture-summary.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { CONFIG } from "../../config.js";
 import { resolveOpencodeHostModel } from "../../services/ai/live-model-choice.js";
 import { buildBoundedSummaryPrompt } from "../../core/capture-context.js";
-import { parseCaptureSummary } from "../../core/extraction.js";
+import { classifyCaptureReply, normalizeStopReason, parseCaptureSummary, } from "../../core/extraction.js";
 import { log } from "../../services/logger.js";
 import { loadOpencodeProvider } from "../../services/ai/opencode-provider-loader.js";
 function buildSystemPrompt(languageName) {
@@ -26,8 +26,19 @@ FORMAT:
 SKIP if: greetings, casual chat, no code/decisions made
 CAPTURE if: code changed, bug fixed, feature added, decision made`;
 }
+/** Reason code for an error thrown on the OpenCode host-model path. */
+function hostModelFailureReason(error) {
+    if (error instanceof Error && error.name === "ZodError")
+        return "schema-mismatch";
+    if (String(error).includes("returned no structured output"))
+        return "empty-text";
+    return "call-error";
+}
 export async function generateOpenCodeAutoCaptureSummary(request, notify) {
     let opencodeProviderError;
+    // Filled per path; when the host model falls back, the external API attempt
+    // overwrites it, so the record describes the call that decided the outcome.
+    const diagnostics = request.diagnostics ?? {};
     const hostModel = resolveOpencodeHostModel(CONFIG);
     if (hostModel) {
         try {
@@ -40,6 +51,9 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
                 ...hostModel,
                 prompt: request.prompt,
             });
+            diagnostics.path = "host-model";
+            diagnostics.provider = providerID;
+            diagnostics.model = modelID;
             if (!isProviderConnected(providerID)) {
                 throw new Error(`opencode provider '${providerID}' is not connected. Check your opencode provider configuration.`);
             }
@@ -59,6 +73,8 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
                 tags: z.array(z.string()),
             });
             const aiPrompt = buildBoundedSummaryPrompt(request.context, systemPrompt, z.toJSONSchema(schema));
+            diagnostics.systemPrompt = systemPrompt;
+            diagnostics.userPrompt = aiPrompt;
             const result = await generateStructuredOutput({
                 client: v2Client,
                 providerID,
@@ -66,6 +82,12 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
                 systemPrompt,
                 userPrompt: aiPrompt,
                 schema,
+                onReply: (reply) => {
+                    diagnostics.stopReason = normalizeStopReason(reply.finish);
+                    diagnostics.blockTypes = reply.partTypes;
+                    diagnostics.rawReply =
+                        reply.structuredOutput === undefined ? "" : JSON.stringify(reply.structuredOutput);
+                },
             });
             return {
                 summary: result.summary,
@@ -75,6 +97,7 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
         }
         catch (error) {
             opencodeProviderError = error;
+            diagnostics.failureReason = hostModelFailureReason(error);
             log("auto-capture: opencode provider failed, falling back to external API", {
                 error: String(error),
             });
@@ -134,19 +157,38 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
     };
     const aiPrompt = buildBoundedSummaryPrompt(request.context, systemPrompt, toolSchema);
     const captureSessionID = `auto-capture-${request.prompt?.id ?? request.sessionId}-${randomUUID()}`;
-    const result = await provider.executeToolCall(systemPrompt, aiPrompt, toolSchema, captureSessionID);
+    // Replace whatever the failed host-model attempt recorded.
+    Object.assign(diagnostics, {
+        path: "external-api",
+        provider: CONFIG.memoryProvider,
+        model: CONFIG.memoryModel,
+        systemPrompt,
+        userPrompt: aiPrompt,
+        stopReason: undefined,
+        blockTypes: undefined,
+        rawReply: undefined,
+        failureReason: undefined,
+    });
+    let result;
+    try {
+        result = await provider.executeToolCall(systemPrompt, aiPrompt, toolSchema, captureSessionID);
+    }
+    catch (error) {
+        diagnostics.failureReason = "call-error";
+        throw error;
+    }
+    diagnostics.stopReason = normalizeStopReason(result.stopReason);
     if (!result.success || !result.data) {
+        diagnostics.failureReason = diagnostics.stopReason === "length" ? "truncated" : "call-error";
         throw new Error(result.error || "Failed to generate summary");
     }
     const rawReply = JSON.stringify(result.data);
+    diagnostics.rawReply = rawReply;
     const summary = parseCaptureSummary(rawReply);
     if (!summary) {
-        log("OpenCode capture: model reply was not a valid capture summary", {
-            provider: CONFIG.memoryProvider,
-            modelId: CONFIG.memoryModel,
-            // The reply can carry conversation content, so log only its size.
-            replyLength: rawReply.length,
-        });
+        // The capture pipeline logs the attempt's metadata; never the reply.
+        diagnostics.failureReason =
+            classifyCaptureReply({ text: rawReply, stopReason: result.stopReason }) ?? "schema-mismatch";
         throw new Error("omms: OpenCode extraction returned an invalid summary payload");
     }
     return summary;

package/dist/adapters/pi/extension.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { CONFIG, initConfigWithLegacyMigration, isConfigured } from "../../config.js";
+import { pruneTraces } from "../../services/capture-diagnostics.js";
 import { executeMemoryOperation } from "../../core/memory-operations.js";
 import { getLanguageName } from "../../services/language-detector.js";
 import { log } from "../../services/logger.js";
@@ -97,6 +98,8 @@ export default function ommsPiExtension(pi) {
         try {
             latestCtx = ctx;
             initConfigWithLegacyMigration(ctx.cwd);
+            // Runs even with tracing off, so turning it off does not leave old traces behind.
+            pruneTraces(CONFIG);
             captureState = createPiCaptureState();
             const globalScope = globalThis;
             if (!globalScope[GLOBAL_PLUGIN_WARMUP_KEY] && isConfigured()) {

package/dist/adapters/pi/provider.js

@@ -1,8 +1,7 @@
 import { CONFIG } from "../../config.js";
 import { buildBoundedSummaryPrompt } from "../../core/capture-context.js";
-import { buildCaptureSystemPrompt, captureSummaryToolSchema, parseCaptureSummary, } from "../../core/extraction.js";
+import { buildCaptureReplyInstruction, buildCaptureSystemPrompt, captureSummaryToolSchema, classifyCaptureReply, normalizeStopReason, parseCaptureSummary, } from "../../core/extraction.js";
 import { detectLanguage, getLanguageName } from "../../services/language-detector.js";
-import { log } from "../../services/logger.js";
 /**
  * Active-model-first resolution: the explicit `piProvider`/`piModel`
  * configuration when both are set, otherwise the active `ctx.model`.
@@ -80,23 +79,51 @@ export function createPiCaptureProvider(resolveModel) {
                 ? detectLanguage(request.userPrompt)
                 : CONFIG.autoCaptureLanguage;
             const systemPrompt = buildCaptureSystemPrompt(getLanguageName(targetLang));
-            const userPrompt = buildBoundedSummaryPrompt(request.context, systemPrompt, captureSummaryToolSchema);
-            const reply = await model.complete({
-                systemPrompt,
-                messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }],
-            });
+            const replyInstruction = buildCaptureReplyInstruction();
+            // The instruction is counted as schema bytes so the context budget leaves room for it.
+            const userPrompt = `${buildBoundedSummaryPrompt(request.context, systemPrompt, {
+                schema: captureSummaryToolSchema,
+                replyInstruction,
+            })}\n\n${replyInstruction}`;
+            const diagnostics = request.diagnostics;
+            if (diagnostics) {
+                diagnostics.path = "host-model";
+                diagnostics.provider = model.provider;
+                diagnostics.model = model.modelId;
+                diagnostics.systemPrompt = systemPrompt;
+                diagnostics.userPrompt = userPrompt;
+            }
+            let reply;
+            try {
+                reply = await model.complete({
+                    systemPrompt,
+                    messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }],
+                });
+            }
+            catch (error) {
+                if (diagnostics)
+                    diagnostics.failureReason = "call-error";
+                throw error;
+            }
+            const rawReply = replyText(reply);
+            if (diagnostics) {
+                diagnostics.stopReason = normalizeStopReason(reply.stopReason);
+                diagnostics.blockTypes = reply.content.map((block) => block.type);
+                diagnostics.rawReply = rawReply;
+            }
             if (reply.stopReason === "error") {
+                if (diagnostics)
+                    diagnostics.failureReason = "call-error";
                 throw new Error(`omms: Pi extraction call failed: ${reply.errorMessage || "unknown error"}`);
             }
-            const rawReply = replyText(reply);
             const summary = parseCaptureSummary(rawReply);
             if (!summary) {
-                log("Pi capture: model reply was not a valid capture summary", {
-                    provider: model.provider,
-                    modelId: model.modelId,
-                    // The reply can carry conversation content, so log only its size.
-                    replyLength: rawReply.length,
-                });
+                // The capture pipeline logs the attempt's metadata; never the reply.
+                if (diagnostics) {
+                    diagnostics.failureReason =
+                        classifyCaptureReply({ text: rawReply, stopReason: reply.stopReason }) ??
+                            "schema-mismatch";
+                }
                 throw new Error("omms: Pi extraction returned an invalid summary payload");
             }
             return summary;

package/dist/config.d.ts

@@ -38,6 +38,9 @@ interface OmmsConfig {
     piProvider?: string;
     piModel?: string;
     aiSessionRetentionDays?: number;
+    /** Write full capture prompts and replies to ~/.omms/traces. Global config only. */
+    captureTrace?: boolean;
+    captureTraceRetentionDays?: number;
     webServerEnabled?: boolean;
     webServerPort?: number;
     webServerHost?: string;
@@ -119,6 +122,8 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     piModel: string | undefined;
     autoCaptureProviderStatus: import("./config.js").AutoCaptureProviderStatus;
     aiSessionRetentionDays: number;
+    captureTrace: boolean;
+    captureTraceRetentionDays: number;
     webServerEnabled: boolean;
     webServerPort: number;
     webServerHost: string;
@@ -201,6 +206,8 @@ export declare let CONFIG: {
     piModel: string | undefined;
     autoCaptureProviderStatus: import("./config.js").AutoCaptureProviderStatus;
     aiSessionRetentionDays: number;
+    captureTrace: boolean;
+    captureTraceRetentionDays: number;
     webServerEnabled: boolean;
     webServerPort: number;
     webServerHost: string;

package/dist/config.js

@@ -48,6 +48,8 @@ const DEFAULTS = {
     autoCaptureMaxRetries: 3,
     autoCaptureMaxContextBytes: 131072,
     aiSessionRetentionDays: 7,
+    captureTrace: false,
+    captureTraceRetentionDays: 7,
     webServerEnabled: true,
     webServerPort: 4747,
     webServerHost: "127.0.0.1",
@@ -352,6 +354,16 @@ const CONFIG_TEMPLATE = `{
   // Days to keep AI session history before cleanup
   "aiSessionRetentionDays": 7,
 
+  // Capture diagnostics: every capture attempt always writes one metadata line
+  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no
+  // conversation text. Set captureTrace to true to also write each attempt's
+  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain
+  // conversation content: <private> text and common API key formats are
+  // redacted, files are readable only by you, and they are deleted after
+  // captureTraceRetentionDays. Only this global file can turn tracing on.
+  // "captureTrace": false,
+  // "captureTraceRetentionDays": 7,
+
   // Temperature for AI API requests (set to false to omit parameter for models that don't support it)
   // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter
   // Set to false and add "memoryTemperature": false in config when using such models
@@ -580,6 +592,8 @@ function buildConfig(fileConfig) {
             memoryApiKey,
         }),
         aiSessionRetentionDays: fileConfig.aiSessionRetentionDays ?? DEFAULTS.aiSessionRetentionDays,
+        captureTrace: fileConfig.captureTrace === true,
+        captureTraceRetentionDays: Math.max(1, Math.floor(fileConfig.captureTraceRetentionDays ?? DEFAULTS.captureTraceRetentionDays)),
         webServerEnabled: fileConfig.webServerEnabled ?? DEFAULTS.webServerEnabled,
         webServerPort: fileConfig.webServerPort ?? DEFAULTS.webServerPort,
         webServerHost: fileConfig.webServerHost ?? DEFAULTS.webServerHost,
@@ -660,6 +674,13 @@ export function initConfig(directory) {
     const projectOverrides = { ...projectConfig };
     delete projectOverrides.autoCleanupEnabled;
     delete projectOverrides.autoCleanupRetentionDays;
+    // A checked-in project file must not start recording conversations; it may
+    // only turn tracing off for its project.
+    if (projectOverrides.captureTrace === true) {
+        log("Project config cannot turn on captureTrace; the value was ignored", { directory });
+        delete projectOverrides.captureTrace;
+    }
+    delete projectOverrides.captureTraceRetentionDays;
     const merged = { ...globalConfig, ...projectOverrides };
     lastFileConfig = merged;
     CONFIG = buildConfig(merged);

package/dist/core/capture-context.js

@@ -4,7 +4,7 @@ const DEFAULT_AUTO_CAPTURE_MAX_CONTEXT_BYTES = 131072;
 const CONTEXT_TRUNCATION_MARKER = "\n[... truncated to autoCaptureMaxContextBytes ...]\n";
 const SUMMARY_REQUEST_OVERHEAD_BYTES = 1024;
 const SUMMARY_OUTPUT_RESERVE_BYTES = 16384;
-const SUMMARY_ANALYSIS_SUFFIX = 'Analyze this conversation. If it contains technical work (code, bugs, features, decisions), create a concise summary and relevant tags. If it\'s non-technical (greetings, casual chat, incomplete requests), return type="skip" with empty summary.';
+const SUMMARY_ANALYSIS_SUFFIX = 'Analyze this conversation. If it contains technical work (code, bugs, features, decisions), create a concise summary and relevant tags. If it\'s non-technical (greetings, casual chat, incomplete requests), set "type" to "skip" with an empty "summary".';
 function fitTextResponses(textResponses, maxBytes) {
     if (textResponses.length === 0 || maxBytes <= 0)
         return "";

package/dist/core/capture.d.ts

@@ -12,4 +12,8 @@ export type CaptureResult = {
     status: "skipped";
     type?: string;
 };
+/**
+ * Run one capture attempt and write exactly one diagnostics record for it,
+ * whether it is saved, skipped, or fails.
+ */
 export declare function captureConversation(workUnit: CaptureWorkUnit, provider: CaptureSummaryProvider): Promise<CaptureResult>;

package/dist/core/capture.js

@@ -1,3 +1,5 @@
+import { CONFIG } from "../config.js";
+import { buildCaptureAttemptRecord, emitCaptureAttempt } from "../services/capture-diagnostics.js";
 import { memoryClient } from "../services/client.js";
 import { getTags } from "../services/tags.js";
 import { buildMarkdownContext, getAutoCaptureMarkdownBudget } from "./capture-context.js";
@@ -15,7 +17,29 @@ async function getLatestProjectMemory(containerTag) {
         return null;
     }
 }
+/**
+ * Run one capture attempt and write exactly one diagnostics record for it,
+ * whether it is saved, skipped, or fails.
+ */
 export async function captureConversation(workUnit, provider) {
+    const diagnostics = {};
+    const startedAt = Date.now();
+    let outcome = "failed";
+    try {
+        const result = await runCapture(workUnit, provider, diagnostics);
+        outcome = result.status === "captured" ? "saved" : "skipped";
+        return result;
+    }
+    finally {
+        const record = buildCaptureAttemptRecord({
+            host: workUnit.host,
+            sourceType: workUnit.sourceType,
+            sessionId: workUnit.hostSessionId,
+        }, diagnostics, outcome, Date.now() - startedAt);
+        emitCaptureAttempt(record, diagnostics, CONFIG);
+    }
+}
+async function runCapture(workUnit, provider, diagnostics) {
     const tags = getTags(workUnit.projectDirectory);
     const latestMemory = await getLatestProjectMemory(tags.project.tag);
     const context = buildMarkdownContext(workUnit.userPrompt, workUnit.textResponses, workUnit.toolCalls, latestMemory, getAutoCaptureMarkdownBudget());
@@ -27,9 +51,11 @@ export async function captureConversation(workUnit, provider) {
             projectDirectory: workUnit.projectDirectory,
             userPrompt: workUnit.userPrompt,
             prompt: workUnit.prompt,
+            diagnostics,
         });
     }
     catch (error) {
+        diagnostics.failureReason ??= "call-error";
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Summary generation failed: ${message}`, { cause: error });
     }
@@ -40,6 +66,8 @@ export async function captureConversation(workUnit, provider) {
         ? `${summaryResult.summary}\n\nTags: ${summaryResult.tags.join(", ")}`
         : summaryResult.summary;
     const source = workUnit.sourceType === "history-import" ? "import" : "auto-capture";
+    // Anything that goes wrong from here on is a storage failure, thrown or reported.
+    diagnostics.failureReason = "persist-error";
     const result = await memoryClient.addMemory(summaryWithTags, tags.project.tag, {
         source,
         type: summaryResult.type,
@@ -64,5 +92,6 @@ export async function captureConversation(workUnit, provider) {
     if (!result.success) {
         throw new Error(`Memory persistence failed: ${result.error || "database write failed"}`);
     }
+    diagnostics.failureReason = undefined;
     return { status: "captured", memoryId: result.id };
 }

package/dist/core/extraction.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { CaptureSummary } from "./host.js";
+import type { CaptureFailureReason, CaptureSummary } from "./host.js";
 /**
  * Shared structured-extraction contract for automatic capture.
  *
@@ -38,6 +38,13 @@ export declare const captureSummaryToolSchema: {
     };
     required: string[];
 };
+/**
+ * Reply-format instruction for paths that get plain text back (the Pi model
+ * bridge). Structured-output and tool-call paths enforce the shape themselves,
+ * so without this the model only sees the Markdown layout of the summary field
+ * and `type="skip"`, and tends to answer in that form instead of JSON.
+ */
+export declare function buildCaptureReplyInstruction(): string;
 export declare function buildCaptureSystemPrompt(languageName: string): string;
 /** Upper bound for LLM-inferred preference confidence (0–1 scale). */
 export declare const USER_PROFILE_LLM_CONFIDENCE_MAX = 1;
@@ -78,3 +85,18 @@ export declare function extractJsonObject(raw: string): unknown;
  * blocks and surrounding prose. Returns null when no valid payload is present.
  */
 export declare function parseCaptureSummary(raw: string): CaptureSummary | null;
+/**
+ * Map provider-specific stop reasons onto one vocabulary so a length limit
+ * reads as `length` on every extraction path. Other values pass through in
+ * lower case.
+ */
+export declare function normalizeStopReason(stopReason: string | null | undefined): string | undefined;
+/**
+ * Explain why a reply is not a usable capture summary. Returns null when the
+ * reply parses (including a skip). Codes are checked in the spec's order, so a
+ * cut-off reply reads as `truncated` rather than `invalid-json`.
+ */
+export declare function classifyCaptureReply(reply: {
+    text: string;
+    stopReason?: string | null;
+}): CaptureFailureReason | null;

package/dist/core/extraction.js

@@ -40,6 +40,18 @@ export const captureSummaryToolSchema = {
     },
     required: ["summary", "type", "tags"],
 };
+/**
+ * Reply-format instruction for paths that get plain text back (the Pi model
+ * bridge). Structured-output and tool-call paths enforce the shape themselves,
+ * so without this the model only sees the Markdown layout of the summary field
+ * and `type="skip"`, and tends to answer in that form instead of JSON.
+ */
+export function buildCaptureReplyInstruction() {
+    return `Reply with only one JSON object and nothing else: no prose, no code fence. It must match this JSON schema:
+${JSON.stringify(captureSummaryToolSchema)}
+Put the Markdown summary (## Request / ## Outcome) inside the "summary" string.
+For a non-technical conversation reply exactly: {"type":"skip","summary":"","tags":[]}`;
+}
 export function buildCaptureSystemPrompt(languageName) {
     return `You are a technical memory recorder for a software development project.
 
@@ -143,3 +155,32 @@ export function parseCaptureSummary(raw) {
         tags: parsed.data.tags.map((tag) => tag.toLowerCase().trim()).filter(Boolean),
     };
 }
+const LENGTH_STOP_REASONS = new Set(["length", "max_tokens", "max_output_tokens"]);
+/**
+ * Map provider-specific stop reasons onto one vocabulary so a length limit
+ * reads as `length` on every extraction path. Other values pass through in
+ * lower case.
+ */
+export function normalizeStopReason(stopReason) {
+    if (!stopReason)
+        return undefined;
+    const lower = stopReason.toLowerCase();
+    return LENGTH_STOP_REASONS.has(lower) ? "length" : lower;
+}
+/**
+ * Explain why a reply is not a usable capture summary. Returns null when the
+ * reply parses (including a skip). Codes are checked in the spec's order, so a
+ * cut-off reply reads as `truncated` rather than `invalid-json`.
+ */
+export function classifyCaptureReply(reply) {
+    if (parseCaptureSummary(reply.text))
+        return null;
+    if (reply.text.trim().length === 0)
+        return "empty-text";
+    if (normalizeStopReason(reply.stopReason) === "length")
+        return "truncated";
+    const json = extractJsonObject(reply.text);
+    if (json === null || typeof json !== "object" || Array.isArray(json))
+        return "invalid-json";
+    return "schema-mismatch";
+}

package/dist/core/host.d.ts

@@ -19,12 +19,35 @@ export interface CaptureSummary {
     type: string;
     tags: string[];
 }
+export type CaptureAttemptOutcome = "saved" | "skipped" | "failed";
+/** Fixed failure codes, in the order classification checks them. */
+export declare const CAPTURE_FAILURE_REASONS: readonly ["call-error", "empty-text", "truncated", "invalid-json", "schema-mismatch", "persist-error"];
+export type CaptureFailureReason = (typeof CAPTURE_FAILURE_REASONS)[number];
+export type CaptureExtractionPath = "host-model" | "external-api";
+/**
+ * Filled in by the extraction path during one capture attempt. The capture
+ * pipeline owns the object and emits it once the outcome is known. Fields a
+ * path cannot observe stay undefined. The prompt and reply fields are only
+ * ever written to the opt-in trace file, never to the log.
+ */
+export interface CaptureAttemptDiagnostics {
+    path?: CaptureExtractionPath;
+    provider?: string;
+    model?: string;
+    stopReason?: string;
+    blockTypes?: string[];
+    systemPrompt?: string;
+    userPrompt?: string;
+    rawReply?: string;
+    failureReason?: CaptureFailureReason;
+}
 export interface CaptureSummaryRequest {
     context: string;
     sessionId: string;
     projectDirectory: string;
     userPrompt: string;
     prompt?: CapturePromptContext;
+    diagnostics?: CaptureAttemptDiagnostics;
 }
 export interface CaptureSummaryProvider {
     summarize(request: CaptureSummaryRequest): Promise<CaptureSummary | null>;

package/dist/core/host.js

@@ -1 +1,9 @@
-export {};
+/** Fixed failure codes, in the order classification checks them. */
+export const CAPTURE_FAILURE_REASONS = [
+    "call-error",
+    "empty-text",
+    "truncated",
+    "invalid-json",
+    "schema-mismatch",
+    "persist-error",
+];

package/dist/index.js

@@ -11,6 +11,7 @@ import { formatMemoriesForCompaction } from "./core/retrieval.js";
 import { performUserProfileLearning } from "./services/user-memory-learning.js";
 import { userPromptManager } from "./services/user-prompt/user-prompt-manager.js";
 import { startWebServer, WebServer } from "./services/web-server.js";
+import { pruneTraces } from "./services/capture-diagnostics.js";
 import { ensureTursoReady } from "./services/turso/ready.js";
 import { tursoConnectionManager } from "./services/turso/connection-manager.js";
 import { WebAuth } from "./services/web-auth.js";
@@ -180,6 +181,8 @@ function logAutoCaptureProviderStatus() {
 export const OmmsPlugin = async (ctx) => {
     const { directory } = ctx;
     initConfigWithLegacyMigration(directory);
+    // Runs even with tracing off, so turning it off does not leave old traces behind.
+    pruneTraces(CONFIG);
     logAutoCaptureProviderStatus();
     const tags = getTags(directory);
     const autoCaptureHost = createOpenCodeAutoCaptureHost(ctx);

package/dist/services/ai/opencode-provider.d.ts

@@ -46,6 +46,8 @@ export declare const STRUCTURED_OUTPUT_METADATA: {
 };
 export declare function setHostFetch(customFetch: typeof fetch): void;
 export declare function resetHostFetch(): void;
+/** Test helper: forget the server URL, as in the native V2 plugin. */
+export declare function resetV2BaseUrlForTests(): void;
 export declare function setConnectedProviders(providers: string[]): void;
 export declare function isProviderConnected(providerName: string): boolean;
 export declare function setV2Client(client: OpencodeClient): void;
@@ -64,6 +66,13 @@ export interface StructuredOutputOptions<T> {
     schema: z.ZodType<T>;
     directory?: string;
     retryCount?: number;
+    /** Called with the raw reply before it is parsed, for capture diagnostics. */
+    onReply?: (reply: StructuredOutputReply) => void;
+}
+export interface StructuredOutputReply {
+    finish?: string;
+    partTypes: string[];
+    structuredOutput: unknown;
 }
 /**
  * Resolve `opencodeModel: "inherit"` to a concrete provider/model.

package/dist/services/ai/opencode-provider.js

@@ -60,6 +60,11 @@ export function setHostFetch(customFetch) {
 export function resetHostFetch() {
     _hostFetch = undefined;
 }
+/** Test helper: forget the server URL, as in the native V2 plugin. */
+export function resetV2BaseUrlForTests() {
+    _v2BaseUrl = undefined;
+    _useSdkTransport = false;
+}
 export function setConnectedProviders(providers) {
     _connectedProviders = new Set(providers);
 }
@@ -117,6 +122,22 @@ function sessionPromptFields(args) {
         },
     };
 }
+function reportReply(onReply, data) {
+    if (!onReply)
+        return;
+    try {
+        onReply({
+            ...(typeof data.info.finish === "string" ? { finish: data.info.finish } : {}),
+            partTypes: (Array.isArray(data.parts) ? data.parts : [])
+                .map((part) => typeof part === "object" && part !== null ? part.type : undefined)
+                .filter((type) => typeof type === "string"),
+            structuredOutput: data.info.structured_output ?? data.info.structured,
+        });
+    }
+    catch {
+        // Diagnostics must never change the call's result.
+    }
+}
 /**
  * Resolve `opencodeModel: "inherit"` to a concrete provider/model.
  *
@@ -167,10 +188,12 @@ export async function generateStructuredOutput(opts) {
         providerID: opts.providerID,
         modelID: opts.modelID,
     });
-    const { client, systemPrompt, userPrompt, schema, directory, retryCount } = opts;
+    const { client, systemPrompt, userPrompt, schema, directory, retryCount, onReply } = opts;
     const { providerID, modelID } = resolved;
     const jsonSchema = schema.toJSONSchema?.() ?? (await import("zod")).z.toJSONSchema(schema);
-    if (_useSdkTransport && hasV2SessionClient(client)) {
+    // The native V2 plugin has no server URL: it hands over a client whose
+    // session API wraps the plugin context, so that client is the only transport.
+    if ((_useSdkTransport || !_v2BaseUrl) && hasV2SessionClient(client)) {
         return generateViaSdkClient(client, {
             providerID,
             modelID,
@@ -180,6 +203,7 @@ export async function generateStructuredOutput(opts) {
             retryCount,
             jsonSchema,
             schema,
+            onReply,
         });
     }
     const baseUrl = _v2BaseUrl;
@@ -190,7 +214,7 @@ export async function generateStructuredOutput(opts) {
     const sessionID = await createSession(base, directory);
     markInternalSession(sessionID);
     try {
-        const info = await withStructuredOutputTimeout(() => promptSession(base, {
+        const reply = await withStructuredOutputTimeout(() => promptSession(base, {
             sessionID,
             directory,
             providerID,
@@ -200,6 +224,8 @@ export async function generateStructuredOutput(opts) {
             jsonSchema,
             retryCount,
         }), () => abortSession(base, sessionID, directory));
+        reportReply(onReply, reply);
+        const info = reply.info;
         if (info.error) {
             throw new Error(`omms: opencode reported ${info.error.name}: ${formatAssistantError(info.error)}`);
         }
@@ -258,6 +284,7 @@ async function generateViaSdkClient(client, args) {
         if (!data.info) {
             throw new Error("omms: prompt response missing `info`");
         }
+        reportReply(args.onReply, data);
         if (data.info.error) {
             throw new Error(`omms: opencode reported ${data.info.error.name}: ${formatAssistantError(data.info.error)}`);
         }
@@ -387,7 +414,7 @@ async function promptSession(base, args) {
     if (!data.info) {
         throw new Error("omms: prompt response missing `info`");
     }
-    return data.info;
+    return data;
 }
 async function abortSession(base, sessionID, directory) {
     const url = `${base}/session/${encodeURIComponent(sessionID)}/abort${buildQuery(directory)}`;