prime-agent-dsh 0.2.0

package/src/durable-file-attachments.ts

@@ -0,0 +1,186 @@
+import { Context } from "@deepseek-ai/cordis";
+import type { FileAttachmentRef } from "@deepseek-ai/dsh-attachment";
+import { LocalAttachmentStore } from "@deepseek-ai/dsh-attachment-local";
+import { lstat, readdir, rm } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+
+const ID = /^sha256:([a-f0-9]{64})$/;
+
+export interface DurableFileAttachmentOptions {
+  /** Dedicated DSH home. DSH stores files below attachments/v1. */
+  readonly dshHome: string;
+  readonly maxObjectBytes?: number;
+  readonly maxTotalBytes?: number;
+  readonly maxObjects?: number;
+}
+
+export interface AttachmentUsage { readonly objects: number; readonly bytes: number }
+export interface AttachmentCleanupResult extends AttachmentUsage { readonly removedObjects: number; readonly removedBytes: number }
+
+/**
+ * Provider-neutral durable files backed by DSH 0.1.6's verbatim attachment
+ * primitives. References contain no model, message, or tool owner.
+ */
+export class DurableFileAttachments {
+  readonly store: LocalAttachmentStore;
+  private readonly maxObjectBytes: number;
+  private readonly maxTotalBytes: number;
+  private readonly maxObjects: number;
+  private operation: Promise<void> = Promise.resolve();
+
+  constructor(options: DurableFileAttachmentOptions) {
+    if (!isAbsolute(options.dshHome)) throw new Error("dshHome must be absolute");
+    this.maxObjectBytes = positive(options.maxObjectBytes ?? 64 * 1024 * 1024, "maxObjectBytes");
+    this.maxTotalBytes = positive(options.maxTotalBytes ?? 512 * 1024 * 1024, "maxTotalBytes");
+    this.maxObjects = positive(options.maxObjects ?? 10_000, "maxObjects");
+    this.store = new LocalAttachmentStore(new Context(), { dshHome: options.dshHome });
+  }
+
+  async save(data: Uint8Array, name = "attachment.bin"): Promise<FileAttachmentRef> {
+    if (data.byteLength > this.maxObjectBytes) throw new Error("attachment exceeds maxObjectBytes");
+    return this.exclusive(async () => {
+      const digest = await sha256(data);
+      const usage = await this.usage();
+      const duplicate = await this.objectExists(digest);
+      if (!duplicate && (usage.objects >= this.maxObjects || usage.bytes + data.byteLength > this.maxTotalBytes)) {
+        throw new Error("attachment quota exceeded");
+      }
+      return this.store.saveFile({ data, name });
+    });
+  }
+
+  /** Read only after DSH verifies both byte length and sha256 digest. */
+  async read(ref: FileAttachmentRef, signal?: AbortSignal): Promise<Uint8Array> {
+    await this.assertSafeLocator(ref);
+    if (ref.bytes > this.maxObjectBytes) throw new Error("attachment exceeds maxObjectBytes");
+    const chunks: Uint8Array[] = []; let size = 0;
+    for await (const chunk of this.store.readFileStream(ref, signal)) { size += chunk.byteLength; if (size > this.maxObjectBytes || size > ref.bytes) throw new Error("attachment read exceeds declared bound"); chunks.push(chunk); }
+    if (size !== ref.bytes) throw new Error("attachment byte length mismatch");
+    const value = new Uint8Array(size); let offset = 0;
+    for (const chunk of chunks) { value.set(chunk, offset); offset += chunk.byteLength; }
+    return value;
+  }
+
+  async *readStream(ref: FileAttachmentRef, signal?: AbortSignal): AsyncIterable<Uint8Array> {
+    await this.assertSafeLocator(ref); if (ref.bytes > this.maxObjectBytes) throw new Error("attachment exceeds maxObjectBytes");
+    let size = 0; for await (const chunk of this.store.readFileStream(ref, signal)) { size += chunk.byteLength; if (size > this.maxObjectBytes || size > ref.bytes) throw new Error("attachment stream exceeds declared bound"); yield chunk; }
+    if (size !== ref.bytes) throw new Error("attachment byte length mismatch");
+  }
+
+  /** Absolute read-only host locator. Invalid/traversing references are rejected by DSH. */
+  hostPath(ref: FileAttachmentRef): string {
+    return this.store.fileHostPath(ref);
+  }
+
+  async usage(): Promise<AttachmentUsage> {
+    const root = join(this.store.root, "file-objects");
+    let objects = 0; let bytes = 0;
+    for (const path of await objectPaths(root)) {
+      const stat = await lstat(path);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`unsafe attachment object: ${path}`);
+      objects++; bytes += stat.size;
+    }
+    return { objects, bytes };
+  }
+
+  /**
+   * Delete generic files not present in `retain`. Callers pass all live durable
+   * references. Image objects are never touched. Unsafe links abort cleanup.
+   */
+  async cleanup(retain: readonly FileAttachmentRef[]): Promise<AttachmentCleanupResult> {
+    return this.exclusive(async () => {
+      const keep = new Set(retain.map(digestOf));
+      const root = join(this.store.root, "file-objects");
+      let removedObjects = 0; let removedBytes = 0;
+      for (const path of await objectPaths(root)) {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`unsafe attachment object: ${path}`);
+        const digest = path.slice(path.lastIndexOf("/") + 1);
+        if (!keep.has(digest)) {
+          const aliases = join(this.store.root, "files", digest.slice(0, 2), digest);
+          await assertSafeTree(aliases);
+          await rm(path); removedObjects++; removedBytes += stat.size;
+          // Aliases are hard links, but may use many safe display names.
+          await rm(aliases, { recursive: true, force: true });
+        }
+      }
+      const usage = await this.usage();
+      return { ...usage, removedObjects, removedBytes };
+    });
+  }
+
+  private async assertSafeLocator(ref: FileAttachmentRef): Promise<void> {
+    digestOf(ref);
+    const root = this.store.root;
+    const path = this.store.fileHostPath(ref);
+    const rel = relative(root, path); if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("attachment path escapes root");
+    const rootStat = await lstat(root); if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error("unsafe attachment root");
+    for (let cursor = path; cursor !== root; cursor = dirname(cursor)) {
+      const stat = await lstat(cursor);
+      if (stat.isSymbolicLink()) throw new Error(`symlink is not allowed in attachment path: ${cursor}`);
+      if (cursor === path && !stat.isFile()) throw new Error("attachment locator is not a file");
+      if (dirname(cursor) === cursor) throw new Error("attachment path escapes root");
+    }
+  }
+
+  private async objectExists(digest: string): Promise<boolean> {
+    try {
+      const stat = await lstat(join(this.store.root, "file-objects", digest.slice(0, 2), digest));
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("unsafe attachment object");
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+      throw error;
+    }
+  }
+
+  private async exclusive<T>(work: () => Promise<T>): Promise<T> {
+    const prior = this.operation; let release!: () => void;
+    this.operation = new Promise<void>((resolve) => { release = resolve; });
+    await prior;
+    try { return await work(); } finally { release(); }
+  }
+}
+
+function positive(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
+  return value;
+}
+function digestOf(ref: FileAttachmentRef): string {
+  const match = ID.exec(String(ref.attachmentId));
+  if (!match || !Number.isSafeInteger(ref.bytes) || ref.bytes < 0) throw new Error("invalid attachment reference");
+  return match[1];
+}
+async function sha256(data: Uint8Array): Promise<string> {
+  const { createHash } = await import("node:crypto");
+  return createHash("sha256").update(data).digest("hex");
+}
+async function objectPaths(root: string): Promise<string[]> {
+  let buckets;
+  try { buckets = await readdir(root, { withFileTypes: true }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+  const result: string[] = [];
+  for (const bucket of buckets) {
+    if (!bucket.isDirectory() || bucket.isSymbolicLink() || !/^[a-f0-9]{2}$/.test(bucket.name)) throw new Error("unsafe attachment object directory");
+    for (const item of await readdir(join(root, bucket.name), { withFileTypes: true })) {
+      if (!item.isFile() || item.isSymbolicLink() || !/^[a-f0-9]{64}$/.test(item.name) || !item.name.startsWith(bucket.name)) throw new Error("unsafe attachment object entry");
+      result.push(join(root, bucket.name, item.name));
+    }
+  }
+  return result;
+}
+
+async function assertSafeTree(root: string): Promise<void> {
+  let entries;
+  try {
+    const stat = await lstat(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`unsafe attachment alias directory: ${root}`);
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error(`unsafe attachment alias: ${entry.name}`);
+  }
+}

package/src/prefix-metrics.ts

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+
+export interface PrefixMeasurement {
+  request: number;
+  bytes: number;
+  previousBytes: number;
+  commonPrefixBytes: number;
+  prefixRatio: number;
+  digest: string;
+  changedAt: number;
+  reason: "initial" | "append" | "model-or-envelope" | "history-rewrite";
+}
+
+export function stableJson(value: unknown, sortKeys = true): string {
+  const seen = new WeakSet<object>();
+  const visit = (item: unknown): unknown => {
+    if (Array.isArray(item)) return item.map(visit);
+    if (item && typeof item === "object") {
+      if (seen.has(item)) throw new Error("cyclic provider payload");
+      seen.add(item);
+      const result: Record<string, unknown> = {};
+      for (const key of (sortKeys ? Object.keys(item).sort() : Object.keys(item))) {
+        if (/authorization|api[_-]?key|token|secret|password|cookie/i.test(key)) { result[key] = "[REDACTED]"; continue; }
+        const value = (item as Record<string, unknown>)[key];
+        if (value !== undefined) result[key] = visit(value);
+      }
+      return result;
+    }
+    return typeof item === "bigint" ? item.toString() : item;
+  };
+  return JSON.stringify(visit(value));
+}
+
+export function commonPrefixBytes(left: string, right: string): number {
+  const a = Buffer.from(left), b = Buffer.from(right); const n = Math.min(a.length, b.length);
+  let i = 0; while (i < n && a[i] === b[i]) i++; return i;
+}
+
+interface PrefixFingerprint {
+  readonly bytes: number;
+  readonly digest: string;
+  /** Fixed-size chunk digests. They retain no provider or transcript text. */
+  readonly chunks: readonly string[];
+}
+
+const PREFIX_CHUNK_BYTES = 256;
+
+function fingerprint(value: string): PrefixFingerprint {
+  const bytes = Buffer.from(value);
+  const chunks: string[] = [];
+  for (let offset = 0; offset < bytes.length; offset += PREFIX_CHUNK_BYTES) {
+    chunks.push(createHash("sha256").update(bytes.subarray(offset, offset + PREFIX_CHUNK_BYTES)).digest("hex"));
+  }
+  return { bytes: bytes.length, digest: createHash("sha256").update(bytes).digest("hex"), chunks: Object.freeze(chunks) };
+}
+
+function measuredCommonPrefix(previous: PrefixFingerprint, currentText: string, current: PrefixFingerprint): number {
+  const bytes = Buffer.from(currentText);
+  // Exact append detection needs only the prior digest, not the prior content.
+  if (bytes.length >= previous.bytes && createHash("sha256").update(bytes.subarray(0, previous.bytes)).digest("hex") === previous.digest) {
+    return previous.bytes;
+  }
+  let chunks = 0;
+  const complete = Math.floor(Math.min(previous.bytes, current.bytes) / PREFIX_CHUNK_BYTES);
+  while (chunks < complete && previous.chunks[chunks] === current.chunks[chunks]) chunks++;
+  // For rewrites this is a privacy-preserving lower bound, accurate to one chunk.
+  return chunks * PREFIX_CHUNK_BYTES;
+}
+
+export class PrefixTracker {
+  private previous?: PrefixFingerprint;
+  private count = 0;
+  constructor(private readonly sortKeys = true) {}
+  measure(payload: unknown): PrefixMeasurement {
+    const canonical = stableJson(payload, this.sortKeys);
+    const current = fingerprint(canonical), previous = this.previous;
+    const common = previous === undefined ? 0 : measuredCommonPrefix(previous, canonical, current);
+    const bytes = current.bytes, previousBytes = previous?.bytes ?? 0;
+    let reason: PrefixMeasurement["reason"] = "initial";
+    if (previous !== undefined) {
+      if (common === previousBytes || common / Math.max(1, previousBytes) >= 0.9) reason = "append";
+      else if (common < Math.min(previousBytes, 1024)) reason = "model-or-envelope";
+      else reason = "history-rewrite";
+    }
+    this.previous = current;
+    return { request: ++this.count, bytes, previousBytes, commonPrefixBytes: common,
+      prefixRatio: previousBytes === 0 ? 0 : common / previousBytes,
+      digest: current.digest, changedAt: common, reason };
+  }
+  reset(): void { this.previous = undefined; this.count = 0; }
+}

package/src/provider-cache-series.ts

@@ -0,0 +1,56 @@
+/** Provider cache accounting. Byte-prefix eligibility belongs in prefix-metrics, not here. */
+export interface ProviderCacheSample {
+  readonly request: number;
+  readonly inputTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+}
+export interface ProviderCachePoint extends ProviderCacheSample {
+  /** null means the provider did not report enough data. */
+  readonly efficiency: number | null;
+}
+export interface ProviderCacheAggregate {
+  readonly requests: number;
+  readonly reportedReadRequests: number;
+  readonly reportedWriteRequests: number;
+  readonly cacheReadTokens: number;
+  readonly cacheWriteTokens: number;
+  readonly inputTokens: number;
+  readonly efficiency: number | null;
+  readonly readP50: number | null;
+  readonly readP90: number | null;
+  readonly writeP50: number | null;
+  readonly writeP90: number | null;
+  readonly efficiencyP50: number | null;
+  readonly efficiencyP90: number | null;
+}
+const valid = (x: unknown): x is number => typeof x === "number" && Number.isFinite(x) && x >= 0;
+function percentile(values: readonly number[], p: number): number | null {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.ceil(p * sorted.length) - 1] ?? null;
+}
+export class ProviderCacheSeries {
+  private readonly values: ProviderCachePoint[] = [];
+  add(sample: ProviderCacheSample): ProviderCachePoint {
+    if (!Number.isSafeInteger(sample.request) || sample.request <= 0) throw new TypeError("request must be a positive integer");
+    for (const [key, value] of Object.entries(sample)) if (key !== "request" && value !== undefined && !valid(value)) throw new TypeError(`${key} must be non-negative`);
+    const read = sample.cacheReadTokens, input = sample.inputTokens;
+    const efficiency = valid(read) && valid(input) && input + read > 0 ? read / (input + read) : null;
+    const point = Object.freeze({ ...sample, efficiency }); this.values.push(point); return point;
+  }
+  points(): readonly ProviderCachePoint[] { return Object.freeze([...this.values]); }
+  aggregate(): ProviderCacheAggregate {
+    const reads = this.values.flatMap(x => valid(x.cacheReadTokens) ? [x.cacheReadTokens] : []);
+    const writes = this.values.flatMap(x => valid(x.cacheWriteTokens) ? [x.cacheWriteTokens] : []);
+    const inputs = this.values.flatMap(x => valid(x.inputTokens) ? [x.inputTokens] : []);
+    const cacheReadTokens = reads.reduce((a, b) => a + b, 0), inputTokens = inputs.reduce((a, b) => a + b, 0);
+    return Object.freeze({ requests: this.values.length, reportedReadRequests: reads.length, reportedWriteRequests: writes.length,
+      cacheReadTokens, cacheWriteTokens: writes.reduce((a, b) => a + b, 0), inputTokens,
+      efficiency: reads.length && inputs.length && inputTokens + cacheReadTokens > 0 ? cacheReadTokens / (inputTokens + cacheReadTokens) : null,
+      readP50: percentile(reads, .5), readP90: percentile(reads, .9),
+      writeP50: percentile(writes, .5), writeP90: percentile(writes, .9),
+      efficiencyP50: percentile(this.values.flatMap(x => x.efficiency === null ? [] : [x.efficiency]), .5),
+      efficiencyP90: percentile(this.values.flatMap(x => x.efficiency === null ? [] : [x.efficiency]), .9) });
+  }
+}

package/src/recursive-context-loader.ts

@@ -0,0 +1,215 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ContextObjectStore, type ContextObjectSyncResult } from "./context-objects.js";
+import { ProviderCacheSeries, type ProviderCacheAggregate, type ProviderCachePoint } from "./provider-cache-series.js";
+
+const number = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+
+interface PendingSync {
+  readonly ctx: ExtensionContext;
+  readonly messages?: readonly unknown[];
+}
+
+export interface SessionContextScope {
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly bindingKey: string;
+  enabled: boolean;
+  disabledReason?: string;
+  lastSync?: ContextObjectSyncResult;
+  /** Process-local completion time for status/doctor freshness. */
+  lastSyncAt?: number;
+  lastError?: string;
+  syncs: number;
+  errors: number;
+  cache?: ProviderCacheAggregate;
+  latestCache?: ProviderCachePoint;
+  cacheSeries?: ProviderCacheSeries;
+  dirty?: boolean;
+  pending?: PendingSync;
+  running?: Promise<void>;
+}
+
+/**
+ * Binds one derived DSH context scope to every Prime AgentSession, including
+ * independently rebound RLM descendants. Prime remains the only loop and log
+ * authority; scopes contain rebuildable projections and private artifacts.
+ */
+export class RecursiveContextLoader {
+  private readonly scopes = new Map<string, SessionContextScope>();
+
+  constructor(private readonly store = new ContextObjectStore()) {}
+
+  register(pi: Pick<ExtensionAPI, "on">): void {
+    pi.on("session_start", async (_event, ctx) => {
+      const scope = this.bind(ctx);
+      await this.requestSync(ctx, scope, undefined, true);
+    });
+    pi.on("context", (event, ctx) => {
+      const scope = this.scopeFor(ctx);
+      this.observeProviderCache(scope, event.messages);
+      void this.requestSync(ctx, scope, event.messages, false);
+      // Observation only: durable conversion and fsync run after this hook returns.
+    });
+    pi.on("message_end", (_event, ctx) => {
+      const scope = this.scopeFor(ctx);
+      void this.requestSync(ctx, scope, undefined, false);
+    });
+    pi.on("turn_end", async (_event, ctx) => {
+      const scope = this.scopeFor(ctx);
+      await this.requestSync(ctx, scope, undefined, true);
+    });
+    pi.on("session_compact", async (_event, ctx) => {
+      const scope = this.scopeFor(ctx);
+      await this.requestSync(ctx, scope, undefined, true);
+    });
+    pi.on("session_shutdown", async (_event, ctx) => {
+      if (!ctx?.sessionManager) { this.scopes.clear(); return; }
+      const sessionId = this.sessionId(ctx);
+      const scope = this.scopes.get(sessionId);
+      if (!scope || scope.bindingKey !== this.bindingKey(ctx)) return;
+      await this.requestSync(ctx, scope, undefined, true);
+      if (this.scopes.get(sessionId) === scope) this.scopes.delete(sessionId);
+    });
+  }
+
+  status(ctx: ExtensionContext): Readonly<SessionContextScope> | undefined {
+    return this.scopes.get(this.sessionId(ctx));
+  }
+
+  setEnabled(ctx: ExtensionContext, enabled: boolean): boolean {
+    const scope = this.scopes.get(this.sessionId(ctx)) ?? this.bind(ctx);
+    scope.enabled = enabled;
+    if (enabled) { delete scope.disabledReason; delete scope.lastError; }
+    return scope.enabled;
+  }
+
+  isEnabled(ctx: ExtensionContext): boolean {
+    return this.scopes.get(this.sessionId(ctx))?.enabled ?? true;
+  }
+
+  /** Record finalized provider usage before Prime emits the next context event. */
+  observeFinalizedAssistant(ctx: ExtensionContext, message: unknown): ProviderCachePoint | undefined {
+    if (!message || typeof message !== "object") return undefined;
+    const value = message as Record<string, unknown>;
+    if (value.role !== "assistant" || !value.usage || typeof value.usage !== "object") return undefined;
+    const usage = value.usage as Record<string, unknown>;
+    const scope = this.scopeFor(ctx);
+    const series = scope.cacheSeries ?? new ProviderCacheSeries();
+    const latest = series.add({
+      request: series.points().length + 1,
+      inputTokens: number(usage.input),
+      cacheReadTokens: number(usage.cacheRead),
+      cacheWriteTokens: number(usage.cacheWrite),
+    });
+    scope.cacheSeries = series;
+    scope.latestCache = latest;
+    scope.cache = series.aggregate();
+    return latest;
+  }
+
+  private async requestSync(ctx: ExtensionContext, scope: SessionContextScope, messages: readonly unknown[] | undefined, wait: boolean): Promise<void> {
+    if (!scope.enabled || this.scopes.get(scope.sessionId) !== scope) return;
+    scope.pending = { ctx: this.detach(ctx), ...(messages === undefined ? {} : { messages: [...messages] }) };
+    scope.dirty = true;
+    this.startWorker(scope);
+    if (wait) while (scope.running) await scope.running;
+  }
+
+  private startWorker(scope: SessionContextScope): void {
+    if (scope.running || !scope.enabled) return;
+    scope.running = Promise.resolve().then(async () => {
+      while (scope.dirty && scope.enabled && this.scopes.get(scope.sessionId) === scope) {
+        scope.dirty = false;
+        const pending = scope.pending;
+        if (!pending) continue;
+        await this.synchronize(pending.ctx, scope, pending.messages);
+      }
+    }).finally(() => {
+      scope.running = undefined;
+      if (scope.dirty && scope.enabled && this.scopes.get(scope.sessionId) === scope) this.startWorker(scope);
+    });
+  }
+
+  private async synchronize(ctx: ExtensionContext, scope: SessionContextScope, messages?: readonly unknown[]): Promise<void> {
+    if (!scope.enabled || this.scopes.get(scope.sessionId) !== scope) return;
+    try {
+      const synced = await this.store.sync(ctx, messages);
+      if (this.scopes.get(scope.sessionId) !== scope) return;
+      if (synced) {
+        scope.lastSync = synced;
+        scope.lastSyncAt = Date.now();
+      }
+      scope.lastError = undefined;
+      scope.syncs++;
+    } catch (error) {
+      if (this.scopes.get(scope.sessionId) !== scope) return;
+      scope.errors++;
+      const message = error instanceof Error ? error.message : String(error);
+      scope.lastError = message;
+      if (error instanceof Error && (error.name === "DurablePublicationUnavailableError" || "code" in error && (error as Error & { code?: string }).code === "DURABLE_PUBLICATION_UNAVAILABLE")) {
+        scope.enabled = false;
+        scope.disabledReason = message;
+        scope.dirty = false;
+        scope.pending = undefined;
+      }
+    }
+  }
+
+  /** Copy every host-owned value needed by deferred work while ctx is valid. */
+  private detach(ctx: ExtensionContext): ExtensionContext {
+    const sessionId = ctx.sessionManager.getSessionId?.() ?? "";
+    const sessionFile = ctx.sessionManager.getSessionFile?.();
+    const leafId = ctx.sessionManager.getLeafId?.();
+    const branch = [...(ctx.sessionManager.getBranch?.() ?? [])];
+    const cwd = ctx.cwd;
+    return {
+      cwd,
+      sessionManager: {
+        getSessionId: () => sessionId,
+        getSessionFile: () => sessionFile,
+        getLeafId: () => leafId,
+        getBranch: () => branch,
+      },
+    } as unknown as ExtensionContext;
+  }
+
+
+  /** Rebuild provider-reported cache accounting from the current native context. */
+  private observeProviderCache(scope: SessionContextScope, input: readonly unknown[]): void {
+    const series = new ProviderCacheSeries();
+    let request = 0;
+    for (const raw of input) {
+      if (!raw || typeof raw !== "object") continue;
+      const value = raw as Record<string, unknown>;
+      if (value.role !== "assistant" || !value.usage || typeof value.usage !== "object") continue;
+      const usage = value.usage as Record<string, unknown>;
+      request++;
+      series.add({ request, inputTokens: number(usage.input), cacheReadTokens: number(usage.cacheRead), cacheWriteTokens: number(usage.cacheWrite) });
+    }
+    scope.cacheSeries = series;
+    scope.cache = series.aggregate();
+    const latest = series.points().at(-1);
+    if (latest) scope.latestCache = latest; else delete scope.latestCache;
+  }
+
+  private sessionId(ctx: ExtensionContext): string {
+    return ctx.sessionManager.getSessionId?.() ?? ctx.cwd;
+  }
+
+  private bindingKey(ctx: ExtensionContext): string {
+    return JSON.stringify([this.sessionId(ctx), ctx.sessionManager.getSessionFile?.() ?? "", ctx.cwd]);
+  }
+
+  private scopeFor(ctx: ExtensionContext): SessionContextScope {
+    const prior = this.scopes.get(this.sessionId(ctx));
+    return prior?.bindingKey === this.bindingKey(ctx) ? prior : this.bind(ctx);
+  }
+
+  private bind(ctx: ExtensionContext): SessionContextScope {
+    const sessionId = this.sessionId(ctx);
+    const prior = this.scopes.get(sessionId);
+    const scope: SessionContextScope = { sessionId, cwd: ctx.cwd, bindingKey: this.bindingKey(ctx), enabled: prior?.enabled ?? true, syncs: 0, errors: 0 };
+    this.scopes.set(sessionId, scope);
+    return scope;
+  }
+}