@luxorai/mcp 0.0.0-stage → 0.3.1

package/dist/client.js

@@ -0,0 +1,575 @@
+/**
+ * TenkiClient — a dependency-free client for the Tenki Cloud API.
+ *
+ * Tenki's API is ConnectRPC (JSON over HTTP/1.1), not REST. Every control-plane
+ * call is `POST {baseUrl}/tenki.sandbox.v1.SandboxService/{Method}` with a
+ * lowerCamelCase JSON body and a JSON response. Per-session file I/O runs on a
+ * separate data-plane endpoint returned at session-create time, authenticated
+ * with a short-lived session certificate.
+ *
+ * The wire details here (headers, the control/data-plane split, and capturing
+ * command stdout/stderr via an `sh -c` redirect + data-plane ReadFile) are
+ * ported from the live-verified n8n community node
+ * (github.com/opencolin/n8n-nodes-tenki).
+ */
+const CONTROL_SERVICE = "tenki.sandbox.v1.SandboxService";
+const DATA_SERVICE = "tenki.sandbox.v1.SandboxSessionDataPlaneService";
+const DEFAULT_BASE_URL = "https://api.tenki.cloud";
+const MAX_RETRIES = 3;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 8000;
+// Rate-limit rejections happen before the server does any work, so they are
+// safe to retry for EVERY method. (For ExecuteCommand this assumes the 429 is
+// the API's own limiter rejecting the call before it ran — true for a
+// ConnectRPC-shaped 429; an intermediary that already forwarded the request
+// would re-run the command.)
+const RATE_LIMIT_CODES = new Set(["rate_limited", "ratelimited", "resource_exhausted", "resourceexhausted"]);
+// Methods that must never double-apply: retrying one that half-applied could
+// boot and bill a second sandbox, publish twice, or re-run a command. The
+// policy is a deny-list shaped by that risk — everything else (reads, and
+// teardown like Terminate*/Delete*/Detach*, where a repeat lands in the same
+// state, worst case a harmless "not found") retries transient failures.
+// Skipping a teardown retry is the expensive mistake: runCode's finally
+// swallows terminate errors, so a transient blip would silently leave a
+// billing sandbox running.
+const NON_IDEMPOTENT_METHOD = /^(Create|Build|Publish|Resume|Extend|ExecuteCommand)/;
+// Data-plane methods safe to retry: read-shaped only. A retried Remove that
+// had actually applied would surface a spurious "not found" for an op that
+// succeeded.
+const DATA_RETRYABLE_METHOD = /^(Read|Stat|List|Get)/;
+const RETRY_AFTER_CAP_MS = 30_000;
+// Every fetch carries a timeout so a hung connection fails the tool call with a
+// clear error instead of blocking it forever (see TenkiClientOptions).
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_EXEC_TIMEOUT_MS = 630_000; // runCode's 600s hard cap + margin
+const EXEC_TIMEOUT_MARGIN_MS = 30_000; // headroom over a command's own timeout
+/**
+ * Methods whose RPC does not return until a long storage/VM operation finishes,
+ * so the 30s default is far too short. A timeout on these is worse than slow:
+ * the operation completes server-side anyway, so the caller is told it failed
+ * while a snapshot (or a paused VM holding a multi-GB pause snapshot) has in
+ * fact been created — an orphaned resource whose id the caller never sees.
+ *
+ * Deliberately limited to the two methods MEASURED to block: CreateSnapshot
+ * (47s observed here; 30s+ elsewhere, with the snapshot ready ~7s in) and
+ * PauseSession (41s observed; the pause itself finished ~7s in). Async methods
+ * that return a handle immediately are NOT listed even though they start long
+ * jobs — BuildTemplate returns PENDING in ~535ms and PublishRegistryImage in
+ * ~278ms, so giving them a 10-minute budget would only delay a genuinely hung
+ * call. Their orphan-on-timeout hazard is real but needs idempotency, not a
+ * bigger timeout.
+ */
+const SLOW_METHOD = /^(CreateSnapshot|PauseSession)$/;
+const DEFAULT_SLOW_TIMEOUT_MS = 600_000;
+// Session-credential cache lifetime handling: a credential whose expiry the API
+// omits (or that we cannot parse) is assumed valid only briefly — never forever —
+// and a known expiry is refreshed early so an in-flight call cannot straddle it.
+// The assumed lifetime can be generous because a stale certificate is recovered
+// by the 401 invalidate-and-re-mint path rather than by cache expiry alone.
+const DEFAULT_CRED_TTL_MS = 300_000;
+const CRED_EXPIRY_SKEW_MS = 30_000;
+const MIN_CRED_TTL_MS = 5_000; // floor for the skewed expiry of a short-lived credential
+/** Home directory of the sandbox's `tenki` user; run-code scripts and capture files live here. */
+const SANDBOX_HOME = "/home/tenki";
+// Inline-output budget per stream (stdout / stderr), in bytes. Outputs at or
+// under the cap return whole; larger ones return a head+tail preview and the
+// full capture file is KEPT in the sandbox so the caller can page through it.
+// The cap exists for the consumer (an LLM context) and for this process: the
+// data plane's ReadFile has no range support, so the only alternative to a
+// server-side preview would be pulling the entire body over the wire.
+const DEFAULT_MAX_OUTPUT_BYTES = 65_536;
+const MIN_OUTPUT_BYTES = 1_024;
+// Head-heavy split: the start of a log names the command/failure context; the
+// tail carries the final error. 3:1 mirrors how people read build output.
+const TRUNCATE_HEAD_FRACTION = 0.75;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function safeJson(text) {
+    try {
+        const p = JSON.parse(text);
+        return typeof p === "object" && p !== null ? p : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** POSIX single-quote a string for safe use inside `sh -c`. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Tenki's auth header is chosen by token prefix (verbatim from the SDK's auth.ts):
+ * `tk_` → Bearer, `ory_st_` → X-Session-Token, otherwise a `tenki_session` cookie.
+ */
+function authHeaders(token) {
+    const t = token.trim();
+    if (t.startsWith("tk_"))
+        return { Authorization: `Bearer ${t}` };
+    if (t.startsWith("ory_st_"))
+        return { "X-Session-Token": t };
+    return { Cookie: `tenki_session=${t}` };
+}
+function interpreterFor(language) {
+    switch (language) {
+        case "python":
+            return { file: `${SANDBOX_HOME}/main.py`, command: "python3", args: [`${SANDBOX_HOME}/main.py`] };
+        case "javascript":
+            return { file: `${SANDBOX_HOME}/main.js`, command: "node", args: [`${SANDBOX_HOME}/main.js`] };
+        case "shell":
+        default:
+            return { file: `${SANDBOX_HOME}/main.sh`, command: "sh", args: [`${SANDBOX_HOME}/main.sh`] };
+    }
+}
+export class TenkiClient {
+    token;
+    baseUrl;
+    credCache = new Map();
+    credInflight = new Map();
+    timeoutMs;
+    execTimeoutMs;
+    slowTimeoutMs;
+    credTtlMs;
+    workspaceId;
+    bearerTokenProvider;
+    constructor(token, baseUrl = DEFAULT_BASE_URL, opts = {}) {
+        this.token = token;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.execTimeoutMs = opts.execTimeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
+        this.slowTimeoutMs = opts.slowTimeoutMs ?? DEFAULT_SLOW_TIMEOUT_MS;
+        this.credTtlMs = opts.credTtlMs ?? DEFAULT_CRED_TTL_MS;
+        this.workspaceId = opts.workspaceId?.trim() || undefined;
+        this.bearerTokenProvider = opts.bearerTokenProvider;
+    }
+    controlAuthHeaders() {
+        if (this.bearerTokenProvider)
+            return { Authorization: `Bearer ${this.bearerTokenProvider()}` };
+        return authHeaders(this.token);
+    }
+    /**
+     * ExecuteCommand blocks until the command finishes, so its timeout follows
+     * the command's own timeout (plus margin) instead of the unary default.
+     */
+    timeoutFor(method, body) {
+        if (SLOW_METHOD.test(method))
+            return this.slowTimeoutMs;
+        if (method !== "ExecuteCommand")
+            return this.timeoutMs;
+        const t = typeof body.timeout === "string" ? Number.parseInt(body.timeout, 10) : Number.NaN; // "30s"
+        return Number.isFinite(t) && t > 0 ? t * 1000 + EXEC_TIMEOUT_MARGIN_MS : this.execTimeoutMs;
+    }
+    /**
+     * fetch + full body read under ONE timeout, with a readable error instead of
+     * a bare AbortError. Reading the body inside the guarded section matters: a
+     * response whose headers arrive but whose body stalls must fail with the
+     * same friendly, retryable timeout as a connection that never responds.
+     */
+    async fetchTextWithTimeout(url, init, timeoutMs, what) {
+        const budget = Math.max(1, Math.floor(timeoutMs));
+        try {
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(budget) });
+            const text = await res.text();
+            return { ok: res.ok, status: res.status, headers: res.headers, text };
+        }
+        catch (e) {
+            const name = e?.name;
+            if (name === "TimeoutError" || name === "AbortError") {
+                throw new Error(`Tenki ${what} timed out after ${budget}ms with no response.`);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Retry policy: rate limits always; `unavailable` and gateway-shaped
+     * 502/503/504 (load balancers and CDNs return these with an HTML or empty
+     * body, no ConnectRPC code) for every method that cannot double-apply.
+     */
+    shouldRetry(method, status, code) {
+        if (status === 429 || RATE_LIMIT_CODES.has(code))
+            return true;
+        const transient = code === "unavailable" || status === 502 || status === 503 || status === 504;
+        return transient && !NON_IDEMPOTENT_METHOD.test(method);
+    }
+    /** Exponential backoff with half-jitter; a Retry-After header (seconds) wins, capped. */
+    backoffMs(attempt, retryAfter) {
+        const ra = retryAfter ? Number.parseInt(retryAfter, 10) : Number.NaN;
+        if (Number.isFinite(ra) && ra >= 0)
+            return Math.min(ra * 1000, RETRY_AFTER_CAP_MS);
+        const base = Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_CAP_MS);
+        return base / 2 + Math.random() * (base / 2);
+    }
+    /**
+     * Unary control-plane call. The WHOLE call — every attempt plus every
+     * backoff sleep — draws from one shared deadline (the method's timeout), so
+     * retries can never stack past it: an MCP client's own 60s default would
+     * otherwise give up before our per-attempt timeouts did. Rate-limit
+     * rejections retry with jittered backoff (honoring Retry-After); transient
+     * `unavailable`/gateway errors AND transport-level failures (timeout,
+     * connection reset, DNS) retry for every method that cannot double-apply.
+     * `service` defaults to SandboxService; pass another fully-qualified ConnectRPC
+     * service (e.g. the SSH gateway service) for methods hosted elsewhere.
+     */
+    async control(method, body = {}, service = CONTROL_SERVICE) {
+        const url = `${this.baseUrl}/${service}/${method}`;
+        const deadline = Date.now() + this.timeoutFor(method, body ?? {});
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetchTextWithTimeout(url, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", "Connect-Protocol-Version": "1", ...this.controlAuthHeaders() },
+                    body: JSON.stringify(body ?? {}),
+                }, deadline - Date.now(), method);
+            }
+            catch (e) {
+                // Transport failure: the request may or may not have reached the
+                // server, so only methods that cannot double-apply are retried.
+                if (attempt < MAX_RETRIES && !NON_IDEMPOTENT_METHOD.test(method)) {
+                    const wait = this.backoffMs(attempt, null);
+                    if (Date.now() + wait < deadline) {
+                        await sleep(wait);
+                        continue;
+                    }
+                }
+                throw e;
+            }
+            if (res.ok)
+                return JSON.parse(res.text);
+            const parsed = safeJson(res.text);
+            const code = typeof parsed?.code === "string" ? parsed.code.toLowerCase() : "";
+            if (attempt < MAX_RETRIES && this.shouldRetry(method, res.status, code)) {
+                const wait = this.backoffMs(attempt, res.headers.get("retry-after"));
+                if (Date.now() + wait < deadline) {
+                    await sleep(wait);
+                    continue;
+                }
+            }
+            const msg = parsed?.message || res.text || `HTTP ${res.status}`;
+            throw new Error(`Tenki ${method} failed (${res.status}${code ? ` ${code}` : ""}): ${msg}`);
+        }
+    }
+    /**
+     * Mint (and cache per session) the data-plane endpoint + session certificate.
+     * A credential with no parseable expiry is cached for credTtlMs — never
+     * forever — and a known expiry is shortened by a skew so an in-flight call
+     * can't straddle the real expiry. Minting is single-flight: concurrent data
+     * calls on a cold cache share one mint instead of each paying a
+     * control-plane round trip for its own certificate.
+     */
+    async credentialFor(sessionId) {
+        const cached = this.credCache.get(sessionId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached;
+        const inflight = this.credInflight.get(sessionId);
+        if (inflight)
+            return inflight;
+        const mint = this.mintCredential(sessionId).finally(() => this.credInflight.delete(sessionId));
+        this.credInflight.set(sessionId, mint);
+        return mint;
+    }
+    async mintCredential(sessionId) {
+        const resp = await this.control("CreateSessionCredential", { sessionId });
+        const cred = resp.credential ?? resp;
+        const token = (cred.credential ?? cred.token);
+        const endpoint = (resp.dataPlaneEndpoint ?? resp.data_plane_endpoint ?? resp.routeStatus?.endpoint);
+        let expiresAt = Date.now() + this.credTtlMs;
+        const raw = cred.expiresAt ?? cred.expires_at;
+        if (typeof raw === "string") {
+            const p = Date.parse(raw);
+            if (!Number.isNaN(p)) {
+                // Floor the skewed expiry so a short-lived credential (< skew) is
+                // still cached briefly instead of the cache being disabled outright.
+                // An ALREADY-expired credential is not cached at all (expiresAt 0):
+                // flooring it would serve a known-dead cert from cache, turning
+                // every data call into a guaranteed 401 → re-mint round trip.
+                expiresAt = p > Date.now() ? Math.max(p - CRED_EXPIRY_SKEW_MS, Date.now() + MIN_CRED_TTL_MS) : 0;
+            }
+        }
+        const entry = { endpoint: endpoint ?? "", token, expiresAt };
+        this.credCache.set(sessionId, entry);
+        return entry;
+    }
+    /**
+     * Unary data-plane call. The inner request is wrapped as
+     * `{ request: { sessionId, ...request } }`. This is the path behind every
+     * file tool AND how tenki_exec reads back its own output, so it gets the
+     * same treatment as the control plane: one shared deadline, rate limits
+     * retried for every method, transient/gateway/transport failures retried
+     * for read-shaped methods. A stale-certificate failure (401/unauthenticated
+     * — the cert may have expired server-side regardless of its stated expiry)
+     * invalidates the cache and re-mints once; permission_denied is NOT an auth
+     * failure — a denied path is a normal user error a fresh cert can never
+     * fix, so re-minting would waste a control-plane round trip per denied call.
+     */
+    async data(sessionId, method, request = {}) {
+        const deadline = Date.now() + this.timeoutMs;
+        let remintedAuth = false;
+        for (let attempt = 0;;) {
+            const cred = await this.credentialFor(sessionId);
+            if (!cred.endpoint) {
+                throw new Error(`Could not resolve the data-plane endpoint for session ${sessionId}.`);
+            }
+            const url = `${cred.endpoint.replace(/\/+$/, "")}/${DATA_SERVICE}/${method}`;
+            let res;
+            try {
+                res = await this.fetchTextWithTimeout(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Connect-Protocol-Version": "1",
+                        "x-tenki-session-cert": cred.token,
+                    },
+                    body: JSON.stringify({ request: { sessionId, ...request } }),
+                }, deadline - Date.now(), `data ${method}`);
+            }
+            catch (e) {
+                if (attempt < MAX_RETRIES && DATA_RETRYABLE_METHOD.test(method)) {
+                    const wait = this.backoffMs(attempt++, null);
+                    if (Date.now() + wait < deadline) {
+                        await sleep(wait);
+                        continue;
+                    }
+                }
+                throw e;
+            }
+            if (res.ok) {
+                const wrapped = JSON.parse(res.text);
+                return wrapped.response ?? wrapped;
+            }
+            const parsed = safeJson(res.text);
+            const code = typeof parsed?.code === "string" ? parsed.code.toLowerCase() : "";
+            if ((res.status === 401 || code === "unauthenticated") && !remintedAuth) {
+                remintedAuth = true;
+                this.credCache.delete(sessionId);
+                continue; // re-mint doesn't consume a retry attempt
+            }
+            const transient = code === "unavailable" || res.status === 502 || res.status === 503 || res.status === 504;
+            const retryable = res.status === 429 || RATE_LIMIT_CODES.has(code) || (transient && DATA_RETRYABLE_METHOD.test(method));
+            if (attempt < MAX_RETRIES && retryable) {
+                const wait = this.backoffMs(attempt++, res.headers.get("retry-after"));
+                if (Date.now() + wait < deadline) {
+                    await sleep(wait);
+                    continue;
+                }
+            }
+            throw new Error(`Tenki data ${method} failed (${res.status}): ${parsed?.message || res.text}`);
+        }
+    }
+    /**
+     * Resolve the calling identity + a default workspace for CreateSession and
+     * other workspace-scoped calls. (Projects were removed from the API — the
+     * proto reserves every project_id field and WhoAmI no longer lists projects —
+     * so there is nothing narrower than a workspace to resolve.)
+     *
+     * CreateSession validates owner_type ∈ {SERVICE, USER} and requires a
+     * non-empty owner_id, but derives the real owner from the authenticated
+     * identity server-side. WhoAmI can return other owner types (e.g. WORKSPACE
+     * for workspace-scoped keys), which the validator rejects — so for those we
+     * send the same placeholder the first-party SDKs hardcode ("SERVICE"/"self").
+     */
+    async resolveOwner() {
+        const resp = await this.control("WhoAmI", {});
+        const workspaces = Array.isArray(resp.workspaces) ? resp.workspaces : [];
+        const ws = this.workspaceId
+            ? workspaces.find((candidate) => (candidate?.workspaceId ?? candidate?.id) === this.workspaceId)
+            : workspaces[0];
+        let ownerType = resp.ownerType;
+        let ownerId = resp.ownerId;
+        // Substitute the placeholder only when WhoAmI returned a type CreateSession
+        // rejects. When ownerType is absent entirely, leave it absent — callers omit
+        // the owner fields and the server derives the owner from the identity.
+        if (ownerType && ownerType !== "USER" && ownerType !== "SERVICE") {
+            ownerType = "SERVICE";
+            ownerId = "self";
+        }
+        return {
+            ownerType,
+            ownerId,
+            workspaceId: this.workspaceId ?? ws?.workspaceId ?? ws?.id,
+        };
+    }
+    /** Poll GetSession until it reaches (or passes into) the target state. */
+    async waitForState(sessionId, target = "RUNNING", { timeoutMs = 180000, intervalMs = 1000 } = {}) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const resp = await this.control("GetSession", { sessionId });
+            const session = resp.session ?? resp;
+            const state = String(session.state ?? "");
+            if (state.includes(target))
+                return session;
+            if (["TERMINATED", "ERROR", "FAILED"].some((s) => state.includes(s))) {
+                throw new Error(`Session ${sessionId} entered ${state} while waiting for ${target}.`);
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for session ${sessionId} to reach ${target} (last state: ${state}).`);
+            }
+            await sleep(intervalMs);
+        }
+    }
+    async readTextFile(sessionId, path) {
+        const resp = await this.data(sessionId, "ReadFile", { path });
+        const content = (resp.content ?? resp.data ?? resp.file?.content ?? "");
+        return content ? Buffer.from(content, "base64").toString("utf8") : "";
+    }
+    async writeTextFile(sessionId, path, text) {
+        const content = Buffer.from(text, "utf8").toString("base64");
+        return this.data(sessionId, "WriteFile", { path, content });
+    }
+    /**
+     * Read a capture file back, capping what crosses the wire. Stat first: a
+     * file at or under the cap is read whole; a larger one gets a server-side
+     * head+tail preview (assembled by `sh` in the sandbox, so the full body
+     * never leaves it — ReadFile has no range support). The preview file is the
+     * caller's to clean up (returned as previewPath); the ORIGINAL is theirs to
+     * keep, so the user can page through the full output afterwards.
+     */
+    async readCaptureFile(sessionId, path, capBytes) {
+        // Stat is an optimization (skip pulling a body we'd mostly discard), not a
+        // gate: if it fails, fall back to the plain whole read — whose own failure
+        // still surfaces as captureError in the caller.
+        let size;
+        try {
+            const stat = await this.data(sessionId, "Stat", { path });
+            size = Number(stat.size ?? 0); // int64 arrives as a JSON string
+        }
+        catch {
+            size = undefined;
+        }
+        if (size === undefined || !Number.isFinite(size) || size <= capBytes) {
+            return { text: await this.readTextFile(sessionId, path), truncated: false };
+        }
+        const head = Math.floor(capBytes * TRUNCATE_HEAD_FRACTION);
+        const tail = capBytes - head;
+        const previewPath = `${path}.preview`;
+        const marker = `\n[... output truncated: ${size} bytes total, showing the first ${head} and last ${tail}. Full output kept in the sandbox at ${path} ...]\n`;
+        const script = `{ head -c ${head} ${shellQuote(path)}; printf %s ${shellQuote(marker)}; tail -c ${tail} ${shellQuote(path)}; } > ${shellQuote(previewPath)}`;
+        await this.control("ExecuteCommand", { sessionId, command: "sh", args: ["-c", script] });
+        return { text: await this.readTextFile(sessionId, previewPath), truncated: true, previewPath };
+    }
+    /**
+     * Run a command in a session and return stdout/stderr inline.
+     *
+     * We wrap the command in `sh -c '<cmd> > out 2> err'`, then read the capture
+     * files back over the data plane, so output is available through a plain-HTTP
+     * client. Capture-read failures degrade gracefully into `captureError` rather
+     * than losing the run — but the result is marked NOT ok, because empty
+     * stdout/stderr next to a zero exit code would otherwise read as a clean,
+     * silent success. Streams over maxOutputBytes come back truncated
+     * (head+tail) with the full capture file retained in the sandbox — see
+     * readCaptureFile; truncation does not affect `ok`.
+     */
+    async execCaptured(sessionId, command, opts = {}) {
+        const suffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const outPath = `${SANDBOX_HOME}/.mcp-exec-${suffix}.out`;
+        const errPath = `${SANDBOX_HOME}/.mcp-exec-${suffix}.err`;
+        const execLine = [command, ...(opts.args ?? [])].map(shellQuote).join(" ");
+        // .trim() only decides WHETHER a cd is emitted; the quoted value passes
+        // through verbatim — trailing/leading whitespace is legal in dir names.
+        // `--` is required: quoting does not stop `cd` from reading a leading-hyphen
+        // value as an option, and `cd -L` silently succeeds into HOME instead of
+        // failing, so the command would then run in the wrong directory.
+        const cd = opts.cwd && opts.cwd.trim() ? `cd -- ${shellQuote(opts.cwd)} && ` : "";
+        const script = `${cd}${execLine} > ${outPath} 2> ${errPath}`;
+        const body = { sessionId, command: "sh", args: ["-c", script] };
+        if (opts.env && Object.keys(opts.env).length)
+            body.env = opts.env;
+        if (opts.timeoutSeconds && opts.timeoutSeconds > 0)
+            body.timeout = `${opts.timeoutSeconds}s`;
+        const resp = await this.control("ExecuteCommand", body);
+        const execution = resp.execution ?? resp;
+        // proto3 omits zero-valued fields: an absent exitCode means 0 (success).
+        // A non-numeric shape coerces to NaN, which the exec outputSchema rejects,
+        // failing the whole call and discarding the run's output — normalize an
+        // unparseable code to -1 so the user still gets their stdout/stderr.
+        const rawExit = typeof execution.exitCode === "number" ? execution.exitCode : Number(execution.exitCode ?? 0);
+        const exitCode = Number.isFinite(rawExit) ? Math.trunc(rawExit) : -1;
+        const cap = Math.max(MIN_OUTPUT_BYTES, Math.floor(opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES));
+        let stdout = "";
+        let stderr = "";
+        let captureError;
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        // Truncated originals are KEPT (their path is returned) so the caller can
+        // page through them; everything else — untruncated captures, previews — is
+        // removed.
+        const toRemove = [];
+        try {
+            const [out, err] = await Promise.all([
+                this.readCaptureFile(sessionId, outPath, cap),
+                this.readCaptureFile(sessionId, errPath, cap),
+            ]);
+            stdout = out.text;
+            stderr = err.text;
+            stdoutTruncated = out.truncated;
+            stderrTruncated = err.truncated;
+            if (out.previewPath)
+                toRemove.push(out.previewPath);
+            if (err.previewPath)
+                toRemove.push(err.previewPath);
+        }
+        catch (e) {
+            captureError = e.message;
+        }
+        if (!stdoutTruncated)
+            toRemove.push(outPath);
+        if (!stderrTruncated)
+            toRemove.push(errPath);
+        try {
+            await this.control("ExecuteCommand", { sessionId, command: "rm", args: ["-f", ...toRemove] });
+        }
+        catch {
+            // Session may have gone away; capture files die with it.
+        }
+        return {
+            command,
+            args: opts.args ?? [],
+            stdout,
+            stderr,
+            exitCode,
+            ok: exitCode === 0 && !captureError,
+            ...(captureError ? { captureError } : {}),
+            ...(stdoutTruncated ? { stdoutTruncated: true, stdoutPath: outPath } : {}),
+            ...(stderrTruncated ? { stderrTruncated: true, stderrPath: errPath } : {}),
+        };
+    }
+    /**
+     * One-shot: boot a throwaway sandbox, run code (shell / python / javascript),
+     * return its output, and terminate the sandbox. Cost-guarded (1 vCPU, 1 GB,
+     * 10-min cap, 5-min idle) so an ephemeral run can never leak a billing session.
+     */
+    async runCode(language, code, opts = {}) {
+        const owner = await this.resolveOwner();
+        const create = await this.control("CreateSession", {
+            cpuCores: 1,
+            memoryMb: 1024,
+            maxDuration: "600s",
+            idleTimeoutMinutes: 5,
+            ...(owner.ownerType ? { ownerType: owner.ownerType } : {}),
+            ...(owner.ownerId ? { ownerId: owner.ownerId } : {}),
+            ...(owner.workspaceId ? { workspaceId: owner.workspaceId } : {}),
+            ...(opts.env && Object.keys(opts.env).length ? { env: opts.env } : {}),
+        });
+        const session = create.session ?? create;
+        const sessionId = (session.id ?? create.sessionId ?? create.id);
+        if (!sessionId)
+            throw new Error("runCode: could not read the created session id from CreateSession.");
+        try {
+            await this.waitForState(sessionId, "RUNNING");
+            const { file, command, args } = interpreterFor(language);
+            await this.writeTextFile(sessionId, file, code);
+            const result = await this.execCaptured(sessionId, command, {
+                args,
+                env: opts.env,
+                timeoutSeconds: opts.timeoutSeconds,
+            });
+            return { sessionId, language, ...result };
+        }
+        finally {
+            try {
+                await this.control("TerminateSession", { sessionId });
+            }
+            catch {
+                // Best-effort teardown; the idle/max-duration guards reap it regardless.
+            }
+        }
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,17 @@
+/**
+ * HTTP/SSE transport for tenki-mcp (v2.0) — makes the server hostable, not just
+ * local-stdio. Uses the MCP SDK's StreamableHTTPServerTransport with a stateful
+ * per-session model: one server + transport per MCP session.
+ *
+ * Enable with TENKI_MCP_TRANSPORT=http. Config:
+ *   PORT                   — listen port (default 3000)
+ *   TENKI_MCP_HTTP_HOST    — bind host (default 127.0.0.1, loopback-only)
+ *   TENKI_MCP_HTTP_TOKEN   — required Bearer token for the /mcp endpoint
+ *
+ * Security posture: loopback-only by default; DNS-rebinding protection on
+ * (Host allowlist); static bearer auth or OAuth required for non-loopback
+ * binds; and per-session/global DoS caps are applied.
+ */
+import http from "node:http";
+import { TenkiClient } from "./client.js";
+export declare function startHttp(client: TenkiClient | null, port: number): http.Server;