@tangle-network/agent-interface 0.51.0 → 0.53.0

package/README.md

@@ -9,6 +9,7 @@ shapes; higher-level packages import from here rather than redefining them.
 
 `AgentRunControlRef` identifies a retained run without depending on a live JavaScript object and may carry the provider's admission digest so reconstruction can reject changed-input reuse.
 `RuntimeEventEnvelope` adds stable run, event, sequence, cursor, and timestamp fields around the existing `StreamEvent` union, and its runtime schema validates every canonical event variant.
+The canonical `cancelled` status identifies caller cancellation and remains distinct from `failed`.
 Providers advertise `retainedControl` only when exact run, result, event, cancellation, replay, detach, turn, and session identity are all implemented together.
 `AgentEnvironment.metadata` is the detached snapshot returned by create or get, so recovery can check persisted annotations without listing environments.
 Metadata can include caller-authored values and does not prove authorization or authorship.
@@ -16,6 +17,9 @@ Metadata can include caller-authored values and does not prove authorization or
 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.
+`RequestedInteractions` defines the strict per-turn posture for `permission`, `question`, and `plan` requests.
+`AgentTurnInput.interactions` and `AgentExecutionInput.interactions` carry that posture through shared execution boundaries.
+An omitted posture leaves provider defaults unchanged, while an empty object enables no interaction kind for that turn.
 `AgentEnvironmentCapabilitiesSchema` strictly validates the complete capability document at runtime, including all-or-nothing durable branching declarations.
 Optional provider methods must be absent when their capability is false so clients cannot expose an action the provider has denied.
 The capability names supported request kinds, answer field types, response scopes, secret answers, concurrency, replay, and response idempotency.

package/dist/environment-runtime.d.ts

@@ -3,7 +3,7 @@ import type { AgentProfileCapabilities, AgentProfileValidationResult } from "./a
 import type { InputPart } from "./parts.js";
 import type { StreamEvent } from "./stream-events.js";
 import type { TokenUsage } from "./execution-types.js";
-import { type InteractionAcknowledgement, type InteractionCapabilities, type InteractionResponseCommand } from "./interaction.js";
+import { type InteractionAcknowledgement, type InteractionCapabilities, type InteractionResponseCommand, type RequestedInteractions } from "./interaction.js";
 import { type ContextTransferReceipt, type ContextTransferRequest, type NativeContextBoundaryProof, type NativeContextContinuationRequest, type NativeContextContinuationTurn } from "./portable-context.js";
 import { type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest, type AgentRunControlRef } from "./runtime-control.js";
 import type { AgentWorkspaceBranching } from "./workspace-branching.js";
@@ -28,6 +28,8 @@ export interface AgentTurnInput {
     /** Verified same-session continuation; never carries duplicate history. */
     nativeContinuation?: NativeContextContinuationRequest;
     context?: Record<string, unknown>;
+    /** Interaction kinds the provider may originate for this turn. */
+    interactions?: RequestedInteractions;
     signal?: AbortSignal;
     providerOptions?: Record<string, unknown>;
 }
@@ -235,6 +237,11 @@ export declare const AgentTurnInputSchema: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>>;
     context: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+    interactions: z.ZodOptional<z.ZodObject<{
+        permission: z.ZodOptional<z.ZodBoolean>;
+        question: z.ZodOptional<z.ZodBoolean>;
+        plan: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
     providerOptions: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
 }, z.core.$strict>;

package/dist/environment-runtime.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { InteractionCapabilitiesSchema } from "./interaction.js";
+import { InteractionCapabilitiesSchema, RequestedInteractionsSchema } from "./interaction.js";
 import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
 import { AgentExactRunControlRefSchema, AgentRunControlRefSchema, CanonicalStreamEventSchema } from "./runtime-control.js";
 import { AgentProfileCapabilitiesSchema } from "./environment-profile-capabilities.js";
@@ -19,6 +19,7 @@ export const AgentTurnInputSchema = z.strictObject({
     contextTransfer: ContextTransferRequestSchema.optional(),
     nativeContinuation: NativeContextContinuationRequestSchema.optional(),
     context: boundedJsonRecordSchema.optional(),
+    interactions: RequestedInteractionsSchema.optional(),
     signal: z.custom().optional(),
     providerOptions: boundedJsonRecordSchema.optional(),
 });

package/dist/environment-terminal.d.ts

@@ -147,11 +147,23 @@ export declare function terminalSessionUsable(ref: TerminalSessionRef, nowIso: s
 /** Bind an attach result to the parent execution and terminal it targeted. */
 export declare function terminalAttachResultMatchesRequest(request: TerminalAttachRequest, result: TerminalAttachResult): boolean;
 /**
- * Live handle for one interactive terminal. Signatures only; a provider adapter
- * binds the transport in phase two.
+ * The replay cursors a terminal handle can serve.
+ *
+ * `earliest` is the oldest cursor `events` accepts and `latest` is the newest
+ * frame the handle holds. A handle retains a bounded number of frames, so a
+ * consumer that holds no cursor, or holds one the handle dropped, reads this
+ * window to resume from a cursor that still exists.
  */
+export declare const TerminalReplayWindowSchema: z.ZodObject<{
+    earliest: z.ZodNumber;
+    latest: z.ZodNumber;
+}, z.core.$strict>;
+export type TerminalReplayWindow = z.infer<typeof TerminalReplayWindowSchema>;
+/** Live handle for one interactive terminal. */
 export interface AgentTerminalSession {
     readonly ref: TerminalSessionRef;
+    /** Cursors this handle can serve, so an evicted cursor is recoverable. */
+    readonly cursors: TerminalReplayWindow;
     input(input: TerminalInput, options?: {
         signal?: AbortSignal;
     }): Promise<void>;

package/dist/environment-terminal.js

@@ -160,3 +160,15 @@ export function terminalAttachResultMatchesRequest(request, result) {
     }
     return true;
 }
+/**
+ * The replay cursors a terminal handle can serve.
+ *
+ * `earliest` is the oldest cursor `events` accepts and `latest` is the newest
+ * frame the handle holds. A handle retains a bounded number of frames, so a
+ * consumer that holds no cursor, or holds one the handle dropped, reads this
+ * window to resume from a cursor that still exists.
+ */
+export const TerminalReplayWindowSchema = z.strictObject({
+    earliest: z.number().int().nonnegative(),
+    latest: z.number().int().nonnegative(),
+});

package/dist/execution-types.d.ts

@@ -2,6 +2,7 @@ import type { AgentExecutionOutcome, PlanContinuation } from "./plan.js";
 import type { InputPart } from "./parts.js";
 import type { ProviderConfig } from "./provider-config.js";
 import type { InteractionExecutionBinding } from "./interaction-envelope.js";
+import type { RequestedInteractions } from "./interaction-permissions.js";
 export type ToolInvocation = {
     toolName: string;
     input: unknown;
@@ -31,6 +32,8 @@ export type AgentExecutionInput = {
     sessionId?: string;
     /** Exact run coordinates required when this turn can emit interactions. */
     interactionBinding?: InteractionExecutionBinding;
+    /** Interaction kinds the provider may originate for this turn. */
+    interactions?: RequestedInteractions;
     workspaceRoot?: string;
     abortSignal?: AbortSignal;
     headers?: Record<string, string>;

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./provider-config.js";
 export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/interaction-permissions.d.ts

@@ -9,6 +9,18 @@ export declare const InteractionKind: {
     readonly Plan: "plan";
 };
 export type WellKnownInteractionKind = (typeof InteractionKind)[keyof typeof InteractionKind];
+/** Interaction kinds a provider may originate for one turn. */
+export type RequestedInteractions = {
+    [InteractionKind.Permission]?: boolean;
+    [InteractionKind.Question]?: boolean;
+    [InteractionKind.Plan]?: boolean;
+};
+/** Strict per-turn interaction posture; an empty object enables no kinds. */
+export declare const RequestedInteractionsSchema: z.ZodObject<{
+    permission: z.ZodOptional<z.ZodBoolean>;
+    question: z.ZodOptional<z.ZodBoolean>;
+    plan: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 /** Field name carrying the grant on a `permission` interaction's response. */
 export declare const PERMISSION_GRANT_FIELD = "grant";
 /** Optional free-text field carrying the user's reason on a `permission` response. */

package/dist/interaction-permissions.js

@@ -10,6 +10,12 @@ export const InteractionKind = {
     /** Agent shares a plan/todo list for review/approval. */
     Plan: "plan",
 };
+/** Strict per-turn interaction posture; an empty object enables no kinds. */
+export const RequestedInteractionsSchema = z.strictObject({
+    [InteractionKind.Permission]: z.boolean().optional(),
+    [InteractionKind.Question]: z.boolean().optional(),
+    [InteractionKind.Plan]: z.boolean().optional(),
+});
 /** Field name carrying the grant on a `permission` interaction's response. */
 export const PERMISSION_GRANT_FIELD = "grant";
 /** Optional free-text field carrying the user's reason on a `permission` response. */

package/dist/runtime-control.js

@@ -291,7 +291,13 @@ export const CanonicalStreamEventSchema = z.discriminatedUnion("type", [
     }),
     z.strictObject({
         type: z.literal("status"),
-        status: z.enum(["started", "processing", "completed", "failed"]),
+        status: z.enum([
+            "started",
+            "processing",
+            "completed",
+            "failed",
+            "cancelled",
+        ]),
         detail: boundedStringSchema.optional(),
     }),
     z.strictObject({

package/dist/stream-events.d.ts

@@ -6,6 +6,7 @@ export type MessagePartUpdatedEvent = {
     part: Part;
     delta?: string;
 };
+export type StreamStatus = "started" | "processing" | "completed" | "failed" | "cancelled";
 export type StreamEvent = MessagePartUpdatedEvent | {
     type: "tool-heartbeat";
     toolName: string;
@@ -24,7 +25,7 @@ export type StreamEvent = MessagePartUpdatedEvent | {
     elapsedMs?: number;
 } | {
     type: "status";
-    status: "started" | "processing" | "completed" | "failed";
+    status: StreamStatus;
     detail?: string;
 } | {
     type: "warning";

package/package.json

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