@luxorai/mcp 0.0.0-stage → 0.3.1

package/dist/tools/files_ops.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema } from "./common.js";
+/**
+ * Filesystem metadata + mutation ops against a sandbox's data plane.
+ *
+ * Extends the basic read/write/list coverage in `files.ts` with `stat`, `mkdir`,
+ * `remove`, and `move`. Stat/Mkdir/Remove are genuine unary data-plane RPCs
+ * (`SandboxSessionDataPlaneService`). The data plane exposes no `Move` method, so
+ * `tenki_move_path` is exec-backed (`mv`) — matching the live-verified n8n node.
+ * Paths are rooted at /home/tenki (the server enforces the sandbox root).
+ */
+export function registerFilesOps(server, client) {
+    server.tool("tenki_stat_path", "Get metadata (size, mode, type, timestamps) for a file or directory in a sandbox. Use to check whether a path exists or inspect it before reading/removing.", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Absolute path under /home/tenki, e.g. /home/tenki/output.txt"),
+    }, async ({ session_id, path }) => ok(await client.data(session_id, "Stat", { path })));
+    server.tool("tenki_make_dir", "Create a directory in a sandbox. Set recursive to also create any missing parent directories (mkdir -p).", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Directory path under /home/tenki, e.g. /home/tenki/project/out"),
+        recursive: z.boolean().optional().describe("Create parent directories as needed (default false)."),
+    }, async ({ session_id, path, recursive }) => ok(await client.data(session_id, "Mkdir", {
+        path,
+        ...(recursive ? { recursive: true } : {}),
+    })));
+    server.tool("tenki_remove_path", "Delete a file or directory in a sandbox. Set recursive to remove a non-empty directory and its contents (rm -r).", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Path to delete under /home/tenki."),
+        recursive: z.boolean().optional().describe("Remove a directory and its contents (default false)."),
+    }, async ({ session_id, path, recursive }) => ok(await client.data(session_id, "Remove", {
+        path,
+        ...(recursive ? { recursive: true } : {}),
+    })));
+    server.tool("tenki_move_path", "Move or rename a file or directory within a sandbox. Both paths are under /home/tenki.", {
+        session_id: sessionIdSchema,
+        from: pathSchema.describe("Source path under /home/tenki, e.g. /home/tenki/old.txt"),
+        to: pathSchema.describe("Destination path under /home/tenki, e.g. /home/tenki/new.txt"),
+    }, async ({ session_id, from, to }) => {
+        // The data plane has no Move RPC (ReadFile/WriteFile/Stat/Mkdir/Remove/List only),
+        // so relocate with an exec-backed `mv`, mirroring the live-verified n8n node.
+        // `ok` keys off the exit code, NOT result.ok: the capture files are an
+        // internal detail here — whether mv's (empty) output could be read back
+        // says nothing about whether the file moved.
+        // `--` so a path beginning with a hyphen is an operand, not an mv option.
+        const result = await client.execCaptured(session_id, "mv", { args: ["--", from, to] });
+        return ok({
+            from,
+            to,
+            ok: result.exitCode === 0,
+            exitCode: result.exitCode,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+            ...(result.captureError ? { captureError: result.captureError } : {}),
+        });
+    });
+}

package/dist/tools/git.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Git operations inside a sandbox (one RPC dispatched by operation string). */
+export declare function registerGit(server: McpServer, client: TenkiClient): void;

package/dist/tools/git.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+/**
+ * The API validates `operation` against exactly this list (GitOperationRequest's
+ * buf.validate `in` constraint) and the engine implements exactly these four —
+ * anything else (status/add/commit/push/...) is rejected server-side. For other
+ * git commands, run `git ...` via tenki_exec.
+ */
+const GIT_OPERATIONS = ["clone", "checkout", "diff", "log"];
+/** Git operations inside a sandbox (one RPC dispatched by operation string). */
+export function registerGit(server, client) {
+    server.tool("tenki_git", "Run a git operation in a sandbox. Only clone, checkout, diff, and log are supported by the API — for any other git command (status, add, commit, push, ...) use tenki_exec with `git ...`. " +
+        "clone arg keys: repo (required, the URL), branch?, depth?, directory?. " +
+        "CAVEAT (live-verified): checkout/diff/log run in the session's working directory (/home/tenki), which is not a repository and has no directory arg — so on a repo cloned into a subdirectory they fail with 'not a git repository'. Use tenki_exec with `git -C <directory> ...` instead (e.g. `git -C /home/tenki/hw log -n 2`). " +
+        "For reference, their arg keys are — checkout: ref (required), create? ('true' = -b); diff: range? or base?+head?, path?; log: max_count?, range?, path?.", {
+        session_id: sessionIdSchema,
+        operation: z.enum(GIT_OPERATIONS).describe("One of: clone, checkout, diff, log (the API rejects anything else)."),
+        // The wire type is map<string,string>, but the values models most want
+        // to send as numbers or booleans (depth, max_count, create) are
+        // accepted here and coerced — a client-side rejection of `create: true`
+        // for a call that would serialize identically helps nobody.
+        args: z
+            .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+            .optional()
+            .describe("Operation args as a key→value object (values are sent as strings; numbers/booleans are coerced). clone: {repo, branch?, depth?, directory?}; checkout: {ref, create?: 'true'}; diff: {range?} or {base?, head?}, {path?}; log: {max_count?, range?, path?}."),
+    }, async ({ session_id, operation, args }) => {
+        const stringArgs = args ? Object.fromEntries(Object.entries(args).map(([k, v]) => [k, String(v)])) : undefined;
+        return ok(await client.control("GitOperation", { sessionId: session_id, operation, ...(stringArgs ? { args: stringArgs } : {}) }));
+    });
+}

package/dist/tools/identity.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Identity / credential tools. */
+export declare function registerIdentity(server: McpServer, client: TenkiClient): void;

package/dist/tools/identity.js

@@ -0,0 +1,5 @@
+import { ok } from "./common.js";
+/** Identity / credential tools. */
+export function registerIdentity(server, client) {
+    server.tool("tenki_whoami", "Return the identity and workspaces for the current API key. Cheap credential test.", {}, async () => ok(await client.control("WhoAmI", {})));
+}

package/dist/tools/ports.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Port exposure / preview URLs. */
+export declare function registerPorts(server: McpServer, client: TenkiClient): void;

package/dist/tools/ports.js

@@ -0,0 +1,6 @@
+import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
+/** Port exposure / preview URLs. */
+export function registerPorts(server, client) {
+    server.tool("tenki_expose_port", "Expose a port from a sandbox and get a public preview URL. Useful when an agent starts a web server it wants to show.", { session_id: sessionIdSchema, port: portSchema, slug: slugSchema.optional() }, async ({ session_id, port, slug }) => ok(await client.control("ExposePort", { sessionId: session_id, port, ...(slug ? { slug } : {}) })));
+    server.tool("tenki_list_exposed_ports", "List the ports currently exposed from a sandbox.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("ListExposedPorts", { sessionId: session_id })));
+}

package/dist/tools/previews.d.ts

@@ -0,0 +1,18 @@
+/**
+ * previews.ts — port preview-URL tools for tenki-mcp.
+ *
+ * Covers the preview / exposure-teardown half of Tenki's Port resource:
+ * removing an inbound exposure (UnexposePort) and the preview-URL lifecycle
+ * (CreatePreviewUrl, OpenPreview, ListPreviewUrls). Port *exposure* itself
+ * (ExposePort / ListExposedPorts) lives in ports.ts and is not re-implemented here.
+ *
+ * All control-plane ConnectRPC calls on tenki.sandbox.v1.SandboxService.
+ *
+ * LIVE-VERIFIED shapes (2026-08-21): projects were REMOVED from the API (every
+ * project_id field is proto-reserved and unknown fields are silently discarded),
+ * so the preview-URL methods are workspace/id-scoped. CreatePreviewUrl requires
+ * a `slug` (>=3 chars, [a-z0-9-]).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerPreviews(server: McpServer, client: TenkiClient): void;

package/dist/tools/previews.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
+export function registerPreviews(server, client) {
+    // ── Unexpose a port (tear down its exposure + preview) ────────────────────────
+    server.tool("tenki_unexpose_port", "Remove an inbound port exposure from a sandbox, taking its public URL/preview offline. Use this to un-publish a port previously exposed with tenki_expose_port.", {
+        session_id: sessionIdSchema.describe("The sandbox session whose port to unexpose."),
+        port: portSchema.describe("The TCP port inside the sandbox to unexpose (1-65535)."),
+    }, async ({ session_id, port }) => ok(await client.control("UnexposePort", { sessionId: session_id, port })));
+    // ── Create a shareable preview URL for a port ─────────────────────────────────
+    server.tool("tenki_create_preview_url", "Create a shareable public preview URL for a port in a sandbox. The sandbox must have inbound networking enabled (create it with allow_inbound).", {
+        session_id: sessionIdSchema.describe("The sandbox session serving the port."),
+        port: portSchema.describe("The TCP port inside the sandbox to create a preview URL for (1-65535)."),
+        slug: slugSchema,
+        expires_at: z
+            .string()
+            .optional()
+            .describe("Optional RFC-3339 timestamp at which the preview URL auto-expires. Omit to keep it until the sandbox ends."),
+    }, async ({ session_id, port, slug, expires_at }) => ok(await client.control("CreatePreviewUrl", {
+        sessionId: session_id,
+        port,
+        slug,
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
+    // ── Open (get) a live preview for a port ──────────────────────────────────────
+    server.tool("tenki_open_preview", "Open a viewer-token-gated (AUTHENTICATED-mode) preview. USE tenki_expose_port OR tenki_create_preview_url INSTEAD for an ordinary web server: for any port other than the web terminal (7681) the API deliberately returns a non-regional fallback host that currently has no edge route, so the URL 404s (live-verified). The returned viewerToken does resolve via tenki_resolve_preview_token; only the URL is unreachable. Requires allow_inbound.", {
+        session_id: sessionIdSchema.describe("The sandbox session serving the port."),
+        port: portSchema.describe("The TCP port inside the sandbox to open a preview for (1-65535)."),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("Optional RFC-3339 timestamp at which the preview auto-expires. Omit to keep it until the sandbox ends."),
+    }, async ({ session_id, port, expires_at }) => ok(await client.control("OpenPreview", {
+        sessionId: session_id,
+        port,
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
+    // ── List the preview URLs bound to a sandbox / project ────────────────────────
+    server.tool("tenki_list_preview_urls", "List the workspace's preview URLs, newest page first. Pass session_id to keep only the ones bound to that sandbox (filtered here, not server-side — so it applies to the page you fetched; raise page_size or follow next_page_token to widen it). Results are paginated: a nextPageToken in the response means more pages exist.", {
+        session_id: sessionIdSchema
+            .optional()
+            .describe("Keep only preview URLs bound to this sandbox. Applied client-side to the fetched page."),
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        page_size: z.number().int().min(1).max(100).optional().describe("Rows per page (server default 20, max 100)."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ session_id, workspace_id, page_size, page_token }) => {
+        // The RPC has no sessionId field (ListPreviewUrlsRequest: workspace_id,
+        // page_size, page_token), so a sessionId sent
+        // on the wire is silently discarded and every session's rows come back.
+        // Filter here instead of advertising a filter that does nothing.
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        const resp = await client.control("ListPreviewUrls", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(page_size !== undefined ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        });
+        const rows = Array.isArray(resp.previewUrls) ? resp.previewUrls : [];
+        const filtered = session_id ? rows.filter((r) => r?.sessionId === session_id) : rows;
+        return ok({
+            previewUrls: filtered,
+            ...(resp.nextPageToken ? { nextPageToken: resp.nextPageToken } : {}),
+            ...(session_id ? { filteredClientSide: true, fetchedOnThisPage: rows.length } : {}),
+        });
+    });
+    // ── Get / delete a specific preview URL ───────────────────────────────────────
+    server.tool("tenki_get_preview_url", "Fetch a specific preview URL's details by id.", { preview_url_id: z.string().describe("The preview URL id.") }, async ({ preview_url_id }) => ok(await client.control("GetPreviewUrl", { previewUrlId: preview_url_id })));
+    server.tool("tenki_delete_preview_url", "Delete a preview URL by id, taking it permanently offline.", { preview_url_id: z.string().describe("The preview URL id to delete.") }, async ({ preview_url_id }) => ok(await client.control("DeletePreviewUrl", { previewUrlId: preview_url_id })));
+    // ── Touch (keep-alive) a preview ──────────────────────────────────────────────
+    server.tool("tenki_touch_preview", "Refresh (keep-alive) a live preview by its preview token so it isn't torn down as idle.", { preview_token: z.string().describe("The preview token (from create_preview_url / open_preview).") }, 
+    // TouchPreview takes a previewToken, not session/port (live-verified).
+    async ({ preview_token }) => ok(await client.control("TouchPreview", { previewToken: preview_token })));
+    // ── Bind / unbind a named preview URL to a session+port ───────────────────────
+    // Advanced routing primitives (shapes SDK-name-verified; not exercised end-to-end here).
+    server.tool("tenki_bind_preview_url", "Bind a named preview URL to a sandbox session and port (advanced routing).", {
+        preview_url_id: z.string().describe("The preview URL id to bind."),
+        session_id: sessionIdSchema,
+        port: portSchema.describe("The port to route the preview URL to."),
+    }, async ({ preview_url_id, session_id, port }) => ok(await client.control("BindPreviewUrl", { previewUrlId: preview_url_id, sessionId: session_id, port })));
+    server.tool("tenki_unbind_preview_url", "Unbind a named preview URL from its current session/port (advanced routing).", { preview_url_id: z.string().describe("The preview URL id to unbind.") }, async ({ preview_url_id }) => ok(await client.control("UnbindPreviewUrl", { previewUrlId: preview_url_id })));
+    server.tool("tenki_resolve_preview_token", "Resolve a preview token to the sandbox/port it points at (advanced).", { token: z.string().describe("The preview token to resolve.") }, async ({ token }) => ok(await client.control("ResolvePreviewToken", { token })));
+}

package/dist/tools/run.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** The headline one-shot execution tool. */
+export declare function registerRun(server: McpServer, client: TenkiClient): void;

package/dist/tools/run.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { ok, envSchema } from "./common.js";
+/** The headline one-shot execution tool. */
+export function registerRun(server, client) {
+    server.tool("tenki_run_code", "Boot a throwaway microVM, run a snippet (shell/python/javascript), return its stdout/stderr/exit code, and tear the sandbox down. Cost-guarded and self-terminating. Use this for one-shot execution when you don't need a persistent sandbox. Output over ~64KB per stream is truncated head+tail — and the sandbox is gone, so for large output use tenki_create_sandbox + tenki_exec and page through the retained file.", {
+        language: z.enum(["shell", "python", "javascript"]).describe("Interpreter for the snippet."),
+        code: z.string().describe("The code to run."),
+        env: envSchema,
+        timeout_seconds: z.number().int().positive().optional().describe("Max seconds for the run (default 30)."),
+    }, async ({ language, code, env, timeout_seconds }) => ok(await client.runCode(language, code, { env, timeoutSeconds: timeout_seconds })));
+}

package/dist/tools/sandboxes.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Sandbox (session) lifecycle. */
+export declare function registerSandboxes(server: McpServer, client: TenkiClient): void;

package/dist/tools/sandboxes.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { ok, envSchema, sessionIdSchema } from "./common.js";
+/** Sandbox (session) lifecycle. */
+export function registerSandboxes(server, client) {
+    server.registerTool("tenki_create_sandbox", {
+        description: "Create a persistent sandbox microVM, optionally from a snapshot or template image. Returns the session (id, state) and its data-plane endpoint. Boots in ~2s. Use tenki_exec / tenki_read_file / tenki_write_file against the returned session_id.",
+        inputSchema: z
+            .object({
+            name: z.string().optional().describe("Human-readable name."),
+            cpu_cores: z.number().int().min(1).max(16).optional().describe("vCPUs (default 2)."),
+            memory_mb: z.number().int().min(128).max(65536).optional().describe("Memory in MB (default 4096)."),
+            disk_size_gb: z.number().int().positive().optional().describe("Disk in GB (default 5)."),
+            max_duration_seconds: z.number().int().positive().optional().describe("Hard lifetime cap in seconds."),
+            idle_timeout_minutes: z.number().int().positive().optional().describe("Reap after N idle minutes."),
+            clone_repo_url: z.string().optional().describe("Git URL to clone into the sandbox on boot."),
+            allow_outbound: z.boolean().optional().describe("Allow outbound networking (off by default)."),
+            allow_inbound: z.boolean().optional().describe("Allow inbound networking (off by default)."),
+            snapshot_id: z.string().optional().describe("Boot from a snapshot."),
+            image: z
+                .string()
+                .optional()
+                .describe("Boot from a template image, passed as a reference STRING: the imageDigestRef of a READY build from tenki_build_template / tenki_get_template_build (e.g. 'ws/name@sha256:...'), or 'workspace/name' for its latest version."),
+            tags: z.array(z.string()).optional().describe("Tags for later filtering."),
+            workspace_id: z.string().optional().describe("Workspace to create in (defaults to the key's first workspace)."),
+            env: envSchema,
+            wait_ready: z.boolean().optional().describe("Poll until the sandbox is RUNNING before returning (default true)."),
+        })
+            .strict(),
+    }, async (a) => {
+        const owner = await client.resolveOwner();
+        const workspaceId = a.workspace_id ?? owner.workspaceId;
+        const body = {
+            ...(owner.ownerType ? { ownerType: owner.ownerType } : {}),
+            ...(owner.ownerId ? { ownerId: owner.ownerId } : {}),
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(a.name ? { name: a.name } : {}),
+            ...(a.cpu_cores ? { cpuCores: a.cpu_cores } : {}),
+            ...(a.memory_mb ? { memoryMb: a.memory_mb } : {}),
+            ...(a.disk_size_gb ? { diskSizeGb: a.disk_size_gb } : {}),
+            ...(a.max_duration_seconds ? { maxDuration: `${a.max_duration_seconds}s` } : {}),
+            ...(a.idle_timeout_minutes ? { idleTimeoutMinutes: a.idle_timeout_minutes } : {}),
+            ...(a.clone_repo_url ? { cloneRepoUrl: a.clone_repo_url } : {}),
+            ...(a.allow_outbound ? { allowOutbound: true } : {}),
+            ...(a.allow_inbound ? { allowInbound: true } : {}),
+            ...(a.snapshot_id ? { snapshotId: a.snapshot_id } : {}),
+            // The API still uses registryRef internally for template-image launches.
+            ...(a.image ? { registryRef: a.image } : {}),
+            ...(a.tags && a.tags.length ? { tags: a.tags } : {}),
+            ...(a.env && Object.keys(a.env).length ? { env: a.env } : {}),
+        };
+        const resp = await client.control("CreateSession", body);
+        const session = resp.session ?? resp;
+        const sessionId = session.id ?? resp.sessionId;
+        const dataPlaneEndpoint = resp.dataPlaneEndpoint ?? resp.data_plane_endpoint;
+        const wait = a.wait_ready !== false;
+        const finalSession = wait && sessionId ? await client.waitForState(sessionId, "RUNNING") : session;
+        return ok({ session: finalSession, dataPlaneEndpoint });
+    });
+    server.tool("tenki_get_sandbox", "Fetch a sandbox's current state and metadata.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("GetSession", { sessionId: session_id })));
+    server.tool("tenki_list_sandboxes", "List sandboxes for the workspace.", {
+        include_terminated: z.boolean().optional().describe("Include terminated sandboxes (default false)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ include_terminated, page_size, page_token }) => ok(await client.control("ListSessions", {
+        ...(include_terminated ? { includeTerminated: true } : {}),
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_terminate_sandbox", "Terminate (destroy) a sandbox. The microVM and its filesystem are gone after this.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("TerminateSession", { sessionId: session_id })));
+    server.tool("tenki_pause_sandbox", "Pause a sandbox (snapshot + suspend) so it can be resumed later.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("PauseSession", { sessionId: session_id })));
+    server.tool("tenki_resume_sandbox", "Resume a previously paused sandbox.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("ResumeSession", { sessionId: session_id })));
+}

package/dist/tools/sessions_admin.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Extended sandbox (session) admin ops on the control plane: wall-clock lifetime
+ * extension, mutable-field updates, bulk termination, activity heartbeats, and
+ * workspace-scoped listing. The lifecycle basics
+ * (create/get/list/terminate/pause/resume) live in sandboxes.ts.
+ */
+export declare function registerSessionsAdmin(server: McpServer, client: TenkiClient): void;

package/dist/tools/sessions_admin.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+/**
+ * Extended sandbox (session) admin ops on the control plane: wall-clock lifetime
+ * extension, mutable-field updates, bulk termination, activity heartbeats, and
+ * workspace-scoped listing. The lifecycle basics
+ * (create/get/list/terminate/pause/resume) live in sandboxes.ts.
+ */
+export function registerSessionsAdmin(server, client) {
+    server.tool("tenki_extend_sandbox", "Extend a running sandbox's wall-clock lifetime by N seconds so it isn't auto-terminated at its max-duration cap.", {
+        session_id: sessionIdSchema.describe("The sandbox/session ID to extend."),
+        additional_duration_seconds: z
+            .number()
+            .int()
+            .positive()
+            .describe("Extra lifetime to add, in seconds (sent as a Duration string, e.g. 3600s)."),
+    }, async ({ session_id, additional_duration_seconds }) => ok(await client.control("ExtendSession", {
+        sessionId: session_id,
+        additionalDuration: `${additional_duration_seconds}s`,
+    })));
+    server.tool("tenki_update_sandbox", "Update mutable fields on an existing sandbox — its name, tags, idle timeout, or max duration.", {
+        session_id: sessionIdSchema.describe("The sandbox/session ID to update."),
+        name: z.string().optional().describe("New human-readable name."),
+        tags: z.array(z.string()).optional().describe("Replacement tag list (send [] to clear all tags)."),
+        idle_timeout_minutes: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Auto-pause after this many idle minutes (cost-safety cap)."),
+        max_duration_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("New hard lifetime cap in seconds (sent as a Duration string, e.g. 3600s)."),
+    }, async ({ session_id, name, tags, idle_timeout_minutes, max_duration_seconds }) => ok(await client.control("UpdateSession", {
+        sessionId: session_id,
+        ...(name !== undefined ? { name } : {}),
+        ...(tags !== undefined ? { tags } : {}),
+        ...(idle_timeout_minutes !== undefined ? { idleTimeoutMinutes: idle_timeout_minutes } : {}),
+        ...(max_duration_seconds !== undefined ? { maxDuration: `${max_duration_seconds}s` } : {}),
+    })));
+    server.tool("tenki_terminate_sandboxes", "Terminate MULTIPLE sandboxes in one call (bulk). IRREVERSIBLE — every listed sandbox and its filesystem is destroyed. Use tenki_terminate_sandbox for a single one.", {
+        session_ids: z.array(sessionIdSchema).min(1).describe("The sandbox/session IDs to terminate."),
+    }, async ({ session_ids }) => ok(await client.control("TerminateSessions", { sessionIds: session_ids })));
+    server.tool("tenki_report_sandbox_activity", "Report client-side activity on a sandbox to reset its idle timer and keep it from being reaped as idle (a keep-alive heartbeat).", { session_id: sessionIdSchema.describe("The sandbox/session ID to mark as active.") }, async ({ session_id }) => ok(await client.control("ReportSessionActivity", { sessionId: session_id })));
+    server.tool("tenki_list_workspace_sandboxes", "List every sandbox belonging to a specific workspace (defaults to the API key's workspace) — useful for spotting leaked, still-billing sandboxes across the workspace.", {
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        include_terminated: z.boolean().optional().describe("Include terminated sandboxes (default false)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ workspace_id, include_terminated, page_size, page_token }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListWorkspaceSandboxes", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(include_terminated ? { includeTerminated: true } : {}),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+}

package/dist/tools/snapshots.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Snapshots — capture a sandbox's disk + memory as a reusable image.
+ *
+ * Restoring is deliberately NOT a tool here: booting a fresh sandbox from a
+ * snapshot is `tenki_create_sandbox` with `snapshot_id` (CreateSession under the
+ * hood). Attached volumes are NOT captured in a snapshot and must be re-attached
+ * to the restored session separately.
+ */
+export declare function registerSnapshots(server: McpServer, client: TenkiClient): void;

package/dist/tools/snapshots.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+/**
+ * Snapshots — capture a sandbox's disk + memory as a reusable image.
+ *
+ * Restoring is deliberately NOT a tool here: booting a fresh sandbox from a
+ * snapshot is `tenki_create_sandbox` with `snapshot_id` (CreateSession under the
+ * hood). Attached volumes are NOT captured in a snapshot and must be re-attached
+ * to the restored session separately.
+ */
+export function registerSnapshots(server, client) {
+    server.tool("tenki_create_snapshot", "Capture a running sandbox's disk and memory as a reusable snapshot (attached volumes are NOT captured); boot a new sandbox from it later with tenki_create_sandbox + snapshot_id.", {
+        session_id: sessionIdSchema.describe("The sandbox session to snapshot."),
+        name: z.string().optional().describe("Human-readable name for the snapshot."),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("RFC-3339 / ISO-8601 timestamp at which the snapshot is auto-deleted. Omit to keep indefinitely."),
+        store_raw_image: z
+            .boolean()
+            .optional()
+            .describe("Also store the raw disk image alongside the snapshot (needed to download it later)."),
+    }, async ({ session_id, name, expires_at, store_raw_image }) => ok(await client.control("CreateSnapshot", {
+        sessionId: session_id,
+        ...(name ? { name } : {}),
+        ...(expires_at ? { expiresAt: expires_at } : {}),
+        ...(store_raw_image !== undefined ? { storeRawImage: store_raw_image } : {}),
+    })));
+    server.tool("tenki_get_snapshot", "Fetch one snapshot's status and metadata by ID.", { snapshot_id: z.string() }, async ({ snapshot_id }) => ok(await client.control("GetSnapshot", { snapshotId: snapshot_id })));
+    server.tool("tenki_list_snapshots", "List the saved snapshots for the workspace (owner inferred from the API key).", {
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ page_size, page_token }) => ok(await client.control("ListSnapshots", {
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_list_session_snapshots", "List the snapshots captured from a specific sandbox session.", {
+        session_id: sessionIdSchema,
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ session_id, page_size, page_token }) => ok(await client.control("ListSessionSnapshots", {
+        sessionId: session_id,
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_list_dangling_snapshots", "List dangling snapshots — those whose source session no longer exists — for the workspace, useful for cleanup.", {
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ page_size, page_token }) => ok(await client.control("ListDanglingSnapshots", {
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_update_snapshot", "Update a snapshot's mutable metadata (name and/or expiry).", {
+        snapshot_id: z.string(),
+        name: z.string().optional().describe("New human-readable name."),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("New RFC-3339 / ISO-8601 auto-delete timestamp."),
+    }, async ({ snapshot_id, name, expires_at }) => ok(await client.control("UpdateSnapshot", {
+        snapshotId: snapshot_id,
+        ...(name !== undefined ? { name } : {}),
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
+    server.tool("tenki_delete_snapshot", "Permanently delete a snapshot by ID.", { snapshot_id: z.string() }, async ({ snapshot_id }) => ok(await client.control("DeleteSnapshot", { snapshotId: snapshot_id })));
+    server.tool("tenki_get_snapshot_download_url", "Get a short-lived, pre-signed URL to download a snapshot's raw disk image (requires the snapshot to have been created with store_raw_image).", { snapshot_id: z.string() }, async ({ snapshot_id }) => ok(await client.control("GetSnapshotDownloadURL", { snapshotId: snapshot_id })));
+    server.tool("tenki_list_workspace_snapshots", "List all snapshots in a workspace (defaults to the key's first workspace). Supports pagination.", {
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ workspace_id, page_size, page_token }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListWorkspaceSnapshots", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+}

package/dist/tools/ssh.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ssh.ts — SSH access tools for tenki-mcp.
+ *
+ * UpdateSSHAuthorizedKeys sets the authorized_keys on a running sandbox (on
+ * SandboxService). IssueSandboxSSHCert and ListActiveSSHGateways live on a
+ * SEPARATE ConnectRPC service (SSHGatewayClientService), reached by passing the
+ * service path to client.control.
+ *
+ * Request shapes are grounded in the published Tenki API surface (CreateSession's
+ * ssh_authorized_keys field → sshAuthorizedKeys). The cert-issuance and gateway
+ * shapes are SDK-name-verified but not exercised end-to-end here.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerSsh(server: McpServer, client: TenkiClient): void;

package/dist/tools/ssh.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+const SSH_GATEWAY_SERVICE = "tenki.sandbox.v1.SSHGatewayClientService";
+export function registerSsh(server, client) {
+    server.tool("tenki_update_ssh_keys", "Set the SSH authorized public keys on a running sandbox, enabling direct SSH access for the given keys.", {
+        session_id: sessionIdSchema,
+        public_keys: z.array(z.string()).describe("SSH public keys (ssh-ed25519 …, ssh-rsa …) to authorize. Replaces the current set."),
+    }, async ({ session_id, public_keys }) => ok(await client.control("UpdateSSHAuthorizedKeys", { sessionId: session_id, sshAuthorizedKeys: public_keys })));
+    server.tool("tenki_issue_ssh_cert", "Issue a short-lived SSH certificate for a public key, authorizing SSH access to a sandbox via the SSH gateway.", {
+        session_id: sessionIdSchema,
+        public_key: z.string().describe("The SSH public key to sign into a certificate."),
+    }, async ({ session_id, public_key }) => ok(await client.control("IssueSandboxSSHCert", { sessionId: session_id, publicKey: public_key }, SSH_GATEWAY_SERVICE)));
+    server.tool("tenki_list_ssh_gateways", "List the currently active SSH gateways for the workspace.", { workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace).") }, async ({ workspace_id }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListActiveSSHGateways", { ...(workspaceId ? { workspaceId } : {}) }, SSH_GATEWAY_SERVICE));
+    });
+}

package/dist/tools/templates.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Template tools — custom-image templates and their builds.
+ *
+ * A "template" is a reusable sandbox-image spec (base image + setup script +
+ * default resources/env); building one produces a snapshot/image that sandboxes
+ * can boot from. Method names and request fields are matched to the generated
+ * `tenki.sandbox.v1.SandboxService` protobuf (the wire contract the control
+ * plane actually speaks). Notable shapes: sizing is a nested `resources` object
+ * ({ cpuCores, memoryMb, diskSizeGb }); the env map is `envVars`; a build is
+ * addressed by `buildId`; and ListActiveTemplateBuilds is scoped by `templateId`.
+ */
+export declare function registerTemplates(server: McpServer, client: TenkiClient): void;