@tangle-network/agent-interface 0.42.0 → 0.43.0

package/README.md

@@ -7,8 +7,11 @@ shapes; higher-level packages import from here rather than redefining them.
 
 ## Durable runs, interactions, and context
 
-`AgentRunControlRef` identifies a retained run without depending on a live JavaScript object.
+`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.
+Providers advertise `retainedControl` only when exact run, result, event, cancellation, replay, detach, turn, and session identity are all implemented together.
+`AgentSession.cancelRun()` accepts a canonical request digest bound to one operation and `AgentRunControlRef`, 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.
 
 An environment advertises `interactions` only when it can originate and answer typed requests.
 `AgentEnvironmentCapabilitiesSchema` strictly validates the complete capability document at runtime, including all-or-nothing durable branching declarations.

package/dist/environment-provider.d.ts

@@ -4,7 +4,7 @@ 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 AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest, 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;
@@ -425,6 +425,7 @@ export declare const AgentNativeContextContinuationResultSchema: z.ZodUnion<read
         environmentId: z.ZodString;
         sessionId: z.ZodOptional<z.ZodString>;
         executionId: z.ZodOptional<z.ZodString>;
+        requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     acknowledgement: z.ZodIntersection<z.ZodObject<{
@@ -523,6 +524,10 @@ export interface AgentSession {
      * repeating it with a different request returns a conflict without dispatch.
      */
     continueNative?(request: NativeContextContinuationRequest, options: AgentNativeContextContinuationOptions): Promise<AgentNativeContextContinuationResult>;
+    /** Retry-safe cancellation bound to one exact run and caller operation. */
+    cancelRun?(request: AgentRunCancellationRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentRunCancellationAcknowledgement>;
     cancel(): Promise<void>;
 }
 export interface AgentEnvironment {
@@ -566,6 +571,13 @@ export interface AgentEnvironmentCapabilities {
         list: boolean;
         messages: boolean;
     };
+    /** Present only when every retained-run identity and retry promise is implemented. */
+    retainedControl?: {
+        exactRunIdentity: boolean;
+        resultIdentity: boolean;
+        eventIdentity: boolean;
+        cancellationIdempotency: boolean;
+    };
     /** Absent when verified, retry-safe same-session continuation is unsupported. */
     nativeContinuation?: {
         /** Boundary comparison and operation admission are one atomic provider action. */
@@ -636,6 +648,12 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
         list: z.ZodBoolean;
         messages: z.ZodBoolean;
     }, z.core.$strict>;
+    retainedControl: z.ZodOptional<z.ZodObject<{
+        exactRunIdentity: z.ZodBoolean;
+        resultIdentity: z.ZodBoolean;
+        eventIdentity: z.ZodBoolean;
+        cancellationIdempotency: z.ZodBoolean;
+    }, z.core.$strict>>;
     nativeContinuation: z.ZodOptional<z.ZodObject<{
         atomicBoundary: z.ZodBoolean;
         requestIdempotency: z.ZodBoolean;

package/dist/environment-provider.js

@@ -138,6 +138,14 @@ export const AgentEnvironmentCapabilitiesSchema = z
         list: z.boolean(),
         messages: z.boolean(),
     }),
+    retainedControl: z
+        .strictObject({
+        exactRunIdentity: z.boolean(),
+        resultIdentity: z.boolean(),
+        eventIdentity: z.boolean(),
+        cancellationIdempotency: z.boolean(),
+    })
+        .optional(),
     nativeContinuation: z
         .strictObject({
         atomicBoundary: z.boolean(),
@@ -170,6 +178,21 @@ export const AgentEnvironmentCapabilitiesSchema = z
         .optional(),
 })
     .superRefine((capabilities, refinement) => {
+    if (capabilities.retainedControl !== undefined &&
+        (!capabilities.retainedControl.exactRunIdentity ||
+            !capabilities.retainedControl.resultIdentity ||
+            !capabilities.retainedControl.eventIdentity ||
+            !capabilities.retainedControl.cancellationIdempotency ||
+            !capabilities.streaming.replay ||
+            !capabilities.streaming.detach ||
+            !capabilities.streaming.turnIdempotency ||
+            !capabilities.sessions.continue)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["retainedControl"],
+            message: "retained control requires exact run, result, event, cancellation, replay, detach, turn, and session identity together",
+        });
+    }
     if (capabilities.nativeContinuation !== undefined &&
         (!capabilities.nativeContinuation.atomicBoundary ||
             !capabilities.nativeContinuation.requestIdempotency ||

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

@@ -683,6 +683,7 @@ export declare const NativeContextContinuationRequestSchema: z.ZodObject<{
         environmentId: z.ZodString;
         sessionId: z.ZodOptional<z.ZodString>;
         executionId: z.ZodOptional<z.ZodString>;
+        requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     expectedBoundary: z.ZodObject<{
         runId: z.ZodString;

package/dist/runtime-control.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { StreamEvent } from "./index.js";
+import type { Sha256Digest } from "./agent-candidate.js";
 /** Provider-neutral coordinates sufficient to recreate control of one run. */
 export interface AgentRunControlRef {
     runId: string;
@@ -7,6 +8,8 @@ export interface AgentRunControlRef {
     environmentId: string;
     sessionId?: string;
     executionId?: string;
+    /** Provider admission digest for detecting changed-input run reuse. */
+    requestDigest?: Sha256Digest;
 }
 export declare const AgentRunControlRefSchema: z.ZodObject<{
     runId: z.ZodString;
@@ -14,7 +17,67 @@ export declare const AgentRunControlRefSchema: z.ZodObject<{
     environmentId: z.ZodString;
     sessionId: z.ZodOptional<z.ZodString>;
     executionId: z.ZodOptional<z.ZodString>;
+    requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
 }, z.core.$strict>;
+export type AgentRunCancellationEffect = "cancel_requested" | "cancelled" | "not_live" | "unknown";
+export interface AgentRunCancellationRequestMaterial {
+    operationId: string;
+    run: AgentRunControlRef;
+    reason?: string;
+}
+export interface AgentRunCancellationRequest extends AgentRunCancellationRequestMaterial {
+    requestDigest: Sha256Digest;
+}
+export declare function agentRunCancellationRequestDigest(request: AgentRunCancellationRequestMaterial): Sha256Digest;
+export declare const AgentRunCancellationRequestSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    run: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        executionId: z.ZodOptional<z.ZodString>;
+        requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+    }, z.core.$strict>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export interface AgentRunCancellationAcknowledgement {
+    operationId: string;
+    requestDigest: Sha256Digest;
+    run: AgentRunControlRef;
+    status: "accepted" | "replayed" | "conflict" | "unknown";
+    effect: AgentRunCancellationEffect;
+    message?: string;
+    retryable?: boolean;
+}
+export declare const AgentRunCancellationAcknowledgementSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    run: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        executionId: z.ZodOptional<z.ZodString>;
+        requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
+    }, z.core.$strict>;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        conflict: "conflict";
+        accepted: "accepted";
+        replayed: "replayed";
+    }>;
+    effect: z.ZodEnum<{
+        unknown: "unknown";
+        cancelled: "cancelled";
+        cancel_requested: "cancel_requested";
+        not_live: "not_live";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare function agentRunCancellationAcknowledgementMatchesRequest(request: AgentRunCancellationRequest, acknowledgement: AgentRunCancellationAcknowledgement): boolean;
 /** Runtime validator for every member of the existing canonical event union. */
 export declare const CanonicalStreamEventSchema: z.ZodType<StreamEvent>;
 /** Ordered, replayable envelope around the existing canonical event union. */

package/dist/runtime-control.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { canonicalCandidateDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { InteractionRequestSchema } from "./interaction.js";
 import { DurablePlanSchema } from "./plan.js";
 const stableIdSchema = z
@@ -12,7 +13,62 @@ export const AgentRunControlRefSchema = z.strictObject({
     environmentId: stableIdSchema,
     sessionId: stableIdSchema.optional(),
     executionId: stableIdSchema.optional(),
+    requestDigest: sha256DigestSchema.optional(),
 });
+export function agentRunCancellationRequestDigest(request) {
+    return canonicalCandidateDigest({
+        operationId: request.operationId,
+        run: AgentRunControlRefSchema.parse(request.run),
+        ...(request.reason === undefined ? {} : { reason: request.reason }),
+    });
+}
+export const AgentRunCancellationRequestSchema = z
+    .strictObject({
+    operationId: stableIdSchema,
+    requestDigest: sha256DigestSchema,
+    run: AgentRunControlRefSchema,
+    reason: z.string().min(1).max(2_048).optional(),
+})
+    .superRefine((request, refinement) => {
+    if (request.requestDigest !== agentRunCancellationRequestDigest(request)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["requestDigest"],
+            message: "run cancellation request digest does not match its content",
+        });
+    }
+});
+export const AgentRunCancellationAcknowledgementSchema = z
+    .strictObject({
+    operationId: stableIdSchema,
+    requestDigest: sha256DigestSchema,
+    run: AgentRunControlRefSchema,
+    status: z.enum(["accepted", "replayed", "conflict", "unknown"]),
+    effect: z.enum(["cancel_requested", "cancelled", "not_live", "unknown"]),
+    message: z.string().min(1).optional(),
+    retryable: z.boolean().optional(),
+})
+    .superRefine((acknowledgement, refinement) => {
+    const known = acknowledgement.effect !== "unknown";
+    if (((acknowledgement.status === "accepted" || acknowledgement.status === "replayed") && !known) ||
+        ((acknowledgement.status === "conflict" || acknowledgement.status === "unknown") && known)) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["effect"],
+            message: "cancellation status and effect certainty do not agree",
+        });
+    }
+});
+export function agentRunCancellationAcknowledgementMatchesRequest(request, acknowledgement) {
+    const exactRequest = AgentRunCancellationRequestSchema.safeParse(request);
+    const exactAcknowledgement = AgentRunCancellationAcknowledgementSchema.safeParse(acknowledgement);
+    if (!exactRequest.success || !exactAcknowledgement.success)
+        return false;
+    return (exactAcknowledgement.data.operationId === exactRequest.data.operationId &&
+        exactAcknowledgement.data.requestDigest === exactRequest.data.requestDigest &&
+        canonicalCandidateDigest(exactAcknowledgement.data.run) ===
+            canonicalCandidateDigest(exactRequest.data.run));
+}
 const unknownRecordSchema = z.record(z.string(), z.unknown());
 const partBase = {
     id: stableIdSchema,

package/dist/workspace-branching.d.ts

@@ -19,6 +19,7 @@ export declare const WorkspaceCheckpointRequestSchema: z.ZodObject<{
         environmentId: z.ZodString;
         sessionId: z.ZodOptional<z.ZodString>;
         executionId: z.ZodOptional<z.ZodString>;
+        requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     name: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
@@ -43,6 +44,7 @@ export declare const WorkspaceCheckpointRefSchema: z.ZodObject<{
         environmentId: z.ZodString;
         sessionId: z.ZodOptional<z.ZodString>;
         executionId: z.ZodOptional<z.ZodString>;
+        requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
     }, z.core.$strict>;
     idempotencyKey: z.ZodString;
     requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -114,6 +116,7 @@ export declare const WorkspaceForkRequestSchema: z.ZodObject<{
             environmentId: z.ZodString;
             sessionId: z.ZodOptional<z.ZodString>;
             executionId: z.ZodOptional<z.ZodString>;
+            requestDigest: z.ZodOptional<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>;
         }, z.core.$strict>;
         idempotencyKey: z.ZodString;
         requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

package/package.json

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