@tenkicloud/mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,161 +1,46 @@
 # Changelog
 
-All notable changes to tenki-mcp. This project follows semantic versioning.
+All notable changes to `@tenkicloud/mcp`. This project follows semantic versioning.
 
-## [0.1.0] — 2026-08-03 — First npm release: typed git, network hardening, structured output
+## [0.2.0] — 2026-08-21
 
-Published as **`@tenkicloud/mcp`**, matching the `@tenkicloud/sandbox` SDK. Install with `npx -y @tenkicloud/mcp`; the command it provides is still `tenki-mcp`.
+- Remove standalone image management tools. Template images remain available through template builds and sandbox creation.
+- Use `image` when creating a sandbox from a template image; removed image-reference arguments are now rejected.
+- Cap `tenki_exec` / `tenki_run_code` inline output at 64 KB per stream (override with `max_output_bytes` on `tenki_exec`). Larger output returns a head+tail preview with `stdoutTruncated`/`stderrTruncated` set, and the full capture file is kept in the sandbox at the reported `stdoutPath`/`stderrPath`.
+- Remove the project-scoped surface — the `tenki_list_project_sandboxes`/`_templates`/`_volumes`/`_snapshots` tools (their API methods no longer exist) and the `project_id` arguments (ignored by the API). Use the workspace-scoped equivalents.
+- Document the template-image path end to end: `image_name` builds require a typed template (`builder_spec`), and `tenki_create_sandbox`'s `image` takes the ready build's `imageDigestRef`.
 
-### Fixed by an end-to-end sweep of all 85 tools against the live API
+## [0.1.0] — 2026-08-03 — Initial release
 
-- **`tenki_create_snapshot` and `tenki_pause_sandbox` reported failure on operations that succeeded.** Both RPCs block until the underlying storage work finishes — measured at 59s and 41s — so the 30s default HTTP budget introduced with the timeout work cut them off. The caller got `timed out after 30000ms` while the snapshot (or a multi-GB pause snapshot) had in fact been created, leaving an orphaned resource whose id it never saw, and an agent that retried burned quota. Both now use a 600s budget, tunable with `TENKI_MCP_SLOW_TIMEOUT_MS` (`TENKI_MCP_TIMEOUT_MS` tunes the ordinary 30s one). Async methods that return a handle in under a second — `BuildTemplate`, `PublishRegistryImage` — deliberately keep the short budget.
-- **`tenki_update_workspace_settings` and `tenki_update_snapshot_retention_settings` did nothing at all, and reported success.** Every field they sent (`defaultIdleTimeoutMinutes`, `defaultMaxDurationSeconds`, `snapshotRetentionDays`, `retentionDays`) is absent from the API; connect-go discards unknown fields, so the server returned 200 with the settings unchanged. They now send the real contract — `pauseRetention`/`snapshotRetention` as protobuf Durations with their `clear*` companions, plus the `max*` quotas — reject a call that would change nothing, and `clear_retention` makes "keep snapshots indefinitely" expressible for the first time. The retention pair is also documented as deprecated upstream in favour of the workspace-settings pair.
-- **`tenki_list_files` hid every dotfile.** The data plane omits dot-prefixed entries unless asked, so `.git`, `.env` and `.gitignore` were invisible and an agent would conclude they did not exist. It now sends `include_hidden` (default true, overridable) and always returns an `entries` array instead of a bare `{}` for an empty directory.
-- **`tenki_list_preview_urls` advertised a filter the API does not have.** `ListPreviewUrls` takes no session id, so the one this tool sent was silently dropped and every session's preview URLs came back as if filtered. The filter is now applied client-side and says so in the result; `page_size`, `page_token` and `workspace_id` — all real fields the tool never exposed — are now available, and the deprecated `project_id` is gone.
-- **`tenki_publish_image`'s documented example could never work:** its own description showed `myws/myimage:latest`, and the API rejects any tag or `@snapshot` on publish. The tagless form is now enforced client-side with an explanatory message.
-- **`tenki_unshare_image` silently revoked nothing** when called with neither `grant_id` nor `grantee_workspace_id`, returning the image object like a success. It now refuses, matching the guard `tenki_delete_image` already had.
-- **`tenki_open_preview` hands back an unreachable URL** for any port but the web terminal (7681): the API deliberately drops the regional host for other ports and returns a fallback that has no edge route, so the URL 404s. The description now says so and points at `tenki_expose_port`/`tenki_create_preview_url`. Platform-side issue; documented rather than worked around.
+Model Context Protocol server for Tenki Cloud — disposable microVM sandboxes for AI agents. Published as **`@tenkicloud/mcp`**, matching the `@tenkicloud/sandbox` SDK. Install with `npx -y @tenkicloud/mcp`; the command it provides is `tenki-mcp`.
 
-### A missing credential no longer looks like a broken server
+### Tools
 
-- **New tool `tenki_auth_status`** (85 tools total) — reports whether a usable credential is configured, which kind (`api_key` for `tk_…`, `oauth_session_token` for `ory_st_…`, or `session_cookie`), which env var it came from, the endpoint targeted, and whether a live identity probe succeeded. Never returns the token. Structured output, annotated read-only, and available under `TENKI_MCP_READONLY` (it is how you diagnose a credential problem in that posture) — `TENKI_MCP_DISABLED_TOOLS` can still drop it.
-- **The server starts without a credential instead of exiting 1.** Exiting made MCP clients report an opaque "server failed to start" while swallowing the stderr line that explained why, leaving the user with a broken server and no cause. It now boots with `tenki_auth_status` as the only registered tool, so an agent can ask what is wrong and relay the fix; the reported `toolsRegistered` count makes that degraded mode explicit. Registering all 84 API tools in that state would only offer tools that cannot work.
-- Reporting status is the whole scope: nothing here logs in, opens a browser, or writes credentials. Get a credential with `tenki login` or from the dashboard.
+- **85 tools covering the full Tenki unary API**, enforced by a CI parity audit (`scripts/parity-audit.mjs` fails the build if any SandboxService / DataPlane / SSHGateway method lacks a tool): sandbox lifecycle, code execution (`tenki_exec`, `tenki_run_code`), files, git, ports and preview URLs, snapshots, volumes, templates, SSH, artifacts, and workspace administration.
+- **`tenki_git`** validates `operation` as an enum of what the API actually supports (`clone`, `checkout`, `diff`, `log`) with per-operation arg keys documented; other git commands go through `tenki_exec`.
+- **`tenki_exec` returns structured output**: it declares an `outputSchema` and returns `structuredContent` (`stdout`/`stderr`/`exitCode`/`ok`) alongside a human-readable rendering in which control characters, bidi overrides, and zero-width marks are escaped to visible `\xNN`/`\uNNNN` — sandbox output is untrusted.
+- **`tenki_auth_status`** reports whether a usable credential is configured, which kind (`api_key`, `oauth_session_token`, or `session_cookie`), which env var it came from, the endpoint targeted, and whether a live identity probe succeeded — without ever returning the token. The server boots without a credential with this as the only registered tool, so a misconfigured client can ask what is wrong instead of seeing an opaque "server failed to start".
+- Shared, described input schemas across modules: session ids (trimmed, non-empty), ports (1–65535), preview slugs (matching the server's own validation), and file paths (blank rejected client-side, otherwise sent verbatim — no silent trimming of legal POSIX filenames).
 
-### Tool-schema DX (git enum, shared schemas, README)
+### Transports
 
-- **`tenki_git` now validates `operation` as an enum of what the API actually supports: `clone`, `checkout`, `diff`, `log`.** The tool previously advertised ten operations, but six of them (status/add/commit/pull/push/fetchPR) are rejected by the API's own validation (`GitOperationRequest` allows exactly four) — a model following the old description was guaranteed a server error. Per-operation arg keys are now documented in the tool description, grounded in the engine's arg builder: clone `{repo, branch?, depth?, directory?}`, checkout `{ref, create?}`, diff `{range? | base?+head?, path?}`, log `{max_count?, range?, path?}`. Other git commands: use `tenki_exec` with `git ...`.
-- **Shared input schemas** in `common.ts`: `sessionIdSchema` (described; trimmed and non-empty, so a whitespace-only id is rejected client-side — previously bare and undescribed in 8 of 14 modules) — reused across ports/previews/files/exec/ssh/snapshots/artifacts/sandboxes/volumes/sessions-admin, including the `session_ids` array in `tenki_terminate_sandboxes`; `portSchema` (1-65535 — `tenki_expose_port` previously accepted port 99999 and learned the constraint from a server error) — ports; `slugSchema` (3-63 chars, lowercase/digits/hyphens, no leading/trailing hyphen — matching the server's shared preview-slug validation, which `ExposePort` also applies) — ports/previews.
-- `tenki_git` accepts numbers and booleans as arg values (`depth: 1`, `create: true`) and coerces them to the strings the wire expects, instead of rejecting values that would serialize identically.
-- **Shared `pathSchema`** (trimmed, non-empty) across every file-path argument (read/write/list/stat/mkdir/remove/move/upload/mount) — an empty or whitespace-only path is rejected client-side instead of by a server error.
-- **`tenki_git` description documents a live-verified caveat:** checkout/diff/log run in the session's working directory and cannot target a repo cloned into a subdirectory (the API has no directory arg for them) — use `tenki_exec` with `git -C <dir> ...` for those until the API grows one. `clone` works as documented.
-- **README**: install forms for Claude Code (`claude mcp add`), Claude Desktop, and Cursor; a consolidated environment-variable table; auth precedence documented (`TENKI_AUTH_TOKEN` wins over `TENKI_API_KEY`); the Tools table no longer lists unsupported git operations.
+- **stdio** (default) and **Streamable HTTP** (`TENKI_MCP_TRANSPORT=http PORT=3000`), built from a shared `createServer()` factory.
+- The HTTP transport is hardened: loopback-only by default (`TENKI_MCP_HTTP_HOST` to expose), bearer auth via `TENKI_MCP_HTTP_TOKEN` (constant-time checked; required to bind a non-loopback host), DNS-rebinding protection via a Host-header allowlist, a 1 MiB request-body cap enforced on both the header and the streamed byte count, session count cap with idle reaping, and SIGTERM/SIGINT graceful shutdown.
 
-### Network-layer hardening (timeouts, retry policy, credential cache)
+### Security posture
 
-- **Every fetch now carries a timeout** — a hung control- or data-plane connection, or a response whose body stalls after the headers arrive, fails the tool call with a clear `timed out after Nms` error naming the method instead of blocking it forever. Unary calls default to 30s; `ExecuteCommand` follows the command's own timeout + 30s margin (630s when the command has none). Tunable via `TenkiClient` options. Each call has ONE shared deadline: retries and backoff sleeps draw from it, so a call can never stack attempts past its timeout.
-- **Retry policy is shaped by double-apply risk, not by method naming.** Methods that must never run twice (`Create*`, `Build*`, `Publish*`, `Resume*`, `Extend*`, `ExecuteCommand`) never retry transient failures — a half-applied `CreateSession` retried could boot and bill a second sandbox. Everything else — reads AND teardown (`Terminate*`/`Delete*`/`Detach*`, where a repeat lands in the same state) — retries `unavailable`, gateway-shaped 502/503/504 (HTML/empty bodies from load balancers included), and transport-level failures (timeout, connection reset, DNS). Rate-limit rejections still retry for every method, with jittered backoff and `Retry-After` honored (capped at 30s).
-- **The data plane retries too.** Read-shaped data-plane methods (`ReadFile`/`Stat`/`List*`) — the path behind every file tool and how `tenki_exec` reads back its own output — now retry rate limits, transient/gateway errors, and transport failures under the same shared deadline. Write-shaped data methods surface failures immediately.
-- **Session-credential cache can no longer go permanently stale.** A credential whose expiry the API omits (or that fails to parse) was previously cached *forever* — once the cert actually expired, every file operation for that session failed for the life of the process. Now: missing expiry → 5-minute TTL; known expiry → refreshed 30s early (floored at 5s so a short-lived credential still caches; a credential already past its expiry is not cached at all); a stale-certificate failure (401/`unauthenticated`) invalidates the cached credential and retries once with a fresh one (never loops; `permission_denied` does NOT re-mint — a denied path is a user error a fresh cert can't fix); and minting is single-flight, so concurrent cold-cache calls share one mint.
-- New offline regression suite `test/client-net.test.mjs` (local `node:http` stub, zero external network) covering all of the above; wired into `npm test` and CI.
+- **Tool annotations on every tool** (`readOnlyHint`, `destructiveHint`, `openWorldHint`) so clients can surface or gate dangerous tools.
+- **Least-privilege env controls:** `TENKI_MCP_READONLY=1` registers only read tools (plus `tenki_auth_status`); `TENKI_MCP_DISABLED_TOOLS=a,b` drops named tools; `TENKI_MCP_AUDIT=1` logs each tool call's name and arg keys — never values, content, or tokens — to stderr. Applied centrally via a registration guard covering both SDK registration APIs.
+- **SECURITY.md** documents the threat model, trust boundaries (the key and endpoint are capabilities; sandbox output is untrusted), and a CSA MCP Server Top-10 mapping.
+- Importing the package cannot execute the server or exit the host process: the package is bin-only.
 
-### Structured tool output (first tool: `tenki_exec`)
+### Network layer
 
-- **`tenki_exec` now declares an `outputSchema` and returns `structuredContent`**, so MCP clients can consume `stdout`/`stderr`/`exitCode`/`ok` as typed JSON instead of re-parsing a stringified blob. The SDK validates every successful result against the schema.
-- **`tenki_exec` returns two text blocks:** the serialized JSON result first (the MCP spec's backwards-compatibility contract for structured content — existing text-parsing consumers keep working), then a human-readable rendering headed by `exit <code>` and character-count markers. Characters that can misrepresent output in a terminal — C0/C1 controls, bidi overrides, zero-width marks — are escaped to visible `\xNN`/`\uNNNN` in the rendering (sandbox output is untrusted); `structuredContent` keeps the raw strings.
-- **Registration guard extended to `registerTool`** — the modern SDK registration API (required for `outputSchema`) now passes through the same least-privilege guard as the legacy `.tool()` form: name-derived annotations, `TENKI_MCP_READONLY`, `TENKI_MCP_DISABLED_TOOLS`, and `TENKI_MCP_AUDIT` all apply. Previously a module using `registerTool` would have silently bypassed all four.
-- **Behavior change:** `tenki_exec` / `tenki_run_code` results now report `ok: false` when the command ran but its output could not be read back (`captureError` set). Previously a capture failure with exit code 0 reported `ok: true` with empty stdout/stderr, which read as a clean silent success. `tenki_move_path` (exec-backed) is unaffected: its `ok` tracks the `mv` exit code, with any `captureError` surfaced separately.
-- An unparseable exit code from the API is normalized to `-1` so the run's output is still returned instead of failing schema validation.
-- Offline regression checks: `tenki_exec` advertises the schema, still carries guard annotations via the `registerTool` path, and exactly one tool declares an `outputSchema` (bump the count when migrating more tools). A new offline suite (`test/exec-output.test.mjs`) calls the tool in-memory and locks down the content blocks, escaping, output validation, and `tenki_move_path` semantics.
+- **Every request carries a timeout** with one shared deadline per call (retries and backoff draw from it): 30s for unary calls (`TENKI_MCP_TIMEOUT_MS`), 600s for RPCs that block on storage work — snapshot creation and pause (`TENKI_MCP_SLOW_TIMEOUT_MS`) — and command execution follows the command's own timeout plus a 30s margin.
+- **Retry policy shaped by double-apply risk:** methods that must never run twice (creates, builds, publishes, resumes, extends, exec) never retry transient failures; reads and idempotent teardown retry `unavailable`, gateway-shaped 502/503/504, and transport-level failures, with rate limits retried for every method under jittered backoff honoring `Retry-After`. Read-shaped data-plane methods retry under the same rules.
+- **Session-credential cache** with expiry-aware refresh, single-flight minting, and invalidate-and-retry-once on a stale certificate (`permission_denied` deliberately does not re-mint).
 
-### Fixed
+### Client
 
-- **Path validation no longer rewrites the path.** `pathSchema` used zod's `.trim()`, which is a *transform*: leading/trailing whitespace (legal in POSIX filenames) was silently stripped before sending, so `tenki_remove_path`/`tenki_move_path` on such a file operated on a *different* path than the one named. Paths now reach the API verbatim, with blank/whitespace-only values still rejected client-side. `tenki_exec`'s `cwd` had the same trim and is fixed too. (`sessionIdSchema` keeps trimming: a session id is a UUID, so surrounding whitespace is always an accident.)
-- **Importing the package no longer terminates the importing process.** `main` pointed at the CLI entrypoint, whose token check runs at module load and calls `process.exit(1)` — so `import "tenki-mcp"` killed the host process outright (and with a token set, would have booted a stdio server inside it). The package is now bin-only: `npx tenki-mcp` and every MCP client config are unaffected (they resolve `bin`), and importing raises a catchable module-not-found error instead.
-- **A path or working directory beginning with a hyphen is no longer read as a command option.** Shell-quoting doesn't prevent it: `cd '-L'` silently succeeds into `$HOME`, so `tenki_exec` with such a `cwd` ran the command in the wrong directory, and `mv '-file' …` failed outright. Both now pass `--` before their operands.
-- **Sandbox creation was broken for workspace-scoped API keys.** `resolveOwner` forwarded WhoAmI's `ownerType` verbatim into `CreateSession`, but the API validates `owner_type ∈ {SERVICE, USER}` and now returns `WORKSPACE` for workspace-scoped keys → every `tenki_create_sandbox`/`tenki_run_code` failed with `400 invalid_argument`. Fix: send the same placeholder the first-party SDKs hardcode (`"SERVICE"`/`"self"`) when WhoAmI returns a type CreateSession rejects — the server derives the real owner from the authenticated identity regardless. Verified live: create → exec (structured) → terminate, 12/12 checks.
-- `test/http-transport.test.mjs` no longer asserts `ownerType === "USER"` (stale against the same API change); it accepts any authenticated owner type.
-
-## [2.0.0-alpha.2] — 2026-07-27 — MCP security hardening + registry fixes
-
-### MCP security hardening (least privilege + annotations)
-
-Applies MCP-native security controls, mapped to the CSA MCP Server Top-10 (esp. MCP-07 excessive permissions). See SECURITY.md.
-
-- **Tool annotations** on all 84 tools (`readOnlyHint` on 36 read tools, `destructiveHint` on the 13 delete/terminate/revoke tools, `openWorldHint` on all) so clients can surface/gate dangerous tools.
-- **Least-privilege env controls:** `TENKI_MCP_READONLY=1` registers only read tools (no create/run/delete/spend); `TENKI_MCP_DISABLED_TOOLS=a,b` drops named tools. Applied centrally via a registration guard — no change to the tool modules.
-- **Audit logging:** `TENKI_MCP_AUDIT=1` logs each tool call name + arg keys (never values/content/token) to stderr.
-- **SECURITY.md** — threat model, trust boundaries (the key + endpoint are capabilities; sandbox output is untrusted), and a full CSA Top-10 mapping. README security section + disclosure policy.
-- Regression test `test/security.test.mjs` (10 offline checks).
-
-### Registry/preview/artifact request-shape fixes
-
-An API-contract review of the write paths found **11 more request-shape bugs** beyond the two already fixed — the registry module was almost entirely non-functional (it sent `reference` where the API wants `ref` / `imageId` / `imageRef`). All fixed and verified (each now reaches a clean not-found instead of a validation error); regression-guarded by test/registry-shapes.test.mjs.
-
-- **registry** (9): `get_image`, `resolve_image_ref` (needs `ref`+`workspaceId`), `set_image_visibility` (needs `ref`+`REGISTRY_VISIBILITY_*` enum), `delete_image` (whole=`ref`; version=`imageId`+`snapshotId`), `share_image` (`imageRef`+`targetWorkspaceId`), `unshare_image` (`ref`), `revoke_image_share_grant` (`grantId`), `publish_image` (needs `ref`+`kind`+`snapshotId`/`sourceTemplateId`, not a session).
-- **previews** (1): `touch_preview` takes a `previewToken`, not session/port.
-- **artifacts** (1): `get_download_url` supports download-by-artifact-id only (the API rejects a path); the non-functional `path` option was removed.
-
-## [2.0.0-alpha.1] — 2026-07-21 — Harden the HTTP transport (security)
-
-An independent security review of the v2.0.0-alpha.0 HTTP transport found three coupled HIGH issues (the endpoint holds a shared TENKI_API_KEY and exposes code-execution + credit-spend tools). All fixed:
-
-- **Loopback-only by default** — binds `127.0.0.1`, not `0.0.0.0`; the banner now shows the real host. Expose with `TENKI_MCP_HTTP_HOST`.
-- **Bearer auth** — set `TENKI_MCP_HTTP_TOKEN` (constant-time checked); the server **refuses to bind to a non-loopback host without it**.
-- **DNS-rebinding protection ON** — Host-header allowlist, so a malicious web page cannot drive the local server (verified: forged Host → 403).
-
-Also: session count cap + idle reaping (init-flood DoS), a 1 MiB request-body cap enforced on both the Content-Length header and the streamed byte count (memory DoS), malformed JSON → JSON-RPC `-32700`/400, no internals in error responses, and SIGTERM/SIGINT graceful shutdown. Offline regression `test/http-input.test.mjs` asserts the 413 + a clean init; `test/http-transport.test.mjs` asserts the auth gate + rebinding rejection (7/7). stdio + tool parity unchanged (84).
-
-## [2.0.0-alpha.0] — 2026-07-21 — HTTP transport (v2 begins)
-
-The server now speaks **Streamable HTTP** in addition to stdio, so it can be hosted for remote MCP clients (`TENKI_MCP_TRANSPORT=http PORT=3000`). Verified end-to-end (connect → tools/list → tool call over HTTP; stdio unchanged, 84 tools). Server construction refactored into a shared `createServer()` factory (src/server.ts) used by both transports.
-
-Streaming exec (`StreamCommandOutput`) and per-request HTTP auth are not yet implemented. Alpha: not for production hosting yet.
-
-## [1.0.2] — 2026-07-21 — Fixes from comprehensive testing
-
-A 34-scenario test matrix run against live Tenki found **two real request-shape bugs**, both fixed and verified end-to-end:
-
-- **tenki_attach_volume** sent a flat request; AttachVolumeRequest nests the target under a `volume` sub-message (`{sessionId, volume:{volumeId, mountPath, readOnly?}}`). Every attach was rejected — this broke the volume warm-cache workflow. Fixed.
-- **tenki_list_image_share_grants** sent `reference`; the API field is `ref` (required). It was silently ignored, 400-ing every call and making the ACL-read surface unreachable. Fixed.
-
-Also: a real MCP **test suite** (`test/`) — a cleanup-safe harness driving the actual MCP protocol + 5 suites (coverage, client-integration, errors-edge, journeys, admin-previews) — **68 checks, all green**. Doc fixes (workspace tool names; create_template setup_script). No tool count change (84).
-
-## [1.0.1] — 2026-07-20 — Fix ResizeVolume field
-
-Live-verifying the volume write path (once a workspace volume-quota block was cleared) surfaced one real bug: `tenki_resize_volume` sent `sizeBytes` but the API expects `newSizeBytes`, so resizes were rejected. Fixed. Full volume lifecycle (create → get → update → resize → delete) now live-verified end-to-end.
-
-## [1.0.0] — 2026-07-20 — Full CLI parity
-
-**84 tools — parity with the entire Tenki unary API**, enforced by a CI parity audit (scripts/parity-audit.mjs fails the build if any SandboxService / DataPlane / SSHGateway method lacks a tool; streaming methods are deferred to v2.0). This release closes the long tail on top of v0.7: binary artifact transfer (get_upload_url / get_download_url), SSH access (update_ssh_keys / issue_ssh_cert / list_ssh_gateways), the preview-URL primitives (get/delete/touch/bind/unbind/resolve), project-scoped list variants (volumes/snapshots/templates), snapshot-retention settings, and registry grant-revoke. New read paths live-verified against api.tenki.cloud; write/advanced additions are grounded in the published API surface and labeled where not exercised end-to-end.
-
-**Tools:** +18 to reach 84 (artifacts x2, ssh x3, preview extras x6, list variants x4, retention x2, revoke-grant x1)
-
-## [0.7.0] — 2026-07-20 — Workspace administration
-
-Workspace-level administration: sandbox usage reporting and get/update of workspace sandbox settings. Live-verified.
-
-**Tools:** tenki_get_workspace_usage, tenki_get_workspace_settings, tenki_update_workspace_settings
-
-## [0.6.0] — 2026-07-20 — Custom runtimes — templates & registry
-
-Bring-your-own-runtime: define an environment once and boot into it warm. Templates add the platform's first async job surface (build, poll, cancel). The registry publishes versioned custom images with a private-by-default ACL surface. List paths live-verified.
-
-**Tools:** 9 template tools (create/get/list/update/delete + build/cancel-build/get-build/list-active-builds) + 9 registry tools (publish/get/list/set-visibility/delete/delete-version/resolve-ref/share/list-share-grants)
-
-## [0.5.0] — 2026-07-20 — Persistent state — snapshots & volumes
-
-Persistent state for the iterative agent loop. Snapshots checkpoint a known-good sandbox to branch or roll back from; volumes are durable disks that carry a cache or dataset across otherwise-ephemeral sandboxes. Destructive verbs are explicit-target-only. Snapshots live-verified; volume shapes verified against the SDK (write path blocked only by a workspace volume quota during testing).
-
-**Tools:** 8 snapshot tools + 8 volume tools (create/get/list/update/delete/resize/attach/detach)
-
-## [0.4.0] — 2026-07-20 — Preview URLs — the ship surface
-
-The ship surface: turn an exposed port into a public, shareable preview URL an agent can hand back. Project-scoped (live-verified: requires projectId + a validated slug). Completes the ports resource with unexpose.
-
-**Tools:** tenki_create_preview_url, tenki_open_preview, tenki_list_preview_urls, tenki_unexpose_port
-
-## [0.3.0] — 2026-07-20 — Session lifecycle & fleet control
-
-Extended session control: extend a sandbox's wall-clock lifetime, update mutable fields (name/tags/idle-timeout/max-duration), bulk-terminate (explicit-id-only, irreversible), an activity heartbeat, and workspace/project-scoped fleet listing. Live-verified.
-
-**Tools:** tenki_extend_sandbox, tenki_update_sandbox, tenki_terminate_sandboxes, tenki_report_sandbox_activity, tenki_list_workspace_sandboxes, tenki_list_project_sandboxes
-
-## [0.2.0] — 2026-07-20 — Filesystem completion (data plane)
-
-Data-plane filesystem metadata + mutation, completing the file surface beyond read/write/list: stat, mkdir (recursive), remove (recursive), and move (exec-backed mv, since the data plane exposes no Move RPC). Live-verified against api.tenki.cloud.
-
-**Tools:** tenki_stat_path, tenki_make_dir, tenki_remove_path, tenki_move_path
-
-## [0.1.0] — 2026-07-20
-Initial release. **15 MCP tools over stdio, live-verified against `api.tenki.cloud`.**
-
-- `tenki_whoami`
-- `tenki_run_code` — ephemeral sandbox: boot → run shell/python/javascript → terminate
-- Sandbox lifecycle: `tenki_create_sandbox`, `tenki_get_sandbox`, `tenki_list_sandboxes`, `tenki_terminate_sandbox`, `tenki_pause_sandbox`, `tenki_resume_sandbox`
-- `tenki_exec` — run a command in a sandbox (stdout/stderr/exit inline)
-- Files: `tenki_read_file`, `tenki_write_file`, `tenki_list_files`
-- `tenki_git`
-- Ports: `tenki_expose_port`, `tenki_list_exposed_ports`
-
-Dependency-free ConnectRPC client (control + data plane), ported from the live-verified [n8n node](https://github.com/opencolin/n8n-nodes-tenki). Tools organized into self-registering modules under `src/tools/`.
+- Dependency-free ConnectRPC client for the control and data planes; runtime dependencies are only `@modelcontextprotocol/sdk` and `zod`. Node ≥ 22.
+- Offline regression suites (security, transport input handling, exec output, network behavior — local stubs, zero external network) run in CI via `npm test`; live end-to-end suites in `test/run.mjs`.

package/README.md

@@ -20,8 +20,6 @@ npx -y @tenkicloud/mcp     # speaks MCP over stdio
 
 Nothing to clone or build. The package installs one command, `tenki-mcp`.
 
-> **Heads up — pending first npm publish.** Until `@tenkicloud/mcp` lands on npm, use [Run it from a clone](#run-it-from-a-clone-instead) below. Every `npx -y @tenkicloud/mcp` form here activates the moment it's published.
-
 ### Use it in Claude Code
 
 ```bash
@@ -111,7 +109,7 @@ Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` comman
 
 ## Tools
 
-**85 tools** — 84 with full parity to the Tenki unary API (enforced by a CI [parity audit](scripts/parity-audit.mjs)), plus `tenki_auth_status`. Grouped by domain:
+**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:
 
 | Domain | Tools |
 |---|---|
@@ -119,17 +117,16 @@ Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` comman
 | **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` |
-| **Session admin** | `tenki_extend_sandbox` · `tenki_update_sandbox` · `tenki_terminate_sandboxes` (bulk) · `tenki_report_sandbox_activity` · `tenki_list_workspace_sandboxes` · `tenki_list_project_sandboxes` |
+| **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 |
 | **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-project · list-workspace · list-dangling · update · delete · get-download-url |
-| **Volumes** | create · get · list · list-project · update · delete · resize · attach · detach |
-| **Templates** | create · get · list · list-project · update · delete · build · cancel-build · get-build · list-active-builds |
-| **Registry** (custom images) | publish · get · list · set-visibility · delete · resolve-ref · share · unshare · list-share-grants · revoke-share-grant |
+| **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` |
 
 Full per-release breakdown in [CHANGELOG.md](CHANGELOG.md).

package/dist/client.d.ts

@@ -21,6 +21,12 @@ export interface ExecResult {
     exitCode: number;
     ok: boolean;
     captureError?: string;
+    stdoutTruncated?: boolean;
+    stderrTruncated?: boolean;
+    /** Sandbox path holding the FULL stdout, present only when stdout was truncated. */
+    stdoutPath?: string;
+    /** Sandbox path holding the FULL stderr, present only when stderr was truncated. */
+    stderrPath?: string;
 }
 export interface TenkiClientOptions {
     /** Timeout for unary control/data-plane calls (default 30s). */
@@ -98,9 +104,10 @@ export declare class TenkiClient {
      */
     data(sessionId: string, method: string, request?: Record<string, unknown>): Promise<Record<string, any>>;
     /**
-     * Resolve the calling identity + a default workspace/project for CreateSession
-     * (which requires a projectId). Picks the first workspace that has a project so
-     * the (workspace, project) pair stays consistent.
+     * Resolve the calling identity + a default workspace for CreateSession and
+     * other workspace-scoped calls. (Projects were removed from the API — the
+     * proto reserves every project_id field and WhoAmI no longer lists projects —
+     * so there is nothing narrower than a workspace to resolve.)
      *
      * CreateSession validates owner_type ∈ {SERVICE, USER} and requires a
      * non-empty owner_id, but derives the real owner from the authenticated
@@ -112,7 +119,6 @@ export declare class TenkiClient {
         ownerType?: string;
         ownerId?: string;
         workspaceId?: string;
-        projectId?: string;
     }>;
     /** Poll GetSession until it reaches (or passes into) the target state. */
     waitForState(sessionId: string, target?: string, { timeoutMs, intervalMs }?: {
@@ -121,6 +127,15 @@ export declare class TenkiClient {
     }): Promise<Record<string, any>>;
     readTextFile(sessionId: string, path: string): Promise<string>;
     writeTextFile(sessionId: string, path: string, text: string): Promise<Record<string, any>>;
+    /**
+     * Read a capture file back, capping what crosses the wire. Stat first: a
+     * file at or under the cap is read whole; a larger one gets a server-side
+     * head+tail preview (assembled by `sh` in the sandbox, so the full body
+     * never leaves it — ReadFile has no range support). The preview file is the
+     * caller's to clean up (returned as previewPath); the ORIGINAL is theirs to
+     * keep, so the user can page through the full output afterwards.
+     */
+    private readCaptureFile;
     /**
      * Run a command in a session and return stdout/stderr inline.
      *
@@ -129,13 +144,16 @@ export declare class TenkiClient {
      * client. Capture-read failures degrade gracefully into `captureError` rather
      * than losing the run — but the result is marked NOT ok, because empty
      * stdout/stderr next to a zero exit code would otherwise read as a clean,
-     * silent success.
+     * silent success. Streams over maxOutputBytes come back truncated
+     * (head+tail) with the full capture file retained in the sandbox — see
+     * readCaptureFile; truncation does not affect `ok`.
      */
     execCaptured(sessionId: string, command: string, opts?: {
         args?: string[];
         cwd?: string;
         env?: Record<string, string>;
         timeoutSeconds?: number;
+        maxOutputBytes?: number;
     }): Promise<ExecResult>;
     /**
      * One-shot: boot a throwaway sandbox, run code (shell / python / javascript),

package/dist/client.js

@@ -71,6 +71,17 @@ const CRED_EXPIRY_SKEW_MS = 30_000;
 const MIN_CRED_TTL_MS = 5_000; // floor for the skewed expiry of a short-lived credential
 /** Home directory of the sandbox's `tenki` user; run-code scripts and capture files live here. */
 const SANDBOX_HOME = "/home/tenki";
+// Inline-output budget per stream (stdout / stderr), in bytes. Outputs at or
+// under the cap return whole; larger ones return a head+tail preview and the
+// full capture file is KEPT in the sandbox so the caller can page through it.
+// The cap exists for the consumer (an LLM context) and for this process: the
+// data plane's ReadFile has no range support, so the only alternative to a
+// server-side preview would be pulling the entire body over the wire.
+const DEFAULT_MAX_OUTPUT_BYTES = 65_536;
+const MIN_OUTPUT_BYTES = 1_024;
+// Head-heavy split: the start of a log names the command/failure context; the
+// tail carries the final error. 3:1 mirrors how people read build output.
+const TRUNCATE_HEAD_FRACTION = 0.75;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function safeJson(text) {
     try {
@@ -335,9 +346,10 @@ export class TenkiClient {
         }
     }
     /**
-     * Resolve the calling identity + a default workspace/project for CreateSession
-     * (which requires a projectId). Picks the first workspace that has a project so
-     * the (workspace, project) pair stays consistent.
+     * Resolve the calling identity + a default workspace for CreateSession and
+     * other workspace-scoped calls. (Projects were removed from the API — the
+     * proto reserves every project_id field and WhoAmI no longer lists projects —
+     * so there is nothing narrower than a workspace to resolve.)
      *
      * CreateSession validates owner_type ∈ {SERVICE, USER} and requires a
      * non-empty owner_id, but derives the real owner from the authenticated
@@ -348,8 +360,7 @@ export class TenkiClient {
     async resolveOwner() {
         const resp = await this.control("WhoAmI", {});
         const workspaces = Array.isArray(resp.workspaces) ? resp.workspaces : [];
-        const ws = workspaces.find((w) => Array.isArray(w?.projects) && w.projects.length > 0) ?? workspaces[0];
-        const proj = Array.isArray(ws?.projects) ? ws.projects[0] : undefined;
+        const ws = workspaces[0];
         let ownerType = resp.ownerType;
         let ownerId = resp.ownerId;
         // Substitute the placeholder only when WhoAmI returned a type CreateSession
@@ -363,7 +374,6 @@ export class TenkiClient {
             ownerType,
             ownerId,
             workspaceId: ws?.workspaceId ?? ws?.id,
-            projectId: proj?.projectId ?? proj?.id,
         };
     }
     /** Poll GetSession until it reaches (or passes into) the target state. */
@@ -393,6 +403,37 @@ export class TenkiClient {
         const content = Buffer.from(text, "utf8").toString("base64");
         return this.data(sessionId, "WriteFile", { path, content });
     }
+    /**
+     * Read a capture file back, capping what crosses the wire. Stat first: a
+     * file at or under the cap is read whole; a larger one gets a server-side
+     * head+tail preview (assembled by `sh` in the sandbox, so the full body
+     * never leaves it — ReadFile has no range support). The preview file is the
+     * caller's to clean up (returned as previewPath); the ORIGINAL is theirs to
+     * keep, so the user can page through the full output afterwards.
+     */
+    async readCaptureFile(sessionId, path, capBytes) {
+        // Stat is an optimization (skip pulling a body we'd mostly discard), not a
+        // gate: if it fails, fall back to the plain whole read — whose own failure
+        // still surfaces as captureError in the caller.
+        let size;
+        try {
+            const stat = await this.data(sessionId, "Stat", { path });
+            size = Number(stat.size ?? 0); // int64 arrives as a JSON string
+        }
+        catch {
+            size = undefined;
+        }
+        if (size === undefined || !Number.isFinite(size) || size <= capBytes) {
+            return { text: await this.readTextFile(sessionId, path), truncated: false };
+        }
+        const head = Math.floor(capBytes * TRUNCATE_HEAD_FRACTION);
+        const tail = capBytes - head;
+        const previewPath = `${path}.preview`;
+        const marker = `\n[... output truncated: ${size} bytes total, showing the first ${head} and last ${tail}. Full output kept in the sandbox at ${path} ...]\n`;
+        const script = `{ head -c ${head} ${shellQuote(path)}; printf %s ${shellQuote(marker)}; tail -c ${tail} ${shellQuote(path)}; } > ${shellQuote(previewPath)}`;
+        await this.control("ExecuteCommand", { sessionId, command: "sh", args: ["-c", script] });
+        return { text: await this.readTextFile(sessionId, previewPath), truncated: true, previewPath };
+    }
     /**
      * Run a command in a session and return stdout/stderr inline.
      *
@@ -401,7 +442,9 @@ export class TenkiClient {
      * client. Capture-read failures degrade gracefully into `captureError` rather
      * than losing the run — but the result is marked NOT ok, because empty
      * stdout/stderr next to a zero exit code would otherwise read as a clean,
-     * silent success.
+     * silent success. Streams over maxOutputBytes come back truncated
+     * (head+tail) with the full capture file retained in the sandbox — see
+     * readCaptureFile; truncation does not affect `ok`.
      */
     async execCaptured(sessionId, command, opts = {}) {
         const suffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -428,18 +471,39 @@ export class TenkiClient {
         // unparseable code to -1 so the user still gets their stdout/stderr.
         const rawExit = typeof execution.exitCode === "number" ? execution.exitCode : Number(execution.exitCode ?? 0);
         const exitCode = Number.isFinite(rawExit) ? Math.trunc(rawExit) : -1;
+        const cap = Math.max(MIN_OUTPUT_BYTES, Math.floor(opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES));
         let stdout = "";
         let stderr = "";
         let captureError;
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        // Truncated originals are KEPT (their path is returned) so the caller can
+        // page through them; everything else — untruncated captures, previews — is
+        // removed.
+        const toRemove = [];
         try {
-            stdout = await this.readTextFile(sessionId, outPath);
-            stderr = await this.readTextFile(sessionId, errPath);
+            const [out, err] = await Promise.all([
+                this.readCaptureFile(sessionId, outPath, cap),
+                this.readCaptureFile(sessionId, errPath, cap),
+            ]);
+            stdout = out.text;
+            stderr = err.text;
+            stdoutTruncated = out.truncated;
+            stderrTruncated = err.truncated;
+            if (out.previewPath)
+                toRemove.push(out.previewPath);
+            if (err.previewPath)
+                toRemove.push(err.previewPath);
         }
         catch (e) {
             captureError = e.message;
         }
+        if (!stdoutTruncated)
+            toRemove.push(outPath);
+        if (!stderrTruncated)
+            toRemove.push(errPath);
         try {
-            await this.control("ExecuteCommand", { sessionId, command: "rm", args: ["-f", outPath, errPath] });
+            await this.control("ExecuteCommand", { sessionId, command: "rm", args: ["-f", ...toRemove] });
         }
         catch {
             // Session may have gone away; capture files die with it.
@@ -452,6 +516,8 @@ export class TenkiClient {
             exitCode,
             ok: exitCode === 0 && !captureError,
             ...(captureError ? { captureError } : {}),
+            ...(stdoutTruncated ? { stdoutTruncated: true, stdoutPath: outPath } : {}),
+            ...(stderrTruncated ? { stderrTruncated: true, stderrPath: errPath } : {}),
         };
     }
     /**
@@ -469,7 +535,6 @@ export class TenkiClient {
             ...(owner.ownerType ? { ownerType: owner.ownerType } : {}),
             ...(owner.ownerId ? { ownerId: owner.ownerId } : {}),
             ...(owner.workspaceId ? { workspaceId: owner.workspaceId } : {}),
-            ...(owner.projectId ? { projectId: owner.projectId } : {}),
             ...(opts.env && Object.keys(opts.env).length ? { env: opts.env } : {}),
         });
         const session = create.session ?? create;

package/dist/index.js

@@ -26,7 +26,7 @@ const token = process.env.TENKI_AUTH_TOKEN || process.env.TENKI_API_KEY;
 if (!token) {
     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 tenki-mcp");
+        "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;
 /** Positive integer from env, or undefined so the client keeps its own default. */

package/dist/server.d.ts

@@ -14,7 +14,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "./client.js";
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 type Cls = "read" | "write" | "destructive";
 export declare function classifyTool(name: string): Cls;
 /**
@@ -24,7 +24,7 @@ export declare function classifyTool(name: string): Cls;
  * start — which MCP clients report as an opaque "server failed to start" —
  * the server boots with ONLY tenki_auth_status registered, so an agent can
  * discover and explain the missing credential. Registering the other tools in
- * that state would offer 84 tools that can only fail.
+ * that state would offer 70 tools that can only fail.
  */
 export declare function createServer(client: TenkiClient | null): McpServer;
 export {};

package/dist/server.js

@@ -26,12 +26,11 @@ import { registerPreviews } from "./tools/previews.js";
 import { registerSnapshots } from "./tools/snapshots.js";
 import { registerVolumes } from "./tools/volumes.js";
 import { registerTemplates } from "./tools/templates.js";
-import { registerRegistry } from "./tools/registry.js";
 import { registerWorkspace } from "./tools/workspace.js";
 import { registerArtifacts } from "./tools/artifacts.js";
 import { registerSsh } from "./tools/ssh.js";
 import { registerAuthStatus } from "./tools/auth_status.js";
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 const modules = [
     registerIdentity,
     registerRun,
@@ -46,7 +45,6 @@ const modules = [
     registerSnapshots,
     registerVolumes,
     registerTemplates,
-    registerRegistry,
     registerWorkspace,
     registerArtifacts,
     registerSsh,
@@ -181,7 +179,7 @@ function guard(server, opts) {
  * start — which MCP clients report as an opaque "server failed to start" —
  * the server boots with ONLY tenki_auth_status registered, so an agent can
  * discover and explain the missing credential. Registering the other tools in
- * that state would offer 84 tools that can only fail.
+ * that state would offer 70 tools that can only fail.
  */
 export function createServer(client) {
     const server = new McpServer({ name: "tenki", version: VERSION });

package/dist/tools/auth_status.js

@@ -19,7 +19,7 @@ export function describeCredential(env = process.env) {
     return { kind: "session_cookie", source };
 }
 const CREDENTIAL_HELP = {
-    none: "No credential found. Set TENKI_API_KEY (a tk_… API key) or TENKI_AUTH_TOKEN (an ory_st_… session token) in the server's environment, then restart it — MCP clients pass env through their server config, e.g. `claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y tenki-mcp`, or the \"env\" block in claude_desktop_config.json / .cursor/mcp.json.",
+    none: "No credential found. Set TENKI_API_KEY (a tk_… API key) or TENKI_AUTH_TOKEN (an ory_st_… session token) in the server's environment, then restart it — MCP clients pass env through their server config, e.g. `claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y @tenkicloud/mcp`, or the \"env\" block in claude_desktop_config.json / .cursor/mcp.json.",
     api_key: "Authenticated with a tk_… API key (Authorization: Bearer).",
     oauth_session_token: "Authenticated with an ory_st_… session token (X-Session-Token). Session tokens expire; an API key is the stabler choice for a long-running server.",
     session_cookie: "Authenticated with a session cookie (the token matched neither the tk_ nor ory_st_ prefix, so it is sent as a tenki_session cookie). If that is not what you intended, check the value.",

package/dist/tools/common.d.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+/** Keep registry-backed implementation fields out of public MCP responses. */
+export declare function publicValue(value: unknown): unknown;
 /** Serialize any tool return value as MCP text content. */
 export declare const ok: (value: unknown) => {
     content: {
@@ -21,7 +23,7 @@ export declare const portSchema: z.ZodNumber;
  * leading/trailing whitespace is legal in POSIX filenames, and zod's .trim()
  * (a transform, not a check) would silently retarget the operation to a
  * different file. Call sites override the description with their own examples. */
-export declare const pathSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const pathSchema: z.ZodString;
 /**
  * Preview-slug schema, matching the server's validatePreviewSlug: 3-63 chars,
  * lowercase/digits/hyphens, no leading/trailing hyphen. ExposePort routes a