@tangle-network/agent-interface 1.3.0 → 1.5.0

package/README.md

@@ -33,9 +33,15 @@ The public `AgentInstanceRecord` contains a credential-free profile identity, no
 
 `AgentRunControlRef` identifies a retained run without depending on a live JavaScript object and may carry the provider's admission digest so reconstruction can reject changed-input reuse.
 `RuntimeEventEnvelope` adds stable run, event, sequence, cursor, and timestamp fields around the existing `StreamEvent` union, and its runtime schema validates every canonical event variant.
+The `child-task` event reports one update of a provider-native child task (a subagent, worker, or delegated task) with a stable `childId`, an optional `parentChildId`, a lifecycle status, start and update times, and the runner, model, usage, and terminal reason when the provider reports them.
+Its `sourceEventId` identifies the exact update, so a consumer applies the first event with a given `sourceEventId` and ignores later copies during replay or reconnect.
+Identity never depends on the bounded `raw` payload, and a provider that cannot report a stable `childId` emits no `child-task` event.
 The canonical `cancelled` status identifies caller cancellation and remains distinct from `failed`.
 Providers advertise `retainedControl` only when exact run, result, event, cancellation, replay, detach, turn, and session identity are all implemented together.
 `AgentEnvironment.metadata` is the detached snapshot returned by create or get, so recovery can check persisted annotations without listing environments.
+`AgentEnvironment.creation` reports what the create call that returned the object did: `created` when the call provisioned the environment, `replayed` when an existing environment matched the idempotency key.
+It is a per-call fact, so a same-key replay returns a view of the same environment with `creation: "replayed"`, and the value is absent when the provider cannot prove either outcome.
+A consumer never destroys an environment whose creation it cannot prove, because another caller can hold it.
 Metadata can include caller-authored values and does not prove authorization or authorship.
 `AgentSession.cancelRun()` accepts a canonical request digest bound to one operation and `AgentExactRunControlRef`, so a caller can safely repeat the same cancellation after losing the first acknowledgement.
 Its acknowledgement repeats the operation, digest, and run coordinates and distinguishes a known cancellation effect from conflict or unknown state.

package/dist/agent-candidate-evidence-schema.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+/**
+ * Evidence that one captured artifact is the canonical bytes of its material.
+ *
+ * The artifact's hash must equal the digest the material canonicalizes to, and
+ * the artifact must actually carry bytes. Both are integrity claims: a record
+ * whose artifact hash names something other than its material is evidence for
+ * a different value, and a zero-length artifact is a claim with nothing behind
+ * it. `label` names the evidence in the refusal so a reader knows which record
+ * failed.
+ */
+export declare function agentCandidateEvidenceSchema<TKind extends string, TMaterial>(kind: TKind, material: z.ZodType<TMaterial>, label: string): z.ZodObject<{
+    kind: z.ZodLiteral<TKind>;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    material: z.ZodType<TMaterial, unknown, z.core.$ZodTypeInternals<TMaterial, unknown>>;
+    artifact: z.ZodUnion<readonly [z.ZodObject<{
+        locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"s3">;
+            bucket: z.ZodString;
+            key: z.ZodString;
+            region: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"ipfs">;
+            cid: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "kind">;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        encoding: z.ZodLiteral<"base64">;
+        content: z.ZodString;
+        sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        byteLength: z.ZodNumber;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;

package/dist/agent-candidate-evidence-schema.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { agentCandidateCapturedArtifactSchema } from "./agent-candidate-artifact-schema.js";
+import { sha256DigestSchema } from "./agent-candidate-schema-common.js";
+/**
+ * Evidence that one captured artifact is the canonical bytes of its material.
+ *
+ * The artifact's hash must equal the digest the material canonicalizes to, and
+ * the artifact must actually carry bytes. Both are integrity claims: a record
+ * whose artifact hash names something other than its material is evidence for
+ * a different value, and a zero-length artifact is a claim with nothing behind
+ * it. `label` names the evidence in the refusal so a reader knows which record
+ * failed.
+ */
+export function agentCandidateEvidenceSchema(kind, material, label) {
+    return z
+        .object({
+        kind: z.literal(kind),
+        digest: sha256DigestSchema,
+        material,
+        artifact: agentCandidateCapturedArtifactSchema,
+    })
+        .strict()
+        .superRefine((evidence, ctx) => {
+        if (evidence.artifact.sha256 !== evidence.digest) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["artifact", "sha256"],
+                message: `${label} artifact hash must equal its canonical material digest`,
+            });
+        }
+        if (evidence.artifact.byteLength === 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["artifact", "byteLength"],
+                message: `${label} artifact must contain canonical material bytes`,
+            });
+        }
+    });
+}

package/dist/agent-candidate-execution-plan-schema.js

@@ -1,3 +1,4 @@
+import { agentCandidateEvidenceSchema } from "./agent-candidate-evidence-schema.js";
 import { z } from "zod";
 import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
 import { agentCandidateContainerSchema, agentCandidateInstructionDeliverySchema, agentCandidateWorkingDirectorySchema, } from "./agent-candidate-code-schema.js";
@@ -448,30 +449,7 @@ export const agentCandidateExecutionPlanMaterialSchema = z
     }
 });
 function planEvidenceSchema(kind, material) {
-    return z
-        .object({
-        kind: z.literal(kind),
-        digest: sha256DigestSchema,
-        material,
-        artifact: agentCandidateCapturedArtifactSchema,
-    })
-        .strict()
-        .superRefine((evidence, ctx) => {
-        if (evidence.artifact.sha256 !== evidence.digest) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["artifact", "sha256"],
-                message: "plan artifact hash must equal its canonical material digest",
-            });
-        }
-        if (evidence.artifact.byteLength === 0) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["artifact", "byteLength"],
-                message: "plan artifact must contain canonical material bytes",
-            });
-        }
-    });
+    return agentCandidateEvidenceSchema(kind, material, "plan");
 }
 export const agentCandidateProfilePlanEvidenceSchema = planEvidenceSchema("agent-profile-workspace-plan", agentCandidateProfilePlanMaterialSchema);
 export const agentCandidateProfileActivationSchema = createAgentProfileActivationEvidenceSchema(agentCandidateProfilePlanEvidenceSchema)

package/dist/agent-candidate-outcome-schema.js

@@ -1,5 +1,6 @@
+import { agentCandidateEvidenceSchema } from "./agent-candidate-evidence-schema.js";
 import { z } from "zod";
-import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
+import { agentCandidateArtifactRefSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
 import { agentCandidateBenchmarkGraderIdentitySchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
 import { agentCandidateMediaTypeSchema, gitObjectSchema, isCanonicalJsonValue, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 const safeCountSchema = z
@@ -174,7 +175,7 @@ function refineModelSettlementMaterial(material, ctx) {
         });
     }
 }
-export const agentCandidateModelSettlementEvidenceSchema = evidenceSchema("agent-candidate-model-settlement", agentCandidateModelSettlementMaterialSchema, "model settlement");
+export const agentCandidateModelSettlementEvidenceSchema = agentCandidateEvidenceSchema("agent-candidate-model-settlement", agentCandidateModelSettlementMaterialSchema, "model settlement");
 export const agentCandidateRepositoryStateSchema = z
     .object({
     identity: z.string().min(1),
@@ -278,7 +279,7 @@ export const agentCandidateTaskOutcomeMaterialSchema = z
         });
     }
 });
-export const agentCandidateTaskOutcomeEvidenceSchema = evidenceSchema("agent-candidate-task-outcome", agentCandidateTaskOutcomeMaterialSchema, "task outcome");
+export const agentCandidateTaskOutcomeEvidenceSchema = agentCandidateEvidenceSchema("agent-candidate-task-outcome", agentCandidateTaskOutcomeMaterialSchema, "task outcome");
 export const agentCandidateBenchmarkDimensionSchema = z
     .object({
     name: normalizedDimensionNameSchema,
@@ -346,7 +347,7 @@ export const agentCandidateBenchmarkResultMaterialSchema = z
         });
     }
 });
-export const agentCandidateBenchmarkResultEvidenceSchema = evidenceSchema("agent-candidate-benchmark-result", agentCandidateBenchmarkResultMaterialSchema, "benchmark result");
+export const agentCandidateBenchmarkResultEvidenceSchema = agentCandidateEvidenceSchema("agent-candidate-benchmark-result", agentCandidateBenchmarkResultMaterialSchema, "benchmark result");
 function sameFixedSpend(left, right) {
     return (left.inputTokens === right.inputTokens &&
         left.outputTokens === right.outputTokens &&
@@ -356,29 +357,3 @@ function sameFixedSpend(left, right) {
         left.costUsdNanos === right.costUsdNanos &&
         left.costProvenance === right.costProvenance);
 }
-function evidenceSchema(kind, material, label) {
-    return z
-        .object({
-        kind: z.literal(kind),
-        digest: sha256DigestSchema,
-        material,
-        artifact: agentCandidateCapturedArtifactSchema,
-    })
-        .strict()
-        .superRefine((evidence, ctx) => {
-        if (evidence.artifact.sha256 !== evidence.digest) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["artifact", "sha256"],
-                message: `${label} artifact hash must equal its canonical material digest`,
-            });
-        }
-        if (evidence.artifact.byteLength === 0) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["artifact", "byteLength"],
-                message: `${label} artifact must contain canonical material bytes`,
-            });
-        }
-    });
-}

package/dist/agent-profile-snapshot.js

@@ -1,4 +1,5 @@
 import { canonicalAgentProfileValue } from "./agent-profile-canonical.js";
+import { deepFreeze } from "./deep-freeze.js";
 import { agentProfileSchema } from "./profile-schema.js";
 /**
  * Detach, validate, and recursively freeze one AgentProfile at an intake boundary.
@@ -12,13 +13,3 @@ export function snapshotAgentProfile(value) {
     canonicalAgentProfileValue(parsed);
     return deepFreeze(parsed);
 }
-function deepFreeze(value, seen = new Set()) {
-    if (value === null || typeof value !== "object" || seen.has(value)) {
-        return value;
-    }
-    seen.add(value);
-    for (const child of Object.values(value)) {
-        deepFreeze(child, seen);
-    }
-    return Object.freeze(value);
-}

package/dist/certified-context.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { deepFreeze } from "./deep-freeze.js";
 import { canonicalCandidateDigest, isSafeRelativePath, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 const MAX_INLINE_CONTEXT_BYTES = 65_536;
 const MAX_TOTAL_INLINE_CONTEXT_BYTES = 131_072;
@@ -203,15 +204,6 @@ export const certifiedContextSchema = z
         });
     }
 });
-function deepFreeze(value) {
-    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
-        for (const child of Object.values(value)) {
-            deepFreeze(child);
-        }
-        Object.freeze(value);
-    }
-    return value;
-}
 const _certifiedContextDeliverySchemaMatches = true;
 const _certifiedContextProvenanceSchemaMatches = true;
 const _certifiedContextEntrySchemaMatches = true;

package/dist/deep-freeze.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Make a validated value immutable before it is handed out.
+ *
+ * A profile snapshot, a certified context, and a capability document are each
+ * evidence: something already checked, that a caller then reads and acts on.
+ * If the copy the caller holds can be written to, the evidence can be changed
+ * after the check that made it trustworthy, and a mutated capability flag
+ * describes a surface the environment does not have.
+ *
+ * Values already visited are skipped, so a value that refers back to itself is
+ * frozen once instead of recursing until the stack runs out.
+ */
+export declare function deepFreeze<T>(value: T, seen?: Set<object>): T;

package/dist/deep-freeze.js

@@ -0,0 +1,22 @@
+/**
+ * Make a validated value immutable before it is handed out.
+ *
+ * A profile snapshot, a certified context, and a capability document are each
+ * evidence: something already checked, that a caller then reads and acts on.
+ * If the copy the caller holds can be written to, the evidence can be changed
+ * after the check that made it trustworthy, and a mutated capability flag
+ * describes a surface the environment does not have.
+ *
+ * Values already visited are skipped, so a value that refers back to itself is
+ * frozen once instead of recursing until the stack runs out.
+ */
+export function deepFreeze(value, seen = new Set()) {
+    if (value === null || typeof value !== "object" || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child, seen);
+    }
+    return Object.freeze(value);
+}

package/dist/environment-command-turn.d.ts

@@ -0,0 +1,48 @@
+import type { ExecResult } from "./environment-requests.js";
+import type { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentEvent, AgentTurnInput } from "./environment-runtime.js";
+/**
+ * Normalize the untyped return of a sandbox SDK's command call into
+ * {@link ExecResult}.
+ *
+ * Sandbox SDKs name the same three facts differently: an exit status under
+ * `exitCode` or `code`, captured output under `stdout` or `output`, and
+ * captured errors under `stderr` or `error`. Reading both names in one place
+ * keeps every adapter's exec surface answering with the same shape.
+ *
+ * A result carrying no exit status is refused. Exit zero is the one value that
+ * means the command succeeded, so reading an absent status as zero reports a
+ * command nobody watched as a command that worked, and the turn that ran it
+ * completes on evidence that was never measured. `source` names the SDK call
+ * whose answer could not be read, because that is where the fix belongs.
+ */
+export declare function execResultFromUnknown(value: unknown, source: string): ExecResult;
+export interface CommandTurnOptions {
+    /** The turn the caller asked this environment to run. */
+    input: AgentTurnInput;
+    /** The environment whose `exec` runs the command. */
+    environment: AgentEnvironment;
+    /** The adapter name the refusal names when no command can be resolved. */
+    providerLabel: string;
+    /** The caller's explicit command for this turn, chosen before any default. */
+    turnCommand?: (input: AgentTurnInput, environment: AgentEnvironment) => string | Promise<string>;
+}
+/**
+ * Run one turn as a single command in an environment whose only surface is a
+ * workspace, and emit the turn's events.
+ *
+ * The command comes from the caller's `turnCommand`, then
+ * `providerOptions.command` or `providerOptions.agentCommand`, then the
+ * prompt. An environment that reaches none of them cannot run the turn and
+ * the turn is refused rather than executing an empty command.
+ */
+export declare function commandTurnEvents(options: CommandTurnOptions): AsyncIterable<AgentEnvironmentEvent>;
+/**
+ * The capability document of a provider whose only surface is a workspace.
+ *
+ * Such an adapter runs commands and moves files in a sandbox. It owns no
+ * agent profile, serves no live or replayable stream, keeps no provider
+ * session, and branches no environment, so every surface outside `workspace`
+ * and `placement` reads false. The caller states its own workspace facts
+ * because they are the only ones that differ between these adapters.
+ */
+export declare function execOnlyEnvironmentCapabilities(workspace: AgentEnvironmentCapabilities["workspace"]): AgentEnvironmentCapabilities;

package/dist/environment-command-turn.js

@@ -0,0 +1,128 @@
+/**
+ * Read one non-empty string from an untyped provider-options bag.
+ *
+ * An absent key and a present key holding a non-string or an empty string are
+ * the same answer: the caller named nothing.
+ */
+function stringOption(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function number(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Normalize the untyped return of a sandbox SDK's command call into
+ * {@link ExecResult}.
+ *
+ * Sandbox SDKs name the same three facts differently: an exit status under
+ * `exitCode` or `code`, captured output under `stdout` or `output`, and
+ * captured errors under `stderr` or `error`. Reading both names in one place
+ * keeps every adapter's exec surface answering with the same shape.
+ *
+ * A result carrying no exit status is refused. Exit zero is the one value that
+ * means the command succeeded, so reading an absent status as zero reports a
+ * command nobody watched as a command that worked, and the turn that ran it
+ * completes on evidence that was never measured. `source` names the SDK call
+ * whose answer could not be read, because that is where the fix belongs.
+ */
+export function execResultFromUnknown(value, source) {
+    const record = value && typeof value === "object" ? value : {};
+    const exitCode = number(record.exitCode) ?? number(record.code);
+    if (exitCode === undefined) {
+        throw new Error(`${source} returned no exit status: a command result must carry a finite exitCode or code`);
+    }
+    return {
+        exitCode,
+        stdout: typeof record.stdout === "string"
+            ? record.stdout
+            : typeof record.output === "string"
+                ? record.output
+                : "",
+        stderr: typeof record.stderr === "string"
+            ? record.stderr
+            : typeof record.error === "string"
+                ? record.error
+                : "",
+    };
+}
+/**
+ * Run one turn as a single command in an environment whose only surface is a
+ * workspace, and emit the turn's events.
+ *
+ * The command comes from the caller's `turnCommand`, then
+ * `providerOptions.command` or `providerOptions.agentCommand`, then the
+ * prompt. An environment that reaches none of them cannot run the turn and
+ * the turn is refused rather than executing an empty command.
+ */
+export async function* commandTurnEvents(options) {
+    const { input, environment, providerLabel } = options;
+    const command = (await options.turnCommand?.(input, environment)) ??
+        stringOption(input.providerOptions?.command) ??
+        stringOption(input.providerOptions?.agentCommand) ??
+        input.prompt;
+    if (!command) {
+        throw new Error(`${providerLabel} provider requires turnCommand, providerOptions.command, or prompt`);
+    }
+    const result = await environment.exec?.(command, {
+        cwd: stringOption(input.providerOptions?.cwd),
+        timeoutMs: input.timeoutMs,
+        signal: input.signal,
+    });
+    const text = result?.stdout ?? "";
+    yield { type: "message.part.updated", data: { delta: text } };
+    yield {
+        type: "result",
+        data: {
+            finalText: text,
+            status: result?.exitCode === 0 ? "completed" : "failed",
+            exitCode: result?.exitCode ?? 1,
+            stderr: result?.stderr ?? "",
+        },
+    };
+}
+/**
+ * The capability document of a provider whose only surface is a workspace.
+ *
+ * Such an adapter runs commands and moves files in a sandbox. It owns no
+ * agent profile, serves no live or replayable stream, keeps no provider
+ * session, and branches no environment, so every surface outside `workspace`
+ * and `placement` reads false. The caller states its own workspace facts
+ * because they are the only ones that differ between these adapters.
+ */
+export function execOnlyEnvironmentCapabilities(workspace) {
+    return {
+        profile: {
+            namedProfiles: false,
+            systemPrompt: { replace: false, append: false },
+            instructions: false,
+            tools: false,
+            permissions: false,
+            mcp: false,
+            subagents: false,
+            resources: {
+                files: true,
+                instructions: false,
+                tools: false,
+                skills: false,
+                agents: false,
+                commands: false,
+            },
+            hooks: false,
+            modes: false,
+            runtimeUpdate: false,
+            validation: false,
+        },
+        streaming: {
+            live: false,
+            replay: false,
+            detach: false,
+            turnIdempotency: false,
+        },
+        sessions: { continue: false, list: false, messages: false },
+        workspace: { ...workspace },
+        branching: { checkpoint: false, fork: false },
+        placement: true,
+        usage: false,
+        confidential: false,
+    };
+}

package/dist/environment-provider.d.ts

@@ -4,3 +4,4 @@ export * from "./environment-interactive.js";
 export * from "./environment-observation.js";
 export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";
+export * from "./environment-command-turn.js";

package/dist/environment-provider.js

@@ -4,3 +4,4 @@ export * from "./environment-interactive.js";
 export * from "./environment-observation.js";
 export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";
+export * from "./environment-command-turn.js";

package/dist/environment-runtime.d.ts

@@ -624,10 +624,34 @@ export interface AgentSession {
         signal?: AbortSignal;
     }): Promise<void>;
 }
+/**
+ * What one {@link AgentEnvironmentProvider.create} call did for the
+ * environment it returned.
+ *
+ * - `created`: this call provisioned the environment.
+ * - `replayed`: an existing environment that matched the idempotency key was
+ *   returned. This call provisioned nothing.
+ *
+ * Absent when the provider cannot distinguish the two. A consumer treats an
+ * absent value as unknown and fails closed: it never destroys an environment
+ * whose creation it cannot prove, because another caller can hold it.
+ */
+export type AgentEnvironmentCreation = "created" | "replayed";
+export declare const AgentEnvironmentCreationSchema: z.ZodEnum<{
+    replayed: "replayed";
+    created: "created";
+}>;
 export interface AgentEnvironment {
     readonly id: string;
     readonly provider: string;
     readonly name?: string;
+    /**
+     * The verdict of the create call that returned this object. It is a
+     * per-call fact: a same-key replay returns a view of the same environment
+     * with `creation: "replayed"`. Absent on `get()` results and when the
+     * provider cannot prove which outcome happened.
+     */
+    readonly creation?: AgentEnvironmentCreation;
     /**
      * Detached metadata returned by the provider.
      * It can contain caller-authored annotations and is not authorization evidence.
@@ -945,15 +969,31 @@ export interface AgentEnvironmentCreateIdempotencyRecord<T> {
     readonly pending: Promise<T>;
     environment?: T;
 }
+/**
+ * Return the per-call view of an environment that a same-key create replayed.
+ *
+ * The view shares every member of the environment, so operations act on the
+ * one environment, and it states `creation: "replayed"` because this call
+ * provisioned nothing. The copy is shallow, so the environment must be a plain
+ * object whose members do not read `this`; a class instance loses its
+ * prototype members in a copy and is rejected.
+ * @internal
+ */
+export declare function replayedAgentEnvironmentView<T extends object>(environment: T): T;
 /**
  * Apply the generic create contract to one provider adapter's keyed requests.
  *
  * The provider's backing service remains responsible for retaining the key
  * across adapter reconstruction. This helper coalesces concurrent retries and
  * rejects collisions before the provider performs another create effect.
+ *
+ * The call that runs `create` receives the environment the provider built,
+ * with the creation verdict the provider could prove. Every same-key call
+ * after it, including one that awaited the same pending create, receives
+ * {@link replayedAgentEnvironmentView} of that environment.
  * @internal
  */
-export declare function createAgentEnvironmentWithIdempotency<T>(records: Map<string, AgentEnvironmentCreateIdempotencyRecord<T>>, input: CreateAgentEnvironmentInput, create: () => Promise<T>): Promise<T>;
+export declare function createAgentEnvironmentWithIdempotency<T extends object>(records: Map<string, AgentEnvironmentCreateIdempotencyRecord<T>>, input: CreateAgentEnvironmentInput, create: () => Promise<T>): Promise<T>;
 export interface AgentEnvironmentProvider {
     readonly name: string;
     readonly exactProcess?: AgentExactProcessProvider;

package/dist/environment-runtime.js

@@ -113,6 +113,10 @@ export function agentNativeContextContinuationResultMatchesRequest(request, outc
         (exactOutcome.result.sessionId === undefined ||
             exactOutcome.result.sessionId === current.sessionId));
 }
+export const AgentEnvironmentCreationSchema = z.enum([
+    "created",
+    "replayed",
+]);
 /** Strict runtime validator for provider capability negotiation. */
 export const AgentEnvironmentCapabilitiesSchema = z
     .strictObject({
@@ -325,12 +329,34 @@ export function agentEnvironmentCreateInputDigest(input) {
         input: material,
     });
 }
+/**
+ * Return the per-call view of an environment that a same-key create replayed.
+ *
+ * The view shares every member of the environment, so operations act on the
+ * one environment, and it states `creation: "replayed"` because this call
+ * provisioned nothing. The copy is shallow, so the environment must be a plain
+ * object whose members do not read `this`; a class instance loses its
+ * prototype members in a copy and is rejected.
+ * @internal
+ */
+export function replayedAgentEnvironmentView(environment) {
+    const prototype = Object.getPrototypeOf(environment);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new Error("a replayed agent environment view requires a plain object environment");
+    }
+    return { ...environment, creation: "replayed" };
+}
 /**
  * Apply the generic create contract to one provider adapter's keyed requests.
  *
  * The provider's backing service remains responsible for retaining the key
  * across adapter reconstruction. This helper coalesces concurrent retries and
  * rejects collisions before the provider performs another create effect.
+ *
+ * The call that runs `create` receives the environment the provider built,
+ * with the creation verdict the provider could prove. Every same-key call
+ * after it, including one that awaited the same pending create, receives
+ * {@link replayedAgentEnvironmentView} of that environment.
  * @internal
  */
 export async function createAgentEnvironmentWithIdempotency(records, input, create) {
@@ -344,7 +370,7 @@ export async function createAgentEnvironmentWithIdempotency(records, input, crea
         if (existing.digest !== digest) {
             throw new Error("agent environment create idempotency key conflicts with a different create input");
         }
-        return existing.environment ?? existing.pending;
+        return replayedAgentEnvironmentView(existing.environment ?? (await existing.pending));
     }
     const pending = Promise.resolve().then(create);
     const record = {

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, createAgentEnvironmentWithIdempotency, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";
@@ -33,6 +33,7 @@ export * from "./agent-profile-materialization.js";
 export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./certified-context.js";
+export * from "./deep-freeze.js";
 export * from "./profile-diff.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./provider-config.js";
 export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, createAgentEnvironmentWithIdempotency, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";
@@ -31,6 +31,7 @@ export * from "./agent-profile-materialization.js";
 export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./certified-context.js";
+export * from "./deep-freeze.js";
 export * from "./profile-diff.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";

package/dist/runtime-control.d.ts

@@ -33,6 +33,15 @@ export declare const AgentExactRunControlRefSchema: z.ZodObject<{
     executionId: z.ZodString;
     requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
 }, z.core.$strict>;
+/**
+ * Whether two references name the same run.
+ *
+ * Comparison is over the reference's canonical form rather than a list of
+ * field names, so a reference that gains a field is compared on it without a
+ * caller having to remember: two runs that differ only in a field nobody
+ * enumerated must not read as one run.
+ */
+export declare function sameAgentRunControlRef(left: AgentRunControlRef, right: AgentRunControlRef): boolean;
 export type AgentRunCancellationEffect = "cancel_requested" | "cancelled" | "not_live" | "unknown";
 export interface AgentRunCancellationRequestMaterial {
     operationId: string;

package/dist/runtime-control.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { canonicalCandidateDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedJsonSchema, boundedStringSchema, } from "./contract-limits.js";
+import { ModelUsageSchema } from "./environment-observation.js";
 import { InteractionRequestSchema } from "./interaction.js";
 import { DurablePlanSchema } from "./plan.js";
 const stableIdSchema = boundedIdentifierSchema;
@@ -17,6 +18,17 @@ export const AgentExactRunControlRefSchema = AgentRunControlRefSchema.extend({
     executionId: stableIdSchema,
     requestDigest: sha256DigestSchema,
 });
+/**
+ * Whether two references name the same run.
+ *
+ * Comparison is over the reference's canonical form rather than a list of
+ * field names, so a reference that gains a field is compared on it without a
+ * caller having to remember: two runs that differ only in a field nobody
+ * enumerated must not read as one run.
+ */
+export function sameAgentRunControlRef(left, right) {
+    return canonicalCandidateDigest(left) === canonicalCandidateDigest(right);
+}
 export function agentRunCancellationRequestDigest(request) {
     const parsed = AgentRunCancellationRequestMaterialSchema.parse(request);
     return canonicalCandidateDigest({
@@ -110,8 +122,7 @@ export function agentRunCancellationAcknowledgementMatchesRequest(request, ackno
         return false;
     return (exactAcknowledgement.data.operationId === exactRequest.data.operationId &&
         exactAcknowledgement.data.requestDigest === exactRequest.data.requestDigest &&
-        canonicalCandidateDigest(exactAcknowledgement.data.run) ===
-            canonicalCandidateDigest(exactRequest.data.run));
+        sameAgentRunControlRef(exactAcknowledgement.data.run, exactRequest.data.run));
 }
 export function agentRunControlRequestDigest(request) {
     const parsed = AgentRunControlRequestMaterialSchema.parse(request);
@@ -187,8 +198,7 @@ export function agentRunControlAcknowledgementMatchesRequest(request, acknowledg
         return false;
     return (exactAcknowledgement.data.operationId === exactRequest.data.operationId &&
         exactAcknowledgement.data.requestDigest === exactRequest.data.requestDigest &&
-        canonicalCandidateDigest(exactAcknowledgement.data.run) ===
-            canonicalCandidateDigest(exactRequest.data.run));
+        sameAgentRunControlRef(exactAcknowledgement.data.run, exactRequest.data.run));
 }
 const unknownRecordSchema = boundedJsonRecordSchema;
 const partBase = {
@@ -263,6 +273,70 @@ const partSchema = z.discriminatedUnion("type", [
         agent: stableIdSchema,
     }),
 ]);
+const TERMINAL_CHILD_TASK_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const epochMillisecondsSchema = z.number().finite().nonnegative();
+/**
+ * Provider-native child task lifecycle. Identity comes only from `childId`,
+ * `parentChildId`, and `sourceEventId`; `raw` is opaque and bounded. A provider
+ * without a stable `childId` emits no `child-task` event.
+ */
+const ChildTaskEventSchema = z
+    .strictObject({
+    type: z.literal("child-task"),
+    childId: stableIdSchema,
+    parentChildId: stableIdSchema.optional(),
+    status: z.enum(["started", "running", "completed", "failed", "cancelled"]),
+    title: boundedStringSchema.optional(),
+    time: z.strictObject({
+        started: epochMillisecondsSchema,
+        updated: epochMillisecondsSchema,
+        ended: epochMillisecondsSchema.optional(),
+    }),
+    runner: stableIdSchema.optional(),
+    model: stableIdSchema.optional(),
+    usage: ModelUsageSchema.optional(),
+    terminalReason: boundedStringSchema.optional(),
+    sourceEventId: stableIdSchema,
+    raw: boundedJsonRecordSchema.optional(),
+})
+    .superRefine((event, refinement) => {
+    const terminal = TERMINAL_CHILD_TASK_STATUSES.has(event.status);
+    if (!terminal && event.time.ended !== undefined) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["time", "ended"],
+            message: "only a terminal child task status may carry an end time",
+        });
+    }
+    if (!terminal && event.terminalReason !== undefined) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["terminalReason"],
+            message: "only a terminal child task status may carry a terminal reason",
+        });
+    }
+    if (event.time.updated < event.time.started) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["time", "updated"],
+            message: "a child task update time cannot precede its start time",
+        });
+    }
+    if (event.time.ended !== undefined && event.time.ended < event.time.started) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["time", "ended"],
+            message: "a child task end time cannot precede its start time",
+        });
+    }
+    if (event.parentChildId === event.childId) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["parentChildId"],
+            message: "a child task cannot be its own parent",
+        });
+    }
+});
 /** Runtime validator for every member of the existing canonical event union. */
 export const CanonicalStreamEventSchema = z.discriminatedUnion("type", [
     z.strictObject({
@@ -332,6 +406,7 @@ export const CanonicalStreamEventSchema = z.discriminatedUnion("type", [
         type: z.literal("plan.submitted"),
         plan: DurablePlanSchema,
     }),
+    ChildTaskEventSchema,
 ]);
 export const RuntimeEventEnvelopeSchema = z.strictObject({
     runId: stableIdSchema,

package/dist/stream-events.d.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from "./execution-types.js";
 import type { InteractionRequest } from "./interaction.js";
 import type { DurablePlan } from "./plan.js";
 import type { Part } from "./parts.js";
@@ -7,6 +8,63 @@ export type MessagePartUpdatedEvent = {
     delta?: string;
 };
 export type StreamStatus = "started" | "processing" | "completed" | "failed" | "cancelled";
+export type ChildTaskStatus = "started" | "running" | "completed" | "failed" | "cancelled";
+/**
+ * One observed update of a provider-native child task: a subagent, worker, or
+ * delegated task that the runner started inside the same run.
+ *
+ * Identity rules:
+ * - `childId` is the provider's stable identifier for the child task. Every
+ *   update of one child repeats the same `childId`. A provider that cannot
+ *   report a stable `childId` emits no `child-task` event.
+ * - `parentChildId` names the parent child task. It is absent when the parent
+ *   is the run itself.
+ * - `sourceEventId` is the provider's identifier for this exact update. Two
+ *   events with the same `sourceEventId` are the same update, so a consumer
+ *   applies the first and ignores the rest during replay or reconnect.
+ * - Identity never depends on `raw`. `raw` is an opaque, bounded copy of
+ *   provider fields that have no canonical position.
+ *
+ * Certainty rules:
+ * - `time.ended` and `terminalReason` are present only with a terminal status
+ *   (`completed`, `failed`, `cancelled`).
+ * - `time.updated` and `time.ended` are never earlier than `time.started`.
+ *
+ * Dedupe example for a consumer that rebuilds the child tree from a replayed
+ * stream. Live and replayed streams produce the same tree because identity
+ * comes only from `childId`, `parentChildId`, and `sourceEventId`:
+ *
+ * ```ts
+ * const applied = new Set<string>();
+ * const children = new Map<string, ChildTaskEvent>();
+ * for (const event of events) {
+ *   if (event.type !== "child-task") continue;
+ *   if (applied.has(event.sourceEventId)) continue;
+ *   applied.add(event.sourceEventId);
+ *   children.set(event.childId, event);
+ * }
+ * ```
+ */
+export type ChildTaskEvent = {
+    type: "child-task";
+    childId: string;
+    parentChildId?: string;
+    status: ChildTaskStatus;
+    title?: string;
+    /** Epoch milliseconds reported by the provider. */
+    time: {
+        started: number;
+        updated: number;
+        ended?: number;
+    };
+    /** Runner that executes the child, for example `claude-code`. */
+    runner?: string;
+    model?: string;
+    usage?: TokenUsage;
+    terminalReason?: string;
+    sourceEventId: string;
+    raw?: Record<string, unknown>;
+};
 export type StreamEvent = MessagePartUpdatedEvent | {
     type: "tool-heartbeat";
     toolName: string;
@@ -53,4 +111,4 @@ export type StreamEvent = MessagePartUpdatedEvent | {
 } | {
     type: "plan.submitted";
     plan: DurablePlan;
-};
+} | ChildTaskEvent;

package/dist/workspace-branching-shared.d.ts

@@ -1,7 +1,45 @@
+import { z } from "zod";
 import type { Sha256Digest } from "./agent-candidate.js";
 import { sha256DigestSchema } from "./agent-candidate-schema-common.js";
 export { sha256DigestSchema };
-export declare const idSchema: import("zod").ZodString;
-export declare const jsonRecordSchema: import("zod").ZodCustom<Record<string, unknown>, Record<string, unknown>>;
+export declare const idSchema: z.ZodString;
+export declare const jsonRecordSchema: z.ZodCustom<Record<string, unknown>, Record<string, unknown>>;
 export declare function wireDigest(value: unknown): Sha256Digest;
 export declare function sameOptionalWireValue(left: unknown, right: unknown): boolean;
+/**
+ * The two fields that identify one durable workspace operation.
+ *
+ * Every result and lookup answer carries them, so a caller can bind an answer
+ * to the exact request it asked before using the resource it names.
+ */
+export declare const operationIdentityShape: {
+    idempotencyKey: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+};
+/**
+ * Refuse a conflict answer that names the request it was asked about.
+ *
+ * A conflict states that the key is already held by a different request. An
+ * answer whose `existingRequestDigest` equals the request's own digest states
+ * a conflict with itself, which is a replay, so the caller would retry a
+ * request the service already accepted.
+ */
+export declare function refuseSelfConflict(result: {
+    status: string;
+    requestDigest: string;
+    existingRequestDigest?: string;
+}, ctx: z.RefinementCtx): void;
+/**
+ * Whether the resource an answer carries was produced by that same operation.
+ *
+ * A checkpoint or forked environment repeats the key and digest of the
+ * operation that made it. An answer carrying a resource stamped with anything
+ * else names a resource the caller did not ask for.
+ */
+export declare function operationResourceIdentityMatches(operation: {
+    idempotencyKey: string;
+    requestDigest: string;
+}, resource: {
+    idempotencyKey: string;
+    requestDigest: string;
+}): boolean;

package/dist/workspace-branching-shared.js

@@ -18,3 +18,42 @@ export function sameOptionalWireValue(left, right) {
         return left === right;
     return wireDigest(left) === wireDigest(right);
 }
+/**
+ * The two fields that identify one durable workspace operation.
+ *
+ * Every result and lookup answer carries them, so a caller can bind an answer
+ * to the exact request it asked before using the resource it names.
+ */
+export const operationIdentityShape = {
+    idempotencyKey: idSchema,
+    requestDigest: sha256DigestSchema,
+};
+/**
+ * Refuse a conflict answer that names the request it was asked about.
+ *
+ * A conflict states that the key is already held by a different request. An
+ * answer whose `existingRequestDigest` equals the request's own digest states
+ * a conflict with itself, which is a replay, so the caller would retry a
+ * request the service already accepted.
+ */
+export function refuseSelfConflict(result, ctx) {
+    if (result.status === "conflict" &&
+        result.existingRequestDigest === result.requestDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["existingRequestDigest"],
+            message: "a conflict must identify a different existing request",
+        });
+    }
+}
+/**
+ * Whether the resource an answer carries was produced by that same operation.
+ *
+ * A checkpoint or forked environment repeats the key and digest of the
+ * operation that made it. An answer carrying a resource stamped with anything
+ * else names a resource the caller did not ask for.
+ */
+export function operationResourceIdentityMatches(operation, resource) {
+    return (resource.idempotencyKey === operation.idempotencyKey &&
+        resource.requestDigest === operation.requestDigest);
+}

package/dist/workspace-checkpoint.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AgentExactRunControlRefSchema } from "./runtime-control.js";
-import { idSchema, jsonRecordSchema, sameOptionalWireValue, sha256DigestSchema, wireDigest } from "./workspace-branching-shared.js";
+import { idSchema, jsonRecordSchema, operationIdentityShape, operationResourceIdentityMatches, refuseSelfConflict, sameOptionalWireValue, sha256DigestSchema, wireDigest } from "./workspace-branching-shared.js";
 import { boundedStringSchema } from "./contract-limits.js";
 const WorkspaceCheckpointMaterialSchema = z.strictObject({
     source: AgentExactRunControlRefSchema,
@@ -56,45 +56,33 @@ export const WorkspaceCheckpointRefSchema = z
         });
     }
 });
-const checkpointOperationBase = {
-    idempotencyKey: idSchema,
-    requestDigest: sha256DigestSchema,
-};
 export const WorkspaceCheckpointResultSchema = z.discriminatedUnion("status", [
     z.strictObject({
         status: z.enum(["created", "replayed"]),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
         checkpoint: WorkspaceCheckpointRefSchema,
     }),
     z.strictObject({
         status: z.literal("conflict"),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
         existingRequestDigest: sha256DigestSchema,
     }),
     z.strictObject({
         status: z.literal("unknown"),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
         message: boundedStringSchema.min(1),
         retryable: z.boolean(),
     }),
-]).superRefine((result, refinement) => {
+]).superRefine((result, ctx) => {
     if ((result.status === "created" || result.status === "replayed") &&
-        (result.checkpoint.idempotencyKey !== result.idempotencyKey ||
-            result.checkpoint.requestDigest !== result.requestDigest)) {
-        refinement.addIssue({
+        !operationResourceIdentityMatches(result, result.checkpoint)) {
+        ctx.addIssue({
             code: "custom",
             path: ["checkpoint"],
             message: "checkpoint identity must match its operation",
         });
     }
-    if (result.status === "conflict" &&
-        result.existingRequestDigest === result.requestDigest) {
-        refinement.addIssue({
-            code: "custom",
-            path: ["existingRequestDigest"],
-            message: "a conflict must identify a different existing request",
-        });
-    }
+    refuseSelfConflict(result, ctx);
 });
 export const WorkspaceOperationLookupRequestSchema = z.strictObject({
     idempotencyKey: idSchema,
@@ -103,42 +91,34 @@ export const WorkspaceOperationLookupRequestSchema = z.strictObject({
 export const WorkspaceCheckpointLookupResultSchema = z.discriminatedUnion("status", [
     z.strictObject({
         status: z.literal("found"),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
         checkpoint: WorkspaceCheckpointRefSchema,
     }),
     z.strictObject({
         status: z.literal("not_found"),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
     }),
     z.strictObject({
         status: z.literal("conflict"),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
         existingRequestDigest: sha256DigestSchema,
     }),
     z.strictObject({
         status: z.literal("unknown"),
-        ...checkpointOperationBase,
+        ...operationIdentityShape,
         message: boundedStringSchema.min(1),
         retryable: z.boolean(),
     }),
-]).superRefine((result, refinement) => {
+]).superRefine((result, ctx) => {
     if (result.status === "found" &&
-        (result.checkpoint.idempotencyKey !== result.idempotencyKey ||
-            result.checkpoint.requestDigest !== result.requestDigest)) {
-        refinement.addIssue({
+        !operationResourceIdentityMatches(result, result.checkpoint)) {
+        ctx.addIssue({
             code: "custom",
             path: ["checkpoint"],
             message: "checkpoint identity must match its lookup operation",
         });
     }
-    if (result.status === "conflict" &&
-        result.existingRequestDigest === result.requestDigest) {
-        refinement.addIssue({
-            code: "custom",
-            path: ["existingRequestDigest"],
-            message: "a conflict must identify a different existing request",
-        });
-    }
+    refuseSelfConflict(result, ctx);
 });
 /** Bind a checkpoint result to the exact request before using the resource. */
 export function workspaceCheckpointResultMatchesRequest(request, result) {
@@ -159,10 +139,8 @@ export function workspaceCheckpointResultMatchesRequest(request, result) {
     return false;
 }
 function checkpointResultMatchesParsed(request, result) {
-    return (result.idempotencyKey === request.idempotencyKey &&
-        result.requestDigest === request.requestDigest &&
-        result.checkpoint.idempotencyKey === request.idempotencyKey &&
-        result.checkpoint.requestDigest === request.requestDigest &&
+    return (operationResourceIdentityMatches(request, result) &&
+        operationResourceIdentityMatches(request, result.checkpoint) &&
         wireDigest(result.checkpoint.source) === wireDigest(request.source) &&
         sameOptionalWireValue(result.checkpoint.metadata, request.metadata) &&
         result.checkpoint.provider === request.source.provider);

package/dist/workspace-fork.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AgentExactRunControlRefSchema } from "./runtime-control.js";
-import { idSchema, jsonRecordSchema, sameOptionalWireValue, sha256DigestSchema, wireDigest } from "./workspace-branching-shared.js";
+import { idSchema, jsonRecordSchema, operationIdentityShape, operationResourceIdentityMatches, refuseSelfConflict, sameOptionalWireValue, sha256DigestSchema, wireDigest } from "./workspace-branching-shared.js";
 import { WorkspaceCheckpointRefSchema } from "./workspace-checkpoint.js";
 import { ConfidentialAttestationSchema, ConfidentialExecutionRequestSchema, confidentialExecutionVerified, } from "./workspace-confidentiality.js";
 import { boundedStringSchema } from "./contract-limits.js";
@@ -155,82 +155,62 @@ export function forkedEnvironmentConfidentialityVerified(request, environment, v
         ...(verifyProviderAttestation ? { verifyProviderAttestation } : {}),
     });
 }
-const forkOperationBase = {
-    idempotencyKey: idSchema,
-    requestDigest: sha256DigestSchema,
-};
 export const WorkspaceForkResultSchema = z.discriminatedUnion("status", [
     z.strictObject({
         status: z.enum(["created", "replayed"]),
-        ...forkOperationBase,
+        ...operationIdentityShape,
         environment: ForkedEnvironmentRefSchema,
     }),
     z.strictObject({
         status: z.literal("conflict"),
-        ...forkOperationBase,
+        ...operationIdentityShape,
         existingRequestDigest: sha256DigestSchema,
     }),
     z.strictObject({
         status: z.literal("unknown"),
-        ...forkOperationBase,
+        ...operationIdentityShape,
         message: boundedStringSchema.min(1),
         retryable: z.boolean(),
     }),
-]).superRefine((result, refinement) => {
+]).superRefine((result, ctx) => {
     if ((result.status === "created" || result.status === "replayed") &&
-        (result.environment.idempotencyKey !== result.idempotencyKey ||
-            result.environment.requestDigest !== result.requestDigest)) {
-        refinement.addIssue({
+        !operationResourceIdentityMatches(result, result.environment)) {
+        ctx.addIssue({
             code: "custom",
             path: ["environment"],
             message: "forked environment identity must match its operation",
         });
     }
-    if (result.status === "conflict" &&
-        result.existingRequestDigest === result.requestDigest) {
-        refinement.addIssue({
-            code: "custom",
-            path: ["existingRequestDigest"],
-            message: "a conflict must identify a different existing request",
-        });
-    }
+    refuseSelfConflict(result, ctx);
 });
 export const WorkspaceForkLookupResultSchema = z.discriminatedUnion("status", [
     z.strictObject({
         status: z.literal("found"),
-        ...forkOperationBase,
+        ...operationIdentityShape,
         environment: ForkedEnvironmentRefSchema,
     }),
-    z.strictObject({ status: z.literal("not_found"), ...forkOperationBase }),
+    z.strictObject({ status: z.literal("not_found"), ...operationIdentityShape }),
     z.strictObject({
         status: z.literal("conflict"),
-        ...forkOperationBase,
+        ...operationIdentityShape,
         existingRequestDigest: sha256DigestSchema,
     }),
     z.strictObject({
         status: z.literal("unknown"),
-        ...forkOperationBase,
+        ...operationIdentityShape,
         message: boundedStringSchema.min(1),
         retryable: z.boolean(),
     }),
-]).superRefine((result, refinement) => {
+]).superRefine((result, ctx) => {
     if (result.status === "found" &&
-        (result.environment.idempotencyKey !== result.idempotencyKey ||
-            result.environment.requestDigest !== result.requestDigest)) {
-        refinement.addIssue({
+        !operationResourceIdentityMatches(result, result.environment)) {
+        ctx.addIssue({
             code: "custom",
             path: ["environment"],
             message: "forked environment identity must match its lookup operation",
         });
     }
-    if (result.status === "conflict" &&
-        result.existingRequestDigest === result.requestDigest) {
-        refinement.addIssue({
-            code: "custom",
-            path: ["existingRequestDigest"],
-            message: "a conflict must identify a different existing request",
-        });
-    }
+    refuseSelfConflict(result, ctx);
 });
 export function workspaceForkResultMatchesRequest(request, result) {
     const parsedRequest = WorkspaceForkRequestSchema.safeParse(request);
@@ -251,10 +231,8 @@ export function workspaceForkResultMatchesRequest(request, result) {
 }
 function forkResultMatchesParsed(request, result) {
     const source = request.checkpoint.source;
-    return (result.idempotencyKey === request.idempotencyKey &&
-        result.requestDigest === request.requestDigest &&
-        result.environment.idempotencyKey === request.idempotencyKey &&
-        result.environment.requestDigest === request.requestDigest &&
+    return (operationResourceIdentityMatches(request, result) &&
+        operationResourceIdentityMatches(request, result.environment) &&
         result.environment.sourceCheckpointId === request.checkpoint.checkpointId &&
         result.environment.provider === request.checkpoint.provider &&
         result.environment.sourceEnvironmentId === source.environmentId &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",