@mono-agent/agent-runtime 0.9.1 → 0.11.0

package/README.md

@@ -16,7 +16,7 @@ Provides five runtime bridges (Claude SDK, Claude Code CLI, Codex app-server, Op
 - `ai/providers/claude-sdk-discovery.js` — isolated Claude SDK model discovery without importing ambient auth/config
 - `createRouterRuntime({ chain, routeSafety, resolveAttempt })` — ordered fallback routing with exact route effort and bounded safety/failover telemetry
 - Provider bridges for `claude` (SDK + CLI), `codex` (app-server), `pi` (Pi SDK), and `opencode`
-- Provider session support: bridges accept `sessionId` in run options and report `provider_session_id`; the runtime exposes `disposeSession` / `disposeAllSessions`
+- Provider session support: bridges accept `sessionId` in run options and report `provider_session_id`; the runtime exposes best-effort disposal, strict cold-refresh, exact-id durable retirement, invalidation, and whole-runtime shutdown operations
 - Sandbox-aware built-in tools and stdio MCP startup through an injectable `RuntimeSandbox` seam (`agent/sandbox-seam.js`) — no direct dependency on `@mono-agent/runtime-adapter`
 
 ## Dependency Boundary
@@ -219,6 +219,10 @@ Returns:
 
 - `run(systemPrompt, options)` — async, runs one agent turn against the chosen backend.
 - `configureTools(next)` — update the tool runtime context after construction.
+- `syncSession(id)` — fsync provider-owned durable state before canonical history commits.
+- `refreshSession(id)` — guarantee the next resume cannot reuse process-local state; absence succeeds and cleanup uncertainty rejects.
+- `retireDurableSession(id, sessionsRoot)` — delete and verify every exact-id durable Pi transcript, including cold duplicates.
+- `disposeSession(id)` / `invalidateSession(id)` / `disposeAllSessions()` — ordinary best-effort eviction, destructive live invalidation, and shutdown cleanup.
 
 ### `runtime.run(systemPrompt, options)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/agent-runtime",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Agent runtime supporting Claude SDK/CLI, Codex, OpenCode, and Pi SDK bridges out of the box",
   "type": "module",
   "license": "GPL-3.0-only",

package/src/agent/prompt/skill-index.js

@@ -37,7 +37,7 @@ export function buildSkillPathNote({ assetsPath, skillsRoot } = {}) {
 /**
  * @param {{body?: string, assetsPath?: string, skillsRoot?: any, maxChars?: number}} [options]
  */
-export function formatSkillBodyWithPathNote({ body, assetsPath, skillsRoot, maxChars = 12000 } = {}) {
+export function formatSkillBodyWithPathNote({ body, assetsPath, skillsRoot, maxChars } = {}) {
   const text = [
     buildSkillPathNote({ assetsPath, skillsRoot }),
     String(body || "").trim(),

package/src/ai/index.js

@@ -7,6 +7,9 @@ export {
   createSessionRegistry,
   disposeAllProviderSessions,
   disposeProviderSession,
+  invalidateProviderSession,
+  refreshProviderSession,
+  syncProviderSession,
 } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";

package/src/ai/providers/pi-native/session-lifecycle.js

@@ -12,9 +12,45 @@
 
 import { InMemorySessionRepo, JsonlSessionRepo } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
+import { open } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { createSessionRegistry } from "../../runtime/sessions.js";
 import { createSessionLiveness } from "../../runtime/session-liveness.js";
 
+async function syncPath(path) {
+  const handle = await open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function syncDurableTranscript(entry) {
+  if (!entry.durable) return;
+  const path = entry.metadata?.path;
+  if (typeof path !== "string" || !path) {
+    throw new Error("Durable Pi session metadata is missing its JSONL path");
+  }
+  // pi-core appends through short-lived file descriptors. Re-open the live
+  // JSONL and fsync it, then fsync its containing directory so both transcript
+  // bytes and the directory entry are stable before host history commits.
+  await syncPath(path);
+  await syncPath(dirname(path));
+}
+
+async function invalidateNativeSession(entry) {
+  await entry.repo.delete(entry.metadata);
+  if (entry.durable) {
+    const path = entry.metadata?.path;
+    if (typeof path !== "string" || !path) {
+      throw new Error("Durable Pi session metadata is missing its JSONL path");
+    }
+    // Make the unlink durable before the registry forgets the busy marker.
+    await syncPath(dirname(path));
+  }
+}
+
 // Live pi-native sessions, keyed by provider session id. Entries are
 // { session, metadata, repo, durable, busy } — identical shape and lifecycle
 // policy to the (now-retired) pi-sdk bridge: in-memory transcripts are freed
@@ -25,11 +61,21 @@ import { createSessionLiveness } from "../../runtime/session-liveness.js";
 const nativeSessionRepo = new InMemorySessionRepo();
 const nativeSessions = createSessionRegistry({
   isBusy: (entry) => entry.busy === true,
-  onEvict: async (entry) => {
+  onSync: syncDurableTranscript,
+  onEvict: async (entry, reason) => {
+    // Ordinary disposal/TTL only drops the live handle so durable sessions can
+    // reopen after restart. Explicit invalidation means the host rejected the
+    // turn before canonical history commit; that poisoned transcript must be
+    // deleted too or it could silently reappear on the next stable-id resume.
+    if (reason === "invalidated") {
+      // Destructive invalidation is an honest API: deletion (and, for JSONL,
+      // parent-directory fsync) must finish before registry removal, and any
+      // failure must reach the caller so it cannot assume cleanup succeeded.
+      await invalidateNativeSession(entry);
+      return;
+    }
     if (entry.durable) return;
-    try {
-      await entry.repo.delete(entry.metadata);
-    } catch { /* best-effort */ }
+    await entry.repo.delete(entry.metadata);
   },
 });
 const liveness = createSessionLiveness(nativeSessions);
@@ -50,6 +96,46 @@ export function resolveDurableNativeSessionRepo(piSessionsRoot) {
   return repo;
 }
 
+/**
+ * Permanently retire every durable Pi transcript with this exact logical id.
+ * This is intentionally stronger than live-session invalidation: history
+ * rotation and retention can retire an epoch after its registry entry was
+ * already evicted or after a process restart. Absence is success; any cleanup
+ * or verification uncertainty rejects so canonical history remains reachable.
+ */
+export async function retireDurableNativeSession(providerSessionId, piSessionsRoot) {
+  if (!isSafeSessionId(providerSessionId)) {
+    throw new TypeError("providerSessionId must be a safe, non-empty session id");
+  }
+  if (typeof piSessionsRoot !== "string" || !piSessionsRoot.trim()) {
+    throw new TypeError("piSessionsRoot must be a non-empty path");
+  }
+
+  // First guarantee this process cannot keep writing through a stale handle.
+  // Other processes are serialized by the history coordinator and must pass
+  // the same cold-refresh barrier before their next turn.
+  await nativeSessions.refresh(providerSessionId);
+
+  const repo = resolveDurableNativeSessionRepo(piSessionsRoot);
+  if (!repo) throw new Error("Durable Pi session repository is unavailable");
+  const matches = (await repo.list()).filter((entry) => entry?.id === providerSessionId);
+  const changedDirectories = new Set();
+  for (const metadata of matches) {
+    if (typeof metadata?.path !== "string" || !metadata.path) {
+      throw new Error(`Durable Pi session ${providerSessionId} has invalid metadata`);
+    }
+    await repo.delete(metadata);
+    changedDirectories.add(dirname(metadata.path));
+  }
+  for (const directory of changedDirectories) await syncPath(directory);
+  if (changedDirectories.size > 0) await syncPath(resolve(piSessionsRoot));
+
+  const remaining = (await repo.list()).filter((entry) => entry?.id === providerSessionId);
+  if (remaining.length > 0) {
+    throw new Error(`Durable Pi session ${providerSessionId} could not be retired completely`);
+  }
+}
+
 // Defense in depth (R4): create-on-miss passes the caller-controlled session id
 // straight to durableRepo.create({ id }), and JsonlSessionRepo writes
 // `${createdAt}_${id}.jsonl` — so an id like "../../../../tmp/pwn" would escape

package/src/ai/runtime/router.js

@@ -14,7 +14,9 @@
 // API:
 //   createRouterRuntime({ host, chain })
 //     returns { run(systemPrompt, options) } plus configureTools /
-//     disposeSession / disposeAllSessions delegated to the inner runtime,
+//     syncSession / refreshSession / retireDurableSession / disposeSession /
+//     invalidateSession / disposeAllSessions
+//     delegated to the inner runtime,
 //     so the router is a drop-in replacement for createRuntime(host).
 //
 //   chain entries:
@@ -388,6 +390,29 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
       // attempts use their isolated route runtime, and applying one route's
       // policy to this shared standby would defeat that isolation.
     },
+    async syncSession(providerSessionId) {
+      let synced = false;
+      for (const runtime of allRuntimes(inner, routeRuntimes)) {
+        synced = Boolean(await runtime.syncSession?.(providerSessionId)) || synced;
+      }
+      return synced;
+    },
+    async refreshSession(providerSessionId) {
+      for (const runtime of allRuntimes(inner, routeRuntimes)) {
+        if (typeof runtime.refreshSession !== "function") {
+          throw new Error("A routed runtime cannot guarantee a cold provider-session reopen");
+        }
+        await runtime.refreshSession(providerSessionId);
+      }
+    },
+    async retireDurableSession(providerSessionId, sessionsRoot) {
+      for (const runtime of allRuntimes(inner, routeRuntimes)) {
+        if (typeof runtime.retireDurableSession !== "function") {
+          throw new Error("A routed runtime cannot retire durable provider-session state");
+        }
+        await runtime.retireDurableSession(providerSessionId, sessionsRoot);
+      }
+    },
     async disposeSession(providerSessionId) {
       let disposed = false;
       for (const runtime of allRuntimes(inner, routeRuntimes)) {
@@ -395,6 +420,13 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
       }
       return disposed;
     },
+    async invalidateSession(providerSessionId) {
+      let invalidated = false;
+      for (const runtime of allRuntimes(inner, routeRuntimes)) {
+        invalidated = Boolean(await runtime.invalidateSession?.(providerSessionId)) || invalidated;
+      }
+      return invalidated;
+    },
     async disposeAllSessions() {
       await Promise.all(allRuntimes(inner, routeRuntimes).map(async (runtime) => runtime.disposeAllSessions?.()));
     },

package/src/ai/runtime/sessions.js

@@ -11,7 +11,8 @@
 // sleep) still cannot resurrect an expired session.
 //
 // `createSessionRegistry` instances self-register in a module-level set so
-// the runtime surface can expose `disposeSession(id)` / `disposeAllSessions()`
+// the runtime surface can expose `syncSession(id)` / `refreshSession(id)` /
+// `disposeSession(id)` / `disposeAllSessions()`
 // without knowing which bridge owns the id. Provider session ids are unique
 // across bridges (codex thread ids, pi uuids), so fan-out dispose is safe.
 
@@ -29,16 +30,34 @@ function normalizeTtl(value, fallback) {
  * @param {object} [options]
  * @param {number} [options.idleTimeoutMs]
  * @param {(value: any, reason: string) => (void | Promise<void>)} [options.onEvict]
+ * @param {(value: any) => (void | Promise<void>)} [options.onSync]
  * @param {() => number} [options.now]
  * @param {(value: any) => boolean} [options.isBusy]
  */
-export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS, onEvict, now = Date.now, isBusy } = {}) {
+export function createSessionRegistry({
+  idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+  onEvict,
+  onSync,
+  now = Date.now,
+  isBusy,
+} = {}) {
   const entries = new Map();
   const defaultTtlMs = normalizeTtl(idleTimeoutMs, DEFAULT_IDLE_TIMEOUT_MS);
+  // A destructive invalidation must keep the id occupied until provider
+  // cleanup is durably complete. Returning a busy placeholder makes existing
+  // await-free liveness claims fail closed instead of treating the id as a
+  // cold-reopen miss while its JSONL is still being unlinked.
+  const unavailable = Object.freeze({ busy: true });
 
-  async function evict(id, reason) {
+  async function evictBestEffort(id, reason) {
     const entry = entries.get(id);
     if (!entry) return false;
+    if (entry.state !== "active") {
+      if ((entry.state === "invalidating" || entry.state === "refreshing") && entry.operation) {
+        try { return await entry.operation; } catch { return false; }
+      }
+      return false;
+    }
     if (reason === "idle_timeout" && isBusy?.(entry.value)) {
       // A session executing a turn must not be torn down by the idle timer;
       // give it a fresh TTL window. Explicit dispose still wins.
@@ -59,10 +78,125 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
     return true;
   }
 
+  async function sync(id) {
+    const entry = entries.get(id);
+    if (!entry) return false;
+    if (entry.state === "syncing" && entry.operation) return entry.operation;
+    if (entry.state === "invalidating" && entry.operation) {
+      await entry.operation;
+      return false;
+    }
+    if (entry.state === "refreshing" && entry.operation) {
+      await entry.operation;
+      return false;
+    }
+    if (entry.state === "invalidation_failed") return false;
+
+    clearTimeout(entry.timer);
+    entry.state = "syncing";
+    const operation = (async () => {
+      try {
+        await onSync?.(entry.value);
+        if (entries.get(id) === entry) {
+          entry.state = "active";
+          entry.operation = null;
+          entry.lastActivityAt = now();
+          armTimer(id, entry);
+        }
+        return true;
+      } catch (error) {
+        // A provider that cannot prove its durable transcript is on disk must
+        // not become resumable. Keep the busy marker in place so the host can
+        // follow with destructive invalidation (or retry sync) honestly.
+        if (entries.get(id) === entry) {
+          entry.state = "sync_failed";
+          entry.operation = null;
+        }
+        throw error;
+      }
+    })();
+    entry.operation = operation;
+    return operation;
+  }
+
+  async function invalidate(id) {
+    const entry = entries.get(id);
+    if (!entry) return false;
+    if (entry.state === "invalidating" && entry.operation) return entry.operation;
+    if (entry.state === "syncing" && entry.operation) {
+      try { await entry.operation; } catch { /* invalidation supersedes sync */ }
+      return invalidate(id);
+    }
+    if (entry.state === "refreshing" && entry.operation) {
+      try { await entry.operation; } catch { /* invalidation supersedes refresh */ }
+      return invalidate(id);
+    }
+
+    clearTimeout(entry.timer);
+    entry.state = "invalidating";
+    const operation = (async () => {
+      try {
+        // Unlike ordinary eviction, destructive provider cleanup is the
+        // operation being promised to the caller. Run it before removal and
+        // let every error propagate; forgetting the entry first would report a
+        // lie and permit a poisoned durable transcript to cold-reopen.
+        await onEvict?.(entry.value, "invalidated");
+        if (entries.get(id) === entry) entries.delete(id);
+        return true;
+      } catch (error) {
+        if (entries.get(id) === entry) {
+          entry.state = "invalidation_failed";
+          entry.operation = null;
+        }
+        throw error;
+      }
+    })();
+    entry.operation = operation;
+    return operation;
+  }
+
+  async function refresh(id) {
+    const entry = entries.get(id);
+    if (!entry) return;
+    if (entry.state === "refreshing" && entry.operation) return entry.operation;
+    if (entry.state === "invalidating" && entry.operation) {
+      await entry.operation;
+      return;
+    }
+    if (entry.state === "syncing" && entry.operation) {
+      await entry.operation;
+      return refresh(id);
+    }
+    if (entry.state === "invalidation_failed") {
+      throw new Error(`Provider session ${String(id)} is awaiting destructive invalidation`);
+    }
+
+    clearTimeout(entry.timer);
+    entry.state = "refreshing";
+    const operation = (async () => {
+      try {
+        // A refresh is stronger than ordinary best-effort disposal: callers use
+        // its successful completion as proof that a subsequent resume cannot
+        // adopt stale process memory. Preserve provider-owned durable state,
+        // but propagate cleanup failures and retain the unavailable marker.
+        await onEvict?.(entry.value, "refreshed");
+        if (entries.get(id) === entry) entries.delete(id);
+      } catch (error) {
+        if (entries.get(id) === entry) {
+          entry.state = "refresh_failed";
+          entry.operation = null;
+        }
+        throw error;
+      }
+    })();
+    entry.operation = operation;
+    return operation;
+  }
+
   function armTimer(id, entry) {
     clearTimeout(entry.timer);
     entry.timer = setTimeout(() => {
-      void evict(id, "idle_timeout");
+      void evictBestEffort(id, "idle_timeout");
     }, entry.ttlMs);
     entry.timer.unref?.();
   }
@@ -71,8 +205,9 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
     get(id) {
       const entry = entries.get(id);
       if (!entry) return undefined;
+      if (entry.state !== "active") return unavailable;
       if (now() - entry.lastActivityAt > entry.ttlMs && !isBusy?.(entry.value)) {
-        void evict(id, "idle_timeout");
+        void evictBestEffort(id, "idle_timeout");
         return undefined;
       }
       return entry.value;
@@ -84,10 +219,22 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
      */
     set(id, value, { idleTimeoutMs: entryTtl } = {}) {
       const previous = entries.get(id);
+      // Never overwrite an in-flight/failed durability operation. The marker
+      // deliberately owns this id until sync recovers or invalidation removes
+      // it, preventing a cold reopen from winning an unlink race.
+      if (previous && previous.state !== "active") return false;
       if (previous) clearTimeout(previous.timer);
-      const entry = { value, lastActivityAt: now(), timer: null, ttlMs: normalizeTtl(entryTtl, defaultTtlMs) };
+      const entry = {
+        value,
+        lastActivityAt: now(),
+        timer: null,
+        ttlMs: normalizeTtl(entryTtl, defaultTtlMs),
+        state: "active",
+        operation: null,
+      };
       entries.set(id, entry);
       armTimer(id, entry);
+      return true;
     },
     /**
      * @param {any} id
@@ -96,6 +243,7 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
     touch(id, { idleTimeoutMs: entryTtl } = {}) {
       const entry = entries.get(id);
       if (!entry) return;
+      if (entry.state !== "active") return;
       if (entryTtl !== undefined) entry.ttlMs = normalizeTtl(entryTtl, entry.ttlMs);
       entry.lastActivityAt = now();
       armTimer(id, entry);
@@ -107,16 +255,26 @@ export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
     delete(id) {
       const entry = entries.get(id);
       if (!entry) return false;
+      if (entry.state !== "active") return false;
       entries.delete(id);
       clearTimeout(entry.timer);
       return true;
     },
     async dispose(id) {
-      return evict(id, "disposed");
+      return evictBestEffort(id, "disposed");
+    },
+    async sync(id) {
+      return sync(id);
+    },
+    async refresh(id) {
+      return refresh(id);
+    },
+    async invalidate(id) {
+      return invalidate(id);
     },
     async disposeAll() {
       const ids = [...entries.keys()];
-      for (const id of ids) await evict(id, "disposed");
+      for (const id of ids) await evictBestEffort(id, "disposed");
     },
     size() {
       return entries.size;
@@ -136,6 +294,49 @@ export async function disposeProviderSession(providerSessionId) {
   return disposed;
 }
 
+/**
+ * Flush provider-owned durable session state after a successful run and before
+ * the host commits canonical history. Providers without durable live state
+ * acknowledge the barrier immediately; provider sync errors propagate.
+ */
+export async function syncProviderSession(providerSessionId) {
+  if (typeof providerSessionId !== "string" || !providerSessionId.trim()) return false;
+  let synced = false;
+  for (const registry of allRegistries) {
+    if (await registry.sync(providerSessionId)) synced = true;
+  }
+  return synced;
+}
+
+/**
+ * Guarantee that no provider registry can reuse process-local state for this
+ * id. Durable provider transcripts are preserved so the next resume reopens
+ * them from disk. Absence is success; cleanup failure rejects.
+ */
+export async function refreshProviderSession(providerSessionId) {
+  if (typeof providerSessionId !== "string" || !providerSessionId.trim()) {
+    throw new TypeError("providerSessionId must be a non-empty string");
+  }
+  for (const registry of allRegistries) {
+    await registry.refresh(providerSessionId);
+  }
+}
+
+/**
+ * Irreversibly discard a provider session whose transcript is not represented
+ * by canonical host history. Unlike ordinary disposal, providers with durable
+ * session caches must remove the persisted transcript as well as the live
+ * registry entry.
+ */
+export async function invalidateProviderSession(providerSessionId) {
+  if (typeof providerSessionId !== "string" || !providerSessionId.trim()) return false;
+  let invalidated = false;
+  for (const registry of allRegistries) {
+    if (await registry.invalidate(providerSessionId)) invalidated = true;
+  }
+  return invalidated;
+}
+
 export async function disposeAllProviderSessions() {
   for (const registry of allRegistries) {
     await registry.disposeAll();

package/src/ai/types.js

@@ -322,7 +322,11 @@
  * The object `createRuntime`/`createRouterRuntime` return.
  * @property {(systemPrompt: string, options: RuntimeRunOptions) => Promise<RuntimeResult>} run
  * @property {(next?: AgentRuntimeToolOptions) => void} configureTools
- * @property {(providerSessionId: string) => Promise<boolean|void>} disposeSession
+ * @property {(providerSessionId: string) => Promise<boolean>} syncSession
+ * @property {(providerSessionId: string) => Promise<void>} refreshSession Guarantees the id has no reusable process-local handle; rejects on failure.
+ * @property {(providerSessionId: string, sessionsRoot: string) => Promise<void>} retireDurableSession Permanently deletes every durable transcript with the exact id; absence is success.
+ * @property {(providerSessionId: string) => Promise<boolean>} disposeSession
+ * @property {(providerSessionId: string) => Promise<boolean>} invalidateSession
  * @property {() => Promise<void>} disposeAllSessions
  */
 

package/src/runtime.js

@@ -30,9 +30,16 @@
 
 import { resolveRuntimeBridge } from "./ai/runtime/registry.js";
 import { createObserverHub } from "./ai/observer.js";
-import { disposeAllProviderSessions, disposeProviderSession } from "./ai/runtime/sessions.js";
+import {
+  disposeAllProviderSessions,
+  disposeProviderSession,
+  invalidateProviderSession,
+  refreshProviderSession,
+  syncProviderSession,
+} from "./ai/runtime/sessions.js";
 import { createToolContext, updateToolContext } from "./agent/tools/shared/tool-context.js";
 import { resolveRuntimeBrand } from "./runtime-brand.js";
+import { retireDurableNativeSession } from "./ai/providers/pi-native/session-lifecycle.js";
 
 /**
  * @typedef {import('./ai/types.js').AgentRuntimeHostOptions} AgentRuntimeHostOptions
@@ -175,9 +182,21 @@ export function createRuntime(host = {}) {
     configureTools(next = {}) {
       updateToolContext(toolContext, pickPresent(next, TOOL_RUNTIME_KEYS));
     },
+    async syncSession(providerSessionId) {
+      return syncProviderSession(providerSessionId);
+    },
+    async refreshSession(providerSessionId) {
+      return refreshProviderSession(providerSessionId);
+    },
+    async retireDurableSession(providerSessionId, sessionsRoot) {
+      return retireDurableNativeSession(providerSessionId, sessionsRoot);
+    },
     async disposeSession(providerSessionId) {
       return disposeProviderSession(providerSessionId);
     },
+    async invalidateSession(providerSessionId) {
+      return invalidateProviderSession(providerSessionId);
+    },
     async disposeAllSessions() {
       return disposeAllProviderSessions();
     },

package/types/ai/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./registry.js";
 export * from "./runtime/model-refs.js";
 export * from "./runtime/registry.js";
-export { createSessionRegistry, disposeAllProviderSessions, disposeProviderSession } from "./runtime/sessions.js";
+export { createSessionRegistry, disposeAllProviderSessions, disposeProviderSession, invalidateProviderSession, refreshProviderSession, syncProviderSession } from "./runtime/sessions.js";
 export { createMetricsObserver, createObserverHub } from "./observer.js";
 export { generatePiNativeResponse, piNativeRuntimeBridge } from "./providers/pi-native.js";
 export { CLAUDE_SDK_CATALOG_VERSION, createClaudeSdkDiscoveryIsolation, curatedClaudeSdkModels, discoverClaudeSdkModels, normalizeClaudeSdkCatalog, normalizeClaudeSdkModelId } from "./providers/claude-sdk-discovery.js";

package/types/ai/providers/pi-native/session-lifecycle.d.ts

@@ -1,4 +1,12 @@
 export function resolveDurableNativeSessionRepo(piSessionsRoot: any): any;
+/**
+ * Permanently retire every durable Pi transcript with this exact logical id.
+ * This is intentionally stronger than live-session invalidation: history
+ * rotation and retention can retire an epoch after its registry entry was
+ * already evicted or after a process restart. Absence is success; any cleanup
+ * or verification uncertainty rejects so canonical history remains reachable.
+ */
+export function retireDurableNativeSession(providerSessionId: any, piSessionsRoot: any): Promise<void>;
 /**
  * Resolve the session for this run: warm registry hit, durable cold reopen,
  * create-on-miss (durable resume only), or fresh create. Mutates runState

package/types/ai/runtime/sessions.d.ts

@@ -2,12 +2,14 @@
  * @param {object} [options]
  * @param {number} [options.idleTimeoutMs]
  * @param {(value: any, reason: string) => (void | Promise<void>)} [options.onEvict]
+ * @param {(value: any) => (void | Promise<void>)} [options.onSync]
  * @param {() => number} [options.now]
  * @param {(value: any) => boolean} [options.isBusy]
  */
-export function createSessionRegistry({ idleTimeoutMs, onEvict, now, isBusy }?: {
+export function createSessionRegistry({ idleTimeoutMs, onEvict, onSync, now, isBusy, }?: {
     idleTimeoutMs?: number;
     onEvict?: (value: any, reason: string) => (void | Promise<void>);
+    onSync?: (value: any) => (void | Promise<void>);
     now?: () => number;
     isBusy?: (value: any) => boolean;
 }): {
@@ -19,7 +21,7 @@ export function createSessionRegistry({ idleTimeoutMs, onEvict, now, isBusy }?:
      */
     set(id: any, value: any, { idleTimeoutMs: entryTtl }?: {
         idleTimeoutMs?: number;
-    }): void;
+    }): boolean;
     /**
      * @param {any} id
      * @param {{idleTimeoutMs?: number}} [options]
@@ -30,9 +32,31 @@ export function createSessionRegistry({ idleTimeoutMs, onEvict, now, isBusy }?:
     has(id: any): boolean;
     /** Remove without running onEvict — for callers that already cleaned up. */
     delete(id: any): boolean;
-    dispose(id: any): Promise<boolean>;
+    dispose(id: any): Promise<any>;
+    sync(id: any): Promise<any>;
+    refresh(id: any): Promise<any>;
+    invalidate(id: any): Promise<any>;
     disposeAll(): Promise<void>;
     size(): number;
 };
 export function disposeProviderSession(providerSessionId: any): Promise<boolean>;
+/**
+ * Flush provider-owned durable session state after a successful run and before
+ * the host commits canonical history. Providers without durable live state
+ * acknowledge the barrier immediately; provider sync errors propagate.
+ */
+export function syncProviderSession(providerSessionId: any): Promise<boolean>;
+/**
+ * Guarantee that no provider registry can reuse process-local state for this
+ * id. Durable provider transcripts are preserved so the next resume reopens
+ * them from disk. Absence is success; cleanup failure rejects.
+ */
+export function refreshProviderSession(providerSessionId: any): Promise<void>;
+/**
+ * Irreversibly discard a provider session whose transcript is not represented
+ * by canonical host history. Unlike ordinary disposal, providers with durable
+ * session caches must remove the persisted transcript as well as the live
+ * registry entry.
+ */
+export function invalidateProviderSession(providerSessionId: any): Promise<boolean>;
 export function disposeAllProviderSessions(): Promise<void>;

package/types/ai/types.d.ts

@@ -282,7 +282,11 @@
  * The object `createRuntime`/`createRouterRuntime` return.
  * @property {(systemPrompt: string, options: RuntimeRunOptions) => Promise<RuntimeResult>} run
  * @property {(next?: AgentRuntimeToolOptions) => void} configureTools
- * @property {(providerSessionId: string) => Promise<boolean|void>} disposeSession
+ * @property {(providerSessionId: string) => Promise<boolean>} syncSession
+ * @property {(providerSessionId: string) => Promise<void>} refreshSession Guarantees the id has no reusable process-local handle; rejects on failure.
+ * @property {(providerSessionId: string, sessionsRoot: string) => Promise<void>} retireDurableSession Permanently deletes every durable transcript with the exact id; absence is success.
+ * @property {(providerSessionId: string) => Promise<boolean>} disposeSession
+ * @property {(providerSessionId: string) => Promise<boolean>} invalidateSession
  * @property {() => Promise<void>} disposeAllSessions
  */
 export const PROVIDER_KIND_VALUES: string[];
@@ -770,6 +774,16 @@ export type AgentRuntimeToolOptions = {
 export type AgentRuntimeInstance = {
     run: (systemPrompt: string, options: RuntimeRunOptions) => Promise<RuntimeResult>;
     configureTools: (next?: AgentRuntimeToolOptions) => void;
-    disposeSession: (providerSessionId: string) => Promise<boolean | void>;
+    syncSession: (providerSessionId: string) => Promise<boolean>;
+    /**
+     * Guarantees the id has no reusable process-local handle; rejects on failure.
+     */
+    refreshSession: (providerSessionId: string) => Promise<void>;
+    /**
+     * Permanently deletes every durable transcript with the exact id; absence is success.
+     */
+    retireDurableSession: (providerSessionId: string, sessionsRoot: string) => Promise<void>;
+    disposeSession: (providerSessionId: string) => Promise<boolean>;
+    invalidateSession: (providerSessionId: string) => Promise<boolean>;
     disposeAllSessions: () => Promise<void>;
 };