@tangle-network/agent-interface 0.40.0 → 0.42.0

package/dist/environment-provider.d.ts

@@ -1,6 +1,11 @@
+import { z } from "zod";
 import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
 import type { AgentCandidateTermination } from "./agent-candidate.js";
 import type { InputPart, StreamEvent, TokenUsage } from "./index.js";
+import { type InteractionAcknowledgement, type InteractionCapabilities, type InteractionResponseCommand } from "./interaction.js";
+import { type ContextTransferReceipt, type ContextTransferRequest, type NativeContextBoundaryProof, type NativeContextContinuationRequest, type NativeContextContinuationTurn } from "./portable-context.js";
+import { type AgentRunControlRef } from "./runtime-control.js";
+import type { AgentWorkspaceBranching } from "./workspace-branching.js";
 /** Portable profile reference: inline profile or provider catalog id. */
 export type AgentProfileRef = AgentProfile | string;
 export type AgentEnvironmentStatus = "pending" | "provisioning" | "running" | "stopped" | "failed" | "expired" | "unknown";
@@ -202,6 +207,12 @@ export interface AgentTurnInput {
     lastEventId?: string;
     turnId?: string;
     detach?: boolean;
+    /** Stable coordinates for a retained run when one already exists. */
+    controlRef?: AgentRunControlRef;
+    /** Approved portable history for a fresh provider session. */
+    contextTransfer?: ContextTransferRequest;
+    /** Verified same-session continuation; never carries duplicate history. */
+    nativeContinuation?: NativeContextContinuationRequest;
     context?: Record<string, unknown>;
     signal?: AbortSignal;
     providerOptions?: Record<string, unknown>;
@@ -214,10 +225,269 @@ export interface AgentTurnResult {
     usage?: TokenUsage;
     metadata?: Record<string, unknown>;
     events?: AgentEnvironmentEvent[];
+    contextTransferReceipt?: ContextTransferReceipt;
 }
+/** Runtime validator for a provider turn returned from durable continuation. */
+export declare const AgentTurnResultSchema: z.ZodObject<{
+    text: z.ZodString;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        totalTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        id: z.ZodOptional<z.ZodString>;
+        normalized: z.ZodOptional<z.ZodType<StreamEvent, unknown, z.core.$ZodTypeInternals<StreamEvent, unknown>>>;
+        usage: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            totalTokens: z.ZodOptional<z.ZodNumber>;
+            cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+            cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+            reasoningTokens: z.ZodOptional<z.ZodNumber>;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        providerEvent: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strict>>>;
+    contextTransferReceipt: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"accepted" | "replayed">;
+        operationId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        planDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        contextDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        destination: z.ZodObject<{
+            runner: z.ZodString;
+            provider: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            profileDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        }, z.core.$strict>;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodString;
+        sessionCreatedForOperationId: z.ZodString;
+        sessionCreatedAt: z.ZodISODateTime;
+        transferredMessageIds: z.ZodArray<z.ZodString>;
+        omittedMessageIds: z.ZodArray<z.ZodString>;
+        admittedAt: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"accepted" | "replayed">;
+        operationId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        planDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        contextDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        destination: z.ZodObject<{
+            runner: z.ZodString;
+            provider: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            profileDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        }, z.core.$strict>;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodString;
+        sessionCreatedForOperationId: z.ZodString;
+        sessionCreatedAt: z.ZodISODateTime;
+        transferredMessageIds: z.ZodArray<z.ZodString>;
+        omittedMessageIds: z.ZodArray<z.ZodString>;
+        admittedAt: z.ZodISODateTime;
+    }, z.core.$strict>], "status">>;
+}, z.core.$strict>;
+/** Durable provider result for one digest-bound native continuation operation. */
+export declare const AgentNativeContextContinuationResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    acknowledgement: z.ZodIntersection<z.ZodObject<{
+        operationId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        status: z.ZodEnum<{
+            conflict: "conflict";
+            accepted: "accepted";
+            transport_failure: "transport_failure";
+            replayed: "replayed";
+            boundary_mismatch: "boundary_mismatch";
+            unverified: "unverified";
+            unknown_session: "unknown_session";
+        }>;
+        historyMessagesSent: z.ZodNumber;
+        existingRequestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        actualBoundary: z.ZodOptional<z.ZodObject<{
+            runId: z.ZodString;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            boundary: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"token">;
+                token: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"revision">;
+                revision: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"digest">;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"messages">;
+                messageIds: z.ZodArray<z.ZodString>;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>], "kind">;
+            observedAt: z.ZodISODateTime;
+        }, z.core.$strict>>;
+        message: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodEnum<{
+            accepted: "accepted";
+            replayed: "replayed";
+        }>;
+    }, z.core.$strip>>;
+    result: z.ZodObject<{
+        text: z.ZodString;
+        success: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        usage: z.ZodOptional<z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            totalTokens: z.ZodOptional<z.ZodNumber>;
+            cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+            cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+            reasoningTokens: z.ZodOptional<z.ZodNumber>;
+            cost: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            id: z.ZodOptional<z.ZodString>;
+            normalized: z.ZodOptional<z.ZodType<StreamEvent, unknown, z.core.$ZodTypeInternals<StreamEvent, unknown>>>;
+            usage: z.ZodOptional<z.ZodObject<{
+                inputTokens: z.ZodNumber;
+                outputTokens: z.ZodNumber;
+                totalTokens: z.ZodOptional<z.ZodNumber>;
+                cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+                cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+                reasoningTokens: z.ZodOptional<z.ZodNumber>;
+                cost: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+            providerEvent: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>>>;
+        contextTransferReceipt: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"accepted" | "replayed">;
+            operationId: z.ZodString;
+            requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            planDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            contextDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            destination: z.ZodObject<{
+                runner: z.ZodString;
+                provider: z.ZodOptional<z.ZodString>;
+                model: z.ZodOptional<z.ZodString>;
+                profileDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+            }, z.core.$strict>;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            sessionCreatedForOperationId: z.ZodString;
+            sessionCreatedAt: z.ZodISODateTime;
+            transferredMessageIds: z.ZodArray<z.ZodString>;
+            omittedMessageIds: z.ZodArray<z.ZodString>;
+            admittedAt: z.ZodISODateTime;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"accepted" | "replayed">;
+            operationId: z.ZodString;
+            requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            planDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            contextDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            destination: z.ZodObject<{
+                runner: z.ZodString;
+                provider: z.ZodOptional<z.ZodString>;
+                model: z.ZodOptional<z.ZodString>;
+                profileDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+            }, z.core.$strict>;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            sessionCreatedForOperationId: z.ZodString;
+            sessionCreatedAt: z.ZodISODateTime;
+            transferredMessageIds: z.ZodArray<z.ZodString>;
+            omittedMessageIds: z.ZodArray<z.ZodString>;
+            admittedAt: z.ZodISODateTime;
+        }, z.core.$strict>], "status">>;
+    }, z.core.$strict>;
+    controlRef: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        executionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    acknowledgement: z.ZodIntersection<z.ZodObject<{
+        operationId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        status: z.ZodEnum<{
+            conflict: "conflict";
+            accepted: "accepted";
+            transport_failure: "transport_failure";
+            replayed: "replayed";
+            boundary_mismatch: "boundary_mismatch";
+            unverified: "unverified";
+            unknown_session: "unknown_session";
+        }>;
+        historyMessagesSent: z.ZodNumber;
+        existingRequestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+        actualBoundary: z.ZodOptional<z.ZodObject<{
+            runId: z.ZodString;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            boundary: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"token">;
+                token: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"revision">;
+                revision: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"digest">;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"messages">;
+                messageIds: z.ZodArray<z.ZodString>;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>], "kind">;
+            observedAt: z.ZodISODateTime;
+        }, z.core.$strict>>;
+        message: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodEnum<{
+            conflict: "conflict";
+            transport_failure: "transport_failure";
+            boundary_mismatch: "boundary_mismatch";
+            unverified: "unverified";
+            unknown_session: "unknown_session";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strict>]>;
+export type AgentNativeContextContinuationResult = z.infer<typeof AgentNativeContextContinuationResultSchema>;
+/** Runtime-only controls kept outside the digest-bound user turn. */
+export interface AgentNativeContextContinuationOptions {
+    turn: NativeContextContinuationTurn;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** Cross-check a successful result against its exact request and retained session. */
+export declare function agentNativeContextContinuationResultMatchesRequest(request: NativeContextContinuationRequest, outcome: AgentNativeContextContinuationResult): boolean;
 export interface AgentSessionRef {
     id: string;
     provider?: string;
+    controlRef?: AgentRunControlRef;
+    contextTransferReceipt?: ContextTransferReceipt;
     metadata?: Record<string, unknown>;
 }
 export interface AgentEnvironmentEvent {
@@ -230,13 +500,29 @@ export interface AgentEnvironmentEvent {
 }
 export interface AgentSession {
     readonly id: string;
+    readonly controlRef?: AgentRunControlRef;
     status(): Promise<AgentSessionStatus | null>;
     events(options?: {
+        /** Exclusive stable event id previously emitted by this session. */
         since?: string;
+        /** Provider execution selected by the durable control reference, when required. */
+        executionId?: string;
         signal?: AbortSignal;
     }): AsyncIterable<AgentEnvironmentEvent>;
     result(): Promise<AgentTurnResult>;
     prompt(input: AgentTurnInput): Promise<AgentTurnResult>;
+    respondToInteraction?(command: InteractionResponseCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<InteractionAcknowledgement>;
+    contextBoundary?(options?: {
+        signal?: AbortSignal;
+    }): Promise<NativeContextBoundaryProof | null>;
+    /**
+     * Atomically verify the boundary and admit one digest-bound continuation.
+     * Repeating an operation id with the same request returns the original result;
+     * repeating it with a different request returns a conflict without dispatch.
+     */
+    continueNative?(request: NativeContextContinuationRequest, options: AgentNativeContextContinuationOptions): Promise<AgentNativeContextContinuationResult>;
     cancel(): Promise<void>;
 }
 export interface AgentEnvironment {
@@ -246,7 +532,12 @@ export interface AgentEnvironment {
     status(): Promise<AgentEnvironmentStatus>;
     stream(input: AgentTurnInput): AsyncIterable<AgentEnvironmentEvent>;
     dispatch?(input: AgentTurnInput): Promise<AgentSessionRef>;
-    session?(id: string): AgentSession;
+    session?(id: string, options?: {
+        controlRef?: AgentRunControlRef;
+    }): AgentSession;
+    respondToInteraction?(command: InteractionResponseCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<InteractionAcknowledgement>;
     read?(path: string, options?: {
         sessionId?: string;
     }): Promise<string>;
@@ -256,6 +547,8 @@ export interface AgentEnvironment {
     exec?(command: string, options?: ExecRequest): Promise<ExecResult>;
     checkpoint?(options?: CheckpointRequest): Promise<CheckpointRef>;
     fork?(checkpoint: CheckpointRef, options?: ForkRequest): Promise<AgentEnvironment>;
+    /** Durable, retry-safe checkpoint and environment-fork operations. */
+    readonly workspaceBranching?: AgentWorkspaceBranching;
     placement?(): Promise<PlacementInfo>;
     refresh?(): Promise<void>;
     destroy?(): Promise<void>;
@@ -273,6 +566,15 @@ export interface AgentEnvironmentCapabilities {
         list: boolean;
         messages: boolean;
     };
+    /** Absent when verified, retry-safe same-session continuation is unsupported. */
+    nativeContinuation?: {
+        /** Boundary comparison and operation admission are one atomic provider action. */
+        atomicBoundary: boolean;
+        /** Operation id + request digest recover retries and reject changed input. */
+        requestIdempotency: boolean;
+    };
+    /** Absent when the provider cannot originate or answer interactions. */
+    interactions?: InteractionCapabilities;
     workspace: {
         read: boolean;
         write: boolean;
@@ -284,6 +586,12 @@ export interface AgentEnvironmentCapabilities {
     branching: {
         checkpoint: boolean;
         fork: boolean;
+        /** True only when key + canonical request digest semantics are implemented. */
+        retrySafe?: boolean;
+        /** True only when operations can be recovered by idempotency key. */
+        lookup?: boolean;
+        /** True only when checkpoints and forked environments have confirmed cleanup. */
+        cleanup?: boolean;
     };
     placement: boolean;
     usage: boolean;
@@ -293,6 +601,89 @@ export interface AgentEnvironmentCapabilities {
         egress: readonly AgentExactProcessEgressMode[];
     };
 }
+/** Strict runtime validator for provider capability negotiation. */
+export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        namedProfiles: z.ZodBoolean;
+        systemPrompt: z.ZodBoolean;
+        instructions: z.ZodBoolean;
+        tools: z.ZodBoolean;
+        permissions: z.ZodBoolean;
+        mcp: z.ZodBoolean;
+        subagents: z.ZodBoolean;
+        resources: z.ZodObject<{
+            files: z.ZodBoolean;
+            instructions: z.ZodBoolean;
+            tools: z.ZodOptional<z.ZodBoolean>;
+            skills: z.ZodOptional<z.ZodBoolean>;
+            agents: z.ZodOptional<z.ZodBoolean>;
+            commands: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>;
+        hooks: z.ZodOptional<z.ZodBoolean>;
+        modes: z.ZodOptional<z.ZodBoolean>;
+        runtimeUpdate: z.ZodBoolean;
+        validation: z.ZodBoolean;
+        extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    streaming: z.ZodObject<{
+        live: z.ZodBoolean;
+        replay: z.ZodBoolean;
+        detach: z.ZodBoolean;
+        turnIdempotency: z.ZodBoolean;
+    }, z.core.$strict>;
+    sessions: z.ZodObject<{
+        continue: z.ZodBoolean;
+        list: z.ZodBoolean;
+        messages: z.ZodBoolean;
+    }, z.core.$strict>;
+    nativeContinuation: z.ZodOptional<z.ZodObject<{
+        atomicBoundary: z.ZodBoolean;
+        requestIdempotency: z.ZodBoolean;
+    }, z.core.$strict>>;
+    interactions: z.ZodOptional<z.ZodObject<{
+        kinds: z.ZodArray<z.ZodString>;
+        answerFieldTypes: z.ZodArray<z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            select: "select";
+            secret: "secret";
+        }>>;
+        responseScopes: z.ZodArray<z.ZodEnum<{
+            interaction: "interaction";
+            session: "session";
+            persistent: "persistent";
+        }>>;
+        secretAnswers: z.ZodBoolean;
+        concurrentRequests: z.ZodBoolean;
+        replay: z.ZodBoolean;
+        responseIdempotency: z.ZodBoolean;
+    }, z.core.$strict>>;
+    workspace: z.ZodObject<{
+        read: z.ZodBoolean;
+        write: z.ZodBoolean;
+        exec: z.ZodBoolean;
+        git: z.ZodBoolean;
+        upload: z.ZodBoolean;
+        download: z.ZodBoolean;
+    }, z.core.$strict>;
+    branching: z.ZodObject<{
+        checkpoint: z.ZodBoolean;
+        fork: z.ZodBoolean;
+        retrySafe: z.ZodOptional<z.ZodBoolean>;
+        lookup: z.ZodOptional<z.ZodBoolean>;
+        cleanup: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    placement: z.ZodBoolean;
+    usage: z.ZodBoolean;
+    confidential: z.ZodBoolean;
+    exactProcess: z.ZodOptional<z.ZodObject<{
+        egress: z.ZodArray<z.ZodEnum<{
+            blocked: "blocked";
+            strict: "strict";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export interface CreateAgentEnvironmentInput {
     profile: AgentProfileRef;
     /** Agent backend inside the provider, for example "opencode" or "codex". */

package/dist/environment-provider.js

@@ -1 +1,214 @@
-export {};
+import { z } from "zod";
+import { InteractionCapabilitiesSchema, } from "./interaction.js";
+/*
+ * Keep the provider contract runtime-validatable. Provider capability data is
+ * commonly read from a remote service or adapter configuration, so its static
+ * TypeScript type is not a trust boundary.
+ */
+const AgentProfileCapabilitiesSchema = z.strictObject({
+    namedProfiles: z.boolean(),
+    systemPrompt: z.boolean(),
+    instructions: z.boolean(),
+    tools: z.boolean(),
+    permissions: z.boolean(),
+    mcp: z.boolean(),
+    subagents: z.boolean(),
+    resources: z.strictObject({
+        files: z.boolean(),
+        instructions: z.boolean(),
+        tools: z.boolean().optional(),
+        skills: z.boolean().optional(),
+        agents: z.boolean().optional(),
+        commands: z.boolean().optional(),
+    }),
+    hooks: z.boolean().optional(),
+    modes: z.boolean().optional(),
+    runtimeUpdate: z.boolean(),
+    validation: z.boolean(),
+    extensions: z.array(z.string().min(1)).optional(),
+});
+import { ContextTransferReceiptSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches, } from "./portable-context.js";
+import { AgentRunControlRefSchema, CanonicalStreamEventSchema, } from "./runtime-control.js";
+const TokenUsageSchema = z.strictObject({
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    totalTokens: z.number().int().nonnegative().optional(),
+    cacheReadInputTokens: z.number().int().nonnegative().optional(),
+    cacheCreationInputTokens: z.number().int().nonnegative().optional(),
+    reasoningTokens: z.number().int().nonnegative().optional(),
+    cost: z.number().finite().nonnegative().optional(),
+});
+const AgentEnvironmentEventSchema = z.strictObject({
+    type: z.string().min(1),
+    data: z.record(z.string(), z.unknown()),
+    id: z.string().min(1).optional(),
+    normalized: CanonicalStreamEventSchema.optional(),
+    usage: TokenUsageSchema.optional(),
+    providerEvent: z.unknown().optional(),
+});
+/** Runtime validator for a provider turn returned from durable continuation. */
+export const AgentTurnResultSchema = z.strictObject({
+    text: z.string(),
+    success: z.boolean(),
+    error: z.string().optional(),
+    sessionId: z.string().min(1).optional(),
+    usage: TokenUsageSchema.optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    events: z.array(AgentEnvironmentEventSchema).optional(),
+    contextTransferReceipt: ContextTransferReceiptSchema.optional(),
+});
+/** Durable provider result for one digest-bound native continuation operation. */
+export const AgentNativeContextContinuationResultSchema = z.union([
+    z
+        .strictObject({
+        acknowledgement: NativeContextContinuationAcknowledgementSchema.and(z.object({ status: z.enum(["accepted", "replayed"]) })),
+        result: AgentTurnResultSchema,
+        /** Exact provider coordinates after the continuation completed. */
+        controlRef: AgentRunControlRefSchema,
+    })
+        .superRefine((outcome, refinement) => {
+        if (outcome.result.contextTransferReceipt !== undefined) {
+            refinement.addIssue({
+                code: "custom",
+                path: ["result", "contextTransferReceipt"],
+                message: "native continuation cannot return a context transfer receipt",
+            });
+        }
+    }),
+    z
+        .strictObject({
+        acknowledgement: NativeContextContinuationAcknowledgementSchema.and(z.object({
+            status: z.enum([
+                "conflict",
+                "boundary_mismatch",
+                "unverified",
+                "unknown_session",
+                "transport_failure",
+            ]),
+        })),
+    })
+        .superRefine((outcome, refinement) => {
+        if (outcome.acknowledgement.status === "transport_failure" &&
+            outcome.acknowledgement.retryable !== true) {
+            refinement.addIssue({
+                code: "custom",
+                path: ["acknowledgement", "retryable"],
+                message: "a durable native continuation transport failure must be retryable",
+            });
+        }
+    }),
+]);
+/** Cross-check a successful result against its exact request and retained session. */
+export function agentNativeContextContinuationResultMatchesRequest(request, outcome) {
+    const parsedRequest = NativeContextContinuationRequestSchema.safeParse(request);
+    const parsedOutcome = AgentNativeContextContinuationResultSchema.safeParse(outcome);
+    if (!parsedRequest.success || !parsedOutcome.success)
+        return false;
+    const exactOutcome = parsedOutcome.data;
+    if (exactOutcome.acknowledgement.status !== "accepted" &&
+        exactOutcome.acknowledgement.status !== "replayed") {
+        return false;
+    }
+    if (!("result" in exactOutcome) || !("controlRef" in exactOutcome)) {
+        return false;
+    }
+    if (!nativeContextContinuationAcknowledgementMatches(parsedRequest.data, exactOutcome.acknowledgement)) {
+        return false;
+    }
+    const source = parsedRequest.data.run;
+    const current = exactOutcome.controlRef;
+    return (current.provider === source.provider &&
+        current.environmentId === source.environmentId &&
+        current.sessionId === source.sessionId &&
+        (exactOutcome.result.sessionId === undefined ||
+            exactOutcome.result.sessionId === current.sessionId));
+}
+/** Strict runtime validator for provider capability negotiation. */
+export const AgentEnvironmentCapabilitiesSchema = z
+    .strictObject({
+    profile: AgentProfileCapabilitiesSchema,
+    streaming: z.strictObject({
+        live: z.boolean(),
+        replay: z.boolean(),
+        detach: z.boolean(),
+        turnIdempotency: z.boolean(),
+    }),
+    sessions: z.strictObject({
+        continue: z.boolean(),
+        list: z.boolean(),
+        messages: z.boolean(),
+    }),
+    nativeContinuation: z
+        .strictObject({
+        atomicBoundary: z.boolean(),
+        requestIdempotency: z.boolean(),
+    })
+        .optional(),
+    interactions: InteractionCapabilitiesSchema.optional(),
+    workspace: z.strictObject({
+        read: z.boolean(),
+        write: z.boolean(),
+        exec: z.boolean(),
+        git: z.boolean(),
+        upload: z.boolean(),
+        download: z.boolean(),
+    }),
+    branching: z.strictObject({
+        checkpoint: z.boolean(),
+        fork: z.boolean(),
+        retrySafe: z.boolean().optional(),
+        lookup: z.boolean().optional(),
+        cleanup: z.boolean().optional(),
+    }),
+    placement: z.boolean(),
+    usage: z.boolean(),
+    confidential: z.boolean(),
+    exactProcess: z
+        .strictObject({
+        egress: z.array(z.enum(["blocked", "strict"])).min(1),
+    })
+        .optional(),
+})
+    .superRefine((capabilities, refinement) => {
+    if (capabilities.nativeContinuation !== undefined &&
+        (!capabilities.nativeContinuation.atomicBoundary ||
+            !capabilities.nativeContinuation.requestIdempotency ||
+            !capabilities.sessions.continue)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["nativeContinuation"],
+            message: "native continuation requires session continuation, atomic boundary admission, and request idempotency together",
+        });
+    }
+    const durableBranching = [
+        capabilities.branching.retrySafe ?? false,
+        capabilities.branching.lookup ?? false,
+        capabilities.branching.cleanup ?? false,
+    ];
+    if (durableBranching.some(Boolean) &&
+        (!durableBranching.every(Boolean) ||
+            !capabilities.branching.checkpoint ||
+            !capabilities.branching.fork)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["branching"],
+            message: "retry-safe branching requires checkpoint, fork, lookup, and cleanup together",
+        });
+    }
+    const egress = capabilities.exactProcess?.egress;
+    if (egress && new Set(egress).size !== egress.length) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["exactProcess", "egress"],
+            message: "exact process egress modes must be unique",
+        });
+    }
+    const extensions = capabilities.profile.extensions;
+    if (extensions && new Set(extensions).size !== extensions.length) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["profile", "extensions"],
+            message: "profile extension namespaces must be unique",
+        });
+    }
+});