@tangle-network/agent-interface 0.36.0 → 0.38.0

package/dist/agent-execution-preparation.d.ts

@@ -0,0 +1,366 @@
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+import { type AgentProfile, type ReasoningEffort } from "./agent-profile.js";
+import type { AgentProfileActivationEvidence } from "./agent-profile-activation.js";
+import { type AgentProfileMaterializationAxis } from "./agent-profile-materialization.js";
+import { type HarnessType } from "./harness.js";
+import { type AgentWorkspaceExecutionBoundLeaseRecord, type AgentWorkspaceSealedLeaseRecord, type AgentWorkspaceSourceSnapshotPolicy } from "./agent-workspace-lease.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;
+    authoredProfileDigest: Sha256Digest;
+    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 interface BuildAgentExecutionPreparationReceiptInput {
+    preparationId: string;
+    requestDigest: Sha256Digest;
+    authoredProfile: AgentProfile;
+    effectiveProfile: AgentProfile;
+    backend: string;
+    harness: HarnessType;
+    harnessVersion: string;
+    resolvedModel: AgentExecutionPreparationResolvedModel;
+    /** Exact sealed public lease projection; owner authorization remains private. */
+    workspaceLease: AgentWorkspaceSealedLeaseRecord;
+    profileActivation: Pick<AgentProfileActivationEvidence, "digest">;
+    axisResults: readonly AgentExecutionPreparationAxisResult[];
+    /** Must digest public decisions and reference identities, not resolved values. */
+    executionPlanDigest: Sha256Digest;
+    materializer: AgentExecutionPreparationMaterializer;
+    expiresAtMs: number;
+    /** Clock used only to refuse already-expired preparations. */
+    nowMs?: number;
+}
+export interface ValidateAgentExecutionPreparationReceiptOptions {
+    receipt: unknown;
+    requestDigest: Sha256Digest;
+    authoredProfile: AgentProfile;
+    effectiveProfile: AgentProfile;
+    /** Expected public-plan identity; callers must not derive it from secret values. */
+    executionPlanDigest: Sha256Digest;
+    profileActivation: Pick<AgentProfileActivationEvidence, "digest">;
+    /** Bound lease closes the receipt→workspace link before compute begins. */
+    workspaceLease: AgentWorkspaceExecutionBoundLeaseRecord;
+    nowMs?: number;
+    preparationId?: string;
+    backend?: string;
+    harness?: HarnessType;
+    harnessVersion?: string;
+}
+export type AgentExecutionPreparationValidationIssueCode = "invalid-receipt" | "invalid-profile" | "invalid-workspace-lease" | "workspace-not-execution-bound" | "execution-binding-mismatch" | "digest-mismatch" | "expectation-mismatch" | "expired" | "missing-coverage" | "ambiguous-coverage" | "duplicate-coverage" | "conflicting-coverage" | "unrequested-coverage" | "invalid-disposition" | "strict-unsupported" | "model-fidelity";
+export interface AgentExecutionPreparationValidationIssue {
+    code: AgentExecutionPreparationValidationIssueCode;
+    message: string;
+    axis?: AgentProfileMaterializationAxis;
+    path?: string;
+}
+export type AgentExecutionPreparationValidationResult = {
+    ok: true;
+    receipt: AgentExecutionPreparationReceipt;
+    issues: [];
+} | {
+    ok: false;
+    issues: AgentExecutionPreparationValidationIssue[];
+};
+export declare const agentExecutionPreparationAxisResultSchema: z.ZodObject<{
+    axis: z.ZodEnum<{
+        permissions: "permissions";
+        tools: "tools";
+        mcp: "mcp";
+        connections: "connections";
+        subagents: "subagents";
+        hooks: "hooks";
+        modes: "modes";
+        metadata: "metadata";
+        description: "description";
+        name: "name";
+        files: "files";
+        version: "version";
+        tags: "tags";
+        harness: "harness";
+        confidential: "confidential";
+        extensions: "extensions";
+        instructions: "instructions";
+        skills: "skills";
+        commands: "commands";
+        systemPrompt: "systemPrompt";
+        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";
+        gemini: "gemini";
+        hermes: "hermes";
+        openclaw: "openclaw";
+        amp: "amp";
+        "factory-droids": "factory-droids";
+        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<{
+            permissions: "permissions";
+            tools: "tools";
+            mcp: "mcp";
+            connections: "connections";
+            subagents: "subagents";
+            hooks: "hooks";
+            modes: "modes";
+            metadata: "metadata";
+            description: "description";
+            name: "name";
+            files: "files";
+            version: "version";
+            tags: "tags";
+            harness: "harness";
+            confidential: "confidential";
+            extensions: "extensions";
+            instructions: "instructions";
+            skills: "skills";
+            commands: "commands";
+            systemPrompt: "systemPrompt";
+            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>;
+/**
+ * Canonical RFC 8785/SHA-256 identity for one validated, public AgentProfile.
+ * Secret-capable MCP/hook fields are tagged. Other prompt, resource, metadata,
+ * and tool text is ordinary public profile data: it may legitimately discuss
+ * credentials, security incidents, or examples that resemble credentials, so
+ * pattern matching cannot decide whether it is secret. Resolve opaque secret
+ * references only after this public identity is fixed.
+ */
+export declare function canonicalAgentProfileDigest(profile: AgentProfile): Sha256Digest;
+/** Build, self-hash, and cross-check one pre-compute executor acknowledgement. */
+export declare function buildAgentExecutionPreparationReceipt(input: BuildAgentExecutionPreparationReceiptInput): AgentExecutionPreparationReceipt;
+/** Validate structure, bindings, expiry, model fidelity, and exact path coverage. */
+export declare function validateAgentExecutionPreparationReceipt(options: ValidateAgentExecutionPreparationReceiptOptions): AgentExecutionPreparationValidationResult;
+/** Throw one structured error when a preparation acknowledgement is invalid. */
+export declare function assertAgentExecutionPreparationReceipt(options: ValidateAgentExecutionPreparationReceiptOptions): AgentExecutionPreparationReceipt;
+export declare class AgentExecutionPreparationValidationError extends Error {
+    readonly issues: readonly AgentExecutionPreparationValidationIssue[];
+    constructor(issues: readonly AgentExecutionPreparationValidationIssue[]);
+}