@tangle-network/agent-interface 0.52.0 → 0.53.0

package/README.md

@@ -17,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/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/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/package.json

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