@luxorai/mcp 0.3.1 → 0.4.0

package/dist/tools/snapshots.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ok, sessionIdSchema } from "./common.js";
+import { ok, sessionIdSchema, tagsPatch, tagsSchema } from "./common.js";
 /**
  * Snapshots — capture a sandbox's disk + memory as a reusable image.
  *
@@ -20,54 +20,73 @@ export function registerSnapshots(server, client) {
             .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", {
+        async: z
+            .boolean()
+            .optional()
+            .describe("Return as soon as the snapshot row exists and poll tenki_get_snapshot for READY, instead of blocking until the capture finishes (default false)."),
+    }, async ({ session_id, name, expires_at, store_raw_image, async: isAsync }) => ok(await client.control("CreateSnapshot", {
         sessionId: session_id,
         ...(name ? { name } : {}),
         ...(expires_at ? { expiresAt: expires_at } : {}),
         ...(store_raw_image !== undefined ? { storeRawImage: store_raw_image } : {}),
+        ...(isAsync ? { async: true } : {}),
     })));
-    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_get_snapshot", "Fetch one snapshot's status and metadata by ID.", { snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots.") }, 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(),
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
     }, 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(),
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
     }, 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(),
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
     }, 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."),
+    server.tool("tenki_update_snapshot", "Update a snapshot's mutable metadata: name, expiry (set or clear), and tags. An expired snapshot can no longer be updated, and a pause snapshot's expiry is managed by its sandbox (both failed_precondition).", {
+        snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots."),
+        name: z.string().max(64).optional().describe("New human-readable name (max 64 chars)."),
         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.", {
+        clear_expires_at: z.boolean().optional().describe("Remove the expiry so the snapshot is kept indefinitely."),
+        tags: tagsSchema.describe("Replacement tag list. Pass [] (or clear_tags) to remove all tags."),
+        clear_tags: z.boolean().optional().describe("Remove all tags from the snapshot."),
+    }, async ({ snapshot_id, name, expires_at, clear_expires_at, tags, clear_tags }) => {
+        if (expires_at !== undefined && clear_expires_at) {
+            throw new Error("tenki_update_snapshot: pass either expires_at or clear_expires_at, not both — clear would win and the new expiry would be silently dropped.");
+        }
+        const tagPatch = tagsPatch(tags, clear_tags);
+        if (name === undefined && expires_at === undefined && !clear_expires_at && !Object.keys(tagPatch).length) {
+            throw new Error("tenki_update_snapshot: pass at least one field to change — nothing was sent.");
+        }
+        return ok(await client.control("UpdateSnapshot", {
+            snapshotId: snapshot_id,
+            ...(name !== undefined ? { name } : {}),
+            ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+            ...(clear_expires_at ? { clearExpiresAt: true } : {}),
+            ...tagPatch,
+        }));
+    });
+    server.tool("tenki_delete_snapshot", "Permanently delete a snapshot by ID.", { snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots.") }, 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().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots.") }, 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. NOTE: the underlying RPC (ListWorkspaceSnapshots) is deprecated upstream in favour of the credential-scoped tenki_list_snapshots; prefer that unless you need an explicit workspace_id.", {
         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(),
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
     }, async ({ workspace_id, page_size, page_token }) => {
         const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
         return ok(await client.control("ListWorkspaceSnapshots", {

package/dist/tools/ssh.d.ts

@@ -6,9 +6,9 @@
  * 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.
+ * Request shapes follow proto/tenki/sandbox/v1/ssh_gateway_client.proto:
+ * IssueSandboxSSHCertRequest { session_id, public_key (32-8192 chars), requested_ttl, source_addresses[] }
+ * ListActiveSSHGatewaysRequest { region, session_id } — there is NO workspace_id field.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "../client.js";

package/dist/tools/ssh.js

@@ -2,16 +2,42 @@ 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.", {
+    server.tool("tenki_update_ssh_keys", "Set the SSH authorized public keys on a running sandbox, enabling direct SSH access for the given keys. Replaces the current set (at least one key is required — the API has no 'clear' operation).", {
         session_id: sessionIdSchema,
-        public_keys: z.array(z.string()).describe("SSH public keys (ssh-ed25519 …, ssh-rsa …) to authorize. Replaces the current set."),
+        public_keys: z
+            .array(z.string().min(1))
+            .min(1)
+            .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.", {
+    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. Returns the certificate, the CA public key (caPub) for known_hosts, expiry, a renewal hint, and pinHostKey — when true, verify the gateway host certificate against caPub (e.g. a `@cert-authority` known_hosts line) rather than trusting on first use.", {
         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));
-    });
+        public_key: z
+            .string()
+            .min(32)
+            .max(8192)
+            .describe("OpenSSH-format public key to sign into a certificate (e.g. 'ssh-ed25519 AAAA…')."),
+        requested_ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Requested certificate lifetime in seconds; the server caps it to policy."),
+        source_addresses: z
+            .array(z.string())
+            .max(16)
+            .optional()
+            .describe("CIDRs bound into the cert's source-address critical option; SSH refuses the cert from any other source IP."),
+    }, async ({ session_id, public_key, requested_ttl_seconds, source_addresses }) => ok(await client.control("IssueSandboxSSHCert", {
+        sessionId: session_id,
+        publicKey: public_key,
+        ...(requested_ttl_seconds ? { requestedTtl: `${requested_ttl_seconds}s` } : {}),
+        ...(source_addresses && source_addresses.length ? { sourceAddresses: source_addresses } : {}),
+    }, SSH_GATEWAY_SERVICE)));
+    server.tool("tenki_list_ssh_gateways", "List the currently active SSH gateways (id, region, public endpoint, health). Filter by region, or pass session_id to get only the gateways that can reach that sandbox's host. Gateways are fleet-wide, not per workspace.", {
+        region: z.string().optional().describe("Only gateways in this region (e.g. 'us', 'eu'). Omit for all regions."),
+        session_id: sessionIdSchema.optional().describe("Only gateways that can reach this sandbox's host."),
+    }, async ({ region, session_id }) => ok(await client.control("ListActiveSSHGateways", {
+        ...(region ? { region } : {}),
+        ...(session_id ? { sessionId: session_id } : {}),
+    }, SSH_GATEWAY_SERVICE)));
 }

package/dist/tools/templates.d.ts

@@ -9,6 +9,7 @@ import type { TenkiClient } from "../client.js";
  * `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`.
+ * addressed by `buildId`; and ListActiveTemplateBuilds / ListTemplateBuilds are scoped
+ * by `templateId`.
  */
 export declare function registerTemplates(server: McpServer, client: TenkiClient): void;

package/dist/tools/templates.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ok, envSchema } from "./common.js";
+import { envSchema, listQuery, ok, protoEnum, searchSchema, tagsPatch, tagsSchema } from "./common.js";
 /**
  * Template tools — custom-image templates and their builds.
  *
@@ -9,7 +9,8 @@ import { ok, envSchema } from "./common.js";
  * `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`.
+ * addressed by `buildId`; and ListActiveTemplateBuilds / ListTemplateBuilds are scoped
+ * by `templateId`.
  */
 export function registerTemplates(server, client) {
     /** Assemble the nested TemplateResources object from flat sizing params (omitting any unset). */
@@ -25,15 +26,15 @@ export function registerTemplates(server, client) {
     };
     // ── Create ──────────────────────────────────────────────────────────────────
     server.tool("tenki_create_template", "Create a custom-image template (a reusable sandbox-image spec: base image + setup script + default resources). Build it into a bootable image later with tenki_build_template. NOTE: only a TYPED template (created with builder_spec, no legacy fields) can build a named, publishable image (image_name) that tenki_create_sandbox boots via its `image` arg.", {
-        name: z.string().describe("Human-readable template name."),
+        name: z.string().min(1).max(64).describe("Human-readable template name (1-64 chars)."),
         base_image_id: z.string().optional().describe("Base image ID to build on top of."),
         setup_script: z.string().optional().describe("Shell script run at build time to provision the image. Required for a from-scratch template (the API rejects a create without it unless you derive from a parent template/image)."),
         start_cmd: z.string().optional().describe("Command run when a sandbox boots from this template."),
-        cpu_cores: z.number().int().min(1).max(16).optional().describe("Default vCPUs for sandboxes from this template (1-16)."),
-        memory_mb: z.number().int().min(512).max(65536).optional().describe("Default memory in MB (512-65536)."),
+        cpu_cores: z.number().int().min(1).max(128).optional().describe("Default vCPUs for sandboxes from this template (1-128; workspace plan may cap lower)."),
+        memory_mb: z.number().int().min(512).max(524288).refine((n) => n % 2 === 0, "memory_mb must be even").optional().describe("Default memory in MB (512-524288, even)."),
         disk_size_gb: z.number().int().min(5).max(100).optional().describe("Default disk in GB (5-100)."),
         env_vars: envSchema,
-        tags: z.array(z.string()).optional().describe("Tags for later filtering."),
+        tags: tagsSchema.describe("Tags for later filtering (≤20, each ≤32 chars of a-z 0-9 _ : . -)."),
         parent_template_id: z.string().optional().describe("Derive this template from an existing template."),
         parent_image: z.string().optional().describe("Derive this template from an existing built image reference."),
         builder_spec: z
@@ -63,17 +64,29 @@ export function registerTemplates(server, client) {
     // ── Get ─────────────────────────────────────────────────────────────────────
     server.tool("tenki_get_template", "Retrieve one template by ID.", { template_id: z.string().describe("The template ID.") }, async ({ template_id }) => ok(await client.control("GetTemplate", { templateId: template_id })));
     // ── List ────────────────────────────────────────────────────────────────────
-    server.tool("tenki_list_templates", "List templates for the workspace, optionally filtered by tags.", {
+    server.tool("tenki_list_templates", "List templates for the workspace with server-side search, build-state filter, tag filter, sorting and optional state-count facets.", {
         tags: z.array(z.string()).optional().describe("Only return templates that carry all of these tags."),
+        search: searchSchema.describe("Free-text search over template name/id (max 256 chars)."),
+        states: z
+            .array(z.enum(["READY", "BUILDING", "PENDING", "FAILED", "UNBUILT"]))
+            .max(16)
+            .optional()
+            .describe("Only templates whose latest build is in any of these states (UNBUILT = never built)."),
+        sort_by: z.enum(["NAME", "CREATED_AT", "UPDATED_AT"]).optional().describe("Column to sort by."),
+        sort_desc: z.boolean().optional().describe("Sort descending (default ascending)."),
+        include_facets: z.boolean().optional().describe("Also return per-state counts for the same filter scope."),
         workspace_id: z.string().optional().describe("Workspace to list from (defaults to the key's first workspace)."),
-        page_size: z.number().int().positive().optional(),
-        page_token: z.string().optional(),
-    }, async ({ tags, workspace_id, page_size, page_token }) => {
+        page_size: z.number().int().min(1).max(100).optional().describe("Rows per page (max 100)."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ tags, search, states, sort_by, sort_desc, include_facets, workspace_id, page_size, page_token }) => {
         const owner = await client.resolveOwner();
         const workspaceId = workspace_id ?? owner.workspaceId;
         return ok(await client.control("ListTemplates", {
             ...(workspaceId ? { workspaceId } : {}),
             ...(tags && tags.length ? { tags } : {}),
+            ...(states && states.length ? { states: states.map((s) => protoEnum("TEMPLATE_LIST_STATE", s)) } : {}),
+            ...(sort_by ? { sortBy: protoEnum("TEMPLATE_SORT_FIELD", sort_by) } : {}),
+            ...listQuery(search, include_facets, sort_desc),
             ...(page_size ? { pageSize: page_size } : {}),
             ...(page_token ? { pageToken: page_token } : {}),
         }));
@@ -85,11 +98,11 @@ export function registerTemplates(server, client) {
         base_image_id: z.string().optional().describe("New base image ID."),
         setup_script: z.string().optional().describe("New build-time provisioning script."),
         start_cmd: z.string().optional().describe("New boot command."),
-        cpu_cores: z.number().int().min(1).max(16).optional().describe("New default vCPUs (1-16)."),
-        memory_mb: z.number().int().min(512).max(65536).optional().describe("New default memory in MB (512-65536)."),
+        cpu_cores: z.number().int().min(1).max(128).optional().describe("New default vCPUs (1-128)."),
+        memory_mb: z.number().int().min(512).max(524288).refine((n) => n % 2 === 0, "memory_mb must be even").optional().describe("New default memory in MB (512-524288, even)."),
         disk_size_gb: z.number().int().min(5).max(100).optional().describe("New default disk in GB (5-100)."),
         env_vars: envSchema,
-        tags: z.array(z.string()).optional().describe("Replacement set of tags."),
+        tags: tagsSchema.describe("Replacement tag list. Pass [] (or clear_tags) to remove all tags."),
         clear_tags: z.boolean().optional().describe("Remove all tags from the template."),
         builder_spec: z.record(z.string(), z.unknown()).optional().describe("Advanced structured build spec (TemplateBuildSpec); passed through as-is."),
     }, async (a) => {
@@ -102,10 +115,12 @@ export function registerTemplates(server, client) {
             ...(a.start_cmd !== undefined ? { startCmd: a.start_cmd } : {}),
             ...(a.env_vars && Object.keys(a.env_vars).length ? { envVars: a.env_vars } : {}),
             ...(Object.keys(resources).length ? { resources } : {}),
-            ...(a.tags && a.tags.length ? { tags: a.tags } : {}),
-            ...(a.clear_tags ? { clearTags: true } : {}),
+            ...tagsPatch(a.tags, a.clear_tags),
             ...(a.builder_spec ? { builderSpec: a.builder_spec } : {}),
         };
+        if (Object.keys(body).length === 1) {
+            throw new Error("tenki_update_template: pass at least one field to change — nothing was sent.");
+        }
         return ok(await client.control("UpdateTemplate", body));
     });
     // ── Delete ──────────────────────────────────────────────────────────────────
@@ -121,8 +136,9 @@ export function registerTemplates(server, client) {
         template_id: z.string().describe("The template ID to build."),
         image_name: z
             .string()
+            .regex(/^[a-z][a-z0-9-]{0,63}$/, "lowercase letters, digits and hyphens; must start with a letter; max 64 chars")
             .optional()
-            .describe("Name for the resulting image. Requires a TYPED template (created with builder_spec) — the API rejects it for legacy setup-script templates."),
+            .describe("Name for the resulting image (^[a-z][a-z0-9-]{0,63}$). Requires a TYPED template (created with builder_spec) — the API rejects it for legacy setup-script templates."),
         publish_raw_image: z.boolean().optional().describe("Publish the raw rootfs image alongside the build snapshot."),
         build_secrets: z.record(z.string(), z.string()).optional().describe("Build-time secrets as a key→value object (not persisted into the image)."),
         build_env: z.record(z.string(), z.string()).optional().describe("Per-build environment overrides frozen into this build only."),
@@ -139,4 +155,8 @@ export function registerTemplates(server, client) {
     server.tool("tenki_get_template_build", "Retrieve one template build by its build ID (state, progress, and result image). A READY build's imageDigestRef is the reference tenki_create_sandbox's `image` arg takes.", { build_id: z.string().describe("The template build ID.") }, async ({ build_id }) => ok(await client.control("GetTemplateBuild", { buildId: build_id })));
     // ── List active builds ──────────────────────────────────────────────────────────
     server.tool("tenki_list_active_template_builds", "List the currently active (in-progress) builds for a given template.", { template_id: z.string().describe("The template ID whose active builds to list.") }, async ({ template_id }) => ok(await client.control("ListActiveTemplateBuilds", { templateId: template_id })));
+    // ── List builds (history + storage) ─────────────────────────────────────────────
+    server.tool("tenki_list_template_builds", "List every build of a template (not just active ones) with what each image holds in workspace storage: version, state, imageBytes, isCurrent, isLaunchable, and deleteBlockedReason (empty when tenki_delete_template_build can free it). Also returns the template-level storage totals.", { template_id: z.string().min(1).describe("The template ID whose builds to list.") }, async ({ template_id }) => ok(await client.control("ListTemplateBuilds", { templateId: template_id })));
+    // ── Delete build ────────────────────────────────────────────────────────────────
+    server.tool("tenki_delete_template_build", "Delete one template build's image to free workspace storage and retire the build (irreversible; a published image version carrying this build is removed with it). Refused with failed_precondition when the image cannot be freed, e.g. the build is still running, its image is still being written or deleted, the template is published from it, a sandbox that is not terminated (running or paused) still uses it, or an image tag, share, snapshot variant or derived template references it — check deleteBlockedReason via tenki_list_template_builds first (empty = deletable). Deleting the template's current build repoints the template at its latest remaining launchable build, or leaves it with none. Returns freedBytes, or cleanupPending when the image is still being removed.", { build_id: z.string().min(1).describe("The template build ID to delete.") }, async ({ build_id }) => ok(await client.control("DeleteTemplateBuild", { buildId: build_id })));
 }

package/dist/tools/titles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Human-readable tool titles, applied centrally by the registration guard in
+ * server.ts so every tool advertises one (MCP `Tool.title` and
+ * `annotations.title`). Connector directories require a title on every tool;
+ * test/presubmission.test.mjs fails if a registered tool has no entry here or an
+ * entry names a tool that is not registered.
+ */
+export declare const TOOL_TITLES: Readonly<Record<string, string>>;

package/dist/tools/titles.js

@@ -0,0 +1,102 @@
+/**
+ * Human-readable tool titles, applied centrally by the registration guard in
+ * server.ts so every tool advertises one (MCP `Tool.title` and
+ * `annotations.title`). Connector directories require a title on every tool;
+ * test/presubmission.test.mjs fails if a registered tool has no entry here or an
+ * entry names a tool that is not registered.
+ */
+export const TOOL_TITLES = {
+    // Identity / auth
+    tenki_whoami: "Show Current Identity",
+    tenki_auth_status: "Check Credential Status",
+    // Sandboxes
+    tenki_run_code: "Run Code in a Throwaway Sandbox",
+    tenki_create_sandbox: "Create Sandbox",
+    tenki_get_sandbox: "Get Sandbox",
+    tenki_get_sandbox_metrics: "Get Sandbox Metrics",
+    tenki_list_sandboxes: "List Sandboxes",
+    tenki_list_workspace_sandboxes: "List Workspace Sandboxes",
+    tenki_terminate_sandbox: "Terminate Sandbox",
+    tenki_terminate_sandboxes: "Terminate Multiple Sandboxes",
+    tenki_pause_sandbox: "Pause Sandbox",
+    tenki_resume_sandbox: "Resume Sandbox",
+    tenki_fork_sandbox: "Fork Sandbox",
+    tenki_extend_sandbox: "Extend Sandbox Lifetime",
+    tenki_update_sandbox: "Update Sandbox",
+    tenki_report_sandbox_activity: "Report Sandbox Activity",
+    // Commands and files
+    tenki_exec: "Run Command in Sandbox",
+    tenki_read_file: "Read File",
+    tenki_write_file: "Write File",
+    tenki_list_files: "List Directory",
+    tenki_stat_path: "Get Path Info",
+    tenki_make_dir: "Create Directory",
+    tenki_remove_path: "Delete File or Directory",
+    tenki_move_path: "Move or Rename Path",
+    tenki_get_upload_url: "Get File Upload URL",
+    tenki_get_download_url: "Get Artifact Download URL",
+    // Git
+    tenki_git_clone: "Clone Git Repository",
+    tenki_git_checkout: "Check Out Git Ref",
+    tenki_git_diff: "Show Git Diff",
+    tenki_git_log: "Show Git Log",
+    // Ports and previews
+    tenki_expose_port: "Expose Port",
+    tenki_list_exposed_ports: "List Exposed Ports",
+    tenki_unexpose_port: "Unexpose Port",
+    tenki_create_preview_url: "Create Preview URL",
+    tenki_open_preview: "Open Authenticated Preview",
+    tenki_list_preview_urls: "List Preview URLs",
+    tenki_get_preview_url: "Get Preview URL",
+    tenki_delete_preview_url: "Delete Preview URL",
+    tenki_touch_preview: "Keep Preview Alive",
+    tenki_bind_preview_url: "Bind Preview URL",
+    tenki_unbind_preview_url: "Unbind Preview URL",
+    tenki_resolve_preview_token: "Resolve Preview Token",
+    // Snapshots
+    tenki_create_snapshot: "Create Snapshot",
+    tenki_get_snapshot: "Get Snapshot",
+    tenki_list_snapshots: "List Snapshots",
+    tenki_list_session_snapshots: "List Sandbox Snapshots",
+    tenki_list_dangling_snapshots: "List Dangling Snapshots",
+    tenki_list_workspace_snapshots: "List Workspace Snapshots",
+    tenki_update_snapshot: "Update Snapshot",
+    tenki_delete_snapshot: "Delete Snapshot",
+    tenki_get_snapshot_download_url: "Get Snapshot Download URL",
+    // Volumes
+    tenki_create_volume: "Create Volume",
+    tenki_get_volume: "Get Volume",
+    tenki_list_volumes: "List Volumes",
+    tenki_update_volume: "Update Volume",
+    tenki_delete_volume: "Delete Volume",
+    tenki_resize_volume: "Resize Volume",
+    tenki_attach_volume: "Attach Volume",
+    tenki_detach_volume: "Detach Volume",
+    // Egress policies
+    tenki_create_egress_policy: "Create Egress Policy",
+    tenki_get_egress_policy: "Get Egress Policy",
+    tenki_list_egress_policies: "List Egress Policies",
+    tenki_update_egress_policy: "Replace Egress Policy",
+    tenki_delete_egress_policy: "Delete Egress Policy",
+    // Templates
+    tenki_create_template: "Create Template",
+    tenki_get_template: "Get Template",
+    tenki_list_templates: "List Templates",
+    tenki_update_template: "Update Template",
+    tenki_delete_template: "Delete Template",
+    tenki_build_template: "Build Template",
+    tenki_cancel_template_build: "Cancel Template Build",
+    tenki_get_template_build: "Get Template Build",
+    tenki_list_active_template_builds: "List Active Template Builds",
+    tenki_list_template_builds: "List Template Builds",
+    tenki_delete_template_build: "Delete Template Build",
+    // Workspace
+    tenki_get_workspace_usage: "Get Workspace Usage",
+    tenki_list_ci_runner_sizes: "List CI Runner Sizes",
+    tenki_get_workspace_preview_domains: "Get Wildcard Preview Domains",
+    tenki_update_workspace_preview_domains: "Update Wildcard Preview Domains",
+    // SSH
+    tenki_update_ssh_keys: "Set SSH Authorized Keys",
+    tenki_issue_ssh_cert: "Issue SSH Certificate",
+    tenki_list_ssh_gateways: "List SSH Gateways",
+};

package/dist/tools/volumes.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ok, pathSchema, sessionIdSchema } from "./common.js";
+import { listQuery, ok, pathSchema, protoEnum, searchSchema, sessionIdSchema, tagsPatch, tagsSchema } from "./common.js";
 /** Volume size bounds the control plane accepts: 1 MiB … 100 GiB, in bytes. */
 const MIN_VOLUME_BYTES = 1_048_576; // 1 MiB
 const MAX_VOLUME_BYTES = 107_374_182_400; // 100 GiB
@@ -27,28 +27,48 @@ export function registerVolumes(server, client) {
     // ── Get ───────────────────────────────────────────────────────────────────
     server.tool("tenki_get_volume", "Fetch a single volume's metadata and current state by its id.", { volume_id: z.string().describe("The volume id, e.g. vol_….") }, async ({ volume_id }) => ok(await client.control("GetVolume", { volumeId: volume_id })));
     // ── List ──────────────────────────────────────────────────────────────────
-    server.tool("tenki_list_volumes", "List persistent volumes in a workspace (defaults to the key's first workspace). Supports pagination.", {
+    server.tool("tenki_list_volumes", "List persistent volumes in a workspace (defaults to the key's first workspace) with server-side search, state filter, sorting and optional state-count facets. Supports pagination.", {
         workspace_id: z.string().optional().describe("Workspace to list volumes from (defaults to the key's first workspace)."),
-        page_size: z.number().int().positive().optional().describe("Max volumes to return per page."),
+        search: searchSchema.describe("Free-text search over volume name/id (max 256 chars)."),
+        states: z.array(z.enum(["AVAILABLE", "IN_USE", "DELETING", "DELETED"])).max(16).optional().describe("Only volumes in any of these states."),
+        sort_by: z.enum(["NAME", "STATE", "SIZE_BYTES", "CREATED_AT"]).optional().describe("Column to sort by."),
+        sort_desc: z.boolean().optional().describe("Sort descending (default ascending)."),
+        include_facets: z.boolean().optional().describe("Also return per-state counts for the same filter scope."),
+        page_size: z.number().int().min(1).max(100).optional().describe("Max volumes to return per page (max 100)."),
         page_token: z.string().optional().describe("Page token from a previous response's nextPageToken."),
-    }, async ({ workspace_id, page_size, page_token }) => {
+    }, async ({ workspace_id, search, states, sort_by, sort_desc, include_facets, page_size, page_token }) => {
         const owner = await client.resolveOwner();
         const workspaceId = workspace_id ?? owner.workspaceId;
         return ok(await client.control("ListVolumes", {
             ...(workspaceId ? { workspaceId } : {}),
+            ...(states && states.length ? { states: states.map((s) => protoEnum("VOLUME_STATE", s)) } : {}),
+            ...(sort_by ? { sortBy: protoEnum("VOLUME_SORT_FIELD", sort_by) } : {}),
+            ...listQuery(search, include_facets, sort_desc),
             ...(page_size ? { pageSize: page_size } : {}),
             ...(page_token ? { pageToken: page_token } : {}),
         }));
     });
     // ── Update ────────────────────────────────────────────────────────────────
-    server.tool("tenki_update_volume", "Rename a volume (update its human-readable name). To change a volume's size use tenki_resize_volume instead.", {
+    server.tool("tenki_update_volume", "Update a volume's name and/or tags (pass at least one). To change a volume's size use tenki_resize_volume instead.", {
         volume_id: z.string().describe("The volume id to update."),
-        name: z.string().describe("New human-readable name for the volume."),
-    }, async ({ volume_id, name }) => ok(await client.control("UpdateVolume", { volumeId: volume_id, name })));
+        name: z.string().min(1).max(64).optional().describe("New human-readable name for the volume."),
+        tags: tagsSchema.describe("Replacement tag list. Pass [] (or clear_tags) to remove all tags."),
+        clear_tags: z.boolean().optional().describe("Remove all tags from the volume."),
+    }, async ({ volume_id, name, tags, clear_tags }) => {
+        const tagPatch = tagsPatch(tags, clear_tags);
+        if (name === undefined && !Object.keys(tagPatch).length) {
+            throw new Error("tenki_update_volume: pass name, tags, or clear_tags — nothing was sent.");
+        }
+        return ok(await client.control("UpdateVolume", {
+            volumeId: volume_id,
+            ...(name !== undefined ? { name } : {}),
+            ...tagPatch,
+        }));
+    });
     // ── Delete ────────────────────────────────────────────────────────────────
     server.tool("tenki_delete_volume", "Permanently delete a volume and destroy its data. Fails with VolumeInUse if the volume is still attached to a session — detach it first.", { volume_id: z.string().describe("The volume id to delete.") }, async ({ volume_id }) => ok(await client.control("DeleteVolume", { volumeId: volume_id })));
     // ── Resize ────────────────────────────────────────────────────────────────
-    server.tool("tenki_resize_volume", "Grow a volume to a new size in bytes (1 MiB … 100 GiB). Volumes can grow but not shrink.", {
+    server.tool("tenki_resize_volume", "Change a volume's size in bytes (1 MiB … 100 GiB). Only a volume that has never been attached can be resized; once attached its size is fixed (failed_precondition), so create a new volume for a different size.", {
         volume_id: z.string().describe("The volume id to resize."),
         size_bytes: sizeBytesSchema,
     }, async ({ volume_id, size_bytes }) => ok(await client.control("ResizeVolume", { volumeId: volume_id, newSizeBytes: size_bytes })));
@@ -66,12 +86,17 @@ export function registerVolumes(server, client) {
         volume: {
             volumeId: volume_id,
             mountPath: mount_path,
-            ...(read_only !== undefined ? { readOnly: read_only } : {}),
+            // proto field is `readonly` (one word); `readOnly` is an unknown field the API discards.
+            ...(read_only !== undefined ? { readonly: read_only } : {}),
         },
     })));
     // ── Detach ────────────────────────────────────────────────────────────────
-    server.tool("tenki_detach_volume", "Unmount a volume from a sandbox session.", {
+    server.tool("tenki_detach_volume", "Unmount a volume from a sandbox session and sync it back to storage. A volume whose sync back is still pending (SYNC_PENDING) cannot be detached, even with force (failed_precondition): wait for the upload to finish or ask Tenki support to recover it. Set force to unplug an attached volume the guest cannot unmount — writes the guest has not flushed are lost.", {
         session_id: sessionIdSchema.describe("The sandbox session to detach the volume from."),
         volume_id: z.string().describe("The volume id to detach."),
-    }, async ({ session_id, volume_id }) => ok(await client.control("DetachVolume", { sessionId: session_id, volumeId: volume_id })));
+        force: z
+            .boolean()
+            .optional()
+            .describe("Force-unplug an ATTACHED volume (default false). Unflushed guest writes are lost. Never releases a SYNC_PENDING attachment; on a host that cannot force detach yet the API returns failed_precondition."),
+    }, async ({ session_id, volume_id, force }) => ok(await client.control("DetachVolume", { sessionId: session_id, volumeId: volume_id, ...(force ? { forceDetach: true } : {}) })));
 }

package/dist/tools/workspace.d.ts

@@ -1,4 +1,12 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "../client.js";
-/** Workspace-level sandbox usage + default settings (incl. snapshot retention). */
+/**
+ * Workspace-level sandbox usage, CI runner sizes and wildcard preview domains.
+ *
+ * The workspace quota/retention settings RPCs (Get/UpdateWorkspaceSandboxSettings,
+ * Get/UpdateWorkspaceSnapshotRetentionSettings) were REMOVED from the API
+ * (tenki-app #5007, 2026-08-07; they 404 on staging and production), so their
+ * tools are gone. Quotas now come from the workspace plan and are read-only
+ * through tenki_get_workspace_usage.
+ */
 export declare function registerWorkspace(server: McpServer, client: TenkiClient): void;