@tenkicloud/mcp 0.3.2-canary.1 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +42 -1
- package/README.md +88 -79
- package/SECURITY.md +2 -2
- package/dist/client.d.ts +16 -1
- package/dist/client.js +62 -16
- package/dist/env.d.ts +6 -0
- package/dist/env.js +25 -0
- package/dist/http.js +13 -10
- package/dist/index.js +9 -8
- package/dist/oauth.d.ts +7 -1
- package/dist/oauth.js +29 -9
- package/dist/server.d.ts +25 -5
- package/dist/server.js +88 -53
- package/dist/tools/artifacts.d.ts +3 -3
- package/dist/tools/artifacts.js +6 -6
- package/dist/tools/auth_status.d.ts +3 -3
- package/dist/tools/auth_status.js +8 -9
- package/dist/tools/common.d.ts +35 -0
- package/dist/tools/common.js +78 -0
- package/dist/tools/egress.d.ts +38 -0
- package/dist/tools/egress.js +153 -0
- package/dist/tools/exec.js +1 -1
- package/dist/tools/files.js +36 -3
- package/dist/tools/files_ops.js +9 -1
- package/dist/tools/git.d.ts +0 -1
- package/dist/tools/git.js +85 -23
- package/dist/tools/ports.d.ts +8 -1
- package/dist/tools/ports.js +24 -3
- package/dist/tools/previews.js +59 -22
- package/dist/tools/sandboxes.d.ts +1 -1
- package/dist/tools/sandboxes.js +342 -26
- package/dist/tools/sessions_admin.js +63 -23
- package/dist/tools/snapshots.js +41 -22
- package/dist/tools/ssh.d.ts +3 -3
- package/dist/tools/ssh.js +35 -9
- package/dist/tools/templates.d.ts +2 -1
- package/dist/tools/templates.js +36 -16
- package/dist/tools/titles.d.ts +8 -0
- package/dist/tools/titles.js +102 -0
- package/dist/tools/volumes.js +36 -11
- package/dist/tools/workspace.d.ts +9 -1
- package/dist/tools/workspace.js +29 -90
- package/package.json +12 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,47 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
All notable changes to `@tenkicloud/mcp
|
|
3
|
+
All notable changes to `@luxorai/mcp` (also published as `@tenkicloud/mcp`). This project follows semantic versioning.
|
|
4
|
+
|
|
5
|
+
## [0.4.1] - 2026-11-12
|
|
6
|
+
|
|
7
|
+
- Package page now shows Luxor names, install commands and links.
|
|
8
|
+
|
|
9
|
+
## [0.4.0] - 2026-11-10
|
|
10
|
+
|
|
11
|
+
- Read `LUXORAI_*` environment variables before their `TENKI_*` equivalents (credentials, endpoint, and every `TENKI_MCP_*` option). `TENKI_*` keeps working.
|
|
12
|
+
- Accept `lx_` API keys alongside `tk_`.
|
|
13
|
+
- `TENKI_MCP_OAUTH_RESOURCE` accepts a comma-separated list; protected-resource metadata returns the entry matching the request host.
|
|
14
|
+
- 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`).
|
|
15
|
+
- 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`.
|
|
16
|
+
- 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).
|
|
17
|
+
- Fix `tenki_attach_volume` `read_only`, which the API silently ignored (wrong wire field name); the mount was always read-write.
|
|
18
|
+
- 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.
|
|
19
|
+
- Fix `tenki_list_ssh_gateways`: `workspace_id` did nothing; the tool now takes `region` and/or `session_id`.
|
|
20
|
+
- `tenki_get_download_url` no longer requires `session_id` (the API ignores it).
|
|
21
|
+
- `tenki_list_preview_urls` filters by `session_id` on the server instead of on the fetched page.
|
|
22
|
+
- `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.
|
|
23
|
+
- 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.
|
|
24
|
+
- 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.
|
|
25
|
+
- `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.
|
|
26
|
+
- 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.
|
|
27
|
+
- `tenki_issue_ssh_cert` documents the new `pinHostKey` flag (verify the gateway host certificate against `caPub`).
|
|
28
|
+
- 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).
|
|
29
|
+
- 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).
|
|
30
|
+
- 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.
|
|
31
|
+
- `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).
|
|
32
|
+
- 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).
|
|
33
|
+
- `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).
|
|
34
|
+
- 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.
|
|
35
|
+
- 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.
|
|
36
|
+
- `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.
|
|
37
|
+
- 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`.
|
|
38
|
+
- `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.
|
|
39
|
+
- **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`.
|
|
40
|
+
- Every tool now has a human-readable `title` (MCP `Tool.title` and `annotations.title`).
|
|
41
|
+
- `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.
|
|
42
|
+
- `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.
|
|
43
|
+
- `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.
|
|
44
|
+
- Every tool parameter now has a description.
|
|
4
45
|
|
|
5
46
|
## [0.2.0] — 2026-08-21
|
|
6
47
|
|
package/README.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Luxor MCP: `@luxorai/mcp`
|
|
2
2
|
|
|
3
|
-
**A [Model Context Protocol](https://modelcontextprotocol.io) server for [
|
|
3
|
+
**A [Model Context Protocol](https://modelcontextprotocol.io) server for [Luxor Sandbox](https://luxor.ai), part of Luxor Agent Cloud by Luxor AI.** Give any agent (Claude, Codex, Cursor) a disposable microVM it can create, run code in, read and write files, run git, and expose to the web. Sandboxes boot in ~2 seconds and are billed per second.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The agent writes code and Luxor runs it in isolation. (**Luxor Code Review** and Luxor's managed CI runners are separate products; this server currently exposes the Sandbox.)
|
|
6
|
+
|
|
7
|
+
The old `@tenkicloud/mcp` name keeps working and publishes the same code.
|
|
6
8
|
|
|
7
9
|
```
|
|
8
10
|
"Run this Python in a fresh sandbox and tell me what it prints."
|
|
@@ -14,19 +16,19 @@ Part of making Tenki the execution layer coding agents reach for: the agent writ
|
|
|
14
16
|
## Quickstart
|
|
15
17
|
|
|
16
18
|
```bash
|
|
17
|
-
export
|
|
18
|
-
npx -y @
|
|
19
|
+
export LUXORAI_API_KEY=lx_your_key_here
|
|
20
|
+
npx -y @luxorai/mcp # speaks MCP over stdio
|
|
19
21
|
```
|
|
20
22
|
|
|
21
|
-
Nothing to clone or build. The package installs
|
|
23
|
+
Nothing to clone or build. The package installs the command `luxor-mcp` (and `tenki-mcp`, the same program).
|
|
22
24
|
|
|
23
25
|
### Use it in Claude Code
|
|
24
26
|
|
|
25
|
-
Connect to
|
|
27
|
+
Connect to Luxor's hosted MCP service and sign in with your Luxor account:
|
|
26
28
|
|
|
27
29
|
```bash
|
|
28
|
-
claude mcp add --transport http
|
|
29
|
-
claude mcp login
|
|
30
|
+
claude mcp add --transport http luxor https://mcp.luxor.ai/mcp
|
|
31
|
+
claude mcp login luxor
|
|
30
32
|
```
|
|
31
33
|
|
|
32
34
|
Claude Code's `mcp add` command stores the server configuration; `mcp login` performs the one-time browser authorization and workspace selection.
|
|
@@ -34,18 +36,20 @@ Claude Code's `mcp add` command stores the server configuration; `mcp login` per
|
|
|
34
36
|
Alternatively, run the MCP server locally with an API key:
|
|
35
37
|
|
|
36
38
|
```bash
|
|
37
|
-
claude mcp add
|
|
39
|
+
claude mcp add luxor --env LUXORAI_API_KEY=lx_your_key_here -- npx -y @luxorai/mcp
|
|
38
40
|
```
|
|
39
41
|
|
|
40
42
|
### Or install it as a Claude Code plugin
|
|
41
43
|
|
|
42
|
-
The repo doubles as a plugin marketplace. This prompts for your API key on install and stores it in your OS keychain
|
|
44
|
+
The repo doubles as a plugin marketplace. This prompts for your API key on install and stores it in your OS keychain, so there is no env var to manage:
|
|
43
45
|
|
|
44
46
|
```
|
|
45
47
|
/plugin marketplace add LuxorLabs/tenki-mcp
|
|
46
|
-
/plugin install
|
|
48
|
+
/plugin install luxor@tenki
|
|
47
49
|
```
|
|
48
50
|
|
|
51
|
+
The `tenki@tenki` plugin is still available.
|
|
52
|
+
|
|
49
53
|
### Use it in Claude Desktop
|
|
50
54
|
|
|
51
55
|
Add to `claude_desktop_config.json`:
|
|
@@ -53,10 +57,10 @@ Add to `claude_desktop_config.json`:
|
|
|
53
57
|
```json
|
|
54
58
|
{
|
|
55
59
|
"mcpServers": {
|
|
56
|
-
"
|
|
60
|
+
"luxor": {
|
|
57
61
|
"command": "npx",
|
|
58
|
-
"args": ["-y", "@
|
|
59
|
-
"env": { "
|
|
62
|
+
"args": ["-y", "@luxorai/mcp"],
|
|
63
|
+
"env": { "LUXORAI_API_KEY": "lx_your_key_here" }
|
|
60
64
|
}
|
|
61
65
|
}
|
|
62
66
|
}
|
|
@@ -69,10 +73,10 @@ Add the same block to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (glob
|
|
|
69
73
|
```json
|
|
70
74
|
{
|
|
71
75
|
"mcpServers": {
|
|
72
|
-
"
|
|
76
|
+
"luxor": {
|
|
73
77
|
"command": "npx",
|
|
74
|
-
"args": ["-y", "@
|
|
75
|
-
"env": { "
|
|
78
|
+
"args": ["-y", "@luxorai/mcp"],
|
|
79
|
+
"env": { "LUXORAI_API_KEY": "lx_your_key_here" }
|
|
76
80
|
}
|
|
77
81
|
}
|
|
78
82
|
}
|
|
@@ -83,22 +87,22 @@ Add the same block to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (glob
|
|
|
83
87
|
The OpenAI Codex CLI reads MCP servers from `~/.codex/config.toml`. Add:
|
|
84
88
|
|
|
85
89
|
```toml
|
|
86
|
-
[mcp_servers.
|
|
90
|
+
[mcp_servers.luxor]
|
|
87
91
|
command = "npx"
|
|
88
|
-
args = ["-y", "@
|
|
89
|
-
env = {
|
|
92
|
+
args = ["-y", "@luxorai/mcp"]
|
|
93
|
+
env = { LUXORAI_API_KEY = "lx_your_key_here" }
|
|
90
94
|
```
|
|
91
95
|
|
|
92
96
|
### Confirm it's working
|
|
93
97
|
|
|
94
98
|
After adding the server, **start a fresh session** so the client loads it, then ask your agent one of:
|
|
95
99
|
|
|
96
|
-
-
|
|
97
|
-
-
|
|
100
|
+
- _"Check tenki auth status."_: confirms your credential was picked up.
|
|
101
|
+
- _"Run `print(2+2)` in a fresh Luxor sandbox."_: a full boot → run → teardown round-trip.
|
|
98
102
|
|
|
99
103
|
If the `tenki_*` tools don't show up, restart the client so it re-reads its config.
|
|
100
104
|
|
|
101
|
-
No key yet? Start the server without one and ask the agent to check `tenki_auth_status
|
|
105
|
+
No key yet? Start the server without one and ask the agent to check `tenki_auth_status`; it reports what to set and where. See [Auth](#auth).
|
|
102
106
|
|
|
103
107
|
### Run it from a clone instead
|
|
104
108
|
|
|
@@ -107,90 +111,95 @@ For development, or to run an unreleased change:
|
|
|
107
111
|
```bash
|
|
108
112
|
git clone https://github.com/LuxorLabs/tenki-mcp.git && cd tenki-mcp
|
|
109
113
|
npm install && npm run build
|
|
110
|
-
|
|
114
|
+
LUXORAI_API_KEY=lx_your_key_here node dist/index.js
|
|
111
115
|
```
|
|
112
116
|
|
|
113
117
|
Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` command in any of the configs above. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development loop.
|
|
114
118
|
|
|
115
119
|
### Environment variables
|
|
116
120
|
|
|
117
|
-
| Variable
|
|
118
|
-
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `PORT`
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
121
|
+
| Variable | Default | Purpose |
|
|
122
|
+
| ------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| `LUXORAI_API_KEY` | - | API key (`lx_…`, or `tk_…`). One of this or `LUXORAI_AUTH_TOKEN` is required. |
|
|
124
|
+
| `LUXORAI_AUTH_TOKEN` | - | Session token (`ory_st_…` or cookie value). **Takes precedence over `LUXORAI_API_KEY`** when both are set. |
|
|
125
|
+
| `LUXORAI_API_ENDPOINT` | `https://api.tenki.cloud` (the same API as `https://api.luxor.ai`) | Control-plane base URL (`LUXORAI_API_URL` is an alias). |
|
|
126
|
+
| `LUXORAI_MCP_READONLY` | off | `1` registers only read tools (no create/run/delete/spend). |
|
|
127
|
+
| `LUXORAI_MCP_DISABLED_TOOLS` | - | Comma-separated tool names to skip registering. |
|
|
128
|
+
| `LUXORAI_MCP_AUDIT` | off | `1` logs each tool call name + arg keys to stderr. |
|
|
129
|
+
| `LUXORAI_MCP_TRANSPORT` | `stdio` | `http` serves Streamable HTTP instead (see below). |
|
|
130
|
+
| `PORT` | `3000` | HTTP transport port. |
|
|
131
|
+
| `LUXORAI_MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind host; non-loopback requires `LUXORAI_MCP_HTTP_TOKEN`. |
|
|
132
|
+
| `LUXORAI_MCP_HTTP_TOKEN` | - | Bearer token for the HTTP endpoint; optional on loopback, required on a non-loopback host. |
|
|
133
|
+
| `LUXORAI_MCP_PUBLIC_URL` | - | Public base URL for an OAuth-protected hosted server. |
|
|
134
|
+
| `LUXORAI_MCP_OAUTH_ISSUER` | - | OAuth authorization-server issuer. Enables delegated OAuth HTTP mode. |
|
|
135
|
+
| `LUXORAI_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. |
|
|
136
|
+
| `LUXORAI_MCP_OAUTH_SCOPE` | `mcp` | Required delegated scope. |
|
|
137
|
+
| `LUXORAI_MCP_IDENTITY_URL` | - | Internal Luxor Identity service endpoint used to exchange OAuth access tokens. |
|
|
138
|
+
| `LUXORAI_MCP_IDENTITY_SERVICE_TOKEN` | - | Service credential for the private Identity token-exchange RPC. |
|
|
139
|
+
|
|
140
|
+
Every `LUXORAI_*` variable above is still accepted under its `TENKI_*` name (for example `TENKI_API_KEY`, `TENKI_MCP_TRANSPORT`). All `LUXORAI_*` credentials are read before any `TENKI_*` one. Keys start with `lx_`; `tk_…` keys are still accepted.
|
|
135
141
|
|
|
136
142
|
## Tools
|
|
137
143
|
|
|
138
|
-
**
|
|
139
|
-
|
|
140
|
-
| Domain
|
|
141
|
-
|
|
142
|
-
| **Auth**
|
|
143
|
-
| **Identity**
|
|
144
|
-
| **Run**
|
|
145
|
-
| **Sandboxes**
|
|
146
|
-
| **Session admin**
|
|
147
|
-
| **Exec**
|
|
148
|
-
| **Files**
|
|
149
|
-
| **Git**
|
|
150
|
-
| **Ports & previews**
|
|
151
|
-
| **Artifacts** (binary transfer) | `tenki_get_upload_url` · `tenki_get_download_url` (signed URLs for binary PUT/GET)
|
|
152
|
-
| **SSH**
|
|
153
|
-
| **Snapshots**
|
|
154
|
-
| **Volumes**
|
|
155
|
-
| **
|
|
156
|
-
| **
|
|
144
|
+
**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`. Tool names keep the `tenki_` prefix. A few admin surfaces (published images, saved Tailscale connections) and implementation-only control-plane methods are intentionally excluded. Grouped by domain:
|
|
145
|
+
|
|
146
|
+
| Domain | Tools |
|
|
147
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
148
|
+
| **Auth** | `tenki_auth_status` (which credential is configured, and does it work; the only tool available when none is) |
|
|
149
|
+
| **Identity** | `tenki_whoami` |
|
|
150
|
+
| **Run** | `tenki_run_code` (one-shot: boot → run shell/python/js → tear down) |
|
|
151
|
+
| **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) |
|
|
152
|
+
| **Session admin** | `tenki_extend_sandbox` · `tenki_update_sandbox` · `tenki_terminate_sandboxes` (bulk) · `tenki_report_sandbox_activity` · `tenki_list_workspace_sandboxes` |
|
|
153
|
+
| **Exec** | `tenki_exec` (stdout/stderr/exit inline) |
|
|
154
|
+
| **Files** | `tenki_read_file` · `tenki_write_file` · `tenki_list_files` · `tenki_stat_path` · `tenki_make_dir` · `tenki_remove_path` · `tenki_move_path` |
|
|
155
|
+
| **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`) |
|
|
156
|
+
| **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 |
|
|
157
|
+
| **Artifacts** (binary transfer) | `tenki_get_upload_url` · `tenki_get_download_url` (signed URLs for binary PUT/GET) |
|
|
158
|
+
| **SSH** | `tenki_update_ssh_keys` · `tenki_issue_ssh_cert` · `tenki_list_ssh_gateways` |
|
|
159
|
+
| **Snapshots** | create · get · list · list-session · list-workspace · list-dangling · update · delete · get-download-url |
|
|
160
|
+
| **Volumes** | create · get · list · update · delete · resize · attach · detach |
|
|
161
|
+
| **Egress policies** | create · get · list · update · delete (named workspace allowlists that `tenki_create_sandbox` pins via `egress_policies`) |
|
|
162
|
+
| **Templates** | create · get · list · update · delete · build · cancel-build · get-build · list-active-builds · list-builds · delete-build |
|
|
163
|
+
| **Workspace** | `tenki_get_workspace_usage` · `tenki_list_ci_runner_sizes` · `tenki_get_workspace_preview_domains` · `tenki_update_workspace_preview_domains` |
|
|
157
164
|
|
|
158
165
|
Full per-release breakdown in [CHANGELOG.md](CHANGELOG.md).
|
|
159
166
|
|
|
167
|
+
**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.
|
|
168
|
+
|
|
160
169
|
## Auth
|
|
161
170
|
|
|
162
|
-
Set one of `
|
|
171
|
+
Set one of `LUXORAI_API_KEY` or `LUXORAI_AUTH_TOKEN` (`TENKI_API_KEY` / `TENKI_AUTH_TOKEN` are still accepted). When both are set, the auth token wins. The header is chosen by token prefix: `lx_…` or `tk_…` → `Authorization: Bearer`, `ory_st_…` → `X-Session-Token`, otherwise a session cookie. Override the endpoint with `LUXORAI_API_ENDPOINT` (default `https://api.tenki.cloud`, the same API as `https://api.luxor.ai`).
|
|
163
172
|
|
|
164
|
-
**Without a credential the server still starts**, registering only `tenki_auth_status
|
|
173
|
+
**Without a credential the server still starts**, registering only `tenki_auth_status`, so instead of an MCP client reporting an opaque "server failed to start", the agent can call that tool and get told what to set. Ask it "check tenki auth status" any time other tools return auth errors: it reports the credential kind (API key vs session token), the endpoint, and whether a live identity probe succeeded, never the token itself. It reports status only; get a credential from the Luxor dashboard.
|
|
165
174
|
|
|
166
175
|
## Host it over HTTP (v2.0-beta)
|
|
167
176
|
|
|
168
177
|
Besides stdio, the server speaks **Streamable HTTP** so it can be hosted for remote MCP clients:
|
|
169
178
|
|
|
170
179
|
```bash
|
|
171
|
-
|
|
180
|
+
LUXORAI_MCP_TRANSPORT=http PORT=3000 LUXORAI_API_KEY=… npx -y @luxorai/mcp
|
|
172
181
|
# → tenki-mcp running on http://127.0.0.1:3000/mcp (Streamable HTTP) [loopback only, no auth]
|
|
173
182
|
```
|
|
174
183
|
|
|
175
|
-
For a single-user deployment, HTTP mode can hold one shared `
|
|
184
|
+
For a single-user deployment, HTTP mode can hold one shared `LUXORAI_API_KEY` and therefore exposes a powerful capability. By default it:
|
|
176
185
|
|
|
177
|
-
- **binds to loopback (`127.0.0.1`) only
|
|
178
|
-
- it **requires a bearer token**: set `
|
|
186
|
+
- **binds to loopback (`127.0.0.1`) only**: set `LUXORAI_MCP_HTTP_HOST=0.0.0.0` to expose it, but then
|
|
187
|
+
- it **requires a bearer token**: set `LUXORAI_MCP_HTTP_TOKEN` and send `Authorization: Bearer <token>`. It **refuses to start** on a non-loopback host without one.
|
|
179
188
|
- **DNS-rebinding protection** is on (Host-header allowlist), so a malicious web page can't drive your local server.
|
|
180
189
|
|
|
181
190
|
```bash
|
|
182
191
|
# expose to a network safely:
|
|
183
|
-
|
|
184
|
-
|
|
192
|
+
LUXORAI_MCP_TRANSPORT=http LUXORAI_MCP_HTTP_HOST=0.0.0.0 PORT=3000 \
|
|
193
|
+
LUXORAI_MCP_HTTP_TOKEN=$(openssl rand -hex 32) LUXORAI_API_KEY=… npx -y @luxorai/mcp
|
|
185
194
|
```
|
|
186
195
|
|
|
187
|
-
Point an HTTP-capable MCP client at `/mcp`. Static-key mode uses one shared `
|
|
196
|
+
Point an HTTP-capable MCP client at `/mcp`. Static-key mode uses one shared `LUXORAI_API_KEY` for all sessions. Verified end-to-end (`test/http-transport.test.mjs`: auth gate, DNS-rebinding rejection, connect → tools/list → tool call over HTTP).
|
|
188
197
|
|
|
189
|
-
Hosted multi-tenant deployments instead use
|
|
198
|
+
Hosted multi-tenant deployments instead use Luxor Identity's OAuth facade. The MCP server publishes RFC 9728 protected-resource metadata and exchanges each caller's access token through the private Identity service. Identity owns Hydra, validates the requested audience and scope, and issues a short-lived API delegation bound to the user, client, and workspace selected on the Luxor consent page. `tenki-mcp` has no Hydra Admin access and does not hold the delegation-signing secret.
|
|
190
199
|
|
|
191
200
|
## How it works
|
|
192
201
|
|
|
193
|
-
|
|
202
|
+
Luxor's API is **ConnectRPC**: JSON over HTTP/1.1, not REST. Every control-plane call is `POST https://api.luxor.ai/tenki.sandbox.v1.SandboxService/{Method}` with a lowerCamelCase JSON body. Per-session file I/O runs on a **separate data-plane endpoint** returned at create time, authenticated with a short-lived session certificate. This server owns both transports so the tools stay one-liners.
|
|
194
203
|
|
|
195
204
|
Command output: `tenki_exec` and `tenki_run_code` capture `stdout`/`stderr` by redirecting to files (`sh -c '… > out 2> err'`) and reading them back over the data plane, so you get the output inline through a plain HTTP client.
|
|
196
205
|
|
|
@@ -198,19 +207,19 @@ The wire details are ported from the live-verified [n8n community node](https://
|
|
|
198
207
|
|
|
199
208
|
## Security
|
|
200
209
|
|
|
201
|
-
This server holds a
|
|
210
|
+
This server holds a Luxor 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:
|
|
202
211
|
|
|
203
|
-
- **Least privilege:** every tool carries MCP annotations
|
|
212
|
+
- **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 `LUXORAI_MCP_READONLY=1` for an inspection-only server (read tools only), or `LUXORAI_MCP_DISABLED_TOOLS=tenki_run_code,…` to drop specific tools.
|
|
204
213
|
- **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)).
|
|
205
|
-
- **Audit:** `
|
|
206
|
-
- **Untrusted output:** `tenki_run_code`/`tenki_exec`/`tenki_read_file` return output from untrusted code
|
|
214
|
+
- **Audit:** `LUXORAI_MCP_AUDIT=1` logs each tool call's name to stderr.
|
|
215
|
+
- **Untrusted output:** `tenki_run_code`/`tenki_exec`/`tenki_read_file` return output from untrusted code; clients should treat tool results as data, not instructions.
|
|
207
216
|
|
|
208
217
|
Report vulnerabilities via a private [security advisory](https://github.com/LuxorLabs/tenki-mcp/security/advisories/new), not a public issue.
|
|
209
218
|
|
|
210
219
|
## Related
|
|
211
220
|
|
|
212
|
-
- **
|
|
213
|
-
- **n8n-nodes-tenki
|
|
221
|
+
- **Luxor Sandbox**, the platform: https://luxor.ai
|
|
222
|
+
- **n8n-nodes-tenki**, Luxor Sandbox as an n8n node: https://github.com/opencolin/n8n-nodes-tenki
|
|
214
223
|
|
|
215
224
|
## License
|
|
216
225
|
|
package/SECURITY.md
CHANGED
|
@@ -13,8 +13,8 @@ Please **do not** open a public issue for security reports. Open a private [GitH
|
|
|
13
13
|
## Controls this server provides
|
|
14
14
|
|
|
15
15
|
### Least privilege (MCP-07 — the main lever)
|
|
16
|
-
Every tool
|
|
17
|
-
`readOnlyHint` on inspection tools
|
|
16
|
+
Every tool has a human-readable **title** and MCP **annotations** so clients can surface/gate danger:
|
|
17
|
+
`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:
|
|
18
18
|
|
|
19
19
|
| Env | Effect |
|
|
20
20
|
|---|---|
|
package/dist/client.d.ts
CHANGED
|
@@ -12,6 +12,12 @@
|
|
|
12
12
|
* ported from the live-verified n8n community node
|
|
13
13
|
* (github.com/opencolin/n8n-nodes-tenki).
|
|
14
14
|
*/
|
|
15
|
+
/**
|
|
16
|
+
* True when the call ended on THIS side — the client's deadline or an MCP-side
|
|
17
|
+
* cancel — so the server never answered and the operation may still complete.
|
|
18
|
+
* A server error never carries the marker, even when its message says "timed out".
|
|
19
|
+
*/
|
|
20
|
+
export declare function isClientAbort(e: unknown): boolean;
|
|
15
21
|
export type Language = "shell" | "python" | "javascript";
|
|
16
22
|
export interface ExecResult {
|
|
17
23
|
command: string;
|
|
@@ -71,6 +77,10 @@ export declare class TenkiClient {
|
|
|
71
77
|
* Retry policy: rate limits always; `unavailable` and gateway-shaped
|
|
72
78
|
* 502/503/504 (load balancers and CDNs return these with an HTML or empty
|
|
73
79
|
* body, no ConnectRPC code) for every method that cannot double-apply.
|
|
80
|
+
* For a method that cannot double-apply, a Connect `resource_exhausted` (the
|
|
81
|
+
* handler's own quota or limit check; edge rate limits arrive as an uncoded
|
|
82
|
+
* 429) or any rejection carrying error details (a fork's partial snapshot and
|
|
83
|
+
* children) means the handler ran, so it is never retried.
|
|
74
84
|
*/
|
|
75
85
|
private shouldRetry;
|
|
76
86
|
/** Exponential backoff with half-jitter; a Retry-After header (seconds) wins, capped. */
|
|
@@ -85,8 +95,11 @@ export declare class TenkiClient {
|
|
|
85
95
|
* connection reset, DNS) retry for every method that cannot double-apply.
|
|
86
96
|
* `service` defaults to SandboxService; pass another fully-qualified ConnectRPC
|
|
87
97
|
* service (e.g. the SSH gateway service) for methods hosted elsewhere.
|
|
98
|
+
* `cancel` (the MCP request's abort signal) drops the HTTP request when the
|
|
99
|
+
* MCP client gives up, so the API sees the disconnect; a cancelled call is
|
|
100
|
+
* never retried.
|
|
88
101
|
*/
|
|
89
|
-
control(method: string, body?: Record<string, unknown>, service?: string): Promise<Record<string, any>>;
|
|
102
|
+
control(method: string, body?: Record<string, unknown>, service?: string, cancel?: AbortSignal): Promise<Record<string, any>>;
|
|
90
103
|
/**
|
|
91
104
|
* Mint (and cache per session) the data-plane endpoint + session certificate.
|
|
92
105
|
* A credential with no parseable expiry is cached for credTtlMs — never
|
|
@@ -132,6 +145,8 @@ export declare class TenkiClient {
|
|
|
132
145
|
timeoutMs?: number;
|
|
133
146
|
intervalMs?: number;
|
|
134
147
|
}): Promise<Record<string, any>>;
|
|
148
|
+
/** A file's raw bytes. The data plane's ReadFile has no range support, so this is always the whole file. */
|
|
149
|
+
readFileBytes(sessionId: string, path: string): Promise<Buffer>;
|
|
135
150
|
readTextFile(sessionId: string, path: string): Promise<string>;
|
|
136
151
|
writeTextFile(sessionId: string, path: string, text: string): Promise<Record<string, any>>;
|
|
137
152
|
/**
|
package/dist/client.js
CHANGED
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
* ported from the live-verified n8n community node
|
|
13
13
|
* (github.com/opencolin/n8n-nodes-tenki).
|
|
14
14
|
*/
|
|
15
|
+
import { isApiKey } from "./env.js";
|
|
15
16
|
const CONTROL_SERVICE = "tenki.sandbox.v1.SandboxService";
|
|
16
17
|
const DATA_SERVICE = "tenki.sandbox.v1.SandboxSessionDataPlaneService";
|
|
17
18
|
const DEFAULT_BASE_URL = "https://api.tenki.cloud";
|
|
@@ -32,7 +33,7 @@ const RATE_LIMIT_CODES = new Set(["rate_limited", "ratelimited", "resource_exhau
|
|
|
32
33
|
// Skipping a teardown retry is the expensive mistake: runCode's finally
|
|
33
34
|
// swallows terminate errors, so a transient blip would silently leave a
|
|
34
35
|
// billing sandbox running.
|
|
35
|
-
const NON_IDEMPOTENT_METHOD = /^(Create|Build|Publish|Resume|Extend|ExecuteCommand)/;
|
|
36
|
+
const NON_IDEMPOTENT_METHOD = /^(Create|Build|Publish|Resume|Extend|Fork|ExecuteCommand)/;
|
|
36
37
|
// Data-plane methods safe to retry: read-shaped only. A retried Remove that
|
|
37
38
|
// had actually applied would surface a spurious "not found" for an op that
|
|
38
39
|
// succeeded.
|
|
@@ -43,6 +44,7 @@ const RETRY_AFTER_CAP_MS = 30_000;
|
|
|
43
44
|
const DEFAULT_TIMEOUT_MS = 30_000;
|
|
44
45
|
const DEFAULT_EXEC_TIMEOUT_MS = 630_000; // runCode's 600s hard cap + margin
|
|
45
46
|
const EXEC_TIMEOUT_MARGIN_MS = 30_000; // headroom over a command's own timeout
|
|
47
|
+
const CREATE_WAIT_READY_TIMEOUT_MS = 90_000; // server holds wait_ready up to 60s + margin
|
|
46
48
|
/**
|
|
47
49
|
* Methods whose RPC does not return until a long storage/VM operation finishes,
|
|
48
50
|
* 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
|
|
|
58
60
|
* ~278ms, so giving them a 10-minute budget would only delay a genuinely hung
|
|
59
61
|
* call. Their orphan-on-timeout hazard is real but needs idempotency, not a
|
|
60
62
|
* bigger timeout.
|
|
63
|
+
*
|
|
64
|
+
* ForkSession holds until its snapshot is READY and every child exists (and is
|
|
65
|
+
* RUNNING with wait); if the caller disconnects first the server terminates the
|
|
66
|
+
* children it could not deliver, so a short budget would destroy the fork.
|
|
67
|
+
*
|
|
68
|
+
* ResumeSession (since tenki-app #6486, sandbox-engine v2.35.0) holds until the
|
|
69
|
+
* session leaves RESUMING. The server's wait has no deadline of its own, and
|
|
70
|
+
* the restore it waits on runs detached for up to 6 minutes
|
|
71
|
+
* (resumeDispatchDetachedTimeout), so a 30s budget reports a slow but
|
|
72
|
+
* successful resume as failed.
|
|
61
73
|
*/
|
|
62
|
-
const SLOW_METHOD = /^(CreateSnapshot|PauseSession)$/;
|
|
74
|
+
const SLOW_METHOD = /^(CreateSnapshot|PauseSession|ForkSession|ResumeSession)$/;
|
|
75
|
+
/**
|
|
76
|
+
* True when the call ended on THIS side — the client's deadline or an MCP-side
|
|
77
|
+
* cancel — so the server never answered and the operation may still complete.
|
|
78
|
+
* A server error never carries the marker, even when its message says "timed out".
|
|
79
|
+
*/
|
|
80
|
+
export function isClientAbort(e) {
|
|
81
|
+
return typeof e?.clientAbort === "string";
|
|
82
|
+
}
|
|
63
83
|
const DEFAULT_SLOW_TIMEOUT_MS = 600_000;
|
|
64
84
|
// Session-credential cache lifetime handling: a credential whose expiry the API
|
|
65
85
|
// omits (or that we cannot parse) is assumed valid only briefly — never forever —
|
|
@@ -98,11 +118,11 @@ function shellQuote(value) {
|
|
|
98
118
|
}
|
|
99
119
|
/**
|
|
100
120
|
* Tenki's auth header is chosen by token prefix (verbatim from the SDK's auth.ts):
|
|
101
|
-
* `tk_` → Bearer, `ory_st_` → X-Session-Token, otherwise a `tenki_session` cookie.
|
|
121
|
+
* `lx_`/`tk_` → Bearer, `ory_st_` → X-Session-Token, otherwise a `tenki_session` cookie.
|
|
102
122
|
*/
|
|
103
123
|
function authHeaders(token) {
|
|
104
124
|
const t = token.trim();
|
|
105
|
-
if (t
|
|
125
|
+
if (isApiKey(t))
|
|
106
126
|
return { Authorization: `Bearer ${t}` };
|
|
107
127
|
if (t.startsWith("ory_st_"))
|
|
108
128
|
return { "X-Session-Token": t };
|
|
@@ -150,8 +170,14 @@ export class TenkiClient {
|
|
|
150
170
|
* the command's own timeout (plus margin) instead of the unary default.
|
|
151
171
|
*/
|
|
152
172
|
timeoutFor(method, body) {
|
|
173
|
+
// With `async: true` these RPCs return once the work is accepted, so the
|
|
174
|
+
// long storage budget would only delay a genuinely hung call.
|
|
153
175
|
if (SLOW_METHOD.test(method))
|
|
154
|
-
return this.slowTimeoutMs;
|
|
176
|
+
return body.async === true ? this.timeoutMs : this.slowTimeoutMs;
|
|
177
|
+
// CreateSession{waitReady} is held server-side for up to 60s (createWaitReadyMaxWait);
|
|
178
|
+
// a 30s client budget would abort a slow boot and orphan the (billing) sandbox.
|
|
179
|
+
if (method === "CreateSession" && body.waitReady === true)
|
|
180
|
+
return Math.max(this.timeoutMs, CREATE_WAIT_READY_TIMEOUT_MS);
|
|
155
181
|
if (method !== "ExecuteCommand")
|
|
156
182
|
return this.timeoutMs;
|
|
157
183
|
const t = typeof body.timeout === "string" ? Number.parseInt(body.timeout, 10) : Number.NaN; // "30s"
|
|
@@ -163,17 +189,21 @@ export class TenkiClient {
|
|
|
163
189
|
* response whose headers arrive but whose body stalls must fail with the
|
|
164
190
|
* same friendly, retryable timeout as a connection that never responds.
|
|
165
191
|
*/
|
|
166
|
-
async fetchTextWithTimeout(url, init, timeoutMs, what) {
|
|
192
|
+
async fetchTextWithTimeout(url, init, timeoutMs, what, cancel) {
|
|
167
193
|
const budget = Math.max(1, Math.floor(timeoutMs));
|
|
194
|
+
const timeout = AbortSignal.timeout(budget);
|
|
168
195
|
try {
|
|
169
|
-
const res = await fetch(url, { ...init, signal: AbortSignal.timeout
|
|
196
|
+
const res = await fetch(url, { ...init, signal: cancel ? AbortSignal.any([timeout, cancel]) : timeout });
|
|
170
197
|
const text = await res.text();
|
|
171
198
|
return { ok: res.ok, status: res.status, headers: res.headers, text };
|
|
172
199
|
}
|
|
173
200
|
catch (e) {
|
|
174
201
|
const name = e?.name;
|
|
202
|
+
if (cancel?.aborted && !timeout.aborted) {
|
|
203
|
+
throw Object.assign(new Error(`Tenki ${what} was cancelled by the MCP client before it returned.`), { clientAbort: "cancelled" });
|
|
204
|
+
}
|
|
175
205
|
if (name === "TimeoutError" || name === "AbortError") {
|
|
176
|
-
throw new Error(`Tenki ${what} timed out after ${budget}ms with no response.`);
|
|
206
|
+
throw Object.assign(new Error(`Tenki ${what} timed out after ${budget}ms with no response.`), { clientAbort: "timeout" });
|
|
177
207
|
}
|
|
178
208
|
throw e;
|
|
179
209
|
}
|
|
@@ -182,8 +212,15 @@ export class TenkiClient {
|
|
|
182
212
|
* Retry policy: rate limits always; `unavailable` and gateway-shaped
|
|
183
213
|
* 502/503/504 (load balancers and CDNs return these with an HTML or empty
|
|
184
214
|
* body, no ConnectRPC code) for every method that cannot double-apply.
|
|
215
|
+
* For a method that cannot double-apply, a Connect `resource_exhausted` (the
|
|
216
|
+
* handler's own quota or limit check; edge rate limits arrive as an uncoded
|
|
217
|
+
* 429) or any rejection carrying error details (a fork's partial snapshot and
|
|
218
|
+
* children) means the handler ran, so it is never retried.
|
|
185
219
|
*/
|
|
186
|
-
shouldRetry(method, status, code) {
|
|
220
|
+
shouldRetry(method, status, code, hasDetails) {
|
|
221
|
+
const handlerRan = hasDetails || code === "resource_exhausted" || code === "resourceexhausted";
|
|
222
|
+
if (handlerRan && NON_IDEMPOTENT_METHOD.test(method))
|
|
223
|
+
return false;
|
|
187
224
|
if (status === 429 || RATE_LIMIT_CODES.has(code))
|
|
188
225
|
return true;
|
|
189
226
|
const transient = code === "unavailable" || status === 502 || status === 503 || status === 504;
|
|
@@ -207,8 +244,11 @@ export class TenkiClient {
|
|
|
207
244
|
* connection reset, DNS) retry for every method that cannot double-apply.
|
|
208
245
|
* `service` defaults to SandboxService; pass another fully-qualified ConnectRPC
|
|
209
246
|
* service (e.g. the SSH gateway service) for methods hosted elsewhere.
|
|
247
|
+
* `cancel` (the MCP request's abort signal) drops the HTTP request when the
|
|
248
|
+
* MCP client gives up, so the API sees the disconnect; a cancelled call is
|
|
249
|
+
* never retried.
|
|
210
250
|
*/
|
|
211
|
-
async control(method, body = {}, service = CONTROL_SERVICE) {
|
|
251
|
+
async control(method, body = {}, service = CONTROL_SERVICE, cancel) {
|
|
212
252
|
const url = `${this.baseUrl}/${service}/${method}`;
|
|
213
253
|
const deadline = Date.now() + this.timeoutFor(method, body ?? {});
|
|
214
254
|
for (let attempt = 0;; attempt++) {
|
|
@@ -218,12 +258,12 @@ export class TenkiClient {
|
|
|
218
258
|
method: "POST",
|
|
219
259
|
headers: { "Content-Type": "application/json", "Connect-Protocol-Version": "1", ...this.controlAuthHeaders() },
|
|
220
260
|
body: JSON.stringify(body ?? {}),
|
|
221
|
-
}, deadline - Date.now(), method);
|
|
261
|
+
}, deadline - Date.now(), method, cancel);
|
|
222
262
|
}
|
|
223
263
|
catch (e) {
|
|
224
264
|
// Transport failure: the request may or may not have reached the
|
|
225
265
|
// server, so only methods that cannot double-apply are retried.
|
|
226
|
-
if (attempt < MAX_RETRIES && !NON_IDEMPOTENT_METHOD.test(method)) {
|
|
266
|
+
if (attempt < MAX_RETRIES && !cancel?.aborted && !NON_IDEMPOTENT_METHOD.test(method)) {
|
|
227
267
|
const wait = this.backoffMs(attempt, null);
|
|
228
268
|
if (Date.now() + wait < deadline) {
|
|
229
269
|
await sleep(wait);
|
|
@@ -236,7 +276,8 @@ export class TenkiClient {
|
|
|
236
276
|
return JSON.parse(res.text);
|
|
237
277
|
const parsed = safeJson(res.text);
|
|
238
278
|
const code = typeof parsed?.code === "string" ? parsed.code.toLowerCase() : "";
|
|
239
|
-
|
|
279
|
+
const details = Array.isArray(parsed?.details) ? parsed.details : [];
|
|
280
|
+
if (attempt < MAX_RETRIES && this.shouldRetry(method, res.status, code, details.length > 0)) {
|
|
240
281
|
const wait = this.backoffMs(attempt, res.headers.get("retry-after"));
|
|
241
282
|
if (Date.now() + wait < deadline) {
|
|
242
283
|
await sleep(wait);
|
|
@@ -244,7 +285,8 @@ export class TenkiClient {
|
|
|
244
285
|
}
|
|
245
286
|
}
|
|
246
287
|
const msg = parsed?.message || res.text || `HTTP ${res.status}`;
|
|
247
|
-
|
|
288
|
+
// Connect error details (type, value, optional protojson `debug`) carry partial results, e.g. a failed fork's snapshot.
|
|
289
|
+
throw Object.assign(new Error(`Tenki ${method} failed (${res.status}${code ? ` ${code}` : ""}): ${msg}`), { code, details });
|
|
248
290
|
}
|
|
249
291
|
}
|
|
250
292
|
/**
|
|
@@ -405,10 +447,14 @@ export class TenkiClient {
|
|
|
405
447
|
await sleep(intervalMs);
|
|
406
448
|
}
|
|
407
449
|
}
|
|
408
|
-
|
|
450
|
+
/** A file's raw bytes. The data plane's ReadFile has no range support, so this is always the whole file. */
|
|
451
|
+
async readFileBytes(sessionId, path) {
|
|
409
452
|
const resp = await this.data(sessionId, "ReadFile", { path });
|
|
410
453
|
const content = (resp.content ?? resp.data ?? resp.file?.content ?? "");
|
|
411
|
-
return content ? Buffer.from(content, "base64").
|
|
454
|
+
return content ? Buffer.from(content, "base64") : Buffer.alloc(0);
|
|
455
|
+
}
|
|
456
|
+
async readTextFile(sessionId, path) {
|
|
457
|
+
return (await this.readFileBytes(sessionId, path)).toString("utf8");
|
|
412
458
|
}
|
|
413
459
|
async writeTextFile(sessionId, path, text) {
|
|
414
460
|
const content = Buffer.from(text, "utf8").toString("base64");
|