@luxorai/mcp 0.3.1 → 0.4.0

package/dist/tools/egress.js

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { ok } from "./common.js";
+/**
+ * Named workspace egress policies (tenki-app #6069): reusable egress allowlists
+ * that tenki_create_sandbox pins by name via `egress_policies`. A session keeps
+ * the expansion it was created with; later edits or deletes do not change it.
+ * Wire shape: SessionEgressPolicy { allowDomains, allowCidrs, interceptHttps,
+ * httpRules[{ domains, methods, exact | prefix | regex }], allowedPorts } — the
+ * path oneof members are plain fields on the rule.
+ */
+const POLICY_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,127}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const policyNameSchema = z
+    .string()
+    .regex(POLICY_NAME, "policy names: letters, digits, _ and -, starting with a letter or _, max 128");
+const domainSchema = z.string().min(1).max(253);
+const pathSchema = z.string().min(1).max(2048).regex(/^\//, "paths start with /");
+export const httpRuleSchema = z
+    .object({
+    domains: z
+        .array(domainSchema)
+        .min(1)
+        .max(256)
+        .describe("Hosts the rule applies to: exact names, single-label '*.example.com' wildcards, or '*' for every allowed domain."),
+    methods: z
+        .array(z.string().min(1).max(32))
+        .max(16)
+        .optional()
+        .describe("HTTP methods (e.g. GET, POST; uppercased by the API). Omit to match every method."),
+    path_exact: pathSchema.optional().describe("Match only this escaped path (no query)."),
+    path_prefix: pathSchema.optional().describe("Match paths starting with this prefix."),
+    path_regex: z.string().min(1).max(1024).optional().describe("RE2 regex that must match the whole escaped path (no query)."),
+})
+    .strict()
+    .refine((r) => [r.path_exact, r.path_prefix, r.path_regex].filter((p) => p !== undefined).length <= 1, {
+    message: "set at most one of path_exact, path_prefix, path_regex",
+});
+export const httpRuleToWire = (r) => ({
+    domains: r.domains,
+    ...(r.methods?.length ? { methods: r.methods } : {}),
+    ...(r.path_exact !== undefined ? { exact: r.path_exact } : {}),
+    ...(r.path_prefix !== undefined ? { prefix: r.path_prefix } : {}),
+    ...(r.path_regex !== undefined ? { regex: r.path_regex } : {}),
+});
+export const allowDomainsSchema = z
+    .array(domainSchema)
+    .max(256)
+    .describe("Allowed hosts: exact names or single-label '*.example.com' wildcards (≤256).");
+export const allowCidrsSchema = z
+    .array(z.string().min(1).max(18))
+    .max(64)
+    .describe("Allowed IPv4 prefixes reachable without a name lookup (≤64; not 0.0.0.0/0).");
+export const interceptHttpsSchema = z
+    .boolean()
+    .describe("Terminate port-443 TLS with the sandbox's managed CA so each request's Host is checked; requires at least one allowed domain. With interception on, public egress is limited to TCP 80/443 through the proxy; other ports are blocked unless listed in allowed_ports.");
+export const httpRulesSchema = z
+    .array(httpRuleSchema)
+    .max(64)
+    .describe("Per-host HTTP method/path rules (≤64; requires intercept_https). On ports 80 and 443 a request matching no rule is refused with 403.");
+export const allowedPortsSchema = z
+    .array(z.number().int().min(1).max(65535))
+    .max(64)
+    .describe("Extra public TCP ports to open besides 80/443 (≤64; requires intercept_https). They skip HTTP inspection but still reach only allowed destinations, so 22 permits git over SSH, including pushes.");
+/**
+ * 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 function egressBodyToWire(tool, b, requireComplete) {
+    const domains = b.allow_domains?.length ? b.allow_domains : undefined;
+    const cidrs = b.allow_cidrs?.length ? b.allow_cidrs : undefined;
+    const rules = b.http_rules?.length ? b.http_rules : undefined;
+    const ports = b.allowed_ports?.length ? b.allowed_ports : undefined;
+    if (requireComplete) {
+        if (!domains && !cidrs && (b.intercept_https || rules || ports))
+            throw new Error(`${tool}: an egress policy must list at least one allowed domain or CIDR.`);
+        if (b.intercept_https && !domains)
+            throw new Error(`${tool}: intercept_https requires at least one allowed domain.`);
+        if (rules && !b.intercept_https)
+            throw new Error(`${tool}: http_rules require intercept_https: true (without interception HTTPS requests would bypass them).`);
+        if (ports && !b.intercept_https)
+            throw new Error(`${tool}: allowed_ports require intercept_https: true (without interception other ports already follow the domain and CIDR allowlist).`);
+    }
+    if (!domains && !cidrs && !b.intercept_https && !rules && !ports)
+        return undefined;
+    return {
+        ...(domains ? { allowDomains: domains } : {}),
+        ...(cidrs ? { allowCidrs: cidrs } : {}),
+        ...(b.intercept_https ? { interceptHttps: true } : {}),
+        ...(rules ? { httpRules: rules.map(httpRuleToWire) } : {}),
+        ...(ports ? { allowedPorts: ports } : {}),
+    };
+}
+const workspaceIdSchema = z.string().optional().describe("Workspace (defaults to the key's workspace).");
+const policyRefSchema = z.string().min(1).describe("Policy ID or name.");
+const revisionSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(4294967295)
+    .describe("The policy's current revision (from tenki_get_egress_policy); a stale revision is refused with ABORTED.");
+const ENABLE_NOTE = "Sandboxes cannot pin policies (failed_precondition) if session egress policies are disabled for the workspace (on by default; Tenki staff can turn it off).";
+export function registerEgress(server, client) {
+    const workspace = async (workspace_id) => {
+        const id = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return id ? { workspaceId: id } : {};
+    };
+    const body = (tool, b) => {
+        const egress = egressBodyToWire(tool, b, true);
+        if (!egress)
+            throw new Error(`${tool}: an egress policy must list at least one allowed domain or CIDR.`);
+        return egress;
+    };
+    server.tool("tenki_create_egress_policy", `Save a named egress policy (allowed domains/CIDRs, optional HTTPS interception, per-host HTTP rules and extra ports) in the workspace, for tenki_create_sandbox's egress_policies to pin by name. ${ENABLE_NOTE}`, {
+        name: policyNameSchema.refine((n) => !UUID.test(n), "a policy name must not be a UUID").describe("Policy name (letters, digits, _ and -; not a UUID). Exact, never trimmed."),
+        allow_domains: allowDomainsSchema.optional(),
+        allow_cidrs: allowCidrsSchema.optional(),
+        intercept_https: interceptHttpsSchema.optional(),
+        http_rules: httpRulesSchema.optional(),
+        allowed_ports: allowedPortsSchema.optional(),
+        workspace_id: workspaceIdSchema,
+    }, async ({ name, workspace_id, ...b }) => ok(await client.control("CreateEgressPolicy", { ...(await workspace(workspace_id)), name, egress: body("tenki_create_egress_policy", b) })));
+    server.tool("tenki_update_egress_policy", "Replace a named egress policy's rules (the whole body; omitted fields are cleared). Requires the current revision. Sandboxes created earlier keep the rules they were created with.", {
+        policy_id: policyRefSchema,
+        expected_revision: revisionSchema,
+        allow_domains: allowDomainsSchema.optional(),
+        allow_cidrs: allowCidrsSchema.optional(),
+        intercept_https: interceptHttpsSchema.optional(),
+        http_rules: httpRulesSchema.optional(),
+        allowed_ports: allowedPortsSchema.optional(),
+        workspace_id: workspaceIdSchema,
+    }, async ({ policy_id, expected_revision, workspace_id, ...b }) => ok(await client.control("UpdateEgressPolicy", {
+        ...(await workspace(workspace_id)),
+        policyId: policy_id,
+        expectedRevision: expected_revision,
+        egress: body("tenki_update_egress_policy", b),
+    })));
+    server.tool("tenki_get_egress_policy", "Get one named egress policy by ID or name: its rules, current revision, and how many non-terminated sandboxes pinned it.", { policy_id: policyRefSchema, workspace_id: workspaceIdSchema }, async ({ policy_id, workspace_id }) => ok(await client.control("GetEgressPolicy", { ...(await workspace(workspace_id)), policyId: policy_id })));
+    server.tool("tenki_list_egress_policies", "List the workspace's named egress policies, ordered by name. Pass next_cursor back as cursor for the next page.", {
+        page_size: z.number().int().min(1).max(100).optional().describe("Max policies per page (≤100, default 50)."),
+        cursor: z.string().optional().describe("next_cursor from the previous page."),
+        workspace_id: workspaceIdSchema,
+    }, async ({ page_size, cursor, workspace_id }) => ok(await client.control("ListEgressPolicies", {
+        ...(await workspace(workspace_id)),
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(cursor ? { cursor } : {}),
+    })));
+    server.tool("tenki_delete_egress_policy", "Delete a named egress policy (requires its current revision). New sandboxes can no longer pin it; sandboxes that already pinned it keep its rules.", { policy_id: policyRefSchema, expected_revision: revisionSchema, workspace_id: workspaceIdSchema }, async ({ policy_id, expected_revision, workspace_id }) => ok(await client.control("DeleteEgressPolicy", {
+        ...(await workspace(workspace_id)),
+        policyId: policy_id,
+        expectedRevision: expected_revision,
+    })));
+}

package/dist/tools/exec.js

@@ -87,7 +87,7 @@ export function registerExec(server, client) {
             args: z.array(z.string()).optional().describe("Arguments."),
             cwd: z.string().optional().describe("Working directory (honored in-script)."),
             env: envSchema,
-            timeout_seconds: z.number().int().positive().optional(),
+            timeout_seconds: z.number().int().positive().optional().describe("Maximum seconds the command may run before it is stopped; omit to use the API's default."),
             max_output_bytes: z
                 .number()
                 .int()

package/dist/tools/files.js

@@ -1,9 +1,42 @@
 import { z } from "zod";
-import { ok, pathSchema, sessionIdSchema } from "./common.js";
+import { ok, pathSchema, sessionIdSchema, utf8CharEnd, utf8CharStart } from "./common.js";
+// Inline read budget, matching tenki_exec's per-stream default. The data
+// plane's ReadFile has no range support, so the whole file still crosses the
+// wire to this process; the cap bounds what is returned to the model.
+const DEFAULT_READ_BYTES = 65_536;
+const MAX_READ_BYTES = 1_048_576;
 /** Filesystem I/O against a sandbox's data plane. */
 export function registerFiles(server, client) {
-    server.tool("tenki_read_file", "Read a UTF-8 text file from a sandbox (paths under /home/tenki).", { session_id: sessionIdSchema, path: pathSchema }, async ({ session_id, path }) => ok({ path, content: await client.readTextFile(session_id, path) }));
-    server.tool("tenki_write_file", "Write a UTF-8 text file to a sandbox (paths under /home/tenki).", { session_id: sessionIdSchema, path: pathSchema, content: z.string() }, async ({ session_id, path, content }) => ok(await client.writeTextFile(session_id, path, content)));
+    server.tool("tenki_read_file", "Read a UTF-8 text file from a sandbox (paths under /home/tenki). Returns at most max_bytes (default 65536) starting at offset, plus the file's totalBytes; when more remains the response has truncated: true and nextOffset — pass it as offset to read the next part.", {
+        session_id: sessionIdSchema,
+        path: pathSchema,
+        offset: z.number().int().min(0).optional().describe("Byte offset to start reading at (default 0). Use nextOffset from a truncated response."),
+        max_bytes: z
+            .number()
+            .int()
+            .min(1024)
+            .max(MAX_READ_BYTES)
+            .optional()
+            .describe(`Maximum bytes of content to return (default ${DEFAULT_READ_BYTES}, max ${MAX_READ_BYTES}). Cuts never split a UTF-8 character.`),
+    }, async ({ session_id, path, offset, max_bytes }) => {
+        const buf = await client.readFileBytes(session_id, path);
+        const totalBytes = buf.length;
+        const requested = offset ?? 0;
+        if (requested > totalBytes) {
+            throw new Error(`offset ${requested} is past the end of ${path} (${totalBytes} bytes).`);
+        }
+        const start = utf8CharStart(buf, requested);
+        const end = utf8CharEnd(buf, start, start + (max_bytes ?? DEFAULT_READ_BYTES));
+        const truncated = end < totalBytes;
+        return ok({
+            path,
+            content: buf.subarray(start, end).toString("utf8"),
+            totalBytes,
+            ...(start > 0 || truncated ? { offset: start, bytesReturned: end - start } : {}),
+            ...(truncated ? { truncated: true, nextOffset: end } : {}),
+        });
+    });
+    server.tool("tenki_write_file", "Write a UTF-8 text file to a sandbox (paths under /home/tenki), creating it or replacing its entire contents.", { session_id: sessionIdSchema, path: pathSchema, content: z.string().describe("Full text to write; an existing file is overwritten.") }, async ({ session_id, path, content }) => ok(await client.writeTextFile(session_id, path, content)));
     server.tool("tenki_list_files", "List a directory in a sandbox, including dotfiles (.git, .env, .gitignore) by default — set include_hidden false to omit them.", {
         session_id: sessionIdSchema,
         path: pathSchema.describe("Directory path, e.g. /home/tenki"),

package/dist/tools/files_ops.js

@@ -18,9 +18,17 @@ export function registerFilesOps(server, client) {
         session_id: sessionIdSchema,
         path: pathSchema.describe("Directory path under /home/tenki, e.g. /home/tenki/project/out"),
         recursive: z.boolean().optional().describe("Create parent directories as needed (default false)."),
-    }, async ({ session_id, path, recursive }) => ok(await client.data(session_id, "Mkdir", {
+        mode: z
+            .number()
+            .int()
+            .min(0)
+            .max(0o7777)
+            .optional()
+            .describe("Permission bits as a number (e.g. 448 for 0700). Default: the sandbox user's umask."),
+    }, async ({ session_id, path, recursive, mode }) => ok(await client.data(session_id, "Mkdir", {
         path,
         ...(recursive ? { recursive: true } : {}),
+        ...(mode !== undefined ? { mode } : {}),
     })));
     server.tool("tenki_remove_path", "Delete a file or directory in a sandbox. Set recursive to remove a non-empty directory and its contents (rm -r).", {
         session_id: sessionIdSchema,

package/dist/tools/git.d.ts

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

package/dist/tools/git.js

@@ -1,30 +1,92 @@
 import { z } from "zod";
-import { ok, sessionIdSchema } from "./common.js";
+import { capText, ok, sessionIdSchema } from "./common.js";
 /**
- * The API validates `operation` against exactly this list (GitOperationRequest's
- * buf.validate `in` constraint) and the engine implements exactly these four —
- * anything else (status/add/commit/push/...) is rejected server-side. For other
- * git commands, run `git ...` via tenki_exec.
+ * Git inside a sandbox, one tool per operation. The API exposes a single
+ * GitOperation RPC whose `operation` must be clone, checkout, diff or log
+ * (GitOperationRequest's buf.validate `in` list) with a string→string args map;
+ * these tools give each operation typed arguments and an accurate read/write
+ * classification (diff/log are reads, clone/checkout change the filesystem).
+ * For any other git command (status, add, commit, push, ...) use tenki_exec.
+ *
+ * Arg keys are the ones the engine reads (tenki-app
+ * backend/internal/domain/sandbox/service/git_operation.go, buildGitOperationArgs):
+ * checkout/diff/log run `git -C <directory>` when `directory` is set — without
+ * it they run in /home/tenki, which is not a repository unless one was cloned
+ * there. Values are argv to the engine's command, never a shell string.
+ *
+ * The engine places repo, branch, directory, ref, range, base and head in
+ * git's argv without `--end-of-options`, so a value starting with `-` would be
+ * parsed as an option: `git diff --output=<file>` truncates a file and
+ * `git clone --upload-pack=<cmd>` runs a command. Those values are refused
+ * here — which is also what keeps tenki_git_diff / tenki_git_log read-only.
+ * `path` is safe: the engine always puts it after `--`.
  */
-const GIT_OPERATIONS = ["clone", "checkout", "diff", "log"];
-/** Git operations inside a sandbox (one RPC dispatched by operation string). */
+// Inline output budget, matching tenki_exec and tenki_read_file.
+const MAX_OUTPUT_BYTES = 65_536;
+// The engine re-trims each value with Go's strings.TrimSpace, which also strips
+// U+0085 (NEL) — JavaScript's trim() and \s do not — so "\u0085--output=x"
+// would reach git as "--output=x". Refuse a '-' behind any such whitespace.
+const noOption = (s) => !/^[\s\u0085]*-/.test(s);
+const NO_OPTION_MSG = "must not start with '-' (git would read it as an option)";
+/** A value the engine passes to git as a bare argument. */
+const gitArg = (description) => z.string().trim().min(1).refine(noOption, NO_OPTION_MSG).describe(description);
+const directorySchema = gitArg("Repository directory in the sandbox, e.g. /home/tenki/myrepo (relative paths resolve from /home/tenki). Omit only if the repository is /home/tenki itself.").optional();
+/** How to get less output, per operation (only diff/log take narrowing args). */
+const NARROW = {
+    diff: "Narrow it with path or range/base/head, or run git through tenki_exec and page its output.",
+    log: "Narrow it with max_count, path or range, or run git through tenki_exec and page its output.",
+};
+const NARROW_DEFAULT = "Run git through tenki_exec to page the full output.";
+async function gitOperation(client, sessionId, operation, args) {
+    const stringArgs = Object.fromEntries(Object.entries(args)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => [k, String(v)]));
+    const resp = await client.control("GitOperation", { sessionId, operation, args: stringArgs });
+    if (typeof resp?.output !== "string")
+        return ok(resp);
+    const capped = capText(resp.output, MAX_OUTPUT_BYTES);
+    if (!capped.truncated)
+        return ok(resp);
+    return ok({
+        ...resp,
+        output: capped.text,
+        truncated: true,
+        totalBytes: capped.totalBytes,
+        note: `Output truncated to ${MAX_OUTPUT_BYTES} bytes. ${NARROW[operation] ?? NARROW_DEFAULT}`,
+    });
+}
 export function registerGit(server, client) {
-    server.tool("tenki_git", "Run a git operation in a sandbox. Only clone, checkout, diff, and log are supported by the API — for any other git command (status, add, commit, push, ...) use tenki_exec with `git ...`. " +
-        "clone arg keys: repo (required, the URL), branch?, depth?, directory?. " +
-        "CAVEAT (live-verified): checkout/diff/log run in the session's working directory (/home/tenki), which is not a repository and has no directory arg — so on a repo cloned into a subdirectory they fail with 'not a git repository'. Use tenki_exec with `git -C <directory> ...` instead (e.g. `git -C /home/tenki/hw log -n 2`). " +
-        "For reference, their arg keys are — checkout: ref (required), create? ('true' = -b); diff: range? or base?+head?, path?; log: max_count?, range?, path?.", {
+    server.tool("tenki_git_clone", "Clone a git repository into a sandbox and return git's output. The target directory must not already exist or must be empty. For other git commands (status, add, commit, push, ...) use tenki_exec with `git ...`.", {
+        session_id: sessionIdSchema,
+        repo: gitArg("Repository URL to clone, e.g. https://github.com/octocat/Hello-World."),
+        branch: gitArg("Branch or tag to check out after cloning (git clone --branch).").optional(),
+        depth: z.number().int().positive().optional().describe("Create a shallow clone with this many commits (git clone --depth)."),
+        directory: gitArg("Directory to clone into, e.g. /home/tenki/myrepo. Defaults to the repository name under /home/tenki.").optional(),
+    }, async ({ session_id, repo, branch, depth, directory }) => gitOperation(client, session_id, "clone", { repo, branch, depth, directory }));
+    server.tool("tenki_git_checkout", "Check out a branch, tag or commit in a repository inside a sandbox (git checkout), optionally creating a new branch. Changes the files in the working tree.", {
         session_id: sessionIdSchema,
-        operation: z.enum(GIT_OPERATIONS).describe("One of: clone, checkout, diff, log (the API rejects anything else)."),
-        // The wire type is map<string,string>, but the values models most want
-        // to send as numbers or booleans (depth, max_count, create) are
-        // accepted here and coerced — a client-side rejection of `create: true`
-        // for a call that would serialize identically helps nobody.
-        args: z
-            .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
-            .optional()
-            .describe("Operation args as a key→value object (values are sent as strings; numbers/booleans are coerced). clone: {repo, branch?, depth?, directory?}; checkout: {ref, create?: 'true'}; diff: {range?} or {base?, head?}, {path?}; log: {max_count?, range?, path?}."),
-    }, async ({ session_id, operation, args }) => {
-        const stringArgs = args ? Object.fromEntries(Object.entries(args).map(([k, v]) => [k, String(v)])) : undefined;
-        return ok(await client.control("GitOperation", { sessionId: session_id, operation, ...(stringArgs ? { args: stringArgs } : {}) }));
+        ref: gitArg("Branch, tag or commit to check out, or the name of the branch to create when create is true."),
+        create: z.boolean().optional().describe("Create ref as a new branch from the current HEAD (git checkout -b). Default false."),
+        directory: directorySchema,
+    }, async ({ session_id, ref, create, directory }) => gitOperation(client, session_id, "checkout", { ref, create: create ? "true" : undefined, directory }));
+    server.tool("tenki_git_diff", `Show a diff for a repository inside a sandbox (git diff): unstaged working-tree changes by default, or between refs. Read-only. Output over ${MAX_OUTPUT_BYTES} bytes is truncated.`, {
+        session_id: sessionIdSchema,
+        range: gitArg("Revision range, e.g. main..feature or HEAD~3. Cannot be combined with base/head.").optional(),
+        base: gitArg("Base ref to diff from (with head: git diff base..head; alone: git diff base).").optional(),
+        head: gitArg("Head ref to diff to (with base: git diff base..head; alone: git diff head).").optional(),
+        path: z.string().trim().min(1).optional().describe("Limit the diff to this file or directory, relative to the repository root."),
+        directory: directorySchema,
+    }, async ({ session_id, range, base, head, path, directory }) => {
+        if (range !== undefined && (base !== undefined || head !== undefined)) {
+            throw new Error("tenki_git_diff: pass either range or base/head, not both.");
+        }
+        return gitOperation(client, session_id, "diff", { range, base, head, path, directory });
     });
+    server.tool("tenki_git_log", `Show commit history for a repository inside a sandbox (git log). Read-only. Output over ${MAX_OUTPUT_BYTES} bytes is truncated.`, {
+        session_id: sessionIdSchema,
+        max_count: z.number().int().positive().max(1000).optional().describe("Maximum number of commits to show (git log --max-count). Set this to keep output small."),
+        range: gitArg("Revision range, e.g. main..feature.").optional(),
+        path: z.string().trim().min(1).optional().describe("Only commits touching this file or directory, relative to the repository root."),
+        directory: directorySchema,
+    }, async ({ session_id, max_count, range, path, directory }) => gitOperation(client, session_id, "log", { max_count, range, path, directory }));
 }

package/dist/tools/ports.d.ts

@@ -1,4 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "../client.js";
-/** Port exposure / preview URLs. */
+/**
+ * Port exposure. ExposePort / ListExposedPorts (and UnexposePort in previews.ts)
+ * are marked deprecated upstream (tenki-app #5663, 2026-09-15) in favour of the
+ * preview-URL RPCs; they still work — ExposePort now creates a preview URL and
+ * auto-mints a slug when none is given, which CreatePreviewUrl cannot do (slug
+ * is required there). Kept as the convenience path; descriptions steer callers
+ * who already have a slug to tenki_create_preview_url.
+ */
 export declare function registerPorts(server: McpServer, client: TenkiClient): void;

package/dist/tools/ports.js

@@ -1,6 +1,27 @@
+import { z } from "zod";
 import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
-/** Port exposure / preview URLs. */
+/**
+ * Port exposure. ExposePort / ListExposedPorts (and UnexposePort in previews.ts)
+ * are marked deprecated upstream (tenki-app #5663, 2026-09-15) in favour of the
+ * preview-URL RPCs; they still work — ExposePort now creates a preview URL and
+ * auto-mints a slug when none is given, which CreatePreviewUrl cannot do (slug
+ * is required there). Kept as the convenience path; descriptions steer callers
+ * who already have a slug to tenki_create_preview_url.
+ */
 export function registerPorts(server, client) {
-    server.tool("tenki_expose_port", "Expose a port from a sandbox and get a public preview URL. Useful when an agent starts a web server it wants to show.", { session_id: sessionIdSchema, port: portSchema, slug: slugSchema.optional() }, async ({ session_id, port, slug }) => ok(await client.control("ExposePort", { sessionId: session_id, port, ...(slug ? { slug } : {}) })));
-    server.tool("tenki_list_exposed_ports", "List the ports currently exposed from a sandbox.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("ListExposedPorts", { sessionId: session_id })));
+    server.tool("tenki_expose_port", "Expose a port from a sandbox and get a public preview URL (a slug is auto-generated unless you pass one). Useful when an agent starts a web server it wants to show. Requires allow_inbound. The API marks ExposePort deprecated in favour of CreatePreviewUrl — if you already have a slug, prefer tenki_create_preview_url; to take the URL down use tenki_unbind_preview_url / tenki_delete_preview_url with the returned previewUrlId.", {
+        session_id: sessionIdSchema,
+        port: portSchema,
+        slug: slugSchema.optional(),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("Optional RFC-3339 timestamp at which the preview URL auto-expires. Omit to keep it until the sandbox ends."),
+    }, async ({ session_id, port, slug, expires_at }) => ok(await client.control("ExposePort", {
+        sessionId: session_id,
+        port,
+        ...(slug ? { slug } : {}),
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
+    server.tool("tenki_list_exposed_ports", "List the ports currently exposed from a sandbox. DEPRECATED upstream (ListExposedPorts): prefer tenki_list_preview_urls with session_id, which lists the same bindings with their ids, slugs and expiry.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("ListExposedPorts", { sessionId: session_id })));
 }

package/dist/tools/previews.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
-import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
+import { listQuery, ok, portSchema, protoEnum, searchSchema, sessionIdSchema, slugSchema } from "./common.js";
+/** The sandbox web terminal (ttyd) port — tenki-app previewports.WebTerminalPort. */
+const WEB_TERMINAL_PORT = 7681;
 export function registerPreviews(server, client) {
     // ── Unexpose a port (tear down its exposure + preview) ────────────────────────
-    server.tool("tenki_unexpose_port", "Remove an inbound port exposure from a sandbox, taking its public URL/preview offline. Use this to un-publish a port previously exposed with tenki_expose_port.", {
+    server.tool("tenki_unexpose_port", "Remove an inbound port exposure from a sandbox, unbinding EVERY preview URL on that port and taking them offline. DEPRECATED upstream (UnexposePort): to take one specific preview URL offline use tenki_unbind_preview_url or tenki_delete_preview_url with its id.", {
         session_id: sessionIdSchema.describe("The sandbox session whose port to unexpose."),
         port: portSchema.describe("The TCP port inside the sandbox to unexpose (1-65535)."),
     }, async ({ session_id, port }) => ok(await client.control("UnexposePort", { sessionId: session_id, port })));
@@ -21,10 +23,20 @@ export function registerPreviews(server, client) {
         slug,
         ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
     })));
-    // ── Open (get) a live preview for a port ──────────────────────────────────────
-    server.tool("tenki_open_preview", "Open a viewer-token-gated (AUTHENTICATED-mode) preview. USE tenki_expose_port OR tenki_create_preview_url INSTEAD for an ordinary web server: for any port other than the web terminal (7681) the API deliberately returns a non-regional fallback host that currently has no edge route, so the URL 404s (live-verified). The returned viewerToken does resolve via tenki_resolve_preview_token; only the URL is unreachable. Requires allow_inbound.", {
-        session_id: sessionIdSchema.describe("The sandbox session serving the port."),
-        port: portSchema.describe("The TCP port inside the sandbox to open a preview for (1-65535)."),
+    // ── Open a viewer-token-gated (authenticated) preview of a port ──────────────
+    // OpenPreview creates an AUTHENTICATED-mode preview. The API resolves a
+    // regional edge URL for the web terminal port (7681); any other port, and any
+    // sandbox with runtime secrets, gets the authenticated fallback domain served
+    // by the sandbox gateway, for which it registers a gateway route
+    // (resolveAuthenticatedPreviewURLForPort / registerAuthenticatedGatewayPreview
+    // in tenki-app backend/internal/domain/sandbox/service/port.go). An earlier
+    // description claimed those fallback URLs 404; that was not reproducible
+    // from the current code or production config and was dropped — confirm with
+    // a live OpenPreview on a non-terminal port. It replaces any earlier
+    // authenticated preview on the same port (deleteAuthenticatedPreviewExposures).
+    server.tool("tenki_open_preview", `Open a viewer-token-gated preview of a port in a sandbox and return its URL and viewer token; unlike tenki_expose_port and tenki_create_preview_url, the URL is not public. Port ${WEB_TERMINAL_PORT} is the sandbox's browser web terminal (ttyd, in the standard images). Requires a sandbox created with allow_inbound; port 22 is reserved. Opening the same port again replaces its earlier preview URL.`, {
+        session_id: sessionIdSchema.describe("The sandbox serving the port."),
+        port: portSchema.describe(`The TCP port inside the sandbox to open a preview for (1-65535, not 22). ${WEB_TERMINAL_PORT} opens the web terminal.`),
         expires_at: z
             .string()
             .optional()
@@ -35,34 +47,50 @@ export function registerPreviews(server, client) {
         ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
     })));
     // ── List the preview URLs bound to a sandbox / project ────────────────────────
-    server.tool("tenki_list_preview_urls", "List the workspace's preview URLs, newest page first. Pass session_id to keep only the ones bound to that sandbox (filtered here, not server-side — so it applies to the page you fetched; raise page_size or follow next_page_token to widen it). Results are paginated: a nextPageToken in the response means more pages exist.", {
-        session_id: sessionIdSchema
+    server.tool("tenki_list_preview_urls", "List the workspace's preview URLs with server-side search, binding-state filter, sorting and optional state-count facets; each row carries the bound sandbox's sessionState and sessionName. Pass session_id to list only the ones bound to that sandbox. Paginated: a nextPageToken in the response means more pages exist.", {
+        session_id: sessionIdSchema.optional().describe("Only preview URLs bound to this sandbox."),
+        search: searchSchema.describe("Free-text search over slug/id (max 256 chars)."),
+        states: z
+            .array(z.enum(["UNBOUND", "BOUND", "OFFLINE", "ORPHANED"]))
+            .max(16)
             .optional()
-            .describe("Keep only preview URLs bound to this sandbox. Applied client-side to the fetched page."),
+            .describe("Only preview URLs in any of these binding states (OFFLINE = bound to a non-running sandbox, ORPHANED = bound to a sandbox that no longer exists)."),
+        sort_by: z.enum(["SLUG", "STATE", "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."),
         workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
         page_size: z.number().int().min(1).max(100).optional().describe("Rows per page (server default 20, max 100)."),
         page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
-    }, async ({ session_id, workspace_id, page_size, page_token }) => {
-        // The RPC has no sessionId field (ListPreviewUrlsRequest: workspace_id,
-        // page_size, page_token), so a sessionId sent
-        // on the wire is silently discarded and every session's rows come back.
-        // Filter here instead of advertising a filter that does nothing.
-        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+    }, async ({ session_id, search, states, sort_by, sort_desc, include_facets, workspace_id, page_size, page_token }) => {
+        // ListPreviewUrlsRequest.session_id (field 5) filters server-side and already
+        // scopes the query, so the WhoAmI lookup for a default workspace is skipped then.
+        const workspaceId = workspace_id ?? (session_id ? undefined : (await client.resolveOwner()).workspaceId);
         const resp = await client.control("ListPreviewUrls", {
             ...(workspaceId ? { workspaceId } : {}),
+            ...(session_id ? { sessionId: session_id } : {}),
+            ...(states && states.length ? { states: states.map((s) => protoEnum("PREVIEW_URL_BINDING_STATE", s)) } : {}),
+            ...(sort_by ? { sortBy: protoEnum("PREVIEW_URL_SORT_FIELD", sort_by) } : {}),
+            ...listQuery(search, include_facets, sort_desc),
             ...(page_size !== undefined ? { pageSize: page_size } : {}),
             ...(page_token ? { pageToken: page_token } : {}),
         });
-        const rows = Array.isArray(resp.previewUrls) ? resp.previewUrls : [];
-        const filtered = session_id ? rows.filter((r) => r?.sessionId === session_id) : rows;
+        // proto3 omits an empty repeated field; normalize so an empty page is an array.
         return ok({
-            previewUrls: filtered,
+            previewUrls: Array.isArray(resp.previewUrls) ? resp.previewUrls : [],
             ...(resp.nextPageToken ? { nextPageToken: resp.nextPageToken } : {}),
-            ...(session_id ? { filteredClientSide: true, fetchedOnThisPage: rows.length } : {}),
+            ...(resp.facets ? { facets: resp.facets } : {}),
         });
     });
     // ── Get / delete a specific preview URL ───────────────────────────────────────
-    server.tool("tenki_get_preview_url", "Fetch a specific preview URL's details by id.", { preview_url_id: z.string().describe("The preview URL id.") }, async ({ preview_url_id }) => ok(await client.control("GetPreviewUrl", { previewUrlId: preview_url_id })));
+    server.tool("tenki_get_preview_url", "Fetch a specific preview URL's details by id OR by slug (pass exactly one).", {
+        preview_url_id: z.string().min(1).optional().describe("The preview URL id."),
+        slug: slugSchema.optional().describe("The preview URL's slug (alternative to preview_url_id)."),
+    }, async ({ preview_url_id, slug }) => {
+        if ((preview_url_id === undefined) === (slug === undefined)) {
+            throw new Error("tenki_get_preview_url: pass exactly one of preview_url_id or slug.");
+        }
+        return ok(await client.control("GetPreviewUrl", preview_url_id ? { previewUrlId: preview_url_id } : { slug }));
+    });
     server.tool("tenki_delete_preview_url", "Delete a preview URL by id, taking it permanently offline.", { preview_url_id: z.string().describe("The preview URL id to delete.") }, async ({ preview_url_id }) => ok(await client.control("DeletePreviewUrl", { previewUrlId: preview_url_id })));
     // ── Touch (keep-alive) a preview ──────────────────────────────────────────────
     server.tool("tenki_touch_preview", "Refresh (keep-alive) a live preview by its preview token so it isn't torn down as idle.", { preview_token: z.string().describe("The preview token (from create_preview_url / open_preview).") }, 
@@ -70,11 +98,20 @@ export function registerPreviews(server, client) {
     async ({ preview_token }) => ok(await client.control("TouchPreview", { previewToken: preview_token })));
     // ── Bind / unbind a named preview URL to a session+port ───────────────────────
     // Advanced routing primitives (shapes SDK-name-verified; not exercised end-to-end here).
-    server.tool("tenki_bind_preview_url", "Bind a named preview URL to a sandbox session and port (advanced routing).", {
+    server.tool("tenki_bind_preview_url", "Bind a named preview URL to a sandbox session and port (advanced routing). A URL whose expiry has lapsed can only be re-bound with a new expires_at.", {
         preview_url_id: z.string().describe("The preview URL id to bind."),
         session_id: sessionIdSchema,
         port: portSchema.describe("The port to route the preview URL to."),
-    }, async ({ preview_url_id, session_id, port }) => ok(await client.control("BindPreviewUrl", { previewUrlId: preview_url_id, sessionId: session_id, port })));
+        expires_at: z
+            .string()
+            .optional()
+            .describe("Optional RFC-3339 timestamp replacing the URL's expiry deadline (required when re-binding a lapsed URL)."),
+    }, async ({ preview_url_id, session_id, port, expires_at }) => ok(await client.control("BindPreviewUrl", {
+        previewUrlId: preview_url_id,
+        sessionId: session_id,
+        port,
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
     server.tool("tenki_unbind_preview_url", "Unbind a named preview URL from its current session/port (advanced routing).", { preview_url_id: z.string().describe("The preview URL id to unbind.") }, async ({ preview_url_id }) => ok(await client.control("UnbindPreviewUrl", { previewUrlId: preview_url_id })));
     server.tool("tenki_resolve_preview_token", "Resolve a preview token to the sandbox/port it points at (advanced).", { token: z.string().describe("The preview token to resolve.") }, async ({ token }) => ok(await client.control("ResolvePreviewToken", { token })));
 }

package/dist/tools/sandboxes.d.ts

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