@tangle-network/agent-interface 1.4.0 → 1.5.0

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-observation.d.ts

@@ -135,8 +135,8 @@ export declare const EnvironmentLifecycleSchema: z.ZodObject<{
         resumable: z.ZodBoolean;
         mode: z.ZodOptional<z.ZodEnum<{
             none: "none";
-            native: "native";
             replayed: "replayed";
+            native: "native";
         }>>;
     }, z.core.$strict>>;
     persistence: z.ZodOptional<z.ZodObject<{
@@ -460,8 +460,8 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 resumable: z.ZodBoolean;
                 mode: z.ZodOptional<z.ZodEnum<{
                     none: "none";
-                    native: "native";
                     replayed: "replayed";
+                    native: "native";
                 }>>;
             }, z.core.$strict>>;
             persistence: z.ZodOptional<z.ZodObject<{
@@ -508,8 +508,8 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 resumable: z.ZodBoolean;
                 mode: z.ZodOptional<z.ZodEnum<{
                     none: "none";
-                    native: "native";
                     replayed: "replayed";
+                    native: "native";
                 }>>;
             }, z.core.$strict>>;
             persistence: z.ZodOptional<z.ZodObject<{

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/index.d.ts

@@ -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

@@ -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

@@ -18,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({
@@ -111,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);
@@ -188,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 = {

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.4.0",
+  "version": "1.5.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",