@luxorai/mcp 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to `@tenkicloud/mcp`. This project follows semantic versioning.
 
+## [0.4.0] - 2026-11-10
+
+- Read `LUXORAI_*` environment variables before their `TENKI_*` equivalents (credentials, endpoint, and every `TENKI_MCP_*` option). `TENKI_*` keeps working.
+- Accept `lx_` API keys alongside `tk_`.
+- `TENKI_MCP_OAUTH_RESOURCE` accepts a comma-separated list; protected-resource metadata returns the entry matching the request host.
+- Add a `luxor-mcp` bin alias and a `luxor` Claude Code plugin. Prepare a gated dual publish as `@luxorai/mcp` (`io.github.LuxorLabs/luxor-mcp`, `ghcr.io/luxorlabs/luxor-mcp`).
+- Remove `tenki_get_workspace_settings`, `tenki_update_workspace_settings`, `tenki_get_snapshot_retention_settings` and `tenki_update_snapshot_retention_settings`: their API methods were removed upstream and every call returned 404. Plan limits are visible through `tenki_get_workspace_usage`.
+- Add `tenki_get_sandbox_metrics` (CPU/memory averages over a window) and `tenki_get_workspace_preview_domains` / `tenki_update_workspace_preview_domains` (wildcard preview domains).
+- Fix `tenki_attach_volume` `read_only`, which the API silently ignored (wrong wire field name); the mount was always read-write.
+- Fix `tenki_update_sandbox`: `max_duration_seconds` always failed (the API requires an explicit sticky value — sticky=false is now sent for you after checking the sandbox is not sticky; a sticky sandbox is refused without an explicit `sticky`); `tags: []` now clears tags; new `sticky` and `clear_tags` arguments; `idle_timeout_minutes` removed because the API cannot change it after creation.
+- Fix `tenki_list_ssh_gateways`: `workspace_id` did nothing; the tool now takes `region` and/or `session_id`.
+- `tenki_get_download_url` no longer requires `session_id` (the API ignores it).
+- `tenki_list_preview_urls` filters by `session_id` on the server instead of on the fetched page.
+- `tenki_create_sandbox`: explicit `allow_inbound: false` / `allow_outbound: false` are sent; new `sticky`, `volumes`, `ssh_authorized_keys`, `metadata`, `egress_allow_domains` / `egress_allow_cidrs`, `template_spec_id`, `setup_env`, `setup_secrets`, `secret_overrides`; the server-side ready wait is used; API `warnings` are returned; `memory_mb` must be even and `disk_size_gb` 5-100.
+- New optional arguments: `async` on `tenki_pause_sandbox` and `tenki_create_snapshot`; `tags` / `clear_tags` on `tenki_update_snapshot` and `tenki_update_volume`, plus `clear_expires_at` on snapshots; `force` on `tenki_detach_volume`; `mode` on `tenki_make_dir`; `expires_at` on `tenki_expose_port` and `tenki_bind_preview_url`; `slug` lookup on `tenki_get_preview_url`; `requested_ttl_seconds` / `source_addresses` on `tenki_issue_ssh_cert`; `tags` / `sticky` filters on the sandbox lists.
+- Tool descriptions now flag the API-deprecated methods behind `tenki_expose_port`, `tenki_unexpose_port`, `tenki_list_exposed_ports`, `tenki_list_workspace_sandboxes` and `tenki_list_workspace_snapshots`, and point to the replacements.
+- `tenki_create_sandbox`: `cpu_cores` up to 128 and `memory_mb` up to 524288 (the API's new ceilings; your plan may cap lower); new `secret_files` (write a workspace secret or inline text to a guest path at boot), `secret_policies` (attach saved secret access policies that inject workspace secrets into matching outbound HTTPS requests) and `tailnet` (join the sandbox to a Tailscale tailnet with an auth key, where the workspace allows it). Template `cpu_cores` / `memory_mb` bounds raised to match.
+- Server-side `search`, `states`, `sort_by` / `sort_desc` and `include_facets` on `tenki_list_workspace_sandboxes` (plus `order`), `tenki_list_volumes`, `tenki_list_templates` and `tenki_list_preview_urls`; preview-URL rows now include the bound sandbox's state and name.
+- `tenki_issue_ssh_cert` documents the new `pinHostKey` flag (verify the gateway host certificate against `caPub`).
+- Contradictory or empty updates are rejected before any call: `tags`+`clear_tags`, `expires_at`+`clear_expires_at`, an egress allowlist with `allow_outbound: false`, and update calls with nothing to change (sandbox, snapshot, volume, template).
+- Add `tenki_list_template_builds` (every build of a template with per-image storage and whether it can be deleted) and `tenki_delete_template_build` (free a build's image and any published image version carrying it; refused while the image is still referenced, e.g. published, in use by a non-terminated sandbox, building or tagged).
+- Add `tenki_create_egress_policy`, `tenki_get_egress_policy`, `tenki_list_egress_policies`, `tenki_update_egress_policy` and `tenki_delete_egress_policy` for named workspace egress policies.
+- `tenki_create_sandbox`: new `egress_policies` (pin saved egress policies by name), `egress_intercept_https` (check each HTTPS request's host) and `egress_http_rules` (allow only matching HTTP methods and paths per host).
+- Add `tenki_fork_sandbox` (start copies of a running sandbox from a fresh snapshot of its memory and disk) and `tenki_list_ci_runner_sizes` (the runs-on sizes Tenki CI can run for the workspace).
+- `tenki_create_sandbox`: new `egress_allowed_ports` (extra TCP ports alongside HTTPS interception, also `allowed_ports` on the egress policy tools), `disable_tailnet` (skip the workspace's default Tailscale connection) and `tailnet.connection_id` / `connection_revision` (join with a Tailscale connection saved in the dashboard instead of an auth key).
+- Descriptions now match the API: HTTPS interception limits public egress to ports 80/443; a volume still syncing back cannot be detached, even with `force`; expired snapshots cannot be booted from or updated, and pause snapshots cannot be booted from or have their expiry changed; another workspace's image with runtime secrets needs each one selected in `secret_overrides`; `tenki_pause_sandbox` returns once the checkpoint is saved on the host, and a tailnet-attached sandbox cannot be paused yet.
+- A fork that fails partway names the snapshot and sandboxes it already created, and is never retried automatically. Create, fork and other non-repeatable calls refused by a workspace limit now fail at once instead of retrying.
+- `tenki_resize_volume` and `tenki_detach_volume` descriptions now match the API: only a never-attached volume can be resized, and a forced detach loses unflushed writes.
+- Update `@modelcontextprotocol/sdk` to 1.32.1 (fixes GHSA-6qxp-vccf-f47h: the OAuth client could send credentials to an authorization server chosen by the MCP server) and refresh transitive pins flagged by `npm audit`.
+- `tenki_resume_sandbox` matches the API's new resume behavior (sandbox-engine v2.35.0): it waits until the sandbox is RUNNING with the 600s slow-operation budget instead of 30s, takes `async` to return once the resume is accepted, and a wait that times out says the sandbox may still be resuming. Calling it again joins a resume in progress.
+- **Breaking:** `tenki_git` is replaced by `tenki_git_clone`, `tenki_git_checkout`, `tenki_git_diff` and `tenki_git_log`, so reads and writes are separate tools. Each takes typed arguments instead of an `operation` + `args` map, and checkout/diff/log take `directory` to target a repository cloned into a subdirectory (previously they always ran in `/home/tenki` and failed with "not a git repository"). Values git would parse as options (a leading `-`, e.g. `--output=<file>`) are refused, and output over 64 KiB is truncated with `totalBytes`.
+- Every tool now has a human-readable `title` (MCP `Tool.title` and `annotations.title`).
+- `destructiveHint` now marks every tool that can overwrite, modify, interrupt or delete existing state, not only deletes: `tenki_exec`, `tenki_write_file`, `tenki_move_path`, `tenki_git_checkout`, every `update` tool, `tenki_pause_sandbox`, `tenki_open_preview`, `tenki_bind_preview_url`, `tenki_resize_volume`, `tenki_cancel_template_build`, `tenki_build_template` (a build with `image_name` changes what `workspace/name` boots) and `tenki_get_upload_url`. Clients that prompt before destructive tools will now prompt for these. Only tools that only add, never change or remove what exists: create (sandboxes, forks, clones, snapshots, volumes, templates, egress policies, preview URLs, port exposures, directories, SSH certificates), resume, extend, attach a volume, keep-alive are non-destructive.
+- `tenki_read_file` returns at most `max_bytes` (default 65536, up to 1 MiB) from `offset`, with `totalBytes`, and `truncated` + `nextOffset` when more remains. Cuts never split a UTF-8 character. Previously it returned the whole file.
+- `tenki_open_preview`'s description now says what it returns (a viewer-token-gated, non-public URL; 7681 is the web terminal) and that reopening a port replaces its earlier URL, instead of steering callers away from it.
+- Every tool parameter now has a description.
+
 ## [0.2.0] — 2026-08-21
 
 - Remove standalone image management tools. Template images remain available through template builds and sandbox creation.

package/README.md

@@ -128,35 +128,40 @@ Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` comman
 | `TENKI_MCP_HTTP_TOKEN` | — | Bearer token for the HTTP endpoint; optional on loopback, required on a non-loopback host. |
 | `TENKI_MCP_PUBLIC_URL` | — | Public base URL for an OAuth-protected hosted server. |
 | `TENKI_MCP_OAUTH_ISSUER` | — | OAuth authorization-server issuer. Enables delegated OAuth HTTP mode. |
-| `TENKI_MCP_OAUTH_RESOURCE` | `<public URL>/mcp` | RFC 8707 resource identifier accepted in access-token audiences. |
+| `TENKI_MCP_OAUTH_RESOURCE` | `<public URL>/mcp` | RFC 8707 resource identifier accepted in access-token audiences. A comma-separated list serves one resource per domain; metadata returns the one matching the request host, else the first. |
 | `TENKI_MCP_OAUTH_SCOPE` | `mcp` | Required delegated scope. |
 | `TENKI_MCP_IDENTITY_URL` | — | Internal Tenki Identity service endpoint used to exchange OAuth access tokens. |
 | `TENKI_MCP_IDENTITY_SERVICE_TOKEN` | — | Service credential for the private Identity token-exchange RPC. |
 
+Every `TENKI_*` variable above also has a `LUXORAI_*` equivalent (for example `LUXORAI_API_KEY`, `LUXORAI_MCP_TRANSPORT`). All `LUXORAI_*` credentials are read before any `TENKI_*` one, and `lx_…` API keys are accepted alongside `tk_…`.
+
 ## Tools
 
-**71 tools** — all 68 public unary API methods (enforced by a CI [parity audit](scripts/parity-audit.mjs)), two workflow helpers, and `tenki_auth_status`. Implementation-only control-plane methods are intentionally excluded. Grouped by domain:
+**82 tools** — all 76 tool-worthy public unary API methods (enforced by a CI [parity audit](scripts/parity-audit.mjs), which also fails if a tool calls a method the API no longer has; `GitOperation` is exposed as one tool per operation), two workflow helpers, and `tenki_auth_status`. A few admin surfaces (published images, saved Tailscale connections) and implementation-only control-plane methods are intentionally excluded. Grouped by domain:
 
 | Domain | Tools |
 |---|---|
 | **Auth** | `tenki_auth_status` (which credential is configured, and does it work — the only tool available when none is) |
 | **Identity** | `tenki_whoami` |
 | **Run** | `tenki_run_code` (one-shot: boot → run shell/python/js → tear down) |
-| **Sandboxes** | `tenki_create_sandbox` · `tenki_get_sandbox` · `tenki_list_sandboxes` · `tenki_terminate_sandbox` · `tenki_pause_sandbox` · `tenki_resume_sandbox` |
+| **Sandboxes** | `tenki_create_sandbox` · `tenki_get_sandbox` · `tenki_get_sandbox_metrics` · `tenki_list_sandboxes` · `tenki_terminate_sandbox` · `tenki_pause_sandbox` · `tenki_resume_sandbox` · `tenki_fork_sandbox` (copies of a running sandbox) |
 | **Session admin** | `tenki_extend_sandbox` · `tenki_update_sandbox` · `tenki_terminate_sandboxes` (bulk) · `tenki_report_sandbox_activity` · `tenki_list_workspace_sandboxes` |
 | **Exec** | `tenki_exec` (stdout/stderr/exit inline) |
 | **Files** | `tenki_read_file` · `tenki_write_file` · `tenki_list_files` · `tenki_stat_path` · `tenki_make_dir` · `tenki_remove_path` · `tenki_move_path` |
-| **Git** | `tenki_git` (clone/checkout/diff/log — the API supports exactly these four; run other git commands via `tenki_exec`) |
-| **Ports & previews** | expose · list-exposed · unexpose · create-preview-url · open-preview · list/get/delete-preview-url · touch-preview · bind/unbind-preview-url · resolve-preview-token |
+| **Git** | `tenki_git_clone` · `tenki_git_checkout` · `tenki_git_diff` · `tenki_git_log` (the four operations the API supports; pass `directory` to target a cloned repo; run other git commands via `tenki_exec`) |
+| **Ports & previews** | expose · list-exposed · unexpose · create-preview-url · open-preview (viewer-token-gated, not public; port 7681 is the web terminal) · list/get/delete-preview-url · touch-preview · bind/unbind-preview-url · resolve-preview-token |
 | **Artifacts** (binary transfer) | `tenki_get_upload_url` · `tenki_get_download_url` (signed URLs for binary PUT/GET) |
 | **SSH** | `tenki_update_ssh_keys` · `tenki_issue_ssh_cert` · `tenki_list_ssh_gateways` |
 | **Snapshots** | create · get · list · list-session · list-workspace · list-dangling · update · delete · get-download-url |
 | **Volumes** | create · get · list · update · delete · resize · attach · detach |
-| **Templates** | create · get · list · update · delete · build · cancel-build · get-build · list-active-builds |
-| **Workspace** | `tenki_get_workspace_usage` · `tenki_get_workspace_settings` · `tenki_update_workspace_settings` · `tenki_get_snapshot_retention_settings` · `tenki_update_snapshot_retention_settings` |
+| **Egress policies** | create · get · list · update · delete (named workspace allowlists that `tenki_create_sandbox` pins via `egress_policies`) |
+| **Templates** | create · get · list · update · delete · build · cancel-build · get-build · list-active-builds · list-builds · delete-build |
+| **Workspace** | `tenki_get_workspace_usage` · `tenki_list_ci_runner_sizes` · `tenki_get_workspace_preview_domains` · `tenki_update_workspace_preview_domains` |
 
 Full per-release breakdown in [CHANGELOG.md](CHANGELOG.md).
 
+**Deprecated upstream, still served:** `tenki_expose_port` / `tenki_unexpose_port` / `tenki_list_exposed_ports` (the API prefers the preview-URL tools), `tenki_list_workspace_sandboxes` / `tenki_list_workspace_snapshots` (prefer the credential-scoped lists), and the `ExecuteCommand` RPC behind `tenki_exec` / `tenki_run_code` / `tenki_move_path` (successor is the data-plane `Run` stream, which needs an HTTP/2 transport this server does not have yet). The parity audit prints these on every run.
+
 ## Auth
 
 Set one of `TENKI_API_KEY` or `TENKI_AUTH_TOKEN` — when both are set, `TENKI_AUTH_TOKEN` wins. The header is chosen by token prefix: `tk_…` → `Authorization: Bearer`, `ory_st_…` → `X-Session-Token`, otherwise a session cookie. Override the endpoint with `TENKI_API_ENDPOINT` (default `https://api.tenki.cloud`).
@@ -200,7 +205,7 @@ The wire details are ported from the live-verified [n8n community node](https://
 
 This server holds a Tenki API key and can run code + spend credits, so treat it as a capability. Full model + [CSA MCP Server Top-10](https://modelcontextprotocol-security.io/top10/server/) mapping in **[SECURITY.md](SECURITY.md)**. Quick controls:
 
-- **Least privilege:** every tool carries MCP annotations (`readOnlyHint` / `destructiveHint`). Run `TENKI_MCP_READONLY=1` for an inspection-only server (read tools only), or `TENKI_MCP_DISABLED_TOOLS=tenki_run_code,…` to drop specific tools.
+- **Least privilege:** every tool carries a title and MCP annotations: `readOnlyHint` on reads, and `destructiveHint` on every tool that can overwrite, modify, interrupt or delete existing state (only tools that create, resume, extend, attach or keep alive without changing existing state are non-destructive). Run `TENKI_MCP_READONLY=1` for an inspection-only server (read tools only), or `TENKI_MCP_DISABLED_TOOLS=tenki_run_code,…` to drop specific tools.
 - **HTTP transport** is loopback-only by default and requires a bearer token to expose to a network (see [Host it over HTTP](#host-it-over-http-v20-beta)).
 - **Audit:** `TENKI_MCP_AUDIT=1` logs each tool call's name to stderr.
 - **Untrusted output:** `tenki_run_code`/`tenki_exec`/`tenki_read_file` return output from untrusted code — clients should treat tool results as data, not instructions.

package/SECURITY.md

@@ -13,8 +13,8 @@ Please **do not** open a public issue for security reports. Open a private [GitH
 ## Controls this server provides
 
 ### Least privilege (MCP-07 — the main lever)
-Every tool is tagged with MCP **annotations** so clients can surface/gate danger:
-`readOnlyHint` on inspection tools, `destructiveHint` on the 13 that delete/terminate/revoke, `openWorldHint` on all (they call an external API). Plus two env controls:
+Every tool has a human-readable **title** and MCP **annotations** so clients can surface/gate danger:
+`readOnlyHint` on the 35 inspection tools; `destructiveHint` on the 30 that can overwrite, modify, interrupt or delete existing state (delete/terminate/detach, but also `tenki_exec`, `tenki_write_file`, `tenki_move_path`, `tenki_git_checkout`, every `update` tool, `tenki_pause_sandbox`, `tenki_build_template` (a named build repoints `workspace/name`), and `tenki_get_upload_url`, whose signed PUT can overwrite a file); neither on the 17 additive tools that only add, never change or remove what exists: create (sandboxes, forks, clones, snapshots, volumes, templates, egress policies, preview URLs, port exposures, directories, SSH certificates), resume, extend, attach a volume, keep-alive; `openWorldHint` on all (they call an external API). Destructive is the default: a new tool is non-destructive only once it is listed as additive in `src/server.ts`. Plus two env controls:
 
 | Env | Effect |
 |---|---|

package/dist/client.d.ts

@@ -12,6 +12,12 @@
  * ported from the live-verified n8n community node
  * (github.com/opencolin/n8n-nodes-tenki).
  */
+/**
+ * True when the call ended on THIS side — the client's deadline or an MCP-side
+ * cancel — so the server never answered and the operation may still complete.
+ * A server error never carries the marker, even when its message says "timed out".
+ */
+export declare function isClientAbort(e: unknown): boolean;
 export type Language = "shell" | "python" | "javascript";
 export interface ExecResult {
     command: string;
@@ -71,6 +77,10 @@ export declare class TenkiClient {
      * 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.
+     * For a method that cannot double-apply, a Connect `resource_exhausted` (the
+     * handler's own quota or limit check; edge rate limits arrive as an uncoded
+     * 429) or any rejection carrying error details (a fork's partial snapshot and
+     * children) means the handler ran, so it is never retried.
      */
     private shouldRetry;
     /** Exponential backoff with half-jitter; a Retry-After header (seconds) wins, capped. */
@@ -85,8 +95,11 @@ export declare class TenkiClient {
      * 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.
+     * `cancel` (the MCP request's abort signal) drops the HTTP request when the
+     * MCP client gives up, so the API sees the disconnect; a cancelled call is
+     * never retried.
      */
-    control(method: string, body?: Record<string, unknown>, service?: string): Promise<Record<string, any>>;
+    control(method: string, body?: Record<string, unknown>, service?: string, cancel?: AbortSignal): Promise<Record<string, any>>;
     /**
      * Mint (and cache per session) the data-plane endpoint + session certificate.
      * A credential with no parseable expiry is cached for credTtlMs — never
@@ -132,6 +145,8 @@ export declare class TenkiClient {
         timeoutMs?: number;
         intervalMs?: number;
     }): Promise<Record<string, any>>;
+    /** A file's raw bytes. The data plane's ReadFile has no range support, so this is always the whole file. */
+    readFileBytes(sessionId: string, path: string): Promise<Buffer>;
     readTextFile(sessionId: string, path: string): Promise<string>;
     writeTextFile(sessionId: string, path: string, text: string): Promise<Record<string, any>>;
     /**

package/dist/client.js

@@ -12,6 +12,7 @@
  * ported from the live-verified n8n community node
  * (github.com/opencolin/n8n-nodes-tenki).
  */
+import { isApiKey } from "./env.js";
 const CONTROL_SERVICE = "tenki.sandbox.v1.SandboxService";
 const DATA_SERVICE = "tenki.sandbox.v1.SandboxSessionDataPlaneService";
 const DEFAULT_BASE_URL = "https://api.tenki.cloud";
@@ -32,7 +33,7 @@ const RATE_LIMIT_CODES = new Set(["rate_limited", "ratelimited", "resource_exhau
 // 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)/;
+const NON_IDEMPOTENT_METHOD = /^(Create|Build|Publish|Resume|Extend|Fork|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.
@@ -43,6 +44,7 @@ const RETRY_AFTER_CAP_MS = 30_000;
 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
+const CREATE_WAIT_READY_TIMEOUT_MS = 90_000; // server holds wait_ready up to 60s + margin
 /**
  * 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:
@@ -58,8 +60,26 @@ const EXEC_TIMEOUT_MARGIN_MS = 30_000; // headroom over a command's own timeout
  * ~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.
+ *
+ * ForkSession holds until its snapshot is READY and every child exists (and is
+ * RUNNING with wait); if the caller disconnects first the server terminates the
+ * children it could not deliver, so a short budget would destroy the fork.
+ *
+ * ResumeSession (since tenki-app #6486, sandbox-engine v2.35.0) holds until the
+ * session leaves RESUMING. The server's wait has no deadline of its own, and
+ * the restore it waits on runs detached for up to 6 minutes
+ * (resumeDispatchDetachedTimeout), so a 30s budget reports a slow but
+ * successful resume as failed.
  */
-const SLOW_METHOD = /^(CreateSnapshot|PauseSession)$/;
+const SLOW_METHOD = /^(CreateSnapshot|PauseSession|ForkSession|ResumeSession)$/;
+/**
+ * True when the call ended on THIS side — the client's deadline or an MCP-side
+ * cancel — so the server never answered and the operation may still complete.
+ * A server error never carries the marker, even when its message says "timed out".
+ */
+export function isClientAbort(e) {
+    return typeof e?.clientAbort === "string";
+}
 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 —
@@ -98,11 +118,11 @@ function shellQuote(value) {
 }
 /**
  * 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.
+ * `lx_`/`tk_` → Bearer, `ory_st_` → X-Session-Token, otherwise a `tenki_session` cookie.
  */
 function authHeaders(token) {
     const t = token.trim();
-    if (t.startsWith("tk_"))
+    if (isApiKey(t))
         return { Authorization: `Bearer ${t}` };
     if (t.startsWith("ory_st_"))
         return { "X-Session-Token": t };
@@ -150,8 +170,14 @@ export class TenkiClient {
      * the command's own timeout (plus margin) instead of the unary default.
      */
     timeoutFor(method, body) {
+        // With `async: true` these RPCs return once the work is accepted, so the
+        // long storage budget would only delay a genuinely hung call.
         if (SLOW_METHOD.test(method))
-            return this.slowTimeoutMs;
+            return body.async === true ? this.timeoutMs : this.slowTimeoutMs;
+        // CreateSession{waitReady} is held server-side for up to 60s (createWaitReadyMaxWait);
+        // a 30s client budget would abort a slow boot and orphan the (billing) sandbox.
+        if (method === "CreateSession" && body.waitReady === true)
+            return Math.max(this.timeoutMs, CREATE_WAIT_READY_TIMEOUT_MS);
         if (method !== "ExecuteCommand")
             return this.timeoutMs;
         const t = typeof body.timeout === "string" ? Number.parseInt(body.timeout, 10) : Number.NaN; // "30s"
@@ -163,17 +189,21 @@ export class TenkiClient {
      * 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) {
+    async fetchTextWithTimeout(url, init, timeoutMs, what, cancel) {
         const budget = Math.max(1, Math.floor(timeoutMs));
+        const timeout = AbortSignal.timeout(budget);
         try {
-            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(budget) });
+            const res = await fetch(url, { ...init, signal: cancel ? AbortSignal.any([timeout, cancel]) : timeout });
             const text = await res.text();
             return { ok: res.ok, status: res.status, headers: res.headers, text };
         }
         catch (e) {
             const name = e?.name;
+            if (cancel?.aborted && !timeout.aborted) {
+                throw Object.assign(new Error(`Tenki ${what} was cancelled by the MCP client before it returned.`), { clientAbort: "cancelled" });
+            }
             if (name === "TimeoutError" || name === "AbortError") {
-                throw new Error(`Tenki ${what} timed out after ${budget}ms with no response.`);
+                throw Object.assign(new Error(`Tenki ${what} timed out after ${budget}ms with no response.`), { clientAbort: "timeout" });
             }
             throw e;
         }
@@ -182,8 +212,15 @@ export class TenkiClient {
      * 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.
+     * For a method that cannot double-apply, a Connect `resource_exhausted` (the
+     * handler's own quota or limit check; edge rate limits arrive as an uncoded
+     * 429) or any rejection carrying error details (a fork's partial snapshot and
+     * children) means the handler ran, so it is never retried.
      */
-    shouldRetry(method, status, code) {
+    shouldRetry(method, status, code, hasDetails) {
+        const handlerRan = hasDetails || code === "resource_exhausted" || code === "resourceexhausted";
+        if (handlerRan && NON_IDEMPOTENT_METHOD.test(method))
+            return false;
         if (status === 429 || RATE_LIMIT_CODES.has(code))
             return true;
         const transient = code === "unavailable" || status === 502 || status === 503 || status === 504;
@@ -207,8 +244,11 @@ export class TenkiClient {
      * 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.
+     * `cancel` (the MCP request's abort signal) drops the HTTP request when the
+     * MCP client gives up, so the API sees the disconnect; a cancelled call is
+     * never retried.
      */
-    async control(method, body = {}, service = CONTROL_SERVICE) {
+    async control(method, body = {}, service = CONTROL_SERVICE, cancel) {
         const url = `${this.baseUrl}/${service}/${method}`;
         const deadline = Date.now() + this.timeoutFor(method, body ?? {});
         for (let attempt = 0;; attempt++) {
@@ -218,12 +258,12 @@ export class TenkiClient {
                     method: "POST",
                     headers: { "Content-Type": "application/json", "Connect-Protocol-Version": "1", ...this.controlAuthHeaders() },
                     body: JSON.stringify(body ?? {}),
-                }, deadline - Date.now(), method);
+                }, deadline - Date.now(), method, cancel);
             }
             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)) {
+                if (attempt < MAX_RETRIES && !cancel?.aborted && !NON_IDEMPOTENT_METHOD.test(method)) {
                     const wait = this.backoffMs(attempt, null);
                     if (Date.now() + wait < deadline) {
                         await sleep(wait);
@@ -236,7 +276,8 @@ export class TenkiClient {
                 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 details = Array.isArray(parsed?.details) ? parsed.details : [];
+            if (attempt < MAX_RETRIES && this.shouldRetry(method, res.status, code, details.length > 0)) {
                 const wait = this.backoffMs(attempt, res.headers.get("retry-after"));
                 if (Date.now() + wait < deadline) {
                     await sleep(wait);
@@ -244,7 +285,8 @@ export class TenkiClient {
                 }
             }
             const msg = parsed?.message || res.text || `HTTP ${res.status}`;
-            throw new Error(`Tenki ${method} failed (${res.status}${code ? ` ${code}` : ""}): ${msg}`);
+            // Connect error details (type, value, optional protojson `debug`) carry partial results, e.g. a failed fork's snapshot.
+            throw Object.assign(new Error(`Tenki ${method} failed (${res.status}${code ? ` ${code}` : ""}): ${msg}`), { code, details });
         }
     }
     /**
@@ -405,10 +447,14 @@ export class TenkiClient {
             await sleep(intervalMs);
         }
     }
-    async readTextFile(sessionId, path) {
+    /** A file's raw bytes. The data plane's ReadFile has no range support, so this is always the whole file. */
+    async readFileBytes(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") : "";
+        return content ? Buffer.from(content, "base64") : Buffer.alloc(0);
+    }
+    async readTextFile(sessionId, path) {
+        return (await this.readFileBytes(sessionId, path)).toString("utf8");
     }
     async writeTextFile(sessionId, path, text) {
         const content = Buffer.from(text, "utf8").toString("base64");

package/dist/env.d.ts

@@ -0,0 +1,6 @@
+/** Every `LUXORAI_<suffix>` is tried (in order) before any legacy `TENKI_<suffix>`. Empty or blank values fall through. */
+export declare function readEnv(...suffixes: string[]): string | undefined;
+/** The env var name {@link readEnv} resolved, for diagnostics. */
+export declare function resolvedEnvName(env: NodeJS.ProcessEnv, ...suffixes: string[]): string | undefined;
+/** API keys carry `lx_` (Luxor AI) or the legacy `tk_` prefix. */
+export declare function isApiKey(token: string): boolean;

package/dist/env.js

@@ -0,0 +1,25 @@
+/** Every `LUXORAI_<suffix>` is tried (in order) before any legacy `TENKI_<suffix>`. Empty or blank values fall through. */
+export function readEnv(...suffixes) {
+    for (const prefix of ["LUXORAI_", "TENKI_"]) {
+        for (const suffix of suffixes) {
+            const value = process.env[`${prefix}${suffix}`];
+            if (value?.trim())
+                return value;
+        }
+    }
+    return undefined;
+}
+/** The env var name {@link readEnv} resolved, for diagnostics. */
+export function resolvedEnvName(env, ...suffixes) {
+    for (const prefix of ["LUXORAI_", "TENKI_"]) {
+        for (const suffix of suffixes) {
+            if (env[`${prefix}${suffix}`]?.trim())
+                return `${prefix}${suffix}`;
+        }
+    }
+    return undefined;
+}
+/** API keys carry `lx_` (Luxor AI) or the legacy `tk_` prefix. */
+export function isApiKey(token) {
+    return token.startsWith("lx_") || token.startsWith("tk_");
+}

package/dist/http.js

@@ -17,8 +17,9 @@ import { randomUUID, timingSafeEqual } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { TenkiClient } from "./client.js";
-import { OAuthResourceRoutes, OAuthTokenVerifier, authorizationBinding, bearerToken, loadOAuthConfig, } from "./oauth.js";
+import { OAuthResourceRoutes, OAuthTokenVerifier, authorizationBinding, bearerToken, loadOAuthConfig, metadataUrlForHost, } from "./oauth.js";
 import { createServer } from "./server.js";
+import { readEnv } from "./env.js";
 const MAX_BODY_BYTES = 1 << 20; // 1 MiB — reject larger POST bodies (memory-DoS guard)
 const MAX_SESSIONS = 256; // cap concurrent sessions (init-flood DoS guard)
 const SESSION_IDLE_MS = 30 * 60 * 1000; // reap sessions idle longer than this
@@ -109,16 +110,18 @@ function authOk(header, expected) {
  * an ephemeral `port: 0` bind still accepts its own address). Anything else —
  * e.g. a rebound attacker domain — is rejected by the transport.
  */
-function allowedHostsFor(server, host, port, publicUrl) {
+function allowedHostsFor(server, host, port, publicUrls = []) {
     const addr = server.address();
     const bound = addr && typeof addr === "object" ? addr.port : port;
     const ports = Array.from(new Set([port, bound]));
     const hosts = Array.from(new Set([host, "127.0.0.1", "localhost", "[::1]", "::1"]));
-    const configured = (process.env.TENKI_MCP_ALLOWED_HOSTS || "")
+    const configured = (readEnv("MCP_ALLOWED_HOSTS") || "")
         .split(",")
         .map((value) => value.trim())
         .filter(Boolean);
-    if (publicUrl) {
+    for (const publicUrl of publicUrls) {
+        if (!URL.canParse(publicUrl))
+            continue;
         const url = new URL(publicUrl);
         configured.push(url.host, url.hostname);
     }
@@ -134,8 +137,8 @@ function oauthUnauthorized(res, metadataUrl, scope) {
         .end(JSON.stringify({ error: "unauthorized" }));
 }
 export function startHttp(client, port) {
-    const host = process.env.TENKI_MCP_HTTP_HOST || "127.0.0.1";
-    const httpToken = process.env.TENKI_MCP_HTTP_TOKEN || "";
+    const host = readEnv("MCP_HTTP_HOST") || "127.0.0.1";
+    const httpToken = readEnv("MCP_HTTP_TOKEN") || "";
     const isLoopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
     const oauthConfig = loadOAuthConfig();
     const oauthVerifier = oauthConfig ? new OAuthTokenVerifier(oauthConfig) : null;
@@ -176,7 +179,7 @@ export function startHttp(client, port) {
                 const token = bearerToken(req.headers["authorization"]);
                 delegated = token ? await oauthVerifier.verify(token) : null;
                 if (!delegated) {
-                    oauthUnauthorized(res, oauthConfig.metadataUrl, oauthConfig.scope);
+                    oauthUnauthorized(res, metadataUrlForHost(oauthConfig, req.headers.host), oauthConfig.scope);
                     return;
                 }
             }
@@ -189,7 +192,7 @@ export function startHttp(client, port) {
             if (existingEntry?.authorization &&
                 delegated &&
                 existingEntry.authorization.binding !== authorizationBinding(delegated)) {
-                oauthUnauthorized(res, oauthConfig.metadataUrl, oauthConfig.scope);
+                oauthUnauthorized(res, metadataUrlForHost(oauthConfig, req.headers.host), oauthConfig.scope);
                 return;
             }
             if (existingEntry?.authorization && delegated) {
@@ -229,7 +232,7 @@ export function startHttp(client, port) {
                         // DNS-rebinding defense: only accept these Host headers, so a rebound
                         // attacker-domain request from a browser is rejected.
                         enableDnsRebindingProtection: true,
-                        allowedHosts: allowedHostsFor(httpServer, host, port, oauthConfig?.publicUrl),
+                        allowedHosts: allowedHostsFor(httpServer, host, port, oauthConfig ? [oauthConfig.publicUrl, ...oauthConfig.resources] : []),
                         onsessioninitialized: (id) => {
                             sessions.set(id, {
                                 transport,
@@ -244,7 +247,7 @@ export function startHttp(client, port) {
                             sessions.delete(id);
                     };
                     const sessionClient = delegated
-                        ? new TenkiClient("", process.env.TENKI_API_ENDPOINT || process.env.TENKI_API_URL || undefined, {
+                        ? new TenkiClient("", readEnv("API_ENDPOINT", "API_URL") || undefined, {
                             workspaceId: delegated.workspaceId,
                             bearerTokenProvider: () => sessionAuthorization.apiDelegationToken,
                         })

package/dist/index.js

@@ -17,32 +17,33 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { TenkiClient } from "./client.js";
 import { createServer } from "./server.js";
 import { startHttp } from "./http.js";
+import { readEnv } from "./env.js";
 // A missing credential is NOT fatal: exiting here is reported by MCP clients as
 // an opaque "server failed to start" with stderr usually swallowed, leaving the
 // user with no idea a token is needed. Instead the server boots with only
 // tenki_auth_status registered (see createServer), so an agent can ask what is
 // wrong and relay the fix.
-const token = process.env.TENKI_AUTH_TOKEN || process.env.TENKI_API_KEY;
-const oauthHttp = Boolean(process.env.TENKI_MCP_OAUTH_ISSUER);
+const token = readEnv("AUTH_TOKEN", "API_KEY");
+const oauthHttp = Boolean(readEnv("MCP_OAUTH_ISSUER"));
 if (!token && !oauthHttp) {
     console.error("tenki-mcp: no credential — starting in unauthenticated mode (only tenki_auth_status is available). " +
         "Set TENKI_API_KEY (tk_…) or TENKI_AUTH_TOKEN (ory_st_…) in the server's env and restart, " +
         "e.g. claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y @tenkicloud/mcp");
 }
-const baseUrl = process.env.TENKI_API_ENDPOINT || process.env.TENKI_API_URL || undefined;
+const baseUrl = readEnv("API_ENDPOINT", "API_URL") || undefined;
 /** Positive integer from env, or undefined so the client keeps its own default. */
-const envMs = (name) => {
-    const n = Number.parseInt(process.env[name] ?? "", 10);
+const envMs = (suffix) => {
+    const n = Number.parseInt(readEnv(suffix) ?? "", 10);
     return Number.isFinite(n) && n > 0 ? n : undefined;
 };
 const client = token
     ? new TenkiClient(token, baseUrl, {
-        timeoutMs: envMs("TENKI_MCP_TIMEOUT_MS"),
-        slowTimeoutMs: envMs("TENKI_MCP_SLOW_TIMEOUT_MS"),
+        timeoutMs: envMs("MCP_TIMEOUT_MS"),
+        slowTimeoutMs: envMs("MCP_SLOW_TIMEOUT_MS"),
     })
     : null;
 async function main() {
-    if ((process.env.TENKI_MCP_TRANSPORT || "stdio").toLowerCase() === "http") {
+    if ((readEnv("MCP_TRANSPORT") || "stdio").toLowerCase() === "http") {
         const httpServer = startHttp(client, Number(process.env.PORT) || 3000);
         for (const sig of ["SIGINT", "SIGTERM"]) {
             process.on(sig, () => httpServer.close(() => process.exit(0)));

package/dist/oauth.d.ts

@@ -2,6 +2,8 @@ import type http from "node:http";
 export interface OAuthConfig {
     issuer: string;
     resource: string;
+    /** Every accepted resource URI (first is `resource`), e.g. one per served domain. */
+    resources: string[];
     publicUrl: string;
     metadataUrl: string;
     identityUrl: string;
@@ -27,7 +29,11 @@ export declare class OAuthTokenVerifier {
 export declare class OAuthResourceRoutes {
     private readonly config;
     constructor(config: OAuthConfig);
-    handle(_req: http.IncomingMessage, res: http.ServerResponse, url: URL): Promise<boolean>;
+    handle(req: http.IncomingMessage, res: http.ServerResponse, url: URL): Promise<boolean>;
 }
+/** The configured resource whose host matches the request (RFC 9728 requires an exact match), else the first. */
+export declare function resourceForHost(config: Pick<OAuthConfig, "resource" | "resources">, host: string | undefined): string;
+/** Protected-resource metadata URL to advertise in a challenge, on the same host as the matched resource. */
+export declare function metadataUrlForHost(config: Pick<OAuthConfig, "resources" | "publicUrl" | "metadataUrl">, host: string | undefined): string;
 export declare function bearerToken(header: string | undefined): string | null;
 export declare function authorizationBinding(authorization: DelegatedAuthorization): string;

package/dist/oauth.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { readEnv } from "./env.js";
 const DEFAULT_SCOPE = "mcp";
 const FETCH_TIMEOUT_MS = 8_000;
 const TOKEN_CACHE_MS = 15_000;
@@ -7,24 +8,26 @@ function trimUrl(value) {
     return value.trim().replace(/\/+$/, "");
 }
 export function loadOAuthConfig() {
-    const issuer = trimUrl(process.env.TENKI_MCP_OAUTH_ISSUER || "");
-    const identityUrl = trimUrl(process.env.TENKI_MCP_IDENTITY_URL || "");
-    const identityServiceToken = (process.env.TENKI_MCP_IDENTITY_SERVICE_TOKEN || "").trim();
-    const publicUrl = trimUrl(process.env.TENKI_MCP_PUBLIC_URL || "");
+    const issuer = trimUrl(readEnv("MCP_OAUTH_ISSUER") || "");
+    const identityUrl = trimUrl(readEnv("MCP_IDENTITY_URL") || "");
+    const identityServiceToken = (readEnv("MCP_IDENTITY_SERVICE_TOKEN") || "").trim();
+    const publicUrl = trimUrl(readEnv("MCP_PUBLIC_URL") || "");
     if (!issuer && !identityUrl && !identityServiceToken && !publicUrl)
         return null;
     if (!issuer || !identityUrl || !identityServiceToken || !publicUrl) {
         throw new Error("TENKI_MCP_OAUTH_ISSUER, TENKI_MCP_IDENTITY_URL, TENKI_MCP_IDENTITY_SERVICE_TOKEN, and TENKI_MCP_PUBLIC_URL must be set together.");
     }
-    const resource = trimUrl(process.env.TENKI_MCP_OAUTH_RESOURCE || `${publicUrl}/mcp`);
+    const configured = (readEnv("MCP_OAUTH_RESOURCE") || "").split(",").map(trimUrl).filter(Boolean);
+    const resources = configured.length ? Array.from(new Set(configured)) : [`${publicUrl}/mcp`];
     return {
         issuer,
-        resource,
+        resource: resources[0],
+        resources,
         publicUrl,
         metadataUrl: `${publicUrl}/.well-known/oauth-protected-resource/mcp`,
         identityUrl,
         identityServiceToken,
-        scope: (process.env.TENKI_MCP_OAUTH_SCOPE || DEFAULT_SCOPE).trim(),
+        scope: (readEnv("MCP_OAUTH_SCOPE") || DEFAULT_SCOPE).trim(),
     };
 }
 function tokenDigest(token) {
@@ -117,10 +120,10 @@ export class OAuthResourceRoutes {
     constructor(config) {
         this.config = config;
     }
-    async handle(_req, res, url) {
+    async handle(req, res, url) {
         if (url.pathname === "/.well-known/oauth-protected-resource/mcp" || url.pathname === "/.well-known/oauth-protected-resource") {
             json(res, 200, {
-                resource: this.config.resource,
+                resource: resourceForHost(this.config, req.headers.host),
                 authorization_servers: [this.config.issuer],
                 scopes_supported: [this.config.scope, "offline_access"],
                 bearer_methods_supported: ["header"],
@@ -135,6 +138,23 @@ export class OAuthResourceRoutes {
         return false;
     }
 }
+/** The configured resource whose host matches the request (RFC 9728 requires an exact match), else the first. */
+export function resourceForHost(config, host) {
+    const wanted = (host ?? "").toLowerCase();
+    return config.resources.find((resource) => urlHost(resource) === wanted) ?? config.resource;
+}
+/** Protected-resource metadata URL to advertise in a challenge, on the same host as the matched resource. */
+export function metadataUrlForHost(config, host) {
+    const wanted = (host ?? "").toLowerCase();
+    const matched = config.resources.find((resource) => urlHost(resource) === wanted);
+    if (!matched || wanted === urlHost(config.publicUrl))
+        return config.metadataUrl;
+    return `${new URL(matched).origin}/.well-known/oauth-protected-resource/mcp`;
+}
+/** Lowercased host of a URL, or undefined when it does not parse (a resource may be any absolute URI). */
+function urlHost(value) {
+    return URL.canParse(value) ? new URL(value).host.toLowerCase() : undefined;
+}
 export function bearerToken(header) {
     const match = /^Bearer (.+)$/.exec(header ?? "");
     return match?.[1]?.trim() || null;