@tangle-network/agent-provider-tangle 0.14.0 → 0.14.2

package/dist/tangle-interactive.js

@@ -1,21 +1,20 @@
-import { AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStopAcknowledgementMatchesCommand, canonicalCandidateDigest, exactAgentInteractiveSessionStart, } from "@tangle-network/agent-interface";
-import { parseBackendType } from "@tangle-network/sandbox";
+import { AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, TerminalReplayWindowSchema, TerminalSessionRefSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStatusMatchesRef, agentInteractiveSessionStopAcknowledgementMatchesCommand, canonicalCandidateDigest, exactAgentInteractiveSessionStart, } from "@tangle-network/agent-interface";
 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.
+ * Sandbox owns the exact reference, control claim, terminal binding, and
+ * mutation acknowledgements. An older handle shape fails this test closed.
  */
 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");
+        const candidate = box
+            .session("__tangle-interactive-probe__")
+            .interactive?.();
+        return isSandboxInteractiveSession(candidate);
     }
     catch {
         return false;
@@ -29,9 +28,9 @@ export function sandboxBacksInteractiveAgent(box) {
  * never creates a second record for any of those facts.
  */
 export function createTangleInteractiveAgentRegistry(box, providerName, environmentId) {
-    const exactHandle = (sessionId) => {
+    const exactHandle = (sessionId, binding) => {
         const session = box.session?.(sessionId);
-        const candidate = session?.interactive?.();
+        const candidate = session?.interactive?.(binding);
         if (!isSandboxInteractiveSession(candidate)) {
             throw new Error("the linked Sandbox SDK does not expose the exact interactive control API");
         }
@@ -50,10 +49,13 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
             throw new Error("the Sandbox returned a different interactive session ref");
         }
     };
-    const assertControl = (ref, control) => {
+    const assertControlMatchesRef = (ref, control) => {
         if (!agentInteractiveSessionControlClaimMatchesRef(ref, control)) {
             throw new Error("the interactive control claim belongs to another process");
         }
+    };
+    const assertActiveControl = (ref, control) => {
+        assertControlMatchesRef(ref, control);
         if (Date.parse(control.expiresAt) <= Date.now()) {
             throw new Error("the interactive control claim has expired");
         }
@@ -62,70 +64,68 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
         async start(request, options) {
             assertOptionKeys(options, ["signal"], "Tangle interactive agent start");
             const exactRequest = exactAgentInteractiveSessionStart(request);
-            const requestedHarness = exactRequest.profile.harness;
-            if (requestedHarness === undefined) {
+            if (exactRequest.profile.harness === 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,
-                });
+                observed = await handle.start(exactRequest, options);
             }
             catch (error) {
                 options?.signal?.throwIfAborted();
                 throw new Error(transportFailureReason("interactive start", error));
             }
             options?.signal?.throwIfAborted();
-            const ref = refFromStart(exactRequest, observed);
+            const ref = AgentInteractiveSessionRefSchema.parse(observed.ref);
+            const control = AgentInteractiveSessionControlClaimSchema.parse(observed.control);
             if (!agentInteractiveSessionRefMatchesStart(exactRequest, ref)) {
                 throw new Error("the Sandbox returned an interactive session with a different admission receipt");
             }
+            assertControlMatchesRef(ref, control);
+            if (observed.state === "running")
+                assertActiveControl(ref, control);
+            if (observed.state === "running" && observed.streamUrl.length === 0) {
+                throw new Error("the Sandbox returned a running session without a stream");
+            }
             return ref;
         },
         get(value) {
             const ref = exactRef(value);
-            const handle = exactHandle(ref.run.sessionId);
+            const handle = exactHandle(ref.run.sessionId, { ref });
+            const mutationHandle = (control) => exactHandle(ref.run.sessionId, { ref, control });
             const readStatus = async (options) => {
                 assertOptionKeys(options, ["signal"], "Tangle interactive agent status");
                 options?.signal?.throwIfAborted();
                 let observed;
                 try {
-                    observed = await handle.status();
+                    observed = await handle.status(options);
                 }
                 catch (error) {
                     options?.signal?.throwIfAborted();
                     throw new Error(transportFailureReason("interactive status", error));
                 }
                 options?.signal?.throwIfAborted();
-                return 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 status = AgentInteractiveSessionStatusSchema.parse(observed);
+                if (!agentInteractiveSessionStatusMatchesRef(ref, status)) {
+                    throw new Error("the Sandbox reported a different interactive agent session identity");
+                }
+                return status;
             };
             const validateControl = async (control, options) => {
-                assertControl(ref, control);
+                assertActiveControl(ref, control);
                 options?.signal?.throwIfAborted();
                 try {
-                    await handle.validateControl(control);
+                    await mutationHandle(control).validateControl(control, options);
                 }
                 catch (error) {
                     options?.signal?.throwIfAborted();
@@ -142,7 +142,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     options?.signal?.throwIfAborted();
                     let raw;
                     try {
-                        raw = await handle.claimControl(exactRequest);
+                        raw = await handle.claimControl(exactRequest, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
@@ -160,59 +160,33 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     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;
+                    let terminal;
                     try {
-                        stream = await handle.attach({
-                            control: exactRequest.control,
-                            ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
-                            ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
-                            handlers: capture.handlers,
-                        });
+                        terminal = await mutationHandle(exactRequest.control).attachAgentTerminal(exactRequest, options);
                     }
                     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");
+                    try {
+                        options?.signal?.throwIfAborted();
+                        const returnedControl = AgentInteractiveSessionControlClaimSchema.parse(terminal.control);
+                        const returnedRef = TerminalSessionRefSchema.parse(terminal.ref);
+                        TerminalReplayWindowSchema.parse(terminal.cursors);
+                        if (canonicalCandidateDigest(returnedControl) !==
+                            canonicalCandidateDigest(exactRequest.control) ||
+                            returnedRef.terminalSessionId !== ref.run.sessionId ||
+                            returnedRef.parentExecutionId !== ref.run.executionId ||
+                            returnedRef.expiresAt !== exactRequest.control.expiresAt ||
+                            !returnedRef.isRunning) {
+                            throw new Error("the Sandbox returned a terminal with a different interactive identity");
+                        }
                     }
-                    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");
+                    catch (error) {
+                        await terminal.detach().catch(() => undefined);
+                        throw error;
                     }
-                    const terminal = bindTangleInteractiveControl(prepared.session, exactRequest.control);
-                    return terminal;
+                    return validatedTerminal(terminal, exactRequest.control, validateControl, ref);
                 },
                 async sendPrompt(command, options) {
                     assertOptionKeys(options, ["signal"], "Tangle interactive agent prompt");
@@ -221,7 +195,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     await validateControl(exactCommand.control, options);
                     let raw;
                     try {
-                        raw = await handle.sendPrompt(exactCommand);
+                        raw = await mutationHandle(exactCommand.control).sendPrompt(exactCommand, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
@@ -241,7 +215,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     await validateControl(exactCommand.control, options);
                     let raw;
                     try {
-                        raw = await handle.stop(exactCommand);
+                        raw = await mutationHandle(exactCommand.control).stop(exactCommand, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
@@ -266,62 +240,43 @@ function isSandboxInteractiveSession(value) {
         "start",
         "claimControl",
         "status",
-        "attach",
+        "attachAgentTerminal",
         "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, sessionId: observed.sessionId },
-        preparationReceipt: observed.preparationReceipt,
-        incarnationId: observed.incarnationId,
-        startedAt: observed.startedAt,
-    });
-    if (observed.harness !== ref.preparationReceipt.harness ||
-        !sameExactSessionRef(ref, observedRef)) {
-        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 }
-            : {}),
-    });
+function validatedTerminal(terminal, control, validate, expectedRef) {
+    const boundControl = Object.freeze({ ...control });
+    return {
+        get ref() {
+            const ref = TerminalSessionRefSchema.parse(terminal.ref);
+            if (ref.terminalSessionId !== expectedRef.run.sessionId ||
+                ref.parentExecutionId !== expectedRef.run.executionId) {
+                throw new Error("the Sandbox terminal changed its interactive session identity");
+            }
+            return ref;
+        },
+        get cursors() {
+            return TerminalReplayWindowSchema.parse(terminal.cursors);
+        },
+        control: boundControl,
+        async input(input, options) {
+            await validate(boundControl, options);
+            await terminal.input(input, options);
+        },
+        async resize(resize, options) {
+            await validate(boundControl, options);
+            await terminal.resize(resize, options);
+        },
+        detach: (options) => terminal.detach(options),
+        async close(options) {
+            await validate(boundControl, options);
+            return terminal.close(options);
+        },
+        events: (options) => terminal.events(options),
+    };
 }
 function sameExactSessionRef(expected, candidate) {
-    return canonicalCandidateDigest(expected) === canonicalCandidateDigest(candidate);
+    return (canonicalCandidateDigest(expected) === canonicalCandidateDigest(candidate));
 }

package/dist/tangle-types.d.ts

@@ -1,5 +1,5 @@
 import type { BackendRegistryEntry, BackendRegistryResponse, BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, AgentExecutionPreparationReceipt, AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentProfile, ConfidentialAttestation, ConfidentialExecutionEnvironment, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
+import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionAttach, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionRef, AgentInteractiveSessionStart, AgentInteractiveSessionStatus, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentInteractiveTerminalSession, ConfidentialAttestation, ConfidentialExecutionEnvironment, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 /**
  * The platform verdict for the create call that returned a sandbox.
@@ -335,57 +335,45 @@ 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 & {
+/** Start result returned by the Sandbox exact interactive-session route. */
+export type SandboxInteractiveSessionStartResultLike = {
     state: "running";
-}) | (SandboxInteractiveSessionIdentityLike & {
+    ref: AgentInteractiveSessionRef;
+    control: AgentInteractiveSessionControlClaim;
+    streamUrl: string;
+} | {
     state: "exited";
+    ref: AgentInteractiveSessionRef;
+    control: AgentInteractiveSessionControlClaim;
     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>;
+    start(request: AgentInteractiveSessionStart, options?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxInteractiveSessionStartResultLike>;
+    claimControl(request: AgentInteractiveSessionControlClaimRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionControlClaimAcknowledgement>;
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionStatus | null>;
+    attachAgentTerminal(request: AgentInteractiveSessionAttach, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveTerminalSession>;
+    /** Confirm that this claim is still the current writable generation. */
+    validateControl(control: AgentInteractiveSessionControlClaim, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    sendPrompt(command: AgentInteractiveSessionPromptCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionPromptAcknowledgement>;
+    stop(command: AgentInteractiveSessionStopCommand, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentInteractiveSessionStopAcknowledgement>;
 }
 export interface SandboxInstanceLike {
     id: string;
@@ -502,7 +490,10 @@ export interface SandboxInstanceLike {
 export interface SandboxSessionLike {
     readonly id: string;
     /** Exact native coding-agent TUI bound to this session id. */
-    interactive?(): unknown;
+    interactive?(options?: {
+        ref?: AgentInteractiveSessionRef;
+        control?: AgentInteractiveSessionControlClaim;
+    }): unknown;
     status(options?: {
         signal?: AbortSignal;
     }): Promise<unknown | null>;