@tangle-network/agent-interface 0.52.0 → 0.54.0

package/README.md

@@ -17,6 +17,10 @@ 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 bounded per-turn posture for well-known and namespaced provider interaction kinds.
+`permission`, `question`, and `plan` keep portable meanings across providers.
+`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.
@@ -113,6 +117,10 @@ const provider: AgentEnvironmentProvider = {
 };
 ```
 
+When caller environment values merge into a bridge or harness process, reject names for which `isRuntimeProcessControlEnvironmentName(name)` returns `true`.
+Use `isCredentialBearingProfileConfigName(name)` before retaining public config.
+These checks do not apply to a replacement environment owned by caller code.
+
 ## Exact process environments
 
 Providers may expose the optional `exactProcess` capability for isolated, reproducible process execution.

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,7 @@ 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.ZodRecord<z.ZodString, z.ZodBoolean>>;
     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,15 @@ 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 = Readonly<Record<string, boolean | undefined>>;
+/**
+ * Bounded per-turn interaction posture.
+ *
+ * The well-known keys above provide portable behavior. Namespaced keys let a
+ * provider extension use the same request, response, and replay protocol.
+ */
+export declare const RequestedInteractionsSchema: z.ZodRecord<z.ZodString, z.ZodBoolean>;
 /** 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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CONTRACT_MAX_MAP_ENTRIES, boundedIdentifierSchema, } from "./contract-limits.js";
 // =============================================================================
 // Well-known kinds + helpers.
 // =============================================================================
@@ -10,6 +11,28 @@ export const InteractionKind = {
     /** Agent shares a plan/todo list for review/approval. */
     Plan: "plan",
 };
+const wellKnownInteractionKinds = new Set(Object.values(InteractionKind));
+const requestedInteractionKindSchema = boundedIdentifierSchema.refine((value) => wellKnownInteractionKinds.has(value) ||
+    (value.includes(".") &&
+        !value.startsWith(".") &&
+        !value.endsWith(".") &&
+        !value.includes("..")), "custom interaction kind must be namespaced");
+/**
+ * Bounded per-turn interaction posture.
+ *
+ * The well-known keys above provide portable behavior. Namespaced keys let a
+ * provider extension use the same request, response, and replay protocol.
+ */
+export const RequestedInteractionsSchema = z
+    .record(requestedInteractionKindSchema, z.boolean())
+    .superRefine((value, context) => {
+    if (Object.keys(value).length > CONTRACT_MAX_MAP_ENTRIES) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `interaction posture exceeds ${CONTRACT_MAX_MAP_ENTRIES} kinds`,
+        });
+    }
+});
 /** 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/profile-schema.d.ts

@@ -177,6 +177,8 @@ export declare const agentProfilePromptSchema: z.ZodObject<{
     appendSystemPrompt: z.ZodOptional<z.ZodString>;
     instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
+/** Return true when a public config name denotes credential material. */
+export declare function isCredentialBearingProfileConfigName(name: string): boolean;
 export declare const agentProfilePublicConfigValueSchema: z.ZodObject<{
     kind: z.ZodLiteral<"public">;
     value: z.ZodString;

package/dist/profile-schema.js

@@ -143,6 +143,10 @@ export const agentProfilePromptSchema = z.strictObject({
 });
 const controlCharacterPattern = /[\u0000-\u001f\u007f]/;
 const secretCapableNamePattern = /(?:^|[_-])(?:api[_-]?key|access[_-]?key|private[_-]?key|token|secret|password|credentials?|authorization|cookie|database[_-]?url|dsn|pat)(?:[_-]|$)/i;
+/** Return true when a public config name denotes credential material. */
+export function isCredentialBearingProfileConfigName(name) {
+    return secretCapableNamePattern.test(name);
+}
 const publicProfileConfigStringSchema = z
     .string()
     .refine((value) => isWellFormedUnicode(value) &&
@@ -181,7 +185,7 @@ function profileConfigRecordSchema(keySchema) {
                 });
             }
             if (value.kind === "public" &&
-                secretCapableNamePattern.test(name)) {
+                isCredentialBearingProfileConfigName(name)) {
                 context.addIssue({
                     code: "custom",
                     path: [name],

package/dist/profile-security.d.ts

@@ -17,6 +17,13 @@
  * application boundary where profiles are still provider-neutral.
  */
 import type { AgentProfile, AgentProfileValidationResult } from "./agent-profile.js";
+/**
+ * Return true when an environment name can alter its owning runtime process.
+ *
+ * Apply this check when caller values merge into a bridge, sidecar, or harness
+ * process. Do not apply it to a replacement environment for caller-owned code.
+ */
+export declare function isRuntimeProcessControlEnvironmentName(name: string): boolean;
 /** Policy for {@link validateAgentProfileSecurity}. */
 export interface AgentProfileSecurityPolicy {
     /**

package/dist/profile-security.js

@@ -16,6 +16,78 @@
  * own profile shape and is a different layer; this is the one to use at the
  * application boundary where profiles are still provider-neutral.
  */
+const runtimeProcessControlEnvironmentNames = new Set([
+    "ALL_PROXY",
+    "BASH_ENV",
+    "CDPATH",
+    "COMSPEC",
+    "CURL_CA_BUNDLE",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "ENV",
+    "GEM_HOME",
+    "GEM_PATH",
+    "GIT_ASKPASS",
+    "GIT_PROXY_COMMAND",
+    "GIT_SSH_COMMAND",
+    "GIT_SSL_NO_VERIFY",
+    "HOME",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "IFS",
+    "LD_AUDIT",
+    "LD_LIBRARY_PATH",
+    "LD_PRELOAD",
+    "LOGNAME",
+    "NODE_EXTRA_CA_CERTS",
+    "NODE_OPTIONS",
+    "NODE_PATH",
+    "NODE_TLS_REJECT_UNAUTHORIZED",
+    "NO_PROXY",
+    "NVM_DIR",
+    "PATH",
+    "PERL5LIB",
+    "PERL5OPT",
+    "PNPM_HOME",
+    "PROMPT_COMMAND",
+    "PWD",
+    "PYTHONHOME",
+    "PYTHONPATH",
+    "PYTHONSTARTUP",
+    "REQUESTS_CA_BUNDLE",
+    "RUBYLIB",
+    "RUBYOPT",
+    "SHELL",
+    "SHELLOPTS",
+    "SSH_ASKPASS",
+    "SSL_CERT_DIR",
+    "SSL_CERT_FILE",
+    "SSLKEYLOGFILE",
+    "TEMP",
+    "TMP",
+    "TMPDIR",
+    "USER",
+    "USERPROFILE",
+    "XDG_CACHE_HOME",
+    "XDG_CONFIG_HOME",
+    "XDG_DATA_HOME",
+    "XDG_RUNTIME_DIR",
+    "XDG_STATE_HOME",
+]);
+/**
+ * Return true when an environment name can alter its owning runtime process.
+ *
+ * Apply this check when caller values merge into a bridge, sidecar, or harness
+ * process. Do not apply it to a replacement environment for caller-owned code.
+ */
+export function isRuntimeProcessControlEnvironmentName(name) {
+    const normalized = name.toUpperCase();
+    return (runtimeProcessControlEnvironmentNames.has(normalized) ||
+        normalized.startsWith("DYLD_") ||
+        normalized.startsWith("GIT_CONFIG_") ||
+        normalized.endsWith("_PROXY"));
+}
 /**
  * Default cloud policy: block the two unattended-code surfaces (local MCP,
  * hooks); leave remote MCP and everything else to the profile. Deliberately

package/package.json

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