@tangle-network/agent-interface 0.53.0 → 0.54.0

package/README.md

@@ -17,7 +17,8 @@ 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.
+`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.
@@ -116,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

@@ -237,11 +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.ZodObject<{
-        permission: z.ZodOptional<z.ZodBoolean>;
-        question: z.ZodOptional<z.ZodBoolean>;
-        plan: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strict>>;
+    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/interaction-permissions.d.ts

@@ -10,17 +10,14 @@ export declare const InteractionKind: {
 };
 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>;
+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,11 +11,27 @@ 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(),
+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";

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.53.0",
+  "version": "0.54.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",