@tangle-network/agent-provider-tangle 0.11.3 → 0.12.0

package/dist/tangle-capabilities.d.ts

@@ -37,6 +37,8 @@ export interface SandboxCapabilitySupport {
     observation: ObservationSurfaceSupport;
     /** The sandbox serves the PTY socket and reports terminal metadata. */
     interactiveTerminal: boolean;
+    /** The SDK can drive the existing native TUI and read its terminal metadata. */
+    interactiveAgent: boolean;
 }
 export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike, requestedResources?: ResourceProfile): SandboxCapabilitySupport;
 /**
@@ -74,6 +76,8 @@ export declare function tangleRetainedControlSupported(declared: AgentEnvironmen
  * running agent.
  */
 export declare function tangleInteractionResponsesSupported(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): boolean;
+/** Decide whether exact native-TUI control is both callable and deployed. */
+export declare function tangleInteractiveAgentSupported(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): boolean;
 /**
  * Narrow a declared capability document to established facts.
  *

package/dist/tangle-capabilities.js

@@ -1,8 +1,9 @@
 import { harnessSystemPromptIntents } from "@tangle-network/agent-interface";
 import { SandboxInstance } from "@tangle-network/sandbox";
-import { ADAPTER_CEILING_DEPLOYMENT, deploymentBacksRetainedControl, } from "./tangle-deployment-capabilities.js";
+import { ADAPTER_CEILING_DEPLOYMENT, deploymentBacksInteractiveAgent, deploymentBacksRetainedControl, } from "./tangle-deployment-capabilities.js";
 import { clientObservationSurfaceSupport, observationSurfaceSupport, } from "./tangle-observation.js";
 import { sandboxBacksInteractiveTerminal } from "./tangle-terminal.js";
+import { sandboxBacksInteractiveAgent } from "./tangle-interactive.js";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
@@ -100,6 +101,17 @@ export function defaultTangleSandboxCapabilities(harness) {
             resize: true,
             reattach: true,
         },
+        interactiveAgent: {
+            start: true,
+            status: true,
+            attach: true,
+            reattach: true,
+            control: true,
+            sendPrompt: true,
+            input: true,
+            resize: true,
+            stop: true,
+        },
     };
 }
 // One reserved id names both probe handles; neither ever reaches the service.
@@ -129,6 +141,7 @@ export function sandboxCapabilitySupport(box, client, requestedResources) {
         respondToInteraction: typeof session?.respondToInteraction === "function",
         observation: observationSurfaceSupport(box, client, requestedResources),
         interactiveTerminal: sandboxBacksInteractiveTerminal(box),
+        interactiveAgent: sandboxBacksInteractiveAgent(box),
     };
 }
 /**
@@ -188,6 +201,7 @@ export function clientCapabilitySupport(client) {
         respondToInteraction: false,
         observation,
         interactiveTerminal: true,
+        interactiveAgent: false,
     };
 }
 /**
@@ -230,6 +244,12 @@ export function tangleInteractionResponsesSupported(declared, support, deploymen
         support.session &&
         support.respondToInteraction);
 }
+/** Decide whether exact native-TUI control is both callable and deployed. */
+export function tangleInteractiveAgentSupported(declared, support, deployment) {
+    return (declared.interactiveAgent !== undefined &&
+        support.interactiveAgent &&
+        deploymentBacksInteractiveAgent(deployment));
+}
 /**
  * Narrow a declared capability document to established facts.
  *
@@ -294,6 +314,11 @@ export function narrowedTangleCapabilities(declared, support, deployment) {
             : {
                 interactiveTerminal: narrowedInteractiveTerminal(declared.interactiveTerminal, support.interactiveTerminal),
             }),
+        ...(declared.interactiveAgent === undefined
+            ? {}
+            : {
+                interactiveAgent: narrowedInteractiveAgent(declared.interactiveAgent, tangleInteractiveAgentSupported(declared, support, deployment)),
+            }),
     };
     // A claimed block is passed through whole. Its sub-flags state what the
     // route carries, not what one deployment reports, and the deployment's own
@@ -337,6 +362,20 @@ function narrowedInteractiveTerminal(declared, supported) {
         reattach: supported ? declared.reattach : false,
     };
 }
+/** One fact decides the exact TUI surface because partial control is unsafe. */
+function narrowedInteractiveAgent(declared, supported) {
+    return {
+        start: supported ? declared.start : false,
+        status: supported ? declared.status : false,
+        attach: supported ? declared.attach : false,
+        reattach: supported ? declared.reattach : false,
+        control: supported ? declared.control : false,
+        sendPrompt: supported ? declared.sendPrompt : false,
+        input: supported ? declared.input : false,
+        resize: supported ? declared.resize : false,
+        stop: supported ? declared.stop : false,
+    };
+}
 /**
  * Narrow provider-level claims to facts the client can prove before any
  * sandbox exists.

package/dist/tangle-contract-safety.d.ts

@@ -17,3 +17,5 @@ export declare function attachCleanupHandle(error: unknown, handle: unknown, cle
 export declare function exactProcessRequestDigest(input: CreateAgentExactProcessEnvironmentInput, providerName: string, options: TangleExactProcessOptions): `sha256:${string}`;
 export declare function validateExactProcessCreateInput(input: CreateAgentExactProcessEnvironmentInput, providerName: string, options: TangleExactProcessOptions): void;
 export declare function awaitWithSignal<T>(operation: Promise<T> | T | undefined, signal?: AbortSignal): Promise<T>;
+/** Await an operation and clean its result if abort wins before it resolves. */
+export declare function awaitWithSignalAndCleanup<T>(operation: () => Promise<T> | T, signal: AbortSignal | undefined, cleanup: (value: T) => Promise<void> | void): Promise<T>;

package/dist/tangle-contract-safety.js

@@ -238,3 +238,32 @@ export async function awaitWithSignal(operation, signal) {
             signal.removeEventListener("abort", listener);
     }
 }
+/** Await an operation and clean its result if abort wins before it resolves. */
+export async function awaitWithSignalAndCleanup(operation, signal, cleanup) {
+    signal?.throwIfAborted();
+    if (!signal)
+        return await operation();
+    let aborted = false;
+    let listener;
+    const observed = Promise.resolve().then(operation).then(async (value) => {
+        if (aborted)
+            await cleanup(value);
+        return value;
+    });
+    try {
+        return await Promise.race([
+            observed,
+            new Promise((_, reject) => {
+                listener = () => {
+                    aborted = true;
+                    reject(new DOMException("The operation was aborted", "AbortError"));
+                };
+                signal.addEventListener("abort", listener, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (listener)
+            signal.removeEventListener("abort", listener);
+    }
+}

package/dist/tangle-deployment-capabilities.d.ts

@@ -28,6 +28,8 @@ export interface DeploymentCapabilitySupport {
      * decides whether a response can be retried safely.
      */
     readonly interactionResponses: boolean;
+    /** Native TUI start, status, attach, control, prompt, and stop. */
+    readonly interactiveAgent: boolean;
 }
 /**
  * The deployment backs nothing.
@@ -88,3 +90,5 @@ export declare function readDeploymentCapabilitySupport(box: SandboxInstanceLike
  * cancellation idempotency.
  */
 export declare function deploymentBacksRetainedControl(deployment: DeploymentCapabilitySupport): boolean;
+/** True only when the deployment proves the complete exact native-TUI path. */
+export declare function deploymentBacksInteractiveAgent(deployment: DeploymentCapabilitySupport): boolean;

package/dist/tangle-deployment-capabilities.js

@@ -14,6 +14,7 @@ export const UNPROVEN_DEPLOYMENT = {
     eventReplay: false,
     executionScopedStatus: false,
     interactionResponses: false,
+    interactiveAgent: false,
 };
 /**
  * The client stage's deployment input: this adapter's ceiling, not a fact.
@@ -36,6 +37,7 @@ export const ADAPTER_CEILING_DEPLOYMENT = {
     eventReplay: true,
     executionScopedStatus: true,
     interactionResponses: true,
+    interactiveAgent: true,
 };
 /**
  * Read the deployment facts out of a capability document. Every flag this
@@ -53,6 +55,12 @@ export function deploymentCapabilitySupport(document) {
         eventReplay: document.runs?.eventReplay === true,
         executionScopedStatus: document.runs?.executionScopedStatus === true,
         interactionResponses: document.interactions?.responseDedupe === true,
+        interactiveAgent: document.interactiveAgent?.start === true &&
+            document.interactiveAgent?.status === true &&
+            document.interactiveAgent?.attach === true &&
+            document.interactiveAgent?.control === true &&
+            document.interactiveAgent?.sendPrompt === true &&
+            document.interactiveAgent?.stop === true,
     };
 }
 /**
@@ -104,3 +112,7 @@ export function deploymentBacksRetainedControl(deployment) {
         deployment.eventReplay &&
         deployment.executionScopedStatus);
 }
+/** True only when the deployment proves the complete exact native-TUI path. */
+export function deploymentBacksInteractiveAgent(deployment) {
+    return deployment.interactiveAgent;
+}

package/dist/tangle-environment.js

@@ -16,6 +16,7 @@ import { tangleInteractionResponder } from "./tangle-interaction-response.js";
 import { createExecutionUsageLog } from "./tangle-usage-log.js";
 import { observeTangleEnvironment } from "./tangle-observation.js";
 import { createTangleTerminalRegistry } from "./tangle-terminal.js";
+import { createTangleInteractiveAgentRegistry } from "./tangle-interactive.js";
 /**
  * Compose one concrete sandbox into an environment.
  *
@@ -59,6 +60,10 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
     const terminals = capabilities.interactiveTerminal?.attach === true
         ? createTangleTerminalRegistry(box)
         : undefined;
+    const interactiveAgents = capabilities.interactiveAgent?.start === true &&
+        capabilities.interactiveAgent.control === true
+        ? createTangleInteractiveAgentRegistry(box, providerName, environmentId)
+        : undefined;
     const dispatch = capabilities.streaming.detach && box.dispatchPrompt
         ? dispatchEnvironmentRun(box, providerName, environmentId)
         : undefined;
@@ -264,6 +269,16 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                 },
             }
             : {}),
+        ...(interactiveAgents
+            ? {
+                async startInteractive(interactiveRequest, options) {
+                    return await interactiveAgents.start(interactiveRequest, options);
+                },
+                interactive(ref) {
+                    return interactiveAgents.get(ref);
+                },
+            }
+            : {}),
         async refresh(options) {
             assertOptionKeys(options, ["signal"], "Tangle refresh");
             options?.signal?.throwIfAborted();

package/dist/tangle-failure-reason.d.ts

@@ -8,6 +8,6 @@
  * identifier, which cannot express a URL, a bearer, or whitespace.
  */
 /** Which transport read one reason describes. */
-export type TransportRead = "environment refresh" | "placement lookup" | "resource usage read" | "subscription read" | "account usage read" | "terminal attach" | "terminal acknowledgement" | "terminal metadata read" | "terminal socket";
+export type TransportRead = "environment refresh" | "placement lookup" | "resource usage read" | "subscription read" | "account usage read" | "terminal attach" | "terminal acknowledgement" | "terminal metadata read" | "terminal socket" | "interactive start" | "interactive control" | "interactive control claim" | "interactive status" | "interactive attach" | "interactive prompt" | "interactive stop";
 /** Name the read that failed and the cause, with nothing copied from it. */
 export declare function transportFailureReason(read: TransportRead, error: unknown): string;

package/dist/tangle-interactive.d.ts

@@ -0,0 +1,24 @@
+import type { AgentInteractiveSession, AgentInteractiveSessionRef, AgentInteractiveSessionStart } from "@tangle-network/agent-interface";
+import type { SandboxInstanceLike } from "./tangle-types.js";
+/** Exact coding-agent TUI operations for one sandbox environment. */
+export interface TangleInteractiveAgentRegistry {
+    start(request: AgentInteractiveSessionStart, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionRef>;
+    get(ref: AgentInteractiveSessionRef): AgentInteractiveSession;
+}
+/**
+ * Test the linked SDK surface without accepting any older interactive shape.
+ *
+ * The current public Sandbox release fails this test. That is intentional:
+ * it has no receipt, control claim, or mutation acknowledgement protocol.
+ */
+export declare function sandboxBacksInteractiveAgent(box: SandboxInstanceLike): boolean;
+/**
+ * Adapt the canonical Sandbox exact interactive API.
+ *
+ * The Sandbox owns process identity, admission receipts, operation replay,
+ * and control generations. This adapter validates each returned value and
+ * never creates a second record for any of those facts.
+ */
+export declare function createTangleInteractiveAgentRegistry(box: SandboxInstanceLike, providerName: string, environmentId: string): TangleInteractiveAgentRegistry;

package/dist/tangle-interactive.js

@@ -0,0 +1,328 @@
+import { AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStopAcknowledgementMatchesCommand, exactAgentInteractiveSessionStart, } from "@tangle-network/agent-interface";
+import { parseBackendType } from "@tangle-network/sandbox";
+import { assertOptionKeys } from "./tangle-environment-validation.js";
+import { transportFailureReason } from "./tangle-failure-reason.js";
+import { bindTangleInteractiveControl, closeTangleStreamQuietly, createTangleTerminalStreamCapture, prepareTangleTerminalAttachment, } from "./tangle-terminal.js";
+/**
+ * Test the linked SDK surface without accepting any older interactive shape.
+ *
+ * The current public Sandbox release fails this test. That is intentional:
+ * it has no receipt, control claim, or mutation acknowledgement protocol.
+ */
+export function sandboxBacksInteractiveAgent(box) {
+    if (typeof box.session !== "function")
+        return false;
+    try {
+        const candidate = box.session("__tangle-interactive-probe__").interactive?.();
+        return (isSandboxInteractiveSession(candidate) &&
+            typeof box.terminals?.get === "function");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Adapt the canonical Sandbox exact interactive API.
+ *
+ * The Sandbox owns process identity, admission receipts, operation replay,
+ * and control generations. This adapter validates each returned value and
+ * never creates a second record for any of those facts.
+ */
+export function createTangleInteractiveAgentRegistry(box, providerName, environmentId) {
+    const exactHandle = (sessionId) => {
+        const session = box.session?.(sessionId);
+        const candidate = session?.interactive?.();
+        if (!isSandboxInteractiveSession(candidate)) {
+            throw new Error("the linked Sandbox SDK does not expose the exact interactive control API");
+        }
+        return candidate;
+    };
+    const exactRef = (value) => {
+        const ref = AgentInteractiveSessionRefSchema.parse(value);
+        if (ref.run.provider !== providerName ||
+            ref.run.environmentId !== environmentId) {
+            throw new Error("the interactive agent reference belongs to a different environment");
+        }
+        return ref;
+    };
+    const assertRef = (expected, candidate) => {
+        if (expected.run.runId !== candidate.run.runId ||
+            expected.run.requestDigest !== candidate.run.requestDigest ||
+            expected.incarnationId !== candidate.incarnationId ||
+            expected.preparationReceipt.digest !== candidate.preparationReceipt.digest) {
+            throw new Error("the Sandbox returned a different interactive session ref");
+        }
+    };
+    const assertControl = (ref, control) => {
+        if (!agentInteractiveSessionControlClaimMatchesRef(ref, control)) {
+            throw new Error("the interactive control claim belongs to another process");
+        }
+        if (Date.parse(control.expiresAt) <= Date.now()) {
+            throw new Error("the interactive control claim has expired");
+        }
+    };
+    return {
+        async start(request, options) {
+            assertOptionKeys(options, ["signal"], "Tangle interactive agent start");
+            const exactRequest = exactAgentInteractiveSessionStart(request);
+            const requestedHarness = exactRequest.profile.harness;
+            if (requestedHarness === undefined) {
+                throw new Error("interactive agent sessions require AgentProfile.harness");
+            }
+            let harness;
+            try {
+                harness = parseBackendType(requestedHarness);
+            }
+            catch {
+                throw new Error("the requested AgentProfile harness has no Tangle Sandbox runner");
+            }
+            options?.signal?.throwIfAborted();
+            const handle = exactHandle(exactRequest.run.sessionId);
+            let observed;
+            try {
+                observed = await handle.start({
+                    harness,
+                    ...(exactRequest.profile.model?.default === undefined
+                        ? {}
+                        : { model: exactRequest.profile.model.default }),
+                    ...(exactRequest.cwd === undefined ? {} : { cwd: exactRequest.cwd }),
+                    ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
+                    ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
+                    profile: exactRequest.profile,
+                    ...(exactRequest.initialPrompt === undefined
+                        ? {}
+                        : { initialPrompt: exactRequest.initialPrompt }),
+                    idempotencyKey: exactRequest.run.runId,
+                    requestDigest: exactRequest.run.requestDigest,
+                });
+            }
+            catch (error) {
+                options?.signal?.throwIfAborted();
+                throw new Error(transportFailureReason("interactive start", error));
+            }
+            options?.signal?.throwIfAborted();
+            const ref = refFromStart(exactRequest, observed);
+            if (!agentInteractiveSessionRefMatchesStart(exactRequest, ref)) {
+                throw new Error("the Sandbox returned an interactive session with a different admission receipt");
+            }
+            return ref;
+        },
+        get(value) {
+            const ref = exactRef(value);
+            const handle = exactHandle(ref.run.sessionId);
+            const readStatus = async (options) => {
+                assertOptionKeys(options, ["signal"], "Tangle interactive agent status");
+                options?.signal?.throwIfAborted();
+                let observed;
+                try {
+                    observed = await handle.status();
+                }
+                catch (error) {
+                    options?.signal?.throwIfAborted();
+                    throw new Error(transportFailureReason("interactive status", error));
+                }
+                options?.signal?.throwIfAborted();
+                return statusFromSandbox(ref, observed);
+            };
+            const validateControl = async (control, options) => {
+                assertControl(ref, control);
+                options?.signal?.throwIfAborted();
+                try {
+                    await handle.validateControl(control);
+                }
+                catch (error) {
+                    options?.signal?.throwIfAborted();
+                    throw new Error(transportFailureReason("interactive control", error));
+                }
+                options?.signal?.throwIfAborted();
+            };
+            return {
+                ref,
+                async claimControl(request, options) {
+                    assertOptionKeys(options, ["signal"], "Tangle interactive control claim");
+                    const exactRequest = AgentInteractiveSessionControlClaimRequestSchema.parse(request);
+                    assertRef(ref, exactRequest.ref);
+                    options?.signal?.throwIfAborted();
+                    let raw;
+                    try {
+                        raw = await handle.claimControl(exactRequest);
+                    }
+                    catch (error) {
+                        options?.signal?.throwIfAborted();
+                        throw new Error(transportFailureReason("interactive control claim", error));
+                    }
+                    options?.signal?.throwIfAborted();
+                    const acknowledgement = AgentInteractiveSessionControlClaimAcknowledgementSchema.parse(raw);
+                    if (!agentInteractiveSessionControlClaimAcknowledgementMatchesRequest(exactRequest, acknowledgement)) {
+                        throw new Error("the Sandbox returned a control claim acknowledgement for another request");
+                    }
+                    return acknowledgement;
+                },
+                status: readStatus,
+                async attach(request, options) {
+                    assertOptionKeys(options, ["signal"], "Tangle interactive agent attach");
+                    const exactRequest = AgentInteractiveSessionAttachSchema.parse(request ?? {});
+                    await validateControl(exactRequest.control, options);
+                    const before = await readStatus(options);
+                    if (before.state !== "running") {
+                        throw new Error("the exact interactive agent session is not running");
+                    }
+                    const terminals = box.terminals;
+                    if (terminals === undefined || typeof terminals.get !== "function") {
+                        throw new Error("the Sandbox client cannot read exact interactive terminal metadata");
+                    }
+                    const capture = createTangleTerminalStreamCapture(exactRequest);
+                    let stream;
+                    try {
+                        stream = await handle.attach({
+                            control: exactRequest.control,
+                            ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
+                            ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
+                            handlers: capture.handlers,
+                        });
+                    }
+                    catch (error) {
+                        options?.signal?.throwIfAborted();
+                        throw new Error(transportFailureReason("interactive attach", error));
+                    }
+                    if (options?.signal?.aborted) {
+                        await closeTangleStreamQuietly(stream);
+                        options.signal.throwIfAborted();
+                    }
+                    const prepared = await prepareTangleTerminalAttachment({
+                        stream,
+                        capture,
+                        terminals,
+                        parentExecutionId: ref.run.executionId,
+                        expectedSessionId: ref.run.sessionId,
+                        signal: options?.signal,
+                        beforeMutation: (operation) => {
+                            if (operation === "detach")
+                                return Promise.resolve();
+                            return validateControl(exactRequest.control, options);
+                        },
+                    });
+                    if (prepared.status === "unknown") {
+                        throw new Error(prepared.message);
+                    }
+                    if (prepared.acknowledgement.restored !== true) {
+                        await prepared.session.detach();
+                        throw new Error("the exact interactive attach did not restore the coding-agent PTY");
+                    }
+                    const after = await readStatus(options);
+                    if (after.state !== "running") {
+                        await prepared.session.detach();
+                        throw new Error("the exact interactive agent exited while its terminal attached");
+                    }
+                    const terminal = bindTangleInteractiveControl(prepared.session, exactRequest.control);
+                    return terminal;
+                },
+                async sendPrompt(command, options) {
+                    assertOptionKeys(options, ["signal"], "Tangle interactive agent prompt");
+                    const exactCommand = AgentInteractiveSessionPromptCommandSchema.parse(command);
+                    assertRef(ref, exactCommand.ref);
+                    await validateControl(exactCommand.control, options);
+                    let raw;
+                    try {
+                        raw = await handle.sendPrompt(exactCommand);
+                    }
+                    catch (error) {
+                        options?.signal?.throwIfAborted();
+                        throw new Error(transportFailureReason("interactive prompt", error));
+                    }
+                    options?.signal?.throwIfAborted();
+                    const acknowledgement = AgentInteractiveSessionPromptAcknowledgementSchema.parse(raw);
+                    if (!agentInteractiveSessionPromptAcknowledgementMatchesCommand(exactCommand, acknowledgement)) {
+                        throw new Error("the Sandbox returned a prompt acknowledgement for another request");
+                    }
+                    return acknowledgement;
+                },
+                async stop(command, options) {
+                    assertOptionKeys(options, ["signal"], "Tangle interactive agent stop");
+                    const exactCommand = AgentInteractiveSessionStopCommandSchema.parse(command);
+                    assertRef(ref, exactCommand.ref);
+                    await validateControl(exactCommand.control, options);
+                    let raw;
+                    try {
+                        raw = await handle.stop(exactCommand);
+                    }
+                    catch (error) {
+                        options?.signal?.throwIfAborted();
+                        throw new Error(transportFailureReason("interactive stop", error));
+                    }
+                    options?.signal?.throwIfAborted();
+                    const acknowledgement = AgentInteractiveSessionStopAcknowledgementSchema.parse(raw);
+                    if (!agentInteractiveSessionStopAcknowledgementMatchesCommand(exactCommand, acknowledgement)) {
+                        throw new Error("the Sandbox returned a stop acknowledgement for another request");
+                    }
+                    return acknowledgement;
+                },
+            };
+        },
+    };
+}
+function isSandboxInteractiveSession(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return [
+        "start",
+        "claimControl",
+        "status",
+        "attach",
+        "validateControl",
+        "sendPrompt",
+        "stop",
+    ].every((key) => typeof candidate[key] === "function");
+}
+function refFromStart(request, observed) {
+    if (observed.sessionId !== request.run.sessionId ||
+        observed.harness !== request.profile.harness) {
+        throw new Error("the Sandbox returned a different interactive session identity");
+    }
+    return AgentInteractiveSessionRefSchema.parse({
+        run: request.run,
+        preparationReceipt: observed.preparationReceipt,
+        incarnationId: observed.incarnationId,
+        startedAt: observed.startedAt,
+    });
+}
+function statusFromSandbox(ref, observed) {
+    if (observed === null) {
+        return AgentInteractiveSessionStatusSchema.parse({
+            state: "unknown",
+            ref,
+            message: "the Sandbox no longer knows this interactive agent session",
+            retryable: false,
+        });
+    }
+    const observedRef = AgentInteractiveSessionRefSchema.parse({
+        run: ref.run,
+        preparationReceipt: observed.preparationReceipt,
+        incarnationId: observed.incarnationId,
+        startedAt: observed.startedAt,
+    });
+    if (observed.sessionId !== ref.run.sessionId ||
+        observed.harness !== ref.preparationReceipt.harness ||
+        observedRef.preparationReceipt.digest !== ref.preparationReceipt.digest) {
+        throw new Error("the Sandbox reported a different interactive agent session identity");
+    }
+    if (observed.state === "running") {
+        if (observed.streamUrl.length === 0) {
+            throw new Error("the Sandbox reported a running session without a stream");
+        }
+        return AgentInteractiveSessionStatusSchema.parse({ state: "running", ref });
+    }
+    return AgentInteractiveSessionStatusSchema.parse({
+        state: "exited",
+        ref,
+        endedAt: observed.endedAt,
+        reason: observed.reason,
+        ...(Number.isSafeInteger(observed.exitCode)
+            ? { exitCode: observed.exitCode }
+            : {}),
+        ...(typeof observed.exitSignal === "string" && observed.exitSignal.length > 0
+            ? { exitSignal: observed.exitSignal }
+            : {}),
+    });
+}

package/dist/tangle-terminal.d.ts

@@ -1,5 +1,6 @@
-import type { AgentTerminalSession, TerminalAttachRequest, TerminalAttachResult } from "@tangle-network/agent-interface";
-import type { SandboxInstanceLike } from "./tangle-types.js";
+import type { AgentInteractiveSessionControlClaim, AgentInteractiveTerminalSession, AgentTerminalSession, TerminalAttachRequest, TerminalAttachResult } from "@tangle-network/agent-interface";
+import type { SandboxInstanceLike, SandboxTerminalReadyLike, SandboxTerminalStreamLike, SandboxTerminalsLike } from "./tangle-types.js";
+import { TerminalFrameLog } from "./tangle-terminal-frames.js";
 /** Terminal handles this environment holds, keyed by terminal session id. */
 export interface TangleTerminalRegistry {
     attach(request: TerminalAttachRequest, options?: {
@@ -9,4 +10,69 @@ export interface TangleTerminalRegistry {
 }
 /** True when this sandbox backs the interactive terminal surface. */
 export declare function sandboxBacksInteractiveTerminal(box: SandboxInstanceLike): boolean;
+/** Stream state captured from handlers that are installed before attach. */
+export interface TangleTerminalStreamCapture {
+    readonly handlers: {
+        onReady(info: SandboxTerminalReadyLike): void;
+        onData(data: Uint8Array): void;
+        onExit(info: {
+            exitCode?: number;
+            exitSignal?: string;
+        }): void;
+        onError(error: Error): void;
+        onClose(): void;
+    };
+    readonly log: TerminalFrameLog;
+    readonly activity: {
+        localMs: number;
+    };
+    readonly exit: {
+        exitCode?: number;
+        exitSignal?: string;
+        seen: boolean;
+    };
+    readonly ready: SandboxTerminalReadyLike | undefined;
+}
+/** A live stream after its exact identity and runtime metadata are checked. */
+export type PreparedTangleTerminal = {
+    status: "ready";
+    session: AgentTerminalSession;
+    stream: SandboxTerminalStreamLike;
+    acknowledgement: SandboxTerminalReadyLike;
+} | {
+    status: "unknown";
+    message: string;
+    retryable: boolean;
+};
+/**
+ * Install one ordered capture before a terminal socket opens.
+ *
+ * Both generic shells and exact coding-agent sessions use this capture. This
+ * keeps replay, resize, exit, and transport ordering identical on both paths.
+ */
+export declare function createTangleTerminalStreamCapture(geometry?: {
+    cols?: number;
+    rows?: number;
+}): TangleTerminalStreamCapture;
+/**
+ * Validate one attached socket and adapt it to the shared terminal contract.
+ *
+ * The runtime acknowledgement and metadata are authoritative. A missing or
+ * different session id closes the socket and returns no usable handle.
+ */
+export declare function prepareTangleTerminalAttachment(input: {
+    stream: SandboxTerminalStreamLike;
+    capture: TangleTerminalStreamCapture;
+    terminals: SandboxTerminalsLike;
+    parentExecutionId: string;
+    expectedSessionId?: string;
+    signal?: AbortSignal;
+    beforeMutation?: (operation: "input" | "resize" | "detach" | "close") => Promise<void>;
+    attachCount?: (terminalSessionId: string) => number;
+    release?: (terminalSessionId: string, stream: SandboxTerminalStreamLike) => void;
+}): Promise<PreparedTangleTerminal>;
 export declare function createTangleTerminalRegistry(box: SandboxInstanceLike): TangleTerminalRegistry;
+/** Close a stream that has not been handed to a caller. */
+export declare function closeTangleStreamQuietly(stream: SandboxTerminalStreamLike): Promise<void>;
+/** Add the exact claim identity without replacing the terminal implementation. */
+export declare function bindTangleInteractiveControl(session: AgentTerminalSession, control: AgentInteractiveSessionControlClaim): AgentInteractiveTerminalSession;

package/dist/tangle-terminal.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { TerminalAttachRequestSchema, TerminalInputSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalSessionUsable, } from "@tangle-network/agent-interface";
 import { TerminalFrameLog } from "./tangle-terminal-frames.js";
-import { awaitWithSignal, MAX_STRING_LENGTH } from "./tangle-contract-safety.js";
+import { awaitWithSignal, awaitWithSignalAndCleanup, MAX_STRING_LENGTH, } from "./tangle-contract-safety.js";
 import { transportFailureReason } from "./tangle-failure-reason.js";
 import { assertOptionKeys } from "./tangle-environment-validation.js";
 const MAX_TERMINAL_DIMENSION = 10_000;
@@ -19,6 +19,166 @@ export function sandboxBacksInteractiveTerminal(box) {
         return false;
     }
 }
+/**
+ * Install one ordered capture before a terminal socket opens.
+ *
+ * Both generic shells and exact coding-agent sessions use this capture. This
+ * keeps replay, resize, exit, and transport ordering identical on both paths.
+ */
+export function createTangleTerminalStreamCapture(geometry) {
+    const log = new TerminalFrameLog();
+    const activity = { localMs: Date.now() };
+    const exit = {
+        seen: false,
+    };
+    const decoder = new TextDecoder();
+    let ready;
+    return {
+        log,
+        activity,
+        exit,
+        get ready() {
+            return ready;
+        },
+        handlers: {
+            onReady(info) {
+                ready = info;
+                log.append({
+                    type: "ready",
+                    ...(geometry?.cols === undefined ? {} : { cols: geometry.cols }),
+                    ...(geometry?.rows === undefined ? {} : { rows: geometry.rows }),
+                });
+            },
+            onData(data) {
+                activity.localMs = Date.now();
+                log.appendOutput(decoder.decode(data, { stream: true }));
+            },
+            onExit(info) {
+                exit.seen = true;
+                exit.exitCode = info.exitCode;
+                exit.exitSignal = info.exitSignal;
+                log.append({
+                    type: "exit",
+                    ...(Number.isSafeInteger(info.exitCode)
+                        ? { exitCode: info.exitCode }
+                        : {}),
+                    ...(typeof info.exitSignal === "string" && info.exitSignal.length > 0
+                        ? { exitSignal: info.exitSignal }
+                        : {}),
+                });
+                log.end();
+            },
+            onError(error) {
+                log.append({ type: "error", message: socketErrorFrame(error) });
+            },
+            onClose() {
+                log.end();
+            },
+        },
+    };
+}
+/**
+ * Validate one attached socket and adapt it to the shared terminal contract.
+ *
+ * The runtime acknowledgement and metadata are authoritative. A missing or
+ * different session id closes the socket and returns no usable handle.
+ */
+export async function prepareTangleTerminalAttachment(input) {
+    let streamClosed = false;
+    const closePreparedStream = async () => {
+        if (streamClosed)
+            return;
+        streamClosed = true;
+        await closeQuietly(input.stream);
+    };
+    let handedOff = false;
+    try {
+        input.signal?.throwIfAborted();
+        let acknowledgement;
+        try {
+            acknowledgement = input.capture.ready ?? input.stream.ready;
+        }
+        catch (error) {
+            await closePreparedStream();
+            return {
+                status: "unknown",
+                message: transportFailureReason("terminal acknowledgement", error),
+                retryable: true,
+            };
+        }
+        if (acknowledgement === undefined ||
+            typeof acknowledgement.sessionId !== "string" ||
+            acknowledgement.sessionId.length === 0) {
+            await closePreparedStream();
+            return {
+                status: "unknown",
+                message: "the Tangle terminal transport attached without a session id",
+                retryable: false,
+            };
+        }
+        if (input.expectedSessionId !== undefined &&
+            acknowledgement.sessionId !== input.expectedSessionId) {
+            await closePreparedStream();
+            return {
+                status: "unknown",
+                message: "the Tangle terminal transport attached a different terminal session",
+                retryable: false,
+            };
+        }
+        if (!Number.isSafeInteger(acknowledgement.detachTimeoutMs) ||
+            acknowledgement.detachTimeoutMs <= 0) {
+            await closePreparedStream();
+            return {
+                status: "unknown",
+                message: "the Tangle terminal transport reported no detach window",
+                retryable: false,
+            };
+        }
+        let info;
+        try {
+            info = await awaitWithSignal(input.terminals.get(acknowledgement.sessionId), input.signal);
+        }
+        catch (error) {
+            await closePreparedStream();
+            input.signal?.throwIfAborted();
+            return {
+                status: "unknown",
+                message: transportFailureReason("terminal metadata read", error),
+                retryable: true,
+            };
+        }
+        input.signal?.throwIfAborted();
+        if (info === null || info === undefined) {
+            await closePreparedStream();
+            return {
+                status: "unknown",
+                message: "the Tangle runtime reported no metadata for the attached terminal",
+                retryable: true,
+            };
+        }
+        const state = terminalStateFromInfo(info, acknowledgement, input.parentExecutionId, input.capture.activity.localMs);
+        if (typeof state === "string") {
+            await closePreparedStream();
+            return { status: "unknown", message: state, retryable: false };
+        }
+        state.attachCount = input.attachCount?.(state.terminalSessionId) ?? 1;
+        const session = createTangleTerminalSession(input.stream, input.capture.log, state, input.capture.activity, input.capture.exit, () => input.release?.(state.terminalSessionId, input.stream), input.beforeMutation);
+        input.signal?.throwIfAborted();
+        handedOff = true;
+        return {
+            status: "ready",
+            session,
+            stream: input.stream,
+            acknowledgement,
+        };
+    }
+    catch (error) {
+        if (!handedOff)
+            await closePreparedStream();
+        input.signal?.throwIfAborted();
+        throw error;
+    }
+}
 export function createTangleTerminalRegistry(box) {
     const attached = new Map();
     return {
@@ -46,61 +206,21 @@ export function createTangleTerminalRegistry(box) {
                 };
             }
             const connectionId = exactRequest.connectionId ?? exactRequest.terminalSessionId ?? randomUUID();
-            const log = new TerminalFrameLog();
-            const activity = { localMs: Date.now() };
-            const exit = {
-                seen: false,
-            };
-            const decoder = new TextDecoder();
-            let ready;
+            const capture = createTangleTerminalStreamCapture({
+                cols: exactRequest.cols,
+                rows: exactRequest.rows,
+            });
             let stream;
             try {
-                stream = await awaitWithSignal(terminals.attach(connectionId, {
+                stream = await awaitWithSignalAndCleanup(() => terminals.attach(connectionId, {
                     ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
                     ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
                     ...(exactRequest.command === undefined
                         ? {}
                         : { command: exactRequest.command }),
                     ...(exactRequest.cwd === undefined ? {} : { cwd: exactRequest.cwd }),
-                    handlers: {
-                        onReady: (info) => {
-                            ready = info;
-                            log.append({
-                                type: "ready",
-                                ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
-                                ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
-                            });
-                        },
-                        onData: (data) => {
-                            activity.localMs = Date.now();
-                            log.appendOutput(decoder.decode(data, { stream: true }));
-                        },
-                        onExit: (info) => {
-                            exit.seen = true;
-                            exit.exitCode = info.exitCode;
-                            exit.exitSignal = info.exitSignal;
-                            log.append({
-                                type: "exit",
-                                ...(Number.isSafeInteger(info.exitCode)
-                                    ? { exitCode: info.exitCode }
-                                    : {}),
-                                ...(typeof info.exitSignal === "string" && info.exitSignal.length > 0
-                                    ? { exitSignal: info.exitSignal }
-                                    : {}),
-                            });
-                            log.end();
-                        },
-                        onError: (error) => {
-                            // A frame belongs to the PTY stream, which carries whatever the
-                            // terminal itself produced, so the socket error is carried as
-                            // the terminal reports it and only its length is bounded.
-                            log.append({ type: "error", message: socketErrorFrame(error) });
-                        },
-                        onClose: () => {
-                            log.end();
-                        },
-                    },
-                }), options?.signal);
+                    handlers: capture.handlers,
+                }), options?.signal, closeQuietly);
             }
             catch (error) {
                 options?.signal?.throwIfAborted();
@@ -110,103 +230,44 @@ export function createTangleTerminalRegistry(box) {
                     retryable: true,
                 };
             }
-            options?.signal?.throwIfAborted();
-            let acknowledgement;
-            try {
-                // `ready` is an accessor on the SDK stream that throws until the
-                // runtime's acknowledgement arrives. Read outside a guard it would
-                // replace this attach's result with a raw transport error and abandon
-                // the socket the attach opened.
-                acknowledgement = ready ?? stream.ready;
-            }
-            catch (error) {
-                await closeQuietly(stream);
-                return {
-                    status: "unknown",
-                    message: transportFailureReason("terminal acknowledgement", error),
-                    retryable: true,
-                };
-            }
-            if (acknowledgement === undefined ||
-                typeof acknowledgement.sessionId !== "string" ||
-                acknowledgement.sessionId.length === 0) {
-                await closeQuietly(stream);
-                return {
-                    status: "unknown",
-                    message: "the Tangle terminal transport attached without a session id",
-                    retryable: false,
-                };
-            }
-            if (exactRequest.terminalSessionId !== undefined &&
-                acknowledgement.sessionId !== exactRequest.terminalSessionId) {
-                await closeQuietly(stream);
-                return {
-                    status: "unknown",
-                    message: "the Tangle terminal transport attached a different terminal session",
-                    retryable: false,
-                };
-            }
-            if (!Number.isSafeInteger(acknowledgement.detachTimeoutMs) ||
-                acknowledgement.detachTimeoutMs <= 0) {
-                // The detach window is the only bound on how long the runtime keeps
-                // this PTY, so without it the reference cannot state an expiry and
-                // every later call would be unbounded.
-                await closeQuietly(stream);
-                return {
-                    status: "unknown",
-                    message: "the Tangle terminal transport reported no detach window",
-                    retryable: false,
-                };
-            }
-            let info;
-            try {
-                info = await awaitWithSignal(terminals.get(acknowledgement.sessionId), options?.signal);
-            }
-            catch (error) {
-                options?.signal?.throwIfAborted();
-                await closeQuietly(stream);
-                return {
-                    status: "unknown",
-                    message: transportFailureReason("terminal metadata read", error),
-                    retryable: true,
-                };
-            }
-            if (info === null || info === undefined) {
-                await closeQuietly(stream);
-                return {
-                    status: "unknown",
-                    message: "the Tangle runtime reported no metadata for the attached terminal",
-                    retryable: true,
-                };
-            }
-            const state = terminalStateFromInfo(info, acknowledgement, exactRequest.parentExecutionId, activity.localMs);
-            if (typeof state === "string") {
+            if (options?.signal?.aborted) {
                 await closeQuietly(stream);
-                return { status: "unknown", message: state, retryable: false };
+                options.signal.throwIfAborted();
             }
-            const previous = attached.get(state.terminalSessionId);
-            state.attachCount =
-                previous === undefined ? 1 : previous.session.ref.attachCount + 1;
-            // A handle drops only the entry it still owns, matched by the socket it
-            // was built on. A later attach replaces that entry with its own socket,
-            // so a stale handle's detach cannot evict the terminal now held.
-            const release = () => {
-                if (attached.get(state.terminalSessionId)?.stream === stream) {
-                    attached.delete(state.terminalSessionId);
-                }
-            };
-            const session = createTangleTerminalSession(stream, log, state, activity, exit, release);
-            attached.set(state.terminalSessionId, { session, stream });
+            const prepared = await prepareTangleTerminalAttachment({
+                stream,
+                capture,
+                terminals,
+                parentExecutionId: exactRequest.parentExecutionId,
+                expectedSessionId: exactRequest.terminalSessionId,
+                signal: options?.signal,
+                attachCount: (terminalSessionId) => {
+                    const previous = attached.get(terminalSessionId);
+                    return previous === undefined ? 1 : previous.session.ref.attachCount + 1;
+                },
+                release: (terminalSessionId, heldStream) => {
+                    if (attached.get(terminalSessionId)?.stream === heldStream) {
+                        attached.delete(terminalSessionId);
+                    }
+                },
+            });
+            if (prepared.status === "unknown")
+                return prepared;
+            const previous = attached.get(prepared.session.ref.terminalSessionId);
+            attached.set(prepared.session.ref.terminalSessionId, {
+                session: prepared.session,
+                stream: prepared.stream,
+            });
             // The registry holds one socket per terminal. The socket this attach
             // replaces stays open on the runtime until its own close, so it is
             // closed here rather than abandoned with the handle that owned it.
             if (previous !== undefined)
                 await closeQuietly(previous.stream);
             return {
-                status: acknowledgement.restored === true ? "reattached" : "attached",
+                status: prepared.acknowledgement.restored === true ? "reattached" : "attached",
                 mode: "attach",
-                ref: session.ref,
-                attachCount: state.attachCount,
+                ref: prepared.session.ref,
+                attachCount: prepared.session.ref.attachCount,
             };
         },
         get(terminalSessionId) {
@@ -272,7 +333,7 @@ function terminalStateFromInfo(info, ready, parentExecutionId, localLastActivity
         attachCount: 1,
     };
 }
-function createTangleTerminalSession(stream, log, state, activity, exit, release) {
+function createTangleTerminalSession(stream, log, state, activity, exit, release, beforeMutation) {
     // A reference describes what this handle can do with its own socket. The
     // runtime keeps a detached PTY alive, but a closed socket carries no input
     // and no output, so a detached or closed handle reports the terminal as not
@@ -330,6 +391,8 @@ function createTangleTerminalSession(stream, log, state, activity, exit, release
             assertOptionKeys(options, ["signal"], "Tangle terminal input");
             const exactInput = TerminalInputSchema.parse(input);
             options?.signal?.throwIfAborted();
+            await beforeMutation?.("input");
+            options?.signal?.throwIfAborted();
             assertUsable("input");
             stream.write(exactInput.data);
             activity.localMs = Date.now();
@@ -338,6 +401,8 @@ function createTangleTerminalSession(stream, log, state, activity, exit, release
             assertOptionKeys(options, ["signal"], "Tangle terminal resize");
             const exactResize = TerminalResizeSchema.parse(resize);
             options?.signal?.throwIfAborted();
+            await beforeMutation?.("resize");
+            options?.signal?.throwIfAborted();
             assertUsable("resize");
             stream.resize(exactResize.cols, exactResize.rows);
             state.cols = exactResize.cols;
@@ -351,6 +416,8 @@ function createTangleTerminalSession(stream, log, state, activity, exit, release
         async detach(options) {
             assertOptionKeys(options, ["signal"], "Tangle terminal detach");
             options?.signal?.throwIfAborted();
+            await beforeMutation?.("detach");
+            options?.signal?.throwIfAborted();
             detached = true;
             release();
             await awaitWithSignal(stream.close(), options?.signal);
@@ -364,6 +431,8 @@ function createTangleTerminalSession(stream, log, state, activity, exit, release
         async close(options) {
             assertOptionKeys(options, ["signal"], "Tangle terminal close");
             options?.signal?.throwIfAborted();
+            await beforeMutation?.("close");
+            options?.signal?.throwIfAborted();
             detached = true;
             release();
             await awaitWithSignal(stream.close(), options?.signal);
@@ -407,6 +476,21 @@ async function closeQuietly(stream) {
         // caller's failure is reported from the attach result it receives.
     }
 }
+/** Close a stream that has not been handed to a caller. */
+export async function closeTangleStreamQuietly(stream) {
+    await closeQuietly(stream);
+}
+/** Add the exact claim identity without replacing the terminal implementation. */
+export function bindTangleInteractiveControl(session, control) {
+    return Object.create(session, {
+        control: {
+            configurable: false,
+            enumerable: true,
+            value: Object.freeze({ ...control }),
+            writable: false,
+        },
+    });
+}
 function boundedLabel(value) {
     return typeof value === "string" && value.length > 0 && value.length <= 512
         ? value

package/dist/tangle-types.d.ts

@@ -1,5 +1,5 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
+import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, AgentExecutionPreparationReceipt, AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentProfile, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 export interface TangleExactProcessOptions {
     teamId?: string;
@@ -103,6 +103,20 @@ export interface SandboxRuntimeCapabilityDocument {
          */
         responseDedupe?: boolean;
     };
+    interactiveAgent?: {
+        /** Start binds one native TUI to the requested session id. */
+        start?: boolean;
+        /** Status returns durable running, exited, stopped, or lost state. */
+        status?: boolean;
+        /** Attach reaches the existing TUI and never creates a shell. */
+        attach?: boolean;
+        /** The deployment owns exact control claims and generation fencing. */
+        control?: boolean;
+        /** Prompt input is sent to that existing TUI. */
+        sendPrompt?: boolean;
+        /** Stop reaps the exact TUI and records its terminal state. */
+        stop?: boolean;
+    };
 }
 export interface SandboxProcessStatusLike {
     pid: number;
@@ -227,6 +241,58 @@ export interface SandboxTerminalsLike {
         handlers?: SandboxTerminalHandlersLike;
     }): Promise<SandboxTerminalStreamLike>;
 }
+/** Identity returned by the Sandbox exact interactive-session route. */
+export interface SandboxInteractiveSessionIdentityLike {
+    sessionId: string;
+    harness: BackendType;
+    startedAt: string;
+    /** Provider-issued process incarnation. Replays return this exact value. */
+    incarnationId: string;
+    /** Canonical provider admission receipt for the effective route. */
+    preparationReceipt: AgentExecutionPreparationReceipt;
+}
+/** Start acknowledgement from the canonical Sandbox interactive API. */
+export interface SandboxInteractiveSessionInfoLike extends SandboxInteractiveSessionIdentityLike {
+    streamUrl: string;
+}
+/** Lifecycle returned by the Sandbox exact interactive-session route. */
+export type SandboxInteractiveSessionStatusLike = (SandboxInteractiveSessionInfoLike & {
+    state: "running";
+}) | (SandboxInteractiveSessionIdentityLike & {
+    state: "exited";
+    endedAt: string;
+    exitCode?: number;
+    exitSignal?: string;
+    reason: "exited" | "stopped" | "lost";
+});
+/** Existing Sandbox SDK handle for one coding harness's native TUI. */
+export interface SandboxInteractiveSessionLike {
+    start(options: {
+        harness: BackendType;
+        model?: string;
+        cwd?: string;
+        cols?: number;
+        rows?: number;
+        profile: AgentProfile;
+        initialPrompt?: string;
+        /** Derived from the exact run; owned by the Sandbox creation ledger. */
+        idempotencyKey: string;
+        /** Exact request digest paired with the idempotency key. */
+        requestDigest: `sha256:${string}`;
+    }): Promise<SandboxInteractiveSessionInfoLike>;
+    claimControl(request: AgentInteractiveSessionControlClaimRequest): Promise<AgentInteractiveSessionControlClaimAcknowledgement>;
+    status(): Promise<SandboxInteractiveSessionStatusLike | null>;
+    attach(options: {
+        control: AgentInteractiveSessionControlClaim;
+        cols?: number;
+        rows?: number;
+        handlers?: SandboxTerminalHandlersLike;
+    }): Promise<SandboxTerminalStreamLike>;
+    /** Validate the current generation before each PTY mutation. */
+    validateControl(control: AgentInteractiveSessionControlClaim): Promise<void>;
+    sendPrompt(command: AgentInteractiveSessionPromptCommand): Promise<AgentInteractiveSessionPromptAcknowledgement>;
+    stop(command: AgentInteractiveSessionStopCommand): Promise<AgentInteractiveSessionStopAcknowledgement>;
+}
 export interface SandboxInstanceLike {
     id: string;
     name?: string;
@@ -302,10 +368,12 @@ export interface SandboxInstanceLike {
     }): Promise<void>;
     delete?(options?: {
         signal?: AbortSignal;
-    }): Promise<void>;
+    }): Promise<unknown>;
 }
 export interface SandboxSessionLike {
     readonly id: string;
+    /** Exact native coding-agent TUI bound to this session id. */
+    interactive?(): unknown;
     status(options?: {
         signal?: AbortSignal;
     }): Promise<unknown | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,8 @@
     "dist/tangle-environment-session.js",
     "dist/tangle-interaction-response.d.ts",
     "dist/tangle-interaction-response.js",
+    "dist/tangle-interactive.d.ts",
+    "dist/tangle-interactive.js",
     "dist/tangle-environment-control.d.ts",
     "dist/tangle-environment-control.js",
     "dist/tangle-environment-validation.d.ts",
@@ -83,7 +85,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.55.0"
+    "@tangle-network/agent-interface": "0.56.0"
   },
   "peerDependencies": {
     "@tangle-network/sandbox": ">=0.23.0 <1.0.0"
@@ -94,13 +96,13 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.145.3",
-    "@tangle-network/agent-runtime": "0.132.13",
-    "@tangle-network/sandbox": "0.23.0",
+    "@tangle-network/agent-eval": "0.145.15",
+    "@tangle-network/agent-runtime": "0.135.3",
+    "@tangle-network/sandbox": "0.27.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@tangle-network/agent-provider-testkit": "0.7.5"
+    "@tangle-network/agent-provider-testkit": "0.8.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",