@luxorai/mcp 0.3.1 → 0.4.0

package/dist/server.d.ts

@@ -4,8 +4,9 @@
  *
  * 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. tags it with MCP annotations (readOnlyHint / destructiveHint / openWorldHint)
- *      so clients can surface or gate dangerous tools;
+ *   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
@@ -14,9 +15,28 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "./client.js";
-export declare const VERSION = "0.3.1";
-type Cls = "read" | "write" | "destructive";
+export declare const VERSION = "0.4.0";
+/**
+ * Tool classes, mapped to MCP annotations by annotationsFor():
+ *   read        → readOnlyHint: true. Pure inspection: no state change, no spend.
+ *   additive    → readOnlyHint: false, destructiveHint: false. Only creates new
+ *                 things or extends existing ones (a sandbox, a snapshot, more
+ *                 lifetime, a keep-alive); never changes or removes what exists.
+ *   destructive → readOnlyHint: false, destructiveHint: true. May overwrite,
+ *                 modify, interrupt or delete existing state.
+ *
+ * Destructive is the DEFAULT for anything that is not a read: a non-read tool
+ * is additive only when it is listed in ADDITIVE. MCP defines
+ * `destructiveHint: false` as "performs only additive updates", and clients use
+ * it to decide whether to ask before a call, so an unlisted new tool must fail
+ * safe (prompt) rather than claim to be harmless.
+ */
+type Cls = "read" | "additive" | "destructive";
 export declare function classifyTool(name: string): Cls;
+/** 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 declare function titleFor(name: string): string;
 /**
  * Build a fresh MCP server instance with all tools registered against `client`.
  *
@@ -24,7 +44,7 @@ export declare function classifyTool(name: string): Cls;
  * start — which MCP clients report as an opaque "server failed to start" —
  * the server boots with ONLY tenki_auth_status registered, so an agent can
  * discover and explain the missing credential. Registering the other tools in
- * that state would offer 70 tools that can only fail.
+ * that state would offer 82 tools that can only fail.
  */
 export declare function createServer(client: TenkiClient | null): McpServer;
 export {};

package/dist/server.js

@@ -4,8 +4,9 @@
  *
  * 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. tags it with MCP annotations (readOnlyHint / destructiveHint / openWorldHint)
- *      so clients can surface or gate dangerous tools;
+ *   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
@@ -29,8 +30,11 @@ 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";
-export const VERSION = "0.3.1";
+import { readEnv } from "./env.js";
+import { TOOL_TITLES } from "./tools/titles.js";
+export const VERSION = "0.4.0";
 const modules = [
     registerIdentity,
     registerRun,
@@ -44,40 +48,75 @@ const modules = [
     registerPreviews,
     registerSnapshots,
     registerVolumes,
+    registerEgress,
     registerTemplates,
     registerWorkspace,
     registerArtifacts,
     registerSsh,
 ];
-// Destroys/removes/revokes a resource → destructiveHint.
+// 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)/;
-// Named exceptions that match the READ prefix below but actually grant a
-// write/spend capability, so they must never be treated as read-only.
-// tenki_get_upload_url returns a signed URL for an arbitrary PUT into the sandbox.
-const WRITE_OVERRIDE = new Set(["tenki_get_upload_url"]);
-// Named exceptions that are pure reads but don't match the READ prefix below.
-// 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).
-const READ_OVERRIDE = new Set(["tenki_auth_status"]);
 // 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 (WRITE_OVERRIDE.has(name))
-        return "write";
-    if (READ_OVERRIDE.has(name) || READ.test(name))
+    if (!NOT_READ.has(name) && (READ_OVERRIDE.has(name) || READ.test(name)))
         return "read";
-    return "write";
+    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((process.env.TENKI_MCP_DISABLED_TOOLS || "")
+    const disabled = new Set((readEnv("MCP_DISABLED_TOOLS") || "")
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean));
-    return { readonly: truthy(process.env.TENKI_MCP_READONLY), disabled, audit: truthy(process.env.TENKI_MCP_AUDIT) };
+    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) {
@@ -87,8 +126,9 @@ function auditKeys(args) {
     return keys.length ? ` args=[${keys.join(",")}]` : "";
 }
 /** MCP annotations derived from a tool's classification. */
-function annotationsFor(cls) {
+function annotationsFor(name, cls) {
     return {
+        title: titleFor(name),
         readOnlyHint: cls === "read",
         destructiveHint: cls === "destructive",
         idempotentHint: cls === "read",
@@ -128,45 +168,40 @@ function noopToolHandle() {
     };
 }
 /**
- * Wrap a server so every tool registration from a module is annotated + 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 annotations, read-only mode, or
- * the denylist. Other access passes through to the real server unchanged.
+ * 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") {
-                return (name, description, schema, 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++;
-                    return target.tool(name, description, schema, annotationsFor(cls), withAudit(name, handler, opts.audit));
-                };
+                // 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) => {
-                    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
-                    // Name-derived classification stays authoritative for the four hints so
-                    // a module cannot soften them; other annotation fields pass through.
-                    if (opts.registered)
-                        opts.registered.count++;
-                    const annotations = {
-                        ...config.annotations,
-                        ...annotationsFor(cls),
-                    };
-                    return target.registerTool(name, { ...config, annotations }, withAudit(name, handler, opts.audit));
-                };
+                return (name, config, handler) => register(target, name, config, handler);
             }
             return Reflect.get(target, prop, receiver);
         },
@@ -179,7 +214,7 @@ function guard(server, opts) {
  * start — which MCP clients report as an opaque "server failed to start" —
  * the server boots with ONLY tenki_auth_status registered, so an agent can
  * discover and explain the missing credential. Registering the other tools in
- * that state would offer 70 tools that can only fail.
+ * that state would offer 82 tools that can only fail.
  */
 export function createServer(client) {
     const server = new McpServer({ name: "tenki", version: VERSION });

package/dist/tools/artifacts.d.ts

@@ -7,9 +7,9 @@
  * GetArtifactDownloadUrl to GET one out. These tools return the signed URL; the
  * caller performs the actual HTTP PUT/GET.
  *
- * GetArtifactUploadUrlRequest { sessionId, path, contentType } is verified from the
- * published Tenki API surface. GetArtifactDownloadUrl takes an artifactId only — the API
- * rejects a path (command stdout/stderr are surfaced as artifact ids).
+ * 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";

package/dist/tools/artifacts.js

@@ -10,10 +10,10 @@ export function registerArtifacts(server, client) {
         path,
         ...(content_type ? { contentType: content_type } : {}),
     })));
-    server.tool("tenki_get_download_url", "Get a short-lived signed URL to download (HTTP GET) a command artifact from a sandbox by its artifact id (e.g. a command's stdout/stderr artifact). Note: the API supports download-by-artifact-id only, not download-by-path.", {
-        session_id: sessionIdSchema,
-        artifact_id: z.string().describe("Artifact id to download (e.g. a command's stdout/stderr artifact)."),
-    }, 
-    // GetArtifactDownloadUrl only accepts an artifact UUID; a `path` is rejected (live-verified).
-    async ({ session_id, artifact_id }) => ok(await client.control("GetArtifactDownloadUrl", { sessionId: session_id, artifactId: artifact_id })));
+    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

@@ -18,13 +18,13 @@ export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "sessi
 export interface CredentialInfo {
     kind: CredentialKind;
     /** Env var the token came from, or undefined when there is none. */
-    source?: "TENKI_AUTH_TOKEN" | "TENKI_API_KEY";
+    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 (`tk_` → Bearer API key,
+ * 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 (TENKI_AUTH_TOKEN wins over TENKI_API_KEY).
+ * index.ts's precedence (LUXORAI_AUTH_TOKEN, LUXORAI_API_KEY, TENKI_AUTH_TOKEN, TENKI_API_KEY).
  */
 export declare function describeCredential(env?: NodeJS.ProcessEnv): CredentialInfo;
 /**

package/dist/tools/auth_status.js

@@ -1,20 +1,19 @@
 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 (`tk_` → Bearer API key,
+ * 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 (TENKI_AUTH_TOKEN wins over TENKI_API_KEY).
+ * index.ts's precedence (LUXORAI_AUTH_TOKEN, LUXORAI_API_KEY, TENKI_AUTH_TOKEN, TENKI_API_KEY).
  */
 export function describeCredential(env = process.env) {
-    const fromToken = env.TENKI_AUTH_TOKEN?.trim();
-    const fromKey = env.TENKI_API_KEY?.trim();
-    const raw = fromToken || fromKey;
-    if (!raw && env.TENKI_MCP_OAUTH_ISSUER?.trim())
+    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" };
-    const source = fromToken ? "TENKI_AUTH_TOKEN" : "TENKI_API_KEY";
-    if (raw.startsWith("tk_"))
+    if (isApiKey(raw))
         return { kind: "api_key", source };
     if (raw.startsWith("ory_st_"))
         return { kind: "oauth_session_token", source };
@@ -64,7 +63,7 @@ export function registerAuthStatus(server, client, toolsRegistered) {
         outputSchema: authOutputSchema,
     }, async () => {
         const cred = describeCredential();
-        const endpoint = process.env.TENKI_API_ENDPOINT || process.env.TENKI_API_URL || "https://api.tenki.cloud";
+        const endpoint = readEnv("API_ENDPOINT", "API_URL") || "https://api.tenki.cloud";
         const base = {
             credential: cred.kind,
             ...(cred.source ? { source: cred.source } : {}),

package/dist/tools/common.d.ts

@@ -8,6 +8,19 @@ export declare const ok: (value: unknown) => {
         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.
@@ -33,3 +46,25 @@ export declare const pathSchema: z.ZodString;
  * 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

@@ -8,6 +8,8 @@ const PUBLIC_KEYS = {
     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) {
@@ -21,6 +23,48 @@ export function publicValue(value) {
 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.
@@ -58,3 +102,37 @@ export const slugSchema = z
     .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 } : {}),
+});

package/dist/tools/egress.d.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { TenkiClient } from "../client.js";
+export declare const policyNameSchema: z.ZodString;
+export declare const httpRuleSchema: z.ZodObject<{
+    domains: z.ZodArray<z.ZodString>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    path_exact: z.ZodOptional<z.ZodString>;
+    path_prefix: z.ZodOptional<z.ZodString>;
+    path_regex: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type HttpRule = z.infer<typeof httpRuleSchema>;
+export declare const httpRuleToWire: (r: HttpRule) => Record<string, unknown>;
+export declare const allowDomainsSchema: z.ZodArray<z.ZodString>;
+export declare const allowCidrsSchema: z.ZodArray<z.ZodString>;
+export declare const interceptHttpsSchema: z.ZodBoolean;
+export declare const httpRulesSchema: z.ZodArray<z.ZodObject<{
+    domains: z.ZodArray<z.ZodString>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    path_exact: z.ZodOptional<z.ZodString>;
+    path_prefix: z.ZodOptional<z.ZodString>;
+    path_regex: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const allowedPortsSchema: z.ZodArray<z.ZodNumber>;
+export interface EgressBody {
+    allow_domains?: string[];
+    allow_cidrs?: string[];
+    intercept_https?: boolean;
+    http_rules?: HttpRule[];
+    allowed_ports?: number[];
+}
+/**
+ * Map an egress body to SessionEgressPolicy JSON. `requireComplete` applies the
+ * checks the API runs on a policy that stands alone; on create they are skipped
+ * when named policies are pinned, because the API merges them first.
+ */
+export declare function egressBodyToWire(tool: string, b: EgressBody, requireComplete: boolean): Record<string, unknown> | undefined;
+export declare function registerEgress(server: McpServer, client: TenkiClient): void;