esoul-sdk 0.7.0 → 0.16.0

package/dist/chart.js

@@ -0,0 +1,247 @@
+/**
+ * A CHART FROM DATA — one SVG for the app's screen and for the chat.
+ *
+ * A research app keeps having to show a series with something marked on it: a
+ * sensor around a fault, a loss curve with the epoch it diverged, a latency trace
+ * with the deploy. `chartSvg(spec)` draws stacked time panels sharing one x axis,
+ * with markers across every panel, as a self-contained SVG string:
+ *
+ *   const svg = chartSvg({
+ *     title: "C143 · temp_probe_fault", xStart, xEnd,
+ *     panels: [{ label: "Water temperature", unit: "°C", points }],
+ *     markers: [{ x: faultAt, label: "probe fault", tone: "page" }],
+ *   });
+ *   <div dangerouslySetInnerHTML={{ __html: svg }} />          // in the app
+ *   const img = await renderChartImage(ctx, { name: "c143", svg }); // for a tool's answer
+ *
+ * Every word is drawn as glyph outlines (chart-font.ts), not `<text>`: a serverless
+ * rasteriser has no fonts, and a chart whose labels vanish is a chart that lies by
+ * omission. Pure — no DOM, no dependencies — so it runs in a browser, a server
+ * op and a unit test alike.
+ */
+import { GLYPHS } from "./chart-font.js";
+const TONE = {
+    page: "#e11d48",
+    escalate: "#db2777",
+    warn: "#d97706",
+    note: "#64748b",
+    info: "#0284c7",
+    ok: "#059669",
+};
+const PALETTE = {
+    light: { bg: "#faf6f0", ink: "#3d2f1e", soft: "#8a7a66", grid: "#e8dfd2", line: "#9a3412", band: "#16a34a" },
+    dark: { bg: "#1c1917", ink: "#f5f0e8", soft: "#a8a29e", grid: "#3a3430", line: "#fb923c", band: "#4ade80" },
+};
+/** The width of a string at a font size, in pixels. */
+export function textWidth(text, size) {
+    let w = 0;
+    for (const ch of text)
+        w += (GLYPHS[ch] ?? GLYPHS["?"] ?? [600, ""])[0];
+    return (w * size) / 1000;
+}
+/** A string as filled glyph outlines. `y` is the baseline. */
+export function textPath(text, x, y, size, opts = { fill: "#000" }) {
+    let s = text;
+    if (opts.maxWidth !== undefined && textWidth(s, size) > opts.maxWidth) {
+        while (s.length > 1 && textWidth(`${s}…`, size) > opts.maxWidth)
+            s = s.slice(0, -1);
+        s = `${s}…`;
+    }
+    const w = textWidth(s, size);
+    const x0 = opts.anchor === "middle" ? x - w / 2 : opts.anchor === "end" ? x - w : x;
+    const k = size / 1000;
+    let adv = 0;
+    let d = "";
+    for (const ch of s) {
+        const g = GLYPHS[ch] ?? GLYPHS["?"];
+        if (!g)
+            continue;
+        if (g[1])
+            d += `<path transform="translate(${round(adv)} 0)" d="${g[1]}"/>`;
+        adv += g[0];
+    }
+    return d ? `<g transform="translate(${round(x0)} ${round(y)}) scale(${round(k, 5)})" fill="${opts.fill}">${d}</g>` : "";
+}
+const round = (n, p = 1) => {
+    const f = 10 ** p;
+    return Math.round(n * f) / f;
+};
+/** A number the way a person reads a measurement: few digits, no noise. */
+export function formatValue(v) {
+    if (!Number.isFinite(v))
+        return "—";
+    const a = Math.abs(v);
+    if (a >= 1000)
+        return v.toFixed(0);
+    if (a >= 100)
+        return v.toFixed(1).replace(/\.0$/, "");
+    if (a >= 1)
+        return v.toFixed(2).replace(/0$/, "").replace(/\.0$/, "");
+    return v.toFixed(3).replace(/0+$/, "").replace(/\.$/, "") || "0";
+}
+/**
+ * A chart as one SVG string from a spec (panels of series, markers, tones): the same picture for the
+ * app's screen (`dangerouslySetInnerHTML`) and, rendered with `renderChartImage` on the server, for
+ * a tool's answer. Text is drawn as glyph outlines, so it needs no fonts where it is rasterised.
+ */
+export function chartSvg(spec) {
+    const theme = PALETTE[spec.theme ?? "light"];
+    const W = Math.max(320, spec.width ?? 960);
+    const PH = Math.max(40, spec.panelHeight ?? 96);
+    const left = 16;
+    const right = 16;
+    const axis = 58; // room for the y labels
+    const plotX0 = left + axis;
+    const plotX1 = W - right;
+    const head = spec.title ? (spec.subtitle ? 58 : 40) : 12;
+    const panelGap = 30; // label row above each panel
+    const foot = spec.xTicks?.length ? 30 : 12;
+    const H = head + spec.panels.length * (PH + panelGap) + foot;
+    const span = spec.xEnd - spec.xStart || 1;
+    const px = (x) => plotX0 + ((x - spec.xStart) / span) * (plotX1 - plotX0);
+    const out = [];
+    out.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}">`);
+    out.push(`<rect width="${W}" height="${H}" fill="${theme.bg}"/>`);
+    if (spec.title)
+        out.push(textPath(spec.title, left, 26, 17, { fill: theme.ink, maxWidth: W - left - right }));
+    if (spec.subtitle)
+        out.push(textPath(spec.subtitle, left, 46, 12, { fill: theme.soft, maxWidth: W - left - right }));
+    const inWindow = (x) => x >= spec.xStart && x <= spec.xEnd;
+    const markers = (spec.markers ?? []).filter((m) => inWindow(m.x));
+    spec.panels.forEach((p, i) => {
+        const top = head + i * (PH + panelGap) + panelGap;
+        const bottom = top + PH;
+        const all = p.points.filter((q) => Number.isFinite(q[0]) && Number.isFinite(q[1]));
+        const step = p.kind === "step";
+        const bad = (v) => !step && !!p.impossible && ((p.impossible.below !== undefined && v <= p.impossible.below) || (p.impossible.above !== undefined && v >= p.impossible.above));
+        const pts = all.filter((q) => !bad(q[1]));
+        const rail = all.filter((q) => bad(q[1]));
+        // Label row: the channel on the left, its latest value on the right.
+        out.push(textPath(`${p.label}${p.unit ? ` · ${p.unit}` : ""}`, left, top - 9, 12, { fill: theme.ink, maxWidth: W / 2 }));
+        if (all.length) {
+            const last = all[all.length - 1][1];
+            const lastText = step ? (last >= 0.5 ? (p.levels?.[1] ?? "on") : (p.levels?.[0] ?? "off")) : `${formatValue(last)}${p.unit ? ` ${p.unit}` : ""}`;
+            out.push(textPath(`now ${lastText}`, plotX1, top - 9, 11, { fill: theme.soft, anchor: "end" }));
+        }
+        out.push(`<rect x="${plotX0}" y="${top}" width="${plotX1 - plotX0}" height="${PH}" fill="none" stroke="${theme.grid}"/>`);
+        if (rail.length) {
+            // The impossible readings, on the panel's bottom edge, one tick each.
+            const c = TONE.page;
+            out.push(`<rect x="${plotX0}" y="${bottom - 3}" width="${plotX1 - plotX0}" height="3" fill="${c}" fill-opacity="0.12"/>`);
+            let ticks = "";
+            for (const q of rail)
+                ticks += `M${round(px(q[0]))} ${bottom - 10}V${bottom}`;
+            out.push(`<path d="${ticks}" stroke="${c}" stroke-width="1.4"/>`);
+            const lo = Math.min(...rail.map((q) => q[1]));
+            out.push(textPath(`${rail.length} impossible reading${rail.length === 1 ? "" : "s"} (down to ${formatValue(lo)})${p.impossible?.label ? ` · ${p.impossible.label}` : ""}`, plotX0 + 6, bottom - 14, 10, { fill: c }));
+        }
+        if (!pts.length) {
+            if (!rail.length)
+                out.push(textPath("no readings in this window", (plotX0 + plotX1) / 2, top + PH / 2 + 4, 12, { fill: theme.soft, anchor: "middle" }));
+            for (const m of markers)
+                out.push(`<line x1="${round(px(m.x))}" x2="${round(px(m.x))}" y1="${top}" y2="${bottom}" stroke="${TONE[m.tone ?? "page"]}" stroke-width="1.4" stroke-opacity="0.85"/>`);
+            return;
+        }
+        let lo = step ? 0 : Math.min(...pts.map((q) => q[1]));
+        let hi = step ? 1 : Math.max(...pts.map((q) => q[1]));
+        if (p.band && !step) {
+            lo = Math.min(lo, p.band.min);
+            hi = Math.max(hi, p.band.max);
+        }
+        if (hi - lo < 1e-9) {
+            lo -= 1;
+            hi += 1;
+        }
+        const pad = step ? 0.12 : 0.08;
+        const y = (v) => bottom - ((v - lo) / (hi - lo)) * PH * (1 - 2 * pad) - PH * pad;
+        if (p.band && !step) {
+            const y0 = y(p.band.max);
+            const y1 = y(p.band.min);
+            out.push(`<rect x="${plotX0}" y="${round(y0)}" width="${plotX1 - plotX0}" height="${round(Math.max(1, y1 - y0))}" fill="${theme.band}" fill-opacity="0.08"/>`);
+            if (p.band.label)
+                out.push(textPath(p.band.label, plotX0 + 6, round(y0) + 12, 10, { fill: theme.band }));
+        }
+        // y labels: the extremes of what is drawn — for a probe fault, -999.9 IS the story.
+        const yl = step ? [p.levels?.[1] ?? "on", p.levels?.[0] ?? "off"] : [formatValue(hi), formatValue(lo)];
+        out.push(textPath(yl[0], plotX0 - 8, y(hi) + 4, 10, { fill: theme.soft, anchor: "end" }));
+        out.push(textPath(yl[1], plotX0 - 8, y(lo) + 4, 10, { fill: theme.soft, anchor: "end" }));
+        // A line is a claim that the value passed between two readings. Where the
+        // readings are far apart (a device silent, a sentinel lifted out), there is no
+        // such claim to make, so the line breaks.
+        // Per panel: a sensor that reports every hour is not "gone" for 40 minutes.
+        const deltas = pts.slice(1).map((q, j) => q[0] - pts[j][0]).sort((a, b) => a - b);
+        const typical = deltas.length ? deltas[Math.floor(deltas.length / 2)] : 0;
+        const gap = spec.gap ?? Math.max(span * 0.05, typical * 4);
+        let d = "";
+        pts.forEach((q, j) => {
+            const X = round(px(q[0]));
+            const Y = round(y(q[1]));
+            const broken = j > 0 && q[0] - pts[j - 1][0] > gap;
+            if (j === 0 || (broken && !step))
+                d += `M${X} ${Y}`;
+            else if (step)
+                d += `H${X}V${Y}`;
+            else
+                d += `L${X} ${Y}`;
+        });
+        if (step && pts.length)
+            d += `H${round(px(Math.min(spec.xEnd, spec.now ?? spec.xEnd)))}`;
+        out.push(`<path d="${d}" fill="none" stroke="${theme.line}" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round"/>`);
+        // Markers cross every panel, so a fault lines up with every channel at once.
+        for (const m of markers) {
+            out.push(`<line x1="${round(px(m.x))}" x2="${round(px(m.x))}" y1="${top}" y2="${bottom}" stroke="${TONE[m.tone ?? "page"]}" stroke-width="1.4" stroke-opacity="0.85"/>`);
+        }
+    });
+    // Marker flags above the first panel, spaced so labels do not sit on each other.
+    const firstTop = head + panelGap;
+    let lastLabelEnd = -Infinity;
+    for (const m of [...markers].sort((a, b) => a.x - b.x)) {
+        const X = px(m.x);
+        const c = TONE[m.tone ?? "page"];
+        out.push(`<path d="M${round(X - 5)} ${firstTop - 24}h10l-5 7z" fill="${c}"/>`);
+        if (m.label && X - 4 > lastLabelEnd) {
+            const lw = Math.min(180, textWidth(m.label, 10));
+            out.push(textPath(m.label, X + 7, firstTop - 17, 10, { fill: c, maxWidth: 180 }));
+            lastLabelEnd = X + 7 + lw + 8;
+        }
+    }
+    if (spec.now !== undefined && inWindow(spec.now)) {
+        const X = round(px(spec.now));
+        out.push(`<line x1="${X}" x2="${X}" y1="${head + panelGap}" y2="${H - foot}" stroke="${theme.ink}" stroke-dasharray="3 3" stroke-opacity="0.45"/>`);
+    }
+    for (const t of spec.xTicks ?? []) {
+        if (!inWindow(t.x))
+            continue;
+        out.push(textPath(t.label, px(t.x), H - 10, 10, { fill: theme.soft, anchor: "middle" }));
+    }
+    out.push("</svg>");
+    return out.join("");
+}
+/**
+ * Naive local timestamps ("2026-03-31T20:58:20" or with a space) as a number for an
+ * x axis — minutes since the epoch, WITHOUT a timezone. Stream times are wall-clock
+ * strings from a device; `new Date(s)` would shift them by the viewer's offset.
+ */
+export function naiveMinutes(ts) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?/.exec(ts ?? "");
+    if (!m)
+        return NaN;
+    return Date.UTC(+m[1], +m[2] - 1, +m[3], +(m[4] ?? 0), +(m[5] ?? 0), +(m[6] ?? 0)) / 60_000;
+}
+/** A naive-minutes value back to "MM-DD HH:MM" for a tick. */
+export function naiveLabel(minutes, withDate = true) {
+    const d = new Date(minutes * 60_000);
+    const p = (n) => String(n).padStart(2, "0");
+    const hm = `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}`;
+    return withDate ? `${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${hm}` : hm;
+}
+/** Evenly spaced ticks across a naive-minutes window, labelled for the span. */
+export function naiveTicks(start, end, count = 6) {
+    const out = [];
+    const n = Math.max(2, count);
+    for (let i = 0; i < n; i++) {
+        const x = start + ((end - start) * i) / (n - 1);
+        out.push({ x, label: naiveLabel(x, end - start > 36 * 60 || i === 0) });
+    }
+    return out;
+}

package/dist/computer.d.ts

@@ -0,0 +1,191 @@
+/**
+ * A MACHINE, FROM SERVER CODE — `computer(ctx, machineNodeId)`.
+ *
+ * A `my_computer` app is a paired personal machine: run a shell command on it,
+ * give Claude Code a task on it, read the result. Its tools answer JSON in a
+ * string, every command is approval-gated unless the owner set the app to
+ * auto, a wait is at most 55 seconds and a command at most 900, and a task that
+ * takes longer than one wait comes back "running" with a commandId to ask for
+ * again. An app orchestrating a machine — a research runner starting a server,
+ * a replay, a Claude Code session — had to know all of that and parse the
+ * strings itself. This holds it once.
+ *
+ *   const box = computer(ctx, machineNodeId);          // ctx: an op's or a task's
+ *   const st = await box.status();                     // { paired, online, autonomy, pendingApproval }
+ *   const r  = await box.run("cd ~/proj && make", { cwd: "~", timeoutSeconds: 600 });
+ *   if (r.status === "pending_approval") …              // the owner must approve in the app
+ *   const done = await box.runToEnd("python -m stream.replay …", { deadlineMs: 300_000 });
+ *   const said = await box.claude("Read README.md and summarise the run steps", { permissionMode: "no_writes" });
+ *
+ * Reaches the machine through `callWorkspaceTool`, so it is gated by the
+ * manifest's `workspaceTools` (`my_computer:run_on_computer`, `my_computer:get_computer_result`,
+ * `my_computer:claude_task`, `my_computer:computer_status`) and works wherever
+ * that works: installed, and in a Forge box through the board's tab.
+ *
+ * Pure: the same file on the npm package and on the platform; each side binds
+ * it to its own `callWorkspaceTool` (`makeComputer`).
+ */
+import type { CallWorkspaceToolArgs } from "./server.js";
+export type CommandStatus = "pending_approval" | "approved" | "running" | "done" | "denied" | "failed" | "unknown";
+/** What a command came back as. Flat: the repo an app compiles in may not narrow a union. */
+export interface CommandOutcome {
+    ok: boolean;
+    status: CommandStatus;
+    commandId?: string;
+    command?: string;
+    exitCode?: number;
+    timedOut?: boolean;
+    durationMs?: number;
+    stdout?: string;
+    stderr?: string;
+    /** The machine's or the platform's own words when something refused or failed. */
+    error?: string;
+    /** What the tool said in words (approval waits carry the sentence to tell the user). */
+    message?: string;
+    /** The tool's answer as it came, for anything this shape does not carry. */
+    raw: string;
+    /**
+     * The machine's output was CUT: the My Computer app keeps at most
+     * `OUTPUT_LIMIT` characters of a command's stdout. A caller parsing the
+     * output must treat a truncated answer as unknown, never as the whole.
+     */
+    truncated?: boolean;
+}
+export interface ClaudeOutcome extends CommandOutcome {
+    answer?: string;
+    sessionId?: string;
+    costUsd?: number;
+    isError?: boolean;
+}
+export interface ComputerStatus {
+    ok: boolean;
+    paired: boolean;
+    online: boolean;
+    hostname?: string;
+    os?: string;
+    autonomy?: "approve" | "auto";
+    pendingApproval?: number;
+    message?: string;
+    error?: string;
+    raw: string;
+}
+export interface RunOptions {
+    cwd?: string;
+    /** Kill the command after this many seconds (default 120, max 900). */
+    timeoutSeconds?: number;
+    /** How long one wait may last before the tool answers (default 30, max 55). */
+    waitSeconds?: number;
+}
+export interface ToEndOptions extends RunOptions {
+    /** Stop asking after this long (default 15 min — a command cannot outlive 900 s anyway). */
+    deadlineMs?: number;
+    /** Keep waiting while the command is pending the owner's approval (default: return at once). */
+    waitForApproval?: boolean;
+    /** Called on every non-terminal answer — say "still waiting for approval" somewhere. */
+    onWait?: (o: CommandOutcome) => void | Promise<void>;
+}
+export interface ClaudeOptions extends ToEndOptions {
+    sessionId?: string;
+    permissionMode?: "full" | "no_writes";
+}
+export interface Computer {
+    readonly machineNodeId: string;
+    status(): Promise<ComputerStatus>;
+    run(command: string, opts?: RunOptions): Promise<CommandOutcome>;
+    result(commandId: string, waitSeconds?: number): Promise<CommandOutcome>;
+    /** `run`, then `result` until it is terminal or the deadline passes. */
+    runToEnd(command: string, opts?: ToEndOptions): Promise<CommandOutcome>;
+    claude(prompt: string, opts?: ClaudeOptions): Promise<ClaudeOutcome>;
+    /** `claude`, then `result` until Claude has answered. */
+    claudeToEnd(prompt: string, opts?: ClaudeOptions): Promise<ClaudeOutcome>;
+    /** The contents of one file, as the machine's `cat` returns it. */
+    readFile(path: string, opts?: {
+        maxBytes?: number;
+    } & ToEndOptions): Promise<{
+        ok: boolean;
+        text: string;
+        error?: string;
+    }>;
+    /**
+     * A JSON answer from a service on the MACHINE's own network — `http://localhost:8600/health`,
+     * a dashboard, a database's REST door — which the platform cannot reach and the machine can.
+     * `curl` runs there; the body comes back parsed. This is how a research app shows what a
+     * server on the analyst's laptop is doing.
+     */
+    fetchJson(url: string, opts?: {
+        method?: "GET" | "POST";
+        body?: unknown;
+        timeoutSeconds?: number;
+    } & ToEndOptions): Promise<{
+        ok: boolean;
+        status?: number;
+        json?: unknown;
+        text: string;
+        error?: string;
+    }>;
+    /**
+     * COMPUTE ON THE MACHINE, BRING BACK A LITTLE JSON. Runs a command whose stdout
+     * is one JSON document and parses it. The machine keeps at most `OUTPUT_LIMIT`
+     * characters of a command's output, so this is the shape for anything big —
+     * a database query, a series to plot, a log to summarise: do the heavy part
+     * THERE and print only what the app needs. A cut answer is an error that says so.
+     */
+    runJson<T = unknown>(command: string, opts?: ToEndOptions): Promise<JsonOutcome<T>>;
+    /** `runJson` for a Python script, fed on stdin to the interpreter you name (default `python3`). */
+    python<T = unknown>(script: string, opts?: {
+        python?: string;
+    } & ToEndOptions): Promise<JsonOutcome<T>>;
+}
+/** Flat, like every outcome here. `ok` with `json`; otherwise `error` in words. */
+export interface JsonOutcome<T = unknown> {
+    ok: boolean;
+    json?: T;
+    status: CommandStatus;
+    commandId?: string;
+    exitCode?: number;
+    /** The command's stderr tail, which is where a script's traceback is. */
+    stderr?: string;
+    error?: string;
+    message?: string;
+    truncated?: boolean;
+}
+export type CallWorkspaceToolFn = (a: CallWorkspaceToolArgs) => Promise<{
+    ok: boolean;
+    text: string;
+    truncated?: boolean;
+}>;
+/** The longest one call waits on a machine command before answering "still running" (a tool call's budget). */
+export declare const MAX_WAIT_SECONDS = 55;
+/** The longest a machine command may run before the machine stops it. */
+export declare const MAX_TIMEOUT_SECONDS = 900;
+/** How much of a command's stdout the My Computer app keeps. Print less than this. */
+export declare const OUTPUT_LIMIT = 8000;
+/** The tool answers `JSON.stringify(json)`; a refusal from the platform is plain words. */
+export declare function parseToolJson(text: string): Record<string, unknown> | null;
+/** One command answer, from whatever the tool said. */
+export declare function parseCommandOutcome(r: {
+    ok: boolean;
+    text: string;
+    truncated?: boolean;
+}): CommandOutcome;
+/** What an app tells a person when the machine waits for them. */
+export declare const APPROVAL_WAIT = "Waiting for the owner to approve this command in the My Computer app (or set that app to Auto).";
+/** A Claude Code task's tool answer as fields: the command's outcome plus `answer`, `sessionId`, `costUsd`, `isError`. */
+export declare function parseClaudeOutcome(r: {
+    ok: boolean;
+    text: string;
+    truncated?: boolean;
+}): ClaudeOutcome;
+/** The machine's status answer as fields: paired, online, hostname, os, autonomy, pending approvals. */
+export declare function parseStatus(r: {
+    ok: boolean;
+    text: string;
+}): ComputerStatus;
+/** Whether a command has finished for good (`done`, `failed`, `denied`) — anything else is worth waiting on. */
+export declare const isTerminal: (s: CommandStatus) => boolean;
+export declare function __forgetAutonomy(): void;
+/** Bind the client to a side's `callWorkspaceTool`. Authors use `computer(...)`, never this. */
+export declare function makeComputer(call: CallWorkspaceToolFn): (ctx: {
+    pluginId: string;
+    nodeId: string;
+}, machineNodeId: string) => Computer;

package/dist/computer.js

@@ -0,0 +1,226 @@
+const TERMINAL = ["done", "failed", "denied"];
+/** The longest one call waits on a machine command before answering "still running" (a tool call's budget). */
+export const MAX_WAIT_SECONDS = 55;
+/** The longest a machine command may run before the machine stops it. */
+export const MAX_TIMEOUT_SECONDS = 900;
+/** How much of a command's stdout the My Computer app keeps. Print less than this. */
+export const OUTPUT_LIMIT = 8_000;
+const TRUNCATION_MARK = "\n…[truncated]";
+const asRecord = (x) => (x && typeof x === "object" && !Array.isArray(x) ? x : null);
+const str = (x) => (typeof x === "string" ? x : undefined);
+const num = (x) => (typeof x === "number" && Number.isFinite(x) ? x : undefined);
+const bool = (x) => (typeof x === "boolean" ? x : undefined);
+/** The tool answers `JSON.stringify(json)`; a refusal from the platform is plain words. */
+export function parseToolJson(text) {
+    const t = (text ?? "").trim();
+    if (!t.startsWith("{"))
+        return null;
+    try {
+        return asRecord(JSON.parse(t));
+    }
+    catch {
+        return null;
+    }
+}
+function statusOf(j) {
+    const s = str(j?.status);
+    return s === "pending_approval" || s === "approved" || s === "running" || s === "done" || s === "denied" || s === "failed" ? s : "unknown";
+}
+/** One command answer, from whatever the tool said. */
+export function parseCommandOutcome(r) {
+    // A tool answer cut in transit is half a JSON document: say so, instead of "no answer".
+    if (r.truncated)
+        return { ok: false, status: "unknown", truncated: true, error: `the machine's answer was cut in transit (${r.text.length} characters arrived) — ask for less`, raw: r.text };
+    const j = parseToolJson(r.text);
+    if (!j)
+        return { ok: false, status: "unknown", error: r.text || "no answer", raw: r.text };
+    const okFlag = j.ok !== false && r.ok;
+    const status = statusOf(j);
+    const stdoutRaw = str(j.stdout);
+    const truncated = !!stdoutRaw && stdoutRaw.endsWith(TRUNCATION_MARK);
+    return {
+        ok: okFlag,
+        status,
+        commandId: str(j.commandId),
+        command: str(j.command),
+        exitCode: num(j.exitCode),
+        timedOut: bool(j.timedOut),
+        durationMs: num(j.durationMs),
+        stdout: truncated ? stdoutRaw.slice(0, -TRUNCATION_MARK.length) : stdoutRaw,
+        ...(truncated ? { truncated: true } : {}),
+        stderr: str(j.stderr),
+        error: str(j.error),
+        // The My Computer route words its waits for a CHAT agent ("park on it with
+        // wait_for_workspace_event…"). An app shows this to a person, so a wait for
+        // approval is said plainly; the agent's hint stays in `raw` (2026-09-14, seen
+        // on an app screen).
+        message: status === "pending_approval" ? APPROVAL_WAIT : str(j.message),
+        raw: r.text,
+    };
+}
+/** What an app tells a person when the machine waits for them. */
+export const APPROVAL_WAIT = "Waiting for the owner to approve this command in the My Computer app (or set that app to Auto).";
+/** A Claude Code task's tool answer as fields: the command's outcome plus `answer`, `sessionId`, `costUsd`, `isError`. */
+export function parseClaudeOutcome(r) {
+    const base = parseCommandOutcome(r);
+    const j = parseToolJson(r.text);
+    return { ...base, answer: str(j?.answer), sessionId: str(j?.sessionId), costUsd: num(j?.costUsd), isError: bool(j?.isError) };
+}
+/** The machine's status answer as fields: paired, online, hostname, os, autonomy, pending approvals. */
+export function parseStatus(r) {
+    const j = parseToolJson(r.text);
+    if (!j)
+        return { ok: false, paired: false, online: false, error: r.text || "no answer", raw: r.text };
+    const autonomy = str(j.autonomy);
+    return {
+        ok: j.ok !== false && r.ok,
+        paired: j.paired === true,
+        online: j.online === true,
+        hostname: str(j.hostname),
+        os: str(j.os),
+        autonomy: autonomy === "auto" || autonomy === "approve" ? autonomy : undefined,
+        pendingApproval: num(j.pendingApproval),
+        message: str(j.message),
+        error: str(j.error),
+        raw: r.text,
+    };
+}
+/** Whether a command has finished for good (`done`, `failed`, `denied`) — anything else is worth waiting on. */
+export const isTerminal = (s) => TERMINAL.includes(s);
+const clampWait = (n) => Math.max(1, Math.min(MAX_WAIT_SECONDS, Math.floor(n ?? 30)));
+/**
+ * What each machine last said about approvals, per process. A command on a machine
+ * set to `approve` cannot finish inside a wait — the tool sits on the whole wait and
+ * then says "pending_approval" — so once a machine has said `approve`, a first ask
+ * waits two seconds, not thirty, and the caller hears "waiting for the owner" at
+ * once. `status()` and every answer that names the autonomy refresh it.
+ */
+const AUTONOMY_SEEN = new Map();
+export function __forgetAutonomy() {
+    AUTONOMY_SEEN.clear();
+}
+const firstWait = (machineNodeId, asked, fallback) => clampWait(asked ?? (AUTONOMY_SEEN.get(machineNodeId) === "approve" ? 2 : fallback));
+const clampTimeout = (n) => (n === undefined ? undefined : Math.max(1, Math.min(MAX_TIMEOUT_SECONDS, Math.floor(n))));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Bind the client to a side's `callWorkspaceTool`. Authors use `computer(...)`, never this. */
+export function makeComputer(call) {
+    return function computer(ctx, machineNodeId) {
+        const invoke = (tool, args) => call({ pluginId: ctx.pluginId, nodeId: ctx.nodeId, tool, args, appType: "my_computer", targetNodeId: machineNodeId });
+        const result = async (commandId, waitSeconds) => parseCommandOutcome(await invoke("get_computer_result", { commandId, ...(waitSeconds !== undefined ? { waitSeconds: clampWait(waitSeconds) } : {}) }));
+        const untilEnd = async (first, opts, parse) => {
+            const deadline = Date.now() + (opts?.deadlineMs ?? 15 * 60_000);
+            let last = first;
+            while (!isTerminal(last.status)) {
+                if (!last.ok || !last.commandId)
+                    return last; // refused, or nothing to ask about
+                if (last.status === "pending_approval" && !opts?.waitForApproval)
+                    return last;
+                await opts?.onWait?.(last);
+                if (Date.now() >= deadline)
+                    return last;
+                // An approval wait polls gently; a running command waits inside the tool.
+                if (last.status === "pending_approval")
+                    await sleep(3_000);
+                last = parse(await invoke("get_computer_result", { commandId: last.commandId, waitSeconds: clampWait(opts?.waitSeconds ?? 50) }));
+            }
+            return last;
+        };
+        // An answer that names the gate teaches the memory too — a pending approval is a machine on `approve`.
+        const noting = (o) => {
+            if (o.status === "pending_approval")
+                AUTONOMY_SEEN.set(machineNodeId, "approve");
+            return o;
+        };
+        const run = async (command, opts) => noting(parseCommandOutcome(await invoke("run_on_computer", {
+            command,
+            ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+            ...(opts?.timeoutSeconds !== undefined ? { timeoutSeconds: clampTimeout(opts.timeoutSeconds) } : {}),
+            waitSeconds: firstWait(machineNodeId, opts?.waitSeconds, 30),
+        })));
+        const claude = async (prompt, opts) => noting(parseClaudeOutcome(await invoke("claude_task", {
+            prompt,
+            ...(opts?.cwd ? { cwd: opts.cwd } : {}),
+            ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+            ...(opts?.permissionMode ? { permissionMode: opts.permissionMode } : {}),
+            ...(opts?.timeoutSeconds !== undefined ? { timeoutSeconds: clampTimeout(opts.timeoutSeconds) } : {}),
+            waitSeconds: firstWait(machineNodeId, opts?.waitSeconds, 20),
+        })));
+        const runJson = async (command, opts) => {
+            const r = await run(command, { timeoutSeconds: opts?.timeoutSeconds ?? 120, waitSeconds: opts?.waitSeconds, ...(opts?.cwd ? { cwd: opts.cwd } : {}) }).then((first) => untilEnd(first, opts, parseCommandOutcome));
+            const base = { status: r.status, commandId: r.commandId, exitCode: r.exitCode, stderr: r.stderr?.slice(-2000), message: r.message };
+            if (r.status === "pending_approval")
+                return { ok: false, ...base, error: `pending_approval: ${r.message ?? "the machine waits for the owner's approval"}` };
+            // A cut answer first: cut in transit it has no status to read, and "status unknown" would hide why.
+            if (r.truncated)
+                return { ok: false, ...base, truncated: true, error: r.error ?? `the output was longer than the machine keeps (${OUTPUT_LIMIT} characters) and was cut — print less` };
+            if (r.status !== "done")
+                return { ok: false, ...base, error: r.error ?? r.message ?? `status ${r.status}` };
+            if (r.exitCode !== 0)
+                return { ok: false, ...base, error: `exited ${r.exitCode}${r.stderr ? `: ${r.stderr.trim().split("\n").slice(-3).join(" | ")}` : ""}` };
+            const text = (r.stdout ?? "").trim();
+            try {
+                return { ok: true, ...base, json: JSON.parse(text) };
+            }
+            catch {
+                return { ok: false, ...base, error: `the output is not JSON: ${text.slice(0, 200)}` };
+            }
+        };
+        return {
+            machineNodeId,
+            status: async () => {
+                const st = parseStatus(await invoke("computer_status", {}));
+                if (st.autonomy)
+                    AUTONOMY_SEEN.set(machineNodeId, st.autonomy);
+                return st;
+            },
+            run,
+            result,
+            runToEnd: (command, opts) => run(command, opts).then((first) => untilEnd(first, opts, parseCommandOutcome)),
+            claude,
+            claudeToEnd: (prompt, opts) => claude(prompt, opts).then((first) => untilEnd(first, opts, parseClaudeOutcome)),
+            fetchJson: async (url, opts) => {
+                const safeUrl = url.replace(/'/g, "'\\''");
+                const method = opts?.method ?? "GET";
+                const body = opts?.body === undefined ? "" : ` -H 'content-type: application/json' --data-binary '${JSON.stringify(opts.body).replace(/'/g, "'\\''")}'`;
+                // The status code rides on the last line, so a refusal is a status, not a guess.
+                const cmd = `curl -sS --max-time ${Math.max(1, Math.min(120, opts?.timeoutSeconds ?? 20))} -X ${method}${body} -w '\n__HTTP__%{http_code}' '${safeUrl}'`;
+                const r = await run(cmd, { timeoutSeconds: 150, waitSeconds: opts?.waitSeconds ?? 20 }).then((first) => untilEnd(first, opts, parseCommandOutcome));
+                if (r.truncated)
+                    return { ok: false, text: r.stdout ?? "", error: r.error ?? `the answer from ${url} was longer than the machine keeps (${OUTPUT_LIMIT} characters) and was cut — ask for less, or compact it on the machine with runJson/python` };
+                if (r.status !== "done")
+                    return { ok: false, text: r.stdout ?? "", error: r.status === "pending_approval" ? `pending_approval: ${r.message ?? "the machine waits for the owner's approval"}` : r.error ?? r.message ?? `status ${r.status}` };
+                const out = r.stdout ?? "";
+                const m = /\n?__HTTP__(\d{3})\s*$/.exec(out);
+                const status = m ? Number(m[1]) : undefined;
+                const text = m ? out.slice(0, m.index) : out;
+                if (r.exitCode !== 0 && !m)
+                    return { ok: false, text, error: r.stderr || `curl exited ${r.exitCode}` };
+                let json;
+                try {
+                    json = text.trim() ? JSON.parse(text) : undefined;
+                }
+                catch {
+                    json = undefined;
+                }
+                return { ok: status !== undefined && status >= 200 && status < 300, status, json, text, ...(status !== undefined && status >= 300 ? { error: `HTTP ${status}` } : {}) };
+            },
+            runJson: (command, opts) => runJson(command, opts),
+            python: async (script, opts) => {
+                const py = (opts?.python ?? "python3").replace(/'/g, "'\\''");
+                // A quoted heredoc: the script reaches the interpreter byte for byte, no shell expansion.
+                const tag = "ESOUL_PY_EOF";
+                if (script.split("\n").some((l) => l.trim() === tag))
+                    return { ok: false, status: "unknown", error: `the script may not contain a line that is exactly ${tag}` };
+                return runJson(`'${py}' - <<'${tag}'\n${script}\n${tag}`, opts);
+            },
+            readFile: async (path, opts) => {
+                const max = Math.max(1, Math.min(2_000_000, opts?.maxBytes ?? 200_000));
+                const safe = path.replace(/'/g, "'\\''");
+                const r = await run(`head -c ${max} '${safe}'`, { timeoutSeconds: 60, waitSeconds: opts?.waitSeconds ?? 20, ...(opts?.cwd ? { cwd: opts.cwd } : {}) }).then((first) => untilEnd(first, opts, parseCommandOutcome));
+                if (r.status === "done" && r.exitCode === 0)
+                    return { ok: true, text: r.stdout ?? "" };
+                return { ok: false, text: r.stdout ?? "", error: r.error ?? r.stderr ?? r.message ?? `status ${r.status}` };
+            },
+        };
+    };
+}