@tangle-network/agent-interface 1.2.0 → 1.4.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-execution-preparation-receipt.d.ts

@@ -0,0 +1,308 @@
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+import { type ReasoningEffort } from "./agent-profile.js";
+import { type AgentProfileMaterializationAxis } from "./agent-profile-materialization.js";
+import { type HarnessType } from "./harness.js";
+import { type AgentWorkspaceSourceSnapshotPolicy } from "./agent-workspace-source-snapshot.js";
+export type AgentExecutionPreparationDisposition = "behavior" | "control" | "overridden" | "unsupported";
+export type AgentExecutionPreparationOwner = "runtime" | "executor";
+/** One exact profile path and how the prepared execution will handle it. */
+export interface AgentExecutionPreparationAxisResult {
+    axis: AgentProfileMaterializationAxis;
+    disposition: AgentExecutionPreparationDisposition;
+    owner: AgentExecutionPreparationOwner;
+    /** Public mechanism identifier; launch arguments are structurally refused. */
+    mechanism: string;
+    evidenceDigest?: Sha256Digest;
+    /** RFC 6901 JSON Pointer. Required when one axis has multiple requested paths. */
+    path?: string;
+    /**
+     * Sanitized public diagnostic prose for an override or unsupported path.
+     * The schema refuses recognized credential formats, but cannot identify
+     * arbitrary secret strings; producers remain responsible for redaction.
+     */
+    reason?: string;
+}
+export interface AgentExecutionPreparationReasoningEffort {
+    requested: ReasoningEffort;
+    resolved?: ReasoningEffort;
+    fidelity: "exact" | "clamped" | "unsupported";
+}
+export interface AgentExecutionPreparationResolvedModel {
+    /** Exact effective profile request; an explicit empty hint remains empty. */
+    requested: string;
+    /** Concrete non-empty model selected for execution. */
+    resolved: string;
+    /** Exact effective provider hint when present, including an explicit empty hint. */
+    provider?: string;
+    reasoningEffort?: AgentExecutionPreparationReasoningEffort;
+}
+export interface AgentExecutionPreparationWorkspace {
+    /** Public, non-secret lifecycle identity for the workspace lease. */
+    leaseId: string;
+    /** Provider that owns the private prepared workspace capability. */
+    provider: string;
+    /**
+     * Digest of the immutable allocation tuple (provider, lease/allocation id,
+     * and canonical root). This binds `leaseId` to its allocation; it is not a
+     * filesystem-content digest.
+     */
+    identityDigest: Sha256Digest;
+    isolation: "per-run" | "shared";
+    /** Canonical source snapshot before the isolated copy is prepared. */
+    sourceSnapshotDigest: Sha256Digest;
+    /** Public identity of the provider's exact snapshot/canonicalization policy. */
+    sourceSnapshotPolicy: AgentWorkspaceSourceSnapshotPolicy;
+    /** Canonical actual workspace after profile activation and before compute. */
+    preparedWorkspaceDigest: Sha256Digest;
+    profileActivationDigest: Sha256Digest;
+}
+export interface AgentExecutionPreparationMaterializer {
+    name: string;
+    version: string;
+}
+/**
+ * Executor acknowledgement emitted after all launch decisions are fixed and
+ * before any agent compute begins.
+ *
+ * `executionPlanDigest` is required to hash only public launch decisions plus
+ * caller-declared public secret-slot/reference identities. Secret values belong
+ * solely in the private prepared-executor closure/capability; hashing them here
+ * would leak equality and permit guessing low-entropy credentials. This receipt
+ * proves public plan identity, not possession of that private capability.
+ * Secret-capable MCP/hook slots structurally accept only tagged public values or
+ * opaque references. Other authored profile text and reference keys remain
+ * caller-declared public data; recognizable-pattern refusal is defense in depth,
+ * not proof that arbitrary text is non-secret.
+ */
+export interface AgentExecutionPreparationReceipt {
+    kind: "agent-execution-preparation";
+    schemaVersion: 1;
+    preparationId: string;
+    requestDigest: Sha256Digest;
+    /** Canonical identity before executor overrides. */
+    authoredProfileDigest: Sha256Digest;
+    /** Canonical identity after executor overrides. */
+    effectiveProfileDigest: Sha256Digest;
+    backend: string;
+    harness: HarnessType;
+    harnessVersion: string;
+    resolvedModel: AgentExecutionPreparationResolvedModel;
+    workspace: AgentExecutionPreparationWorkspace;
+    axisResults: AgentExecutionPreparationAxisResult[];
+    /** Caller-supplied digest of public decisions and secret-reference identities. */
+    executionPlanDigest: Sha256Digest;
+    materializer: AgentExecutionPreparationMaterializer;
+    expiresAtMs: number;
+    digest: Sha256Digest;
+}
+export declare const agentExecutionPreparationAxisResultSchema: z.ZodObject<{
+    axis: z.ZodEnum<{
+        name: "name";
+        systemPrompt: "systemPrompt";
+        appendSystemPrompt: "appendSystemPrompt";
+        instructions: "instructions";
+        files: "files";
+        tools: "tools";
+        skills: "skills";
+        commands: "commands";
+        description: "description";
+        version: "version";
+        tags: "tags";
+        harness: "harness";
+        permissions: "permissions";
+        mcp: "mcp";
+        connections: "connections";
+        subagents: "subagents";
+        hooks: "hooks";
+        modes: "modes";
+        confidential: "confidential";
+        metadata: "metadata";
+        extensions: "extensions";
+        modelDefault: "modelDefault";
+        modelSmall: "modelSmall";
+        modelProvider: "modelProvider";
+        modelReasoningEffort: "modelReasoningEffort";
+        modelMetadata: "modelMetadata";
+        resourceTools: "resourceTools";
+        resourceAgents: "resourceAgents";
+        resourceInstructions: "resourceInstructions";
+        resourceFailOnError: "resourceFailOnError";
+    }>;
+    disposition: z.ZodEnum<{
+        unsupported: "unsupported";
+        behavior: "behavior";
+        control: "control";
+        overridden: "overridden";
+    }>;
+    owner: z.ZodEnum<{
+        runtime: "runtime";
+        executor: "executor";
+    }>;
+    mechanism: z.ZodString;
+    evidenceDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+    path: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentExecutionPreparationReasoningEffortSchema: z.ZodObject<{
+    requested: z.ZodEnum<{
+        none: "none";
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        ultracode: "ultracode";
+    }>;
+    resolved: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        ultracode: "ultracode";
+    }>>;
+    fidelity: z.ZodEnum<{
+        exact: "exact";
+        unsupported: "unsupported";
+        clamped: "clamped";
+    }>;
+}, z.core.$strict>;
+export declare const agentExecutionPreparationReceiptSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"agent-execution-preparation">;
+    schemaVersion: z.ZodLiteral<1>;
+    preparationId: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    authoredProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    effectiveProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    backend: z.ZodString;
+    harness: z.ZodEnum<{
+        "claude-code": "claude-code";
+        nanoclaw: "nanoclaw";
+        codex: "codex";
+        opencode: "opencode";
+        "kimi-code": "kimi-code";
+        pi: "pi";
+        prime: "prime";
+        gemini: "gemini";
+        hermes: "hermes";
+        openclaw: "openclaw";
+        amp: "amp";
+        "factory-droids": "factory-droids";
+        forge: "forge";
+        cursor: "cursor";
+        acp: "acp";
+        "cli-base": "cli-base";
+    }>;
+    harnessVersion: z.ZodString;
+    resolvedModel: z.ZodObject<{
+        requested: z.ZodString;
+        resolved: z.ZodString;
+        provider: z.ZodOptional<z.ZodString>;
+        reasoningEffort: z.ZodOptional<z.ZodObject<{
+            requested: z.ZodEnum<{
+                none: "none";
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                ultracode: "ultracode";
+            }>;
+            resolved: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                ultracode: "ultracode";
+            }>>;
+            fidelity: z.ZodEnum<{
+                exact: "exact";
+                unsupported: "unsupported";
+                clamped: "clamped";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    workspace: z.ZodObject<{
+        leaseId: z.ZodString;
+        provider: z.ZodString;
+        identityDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        isolation: z.ZodEnum<{
+            "per-run": "per-run";
+            shared: "shared";
+        }>;
+        sourceSnapshotDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        sourceSnapshotPolicy: z.ZodObject<{
+            kind: z.ZodLiteral<"provider-declared">;
+            name: z.ZodString;
+            version: z.ZodNumber;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+        preparedWorkspaceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        profileActivationDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+    axisResults: z.ZodArray<z.ZodObject<{
+        axis: z.ZodEnum<{
+            name: "name";
+            systemPrompt: "systemPrompt";
+            appendSystemPrompt: "appendSystemPrompt";
+            instructions: "instructions";
+            files: "files";
+            tools: "tools";
+            skills: "skills";
+            commands: "commands";
+            description: "description";
+            version: "version";
+            tags: "tags";
+            harness: "harness";
+            permissions: "permissions";
+            mcp: "mcp";
+            connections: "connections";
+            subagents: "subagents";
+            hooks: "hooks";
+            modes: "modes";
+            confidential: "confidential";
+            metadata: "metadata";
+            extensions: "extensions";
+            modelDefault: "modelDefault";
+            modelSmall: "modelSmall";
+            modelProvider: "modelProvider";
+            modelReasoningEffort: "modelReasoningEffort";
+            modelMetadata: "modelMetadata";
+            resourceTools: "resourceTools";
+            resourceAgents: "resourceAgents";
+            resourceInstructions: "resourceInstructions";
+            resourceFailOnError: "resourceFailOnError";
+        }>;
+        disposition: z.ZodEnum<{
+            unsupported: "unsupported";
+            behavior: "behavior";
+            control: "control";
+            overridden: "overridden";
+        }>;
+        owner: z.ZodEnum<{
+            runtime: "runtime";
+            executor: "executor";
+        }>;
+        mechanism: z.ZodString;
+        evidenceDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        path: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    materializer: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    expiresAtMs: z.ZodNumber;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+/** @internal Canonical identity for one preparation axis and path. */
+export declare function agentExecutionPreparationAxisResultKey(axis: AgentProfileMaterializationAxis, path: string | undefined): string;
+/** @internal Exact public equality for preparation axis rows. */
+export declare function agentExecutionPreparationAxisResultsEqual(left: AgentExecutionPreparationAxisResult, right: AgentExecutionPreparationAxisResult): boolean;
+/** @internal Canonical order for preparation axis rows. */
+export declare function compareAgentExecutionPreparationAxisResults(left: AgentExecutionPreparationAxisResult, right: AgentExecutionPreparationAxisResult): number;

package/dist/agent-execution-preparation-receipt.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import { canonicalCandidateDigest, canonicalCandidateJson, isCanonicalJsonValue, isWellFormedUnicode, looksLikeCredential, omitTopLevelDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { REASONING_EFFORTS } from "./agent-profile.js";
+import { AGENT_PROFILE_MATERIALIZATION_AXES, } from "./agent-profile-materialization.js";
+import { harnessTypeSchema } from "./harness.js";
+import { agentWorkspaceSourceSnapshotPolicySchema, } from "./agent-workspace-source-snapshot.js";
+const nonBlankStringSchema = z
+    .string()
+    .refine((value) => value.trim().length > 0, "value cannot be blank");
+const publicMechanismIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/, "mechanism must be a public identifier, not launch arguments")
+    .refine((value) => !looksLikeCredential(value), "mechanism cannot carry credential-like material");
+const publicLifecycleIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._~:/+-]{0,499}$/, "lifecycle identity must be a public identifier")
+    .refine((value) => !looksLikeCredential(value), "lifecycle identity cannot carry credential-like material");
+const publicReasonSchema = nonBlankStringSchema
+    .max(4_000)
+    .refine((value) => !looksLikeCredential(value), "reason cannot carry credential-like material");
+const jsonPointerSchema = z
+    .string()
+    .refine(isCanonicalJsonPointer, "path must be a canonical RFC 6901 JSON Pointer");
+export const agentExecutionPreparationAxisResultSchema = z
+    .strictObject({
+    axis: z.enum(AGENT_PROFILE_MATERIALIZATION_AXES),
+    disposition: z.enum(["behavior", "control", "overridden", "unsupported"]),
+    owner: z.enum(["runtime", "executor"]),
+    mechanism: publicMechanismIdentifierSchema,
+    evidenceDigest: sha256DigestSchema.optional(),
+    path: jsonPointerSchema.optional(),
+    reason: publicReasonSchema.optional(),
+})
+    .superRefine((result, context) => {
+    const requiresReason = result.disposition === "overridden" ||
+        result.disposition === "unsupported";
+    if (requiresReason && result.reason === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["reason"],
+            message: `${result.disposition} profile coverage requires a reason`,
+        });
+    }
+    if (!requiresReason && result.reason !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["reason"],
+            message: `${result.disposition} profile coverage cannot carry an override reason`,
+        });
+    }
+});
+const reasoningEffortSchema = z.enum(REASONING_EFFORTS);
+export const agentExecutionPreparationReasoningEffortSchema = z
+    .strictObject({
+    requested: reasoningEffortSchema,
+    resolved: reasoningEffortSchema.optional(),
+    fidelity: z.enum(["exact", "clamped", "unsupported"]),
+})
+    .superRefine((effort, context) => {
+    if (effort.fidelity === "unsupported") {
+        if (effort.resolved !== undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["resolved"],
+                message: "unsupported reasoning effort cannot claim a resolved value",
+            });
+        }
+        return;
+    }
+    if (effort.resolved === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["resolved"],
+            message: `${effort.fidelity} reasoning fidelity requires a resolved value`,
+        });
+        return;
+    }
+    if (effort.fidelity === "exact" && effort.resolved !== effort.requested) {
+        context.addIssue({
+            code: "custom",
+            path: ["resolved"],
+            message: "exact reasoning fidelity must preserve the requested effort",
+        });
+    }
+    if (effort.fidelity === "clamped") {
+        if (effort.resolved === effort.requested) {
+            context.addIssue({
+                code: "custom",
+                path: ["resolved"],
+                message: "clamped reasoning fidelity must change the requested effort",
+            });
+        }
+        else if (!isDownwardReasoningClamp(effort.requested, effort.resolved)) {
+            context.addIssue({
+                code: "custom",
+                path: ["resolved"],
+                message: "reasoning effort may clamp down but must never increase",
+            });
+        }
+    }
+});
+export const agentExecutionPreparationReceiptSchema = z
+    .strictObject({
+    kind: z.literal("agent-execution-preparation"),
+    schemaVersion: z.literal(1),
+    preparationId: nonBlankStringSchema.max(500),
+    requestDigest: sha256DigestSchema,
+    authoredProfileDigest: sha256DigestSchema,
+    effectiveProfileDigest: sha256DigestSchema,
+    backend: nonBlankStringSchema.max(200),
+    harness: harnessTypeSchema,
+    harnessVersion: nonBlankStringSchema.max(200),
+    resolvedModel: z.strictObject({
+        requested: z.string().max(500),
+        resolved: nonBlankStringSchema.max(500),
+        provider: z.string().max(200).optional(),
+        reasoningEffort: agentExecutionPreparationReasoningEffortSchema.optional(),
+    }),
+    workspace: z.strictObject({
+        leaseId: publicLifecycleIdentifierSchema,
+        provider: publicLifecycleIdentifierSchema,
+        identityDigest: sha256DigestSchema,
+        isolation: z.enum(["per-run", "shared"]),
+        sourceSnapshotDigest: sha256DigestSchema,
+        sourceSnapshotPolicy: agentWorkspaceSourceSnapshotPolicySchema,
+        preparedWorkspaceDigest: sha256DigestSchema,
+        profileActivationDigest: sha256DigestSchema,
+    }),
+    axisResults: z.array(agentExecutionPreparationAxisResultSchema),
+    executionPlanDigest: sha256DigestSchema,
+    materializer: z.strictObject({
+        name: nonBlankStringSchema.max(200),
+        version: nonBlankStringSchema.max(200),
+    }),
+    expiresAtMs: z.number().int().positive().safe(),
+    digest: sha256DigestSchema,
+})
+    .superRefine((receipt, context) => {
+    const seen = new Map();
+    for (const [index, result] of receipt.axisResults.entries()) {
+        const key = agentExecutionPreparationAxisResultKey(result.axis, result.path);
+        const previous = seen.get(key);
+        if (previous !== undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["axisResults", index],
+                message: agentExecutionPreparationAxisResultsEqual(previous, result)
+                    ? "duplicate profile axis/path result"
+                    : "conflicting profile axis/path results",
+            });
+        }
+        else {
+            seen.set(key, result);
+        }
+        if (index > 0 &&
+            compareAgentExecutionPreparationAxisResults(receipt.axisResults[index - 1], result) >= 0) {
+            context.addIssue({
+                code: "custom",
+                path: ["axisResults", index],
+                message: "profile axis/path results must be canonically sorted",
+            });
+        }
+    }
+    if (!isCanonicalJsonValue(receipt)) {
+        context.addIssue({
+            code: "custom",
+            message: "execution preparation receipt must contain only RFC 8785 JSON values",
+        });
+    }
+    else if (canonicalCandidateDigest(omitTopLevelDigest(receipt)) !== receipt.digest) {
+        context.addIssue({
+            code: "custom",
+            path: ["digest"],
+            message: "execution preparation receipt digest is invalid",
+        });
+    }
+});
+/** @internal Canonical identity for one preparation axis and path. */
+export function agentExecutionPreparationAxisResultKey(axis, path) {
+    return `${axis}\u0000${path ?? ""}`;
+}
+/** @internal Exact public equality for preparation axis rows. */
+export function agentExecutionPreparationAxisResultsEqual(left, right) {
+    try {
+        return canonicalCandidateJson(left) === canonicalCandidateJson(right);
+    }
+    catch {
+        return false;
+    }
+}
+const AXIS_ORDER = new Map(AGENT_PROFILE_MATERIALIZATION_AXES.map((axis, index) => [axis, index]));
+/** @internal Canonical order for preparation axis rows. */
+export function compareAgentExecutionPreparationAxisResults(left, right) {
+    const axisDifference = (AXIS_ORDER.get(left.axis) ?? Number.MAX_SAFE_INTEGER) -
+        (AXIS_ORDER.get(right.axis) ?? Number.MAX_SAFE_INTEGER);
+    if (axisDifference !== 0)
+        return axisDifference;
+    const leftPath = left.path ?? "";
+    const rightPath = right.path ?? "";
+    return leftPath < rightPath ? -1 : leftPath > rightPath ? 1 : 0;
+}
+function isCanonicalJsonPointer(value) {
+    if (!value.startsWith("/") || !isWellFormedUnicode(value))
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        if (value[index] !== "~")
+            continue;
+        const escape = value[index + 1];
+        if (escape !== "0" && escape !== "1")
+            return false;
+        index += 1;
+    }
+    return true;
+}
+function isDownwardReasoningClamp(requested, resolved) {
+    return (REASONING_EFFORTS.indexOf(resolved) < REASONING_EFFORTS.indexOf(requested));
+}