prime-agent-dsh 0.2.0

package/src/context-converter.ts

@@ -0,0 +1,176 @@
+import { freezeMessage, type ContentBlock, type Message } from "@deepseek-ai/dsh-llm";
+import { MessageId, ToolCallId } from "@deepseek-ai/dsh-llm";
+import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
+
+/** Prime's model-context message shape. Kept structural so this bridge does not depend on Prime internals. */
+export type PrimeMessage = Record<string, unknown> & { role: string };
+export type PrimeEnvelope = { id?: string; parentId?: string | null; timestamp?: string; message: PrimeMessage };
+export type ConversionCapability = "prime-image-admission" | "dsh-image-resolution";
+export class ConversionCapabilityError extends Error {
+  readonly code = "CAPABILITY_UNAVAILABLE";
+  constructor(readonly capability: ConversionCapability, message: string, readonly data?: unknown) { super(message); }
+}
+export interface ConverterCapabilities {
+  /** Admit inline Prime bytes into DSH's durable attachment store. */
+  admitImage?: (image: { data: string; mimeType: string; name?: string }) => ImageAttachmentRef;
+  /** Resolve a DSH durable reference back to inline Prime bytes. */
+  resolveImage?: (attachment: ImageAttachmentRef) => { data: string; mimeType: string };
+}
+export interface AsyncConverterCapabilities {
+  /** Admit inline Prime bytes before constructing the immutable DSH message. */
+  admitImages?: (images: readonly { data: string; mimeType: string; name?: string }[]) => Promise<readonly ImageAttachmentRef[]>;
+  /** Resolve and verify DSH bytes before constructing a Prime message. */
+  resolveImage?: (attachment: ImageAttachmentRef) => Promise<{ data: string; mimeType: string }>;
+}
+
+type PrimeMeta = { role: string; envelope?: Omit<PrimeEnvelope, "message">; fields: Record<string, unknown> };
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const string = (v: unknown, what: string): string => { if (typeof v !== "string") throw new TypeError(`${what} must be a string`); return v; };
+
+/** Detach metadata into the lossless-JSON subset required by DSH session events. */
+function jsonBoundary(value: unknown, ancestors = new Set<object>()): unknown {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? (Object.is(value, -0) ? 0 : value) : null;
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value !== "object" || ancestors.has(value)) return undefined;
+  if (Array.isArray(value)) {
+    ancestors.add(value);
+    const result = Array.from({ length: value.length }, (_, index) => jsonBoundary(value[index], ancestors) ?? null);
+    ancestors.delete(value);
+    return result;
+  }
+  const prototype = Reflect.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return undefined;
+  ancestors.add(value);
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(value)) {
+    let item: unknown;
+    try { item = jsonBoundary((value as Record<string, unknown>)[key], ancestors); } catch { continue; }
+    if (item !== undefined) result[key] = item;
+  }
+  ancestors.delete(value);
+  return result;
+}
+function jsonRecord(value: Record<string, unknown>): Record<string, unknown> {
+  return jsonBoundary(value) as Record<string, unknown>;
+}
+function parts(content: unknown): Record<string, unknown>[] {
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  if (!Array.isArray(content)) throw new TypeError("message content must be a string or array");
+  return content.map((p, i) => { if (!object(p) || typeof p.type !== "string") throw new TypeError(`invalid content block at index ${i}`); return p; });
+}
+function toDshBlocks(content: unknown, caps: ConverterCapabilities, assistant: boolean): ContentBlock[] {
+  return parts(content).map((p): ContentBlock => {
+    switch (p.type) {
+      case "text": return { type: "text", text: string(p.text, "text") };
+      case "thinking": if (!assistant) throw new TypeError("thinking is only valid in assistant content"); return { type: "reasoning", text: string(p.thinking, "thinking") };
+      case "toolCall": {
+        if (!assistant) throw new TypeError("toolCall is only valid in assistant content");
+        const args = p.arguments;
+        return { type: "tool-call", id: ToolCallId(string(p.id, "toolCall.id")), name: string(p.name, "toolCall.name"), arguments: typeof args === "string" ? args : JSON.stringify(jsonBoundary(args ?? {}) ?? {}) };
+      }
+      case "image": {
+        if (!caps.admitImage) throw new ConversionCapabilityError("prime-image-admission", "inline Prime images require an attachment admission capability", { mimeType: p.mimeType });
+        return { type: "image", attachment: caps.admitImage({ data: string(p.data, "image.data"), mimeType: string(p.mimeType, "image.mimeType"), ...(typeof p.name === "string" ? { name: p.name } : {}) }) };
+      }
+      default: throw new ConversionCapabilityError("prime-image-admission", `unsupported Prime content block: ${String(p.type)}`, { block: p });
+    }
+  });
+}
+function split(input: PrimeMessage | PrimeEnvelope): { message: PrimeMessage; envelope?: Omit<PrimeEnvelope, "message"> } {
+  if (object(input) && object(input.message)) { const { message, ...envelope } = input; return { message: message as PrimeMessage, envelope: envelope as Omit<PrimeEnvelope, "message"> }; }
+  return { message: input as PrimeMessage };
+}
+/** Lossless Prime -> DSH projection. Prime-only fields ride source.prime for the reverse projection. */
+export function primeToDsh(input: PrimeMessage | PrimeEnvelope, caps: ConverterCapabilities = {}, idOverride?: string): Message {
+  const { message: p, envelope } = split(input); const role = string(p.role, "role");
+  const rawFields: Record<string, unknown> = {}; for (const [k, v] of Object.entries(p)) if (k !== "role" && k !== "content") rawFields[k] = v;
+  const fields = jsonRecord(rawFields);
+  const safeEnvelope = envelope ? jsonRecord(envelope) as Omit<PrimeEnvelope, "message"> : undefined;
+  const meta: PrimeMeta = { role, ...(safeEnvelope ? { envelope: safeEnvelope } : {}), fields };
+  let content: ContentBlock[]; let dshRole: "user" | "assistant"; let source: Message["source"] & { prime: PrimeMeta };
+  if (role === "user") { content = toDshBlocks(p.content, caps, false); dshRole = "user"; source = { kind: "user", prime: meta }; }
+  else if (role === "assistant") { const replayState = jsonBoundary(p.replayState); content = toDshBlocks(p.content, caps, true); dshRole = "assistant"; source = { kind: "model", provider: typeof p.provider === "string" ? p.provider : "external", model: typeof p.model === "string" ? p.model : "unknown", ...(replayState === undefined ? {} : { replayState }), prime: meta }; }
+  else if (role === "toolResult") {
+    const callId = ToolCallId(string(p.toolCallId, "toolCallId"));
+    content = [{ type: "tool-result", toolCallId: callId, content: toDshBlocks(p.content, caps, false), isError: p.isError === true }]; dshRole = "user"; source = { kind: "tool", callId, prime: meta };
+  } else if (["bashExecution", "custom", "branchSummary", "compactionSummary"].includes(role)) {
+    const text = role === "bashExecution" ? `${typeof p.command === "string" ? p.command : ""}
+${typeof p.output === "string" ? p.output : ""}` : typeof p.summary === "string" ? p.summary : "";
+    content = role === "custom" ? toDshBlocks(p.content, caps, false) : [{ type: "text", text }]; dshRole = "user"; source = role.includes("Summary")
+      ? { kind: "plugin", plugin: `prime:${role}`, form: "recall", prime: meta }
+      : { kind: "plugin", plugin: `prime:${role}`, form: "notice", summary: role, prime: meta };
+  } else throw new TypeError(`unsupported Prime role: ${role}`);
+  const id = idOverride ?? (typeof envelope?.id === "string" ? envelope.id : typeof p.id === "string" ? p.id : crypto.randomUUID());
+  return freezeMessage({ id: MessageId(id), role: dshRole, content, source });
+}
+function fromDshBlocks(content: readonly ContentBlock[], caps: ConverterCapabilities): Record<string, unknown>[] {
+  return content.flatMap((b): Record<string, unknown>[] => {
+    switch (b.type) {
+      case "text": return [{ type: "text", text: b.text }];
+      case "reasoning": return [{ type: "thinking", thinking: b.text }];
+      case "tool-call": { let args: unknown; try { args = JSON.parse(b.arguments); } catch { args = b.arguments; } return [{ type: "toolCall", id: b.id, name: b.name, arguments: args }]; }
+      case "image": { if (!caps.resolveImage) throw new ConversionCapabilityError("dsh-image-resolution", "DSH image references require an attachment resolution capability", { attachment: b.attachment }); const x = caps.resolveImage(b.attachment); return [{ type: "image", data: x.data, mimeType: x.mimeType, ...(b.attachment.name ? { name: b.attachment.name } : {}) }]; }
+      case "tool-result": return fromDshBlocks(b.content, caps);
+      default: throw new TypeError(`unsupported DSH content block: ${String((b as unknown as { type?: unknown }).type)}`);
+    }
+  });
+}
+/** Lossless DSH -> Prime projection for messages produced by this bridge; canonical mapping otherwise. */
+export function dshToPrime(message: Message, caps: ConverterCapabilities = {}): PrimeMessage | PrimeEnvelope {
+  const sourceWithPrime = message.source as Message["source"] & { prime?: unknown };
+  const meta = object(sourceWithPrime.prime) ? sourceWithPrime.prime as PrimeMeta : undefined;
+  if (meta) {
+    const restored: PrimeMessage = { role: meta.role, ...meta.fields };
+    if (["user", "assistant", "toolResult", "custom"].includes(meta.role)) restored.content = fromDshBlocks(message.content[0]?.type === "tool-result" ? message.content[0].content : message.content, caps);
+    if (meta.role === "toolResult") { const block = message.content[0] as Extract<ContentBlock, { type: "tool-result" }>; restored.toolCallId = block.toolCallId; restored.isError = block.isError === true; }
+    return meta.envelope ? { ...meta.envelope, message: restored } : restored;
+  }
+  if (message.role === "assistant") return { role: "assistant", content: fromDshBlocks(message.content, caps), provider: message.source.kind === "model" ? message.source.provider : "external", model: message.source.kind === "model" ? message.source.model : "unknown" };
+  if (message.source.kind === "tool") { const b = message.content[0]; if (b?.type !== "tool-result") throw new TypeError("tool-source message lacks tool-result block"); return { role: "toolResult", toolCallId: b.toolCallId, toolName: "unknown", content: fromDshBlocks(b.content, caps), isError: b.isError === true }; }
+  return { role: "user", content: fromDshBlocks(message.content, caps) };
+}
+
+
+/** Async Prime -> DSH projection for attachment stores with durable I/O. */
+export async function primeToDshAsync(input: PrimeMessage | PrimeEnvelope, caps: AsyncConverterCapabilities = {}, idOverride?: string): Promise<Message> {
+  const { message, envelope } = split(input);
+  const images = parts(message.content).filter((part) => part.type === "image");
+  if (images.length > 0 && !caps.admitImages) throw new ConversionCapabilityError("prime-image-admission", "inline Prime images require an attachment admission capability");
+  const uploads = images.map((part) => ({
+    data: string(part.data, "image.data"),
+    mimeType: string(part.mimeType, "image.mimeType"),
+    ...(typeof part.name === "string" ? { name: part.name } : {}),
+  }));
+  const admitted = caps.admitImages ? await caps.admitImages(uploads) : [];
+  let next = 0;
+  const syncCaps: ConverterCapabilities = { admitImage: () => {
+    const attachment = admitted[next++];
+    if (!attachment) throw new Error("admitted image reference is missing");
+    return attachment;
+  } };
+  return primeToDsh(envelope ? { ...envelope, message } : message, syncCaps, idOverride);
+}
+
+async function resolveDshBlocks(content: readonly ContentBlock[], caps: AsyncConverterCapabilities): Promise<ConverterCapabilities> {
+  const resolved = new Map<ImageAttachmentRef, { data: string; mimeType: string }>();
+  const visit = async (blocks: readonly ContentBlock[]): Promise<void> => {
+    for (const block of blocks) {
+      if (block.type === "image") {
+        if (!caps.resolveImage) throw new ConversionCapabilityError("dsh-image-resolution", "DSH image references require an attachment resolution capability", { attachment: block.attachment });
+        resolved.set(block.attachment, await caps.resolveImage(block.attachment));
+      } else if (block.type === "tool-result") await visit(block.content);
+    }
+  };
+  await visit(content);
+  return { resolveImage: (attachment) => {
+    const image = resolved.get(attachment);
+    if (!image) throw new Error("resolved image bytes are missing");
+    return image;
+  } };
+}
+
+/** Async DSH -> Prime projection that verifies and resolves durable image references. */
+export async function dshToPrimeAsync(message: Message, caps: AsyncConverterCapabilities = {}): Promise<PrimeMessage | PrimeEnvelope> {
+  return dshToPrime(message, await resolveDshBlocks(message.content, caps));
+}

package/src/context-objects.ts

@@ -0,0 +1,247 @@
+import { closeSync, chmodSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { dirname, join, sep } from "node:path";
+import { buildContextEntries, sessionEntryToContextMessages, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { primeToDshAsync, type PrimeEnvelope, type PrimeMessage } from "./context-converter.js";
+import { DurableContextStore, type PublicationDiagnostics, type PublishResult } from "./durable-context-store.js";
+import { stableJson } from "./prefix-metrics.js";
+import { LocalDshImageAttachments, type DshImageAttachmentGateway } from "./dsh-image-attachments.js";
+
+export const CONTEXT_OBJECT_VERSION = "prime-agent-dsh/context-object-v1" as const;
+
+type JsonObject = Record<string, unknown>;
+
+export interface ContextObjectMetrics {
+  readonly assistantMessages: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheReadTokens: number;
+  readonly cacheWriteTokens: number;
+  readonly totalTokens: number;
+}
+
+export interface ContextObjectManifest {
+  readonly version: typeof CONTEXT_OBJECT_VERSION;
+  readonly sessionId: string;
+  readonly branchId: string;
+  readonly revision: number;
+  readonly observedAt: number;
+  readonly messageCount: number;
+  readonly entryCount: number;
+  readonly cropped: boolean;
+  readonly syncMode: "append" | "noop" | "rebuild";
+  readonly commonPrefixMessages: number;
+  readonly metrics: ContextObjectMetrics;
+  /** Digest of the immutable derived object. */
+  readonly digest: string;
+  /** Path to the current immutable v3 reference object. */
+  readonly snapshot: string;
+  readonly commit?: string;
+  readonly sourceDigest?: string;
+  readonly effectiveDigest?: string;
+  readonly publication?: PublicationDiagnostics;
+}
+
+export interface ContextObjectSyncResult {
+  readonly manifest: ContextObjectManifest;
+  readonly root: string;
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function tokenCount(value: unknown): number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function metricsFromBranch(branch: readonly unknown[]): ContextObjectMetrics {
+  const totals = { assistantMessages: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0 };
+  for (const raw of branch) {
+    if (!isObject(raw) || raw.type !== "message" || !isObject(raw.message) || raw.message.role !== "assistant") continue;
+    const usage = isObject(raw.message.usage) ? raw.message.usage : undefined;
+    if (!usage) continue;
+    totals.assistantMessages++;
+    totals.inputTokens += tokenCount(usage.input);
+    totals.outputTokens += tokenCount(usage.output);
+    totals.cacheReadTokens += tokenCount(usage.cacheRead);
+    totals.cacheWriteTokens += tokenCount(usage.cacheWrite);
+    totals.totalTokens += tokenCount(usage.totalTokens);
+  }
+  return totals;
+}
+
+function asPrimeInput(value: unknown): PrimeMessage | PrimeEnvelope {
+  if (!isObject(value)) throw new TypeError("Prime context message must be an object");
+  if (isObject(value.message) && typeof value.message.role === "string") return value as PrimeEnvelope;
+  if (typeof value.role === "string") return value as PrimeMessage;
+  throw new TypeError("Prime context message has no role");
+}
+
+function lstatExists(path: string): boolean {
+  try { lstatSync(path); return true; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+}
+
+function ensurePrivateDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Context object root is not a private directory: ${path}`);
+  chmodSync(path, 0o700);
+}
+
+function atomicPrivateWrite(path: string, content: string): void {
+  const temp = `${path}.${randomBytes(12).toString("hex")}.tmp`;
+  const fd = openSync(temp, "wx", 0o600);
+  try {
+    writeFileSync(fd, content, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(temp, path);
+  chmodSync(path, 0o600);
+  let directory: number | undefined;
+  try { directory = openSync(dirname(path), constants.O_RDONLY); fsyncSync(directory); }
+  finally { if (directory !== undefined) closeSync(directory); }
+}
+
+function effectiveSourceIndexes(rawBranch: readonly unknown[], messages: readonly unknown[]): Array<number | null> {
+  const candidates: Array<{ sourceIndex: number; fingerprint: string }> = [];
+  rawBranch.forEach((entry, sourceIndex) => {
+    try {
+      for (const message of sessionEntryToContextMessages(entry as SessionEntry)) {
+        candidates.push({ sourceIndex, fingerprint: stableJson(message) });
+      }
+    } catch { /* unsupported/log-only entries do not enter model context */ }
+  });
+  let cursor = 0;
+  return messages.map((message) => {
+    const fingerprint = stableJson(message);
+    let found = candidates.findIndex((candidate, index) => index >= cursor && candidate.fingerprint === fingerprint);
+    if (found < 0) found = candidates.findIndex((candidate) => candidate.fingerprint === fingerprint);
+    if (found < 0) return null;
+    cursor = found + 1;
+    return candidates[found]?.sourceIndex ?? null;
+  });
+}
+
+/** Resolve the artifact directory shared with Prime's per-session Python kernel. */
+export function contextObjectRoot(sessionId: string, sessionFile: string | undefined): string | undefined {
+  if (!sessionFile || !/^[A-Za-z0-9._-]{1,128}$/.test(sessionId)) return undefined;
+  const sessionDir = dirname(sessionFile);
+  // RLM child JSONL files already live inside their inherited artifact tree and
+  // PRIME_AGENT sets RLM_SESSION_DIR to that directory. Root sessions—including
+  // custom --session-dir roots—use the sibling session-artifacts/<id> layout.
+  if (sessionDir.split(sep).includes("session-artifacts")) return join(sessionDir, "dsh-context");
+  return join(dirname(sessionDir), "session-artifacts", sessionId, "dsh-context");
+}
+
+/**
+ * Maintains a rebuildable DSH projection and immutable filesystem snapshots.
+ * Prime JSONL remains canonical; this store never edits Prime or DSH history.
+ */
+export class ContextObjectStore {
+  constructor(private readonly attachments: DshImageAttachmentGateway = new LocalDshImageAttachments()) {}
+
+  /** Recover the newest valid committed generation without trusting CURRENT or manifest.json. */
+  recover(ctx: ExtensionContext): PublishResult | undefined {
+    const binding = this.binding(ctx);
+    if (!binding) return undefined;
+    const recovered = new DurableContextStore(binding).recover();
+    if (!recovered) return undefined;
+    const publication = recovered.commit.publication ?? {
+      source: { mode: "noop" as const, reused: recovered.object.sourceEntryDigests.length, new: 0, reindexed: 0 },
+      effective: { reused: recovered.object.effectiveEntryDigests.length, new: 0, reindexed: 0, rebuildReason: "none" as const },
+    };
+    return { ...recovered, mode: "noop", publication };
+  }
+
+  async sync(ctx: ExtensionContext, inputMessages?: readonly unknown[]): Promise<ContextObjectSyncResult | undefined> {
+    const binding = this.binding(ctx);
+    if (!binding) return undefined;
+    const { sessionId } = binding.binding;
+    const { root } = binding;
+    const branchId = ctx.sessionManager.getLeafId?.() ?? "root";
+    const rawBranch = (ctx.sessionManager.getBranch?.() ?? []) as readonly unknown[];
+    // ReadonlySessionManager has no buildSessionContext() at runtime. Rebuild the
+    // confirmed public context from its durable branch after persistence.
+    const messages = inputMessages ?? buildContextEntries(rawBranch as SessionEntry[], branchId)
+      .flatMap((entry) => sessionEntryToContextMessages(entry));
+    const sourceIndexes = effectiveSourceIndexes(rawBranch, messages);
+    const selected = messages.flatMap((message, index) => {
+      const sourceIndex = sourceIndexes[index];
+      return sourceIndex === null || sourceIndex === undefined ? [] : [{ message, originalIndex: index, sourceIndex }];
+    });
+    // A context event can include the current user message before Prime commits
+    // it. Reference-only DSH indexes only confirmed Prime entries and catches up
+    // on the next lifecycle observation instead of copying pending content.
+    const canonical = await Promise.all(selected.map(({ message, originalIndex }) => primeToDshAsync(
+      asPrimeInput(message),
+      { admitImages: (images) => this.attachments.admitPrimeImages(images) },
+      `prime-${createHash("sha256").update(`${originalIndex}:`).update(stableJson(message)).digest("hex").slice(0, 32)}`,
+    )));
+    const metrics = metricsFromBranch(rawBranch);
+    const store = new DurableContextStore(binding);
+    const published = await store.publish({
+      source: rawBranch,
+      effective: canonical,
+      effectiveSourceIndexes: selected.map(({ sourceIndex }) => sourceIndex),
+      converterVersion: "prime-to-dsh-v2-reference",
+      schemaVersion: CONTEXT_OBJECT_VERSION,
+      branchId,
+      observedAt: Date.now(),
+      compatibilityMetrics: { ...metrics },
+      cropped: selected.length !== messages.length,
+    });
+    const view = published.object.compatibility;
+    const manifest: ContextObjectManifest = {
+      version: CONTEXT_OBJECT_VERSION,
+      sessionId,
+      branchId: view.branchId,
+      revision: published.commit.generation,
+      observedAt: published.commit.observedAt,
+      messageCount: view.messageCount,
+      entryCount: published.object.sourceEntryDigests.length,
+      cropped: view.cropped,
+      syncMode: published.mode,
+      commonPrefixMessages: published.commit.commonPrefix,
+      metrics,
+      digest: published.commit.object,
+      snapshot: `objects/${published.commit.object}.json`,
+      commit: published.commitDigest,
+      sourceDigest: published.commit.sourceDigest,
+      effectiveDigest: published.commit.effectiveDigest,
+      publication: published.publication,
+    };
+    ensurePrivateDirectory(root);
+    const branchKey = createHash("sha256").update(branchId).digest("hex");
+    const immutableManifest = join(root, `manifest-${branchKey}-${published.commitDigest}.json`);
+    if (!lstatExists(immutableManifest)) atomicPrivateWrite(immutableManifest, `${JSON.stringify(manifest)}\n`);
+    atomicPrivateWrite(join(root, `manifest-${branchKey}.json`), `${JSON.stringify(manifest)}\n`);
+    // Current-view pointer only. Authoritative readers pass an immutable digest or expected branch.
+    atomicPrivateWrite(join(root, "manifest.json"), `${JSON.stringify(manifest)}\n`);
+    this.pruneCompatibilityManifests(root, branchKey);
+    return { manifest, root };
+  }
+
+
+  private pruneCompatibilityManifests(root: string, currentBranchKey: string): void {
+    const retained = new Set(readdirSync(join(root, "heads"))
+      .flatMap((name) => /^\d{16}-([a-f0-9]{64})$/.exec(name)?.[1] ?? []));
+    for (const name of readdirSync(root)) {
+      const immutable = /^manifest-[a-f0-9]{64}-([a-f0-9]{64})\.json$/.exec(name);
+      const branch = /^manifest-([a-f0-9]{64})\.json$/.exec(name);
+      if ((immutable && !retained.has(immutable[1] ?? "")) || (branch && branch[1] !== currentBranchKey)) {
+        try { unlinkSync(join(root, name)); } catch { /* best effort; compatibility views are rebuildable */ }
+      }
+    }
+  }
+
+  private binding(ctx: ExtensionContext): ConstructorParameters<typeof DurableContextStore>[0] | undefined {
+    const sessionId = ctx.sessionManager.getSessionId?.() ?? "";
+    const primeSessionFile = ctx.sessionManager.getSessionFile?.();
+    const root = contextObjectRoot(sessionId, primeSessionFile);
+    if (!sessionId || !primeSessionFile || !root) return undefined;
+    return { root, binding: { sessionId, primeSessionFile } };
+  }
+}

package/src/context-protocol.ts

@@ -0,0 +1,37 @@
+import type { Message } from "@deepseek-ai/dsh-llm";
+
+export const PROTOCOL = "dsh-context/1" as const;
+export type RequestId = string | number;
+export interface BranchKey { sessionId: string; branchId: string }
+export type SimpleMessage =
+  | { role: "user"; content: string; source?: string }
+  | { role: "assistant"; content: string; provider?: string; model?: string };
+export interface SyncParams { key: BranchKey; messages: SimpleMessage[]; expectedRevision?: number }
+export interface CanonicalSyncParams { key: BranchKey; messages: Message[]; expectedRevision?: number }
+export interface ProjectParams { key: BranchKey; from?: number; limit?: number }
+export type Method = "initialize" | "session/sync" | "session/sync-canonical" | "project" | "status" | "shutdown";
+export interface Request<M extends string = string, P = unknown> { version: typeof PROTOCOL; id: RequestId; method: M; params?: P }
+export interface InitializeResult { protocol: typeof PROTOCOL; implementation: { name: string; version: string }; capabilities: { transport: readonly ["in-process"]; methods: readonly Method[]; dshSession: true; agentLoop: false } }
+export interface SyncResult { key: BranchKey; revision: number; eventCount: number; messageCount: number; mode: "append" | "noop" | "rebuild"; commonPrefixMessages: number }
+export interface ProjectResult { key: BranchKey; revision: number; total: number; from: number; messages: Message[] }
+export interface SessionSummary { key: BranchKey; revision: number; eventCount: number; messageCount: number }
+export interface StatusResult { initialized: boolean; shuttingDown: boolean; sessionCount: number; sessions: SessionSummary[] }
+export interface ShutdownResult { accepted: true }
+export interface ResultMap { initialize: InitializeResult; "session/sync": SyncResult; "session/sync-canonical": SyncResult; project: ProjectResult; status: StatusResult; shutdown: ShutdownResult }
+export type MethodResult = ResultMap[keyof ResultMap];
+export interface Success<R extends MethodResult = MethodResult> { version: typeof PROTOCOL; id: RequestId; ok: true; result: R }
+export type ProtocolErrorCode = "INVALID_REQUEST" | "UNSUPPORTED_VERSION" | "SHUTTING_DOWN" | "ALREADY_INITIALIZED" | "NOT_INITIALIZED" | "METHOD_NOT_FOUND" | "INVALID_PARAMS" | "REVISION_CONFLICT" | "SESSION_NOT_FOUND" | "INTERNAL";
+export interface Failure { version: typeof PROTOCOL; id: RequestId | null; ok: false; error: { code: ProtocolErrorCode; message: string; data?: unknown } }
+export type Response<R extends MethodResult = MethodResult> = Success<R> | Failure;
+
+/** Typed in-process client; method/result relationships cannot be lost at call sites. */
+export class ContextProtocolClient {
+  private nextId = 0;
+  constructor(private readonly transport: (request: Request) => Response) {}
+  call<M extends keyof ResultMap>(method: M, params?: RequestParams<M>): Response<ResultMap[M]> {
+    const response = this.transport({ version: PROTOCOL, id: ++this.nextId, method, params });
+    return response as Response<ResultMap[M]>;
+  }
+}
+export type RequestParams<M extends keyof ResultMap> =
+  M extends "session/sync" ? SyncParams : M extends "session/sync-canonical" ? CanonicalSyncParams : M extends "project" ? ProjectParams : undefined;

package/src/context-spill.ts

@@ -0,0 +1,109 @@
+import { Buffer } from "node:buffer";
+import type { FileAttachmentRef } from "@deepseek-ai/dsh-attachment";
+import type { DurableFileAttachments } from "./durable-file-attachments.js";
+
+export const CONTEXT_SPILL_VERSION = "prime-agent-dsh/context-spill-v1" as const;
+
+export interface ContextSpillLocator {
+  readonly version: typeof CONTEXT_SPILL_VERSION;
+  readonly encoding: "utf-8";
+  readonly attachment: FileAttachmentRef;
+}
+export interface InlineContextText { readonly text: string; readonly spilled: false }
+export interface SpilledContextText {
+  readonly text: string;
+  readonly spilled: true;
+  readonly locator: ContextSpillLocator;
+  readonly originalBytes: number;
+}
+export type ContextText = InlineContextText | SpilledContextText;
+export interface SpillOptions {
+  /** Spill only when exact UTF-8 size is greater than this value. */
+  readonly thresholdBytes?: number;
+  /** Maximum UTF-8 bytes in the returned preview, including its marker. */
+  readonly previewBytes?: number;
+  readonly name?: string;
+}
+
+/**
+ * Persist oversized context without making persistence a new failure mode.
+ * Any write/quota error returns the exact original inline string.
+ */
+export async function spillContextText(
+  attachments: Pick<DurableFileAttachments, "save">,
+  value: string,
+  options: SpillOptions = {},
+): Promise<ContextText> {
+  const threshold = limit(options.thresholdBytes ?? 32 * 1024, "thresholdBytes");
+  const previewBytes = limit(options.previewBytes ?? 4 * 1024, "previewBytes");
+  if (!wellFormed(value)) return { text: value, spilled: false };
+  const data = Buffer.from(value, "utf8");
+  if (data.byteLength <= threshold) return { text: value, spilled: false };
+  try {
+    const attachment = await attachments.save(data, options.name ?? "context.txt");
+    return {
+      text: utf8Preview(data, previewBytes),
+      spilled: true,
+      locator: { version: CONTEXT_SPILL_VERSION, encoding: "utf-8", attachment },
+      originalBytes: data.byteLength,
+    };
+  } catch {
+    return { text: value, spilled: false };
+  }
+}
+
+
+export interface TextToolResult {
+  readonly content: string;
+  readonly [key: string]: unknown;
+}
+export type SpilledToolResult<T extends TextToolResult> = T & { readonly contextSpill?: ContextSpillLocator };
+
+/** Spill the string payload of a tool result while preserving all other fields. */
+export async function spillToolResult<T extends TextToolResult>(
+  attachments: Pick<DurableFileAttachments, "save">,
+  result: T,
+  options: SpillOptions = {},
+): Promise<SpilledToolResult<T>> {
+  const spilled = await spillContextText(attachments, result.content, {
+    ...options,
+    name: options.name ?? "tool-result.txt",
+  });
+  if (!spilled.spilled) return result;
+  return { ...result, content: spilled.text, contextSpill: spilled.locator };
+}
+
+/** Resolve a locator after the attachment backend verifies its size and digest. */
+export async function resolveContextSpill(
+  attachments: Pick<DurableFileAttachments, "read">,
+  locator: ContextSpillLocator,
+  signal?: AbortSignal,
+): Promise<string> {
+  if (locator.version !== CONTEXT_SPILL_VERSION || locator.encoding !== "utf-8") throw new Error("invalid context spill locator");
+  const bytes = await attachments.read(locator.attachment, signal);
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+
+/** UTF-8-safe prefix whose encoded size never exceeds `maximum`. */
+export function utf8Preview(data: Uint8Array, maximum: number): string {
+  limit(maximum, "maximum");
+  if (data.byteLength <= maximum) return new TextDecoder("utf-8", { fatal: true }).decode(data);
+  const marker = `\n[… ${data.byteLength} UTF-8 bytes total; full content at locator …]`;
+  const markerBytes = Buffer.byteLength(marker);
+  if (markerBytes > maximum) return truncateUtf8(Buffer.from(marker), maximum);
+  return truncateUtf8(data, maximum - markerBytes) + marker;
+}
+
+function truncateUtf8(data: Uint8Array, maximum: number): string {
+  let end = Math.min(maximum, data.byteLength);
+  while (end > 0 && (data[end] & 0xc0) === 0x80) end--;
+  return new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(0, end));
+}
+function limit(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
+  return value;
+}
+
+function wellFormed(value: string): boolean {
+  for (let i = 0; i < value.length; i++) { const code = value.charCodeAt(i); if (code >= 0xd800 && code <= 0xdbff) { const next = value.charCodeAt(++i); if (!(next >= 0xdc00 && next <= 0xdfff)) return false; } else if (code >= 0xdc00 && code <= 0xdfff) return false; } return true;
+}

package/src/dsh-context-service.ts

@@ -0,0 +1,38 @@
+import { Session, SessionId } from "@deepseek-ai/dsh-session";
+import { createAssistantMessage, createUserMessage, freezeMessage, type AssistantMessage, type Message, type ToolResultMessage, type UserMessage } from "@deepseek-ai/dsh-llm";
+import { PROTOCOL, type BranchKey, type CanonicalSyncParams, type MethodResult, type ProjectParams, type ProjectResult, type ProtocolErrorCode, type Request, type RequestId, type Response, type SessionSummary, type ShutdownResult, type SimpleMessage, type StatusResult, type Success, type SyncParams, type SyncResult, type InitializeResult } from "./context-protocol.js";
+
+type State = { session: Session; revision: number; canonical: readonly Message[] };
+type ObjectValue = Record<string, unknown>;
+const object = (value: unknown): ObjectValue | undefined => typeof value === "object" && value !== null && !Array.isArray(value) ? value as ObjectValue : undefined;
+const integer = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const stateKey = (key: BranchKey): string => JSON.stringify([key.sessionId, key.branchId]);
+class ProtocolFault extends Error { constructor(readonly code: ProtocolErrorCode, message: string, readonly data?: unknown) { super(message); } }
+const fault = (code: ProtocolErrorCode, message: string, data?: unknown): ProtocolFault => new ProtocolFault(code, message, data);
+
+class Validator {
+  request(raw: unknown): Request { const v=object(raw); if(!v) throw fault("INVALID_REQUEST","request must be an object"); if(v.version!==PROTOCOL) throw fault("UNSUPPORTED_VERSION",`expected ${PROTOCOL}`); if((typeof v.id!=="string"&&typeof v.id!=="number")||typeof v.method!=="string") throw fault("INVALID_REQUEST","id and method are required"); return {version:PROTOCOL,id:v.id,method:v.method,...(v.params===undefined?{}:{params:v.params})}; }
+  key(raw: unknown): BranchKey { const v=object(raw); if(!v||typeof v.sessionId!=="string"||!v.sessionId||typeof v.branchId!=="string"||!v.branchId) throw fault("INVALID_PARAMS","key requires non-empty sessionId and branchId"); return {sessionId:v.sessionId,branchId:v.branchId}; }
+  revision(v:ObjectValue): number|undefined { if(v.expectedRevision!==undefined&&!integer(v.expectedRevision)) throw fault("INVALID_PARAMS","expectedRevision must be a non-negative integer"); return v.expectedRevision; }
+  sync(raw:unknown):SyncParams { const v=object(raw); if(!v||!Array.isArray(v.messages)) throw fault("INVALID_PARAMS","session/sync requires key and messages[]"); const messages=v.messages.map((x,i)=>this.simple(x,i)); const expectedRevision=this.revision(v); return {key:this.key(v.key),messages,...(expectedRevision===undefined?{}:{expectedRevision})}; }
+  canonical(raw:unknown):CanonicalSyncParams { const v=object(raw); if(!v||!Array.isArray(v.messages)) throw fault("INVALID_PARAMS","session/sync-canonical requires key and messages[]"); let messages:Message[]; try { messages=v.messages.map(m=>freezeMessage(m as Message)); } catch(error) { throw fault("INVALID_PARAMS",error instanceof Error?error.message:"invalid canonical message"); } const expectedRevision=this.revision(v); return {key:this.key(v.key),messages,...(expectedRevision===undefined?{}:{expectedRevision})}; }
+  project(raw:unknown):ProjectParams { const v=object(raw); if(!v) throw fault("INVALID_PARAMS","project requires key"); for(const name of ["from","limit"] as const) if(v[name]!==undefined&&!integer(v[name])) throw fault("INVALID_PARAMS","from and limit must be non-negative integers"); return {key:this.key(v.key),...(v.from===undefined?{}:{from:v.from as number}),...(v.limit===undefined?{}:{limit:v.limit as number})}; }
+  private simple(raw:unknown,index:number):SimpleMessage { const v=object(raw); if(!v||(v.role!=="user"&&v.role!=="assistant")||typeof v.content!=="string") throw fault("INVALID_PARAMS",`invalid message at index ${index}`); if(v.role==="user") { if(v.source!==undefined&&typeof v.source!=="string") throw fault("INVALID_PARAMS",`invalid message at index ${index}`); return {role:"user",content:v.content,...(v.source===undefined?{}:{source:v.source})}; } if(v.provider!==undefined&&typeof v.provider!=="string"||v.model!==undefined&&typeof v.model!=="string") throw fault("INVALID_PARAMS",`invalid message at index ${index}`); return {role:"assistant",content:v.content,...(v.provider===undefined?{}:{provider:v.provider}),...(v.model===undefined?{}:{model:v.model})}; }
+}
+
+export class ContextService {
+ private initialized=false; private stopping=false; private readonly sessions=new Map<string,State>(); private readonly validator=new Validator();
+ constructor(private readonly onShutdown:()=>void=()=>{}){}
+ handle(raw:unknown):Response { let id:RequestId|null=null; try { const req=this.validator.request(raw); id=req.id; if(this.stopping&&req.method!=="status") throw fault("SHUTTING_DOWN","service is shutting down"); return this.success(id,this.dispatch(req)); } catch(error) { const f=error instanceof ProtocolFault?error:fault("INTERNAL",error instanceof Error?error.message:String(error)); return {version:PROTOCOL,id,ok:false,error:{code:f.code,message:f.message,...(f.data===undefined?{}:{data:f.data})}}; } }
+ private success(id:RequestId,result:MethodResult):Success{return {version:PROTOCOL,id,ok:true,result};}
+ private dispatch(req:Request):MethodResult { if(req.method==="initialize") return this.initialize(); if(!this.initialized) throw fault("NOT_INITIALIZED","call initialize first"); switch(req.method){case "session/sync":return this.syncSimple(this.validator.sync(req.params));case "session/sync-canonical":return this.syncCanonical(this.validator.canonical(req.params));case "project":return this.project(this.validator.project(req.params));case "status":return this.status();case "shutdown":return this.shutdown();default:throw fault("METHOD_NOT_FOUND",`unknown method: ${req.method}`);} }
+ private initialize():InitializeResult { if(this.initialized) throw fault("ALREADY_INITIALIZED","initialize may be called once"); this.initialized=true; return {protocol:PROTOCOL,implementation:{name:"dsh-inference-context",version:"0.0.1"},capabilities:{transport:["in-process"],methods:["initialize","session/sync","session/sync-canonical","project","status","shutdown"],dshSession:true,agentLoop:false}}; }
+ private syncSimple(p:SyncParams):SyncResult { const messages=p.messages.map(input=>input.role==="user"?createUserMessage({content:[{type:"text",text:input.content}],source:input.source&&input.source!=="user"?{kind:"plugin",plugin:input.source}:{kind:"user"}}):createAssistantMessage({content:[{type:"text",text:input.content}],source:{provider:input.provider??"external",model:input.model??"unknown"}})); return this.syncCanonical({key:p.key,messages,...(p.expectedRevision===undefined?{}:{expectedRevision:p.expectedRevision})}); }
+ private syncCanonical(p:CanonicalSyncParams):SyncResult { const sk=stateKey(p.key), prior=this.sessions.get(sk), actual=prior?.revision??0; if(p.expectedRevision!==undefined&&p.expectedRevision!==actual) throw fault("REVISION_CONFLICT","expectedRevision does not match",{actualRevision:actual}); const incoming=p.messages.map(m=>freezeMessage(m)); let common=0; if(prior) while(common<prior.canonical.length&&common<incoming.length&&JSON.stringify(prior.canonical[common])===JSON.stringify(incoming[common])) common++; if(prior&&common===prior.canonical.length&&common===incoming.length) return this.syncResult(p.key,prior,"noop",common); let session:Session,mode:"append"|"rebuild"; if(prior&&common===prior.canonical.length){ session=Session.create(SessionId(p.key.sessionId),prior.session.snapshotEvents()); mode="append"; this.append(session,incoming.slice(common),common); } else { session=Session.create(SessionId(p.key.sessionId)); mode="rebuild"; this.append(session,incoming,0); } const next={session,revision:actual+1,canonical:incoming}; this.sessions.set(sk,next); return this.syncResult(p.key,next,mode,common); }
+ private append(session:Session,messages:readonly Message[],offset:number):void { messages.forEach((message,index)=>{const step=offset+index;if(message.role==="assistant"){const assistant=message as AssistantMessage;session.append("assistant/message",{turn:step,step,message:assistant,stream:[]},{surfaceOp:"append"});for(const block of assistant.content)if(block.type==="tool-call")session.append("tool/call",{turn:step,step,callId:block.id,name:block.name,arguments:block.arguments});}else if(message.source.kind==="tool")session.append("tool/result",{turn:step,step,message:message as ToolResultMessage},{surfaceOp:"append"});else session.append("user/message",message as UserMessage,{surfaceOp:"append"});}); }
+ private syncResult(key:BranchKey,state:State,mode:SyncResult["mode"],commonPrefixMessages:number):SyncResult{return {key,revision:state.revision,eventCount:state.session.seq,messageCount:state.canonical.length,mode,commonPrefixMessages};}
+ private project(p:ProjectParams):ProjectResult { const state=this.sessions.get(stateKey(p.key));if(!state)throw fault("SESSION_NOT_FOUND",`unknown branch: ${p.key.sessionId}/${p.key.branchId}`);const derived=state.session.deriveMessages();const from=p.from??0,limit=p.limit??derived.length;return {key:p.key,revision:state.revision,total:derived.length,from,messages:derived.slice(from,from+limit)}; }
+ private status():StatusResult { const sessions:SessionSummary[]=[...this.sessions.values()].map(s=>({key:this.keyFor(s),revision:s.revision,eventCount:s.session.seq,messageCount:s.canonical.length}));return {initialized:true,shuttingDown:this.stopping,sessionCount:sessions.length,sessions}; }
+ private keyFor(target:State):BranchKey { for(const [encoded,state] of this.sessions)if(state===target){const parsed:unknown=JSON.parse(encoded);if(Array.isArray(parsed)&&typeof parsed[0]==="string"&&typeof parsed[1]==="string")return {sessionId:parsed[0],branchId:parsed[1]};}throw new Error("orphan session state"); }
+ private shutdown():ShutdownResult{this.stopping=true;queueMicrotask(this.onShutdown);return {accepted:true};}
+}