@tangle-network/agent-interface 0.41.0 → 0.42.1

package/README.md

@@ -30,7 +30,11 @@ Partial input or output always requires explicit user or policy acceptance, even
 `contextTransferResultMatchesRequest()` checks the operation identifier and request digest for every outcome before a caller accepts, retries, or reports it.
 Its successful receipt repeats the exact destination and carries the provider's session-creation operation and timestamp, identifying the one fresh provider session that admitted the context.
 `NativeContextBoundaryProof` is the separate path for same-session continuation and includes the exact run identity.
-Continuation is valid only when the provider proves the recorded token, revision, digest, or message boundary, sends zero copied history, and applies retry or changed-input conflict semantics.
+`NativeContextContinuationRequest.turnDigest` binds the operation to the exact new JSON-stable user turn; timeout and abort controls live outside that turn under `AgentNativeContextContinuationOptions`.
+Continuation is valid only when the provider atomically proves the recorded token, revision, digest, or message boundary, sends zero copied history, and applies retry or changed-input conflict semantics.
+Providers advertise `nativeContinuation` only when both guarantees are implemented and expose `AgentSession.continueNative()` as the single durable operation.
+An accepted or replayed operation returns its original turn result and exact current control reference; `AgentNativeContextContinuationResultSchema` validates that shape and `agentNativeContextContinuationResultMatchesRequest()` checks its request and retained-session bindings.
+A changed request with the same operation identifier conflicts without dispatch.
 
 Providers that support recoverable workspace copies expose `workspaceBranching` and set `branching.retrySafe`, `branching.lookup`, and `branching.cleanup` together.
 Checkpoint and fork requests bind an idempotency key to a canonical request digest.
@@ -39,7 +43,7 @@ A checkpoint with dependent forks returns `in_use` plus the blocking environment
 The older `checkpoint()` and `fork()` methods remain source-compatible for providers that have not yet implemented recovery semantics, but clients must not present them as durable workspace branching.
 
 All new wire values have exported Zod schemas on the package root.
-Omitting `interactions` or leaving the three durable branching flags false is the compatible declaration for existing providers.
+Omitting `interactions` and `nativeContinuation`, or leaving the three durable branching flags false, is the compatible declaration for existing providers.
 
 ## Install
 

package/dist/environment-provider.d.ts

@@ -3,8 +3,8 @@ import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResu
 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, ContextTransferRequest, NativeContextBoundaryProof, NativeContextContinuationRequest } from "./portable-context.js";
-import type { AgentRunControlRef } from "./runtime-control.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;
@@ -227,6 +227,262 @@ export interface AgentTurnResult {
     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;
@@ -261,6 +517,12 @@ export interface AgentSession {
     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 {
@@ -304,6 +566,13 @@ 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: {
@@ -367,6 +636,10 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
         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<{

package/dist/environment-provider.js

@@ -27,6 +27,102 @@ const AgentProfileCapabilitiesSchema = z.strictObject({
     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({
@@ -42,6 +138,12 @@ export const AgentEnvironmentCapabilitiesSchema = z
         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(),
@@ -68,6 +170,16 @@ export const AgentEnvironmentCapabilitiesSchema = z
         .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,

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 import type { InteractionAcknowledgement, InteractionRequest, InteractionResponse, InteractionResponseCommand } from "./interaction.js";
 import type { AgentExecutionOutcome, DurablePlan, PlanContinuation, SdkPlanHost } from "./plan.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/index.js

@@ -4,7 +4,7 @@
  * Shared types and interfaces for SDK provider adapters.
  * This package defines the contract between the sidecar and provider implementations.
  */
-export { AgentEnvironmentCapabilitiesSchema } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/interaction.d.ts

@@ -23,6 +23,7 @@ export declare const InteractionFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     type: z.ZodLiteral<"text">;
     multiline: z.ZodOptional<z.ZodBoolean>;
     placeholder: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
     default: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     label: z.ZodString;
@@ -57,6 +58,7 @@ export declare const InteractionFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"secret">;
     placeholder: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
     name: z.ZodString;
     label: z.ZodString;
     required: z.ZodOptional<z.ZodBoolean>;
@@ -67,6 +69,7 @@ export declare const InteractionAnswerSpecSchema: z.ZodObject<{
         type: z.ZodLiteral<"text">;
         multiline: z.ZodOptional<z.ZodBoolean>;
         placeholder: z.ZodOptional<z.ZodString>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
         default: z.ZodOptional<z.ZodString>;
         name: z.ZodString;
         label: z.ZodString;
@@ -101,6 +104,7 @@ export declare const InteractionAnswerSpecSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"secret">;
         placeholder: z.ZodOptional<z.ZodString>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
         name: z.ZodString;
         label: z.ZodString;
         required: z.ZodOptional<z.ZodBoolean>;
@@ -204,6 +208,7 @@ export declare const InteractionRequestSchema: z.ZodObject<{
             type: z.ZodLiteral<"text">;
             multiline: z.ZodOptional<z.ZodBoolean>;
             placeholder: z.ZodOptional<z.ZodString>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
             default: z.ZodOptional<z.ZodString>;
             name: z.ZodString;
             label: z.ZodString;
@@ -238,6 +243,7 @@ export declare const InteractionRequestSchema: z.ZodObject<{
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"secret">;
             placeholder: z.ZodOptional<z.ZodString>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
             name: z.ZodString;
             label: z.ZodString;
             required: z.ZodOptional<z.ZodBoolean>;

package/dist/interaction.js

@@ -37,6 +37,8 @@ export const InteractionFieldSchema = z
         type: z.literal("text"),
         multiline: z.boolean().optional(),
         placeholder: z.string().optional(),
+        /** Maximum answer length chosen by the request author. Omission means no contract limit. */
+        maxLength: z.number().int().positive().optional(),
         default: z.string().optional(),
     }),
     z.strictObject({
@@ -76,9 +78,22 @@ export const InteractionFieldSchema = z
         ...FieldBase,
         type: z.literal("secret"),
         placeholder: z.string().optional(),
+        /** Maximum answer length chosen by the request author. Omission means no contract limit. */
+        maxLength: z.number().int().positive().optional(),
     }),
 ])
     .superRefine((field, context) => {
+    if (field.type === "text" &&
+        field.default !== undefined &&
+        field.maxLength !== undefined &&
+        field.default.length > field.maxLength) {
+        context.addIssue({
+            code: "custom",
+            path: ["default"],
+            message: "text field default exceeds maxLength",
+        });
+        return;
+    }
     if (field.type === "number") {
         if (field.min !== undefined &&
             field.max !== undefined &&
@@ -489,10 +504,15 @@ export function validateInteractionAnswer(spec, data) {
         }
         switch (field.type) {
             case "text":
-            case "secret":
-                if (typeof v !== "string")
+            case "secret": {
+                if (typeof v !== "string") {
                     errors.push(`field "${field.name}" must be a string`);
+                }
+                else if (field.maxLength !== undefined && v.length > field.maxLength) {
+                    errors.push(`field "${field.name}" exceeds maxLength ${field.maxLength}`);
+                }
                 break;
+            }
             case "number":
                 if (typeof v !== "number" || !Number.isFinite(v)) {
                     errors.push(`field "${field.name}" must be a finite number`);

package/dist/portable-context.d.ts

@@ -630,17 +630,53 @@ export type NativeContextBoundaryProof = z.infer<typeof NativeContextBoundaryPro
 export interface NativeContextContinuationRequest {
     operationId: string;
     requestDigest: Sha256Digest;
+    turnDigest: Sha256Digest;
     run: AgentRunControlRef;
     expectedBoundary: NativeContextBoundaryProof;
 }
 export interface NativeContextContinuationRequestMaterial {
+    turnDigest: Sha256Digest;
     run: AgentRunControlRef;
     expectedBoundary: NativeContextBoundaryProof;
 }
+/** JSON-stable user turn admitted by a native same-session continuation. */
+export interface NativeContextContinuationTurn {
+    prompt?: string;
+    parts?: InputPart[];
+    model?: string;
+    context?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+export declare const NativeContextContinuationTurnSchema: z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodString>;
+    parts: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        filename: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        filename: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>>;
+    model: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+/** Bind retry identity to the exact new user turn, excluding timeout and abort controls. */
+export declare function nativeContextContinuationTurnDigest(turn: NativeContextContinuationTurn): Sha256Digest;
 export declare function nativeContextContinuationRequestDigest(request: NativeContextContinuationRequestMaterial): Sha256Digest;
 export declare const NativeContextContinuationRequestSchema: z.ZodObject<{
     operationId: z.ZodString;
     requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    turnDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     run: z.ZodObject<{
         runId: z.ZodString;
         provider: z.ZodString;

package/dist/portable-context.js

@@ -559,8 +559,20 @@ export const NativeContextBoundaryProofSchema = z.strictObject({
     boundary: NativeContextBoundarySchema,
     observedAt: z.iso.datetime(),
 });
+export const NativeContextContinuationTurnSchema = z.strictObject({
+    prompt: z.string().optional(),
+    parts: z.array(InputPartSchema).optional(),
+    model: z.string().min(1).optional(),
+    context: jsonRecordSchema.optional(),
+    providerOptions: jsonRecordSchema.optional(),
+});
+/** Bind retry identity to the exact new user turn, excluding timeout and abort controls. */
+export function nativeContextContinuationTurnDigest(turn) {
+    return wireDigest(NativeContextContinuationTurnSchema.parse(turn));
+}
 export function nativeContextContinuationRequestDigest(request) {
     return wireDigest({
+        turnDigest: request.turnDigest,
         run: request.run,
         expectedBoundary: request.expectedBoundary,
     });
@@ -569,6 +581,7 @@ export const NativeContextContinuationRequestSchema = z
     .strictObject({
     operationId: idSchema,
     requestDigest: sha256DigestSchema,
+    turnDigest: sha256DigestSchema,
     run: AgentRunControlRefSchema,
     expectedBoundary: NativeContextBoundaryProofSchema,
 })

package/package.json

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