@tangle-network/agent-interface 0.53.0 → 0.55.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-interactive.d.ts

@@ -0,0 +1,416 @@
+import { z } from "zod";
+import type { AgentTerminalSession } from "./environment-terminal.js";
+import { type AgentExactRunControlRef } from "./runtime-control.js";
+declare const AgentInteractiveSessionRunCoordinatesSchema: z.ZodObject<{
+    provider: z.ZodString;
+    environmentId: z.ZodString;
+    sessionId: z.ZodString;
+    executionId: z.ZodString;
+}, z.core.$strict>;
+export type AgentInteractiveSessionRunCoordinates = z.infer<typeof AgentInteractiveSessionRunCoordinatesSchema>;
+/**
+ * Durable identity of one coding-agent TUI.
+ *
+ * This reference identifies the exact admitted run and effective profile.
+ * It is not a generic shell id and cannot be used to create another process.
+ */
+export declare const AgentInteractiveSessionRefSchema: z.ZodObject<{
+    run: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodString;
+        executionId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+    requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    admittedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    incarnationId: z.ZodString;
+    harness: z.ZodEnum<{
+        "claude-code": "claude-code";
+        nanoclaw: "nanoclaw";
+        codex: "codex";
+        opencode: "opencode";
+        "kimi-code": "kimi-code";
+        pi: "pi";
+        prime: "prime";
+        gemini: "gemini";
+        hermes: "hermes";
+        openclaw: "openclaw";
+        amp: "amp";
+        "factory-droids": "factory-droids";
+        forge: "forge";
+        cursor: "cursor";
+        acp: "acp";
+        "cli-base": "cli-base";
+    }>;
+    startedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AgentInteractiveSessionRef = z.infer<typeof AgentInteractiveSessionRefSchema>;
+/** Start one native coding-agent TUI for an already admitted run. */
+export declare const AgentInteractiveSessionStartSchema: z.ZodObject<{
+    run: z.ZodObject<{
+        runId: z.ZodString;
+        provider: z.ZodString;
+        environmentId: z.ZodString;
+        sessionId: z.ZodString;
+        executionId: z.ZodString;
+        requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>;
+    profile: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        prompt: z.ZodOptional<z.ZodObject<{
+            systemPrompt: z.ZodOptional<z.ZodString>;
+            appendSystemPrompt: z.ZodOptional<z.ZodString>;
+            instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        model: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
+            small: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodString>;
+            reasoningEffort: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                ultracode: "ultracode";
+            }>>;
+            maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+            maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+            maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        }, z.core.$strict>>;
+        harness: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            nanoclaw: "nanoclaw";
+            codex: "codex";
+            opencode: "opencode";
+            "kimi-code": "kimi-code";
+            pi: "pi";
+            prime: "prime";
+            gemini: "gemini";
+            hermes: "hermes";
+            openclaw: "openclaw";
+            amp: "amp";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            cursor: "cursor";
+            acp: "acp";
+            "cli-base": "cli-base";
+        }>>;
+        permissions: z.ZodOptional<z.ZodType<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown, z.core.$ZodTypeInternals<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown>>>;
+        tools: z.ZodOptional<z.ZodType<Record<string, boolean>, unknown, z.core.$ZodTypeInternals<Record<string, boolean>, unknown>>>;
+        mcp: z.ZodOptional<z.ZodType<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown, z.core.$ZodTypeInternals<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown>>>;
+        connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            connectionId: z.ZodString;
+            capabilities: z.ZodArray<z.ZodString>;
+            alias: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        subagents: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                resource: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"inline">;
+                    name: z.ZodString;
+                    content: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"github">;
+                    repository: z.ZodOptional<z.ZodString>;
+                    path: z.ZodString;
+                    ref: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>;
+                executable: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            skills: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            commands: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>]>>;
+            failOnError: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        hooks: z.ZodOptional<z.ZodType<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "raw" | "bearer" | undefined;
+            }> | undefined;
+        }[]>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "raw" | "bearer" | undefined;
+            }> | undefined;
+        }[]>, unknown>>>;
+        modes: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        confidential: z.ZodOptional<z.ZodObject<{
+            tee: z.ZodOptional<z.ZodString>;
+            attestationNonce: z.ZodOptional<z.ZodString>;
+            sealed: z.ZodOptional<z.ZodBoolean>;
+            attestationRefresh: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
+    }, z.core.$strict>;
+    requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    initialPrompt: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    cols: z.ZodOptional<z.ZodNumber>;
+    rows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentInteractiveSessionStart = z.infer<typeof AgentInteractiveSessionStartSchema>;
+export type AgentInteractiveSessionStartInput = Omit<AgentInteractiveSessionStart, "run">;
+/** Digest the exact process-start request independently of its derived run id. */
+export declare function agentInteractiveSessionRequestDigest(coordinates: AgentInteractiveSessionRunCoordinates, input: AgentInteractiveSessionStartInput): `sha256:${string}`;
+/** Mint the one exact run reference a provider must acknowledge for this start. */
+export declare function agentInteractiveSessionRunRef(coordinates: AgentInteractiveSessionRunCoordinates, input: AgentInteractiveSessionStartInput): AgentExactRunControlRef;
+/** Geometry for one attachment to the existing coding-agent TUI. */
+export declare const AgentInteractiveSessionAttachSchema: z.ZodObject<{
+    cols: z.ZodOptional<z.ZodNumber>;
+    rows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AgentInteractiveSessionAttach = z.infer<typeof AgentInteractiveSessionAttachSchema>;
+/** Provider-observed lifecycle of one native coding-agent TUI. */
+export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"running">;
+    ref: z.ZodObject<{
+        run: z.ZodObject<{
+            runId: z.ZodString;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            executionId: z.ZodString;
+            requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+        requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        admittedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        incarnationId: z.ZodString;
+        harness: z.ZodEnum<{
+            "claude-code": "claude-code";
+            nanoclaw: "nanoclaw";
+            codex: "codex";
+            opencode: "opencode";
+            "kimi-code": "kimi-code";
+            pi: "pi";
+            prime: "prime";
+            gemini: "gemini";
+            hermes: "hermes";
+            openclaw: "openclaw";
+            amp: "amp";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            cursor: "cursor";
+            acp: "acp";
+            "cli-base": "cli-base";
+        }>;
+        startedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"exited">;
+    ref: z.ZodObject<{
+        run: z.ZodObject<{
+            runId: z.ZodString;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            executionId: z.ZodString;
+            requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+        requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        admittedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        incarnationId: z.ZodString;
+        harness: z.ZodEnum<{
+            "claude-code": "claude-code";
+            nanoclaw: "nanoclaw";
+            codex: "codex";
+            opencode: "opencode";
+            "kimi-code": "kimi-code";
+            pi: "pi";
+            prime: "prime";
+            gemini: "gemini";
+            hermes: "hermes";
+            openclaw: "openclaw";
+            amp: "amp";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            cursor: "cursor";
+            acp: "acp";
+            "cli-base": "cli-base";
+        }>;
+        startedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    endedAt: z.ZodISODateTime;
+    reason: z.ZodEnum<{
+        exited: "exited";
+        stopped: "stopped";
+        lost: "lost";
+    }>;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    exitSignal: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"unknown">;
+    ref: z.ZodObject<{
+        run: z.ZodObject<{
+            runId: z.ZodString;
+            provider: z.ZodString;
+            environmentId: z.ZodString;
+            sessionId: z.ZodString;
+            executionId: z.ZodString;
+            requestDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>;
+        requestedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        admittedProfileDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        incarnationId: z.ZodString;
+        harness: z.ZodEnum<{
+            "claude-code": "claude-code";
+            nanoclaw: "nanoclaw";
+            codex: "codex";
+            opencode: "opencode";
+            "kimi-code": "kimi-code";
+            pi: "pi";
+            prime: "prime";
+            gemini: "gemini";
+            hermes: "hermes";
+            openclaw: "openclaw";
+            amp: "amp";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            cursor: "cursor";
+            acp: "acp";
+            "cli-base": "cli-base";
+        }>;
+        startedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    message: z.ZodString;
+    retryable: z.ZodBoolean;
+}, z.core.$strict>], "state">;
+export type AgentInteractiveSessionStatus = z.infer<typeof AgentInteractiveSessionStatusSchema>;
+/**
+ * Exact native TUI selected for one run.
+ *
+ * `attach` reaches the existing process. It never creates a shell or starts a
+ * second coding-agent process. Detach and terminal close affect only the live
+ * socket; `stop` terminates the provider-owned coding-agent process.
+ */
+export interface AgentInteractiveSession {
+    readonly ref: AgentInteractiveSessionRef;
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionStatus>;
+    attach(request?: AgentInteractiveSessionAttach, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentTerminalSession>;
+    sendPrompt?(prompt: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    stop(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionStatus>;
+}
+/** Parse a start request and prove its profile identity before provider work. */
+export declare function exactAgentInteractiveSessionStart(value: AgentInteractiveSessionStart): AgentInteractiveSessionStart;
+/** Prove that a provider returned the exact run, profile, and runner requested. */
+export declare function agentInteractiveSessionRefMatchesStart(request: AgentInteractiveSessionStart, ref: AgentInteractiveSessionRef): boolean;
+/** Prove that a status belongs to the handle that requested it. */
+export declare function agentInteractiveSessionStatusMatchesRef(ref: AgentInteractiveSessionRef, status: AgentInteractiveSessionStatus): boolean;
+export {};

package/dist/environment-interactive.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import { canonicalCandidateDigest, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { canonicalAgentProfileDigest } from "./agent-execution-preparation.js";
+import { boundedIdentifierSchema, boundedStringSchema, } from "./contract-limits.js";
+import { harnessTypeSchema } from "./harness.js";
+import { agentProfileSchema } from "./profile-schema.js";
+import { AgentExactRunControlRefSchema, } from "./runtime-control.js";
+const INTERACTIVE_MAX_DIMENSION = 10_000;
+const interactiveDimensionSchema = z
+    .number()
+    .int()
+    .positive()
+    .max(INTERACTIVE_MAX_DIMENSION);
+const AgentInteractiveSessionRunCoordinatesSchema = z.strictObject({
+    provider: boundedIdentifierSchema,
+    environmentId: boundedIdentifierSchema,
+    sessionId: boundedIdentifierSchema,
+    executionId: boundedIdentifierSchema,
+});
+/**
+ * Durable identity of one coding-agent TUI.
+ *
+ * This reference identifies the exact admitted run and effective profile.
+ * It is not a generic shell id and cannot be used to create another process.
+ */
+export const AgentInteractiveSessionRefSchema = z.strictObject({
+    run: AgentExactRunControlRefSchema,
+    /** Canonical digest of the AgentProfile submitted by the caller. */
+    requestedProfileDigest: sha256DigestSchema,
+    /** Canonical digest of the effective profile the provider admitted. */
+    admittedProfileDigest: sha256DigestSchema,
+    /** Provider-issued identity of this exact process incarnation. */
+    incarnationId: boundedIdentifierSchema,
+    harness: harnessTypeSchema,
+    startedAt: z.iso.datetime().max(64),
+});
+/** Start one native coding-agent TUI for an already admitted run. */
+export const AgentInteractiveSessionStartSchema = z.strictObject({
+    run: AgentExactRunControlRefSchema,
+    profile: agentProfileSchema,
+    requestedProfileDigest: sha256DigestSchema,
+    initialPrompt: boundedStringSchema.optional(),
+    cwd: boundedStringSchema.min(1).optional(),
+    cols: interactiveDimensionSchema.optional(),
+    rows: interactiveDimensionSchema.optional(),
+});
+/** Digest the exact process-start request independently of its derived run id. */
+export function agentInteractiveSessionRequestDigest(coordinates, input) {
+    const exactCoordinates = AgentInteractiveSessionRunCoordinatesSchema.parse(coordinates);
+    const exactInput = AgentInteractiveSessionStartSchema.omit({ run: true }).parse(input);
+    return canonicalCandidateDigest({
+        kind: "agent-interactive-session-start.v1",
+        run: exactCoordinates,
+        requestedProfileDigest: exactInput.requestedProfileDigest,
+        ...(exactInput.initialPrompt === undefined
+            ? {}
+            : { initialPrompt: exactInput.initialPrompt }),
+        ...(exactInput.cwd === undefined ? {} : { cwd: exactInput.cwd }),
+        ...(exactInput.cols === undefined ? {} : { cols: exactInput.cols }),
+        ...(exactInput.rows === undefined ? {} : { rows: exactInput.rows }),
+    });
+}
+/** Mint the one exact run reference a provider must acknowledge for this start. */
+export function agentInteractiveSessionRunRef(coordinates, input) {
+    const exactCoordinates = AgentInteractiveSessionRunCoordinatesSchema.parse(coordinates);
+    const requestDigest = agentInteractiveSessionRequestDigest(exactCoordinates, input);
+    return AgentExactRunControlRefSchema.parse({
+        ...exactCoordinates,
+        runId: `interactive-run-${requestDigest.slice("sha256:".length)}`,
+        requestDigest,
+    });
+}
+/** Geometry for one attachment to the existing coding-agent TUI. */
+export const AgentInteractiveSessionAttachSchema = z.strictObject({
+    cols: interactiveDimensionSchema.optional(),
+    rows: interactiveDimensionSchema.optional(),
+});
+/** Provider-observed lifecycle of one native coding-agent TUI. */
+export const AgentInteractiveSessionStatusSchema = z.discriminatedUnion("state", [
+    z.strictObject({
+        state: z.literal("running"),
+        ref: AgentInteractiveSessionRefSchema,
+    }),
+    z.strictObject({
+        state: z.literal("exited"),
+        ref: AgentInteractiveSessionRefSchema,
+        endedAt: z.iso.datetime().max(64),
+        reason: z.enum(["exited", "stopped", "lost"]),
+        exitCode: z.number().int().optional(),
+        exitSignal: boundedStringSchema.min(1).optional(),
+    }),
+    z.strictObject({
+        state: z.literal("unknown"),
+        ref: AgentInteractiveSessionRefSchema,
+        message: boundedStringSchema.min(1),
+        retryable: z.boolean(),
+    }),
+]);
+/** Parse a start request and prove its profile identity before provider work. */
+export function exactAgentInteractiveSessionStart(value) {
+    const parsed = AgentInteractiveSessionStartSchema.parse(value);
+    if (parsed.profile.harness === undefined) {
+        throw new Error("interactive agent sessions require AgentProfile.harness");
+    }
+    const digest = canonicalAgentProfileDigest(parsed.profile);
+    if (digest !== parsed.requestedProfileDigest) {
+        throw new Error("interactive agent session requested profile digest does not match its profile");
+    }
+    const { run, ...input } = parsed;
+    const expectedRun = agentInteractiveSessionRunRef(runCoordinates(run), input);
+    if (!sameExactRun(run, expectedRun)) {
+        throw new Error("interactive agent session run identity does not match its start request");
+    }
+    return parsed;
+}
+/** Prove that a provider returned the exact run, profile, and runner requested. */
+export function agentInteractiveSessionRefMatchesStart(request, ref) {
+    const parsedRequest = AgentInteractiveSessionStartSchema.safeParse(request);
+    const parsedRef = AgentInteractiveSessionRefSchema.safeParse(ref);
+    if (!parsedRequest.success || !parsedRef.success)
+        return false;
+    const harness = parsedRequest.data.profile.harness;
+    if (harness === undefined)
+        return false;
+    return (parsedRef.data.requestedProfileDigest ===
+        parsedRequest.data.requestedProfileDigest &&
+        parsedRef.data.harness === harness &&
+        sameExactRun(parsedRef.data.run, parsedRequest.data.run));
+}
+/** Prove that a status belongs to the handle that requested it. */
+export function agentInteractiveSessionStatusMatchesRef(ref, status) {
+    const parsedRef = AgentInteractiveSessionRefSchema.safeParse(ref);
+    const parsedStatus = AgentInteractiveSessionStatusSchema.safeParse(status);
+    if (!parsedRef.success || !parsedStatus.success)
+        return false;
+    const observed = parsedStatus.data.ref;
+    return (observed.requestedProfileDigest === parsedRef.data.requestedProfileDigest &&
+        observed.admittedProfileDigest === parsedRef.data.admittedProfileDigest &&
+        observed.incarnationId === parsedRef.data.incarnationId &&
+        observed.harness === parsedRef.data.harness &&
+        observed.startedAt === parsedRef.data.startedAt &&
+        sameExactRun(observed.run, parsedRef.data.run));
+}
+function sameExactRun(left, right) {
+    return (left.runId === right.runId &&
+        left.provider === right.provider &&
+        left.environmentId === right.environmentId &&
+        left.sessionId === right.sessionId &&
+        left.executionId === right.executionId &&
+        left.requestDigest === right.requestDigest);
+}
+function runCoordinates(run) {
+    return {
+        provider: run.provider,
+        environmentId: run.environmentId,
+        sessionId: run.sessionId,
+        executionId: run.executionId,
+    };
+}

package/dist/environment-observation.d.ts

@@ -107,8 +107,8 @@ export declare const AgentEnvironmentStatusSchema: z.ZodEnum<{
     expired: "expired";
     pending: "pending";
     running: "running";
-    provisioning: "provisioning";
     stopped: "stopped";
+    provisioning: "provisioning";
 }>;
 /** Lifecycle, cleanup, continuity, and persistence of one environment. */
 export declare const EnvironmentLifecycleSchema: z.ZodObject<{
@@ -118,8 +118,8 @@ export declare const EnvironmentLifecycleSchema: z.ZodObject<{
         expired: "expired";
         pending: "pending";
         running: "running";
-        provisioning: "provisioning";
         stopped: "stopped";
+        provisioning: "provisioning";
     }>;
     cleanup: z.ZodOptional<z.ZodObject<{
         policy: z.ZodOptional<z.ZodEnum<{
@@ -135,8 +135,8 @@ export declare const EnvironmentLifecycleSchema: z.ZodObject<{
         resumable: z.ZodBoolean;
         mode: z.ZodOptional<z.ZodEnum<{
             none: "none";
-            native: "native";
             replayed: "replayed";
+            native: "native";
         }>>;
     }, z.core.$strict>>;
     persistence: z.ZodOptional<z.ZodObject<{
@@ -443,8 +443,8 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 expired: "expired";
                 pending: "pending";
                 running: "running";
-                provisioning: "provisioning";
                 stopped: "stopped";
+                provisioning: "provisioning";
             }>;
             cleanup: z.ZodOptional<z.ZodObject<{
                 policy: z.ZodOptional<z.ZodEnum<{
@@ -460,8 +460,8 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 resumable: z.ZodBoolean;
                 mode: z.ZodOptional<z.ZodEnum<{
                     none: "none";
-                    native: "native";
                     replayed: "replayed";
+                    native: "native";
                 }>>;
             }, z.core.$strict>>;
             persistence: z.ZodOptional<z.ZodObject<{
@@ -491,8 +491,8 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 expired: "expired";
                 pending: "pending";
                 running: "running";
-                provisioning: "provisioning";
                 stopped: "stopped";
+                provisioning: "provisioning";
             }>;
             cleanup: z.ZodOptional<z.ZodObject<{
                 policy: z.ZodOptional<z.ZodEnum<{
@@ -508,8 +508,8 @@ export declare const AgentEnvironmentObservationSchema: z.ZodObject<{
                 resumable: z.ZodBoolean;
                 mode: z.ZodOptional<z.ZodEnum<{
                     none: "none";
-                    native: "native";
                     replayed: "replayed";
+                    native: "native";
                 }>>;
             }, z.core.$strict>>;
             persistence: z.ZodOptional<z.ZodObject<{

package/dist/environment-provider.d.ts

@@ -1,5 +1,6 @@
 export * from "./environment-requests.js";
 export * from "./environment-exact-process.js";
+export * from "./environment-interactive.js";
 export * from "./environment-observation.js";
 export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";

package/dist/environment-provider.js

@@ -1,5 +1,6 @@
 export * from "./environment-requests.js";
 export * from "./environment-exact-process.js";
+export * from "./environment-interactive.js";
 export * from "./environment-observation.js";
 export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";

package/dist/environment-runtime.d.ts

@@ -10,6 +10,7 @@ import type { AgentWorkspaceBranching } from "./workspace-branching.js";
 import type { AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSessionStatus, CheckpointRef, CheckpointRequest, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from "./environment-requests.js";
 import type { AgentExactProcessEgressMode, AgentExactProcessProvider } from "./environment-exact-process.js";
 import type { AgentEnvironmentObservation } from "./environment-observation.js";
+import type { AgentInteractiveSession, AgentInteractiveSessionRef, AgentInteractiveSessionStart } from "./environment-interactive.js";
 import type { AgentTerminalSession, TerminalAttachRequest, TerminalAttachResult } from "./environment-terminal.js";
 export interface AgentTurnInput {
     prompt?: string;
@@ -237,11 +238,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>;
@@ -692,6 +689,12 @@ export interface AgentEnvironment {
     terminal?(terminalSessionId: string, options?: {
         signal?: AbortSignal;
     }): AgentTerminalSession;
+    /** Start one native coding-agent TUI bound to an exact admitted run. */
+    startInteractive?(request: AgentInteractiveSessionStart, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionRef>;
+    /** Reconstruct the exact native coding-agent TUI named by a durable reference. */
+    interactive?(ref: AgentInteractiveSessionRef): AgentInteractiveSession;
     refresh?(options?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -770,6 +773,17 @@ export interface AgentEnvironmentCapabilities {
         resize: boolean;
         reattach: boolean;
     };
+    /** Present only when the provider can start and rediscover exact agent TUIs. */
+    interactiveAgent?: {
+        start: boolean;
+        status: boolean;
+        attach: boolean;
+        reattach: boolean;
+        sendPrompt: boolean;
+        input: boolean;
+        resize: boolean;
+        stop: boolean;
+    };
 }
 /** Strict runtime validator for provider capability negotiation. */
 export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
@@ -879,6 +893,16 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
         resize: z.ZodBoolean;
         reattach: z.ZodBoolean;
     }, z.core.$strict>>;
+    interactiveAgent: z.ZodOptional<z.ZodObject<{
+        start: z.ZodBoolean;
+        status: z.ZodBoolean;
+        attach: z.ZodBoolean;
+        reattach: z.ZodBoolean;
+        sendPrompt: z.ZodBoolean;
+        input: z.ZodBoolean;
+        resize: z.ZodBoolean;
+        stop: z.ZodBoolean;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export interface CreateAgentEnvironmentInput {
     profile: AgentProfileRef;

package/dist/environment-runtime.js

@@ -189,6 +189,18 @@ export const AgentEnvironmentCapabilitiesSchema = z
         reattach: z.boolean(),
     })
         .optional(),
+    interactiveAgent: z
+        .strictObject({
+        start: z.boolean(),
+        status: z.boolean(),
+        attach: z.boolean(),
+        reattach: z.boolean(),
+        sendPrompt: z.boolean(),
+        input: z.boolean(),
+        resize: z.boolean(),
+        stop: z.boolean(),
+    })
+        .optional(),
 })
     .superRefine((capabilities, refinement) => {
     if (capabilities.retainedControl !== undefined &&
@@ -249,6 +261,31 @@ export const AgentEnvironmentCapabilitiesSchema = z
             message: "interactive terminal input, resize, and reattach each require attach",
         });
     }
+    const interactiveAgent = capabilities.interactiveAgent;
+    if (interactiveAgent !== undefined &&
+        (interactiveAgent.status ||
+            interactiveAgent.attach ||
+            interactiveAgent.reattach ||
+            interactiveAgent.sendPrompt ||
+            interactiveAgent.input ||
+            interactiveAgent.resize ||
+            interactiveAgent.stop) &&
+        !interactiveAgent.start) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["interactiveAgent"],
+            message: "interactive agent status, attach, reattach, sendPrompt, input, resize, and stop each require start",
+        });
+    }
+    if (interactiveAgent !== undefined &&
+        (interactiveAgent.reattach || interactiveAgent.input || interactiveAgent.resize) &&
+        !interactiveAgent.attach) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["interactiveAgent"],
+            message: "interactive agent reattach, input, and resize each require attach",
+        });
+    }
     const extensions = capabilities.profile.extensions;
     if (extensions && new Set(extensions).size !== extensions.length) {
         refinement.addIssue({

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, TerminalReplayWindowSchema, 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, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, 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, TerminalReplayWindowSchema, 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, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, 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

@@ -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.55.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",