@luxorai/mcp 0.0.0-stage → 0.4.0

package/dist/server.js

@@ -0,0 +1,238 @@
+/**
+ * Shared MCP server factory — builds a server with every tool module registered.
+ * Used by both transports: stdio (index.ts) and HTTP (http.ts).
+ *
+ * Security controls (see SECURITY.md; maps to CSA MCP Server Top-10 MCP-07
+ * "excessive permissions"). Every tool is registered through a guard that:
+ *   1. gives it a human-readable title (tools/titles.ts) and MCP annotations
+ *      (readOnlyHint / destructiveHint / openWorldHint) so clients can surface
+ *      or gate dangerous tools;
+ *   2. enforces least-privilege via env:
+ *        TENKI_MCP_READONLY=1        → register ONLY read tools (no create/run/delete/spend)
+ *        TENKI_MCP_DISABLED_TOOLS=a,b → skip these named tools
+ *   3. optionally audit-logs each call name to stderr: TENKI_MCP_AUDIT=1
+ *      (tool name + argument KEYS only — never values, content, or the token).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerIdentity } from "./tools/identity.js";
+import { registerRun } from "./tools/run.js";
+import { registerSandboxes } from "./tools/sandboxes.js";
+import { registerSessionsAdmin } from "./tools/sessions_admin.js";
+import { registerExec } from "./tools/exec.js";
+import { registerFiles } from "./tools/files.js";
+import { registerFilesOps } from "./tools/files_ops.js";
+import { registerGit } from "./tools/git.js";
+import { registerPorts } from "./tools/ports.js";
+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 { registerWorkspace } from "./tools/workspace.js";
+import { registerArtifacts } from "./tools/artifacts.js";
+import { registerSsh } from "./tools/ssh.js";
+import { registerEgress } from "./tools/egress.js";
+import { registerAuthStatus } from "./tools/auth_status.js";
+import { readEnv } from "./env.js";
+import { TOOL_TITLES } from "./tools/titles.js";
+export const VERSION = "0.4.0";
+const modules = [
+    registerIdentity,
+    registerRun,
+    registerSandboxes,
+    registerSessionsAdmin,
+    registerExec,
+    registerFiles,
+    registerFilesOps,
+    registerGit,
+    registerPorts,
+    registerPreviews,
+    registerSnapshots,
+    registerVolumes,
+    registerEgress,
+    registerTemplates,
+    registerWorkspace,
+    registerArtifacts,
+    registerSsh,
+];
+// Destroys/removes/revokes a resource. Checked first, so a name with one of
+// these prefixes is destructive even if it is mistakenly listed in ADDITIVE.
+const DESTRUCTIVE = /^tenki_(terminate|delete|remove|unshare|revoke|detach|unexpose|unbind)/;
+// Pure inspection, no state change / no spend → readOnlyHint.
+const READ = /^tenki_(get|list|whoami|resolve|stat|read)/;
+// Names that match the READ prefix but are not reads. tenki_get_upload_url
+// returns a signed URL for an HTTP PUT that can overwrite a file in the sandbox.
+const NOT_READ = new Set(["tenki_get_upload_url"]);
+// Pure reads that don't match the READ prefix. tenki_auth_status only inspects
+// the ambient credential + probes WhoAmI, so it must stay available under
+// TENKI_MCP_READONLY (it is how an operator diagnoses a credential problem in
+// that posture). git diff/log only read the repository.
+const READ_OVERRIDE = new Set(["tenki_auth_status", "tenki_git_diff", "tenki_git_log"]);
+// Non-read tools that only add. Everything else that is not a read is
+// destructive — see the class comment above for why that is the default.
+const ADDITIVE = new Set([
+    "tenki_run_code", // boots, uses and tears down its own throwaway sandbox
+    "tenki_create_sandbox",
+    "tenki_fork_sandbox", // the source keeps running; children are new sandboxes
+    "tenki_resume_sandbox",
+    "tenki_extend_sandbox",
+    "tenki_report_sandbox_activity", // keep-alive
+    "tenki_make_dir",
+    "tenki_git_clone", // git refuses a non-empty target directory
+    "tenki_expose_port",
+    "tenki_create_preview_url",
+    "tenki_touch_preview", // keep-alive
+    "tenki_create_snapshot",
+    "tenki_create_volume",
+    "tenki_attach_volume",
+    "tenki_create_egress_policy",
+    "tenki_create_template",
+    // Not tenki_build_template: a build with image_name publishes a new latest
+    // version, which changes what an existing `workspace/name` reference boots.
+    "tenki_issue_ssh_cert",
+]);
+export function classifyTool(name) {
+    if (DESTRUCTIVE.test(name))
+        return "destructive";
+    if (!NOT_READ.has(name) && (READ_OVERRIDE.has(name) || READ.test(name)))
+        return "read";
+    if (ADDITIVE.has(name))
+        return "additive";
+    return "destructive";
+}
+/** Title for a tool: the TOOL_TITLES entry, else one derived from the name so
+ * a tool is never advertised without a title (the offline suite fails on a
+ * missing entry, so the fallback only guards production). */
+export function titleFor(name) {
+    return (TOOL_TITLES[name] ??
+        name
+            .replace(/^tenki_/, "")
+            .split("_")
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(" "));
+}
+function readGuardOpts() {
+    const truthy = (v) => v === "1" || (v ?? "").toLowerCase() === "true";
+    const disabled = new Set((readEnv("MCP_DISABLED_TOOLS") || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
+    return { readonly: truthy(readEnv("MCP_READONLY")), disabled, audit: truthy(readEnv("MCP_AUDIT")) };
+}
+/** Log a tool call's name + argument KEYS (never values/content/token) to stderr. */
+function auditKeys(args) {
+    if (!args || typeof args !== "object")
+        return "";
+    const keys = Object.keys(args);
+    return keys.length ? ` args=[${keys.join(",")}]` : "";
+}
+/** MCP annotations derived from a tool's classification. */
+function annotationsFor(name, cls) {
+    return {
+        title: titleFor(name),
+        readOnlyHint: cls === "read",
+        destructiveHint: cls === "destructive",
+        idempotentHint: cls === "read",
+        openWorldHint: true, // every tool reaches the external Tenki API
+    };
+}
+/** Wrap a handler so TENKI_MCP_AUDIT=1 logs the call name + argument keys. */
+function withAudit(name, handler, audit) {
+    if (!audit)
+        return handler;
+    return async (args, extra) => {
+        try {
+            // A tool registered WITHOUT an input schema is invoked as (extra) —
+            // one argument — so the first param would be the request context, not
+            // tool args. Log arg keys only for the two-argument (args, extra) shape.
+            console.error(`[tenki-mcp audit] ${name}${extra === undefined ? "" : auditKeys(args)}`);
+        }
+        catch {
+            /* never let logging break a call */
+        }
+        return handler(args, extra);
+    };
+}
+/**
+ * Handle returned for a tool the guard skipped (denylist / read-only posture).
+ * The real registration APIs return a RegisteredTool handle; a module that
+ * calls .enable()/.remove() on its registration must not crash only in
+ * read-only or denylist mode, so skipped registrations get an inert stand-in.
+ */
+function noopToolHandle() {
+    return {
+        enabled: false,
+        enable() { },
+        disable() { },
+        update() { },
+        remove() { },
+    };
+}
+/**
+ * Wrap a server so every tool registration from a module is titled, annotated
+ * and subject to the least-privilege env controls above. Both registration APIs
+ * are guarded: the legacy `.tool(name, description, schema, handler)` form and
+ * the modern `.registerTool(name, config, handler)` form (the only one that
+ * accepts an outputSchema) — so neither path can bypass titles, annotations,
+ * read-only mode, or the denylist. Legacy calls are re-issued as registerTool,
+ * because the SDK's tool() overloads have no title parameter (MCP `Tool.title`
+ * would be undefined). Other access passes through to the real server unchanged.
+ */
+function guard(server, opts) {
+    const register = (target, name, config, handler) => {
+        const cls = classifyTool(name);
+        if (opts.disabled.has(name))
+            return noopToolHandle(); // explicit denylist
+        if (opts.readonly && cls !== "read")
+            return noopToolHandle(); // read-only posture: skip anything that mutates/spends
+        if (opts.registered)
+            opts.registered.count++;
+        // Name-derived classification and title stay authoritative so a module
+        // cannot soften the hints; other annotation fields pass through.
+        const annotations = {
+            ...config.annotations,
+            ...annotationsFor(name, cls),
+        };
+        return target.registerTool(name, { ...config, title: titleFor(name), annotations }, withAudit(name, handler, opts.audit));
+    };
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === "tool") {
+                // Every module uses the four-argument form; a schema-less tool passes {}.
+                return (name, description, schema, handler) => register(target, name, { description, inputSchema: schema }, handler);
+            }
+            if (prop === "registerTool") {
+                return (name, config, handler) => register(target, name, config, handler);
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Build a fresh MCP server instance with all tools registered against `client`.
+ *
+ * `client` is null when no credential was supplied. Rather than refusing to
+ * 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 82 tools that can only fail.
+ */
+export function createServer(client) {
+    const server = new McpServer({ name: "tenki", version: VERSION });
+    const opts = { ...readGuardOpts(), registered: { count: 0 } };
+    const guarded = guard(server, opts);
+    if (client)
+        for (const register of modules)
+            register(guarded, client);
+    // Registered last, through the same guard as everything else, so its
+    // toolsRegistered figure counts the tools above it (+1 for itself).
+    // READ_OVERRIDE keeps it available under TENKI_MCP_READONLY;
+    // TENKI_MCP_DISABLED_TOOLS can still drop it.
+    registerAuthStatus(guarded, client, opts.registered.count + 1);
+    if (!client)
+        console.error("tenki-mcp: no credential — only tenki_auth_status registered. Set TENKI_API_KEY or TENKI_AUTH_TOKEN and restart.");
+    if (opts.readonly)
+        console.error("tenki-mcp: TENKI_MCP_READONLY — only read-only tools registered.");
+    else if (opts.disabled.size)
+        console.error(`tenki-mcp: disabled tools — ${[...opts.disabled].join(", ")}`);
+    return server;
+}

package/dist/tools/artifacts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * artifacts.ts — signed-URL binary transfer for tenki-mcp.
+ *
+ * The text file tools (read_file/write_file) round-trip UTF-8 over the data plane.
+ * For binary payloads (datasets, wheels, images, build outputs) Tenki issues short-
+ * lived signed URLs: GetArtifactUploadUrl to PUT a file into the sandbox, and
+ * GetArtifactDownloadUrl to GET one out. These tools return the signed URL; the
+ * caller performs the actual HTTP PUT/GET.
+ *
+ * GetArtifactUploadUrlRequest is { session_id, path, content_type }.
+ * GetArtifactDownloadUrlRequest is { artifact_id } ONLY — there is no session_id
+ * field (the API discards unknown fields silently), so the tool no longer requires one.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerArtifacts(server: McpServer, client: TenkiClient): void;

package/dist/tools/artifacts.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema } from "./common.js";
+export function registerArtifacts(server, client) {
+    server.tool("tenki_get_upload_url", "Get a short-lived signed URL to upload (HTTP PUT) a binary file to a path inside a sandbox. Use for non-text payloads too large or binary for tenki_write_file.", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Destination path in the sandbox, e.g. /home/tenki/data.bin"),
+        content_type: z.string().optional().describe("MIME type of the upload, e.g. application/octet-stream."),
+    }, async ({ session_id, path, content_type }) => ok(await client.control("GetArtifactUploadUrl", {
+        sessionId: session_id,
+        path,
+        ...(content_type ? { contentType: content_type } : {}),
+    })));
+    server.tool("tenki_get_download_url", "Get a short-lived signed URL to download (HTTP GET) an artifact by its artifact id (e.g. the artifactId returned by tenki_get_upload_url, or a template build's buildLogArtifactId). The API supports download-by-artifact-id only, not download-by-path.", {
+        artifact_id: z.string().describe("Artifact id (UUID) to download."),
+        session_id: sessionIdSchema
+            .optional()
+            .describe("Ignored — kept for backwards compatibility; the API addresses artifacts by id alone."),
+    }, async ({ artifact_id }) => ok(await client.control("GetArtifactDownloadUrl", { artifactId: artifact_id })));
+}

package/dist/tools/auth_status.d.ts

@@ -0,0 +1,35 @@
+/**
+ * auth_status.ts — the one tool that works without a credential.
+ *
+ * Without this, a user who installs the server before setting a token gets a
+ * process that exits 1; MCP clients surface that as "server failed to start"
+ * and usually swallow stderr, so the actual cause (no token) is invisible. The
+ * server therefore boots credential-less with ONLY this tool registered, so an
+ * agent can ask what's wrong and get an actionable answer.
+ *
+ * It reports status; it does NOT log in. Obtaining a token is out of scope for
+ * the server (see `tenki login`), and nothing here opens a browser or writes
+ * credentials anywhere.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** How the server authenticates API calls. */
+export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "session_cookie" | "hosted_oauth";
+export interface CredentialInfo {
+    kind: CredentialKind;
+    /** Env var the token came from, or undefined when there is none. */
+    source?: "LUXORAI_AUTH_TOKEN" | "LUXORAI_API_KEY" | "TENKI_AUTH_TOKEN" | "TENKI_API_KEY";
+}
+/**
+ * Classify the ambient credential WITHOUT returning any of its material.
+ * Mirrors the header selection in client.ts (`lx_`/`tk_` → Bearer API key,
+ * `ory_st_` → OAuth/Ory session token, anything else → session cookie) and
+ * index.ts's precedence (LUXORAI_AUTH_TOKEN, LUXORAI_API_KEY, TENKI_AUTH_TOKEN, TENKI_API_KEY).
+ */
+export declare function describeCredential(env?: NodeJS.ProcessEnv): CredentialInfo;
+/**
+ * Report authentication status. `client` is null when the server booted without
+ * a credential; `toolsRegistered` lets the caller see it is in that degraded
+ * single-tool mode rather than guessing from a short tools/list.
+ */
+export declare function registerAuthStatus(server: McpServer, client: TenkiClient | null, toolsRegistered: number): void;

package/dist/tools/auth_status.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { isApiKey, readEnv, resolvedEnvName } from "../env.js";
+/**
+ * Classify the ambient credential WITHOUT returning any of its material.
+ * Mirrors the header selection in client.ts (`lx_`/`tk_` → Bearer API key,
+ * `ory_st_` → OAuth/Ory session token, anything else → session cookie) and
+ * index.ts's precedence (LUXORAI_AUTH_TOKEN, LUXORAI_API_KEY, TENKI_AUTH_TOKEN, TENKI_API_KEY).
+ */
+export function describeCredential(env = process.env) {
+    const source = resolvedEnvName(env, "AUTH_TOKEN", "API_KEY");
+    const raw = source ? env[source].trim() : "";
+    if (!raw && resolvedEnvName(env, "MCP_OAUTH_ISSUER"))
+        return { kind: "hosted_oauth" };
+    if (!raw)
+        return { kind: "none" };
+    if (isApiKey(raw))
+        return { kind: "api_key", source };
+    if (raw.startsWith("ory_st_"))
+        return { kind: "oauth_session_token", source };
+    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 @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.",
+    hosted_oauth: "Authenticated through the hosted OAuth session for this MCP connection.",
+};
+const authOutputSchema = {
+    authenticated: z.boolean().describe("True only when a credential is present AND a live identity probe succeeded."),
+    credential: z
+        .enum(["none", "api_key", "oauth_session_token", "session_cookie", "hosted_oauth"])
+        .describe("Kind of credential the server is running with. Never includes the token itself."),
+    source: z
+        .string()
+        .optional()
+        .describe("Environment variable the credential came from (TENKI_AUTH_TOKEN takes precedence over TENKI_API_KEY)."),
+    endpoint: z.string().describe("Control-plane base URL the server is pointed at."),
+    toolsRegistered: z
+        .number()
+        .int()
+        .describe("How many tools this server registered. Without a credential only this one is registered."),
+    identity: z
+        .object({
+        ownerType: z.string().optional(),
+        ownerId: z.string().optional(),
+        workspaces: z.number().int().optional(),
+    })
+        .optional()
+        .describe("Identity returned by the live probe, when it succeeded."),
+    error: z.string().optional().describe("Why the probe failed, when a credential is present but unusable (expired, revoked, wrong endpoint)."),
+    detail: z.string().describe("Human-readable status plus, when unauthenticated, how to supply a credential."),
+};
+/**
+ * Report authentication status. `client` is null when the server booted without
+ * a credential; `toolsRegistered` lets the caller see it is in that degraded
+ * single-tool mode rather than guessing from a short tools/list.
+ */
+export function registerAuthStatus(server, client, toolsRegistered) {
+    server.registerTool("tenki_auth_status", {
+        description: "Report whether the server has a usable Tenki credential, which kind (API key vs OAuth session token), and the endpoint it targets — verified with a live identity probe. Call this first when other tools fail with auth errors, or when this is the only tool available (which means no credential is configured). Reports status only; it does not log in and never returns the token.",
+        inputSchema: {},
+        outputSchema: authOutputSchema,
+    }, async () => {
+        const cred = describeCredential();
+        const endpoint = readEnv("API_ENDPOINT", "API_URL") || "https://api.tenki.cloud";
+        const base = {
+            credential: cred.kind,
+            ...(cred.source ? { source: cred.source } : {}),
+            endpoint,
+            toolsRegistered,
+        };
+        if (!client || cred.kind === "none") {
+            const result = {
+                ...base,
+                authenticated: false,
+                detail: CREDENTIAL_HELP.none,
+            };
+            return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        try {
+            const resp = await client.control("WhoAmI", {});
+            const workspaces = Array.isArray(resp.workspaces) ? resp.workspaces.length : undefined;
+            const result = {
+                ...base,
+                authenticated: true,
+                identity: {
+                    ...(typeof resp.ownerType === "string" ? { ownerType: resp.ownerType } : {}),
+                    ...(typeof resp.ownerId === "string" ? { ownerId: resp.ownerId } : {}),
+                    ...(workspaces !== undefined ? { workspaces } : {}),
+                },
+                detail: CREDENTIAL_HELP[cred.kind],
+            };
+            return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            const result = {
+                ...base,
+                authenticated: false,
+                error: e.message,
+                detail: cred.kind === "hosted_oauth"
+                    ? "The hosted OAuth session is present, but the identity probe failed. Run MCP login again."
+                    : `A ${cred.kind === "api_key" ? "tk_… API key" : "credential"} is set (from ${cred.source}) but the identity probe failed — it may be expired, revoked, or the endpoint may be wrong. ${CREDENTIAL_HELP.none}`,
+            };
+            return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    });
+}

package/dist/tools/common.d.ts

@@ -0,0 +1,70 @@
+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: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** First index ≥ i that starts a character: i itself unless i is inside one, then that character's end. */
+export declare function utf8CharStart(buf: Buffer, i: number): number;
+/** Largest end ≤ limit that does not split a character; always > start when limit > start. */
+export declare function utf8CharEnd(buf: Buffer, start: number, limit: number): number;
+/**
+ * Cap a text field at maxBytes without splitting a UTF-8 character. Returns the
+ * text unchanged when it fits; otherwise the head plus the original size.
+ */
+export declare function capText(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+    totalBytes: number;
+};
+/** Shared env-map schema used by tools that accept environment variables. */
+export declare const envSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+/** Shared session-id schema — every per-sandbox tool takes one of these.
+ * Trimmed, unlike pathSchema below: a session id is a UUID, so surrounding
+ * whitespace is always an accident (and the API's uuid validation would
+ * reject it), which makes trimming a safe correction rather than the silent
+ * retargeting it would be for a filename. */
+export declare const sessionIdSchema: z.ZodString;
+/** Shared TCP-port schema. */
+export declare const portSchema: z.ZodNumber;
+/** Shared sandbox-path schema — rejects an empty or whitespace-only path
+ * client-side instead of by a server error, WITHOUT transforming the value:
+ * 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.ZodString;
+/**
+ * Preview-slug schema, matching the server's validatePreviewSlug: 3-63 chars,
+ * lowercase/digits/hyphens, no leading/trailing hyphen. ExposePort routes a
+ * slug through the SAME preview validation (exposePersistentPreviewURL), so
+ * this applies to tenki_expose_port too. The server additionally rejects
+ * consecutive hyphens, reserved names, and workspace-length overflows —
+ * those stay server-side.
+ */
+export declare const slugSchema: z.ZodString;
+/**
+ * Shared tag-list schema, matching the API's repeated-string constraint on
+ * sessions, snapshots, volumes and templates: ≤20 tags, each ≤32 chars of
+ * [a-z0-9_:.-] starting with a letter or digit.
+ */
+export declare const tagsSchema: z.ZodOptional<z.ZodArray<z.ZodString>>;
+/**
+ * Wire mapping for the tags/clear_tags pair shared by sessions, snapshots and
+ * volumes. proto3 drops an empty repeated field, so `[]` becomes clear_tags;
+ * a non-empty list together with clear_tags is rejected because the server
+ * applies clear_tags first and would silently discard the list.
+ */
+export declare function tagsPatch(tags?: string[], clearTags?: boolean): {
+    tags?: string[];
+    clearTags?: true;
+};
+/** Free-text search across a list (server-side; API max 256 chars). */
+export declare const searchSchema: z.ZodOptional<z.ZodString>;
+/** Prefix a bare enum name the way protobuf JSON expects it (e.g. RUNNING → SESSION_STATE_RUNNING). */
+export declare const protoEnum: (prefix: string, value: string) => string;
+/** Common server-side list options shared by the sandbox, volume, template and preview-URL lists. */
+export declare const listQuery: (search?: string, includeFacets?: boolean, sortDesc?: boolean) => Record<string, unknown>;

package/dist/tools/common.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+const PUBLIC_KEYS = {
+    registryRef: "image",
+    registry_ref: "image",
+    sourceRegistryImageId: "sourceImageId",
+    source_registry_image_id: "source_image_id",
+    sourceRegistryWorkspaceId: "sourceImageWorkspaceId",
+    source_registry_workspace_id: "source_image_workspace_id",
+    sourceRegistryRef: "sourceImage",
+    source_registry_ref: "source_image",
+    registryImageName: "publishedImageName",
+    registry_image_name: "published_image_name",
+};
+/** Keep registry-backed implementation fields out of public MCP responses. */
+export function publicValue(value) {
+    if (Array.isArray(value))
+        return value.map(publicValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [PUBLIC_KEYS[key] ?? key, publicValue(child)]));
+}
+/** Serialize any tool return value as MCP text content. */
+export const ok = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(publicValue(value), null, 2) }],
+});
+// UTF-8 boundary handling for byte-capped text. A position is "inside a
+// character" only when a lead byte at most 3 bytes before it declares a
+// sequence long enough to cover it. Stray continuation bytes (binary data,
+// invalid UTF-8) are not inside anything, so a cut lands exactly there. Start
+// and end use the same rule, so consecutive pages tile the file with no gap or
+// overlap, on valid UTF-8 and on binary alike.
+const isContinuation = (b) => (b & 0xc0) === 0x80;
+/** Sequence length a lead byte declares (1 for ASCII and invalid leads). */
+const utf8SeqLen = (b) => (b >= 0xf0 && b <= 0xf7 ? 4 : b >= 0xe0 && b <= 0xef ? 3 : b >= 0xc0 && b <= 0xdf ? 2 : 1);
+/** Start of the character covering i, or -1 when i is a character start or a stray byte. */
+function coveringLead(buf, i, floor) {
+    if (i >= buf.length || !isContinuation(buf[i]))
+        return -1;
+    for (let back = 1; back <= 3 && i - back >= floor; back++) {
+        const b = buf[i - back];
+        if (!isContinuation(b))
+            return utf8SeqLen(b) > back ? i - back : -1;
+    }
+    return -1;
+}
+/** First index ≥ i that starts a character: i itself unless i is inside one, then that character's end. */
+export function utf8CharStart(buf, i) {
+    const lead = coveringLead(buf, i, 0);
+    return lead < 0 ? i : Math.min(lead + utf8SeqLen(buf[lead]), buf.length);
+}
+/** Largest end ≤ limit that does not split a character; always > start when limit > start. */
+export function utf8CharEnd(buf, start, limit) {
+    if (limit >= buf.length)
+        return buf.length;
+    const lead = coveringLead(buf, limit, start + 1);
+    return lead < 0 ? limit : lead;
+}
+/**
+ * Cap a text field at maxBytes without splitting a UTF-8 character. Returns the
+ * text unchanged when it fits; otherwise the head plus the original size.
+ */
+export function capText(text, maxBytes) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= maxBytes)
+        return { text, truncated: false, totalBytes: buf.length };
+    return { text: buf.subarray(0, utf8CharEnd(buf, 0, maxBytes)).toString("utf8"), truncated: true, totalBytes: buf.length };
+}
+/** Shared env-map schema used by tools that accept environment variables. */
+export const envSchema = z.record(z.string(), z.string()).optional().describe("Environment variables as a key→value object.");
+/** Shared session-id schema — every per-sandbox tool takes one of these.
+ * Trimmed, unlike pathSchema below: a session id is a UUID, so surrounding
+ * whitespace is always an accident (and the API's uuid validation would
+ * reject it), which makes trimming a safe correction rather than the silent
+ * retargeting it would be for a filename. */
+export const sessionIdSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .describe("Sandbox session id (UUID), from tenki_create_sandbox or tenki_list_sandboxes.");
+/** Shared TCP-port schema. */
+export const portSchema = z.number().int().min(1).max(65535).describe("TCP port inside the sandbox (1-65535).");
+/** Shared sandbox-path schema — rejects an empty or whitespace-only path
+ * client-side instead of by a server error, WITHOUT transforming the value:
+ * 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 const pathSchema = z
+    .string()
+    .refine((s) => s.trim().length > 0, "path must not be empty or whitespace-only")
+    .describe("Absolute path inside the sandbox, under /home/tenki.");
+/**
+ * Preview-slug schema, matching the server's validatePreviewSlug: 3-63 chars,
+ * lowercase/digits/hyphens, no leading/trailing hyphen. ExposePort routes a
+ * slug through the SAME preview validation (exposePersistentPreviewURL), so
+ * this applies to tenki_expose_port too. The server additionally rejects
+ * consecutive hyphens, reserved names, and workspace-length overflows —
+ * those stay server-side.
+ */
+export const slugSchema = z
+    .string()
+    .min(3)
+    .max(63)
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "lowercase letters, digits, and hyphens; cannot start or end with a hyphen")
+    .describe("Subdomain slug for the preview URL (3-63 chars, lowercase letters/digits/hyphens, no leading/trailing hyphen).");
+/**
+ * Shared tag-list schema, matching the API's repeated-string constraint on
+ * sessions, snapshots, volumes and templates: ≤20 tags, each ≤32 chars of
+ * [a-z0-9_:.-] starting with a letter or digit.
+ */
+export const tagsSchema = z
+    .array(z.string().max(32).regex(/^[a-z0-9][a-z0-9_:.-]*$/, "lowercase letters, digits, and _:.- ; must start with a letter or digit"))
+    .max(20)
+    .optional()
+    .describe("Tags (≤20, each ≤32 chars of a-z 0-9 _ : . -).");
+/**
+ * Wire mapping for the tags/clear_tags pair shared by sessions, snapshots and
+ * volumes. proto3 drops an empty repeated field, so `[]` becomes clear_tags;
+ * a non-empty list together with clear_tags is rejected because the server
+ * applies clear_tags first and would silently discard the list.
+ */
+export function tagsPatch(tags, clearTags) {
+    if (clearTags && tags && tags.length) {
+        throw new Error("pass either tags (a replacement list) or clear_tags, not both — clear_tags would win and the tags would be silently dropped.");
+    }
+    if (clearTags || (tags !== undefined && tags.length === 0))
+        return { clearTags: true };
+    return tags && tags.length ? { tags } : {};
+}
+/** Free-text search across a list (server-side; API max 256 chars). */
+export const searchSchema = z.string().max(256).optional();
+/** Prefix a bare enum name the way protobuf JSON expects it (e.g. RUNNING → SESSION_STATE_RUNNING). */
+export const protoEnum = (prefix, value) => `${prefix}_${value}`;
+/** Common server-side list options shared by the sandbox, volume, template and preview-URL lists. */
+export const listQuery = (search, includeFacets, sortDesc) => ({
+    ...(search && search.trim() ? { search: search.trim() } : {}),
+    ...(includeFacets ? { includeFacets: true } : {}),
+    ...(sortDesc ? { sortDesc: true } : {}),
+});