@tangle-network/agent-provider-tangle 0.9.0 → 0.10.0

package/dist/tangle-terminal-frames.js

@@ -0,0 +1,137 @@
+import { MAX_ARRAY_LENGTH, MAX_STRING_LENGTH } from "./tangle-contract-safety.js";
+/** Frames retained for replay. An older cursor is refused, never skipped. */
+const MAX_RETAINED_FRAMES = MAX_ARRAY_LENGTH;
+/**
+ * Ordered terminal frames with a replay cursor.
+ *
+ * Every frame takes a monotonic ordinal, and an `output` frame also takes a
+ * monotonic `seq` that a consumer replays from. `since` is EXCLUSIVE: it names
+ * the last sequence the consumer processed, so a reconnect resumes with
+ * neither loss nor duplication. A cursor whose successor frames were evicted is
+ * refused, because silently resuming after the gap would drop terminal output
+ * the consumer believes it received.
+ *
+ * The buffer is bounded, so the accepted cursors move as frames are evicted.
+ * {@link cursors} states the window they moved to: `earliest` is the oldest
+ * cursor `read` accepts and delivers every retained frame from, and `latest` is
+ * the newest output frame. A read with no cursor starts at `earliest`, so a
+ * consumer that holds none is never locked out. A consumer that names an
+ * evicted cursor is refused and told which cursor to resume from, because it
+ * believes it received the frames the gap would silently drop.
+ */
+export class TerminalFrameLog {
+    entries = [];
+    lastOrdinal = 0;
+    outputSeq = 0;
+    evictedOrdinal = 0;
+    evictedOutputSeq = 0;
+    ended = false;
+    waiters = [];
+    append(event) {
+        this.lastOrdinal += 1;
+        this.entries.push({ ordinal: this.lastOrdinal, event });
+        while (this.entries.length > MAX_RETAINED_FRAMES) {
+            const dropped = this.entries.shift();
+            if (dropped === undefined)
+                continue;
+            this.evictedOrdinal = dropped.ordinal;
+            if (dropped.event.type === "output")
+                this.evictedOutputSeq = dropped.event.seq;
+        }
+        this.wake();
+    }
+    /** Append decoded PTY text, split so no frame exceeds the contract bound. */
+    appendOutput(text) {
+        for (let offset = 0; offset < text.length; offset += MAX_STRING_LENGTH) {
+            this.outputSeq += 1;
+            this.append({
+                type: "output",
+                seq: this.outputSeq,
+                data: text.slice(offset, offset + MAX_STRING_LENGTH),
+            });
+        }
+    }
+    /** No more frames will arrive; readers drain what is retained and return. */
+    end() {
+        this.ended = true;
+        this.wake();
+    }
+    /**
+     * The cursors this buffer can serve. Reading from `earliest` yields every
+     * retained frame and loses no output, because eviction drops output frames in
+     * sequence order and `earliest` names the newest one that was dropped.
+     */
+    get cursors() {
+        return { earliest: this.evictedOutputSeq, latest: this.outputSeq };
+    }
+    async *read(since, signal) {
+        signal?.throwIfAborted();
+        // An absent cursor resolves to the oldest retained frame here, where the
+        // read begins, so frames evicted between the call and the first iteration
+        // cannot lock the consumer out of a window it never named.
+        let cursor = this.ordinalForCursor(since ?? this.evictedOutputSeq);
+        while (true) {
+            signal?.throwIfAborted();
+            if (this.evictedOrdinal > cursor) {
+                throw new Error("Tangle terminal frames were evicted before this consumer read them");
+            }
+            const pending = this.entries.filter((entry) => entry.ordinal > cursor);
+            if (pending.length > 0) {
+                for (const entry of pending) {
+                    cursor = entry.ordinal;
+                    yield entry.event;
+                    signal?.throwIfAborted();
+                }
+                continue;
+            }
+            if (this.ended)
+                return;
+            await this.waitForFrames(signal);
+        }
+    }
+    ordinalForCursor(since) {
+        if (!Number.isSafeInteger(since) || since < 0) {
+            throw new Error("Tangle terminal replay cursor must be a non-negative safe integer");
+        }
+        if (since > this.outputSeq) {
+            throw new Error("Tangle terminal replay cursor is ahead of the retained frames");
+        }
+        // The oldest accepted cursor names the newest evicted output frame, so a
+        // consumer holding it has processed every frame this buffer dropped and
+        // receives every frame it still holds.
+        if (since === this.evictedOutputSeq)
+            return this.evictedOrdinal;
+        const found = this.entries.find((entry) => entry.event.type === "output" && entry.event.seq === since);
+        if (found === undefined) {
+            // Name the live cursor in the refusal, so a consumer that read no window
+            // still learns where it can resume instead of retrying the dropped one.
+            throw new Error(`Tangle terminal replay cursor is older than the retained frame buffer; resume from cursor ${this.evictedOutputSeq}`);
+        }
+        return found.ordinal;
+    }
+    waitForFrames(signal) {
+        return new Promise((resolve, reject) => {
+            let onAbort;
+            const wake = () => {
+                if (onAbort !== undefined)
+                    signal?.removeEventListener("abort", onAbort);
+                resolve();
+            };
+            this.waiters.push(wake);
+            if (signal !== undefined) {
+                onAbort = () => {
+                    reject(signal.reason instanceof Error
+                        ? signal.reason
+                        : new DOMException("The operation was aborted", "AbortError"));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+        });
+    }
+    wake() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const waiter of waiters)
+            waiter();
+    }
+}

package/dist/tangle-terminal.d.ts

@@ -0,0 +1,12 @@
+import type { AgentTerminalSession, TerminalAttachRequest, TerminalAttachResult } from "@tangle-network/agent-interface";
+import type { SandboxInstanceLike } from "./tangle-types.js";
+/** Terminal handles this environment holds, keyed by terminal session id. */
+export interface TangleTerminalRegistry {
+    attach(request: TerminalAttachRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<TerminalAttachResult>;
+    get(terminalSessionId: string): AgentTerminalSession;
+}
+/** True when this sandbox backs the interactive terminal surface. */
+export declare function sandboxBacksInteractiveTerminal(box: SandboxInstanceLike): boolean;
+export declare function createTangleTerminalRegistry(box: SandboxInstanceLike): TangleTerminalRegistry;

package/dist/tangle-terminal.js

@@ -0,0 +1,439 @@
+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 { transportFailureReason } from "./tangle-failure-reason.js";
+import { assertOptionKeys } from "./tangle-environment-validation.js";
+const MAX_TERMINAL_DIMENSION = 10_000;
+/** True when this sandbox backs the interactive terminal surface. */
+export function sandboxBacksInteractiveTerminal(box) {
+    // Attach opens the PTY socket; `get` supplies the shell, working directory,
+    // and geometry a terminal reference must state. Neither alone is enough.
+    // The member is an accessor on the SDK class, so a client that cannot build
+    // the manager fails the check instead of failing the capability read.
+    try {
+        const terminals = box.terminals;
+        return (typeof terminals?.attach === "function" && typeof terminals?.get === "function");
+    }
+    catch {
+        return false;
+    }
+}
+export function createTangleTerminalRegistry(box) {
+    const attached = new Map();
+    return {
+        async attach(request, options) {
+            assertOptionKeys(options, ["signal"], "Tangle terminal attach");
+            const exactRequest = TerminalAttachRequestSchema.parse(request);
+            options?.signal?.throwIfAborted();
+            const terminals = box.terminals;
+            if (terminals === undefined ||
+                typeof terminals.attach !== "function" ||
+                typeof terminals.get !== "function") {
+                return {
+                    status: "unavailable",
+                    reason: "the Sandbox client exposes no interactive terminal transport",
+                };
+            }
+            if (exactRequest.mode === "logical") {
+                // Sandbox resumes a terminal by reattaching its PTY and replaying the
+                // retained screen. It exposes no way to read that history without
+                // attaching, so a logical resume is refused rather than served by an
+                // attach the caller did not ask for.
+                return {
+                    status: "unavailable",
+                    reason: 'the Tangle sandbox transport has no logical terminal resume; attach with mode "attach"',
+                };
+            }
+            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;
+            let stream;
+            try {
+                stream = await awaitWithSignal(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);
+            }
+            catch (error) {
+                options?.signal?.throwIfAborted();
+                return {
+                    status: "unknown",
+                    message: transportFailureReason("terminal attach", error),
+                    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") {
+                await closeQuietly(stream);
+                return { status: "unknown", message: state, retryable: false };
+            }
+            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 });
+            // 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",
+                mode: "attach",
+                ref: session.ref,
+                attachCount: state.attachCount,
+            };
+        },
+        get(terminalSessionId) {
+            const held = attached.get(terminalSessionId);
+            if (held === undefined) {
+                throw new Error("Tangle terminal is not attached through this environment");
+            }
+            return held.session;
+        },
+    };
+}
+/**
+ * Build the terminal facts from what the runtime reported. Every field a
+ * terminal reference must state is required here: a runtime that omits one
+ * cannot be described, so the attach fails closed rather than inventing a
+ * shell, a directory, or a geometry the PTY does not have.
+ */
+function terminalStateFromInfo(info, ready, parentExecutionId, localLastActivityMs) {
+    const name = boundedLabel(info.name);
+    if (name === undefined)
+        return "the Tangle runtime reported a terminal without a name";
+    const shell = boundedLabel(info.shell);
+    if (shell === undefined)
+        return "the Tangle runtime reported a terminal without a shell";
+    const cwd = boundedLabel(info.cwd);
+    if (cwd === undefined) {
+        return "the Tangle runtime reported a terminal without a working directory";
+    }
+    const cols = terminalDimension(info.cols);
+    const rows = terminalDimension(info.rows);
+    if (cols === undefined || rows === undefined) {
+        return "the Tangle runtime reported a terminal without a valid geometry";
+    }
+    const createdAt = isoTimestamp(info.createdAt);
+    const lastActivityMs = epochMs(info.lastActivityAt);
+    if (createdAt === undefined || lastActivityMs === undefined) {
+        return "the Tangle runtime reported a terminal without valid timestamps";
+    }
+    if (typeof info.isRunning !== "boolean") {
+        return "the Tangle runtime reported a terminal without a running state";
+    }
+    return {
+        terminalSessionId: ready.sessionId,
+        parentExecutionId,
+        connectionId: ready.connectionId,
+        name,
+        shell,
+        ...(boundedLabel(info.command) === undefined
+            ? {}
+            : { command: boundedLabel(info.command) }),
+        cwd,
+        cols,
+        rows,
+        createdAt,
+        runtimeLastActivityMs: lastActivityMs,
+        localLastActivityMs,
+        detachTimeoutMs: ready.detachTimeoutMs,
+        isRunning: info.isRunning,
+        ...(Number.isSafeInteger(info.exitCode) ? { exitCode: info.exitCode } : {}),
+        ...(boundedLabel(info.exitSignal) === undefined
+            ? {}
+            : { exitSignal: boundedLabel(info.exitSignal) }),
+        attachCount: 1,
+    };
+}
+function createTangleTerminalSession(stream, log, state, activity, exit, release) {
+    // 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
+    // running and every operation that needs a live socket is denied. The handle
+    // releases its registry entry at that same instant, before the socket close
+    // it cannot un-commit, so a close that fails mid-flight leaks no entry.
+    let detached = false;
+    const socketOpen = () => detached === false && stream.isOpen !== false;
+    const currentRef = () => {
+        const lastActivityMs = Math.max(state.runtimeLastActivityMs, activity.localMs);
+        return TerminalSessionRefSchema.parse({
+            terminalSessionId: state.terminalSessionId,
+            parentExecutionId: state.parentExecutionId,
+            name: state.name,
+            shell: state.shell,
+            ...(state.command === undefined ? {} : { command: state.command }),
+            cwd: state.cwd,
+            cols: state.cols,
+            rows: state.rows,
+            connectionId: state.connectionId,
+            createdAt: state.createdAt,
+            lastActivityAt: new Date(lastActivityMs).toISOString(),
+            // The runtime keeps a detached PTY for its detach window and no longer,
+            // so the reference expires one window after the last activity it can
+            // prove. An attached socket keeps renewing that instant, and a reference
+            // read after the window denies use instead of guessing.
+            expiresAt: new Date(lastActivityMs + state.detachTimeoutMs).toISOString(),
+            isRunning: state.isRunning && !exit.seen && socketOpen(),
+            ...(exit.seen && Number.isSafeInteger(exit.exitCode)
+                ? { exitCode: exit.exitCode }
+                : state.exitCode === undefined
+                    ? {}
+                    : { exitCode: state.exitCode }),
+            ...(exit.seen && typeof exit.exitSignal === "string" && exit.exitSignal.length > 0
+                ? { exitSignal: exit.exitSignal }
+                : state.exitSignal === undefined
+                    ? {}
+                    : { exitSignal: state.exitSignal }),
+            attachCount: state.attachCount,
+        });
+    };
+    const assertUsable = (operation) => {
+        if (!terminalSessionUsable(currentRef(), new Date().toISOString())) {
+            throw new Error(`Tangle terminal ${operation} requires a live, unexpired terminal`);
+        }
+    };
+    return {
+        get ref() {
+            return currentRef();
+        },
+        get cursors() {
+            return log.cursors;
+        },
+        async input(input, options) {
+            assertOptionKeys(options, ["signal"], "Tangle terminal input");
+            const exactInput = TerminalInputSchema.parse(input);
+            options?.signal?.throwIfAborted();
+            assertUsable("input");
+            stream.write(exactInput.data);
+            activity.localMs = Date.now();
+        },
+        async resize(resize, options) {
+            assertOptionKeys(options, ["signal"], "Tangle terminal resize");
+            const exactResize = TerminalResizeSchema.parse(resize);
+            options?.signal?.throwIfAborted();
+            assertUsable("resize");
+            stream.resize(exactResize.cols, exactResize.rows);
+            state.cols = exactResize.cols;
+            state.rows = exactResize.rows;
+            activity.localMs = Date.now();
+            // The runtime does not echo a geometry change, so the ordered frame log
+            // records it here; a consumer replaying frames sees the resize in order
+            // with the output it applies to.
+            log.append({ type: "resize", cols: exactResize.cols, rows: exactResize.rows });
+        },
+        async detach(options) {
+            assertOptionKeys(options, ["signal"], "Tangle terminal detach");
+            options?.signal?.throwIfAborted();
+            detached = true;
+            release();
+            await awaitWithSignal(stream.close(), options?.signal);
+            state.attachCount = Math.max(0, state.attachCount - 1);
+            return {
+                status: "detached",
+                terminalSessionId: state.terminalSessionId,
+                connectionId: state.connectionId,
+            };
+        },
+        async close(options) {
+            assertOptionKeys(options, ["signal"], "Tangle terminal close");
+            options?.signal?.throwIfAborted();
+            detached = true;
+            release();
+            await awaitWithSignal(stream.close(), options?.signal);
+            state.attachCount = Math.max(0, state.attachCount - 1);
+            if (exit.seen) {
+                state.isRunning = false;
+                return {
+                    status: "closed",
+                    terminalSessionId: state.terminalSessionId,
+                    ...(Number.isSafeInteger(exit.exitCode) ? { exitCode: exit.exitCode } : {}),
+                    ...(typeof exit.exitSignal === "string" && exit.exitSignal.length > 0
+                        ? { exitSignal: exit.exitSignal }
+                        : {}),
+                };
+            }
+            // Sandbox exposes no terminal delete, so a socket close only detaches:
+            // the PTY survives until its detach window expires. Reporting `closed`
+            // would claim a termination this adapter cannot prove.
+            return {
+                status: "unknown",
+                terminalSessionId: state.terminalSessionId,
+                message: "the Sandbox client exposes no terminal delete; the runtime keeps this PTY until its detach window expires",
+                retryable: false,
+            };
+        },
+        events(options) {
+            assertOptionKeys(options, ["since", "signal"], "Tangle terminal events");
+            // The absent cursor stays absent: the frame log resolves it to the oldest
+            // frame it still retains. Naming 0 here would hand a fresh consumer the
+            // one cursor the log refuses once the buffer has evicted an output frame.
+            return log.read(options?.since, options?.signal);
+        },
+    };
+}
+async function closeQuietly(stream) {
+    try {
+        await stream.close();
+    }
+    catch {
+        // The attach already failed, and the socket is being abandoned. The
+        // caller's failure is reported from the attach result it receives.
+    }
+}
+function boundedLabel(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 512
+        ? value
+        : undefined;
+}
+function terminalDimension(value) {
+    return typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value > 0 &&
+        value <= MAX_TERMINAL_DIMENSION
+        ? value
+        : undefined;
+}
+function epochMs(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? time : undefined;
+}
+function isoTimestamp(value) {
+    const time = epochMs(value);
+    return time === undefined ? undefined : new Date(time).toISOString();
+}
+function socketErrorFrame(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const trimmed = message.trim();
+    return trimmed.length === 0
+        ? "the Tangle terminal transport failed without a message"
+        : trimmed.slice(0, MAX_STRING_LENGTH);
+}