@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/dist/shared/system-directive.d.ts

@@ -0,0 +1,3 @@
+export declare function isSystemDirective(text: string): boolean;
+export declare function removeSystemReminders(text: string): string;
+//# sourceMappingURL=system-directive.d.ts.map

package/dist/shared/system-directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-directive.d.ts","sourceRoot":"","sources":["../../src/shared/system-directive.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/shared/tag-owner-id.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare const TEXT_TAG_IDENTITY_MARKER = ":mc-text-v1:";
+/**
+ * The owning message id of a content tag id. An id with neither suffix is
+ * returned unchanged: it already is the message id.
+ */
+export declare function contentTagOwnerMessageId(contentId: string): string;
+//# sourceMappingURL=tag-owner-id.d.ts.map

package/dist/shared/tag-owner-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-owner-id.d.ts","sourceRoot":"","sources":["../../src/shared/tag-owner-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,wBAAwB,iBAAiB,CAAC;AAKvD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAMlE"}

package/dist/shared/tag-transcript.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Harness-agnostic tagging over the Transcript interface.
+ *
+ * This is a deliberately minimal alternative to the OpenCode-specific
+ * `tag-messages.ts` that operates on `MessageLike[]`. The OpenCode flow
+ * carries 380+ lines of accumulated complexity:
+ *
+ *   - source-content persistence (for cross-pass detag/restore behavior),
+ *   - tool-call indexing across separate "tool" and "tool_result" parts,
+ *   - reasoning-byte tracking for historian projection,
+ *   - file-part stable IDs,
+ *   - existing-tag resolver with content-id fallback.
+ *
+ * Most of that is OpenCode-specific (cache stability across multi-pass
+ * transforms, AI SDK part-id semantics, file part shapes). Pi's
+ * `pi.on("context", ...)` fires once per LLM call with a complete
+ * `AgentMessage[]`, so we can use a simpler tagging contract:
+ *
+ *   1. Walk the transcript in order.
+ *   2. For each tag-eligible part (text, tool_use, tool_result), assign
+ *      a tag number via the shared `Tagger`.
+ *   3. Inject `§N§ ` prefix into the visible text (unless skipped).
+ *   4. Build a `TagTarget` so `applyPendingOperations` from
+ *      `apply-operations.ts` can replace this part with a sentinel when
+ *      a queued drop fires.
+ *
+ * Tool drops aggregate by call_id across both invocation and result
+ * occurrences (mirrors OpenCode tag-messages.ts:196-220). When a drop
+ * fires for a tool tag, BOTH the assistant `toolCall`/`tool_use` part
+ * and the user `toolResult`/`tool_result` part are mutated together so
+ * the LLM sees consistent dropped state. Without this aggregation:
+ *
+ *   - Tool tag byte_size reflects only the args (~58 bytes for a `read`)
+ *     because the FIRST occurrence (invocation) is tagged first and
+ *     `assignTag` short-circuits the SECOND occurrence (result, ~4KB)
+ *     to the same tag without updating byte_size.
+ *   - Drops touch only the second occurrence (last write wins on
+ *     `targets.set`), leaving the first in original form.
+ *
+ * Reuses unchanged from the OpenCode path:
+ *
+ *   - `Tagger` (DB-backed counter + assignment store).
+ *   - `applyPendingOperations` (operates on `Map<number, TagTarget>`).
+ *   - `applyFlushedStatuses` (same).
+ *   - Tag prefix primitives (`prependTag`, `stripTagPrefix`, `byteSize`).
+ */
+import type { ContextDatabase } from "../features/magic-context/storage";
+import { type Tagger } from "../features/magic-context/tagger";
+import type { TagTarget } from "../hooks/magic-context/tag-messages";
+import { TEXT_TAG_IDENTITY_MARKER } from "./tag-owner-id";
+import type { Transcript } from "./transcript";
+export { TEXT_TAG_IDENTITY_MARKER };
+export interface TagTranscriptOptions {
+    /**
+     * When true, skip injecting `§N§` prefix into visible text. Tags
+     * still get assigned in the DB so historian/drops can reference
+     * them; the agent just doesn't see the markers. Used when the session's
+     * tool surface has no `mmc_reduce` tool to act on the markers. Cache-safe
+     * because the availability verdict is frozen per session.
+     */
+    skipPrefixInjection?: boolean;
+    /**
+     * Pi-only: map of messageId → raw-message fingerprint. When a NEW message
+     * text tag is created, its fingerprint is persisted on the tag row so a
+     * later pass can adopt the fallback-id tag onto the real SessionEntry id
+     * (keeping tag_number/§N§ stable). OpenCode omits this → tags store NULL
+     * → adoption never fires. Keyed by the bare messageId (not the `:pN`
+     * contentId) since all parts of a message share one fingerprint.
+     */
+    entryFingerprintByMessageId?: ReadonlyMap<string, string>;
+    /**
+     * Stable Pi message ids observed on a prior pass. Their immutable parts may
+     * reuse tag assignments while this pass still reapplies visible prefixes and
+     * rebuilds the complete set of messages affected by each tag.
+     */
+    reuseMessageIds?: ReadonlySet<string>;
+    /**
+     * Pi message ids whose persisted text-part vector no longer matches the
+     * current vector. Their parts use content-derived identities instead of
+     * positional `:pN` keys, so sibling insertion/deletion cannot rebind an
+     * older durable tag to different text.
+     */
+    textIdentityDriftMessageIds?: ReadonlySet<string>;
+    /** Source-content cache shared with Pi's batched identity preflight. */
+    textIdentitySourceCache?: Map<number, string>;
+    /** Exact text/count pairs retained by Pi for safe lazy-token backfill reuse. */
+    textTokenCache?: Map<string, {
+        text: string;
+        tokenCount: number;
+    }>;
+    /** Exact tool-result text/count pairs retained under composite tag identity. */
+    toolTokenCache?: Map<string, {
+        text: string;
+        tokenCount: number;
+    }>;
+    /** Optional process-local benchmark callback; production callers omit it. */
+    onTiming?: (phase: "identity" | "prefix" | "targets" | "tokenCounting", elapsedMs: number) => void;
+}
+export interface TagTranscriptResult {
+    targets: Map<number, TagTarget>;
+}
+export declare function tagTranscript(sessionId: string, transcript: Transcript, tagger: Tagger, db: ContextDatabase, options?: TagTranscriptOptions): TagTranscriptResult;
+//# sourceMappingURL=tag-transcript.d.ts.map

package/dist/shared/tag-transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-transcript.d.ts","sourceRoot":"","sources":["../../src/shared/tag-transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAQzE,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAWrF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAErE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAqC,MAAM,cAAc,CAAC;AAGlF,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC,MAAM,WAAW,oBAAoB;IACjC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;OAOG;IACH,2BAA2B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D;;;;OAIG;IACH,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClD,wEAAwE;IACxE,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,gFAAgF;IAChF,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,gFAAgF;IAChF,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CACP,KAAK,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,eAAe,EAC1D,SAAS,EAAE,MAAM,KAChB,IAAI,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACnC;AAkGD,wBAAgB,aAAa,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE,oBAAyB,GACnC,mBAAmB,CAqXrB"}

package/dist/shared/tail-hygiene-status.d.ts

@@ -0,0 +1,24 @@
+import type { Channel1State } from "../hooks/magic-context/ctx-reduce-nudge";
+import type { TailHygieneStatus } from "./rpc-types";
+export interface WireTailHygieneBaseline {
+    u?: number;
+    t?: number;
+    severity?: number;
+    evaluable?: boolean;
+    generation_invalidated?: boolean;
+    baseline_generation?: number;
+    computed_at_ms?: number;
+    reclaimable_tool_output_count?: number;
+}
+/** Normalize either renderer authority's persisted baseline without dropping valid zeros. */
+export declare function resolveTailHygieneStatus(tsBaseline: Channel1State | undefined, rustBaseline?: WireTailHygieneBaseline | null): TailHygieneStatus | undefined;
+/**
+ * The reclaimable share and the two masses it is computed from.
+ *
+ * The tokenizer calibration makes `u` and `t` fractional, but a token count is
+ * a whole number to the reader: `63,063.522 tok` reads as a measurement error,
+ * not as precision. Both masses are rounded here, at the one formatter every
+ * host prints, so the dialog, the sidebar and Pi cannot disagree.
+ */
+export declare function formatTailHygiene(status: TailHygieneStatus): string;
+//# sourceMappingURL=tail-hygiene-status.d.ts.map

package/dist/shared/tail-hygiene-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tail-hygiene-status.d.ts","sourceRoot":"","sources":["../../src/shared/tail-hygiene-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACpC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B,CAAC,EAAE,MAAM,CAAC;CAC1C;AAMD,6FAA6F;AAC7F,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,aAAa,GAAG,SAAS,EACrC,YAAY,CAAC,EAAE,uBAAuB,GAAG,IAAI,GAC9C,iBAAiB,GAAG,SAAS,CAoC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAInE"}

package/dist/shared/test-temp-dir.d.ts

@@ -0,0 +1,46 @@
+export declare const TEST_TEMP_DIR_PREFIXES: readonly ["mc-plugin-test-xdg-pid-", "mc-pi-test-xdg-", "mc-conflict-", "mc-conflict-fixer-", "mc-config-secret-", "pi-reasoning-replay-", "pi-session-api-test-", "pi-symlink-test-", "pi-running-vs-stale-", "pi-dist-metadata-", "pi-traversal-", "pi-source-mode-", "pi-source-missing-", "pi-nonprefixed-", "pi-default-cond-", "pi-array-exports-", "pi-extensionless-", "pi-tsx-source-", "pi-guidance-", "pi-system-v2-", "pi-no-guidance-", "pi-guidance-dedup-", "pi-noreduce-", "pi-language-baseline-", "pi-language-unset-", "pi-language-set-", "pi-a1-guidance-", "pi-prompt-epoch-", "pi-embedding-bootstrap-", "pi-embedding-home-", "magic-context-pi-latch-test-", "magic-context-pi-index-test-", "mc-test-temp-dir-helper-", "mc-v2-surface-", "mc-test-db-backstop-"];
+export type TestTempDirPrefix = string;
+type AfterAll = (callback: () => void) => void;
+type SweepOptions = {
+    tempDir?: string;
+    nowMs?: number;
+    staleAgeMs?: number;
+};
+/**
+ * Creates a test-owned root under the system temp directory. The returned cleanup
+ * only removes roots made by this module, so an accidental path cannot delete an
+ * unrelated temp directory.
+ */
+export declare function createTestTempDir(prefix: TestTempDirPrefix, nameSuffix?: string): {
+    dir: string;
+    cleanup: () => void;
+};
+/**
+ * Registers fixtures with an explicit parent (including ADV_ROOT and nested roots).
+ * A common namespace lets the stale sweep recognize every system-temp fixture,
+ * without maintaining a list of caller-supplied labels.
+ */
+export declare function createTestTempDirFromPath(prefixPath: string): string;
+/** Removes one registered test root; busy roots remain registered for an exit retry. */
+export declare function cleanupTestTempDir(directory: string): void;
+/** Removes every root registered by this process. Safe to call more than once. */
+export declare function cleanupRegisteredTestTempDirs(): void;
+/**
+ * Runs a callback with a fresh root and removes that root even when the callback throws.
+ * This keeps small fixture builders from forgetting a failure-path cleanup.
+ */
+export declare function withTestTempDir<T>(prefix: TestTempDirPrefix, callback: (directory: string) => T): T;
+/**
+ * Installs both Bun's normal suite cleanup and an exit fallback for aborted runs.
+ * The callback is passed in so this utility remains usable from the test preload
+ * without making production code import bun:test.
+ */
+export declare function installTestTempDirCleanup(afterAll: AfterAll): void;
+/**
+ * Removes only old, recognized test roots from one temp directory. The scan does
+ * one directory read, ignores non-directories, and leaves fresh roots and every
+ * unrecognized name alone so concurrently running tools stay isolated.
+ */
+export declare function sweepStaleTestTempDirs({ tempDir, nowMs, staleAgeMs, }?: SweepOptions): string[];
+export {};
+//# sourceMappingURL=test-temp-dir.d.ts.map

package/dist/shared/test-temp-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-temp-dir.d.ts","sourceRoot":"","sources":["../../src/shared/test-temp-dir.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,sBAAsB,6vBAqCzB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAGvC,KAAK,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAC/C,KAAK,YAAY,GAAG;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAkBF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,iBAAiB,EACzB,UAAU,SAAK,GAChB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAOtC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAUpE;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAe1D;AAED,kFAAkF;AAClF,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC7B,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,CAAC,GACnC,CAAC,CAOH;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EACnC,OAAkB,EAClB,KAAkB,EAClB,UAAkC,GACrC,GAAE,YAAiB,GAAG,MAAM,EAAE,CAsB9B"}

package/dist/shared/transcript.d.ts

@@ -0,0 +1,251 @@
+import type { HarnessId } from "./harness";
+/**
+ * Harness-agnostic transcript interface.
+ *
+ * Magic Context's transform pipeline operates on messages in a specific
+ * shape: ordered messages with role-tagged parts (text, tool, reasoning,
+ * tool_result, image), where tagging, sentinel stripping, and queued-drop
+ * application MUTATE part content in-place. OpenCode's plugin transform
+ * receives a `{ info, parts: unknown[] }[]` array and the AI SDK reads
+ * those mutations directly. Pi's `pi.on("context", ...)` event delivers a
+ * `AgentMessage[]` and accepts a fully-replaced array as the result.
+ *
+ * Rather than building a bidirectional `MessageLike[] ↔ AgentMessage[]`
+ * adapter (Oracle's rejected Q1 alternative — too much round-trip
+ * complexity, double-conversion bugs), this module defines a small
+ * adapter contract that:
+ *
+ *   1. Exposes ordered messages with a *uniform* part-level mutation
+ *      surface, regardless of underlying shape.
+ *   2. Is owned by the harness — OpenCode's adapter mutates `parts[]`
+ *      directly (zero copies), Pi's adapter rebuilds an `AgentMessage[]`
+ *      from the mutated transcript only at commit time.
+ *   3. Lets the shared transform code (tagging, stripping, drops)
+ *      operate on `TranscriptPart` interface instances without caring
+ *      whether they're wrapping `Part` from `@opencode-ai/sdk` or
+ *      `TextContent | ToolCall | ThinkingContent` from `@earendil-works/pi-ai`.
+ *
+ * What this interface deliberately does NOT do:
+ *
+ * - **No data round-trip.** The transcript is a *view* over harness data;
+ *   it doesn't define a third canonical message shape. There's no JSON
+ *   serialization, no normalization to a common DTO. Round-trip-free
+ *   adapters are 10x simpler and faster.
+ *
+ * - **No mutation semantics divergence.** Both adapters expose the same
+ *   in-place mutation API (`setText`, `setOutput`, `replaceWithSentinel`).
+ *   Whether mutation flushes to the source array immediately (OpenCode)
+ *   or accumulates until `commit()` (Pi) is the adapter's concern.
+ *
+ * - **No session-storage abstraction.** Compartment storage, ordinals,
+ *   raw-history reads — those live in feature modules, not here. The
+ *   transcript only models the *current turn's* live message buffer.
+ *
+ * Step 4b.1 ships ONLY the interface and OpenCode adapter migration.
+ * Pi adapter implementation lands in 4b.2 alongside the Pi context-event
+ * wire-up, since the two are co-designed (the Pi adapter has to satisfy
+ * the same operations the tagging code calls). 4b.3 wires the Pi
+ * compartment trigger and historian invocation. 4b.4 nudges + auto-search.
+ */
+/** Categorical kind of a transcript part, useful for filter predicates. */
+export type TranscriptPartKind = "text" | "thinking" | "tool_use" | "tool_result" | "image" | "file" | "structural" | "unknown";
+/**
+ * A single content fragment within a transcript message.
+ *
+ * The interface is intentionally narrow: it exposes the operations Magic
+ * Context's transform code performs (read kind, read text, mutate text,
+ * mutate tool output, drop, replace with sentinel) and nothing more. Each
+ * harness adapter implements these against its native part type.
+ *
+ * IMPORTANT: implementations are stateful proxies over the live source
+ * data. Calling `setText("...")` on an OpenCode part mutates the
+ * underlying `Part.text`; calling it on a Pi part flips a dirty flag and
+ * the adapter's `commit()` rebuilds the affected `AgentMessage`. Either
+ * way, the transcript code reads back consistent values via `getText()`.
+ */
+export interface TranscriptPart {
+    /** Discriminator for filter logic. Stable across mutations. */
+    readonly kind: TranscriptPartKind;
+    /** True when the host marks this tool result as carrying a user's answer. */
+    hasUserAnswer?(): boolean;
+    /**
+     * Best-effort identifier for cross-pass tracking. May be:
+     * - OpenCode part ID (e.g. "prt_..."), stable across passes.
+     * - Pi tool-call ID for tool_use/tool_result parts.
+     * - undefined for synthetic/structural parts.
+     *
+     * Pure parts without a stable ID return undefined and are tracked
+     * positionally within their containing message instead.
+     */
+    readonly id: string | undefined;
+    /**
+     * The user-/agent-visible text payload, if this part has one. Returns
+     * undefined for parts that have no text representation (image, file,
+     * structural-only). For thinking parts returns the thinking text. For
+     * tool_use returns the JSON-stringified arguments (so size accounting
+     * reflects what the model sees). For tool_result returns the
+     * concatenated text content of the result.
+     */
+    getText(): string | undefined;
+    /**
+     * Replace the visible text payload. Applies only to text and thinking
+     * parts; throws for kinds where mutation isn't meaningful (the caller
+     * should check `kind` first).
+     *
+     * Returns true if the underlying source data actually changed (so
+     * deduplication helpers can short-circuit). Returns false when the
+     * new text equals the existing text byte-for-byte.
+     */
+    setText(newText: string): boolean;
+    /**
+     * For tool_result parts: replace the text content of the result.
+     * For tool_use parts: replace JSON-serialized arguments.
+     * For everything else: throws — caller should check `kind` first.
+     */
+    setToolOutput(newText: string): boolean;
+    /**
+     * Tool-specific metadata exposed for tagging/drop accounting:
+     * - toolName: tool identifier (e.g. "bash", "mmc_search"). undefined
+     *   for non-tool parts.
+     * - inputByteSize: serialized argument size; used by historian
+     *   pressure projection to estimate post-drop savings.
+     * - inputTokenCount: real-tokenizer count of the same serialized
+     *   argument, stored on the tag so token-budget consumers SUM stored
+     *   counts instead of re-tokenizing. 0 for non-tool parts.
+     *
+     * For non-tool parts both byte fields are undefined/0.
+     */
+    getToolMetadata(): {
+        toolName: string | undefined;
+        inputByteSize: number;
+        inputTokenCount: number;
+    };
+    /**
+     * Non-mutating read of this tool invocation's input object, or null for
+     * non-tool parts / parts without an input. Used by smart-drops supersession
+     * selection (read `mmc_note`'s action, an edit's `filePath`) without
+     * touching the wire. Returns the live object reference; callers must NOT
+     * mutate it.
+     */
+    getToolInput?(): Record<string, unknown> | null;
+    /**
+     * Replace this tool invocation's input object with `input`. Used by the
+     * smart-drops edit_marker path to write back a filePath-preserving,
+     * region-hint-clamped copy of an edit's arguments. Returns true if the part
+     * carried a writable tool input. No-op (false) for non-tool parts.
+     */
+    setToolInput?(input: Record<string, unknown>): boolean;
+    /**
+     * Replace this part with a sentinel placeholder. Sentinels look like
+     * `[dropped §N§]` or `[truncated §N§]` and survive cache-busting
+     * cycles by carrying their original tag number. Used by the
+     * apply-operations flow when a queued drop fires.
+     *
+     * Implementations replace the part *in place* in the parent message's
+     * part array. The replaced part's `kind` shifts to "structural" so
+     * subsequent transform passes don't double-process it.
+     *
+     * Returns true on success; returns false if the part can't be
+     * replaced (e.g. it's already a sentinel, or it's an image part).
+     */
+    replaceWithSentinel(sentinelText: string): boolean;
+    /** Remove one half of a complete tool arc. Callers must remove both halves together. */
+    remove?(): boolean;
+    /** Refuse structural deletion when the adapter cannot match provider-native identity safely. */
+    /** A deferred durable decision vetoes the whole drop, including sentinel fallback. */
+    canRemove?(): boolean | "defer";
+    /**
+     * Optional: serialized byte size of the part's REAL payload, including
+     * non-text content (images, structured data) that `getText()` can't
+     * surface. Used by emergency-drop reclaim accounting so an image-only
+     * tool result is sized by its actual payload, not treated as ~0 bytes.
+     * Adapters that can compute this (e.g. Pi's tool_result proxy, which
+     * closes over the raw content array) should implement it; callers fall
+     * back to the text/JSON estimate when it's absent.
+     */
+    rawByteSize?(): number;
+}
+/**
+ * A single message in the transcript, exposing role + ordered parts.
+ *
+ * Lifetime: a TranscriptMessage is valid only within a single transform
+ * pass. Adapters do not guarantee identity across passes — callers must
+ * use `info.id` for cross-pass correlation, never the message reference.
+ */
+export interface TranscriptMessage {
+    /** Override when the receiving protocol does not merge adjacent assistant reasoning turns. */
+    requiresToolArcSkeleton?: boolean;
+    /**
+     * Lightweight metadata exposed for tagging, sentinel persistence, and
+     * cross-pass correlation. Adapters fill these from harness-native
+     * fields:
+     *
+     * - id: provider-stable message ID (OpenCode `msg_...`, Pi entryId).
+     * - role: "user" | "assistant" | "system" | "tool" | other custom roles.
+     * - sessionId: session identifier, used to scope DB writes.
+     *
+     * IMPORTANT for Pi: Pi's `ToolResultMessage` has role "toolResult"
+     * which the OpenCode-derived transform code expects to NOT be present
+     * (OpenCode folds tool results into the next user message's parts).
+     * The Pi adapter therefore exposes tool-result messages as parts of a
+     * synthetic "user" message in the transcript view, even though the
+     * underlying Pi storage has them as separate top-level entries. This
+     * is the *only* shape normalization the adapter performs.
+     */
+    readonly info: {
+        id?: string;
+        role: string;
+        sessionId?: string;
+    };
+    /** Ordered parts. Same ordering invariants as the underlying source. */
+    readonly parts: TranscriptPart[];
+}
+/**
+ * Adapter contract: everything the transform pipeline calls on a
+ * harness-specific transcript implementation.
+ *
+ * Adapters are owned by the harness adapter layer (OpenCode's
+ * messages-transform.ts, Pi's context-event handler). The shared
+ * transform code receives a Transcript and operates only through this
+ * interface — it never imports from `@opencode-ai/sdk` or
+ * `@earendil-works/pi-ai`.
+ */
+export interface Transcript {
+    /** Ordered messages in the current pass. */
+    readonly messages: TranscriptMessage[];
+    /**
+     * Adapter identification. Useful for:
+     * - Logging (`magic-context[opencode]` vs `magic-context[pi]`).
+     * - Per-harness behaviors gated at adapter level (e.g. opencode-only
+     *   compaction marker injection).
+     * - Test assertions confirming the right adapter ran.
+     */
+    readonly harness: HarnessId;
+    /**
+     * Commit accumulated mutations to the underlying source array.
+     *
+     * For OpenCode: no-op — parts are mutated directly in `Part.text`/
+     * `Part.state.output` and OpenCode reads them back from the same
+     * array, so changes are already visible.
+     *
+     * For Pi: rebuilds a new `AgentMessage[]` from the dirty messages
+     * and stores it on the adapter so `pi.on("context", ...)` can return
+     * `{ messages }` to Pi. Idempotent: calling twice is safe.
+     *
+     * Always called exactly once per pass, after the transform pipeline
+     * finishes. Adapters that don't need it implement it as a no-op.
+     */
+    commit(): void;
+}
+/**
+ * Sentinel marker for transcript parts that should be ignored by all
+ * downstream transform stages (tagging, drops, indexing). Adapters set
+ * this on parts that exist only as structural artifacts (e.g. OpenCode's
+ * `step-start`/`step-finish`).
+ *
+ * Exported so harness adapters can stamp it on synthetic parts they
+ * create internally and so test fixtures can construct synthetic
+ * transcripts without needing real OpenCode/Pi structures.
+ */
+export declare const STRUCTURAL_SENTINEL_KIND: TranscriptPartKind;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/shared/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/shared/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GACxB,MAAM,GACN,UAAU,GACV,UAAU,GACV,aAAa,GACb,OAAO,GACP,MAAM,GACN,YAAY,GACZ,SAAS,CAAC;AAEhB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAElC,6EAA6E;IAC7E,aAAa,CAAC,IAAI,OAAO,CAAC;IAE1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC;;;;;;;OAOG;IACH,OAAO,IAAI,MAAM,GAAG,SAAS,CAAC;IAE9B;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAExC;;;;;;;;;;;OAWG;IACH,eAAe,IAAI;QACf,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KAC3B,CAAC;IAEF;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEhD;;;;;OAKG;IACH,YAAY,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IAEvD;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IAEnD,wFAAwF;IACxF,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,gGAAgG;IAChG,sFAAsF;IACtF,SAAS,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC;IAEhC;;;;;;;;OAQG;IACH,WAAW,CAAC,IAAI,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,8FAA8F;IAC9F,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,IAAI,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEjE,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAEvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAE5B;;;;;;;;;;;;;OAaG;IACH,MAAM,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,EAAE,kBAAiC,CAAC"}

package/dist/shared/user-answer.d.ts

@@ -0,0 +1,4 @@
+/** Host-owned answer metadata, independent of the tool's registered name. */
+export declare function hasUserAnswerMetadata(value: unknown): boolean;
+export declare function toolPartHasUserAnswer(part: unknown): boolean;
+//# sourceMappingURL=user-answer.d.ts.map

package/dist/shared/user-answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-answer.d.ts","sourceRoot":"","sources":["../../src/shared/user-answer.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO7D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAI5D"}

package/dist/shared/user-facing-codes.d.ts

@@ -0,0 +1,135 @@
+export declare const USER_FACING_FAILURES: {
+    readonly historian_unavailable: {
+        readonly code: "MC-H01";
+        readonly sentence: "History compression could not finish this turn.";
+        readonly action: "It will retry automatically.";
+    };
+    readonly hidden_cleanup_unbound: {
+        readonly code: "MC-H02";
+        readonly sentence: "Some finished background sessions could not be removed from this host.";
+        readonly action: "They are removed automatically the next time Magic Context runs inside a registered OpenCode service.";
+    };
+    readonly historian_saved_history_misaligned: {
+        readonly code: "MC-H03";
+        readonly sentence: "History compression is paused because this session's saved summaries no longer line up with its messages.";
+        readonly action: "Run /mmc-recomp to rebuild them.";
+    };
+    readonly history_boundary_unresolved: {
+        readonly code: "MC-H04";
+        readonly sentence: "This request was not sent: the message that marks where this session's history summary ends is missing from the OpenCode store, and without it the request is larger than the model's context window.";
+        readonly action: "Run /mmc-recomp to rebuild the history summary.";
+    };
+    readonly history_over_window_unmanaged: {
+        readonly code: "MC-H06";
+        readonly sentence: "This request was not sent: this session's history is larger than the model's context window, and Magic Context does not have a summary of it yet to send in its place.";
+        readonly action: "Send your message again once history compression has caught up, or switch to a model with a larger context window.";
+    };
+    readonly frozen_history_over_window: {
+        readonly code: "MC-H07";
+        readonly sentence: "This request was not sent: the conversation is larger than the context window the provider reported, and the compressed history Magic Context has ready does not fit either.";
+        readonly action: "Run /mmc-flush to compress it now, then send your message again.";
+    };
+    readonly historian_window_too_small: {
+        readonly code: "MC-H05";
+        readonly sentence: "History compression is paused because the history model's context window is too small for its instructions.";
+        readonly action: "Set historian.model in magic-context.jsonc to a model with a larger context window.";
+    };
+    readonly recomp_unavailable: {
+        readonly code: "MC-R01";
+        readonly sentence: "History compression could not be rebuilt.";
+        readonly action: "Run /mmc-recomp again.";
+    };
+    readonly status_unavailable: {
+        readonly code: "MC-S01";
+        readonly sentence: "Magic Context status is temporarily unavailable.";
+        readonly action: "Retry /mmc-status in a moment.";
+    };
+    readonly transform_update_failed: {
+        readonly code: "MC-S02";
+        readonly sentence: "The last context update did not finish.";
+        readonly action: "Send another message to retry.";
+    };
+    readonly transform_pass_degraded: {
+        readonly code: "MC-S06";
+        readonly sentence: "This request was not sent: Magic Context could not finish preparing it, and without that preparation it could be far larger than the previous request.";
+        readonly action: "Send your message again.";
+    };
+    readonly configuration_warning: {
+        readonly code: "MC-S03";
+        readonly sentence: "Some configuration settings could not be applied.";
+        readonly action: "Fix the configuration warning shown in /mmc-status, then restart.";
+    };
+    readonly status_log_unavailable: {
+        readonly code: "MC-S04";
+        readonly sentence: "Some diagnostic details could not be saved.";
+        readonly action: "Retry /mmc-status in a moment.";
+    };
+    readonly memory_writes_paused: {
+        readonly code: "MC-C01";
+        readonly sentence: "Memory writes are paused while the engine syncs.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly memory_access_unavailable: {
+        readonly code: "MC-C02";
+        readonly sentence: "Memory access is temporarily unavailable.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly note_changes_paused: {
+        readonly code: "MC-C03";
+        readonly sentence: "Note changes are paused while the engine syncs.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly note_access_unavailable: {
+        readonly code: "MC-C04";
+        readonly sentence: "Notes are temporarily unavailable.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly context_cleanup_paused: {
+        readonly code: "MC-C05";
+        readonly sentence: "Context cleanup is paused while the engine syncs.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly partial_history_unavailable: {
+        readonly code: "MC-C06";
+        readonly sentence: "Partial history compression is not available in the current mode.";
+        readonly action: "Run /mmc-recomp without a range.";
+    };
+    readonly history_compression_paused: {
+        readonly code: "MC-C09";
+        readonly sentence: "History compression is paused while the engine syncs.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly history_compression_needs_message: {
+        readonly code: "MC-C12";
+        readonly sentence: "History compression has not seen this session since Magic Context reconnected.";
+        readonly action: "Send a message in this session first, then run /mmc-wrapup again.";
+    };
+    readonly context_service_unavailable: {
+        readonly code: "MC-C10";
+        readonly sentence: "Magic Context is temporarily unavailable.";
+        readonly action: "Retry in a moment.";
+    };
+    readonly compaction_marker_missing: {
+        readonly code: "MC-C11";
+        readonly sentence: "The history boundary marker is missing from the OpenCode store, so requests carry the full session.";
+        readonly action: "It is retried on every message; if this persists, run `/mmc-flush`.";
+    };
+    readonly memory_mirror_stalled: {
+        readonly code: "MC-M01";
+        readonly sentence: "Memory synchronization stopped before the host mirror caught up.";
+        readonly action: "Send another message to resume it, or run `ck doctor drain-authority`.";
+    };
+    readonly memory_authority_mismatch: {
+        readonly code: "MC-M02";
+        readonly sentence: "Memory authority is inconsistent between the host and module.";
+        readonly action: "Run `ck doctor drain-authority` before changing Rust mode.";
+    };
+};
+export type UserFacingFailureKey = keyof typeof USER_FACING_FAILURES;
+export type UserFacingTextStyle = "markdown" | "plain";
+export declare function renderUserFacingFailure(key: UserFacingFailureKey, style?: UserFacingTextStyle): string;
+export declare function userFacingFailureCode(key: UserFacingFailureKey): string;
+export type CapabilityRefusal = "memory_write" | "memory_access" | "note_change" | "note_access" | "context_cleanup" | "partial_history" | "history_compression" | "context_service";
+export declare function renderCapabilityRefusal(capability: CapabilityRefusal): string;
+export declare function capabilityRefusalCode(capability: CapabilityRefusal): string;
+//# sourceMappingURL=user-facing-codes.d.ts.map

package/dist/shared/user-facing-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-facing-codes.d.ts","sourceRoot":"","sources":["../../src/shared/user-facing-codes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqIvB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,OAAO,CAAC;AAEvD,wBAAgB,uBAAuB,CACnC,GAAG,EAAE,oBAAoB,EACzB,KAAK,GAAE,mBAAgC,GACxC,MAAM,CAIR;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAEvE;AAED,MAAM,MAAM,iBAAiB,GACvB,cAAc,GACd,eAAe,GACf,aAAa,GACb,aAAa,GACb,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,GACrB,iBAAiB,CAAC;AAaxB,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAE7E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAE3E"}