@tangle-network/agent-runtime 0.138.0 → 0.139.0

package/dist/durable.d.ts

@@ -1,3 +1,4 @@
+import { x as NodeId } from "./types-D4arYjUl.js";
 //#region src/durable/chat-engine.d.ts
 /**
  * `handleChatTurn` is a framework-neutral chat-turn HTTP orchestrator.
@@ -130,5 +131,37 @@ declare function deriveExecutionId(input: {
   turnIndex: number;
 }): string;
 //#endregion
-export { type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type RunChatTurnInput, deriveExecutionId, handleChatTurn };
+//#region src/durable/supervision-discovery.d.ts
+interface DurableCoordinationStreamIdentity {
+  readonly runId: string;
+  /** Exact owner ids present in the side-log, sorted for deterministic display. */
+  readonly ownerIds: readonly string[];
+  /** Records written before owner-scoped coordination identities were introduced. */
+  readonly unscopedRecords: number;
+  readonly recordCount: number;
+}
+/**
+ * Identities discoverable from one `supervise({ runDir })` directory without
+ * already knowing the root node or coordination run id stored inside it.
+ */
+interface DurableSupervisionDiscovery {
+  readonly runDir: string;
+  readonly spawnJournalPath: string;
+  readonly coordinationLogPath: string;
+  readonly roots: readonly NodeId[];
+  readonly coordinationStreams: readonly DurableCoordinationStreamIdentity[];
+}
+/**
+ * Discover the stable identities recorded by Runtime's durable supervision
+ * files. This is the developer-facing first step before calling
+ * `FileSpawnJournal.loadTree(root)`, `loadSpawnForest(journal, root)`, or
+ * `FileCoordinationLog.load(runId, ownerId)`.
+ *
+ * Missing files produce empty collections. A malformed committed JSONL record
+ * still fails loud through the same parser used by the runtime; a torn final
+ * append is ignored because it was never acknowledged as committed.
+ */
+declare function discoverDurableSupervisionRun(runDir: string): Promise<DurableSupervisionDiscovery>;
+//#endregion
+export { type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, type DurableCoordinationStreamIdentity, type DurableSupervisionDiscovery, type RunChatTurnInput, deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn };
 //# sourceMappingURL=durable.d.ts.map

package/dist/durable.js

@@ -1,3 +1,5 @@
+import { t as parseCommittedJsonLines } from "./jsonl-file-DtxhdAkZ.js";
+import { resolve } from "node:path";
 //#region src/durable/chat-engine.ts
 const encoder = new TextEncoder();
 function encodeLine(event) {
@@ -119,6 +121,85 @@ function deriveExecutionId(input) {
 	return executionId;
 }
 //#endregion
-export { deriveExecutionId, handleChatTurn };
+//#region src/durable/supervision-discovery.ts
+/**
+* Discover the stable identities recorded by Runtime's durable supervision
+* files. This is the developer-facing first step before calling
+* `FileSpawnJournal.loadTree(root)`, `loadSpawnForest(journal, root)`, or
+* `FileCoordinationLog.load(runId, ownerId)`.
+*
+* Missing files produce empty collections. A malformed committed JSONL record
+* still fails loud through the same parser used by the runtime; a torn final
+* append is ignored because it was never acknowledged as committed.
+*/
+async function discoverDurableSupervisionRun(runDir) {
+	if (typeof runDir !== "string" || runDir.trim().length === 0) throw new TypeError("discoverDurableSupervisionRun: runDir must be a non-empty string");
+	const canonicalRunDir = resolve(runDir);
+	const spawnJournalPath = `${canonicalRunDir}/spawn-journal.jsonl`;
+	const coordinationLogPath = `${canonicalRunDir}/coordination-log.jsonl`;
+	const [spawnText, coordinationText] = await Promise.all([readOptionalText(spawnJournalPath), readOptionalText(coordinationLogPath)]);
+	const allRoots = /* @__PURE__ */ new Set();
+	const nestedRoots = /* @__PURE__ */ new Set();
+	if (spawnText !== void 0) for (const record of parseCommittedJsonLines(spawnText, spawnJournalPath)) {
+		if (record.kind === "begin") {
+			if (typeof record.root !== "string" || record.root.length === 0) throw new Error(`${spawnJournalPath}: begin record has no non-empty string root identity`);
+			allRoots.add(record.root);
+			continue;
+		}
+		if (record.kind !== "event") continue;
+		const event = record.event;
+		if (!isRecord(event) || event.kind !== "spawned") continue;
+		if (!Object.hasOwn(event, "ownedTreeRoot")) continue;
+		if (typeof event.ownedTreeRoot !== "string" || event.ownedTreeRoot.length === 0) throw new Error(`${spawnJournalPath}: spawned event ownedTreeRoot must be a non-empty string when present`);
+		nestedRoots.add(event.ownedTreeRoot);
+	}
+	const streams = /* @__PURE__ */ new Map();
+	if (coordinationText !== void 0) for (const record of parseCommittedJsonLines(coordinationText, coordinationLogPath)) {
+		if (typeof record.runId !== "string" || record.runId.length === 0) throw new Error(`${coordinationLogPath}: record has no non-empty string runId identity`);
+		const stream = streams.get(record.runId) ?? {
+			owners: /* @__PURE__ */ new Set(),
+			unscopedRecords: 0,
+			recordCount: 0
+		};
+		stream.recordCount += 1;
+		if (record.ownerId === void 0) stream.unscopedRecords += 1;
+		else if (typeof record.ownerId === "string" && record.ownerId.length > 0) stream.owners.add(record.ownerId);
+		else throw new Error(`${coordinationLogPath}: ownerId must be a non-empty string when present`);
+		streams.set(record.runId, stream);
+	}
+	const coordinationStreams = [...streams.entries()].sort(([left], [right]) => compareText(left, right)).map(([runId, stream]) => Object.freeze({
+		runId,
+		ownerIds: Object.freeze([...stream.owners].sort(compareText)),
+		unscopedRecords: stream.unscopedRecords,
+		recordCount: stream.recordCount
+	}));
+	return Object.freeze({
+		runDir: canonicalRunDir,
+		spawnJournalPath,
+		coordinationLogPath,
+		roots: Object.freeze([...allRoots].filter((root) => !nestedRoots.has(root)).sort(compareText)),
+		coordinationStreams: Object.freeze(coordinationStreams)
+	});
+}
+async function readOptionalText(path) {
+	const fs = await import("node:fs/promises");
+	try {
+		return await fs.readFile(path, "utf8");
+	} catch (error) {
+		if (isNoEntError(error)) return void 0;
+		throw error;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function compareText(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+function isNoEntError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+export { deriveExecutionId, discoverDurableSupervisionRun, handleChatTurn };
 
 //# sourceMappingURL=durable.js.map

package/dist/durable.js.map

@@ -1 +1 @@
-{"version":3,"file":"durable.js","names":[],"sources":["../src/durable/chat-engine.ts","../src/durable/execution-handle.ts"],"sourcesContent":["/**\n * `handleChatTurn` is a framework-neutral chat-turn HTTP orchestrator.\n * Owns the NDJSON `ChatStreamEvent` line protocol, the `session.run.*`\n * lifecycle vocabulary, and the persist / post-process / trace-flush\n * hook order. Returns a `ReadableStream` body the product hands to its\n * platform `Response`.\n *\n * Sandbox owns long-running execution, reconnect, and replay.\n * The producer this engine wraps already speaks that protocol; this\n * engine frames the events and orders product callbacks.\n *\n * Hooks (`ChatTurnHooks`):\n *   - `produce`: build the backend event stream\n *   - `persistAssistantMessage`: write the assistant turn to the product DB\n *   - `onTurnComplete?`: post-process proposals, citations, and similar work\n *   - `onEvent?`: send each event to another consumer\n *   - `transformFinalText?`: transform text before persistence\n *   - `traceFlush?`: let `waitUntil` keep the worker alive for export\n *\n * Framework neutrality: takes already-resolved values (`identity` tuple,\n * a `waitUntil`), never a `Request` or a `Context`. The product's thin\n * route adapter does auth + parse + access-control, then calls\n * `handleChatTurn(...)` and returns `result.body` as its platform `Response`.\n */\n\n/** The NDJSON line protocol every product chat client already speaks. */\nexport interface ChatStreamEvent {\n  type: string\n  data?: Record<string, unknown>\n}\n\n/** Identity of a chat turn. `tenantId` is the workspace id for workspace-\n *  scoped products and the user id for session-scoped products. */\nexport interface ChatTurnIdentity {\n  tenantId: string\n  /** Thread / session id. */\n  sessionId: string\n  userId: string\n  /** Monotonic 0-based turn index within the session. */\n  turnIndex: number\n}\n\n/** The live side of a turn returned by the product's `produce` hook. */\nexport interface ChatTurnProducer<TEvent extends ChatStreamEvent = ChatStreamEvent> {\n  /** The turn's event stream. Forwarded verbatim to the caller. */\n  stream: AsyncGenerator<TEvent, void, unknown>\n  /** The turn's final assistant text. Read once, after `stream` drains. */\n  finalText(): string\n}\n\n/** Product callbacks invoked while one chat turn runs. */\nexport interface ChatTurnHooks {\n  /** Build the backend stream. The engine forwards events verbatim and\n   *  reads `finalText()` once the stream drains. */\n  produce(): ChatTurnProducer\n  /** Persist the assistant message to the product's own store. Called\n   *  once, after drain, with the assembled (transform-applied) text. */\n  persistAssistantMessage(input: { identity: ChatTurnIdentity; finalText: string }): Promise<void>\n  /** Optional post-processing for proposals, citations, or credit metering.\n   *  Errors are logged without failing a turn that already streamed. */\n  onTurnComplete?(input: { identity: ChatTurnIdentity; finalText: string }): Promise<void>\n  /** Optional per-event side channel, such as a Durable Object broadcast.\n   *  Runs for every emitted event, including the lifecycle envelope.\n   *  Errors are logged without breaking the chat stream. */\n  onEvent?(event: ChatStreamEvent): void | Promise<void>\n  /** Optional pre-persist transform of the final text (e.g. PII\n   *  redaction). Affects only what is persisted; the live stream is\n   *  never altered. */\n  transformFinalText?(text: string): string | Promise<string>\n  /** Optional trace flush. Handed to `waitUntil` so the worker stays alive\n   *  until export completes. */\n  traceFlush?(): Promise<void>\n}\n\n/** Inputs for one streamed product chat turn. */\nexport interface RunChatTurnInput {\n  identity: ChatTurnIdentity\n  hooks: ChatTurnHooks\n  /** Worker liveness hook. When omitted, trace flush is awaited inline\n   *  before the stream closes. */\n  waitUntil?: (p: Promise<unknown>) => void\n  /** Structured logger for swallowed hook errors. Defaults to\n   *  `console.error` so failures surface without product wiring. */\n  log?: (message: string, meta?: Record<string, unknown>) => void\n}\n\n/** HTTP response values returned for one chat turn. */\nexport interface ChatTurnResult {\n  /** NDJSON body to return as the platform `Response` body. */\n  body: ReadableStream<Uint8Array>\n  /** Content type for the response. */\n  contentType: 'application/x-ndjson'\n}\n\nconst encoder = new TextEncoder()\n\nfunction encodeLine(event: ChatStreamEvent): Uint8Array {\n  return encoder.encode(`${JSON.stringify(event)}\\n`)\n}\n\nfunction defaultLog(message: string, meta?: Record<string, unknown>): void {\n  if (meta) console.error(message, meta)\n  else console.error(message)\n}\n\n/**\n * Run one chat turn. Returns immediately with a `ReadableStream` body;\n * execution starts while the stream is constructed. Backend\n * failures surface as `error` + `session.run.failed` events.\n */\nexport function handleChatTurn(input: RunChatTurnInput): ChatTurnResult {\n  const log = input.log ?? defaultLog\n  const { identity, hooks } = input\n\n  const body = new ReadableStream<Uint8Array>({\n    start: async (controller) => {\n      const emit = async (event: ChatStreamEvent): Promise<void> => {\n        controller.enqueue(encodeLine(event))\n        if (hooks.onEvent) {\n          try {\n            await hooks.onEvent(event)\n          } catch (err) {\n            log('[chat-engine] onEvent hook threw', {\n              error: err instanceof Error ? err.message : String(err),\n            })\n          }\n        }\n      }\n\n      try {\n        await emit({\n          type: 'session.run.started',\n          data: {\n            sessionId: identity.sessionId,\n            tenantId: identity.tenantId,\n            turnIndex: identity.turnIndex,\n          },\n        })\n\n        const producer = hooks.produce()\n        for await (const event of producer.stream) {\n          await emit(event)\n        }\n        const rawFinal = producer.finalText()\n        const finalText = hooks.transformFinalText\n          ? await hooks.transformFinalText(rawFinal)\n          : rawFinal\n\n        await hooks.persistAssistantMessage({ identity, finalText })\n        if (hooks.onTurnComplete) {\n          try {\n            await hooks.onTurnComplete({ identity, finalText })\n          } catch (err) {\n            log('[chat-engine] onTurnComplete threw', {\n              error: err instanceof Error ? err.message : String(err),\n            })\n          }\n        }\n\n        await emit({\n          type: 'session.run.completed',\n          data: { sessionId: identity.sessionId },\n        })\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err)\n        log('[chat-engine] turn failed', { error: message })\n        await emit({ type: 'error', data: { message } })\n        await emit({\n          type: 'session.run.failed',\n          data: { sessionId: identity.sessionId, message },\n        })\n      } finally {\n        if (hooks.traceFlush) {\n          const flush = hooks.traceFlush().catch((err) =>\n            log('[chat-engine] traceFlush threw', {\n              error: err instanceof Error ? err.message : String(err),\n            }),\n          )\n          if (input.waitUntil) input.waitUntil(flush)\n          else await flush\n        }\n        controller.close()\n      }\n    },\n  })\n\n  return { body, contentType: 'application/x-ndjson' }\n}\n","/**\n * Derive a stable execution id from the run identity.\n * The same `(projectId, sessionId, turnIndex)` tuple yields the same id.\n *\n * Use the result as both `PromptOptions.executionId` and\n * `PromptOptions.turnId` on the first dispatch.\n * The execution id addresses the server-side execution for reconnect and\n * replay; the turn id makes a repeated dispatch idempotent.\n * An execution id alone does not make a repeated POST idempotent.\n *\n * Format is readable, not hashed: operators grepping orchestrator logs\n * for `gtm-agent:thread-abc:3` find the run without translating an\n * opaque id. Components are URL-encoded so delimiters inside caller ids\n * cannot collapse distinct tuples. The final id is limited to the\n * orchestrator replay route's 256-byte maximum. Execution ids are not a\n * secrecy boundary.\n *\n * Wire integration:\n *   - Initial dispatch: pass the result as `executionId` and `turnId`.\n *   - Stream replay: pass it as `executionId` with `lastEventId`.\n *\n * @throws `TypeError` when either string id is blank.\n * @throws `RangeError` when `turnIndex` is invalid or the result exceeds 256 bytes.\n */\nexport function deriveExecutionId(input: {\n  projectId: string\n  sessionId: string\n  turnIndex: number\n}): string {\n  if (input.projectId.trim().length === 0) {\n    throw new TypeError('projectId must be a non-empty string')\n  }\n  if (input.sessionId.trim().length === 0) {\n    throw new TypeError('sessionId must be a non-empty string')\n  }\n  if (!Number.isSafeInteger(input.turnIndex) || input.turnIndex < 0) {\n    throw new RangeError('turnIndex must be a non-negative safe integer')\n  }\n\n  const executionId = [\n    encodeURIComponent(input.projectId),\n    encodeURIComponent(input.sessionId),\n    String(input.turnIndex),\n  ].join(':')\n  if (executionId.length > 256) {\n    throw new RangeError('derived execution id must not exceed 256 bytes')\n  }\n  return executionId\n}\n"],"mappings":";AA8FA,MAAM,UAAU,IAAI,YAAY;AAEhC,SAAS,WAAW,OAAoC;CACtD,OAAO,QAAQ,OAAO,GAAG,KAAK,UAAU,KAAK,EAAE,GAAG;AACpD;AAEA,SAAS,WAAW,SAAiB,MAAsC;CACzE,IAAI,MAAM,QAAQ,MAAM,SAAS,IAAI;MAChC,QAAQ,MAAM,OAAO;AAC5B;;;;;;AAOA,SAAgB,eAAe,OAAyC;CACtE,MAAM,MAAM,MAAM,OAAO;CACzB,MAAM,EAAE,UAAU,UAAU;CA0E5B,OAAO;EAAE,MAAA,IAxEQ,eAA2B,EAC1C,OAAO,OAAO,eAAe;GAC3B,MAAM,OAAO,OAAO,UAA0C;IAC5D,WAAW,QAAQ,WAAW,KAAK,CAAC;IACpC,IAAI,MAAM,SACR,IAAI;KACF,MAAM,MAAM,QAAQ,KAAK;IAC3B,SAAS,KAAK;KACZ,IAAI,oCAAoC,EACtC,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EACxD,CAAC;IACH;GAEJ;GAEA,IAAI;IACF,MAAM,KAAK;KACT,MAAM;KACN,MAAM;MACJ,WAAW,SAAS;MACpB,UAAU,SAAS;MACnB,WAAW,SAAS;KACtB;IACF,CAAC;IAED,MAAM,WAAW,MAAM,QAAQ;IAC/B,WAAW,MAAM,SAAS,SAAS,QACjC,MAAM,KAAK,KAAK;IAElB,MAAM,WAAW,SAAS,UAAU;IACpC,MAAM,YAAY,MAAM,qBACpB,MAAM,MAAM,mBAAmB,QAAQ,IACvC;IAEJ,MAAM,MAAM,wBAAwB;KAAE;KAAU;IAAU,CAAC;IAC3D,IAAI,MAAM,gBACR,IAAI;KACF,MAAM,MAAM,eAAe;MAAE;MAAU;KAAU,CAAC;IACpD,SAAS,KAAK;KACZ,IAAI,sCAAsC,EACxC,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EACxD,CAAC;IACH;IAGF,MAAM,KAAK;KACT,MAAM;KACN,MAAM,EAAE,WAAW,SAAS,UAAU;IACxC,CAAC;GACH,SAAS,KAAK;IACZ,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;IAC/D,IAAI,6BAA6B,EAAE,OAAO,QAAQ,CAAC;IACnD,MAAM,KAAK;KAAE,MAAM;KAAS,MAAM,EAAE,QAAQ;IAAE,CAAC;IAC/C,MAAM,KAAK;KACT,MAAM;KACN,MAAM;MAAE,WAAW,SAAS;MAAW;KAAQ;IACjD,CAAC;GACH,UAAU;IACR,IAAI,MAAM,YAAY;KACpB,MAAM,QAAQ,MAAM,WAAW,CAAC,CAAC,OAAO,QACtC,IAAI,kCAAkC,EACpC,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EACxD,CAAC,CACH;KACA,IAAI,MAAM,WAAW,MAAM,UAAU,KAAK;UACrC,MAAM;IACb;IACA,WAAW,MAAM;GACnB;EACF,EACF,CAEY;EAAG,aAAa;CAAuB;AACrD;;;;;;;;;;;;;;;;;;;;;;;;;;;ACnKA,SAAgB,kBAAkB,OAIvB;CACT,IAAI,MAAM,UAAU,KAAK,CAAC,CAAC,WAAW,GACpC,MAAM,IAAI,UAAU,sCAAsC;CAE5D,IAAI,MAAM,UAAU,KAAK,CAAC,CAAC,WAAW,GACpC,MAAM,IAAI,UAAU,sCAAsC;CAE5D,IAAI,CAAC,OAAO,cAAc,MAAM,SAAS,KAAK,MAAM,YAAY,GAC9D,MAAM,IAAI,WAAW,+CAA+C;CAGtE,MAAM,cAAc;EAClB,mBAAmB,MAAM,SAAS;EAClC,mBAAmB,MAAM,SAAS;EAClC,OAAO,MAAM,SAAS;CACxB,CAAC,CAAC,KAAK,GAAG;CACV,IAAI,YAAY,SAAS,KACvB,MAAM,IAAI,WAAW,gDAAgD;CAEvE,OAAO;AACT"}
+{"version":3,"file":"durable.js","names":[],"sources":["../src/durable/chat-engine.ts","../src/durable/execution-handle.ts","../src/durable/supervision-discovery.ts"],"sourcesContent":["/**\n * `handleChatTurn` is a framework-neutral chat-turn HTTP orchestrator.\n * Owns the NDJSON `ChatStreamEvent` line protocol, the `session.run.*`\n * lifecycle vocabulary, and the persist / post-process / trace-flush\n * hook order. Returns a `ReadableStream` body the product hands to its\n * platform `Response`.\n *\n * Sandbox owns long-running execution, reconnect, and replay.\n * The producer this engine wraps already speaks that protocol; this\n * engine frames the events and orders product callbacks.\n *\n * Hooks (`ChatTurnHooks`):\n *   - `produce`: build the backend event stream\n *   - `persistAssistantMessage`: write the assistant turn to the product DB\n *   - `onTurnComplete?`: post-process proposals, citations, and similar work\n *   - `onEvent?`: send each event to another consumer\n *   - `transformFinalText?`: transform text before persistence\n *   - `traceFlush?`: let `waitUntil` keep the worker alive for export\n *\n * Framework neutrality: takes already-resolved values (`identity` tuple,\n * a `waitUntil`), never a `Request` or a `Context`. The product's thin\n * route adapter does auth + parse + access-control, then calls\n * `handleChatTurn(...)` and returns `result.body` as its platform `Response`.\n */\n\n/** The NDJSON line protocol every product chat client already speaks. */\nexport interface ChatStreamEvent {\n  type: string\n  data?: Record<string, unknown>\n}\n\n/** Identity of a chat turn. `tenantId` is the workspace id for workspace-\n *  scoped products and the user id for session-scoped products. */\nexport interface ChatTurnIdentity {\n  tenantId: string\n  /** Thread / session id. */\n  sessionId: string\n  userId: string\n  /** Monotonic 0-based turn index within the session. */\n  turnIndex: number\n}\n\n/** The live side of a turn returned by the product's `produce` hook. */\nexport interface ChatTurnProducer<TEvent extends ChatStreamEvent = ChatStreamEvent> {\n  /** The turn's event stream. Forwarded verbatim to the caller. */\n  stream: AsyncGenerator<TEvent, void, unknown>\n  /** The turn's final assistant text. Read once, after `stream` drains. */\n  finalText(): string\n}\n\n/** Product callbacks invoked while one chat turn runs. */\nexport interface ChatTurnHooks {\n  /** Build the backend stream. The engine forwards events verbatim and\n   *  reads `finalText()` once the stream drains. */\n  produce(): ChatTurnProducer\n  /** Persist the assistant message to the product's own store. Called\n   *  once, after drain, with the assembled (transform-applied) text. */\n  persistAssistantMessage(input: { identity: ChatTurnIdentity; finalText: string }): Promise<void>\n  /** Optional post-processing for proposals, citations, or credit metering.\n   *  Errors are logged without failing a turn that already streamed. */\n  onTurnComplete?(input: { identity: ChatTurnIdentity; finalText: string }): Promise<void>\n  /** Optional per-event side channel, such as a Durable Object broadcast.\n   *  Runs for every emitted event, including the lifecycle envelope.\n   *  Errors are logged without breaking the chat stream. */\n  onEvent?(event: ChatStreamEvent): void | Promise<void>\n  /** Optional pre-persist transform of the final text (e.g. PII\n   *  redaction). Affects only what is persisted; the live stream is\n   *  never altered. */\n  transformFinalText?(text: string): string | Promise<string>\n  /** Optional trace flush. Handed to `waitUntil` so the worker stays alive\n   *  until export completes. */\n  traceFlush?(): Promise<void>\n}\n\n/** Inputs for one streamed product chat turn. */\nexport interface RunChatTurnInput {\n  identity: ChatTurnIdentity\n  hooks: ChatTurnHooks\n  /** Worker liveness hook. When omitted, trace flush is awaited inline\n   *  before the stream closes. */\n  waitUntil?: (p: Promise<unknown>) => void\n  /** Structured logger for swallowed hook errors. Defaults to\n   *  `console.error` so failures surface without product wiring. */\n  log?: (message: string, meta?: Record<string, unknown>) => void\n}\n\n/** HTTP response values returned for one chat turn. */\nexport interface ChatTurnResult {\n  /** NDJSON body to return as the platform `Response` body. */\n  body: ReadableStream<Uint8Array>\n  /** Content type for the response. */\n  contentType: 'application/x-ndjson'\n}\n\nconst encoder = new TextEncoder()\n\nfunction encodeLine(event: ChatStreamEvent): Uint8Array {\n  return encoder.encode(`${JSON.stringify(event)}\\n`)\n}\n\nfunction defaultLog(message: string, meta?: Record<string, unknown>): void {\n  if (meta) console.error(message, meta)\n  else console.error(message)\n}\n\n/**\n * Run one chat turn. Returns immediately with a `ReadableStream` body;\n * execution starts while the stream is constructed. Backend\n * failures surface as `error` + `session.run.failed` events.\n */\nexport function handleChatTurn(input: RunChatTurnInput): ChatTurnResult {\n  const log = input.log ?? defaultLog\n  const { identity, hooks } = input\n\n  const body = new ReadableStream<Uint8Array>({\n    start: async (controller) => {\n      const emit = async (event: ChatStreamEvent): Promise<void> => {\n        controller.enqueue(encodeLine(event))\n        if (hooks.onEvent) {\n          try {\n            await hooks.onEvent(event)\n          } catch (err) {\n            log('[chat-engine] onEvent hook threw', {\n              error: err instanceof Error ? err.message : String(err),\n            })\n          }\n        }\n      }\n\n      try {\n        await emit({\n          type: 'session.run.started',\n          data: {\n            sessionId: identity.sessionId,\n            tenantId: identity.tenantId,\n            turnIndex: identity.turnIndex,\n          },\n        })\n\n        const producer = hooks.produce()\n        for await (const event of producer.stream) {\n          await emit(event)\n        }\n        const rawFinal = producer.finalText()\n        const finalText = hooks.transformFinalText\n          ? await hooks.transformFinalText(rawFinal)\n          : rawFinal\n\n        await hooks.persistAssistantMessage({ identity, finalText })\n        if (hooks.onTurnComplete) {\n          try {\n            await hooks.onTurnComplete({ identity, finalText })\n          } catch (err) {\n            log('[chat-engine] onTurnComplete threw', {\n              error: err instanceof Error ? err.message : String(err),\n            })\n          }\n        }\n\n        await emit({\n          type: 'session.run.completed',\n          data: { sessionId: identity.sessionId },\n        })\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err)\n        log('[chat-engine] turn failed', { error: message })\n        await emit({ type: 'error', data: { message } })\n        await emit({\n          type: 'session.run.failed',\n          data: { sessionId: identity.sessionId, message },\n        })\n      } finally {\n        if (hooks.traceFlush) {\n          const flush = hooks.traceFlush().catch((err) =>\n            log('[chat-engine] traceFlush threw', {\n              error: err instanceof Error ? err.message : String(err),\n            }),\n          )\n          if (input.waitUntil) input.waitUntil(flush)\n          else await flush\n        }\n        controller.close()\n      }\n    },\n  })\n\n  return { body, contentType: 'application/x-ndjson' }\n}\n","/**\n * Derive a stable execution id from the run identity.\n * The same `(projectId, sessionId, turnIndex)` tuple yields the same id.\n *\n * Use the result as both `PromptOptions.executionId` and\n * `PromptOptions.turnId` on the first dispatch.\n * The execution id addresses the server-side execution for reconnect and\n * replay; the turn id makes a repeated dispatch idempotent.\n * An execution id alone does not make a repeated POST idempotent.\n *\n * Format is readable, not hashed: operators grepping orchestrator logs\n * for `gtm-agent:thread-abc:3` find the run without translating an\n * opaque id. Components are URL-encoded so delimiters inside caller ids\n * cannot collapse distinct tuples. The final id is limited to the\n * orchestrator replay route's 256-byte maximum. Execution ids are not a\n * secrecy boundary.\n *\n * Wire integration:\n *   - Initial dispatch: pass the result as `executionId` and `turnId`.\n *   - Stream replay: pass it as `executionId` with `lastEventId`.\n *\n * @throws `TypeError` when either string id is blank.\n * @throws `RangeError` when `turnIndex` is invalid or the result exceeds 256 bytes.\n */\nexport function deriveExecutionId(input: {\n  projectId: string\n  sessionId: string\n  turnIndex: number\n}): string {\n  if (input.projectId.trim().length === 0) {\n    throw new TypeError('projectId must be a non-empty string')\n  }\n  if (input.sessionId.trim().length === 0) {\n    throw new TypeError('sessionId must be a non-empty string')\n  }\n  if (!Number.isSafeInteger(input.turnIndex) || input.turnIndex < 0) {\n    throw new RangeError('turnIndex must be a non-negative safe integer')\n  }\n\n  const executionId = [\n    encodeURIComponent(input.projectId),\n    encodeURIComponent(input.sessionId),\n    String(input.turnIndex),\n  ].join(':')\n  if (executionId.length > 256) {\n    throw new RangeError('derived execution id must not exceed 256 bytes')\n  }\n  return executionId\n}\n","import { resolve } from 'node:path'\nimport type { NodeId } from '../runtime/supervise/types'\nimport { parseCommittedJsonLines } from './jsonl-file'\n\nexport interface DurableCoordinationStreamIdentity {\n  readonly runId: string\n  /** Exact owner ids present in the side-log, sorted for deterministic display. */\n  readonly ownerIds: readonly string[]\n  /** Records written before owner-scoped coordination identities were introduced. */\n  readonly unscopedRecords: number\n  readonly recordCount: number\n}\n\n/**\n * Identities discoverable from one `supervise({ runDir })` directory without\n * already knowing the root node or coordination run id stored inside it.\n */\nexport interface DurableSupervisionDiscovery {\n  readonly runDir: string\n  readonly spawnJournalPath: string\n  readonly coordinationLogPath: string\n  readonly roots: readonly NodeId[]\n  readonly coordinationStreams: readonly DurableCoordinationStreamIdentity[]\n}\n\ntype SpawnJournalIdentityRecord = {\n  readonly kind?: unknown\n  readonly root?: unknown\n  readonly event?: unknown\n}\n\ntype CoordinationIdentityRecord = {\n  readonly runId?: unknown\n  readonly ownerId?: unknown\n}\n\n/**\n * Discover the stable identities recorded by Runtime's durable supervision\n * files. This is the developer-facing first step before calling\n * `FileSpawnJournal.loadTree(root)`, `loadSpawnForest(journal, root)`, or\n * `FileCoordinationLog.load(runId, ownerId)`.\n *\n * Missing files produce empty collections. A malformed committed JSONL record\n * still fails loud through the same parser used by the runtime; a torn final\n * append is ignored because it was never acknowledged as committed.\n */\nexport async function discoverDurableSupervisionRun(\n  runDir: string,\n): Promise<DurableSupervisionDiscovery> {\n  if (typeof runDir !== 'string' || runDir.trim().length === 0) {\n    throw new TypeError('discoverDurableSupervisionRun: runDir must be a non-empty string')\n  }\n\n  const canonicalRunDir = resolve(runDir)\n  const spawnJournalPath = `${canonicalRunDir}/spawn-journal.jsonl`\n  const coordinationLogPath = `${canonicalRunDir}/coordination-log.jsonl`\n  const [spawnText, coordinationText] = await Promise.all([\n    readOptionalText(spawnJournalPath),\n    readOptionalText(coordinationLogPath),\n  ])\n\n  const allRoots = new Set<NodeId>()\n  const nestedRoots = new Set<NodeId>()\n  if (spawnText !== undefined) {\n    for (const record of parseCommittedJsonLines<SpawnJournalIdentityRecord>(\n      spawnText,\n      spawnJournalPath,\n    )) {\n      if (record.kind === 'begin') {\n        if (typeof record.root !== 'string' || record.root.length === 0) {\n          throw new Error(`${spawnJournalPath}: begin record has no non-empty string root identity`)\n        }\n        allRoots.add(record.root as NodeId)\n        continue\n      }\n      if (record.kind !== 'event') continue\n      const event = record.event\n      if (!isRecord(event) || event.kind !== 'spawned') continue\n      if (!Object.hasOwn(event, 'ownedTreeRoot')) continue\n      if (typeof event.ownedTreeRoot !== 'string' || event.ownedTreeRoot.length === 0) {\n        throw new Error(\n          `${spawnJournalPath}: spawned event ownedTreeRoot must be a non-empty string when present`,\n        )\n      }\n      nestedRoots.add(event.ownedTreeRoot as NodeId)\n    }\n  }\n\n  const streams = new Map<\n    string,\n    { owners: Set<string>; unscopedRecords: number; recordCount: number }\n  >()\n  if (coordinationText !== undefined) {\n    for (const record of parseCommittedJsonLines<CoordinationIdentityRecord>(\n      coordinationText,\n      coordinationLogPath,\n    )) {\n      if (typeof record.runId !== 'string' || record.runId.length === 0) {\n        throw new Error(`${coordinationLogPath}: record has no non-empty string runId identity`)\n      }\n      const stream = streams.get(record.runId) ?? {\n        owners: new Set<string>(),\n        unscopedRecords: 0,\n        recordCount: 0,\n      }\n      stream.recordCount += 1\n      if (record.ownerId === undefined) {\n        stream.unscopedRecords += 1\n      } else if (typeof record.ownerId === 'string' && record.ownerId.length > 0) {\n        stream.owners.add(record.ownerId)\n      } else {\n        throw new Error(`${coordinationLogPath}: ownerId must be a non-empty string when present`)\n      }\n      streams.set(record.runId, stream)\n    }\n  }\n\n  const coordinationStreams = [...streams.entries()]\n    .sort(([left], [right]) => compareText(left, right))\n    .map(([runId, stream]) =>\n      Object.freeze({\n        runId,\n        ownerIds: Object.freeze([...stream.owners].sort(compareText)),\n        unscopedRecords: stream.unscopedRecords,\n        recordCount: stream.recordCount,\n      }),\n    )\n\n  return Object.freeze({\n    runDir: canonicalRunDir,\n    spawnJournalPath,\n    coordinationLogPath,\n    roots: Object.freeze([...allRoots].filter((root) => !nestedRoots.has(root)).sort(compareText)),\n    coordinationStreams: Object.freeze(coordinationStreams),\n  })\n}\n\nasync function readOptionalText(path: string): Promise<string | undefined> {\n  const fs = await import('node:fs/promises')\n  try {\n    return await fs.readFile(path, 'utf8')\n  } catch (error) {\n    if (isNoEntError(error)) return undefined\n    throw error\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nfunction compareText(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0\n}\n\nfunction isNoEntError(error: unknown): boolean {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    'code' in error &&\n    (error as { code: unknown }).code === 'ENOENT'\n  )\n}\n"],"mappings":"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"}

package/dist/{environment-provider-CLNVqp6H.js → environment-provider-BAO8wt1_.js}

@@ -1,5 +1,7 @@
+import { C as sameControlCoordinates, E as promptOptionsFromAgentTurnInput, T as promptFromAgentTurnInput, d as awaitAbortable } from "./retained-run-binding-Dp2e8xne.js";
 import { _ as zeroTokenUsage } from "./util-C1bv6yog.js";
-import { harnessSystemPromptIntents } from "@tangle-network/agent-interface";
+import { t as canonicalStreamEventFromSandboxEvent } from "./sandbox-events-DPmXlcKw.js";
+import { AgentExactRunControlRefSchema, AgentRunCancellationRequestSchema, harnessSystemPromptIntents } from "@tangle-network/agent-interface";
 import { isDeepStrictEqual } from "node:util";
 //#region src/runtime/tangle-sandbox-exact-process-provider.ts
 const exactProcessProviderMarker = "agent-runtime.exact-process-provider";
@@ -458,7 +460,7 @@ function sandboxClientAsProvider(client, options = {}) {
 		...options.validateProfile ? { validateProfile: options.validateProfile } : {},
 		async create(input) {
 			const createOptions = options.mapCreateInput?.(input) ?? await sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode", options.resolveProfile);
-			return sandboxInstanceAsEnvironment(await client.create(createOptions), providerName, client);
+			return sandboxInstanceAsEnvironment(await client.create(createOptions, input.signal === void 0 ? void 0 : { signal: input.signal }), providerName, client);
 		},
 		...hasGet(client) ? { async get(id) {
 			const box = await client.get(id);
@@ -660,7 +662,12 @@ function environmentAsSandboxInstance(environment, options) {
 				if (cancellationStarted || !input.sessionId || !environment.session) return;
 				cancellationStarted = true;
 				try {
-					cancellation = environment.session(input.sessionId).cancel().catch((error) => {
+					const session = environment.session(input.sessionId, {
+						...input.controlRef === void 0 ? {} : { controlRef: input.controlRef },
+						...input.signal === void 0 ? {} : { signal: input.signal }
+					});
+					assertScopedSessionForInput(session, input);
+					cancellation = session.cancel().catch((error) => {
 						cancellationFailed = true;
 						cancellationError = error;
 					});
@@ -725,8 +732,8 @@ function environmentAsSandboxInstance(environment, options) {
 			if (!session) throw new ValidationError("providerAsSandboxClient: dispatch returned no session");
 			return sandboxDispatchResultFromSessionRef(session);
 		} } : {},
-		...environment.session ? { session(id) {
-			return sandboxSessionFromAgentSession(environment.session?.(id));
+		...environment.session ? { session(id, sessionOptions) {
+			return sandboxSessionFromAgentSession(environment.session?.(id, sessionOptions), sessionOptions?.controlRef);
 		} } : {},
 		...environment.read ? { read: environment.read.bind(environment) } : {},
 		...environment.write ? { write: environment.write.bind(environment) } : {},
@@ -753,19 +760,25 @@ function sandboxInstanceAsEnvironment(box, providerName, client) {
 		id: String(box.id),
 		provider: providerName,
 		...typeof box.name === "string" ? { name: box.name } : {},
+		...readBoxMetadata(box) ? { metadata: readBoxMetadata(box) } : {},
 		async status() {
 			await maybeRefresh(box);
 			return statusFromUnknown(readBoxStatus(box));
 		},
 		async *stream(input) {
-			for await (const event of box.streamPrompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input))) yield environmentEventFromSandboxEvent(event);
+			for await (const event of box.streamPrompt(promptFromAgentTurnInput(input), promptOptionsFromAgentTurnInput(input))) yield environmentEventFromSandboxEvent(event);
 		},
 		...hasDispatchPrompt(box) ? { async dispatch(input) {
-			return sessionRefFromSandboxDispatch(await box.dispatchPrompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input)), providerName);
-		} } : {},
-		...hasSession(box) ? { session(id) {
-			return sandboxSessionAsAgentSession(box.session(id));
+			return sessionRefFromSandboxDispatch(await box.dispatchPrompt(promptFromAgentTurnInput(input), promptOptionsFromAgentTurnInput(input)), providerName);
 		} } : {},
+		...hasSession(box) ? {
+			session(id, sessionOptions) {
+				return sandboxSessionAsAgentSession(box.session(id), sessionOptions?.controlRef);
+			},
+			async respondToInteraction(command, options) {
+				return (await box.session(command.binding.sessionId).respondToInteraction(command, options)).acknowledgement;
+			}
+		} : {},
 		...hasRead(box) ? { read: box.read.bind(box) } : {},
 		...hasWrite(box) ? { write: box.write.bind(box) } : {},
 		...hasExec(box) ? { async exec(command, options) {
@@ -797,32 +810,50 @@ function sandboxInstanceAsEnvironment(box, providerName, client) {
 		}
 	};
 }
-function sandboxSessionAsAgentSession(session) {
+function sandboxSessionAsAgentSession(session, expectedControlRef) {
+	const controlRef = resolveSessionControlRef(session.controlRef, expectedControlRef, { allowExpectedWhenActualAbsent: true });
 	return {
 		id: session.id,
+		...controlRef === void 0 ? {} : { controlRef },
 		async status() {
 			const status = await session.status();
 			if (!status) return null;
+			assertSandboxStatusBinding(status, controlRef);
 			return sessionStatusFromUnknown(status.status);
 		},
 		async *events(options) {
-			for await (const event of session.events(options)) yield environmentEventFromSandboxEvent(event);
+			const executionId = scopedExecutionId(controlRef, options?.executionId);
+			for await (const event of session.events({
+				...options?.since === void 0 ? {} : { since: options.since },
+				...executionId === void 0 ? {} : { executionId },
+				...options?.signal === void 0 ? {} : { signal: options.signal }
+			})) yield environmentEventFromSandboxEvent(event);
 		},
-		async result() {
-			return agentTurnResultFromPromptResult(await session.result());
+		async result(options) {
+			return agentTurnResultFromPromptResult(await awaitAbortable(Promise.resolve().then(() => session.result({ ...controlRef?.executionId === void 0 ? {} : { executionId: controlRef.executionId } })), options?.signal));
 		},
 		async prompt(input) {
-			return agentTurnResultFromPromptResult(await session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input)));
+			return agentTurnResultFromPromptResult(await session.prompt(promptFromAgentTurnInput(input), promptOptionsFromAgentTurnInput(input)));
 		},
+		...session.respondToInteraction ? { async respondToInteraction(command, options) {
+			assertInteractionCommandScope(command, controlRef);
+			return (await session.respondToInteraction(command, options)).acknowledgement;
+		} } : {},
+		...session.cancelRun ? { async cancelRun(request, options) {
+			assertCancellationScope(request, controlRef);
+			return session.cancelRun(request, options);
+		} } : {},
 		cancel() {
-			return session.interrupt().then(() => void 0);
+			return session.interrupt(controlRef?.executionId === void 0 ? void 0 : { executionId: controlRef.executionId }).then(() => void 0);
 		}
 	};
 }
-function sandboxSessionFromAgentSession(session) {
+function sandboxSessionFromAgentSession(session, expectedControlRef) {
 	if (!session) throw new ValidationError("providerAsSandboxClient: session is unavailable");
+	const controlRef = resolveSessionControlRef(session.controlRef, expectedControlRef);
 	return {
 		id: session.id,
+		...controlRef === void 0 ? {} : { controlRef },
 		async status() {
 			const status = await session.status();
 			if (!status) return null;
@@ -832,15 +863,30 @@ function sandboxSessionFromAgentSession(session) {
 			};
 		},
 		async *events(options) {
-			for await (const event of session.events(options)) yield sandboxEventFromEnvironmentEvent(event);
+			const executionId = scopedExecutionId(controlRef, options?.executionId);
+			for await (const event of session.events({
+				...options?.since === void 0 ? {} : { since: options.since },
+				...executionId === void 0 ? {} : { executionId },
+				...options?.signal === void 0 ? {} : { signal: options.signal }
+			})) yield sandboxEventFromEnvironmentEvent(event);
 		},
-		async result() {
+		async result(options) {
+			scopedExecutionId(controlRef, options?.executionId);
 			return promptResultFromAgentTurnResult(await session.result());
 		},
 		async prompt(message, options) {
 			return promptResultFromAgentTurnResult(await session.prompt(turnInputFromPrompt(message, options)));
 		},
-		async interrupt() {
+		...session.respondToInteraction ? { async respondToInteraction(command, options) {
+			assertInteractionCommandScope(command, controlRef);
+			return { acknowledgement: await session.respondToInteraction(command, options) };
+		} } : {},
+		...session.cancelRun ? { async cancelRun(request, options) {
+			assertCancellationScope(request, controlRef);
+			return session.cancelRun(request, options);
+		} } : {},
+		async interrupt(options) {
+			scopedExecutionId(controlRef, options?.executionId);
 			await session.cancel();
 			return { cancelled: true };
 		}
@@ -877,10 +923,12 @@ function promptResultFromAgentTurnResult(result) {
 }
 function environmentEventFromSandboxEvent(event) {
 	const data = event.data && typeof event.data === "object" ? event.data : {};
+	const normalized = canonicalStreamEventFromSandboxEvent(event);
 	return {
 		type: String(event.type),
 		data,
 		...event.id ? { id: event.id } : {},
+		...normalized ? { normalized } : {},
 		usage: tokenUsageFromData(data),
 		providerEvent: event
 	};
@@ -955,37 +1003,56 @@ function turnInputFromPrompt(message, options) {
 		...options?.turnId ? { turnId: options.turnId } : {},
 		...options?.detach !== void 0 ? { detach: options.detach } : {},
 		...options?.context ? { context: options.context } : {},
+		...options?.runControlRef ? { controlRef: options.runControlRef } : {},
+		...options?.backend?.interactions ? { interactions: options.backend.interactions } : {},
 		...options?.signal ? { signal: options.signal } : {},
 		...options?.backend ? { providerOptions: { backend: options.backend } } : {}
 	};
 }
-function promptFromTurnInput(input) {
-	if (input.parts) return input.parts.map(promptPartFromInputPart);
-	return input.prompt ?? "";
+function resolveSessionControlRef(actual, expected, options = {}) {
+	if (expected === void 0) {
+		if (actual === void 0) return void 0;
+		return AgentExactRunControlRefSchema.parse(actual);
+	}
+	const expectedExact = AgentExactRunControlRefSchema.parse(expected);
+	if (actual === void 0) {
+		if (options.allowExpectedWhenActualAbsent === true) return expectedExact;
+		throw new ValidationError("provider session omitted the required exact run control reference");
+	}
+	const actualExact = AgentExactRunControlRefSchema.safeParse(actual);
+	if (!actualExact.success) throw new ValidationError("provider session returned an invalid exact run control reference");
+	if (!sameControlCoordinates(actualExact.data, expectedExact)) throw new ValidationError("provider session returned a different exact run control reference");
+	return actualExact.data;
+}
+function assertSandboxStatusBinding(status, controlRef) {
+	if (!status || typeof status !== "object" || controlRef === void 0) return;
+	const record = status;
+	if (record.runControlRef !== void 0) {
+		if (!sameControlCoordinates(AgentExactRunControlRefSchema.parse(record.runControlRef), controlRef)) throw new ValidationError("sandbox status returned a different exact run control reference");
+	}
+	for (const key of ["activeExecutionId", "latestExecutionId"]) {
+		const executionId = record[key];
+		if (executionId !== void 0 && executionId !== controlRef.executionId) throw new ValidationError("sandbox status returned a different execution");
+	}
 }
-function promptPartFromInputPart(part) {
-	if (part.type === "text" || part.type === "image") return part;
-	if (part.content !== void 0 || part.path !== void 0) throw new ValidationError("Tangle Sandbox file prompt parts require a URL; inline content and local paths are not representable");
-	if (!part.filename || !part.url) throw new ValidationError("Tangle Sandbox file prompt parts require both filename and URL");
-	return {
-		type: "file",
-		filename: part.filename,
-		...part.mediaType ? { mediaType: part.mediaType } : {},
-		url: part.url
-	};
+function assertInteractionCommandScope(command, controlRef) {
+	if (controlRef === void 0) return;
+	if (command.binding.runId !== controlRef.runId || command.binding.provider !== controlRef.provider || command.binding.environmentId !== controlRef.environmentId || command.binding.sessionId !== controlRef.sessionId || command.binding.executionId !== controlRef.executionId) throw new ValidationError("interaction response targeted a different execution");
 }
-function promptOptionsFromTurnInput(input) {
-	return {
-		...input.sessionId ? { sessionId: input.sessionId } : {},
-		...input.model ? { model: input.model } : {},
-		...input.timeoutMs ? { timeoutMs: input.timeoutMs } : {},
-		...input.context ? { context: input.context } : {},
-		...input.signal ? { signal: input.signal } : {},
-		...input.executionId ? { executionId: input.executionId } : {},
-		...input.lastEventId ? { lastEventId: input.lastEventId } : {},
-		...input.turnId ? { turnId: input.turnId } : {},
-		...input.detach !== void 0 ? { detach: input.detach } : {}
-	};
+function assertCancellationScope(request, controlRef) {
+	if (controlRef === void 0) throw new ValidationError("durable cancellation requires an exact wrapper run control reference");
+	if (!sameControlCoordinates(AgentRunCancellationRequestSchema.parse(request).run, controlRef)) throw new ValidationError("cancellation targeted a different execution");
+}
+function scopedExecutionId(controlRef, requested) {
+	if (controlRef?.executionId !== void 0 && requested !== void 0 && controlRef.executionId !== requested) throw new ValidationError("session operation targeted a different execution");
+	return controlRef?.executionId ?? requested;
+}
+function assertScopedSessionForInput(session, input) {
+	if (input.executionId === void 0 && input.controlRef === void 0) return;
+	const sessionControlRef = AgentExactRunControlRefSchema.safeParse(session.controlRef);
+	if (!sessionControlRef.success) throw new ValidationError("provider session did not expose an exact run control reference for scoped cancellation");
+	const expectedControlRef = input.controlRef === void 0 ? void 0 : AgentExactRunControlRefSchema.parse(input.controlRef);
+	if (input.executionId !== void 0 && sessionControlRef.data.executionId !== input.executionId || expectedControlRef !== void 0 && !sameControlCoordinates(sessionControlRef.data, expectedControlRef)) throw new ValidationError("provider session returned a different exact run control reference");
 }
 function taskToTurnInput(task, signal) {
 	return {
@@ -1111,11 +1178,23 @@ function agentTurnResultFromPromptResult(result) {
 	};
 }
 function sandboxDispatchResultFromSessionRef(session) {
+	const controlRef = session.controlRef === void 0 ? void 0 : AgentExactRunControlRefSchema.parse(session.controlRef);
+	const metadataExecutionId = optionalDispatchIdentity(session.metadata?.executionId, "executionId");
+	if (controlRef !== void 0) {
+		if (controlRef.sessionId !== session.id) throw new ValidationError("provider dispatch returned a control reference for another session");
+		if (session.provider !== void 0 && controlRef.provider !== session.provider) throw new ValidationError("provider dispatch returned a control reference for another provider");
+		if (metadataExecutionId !== void 0 && metadataExecutionId !== controlRef.executionId) throw new ValidationError("provider dispatch returned conflicting execution identities");
+	}
 	const status = session.metadata && Object.hasOwn(session.metadata, "status") ? sessionStatusFromUnknown(session.metadata?.status) : "running";
 	return {
 		sessionId: session.id,
 		status,
-		alreadyExisted: session.metadata?.alreadyExisted === true
+		alreadyExisted: session.metadata?.alreadyExisted === true,
+		...session.metadata?.dispatched === void 0 ? {} : { dispatched: session.metadata.dispatched === true },
+		...controlRef === void 0 ? metadataExecutionId === void 0 ? {} : { executionId: metadataExecutionId } : {
+			executionId: controlRef.executionId,
+			runControlRef: controlRef
+		}
 	};
 }
 function sessionRefFromSandboxDispatch(dispatched, providerName) {
@@ -1123,15 +1202,35 @@ function sessionRefFromSandboxDispatch(dispatched, providerName) {
 	const id = record?.sessionId ?? record?.id;
 	if (typeof id !== "string" || id.length === 0) throw new ValidationError("sandboxClientAsProvider: dispatch returned no session id");
 	if (!record) throw new ValidationError("sandboxClientAsProvider: dispatch returned no session record");
+	const executionId = optionalDispatchIdentity(record.executionId, "executionId");
+	const controlRef = record.runControlRef === void 0 ? void 0 : AgentExactRunControlRefSchema.parse(record.runControlRef);
+	if (controlRef !== void 0) {
+		if (controlRef.sessionId !== id || controlRef.provider !== providerName) throw new ValidationError("sandbox dispatch returned a control reference for another session");
+		if (executionId !== void 0 && controlRef.executionId !== executionId) throw new ValidationError("sandbox dispatch returned conflicting execution identities");
+	}
+	if (record.alreadyExisted !== void 0 && typeof record.alreadyExisted !== "boolean") throw new ValidationError("sandbox dispatch returned an invalid alreadyExisted flag");
+	if (record.dispatched !== void 0 && typeof record.dispatched !== "boolean") throw new ValidationError("sandbox dispatch returned an invalid dispatched flag");
+	if (record.status !== void 0 && !isSandboxSessionStatus(record.status)) throw new ValidationError("sandbox dispatch returned an invalid session status");
 	return {
 		id,
 		provider: providerName,
+		...controlRef === void 0 ? {} : { controlRef },
 		metadata: {
 			...record.status ? { status: record.status } : {},
-			...record.alreadyExisted !== void 0 ? { alreadyExisted: record.alreadyExisted } : {}
+			...executionId === void 0 ? {} : { executionId },
+			...record.alreadyExisted !== void 0 ? { alreadyExisted: record.alreadyExisted } : {},
+			...record.dispatched !== void 0 ? { dispatched: record.dispatched } : {}
 		}
 	};
 }
+function optionalDispatchIdentity(value, label) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "string" || value.length === 0) throw new ValidationError(`sandbox dispatch returned an invalid ${label}`);
+	return value;
+}
+function isSandboxSessionStatus(value) {
+	return value === "queued" || value === "running" || value === "completed" || value === "failed" || value === "cancelled";
+}
 function execResultFromSandboxExecResult(result) {
 	const record = result;
 	const exitCode = finiteNumber(record.exitCode) ?? finiteNumber(record.code);
@@ -1284,4 +1383,4 @@ function hasExec(box) {
 //#endregion
 export { sandboxClientAsProvider as a, resolveAgentEnvironmentProvider as i, providerAsExecutor as n, createTangleSandboxExactProcessProvider as o, providerAsSandboxClient as r, createAgentEnvironmentProviderRegistry as t };
 
-//# sourceMappingURL=environment-provider-CLNVqp6H.js.map
+//# sourceMappingURL=environment-provider-BAO8wt1_.js.map