@tenkicloud/mcp 0.3.2-canary.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +42 -1
  2. package/README.md +88 -79
  3. package/SECURITY.md +2 -2
  4. package/dist/client.d.ts +16 -1
  5. package/dist/client.js +62 -16
  6. package/dist/env.d.ts +6 -0
  7. package/dist/env.js +25 -0
  8. package/dist/http.js +13 -10
  9. package/dist/index.js +9 -8
  10. package/dist/oauth.d.ts +7 -1
  11. package/dist/oauth.js +29 -9
  12. package/dist/server.d.ts +25 -5
  13. package/dist/server.js +88 -53
  14. package/dist/tools/artifacts.d.ts +3 -3
  15. package/dist/tools/artifacts.js +6 -6
  16. package/dist/tools/auth_status.d.ts +3 -3
  17. package/dist/tools/auth_status.js +8 -9
  18. package/dist/tools/common.d.ts +35 -0
  19. package/dist/tools/common.js +78 -0
  20. package/dist/tools/egress.d.ts +38 -0
  21. package/dist/tools/egress.js +153 -0
  22. package/dist/tools/exec.js +1 -1
  23. package/dist/tools/files.js +36 -3
  24. package/dist/tools/files_ops.js +9 -1
  25. package/dist/tools/git.d.ts +0 -1
  26. package/dist/tools/git.js +85 -23
  27. package/dist/tools/ports.d.ts +8 -1
  28. package/dist/tools/ports.js +24 -3
  29. package/dist/tools/previews.js +59 -22
  30. package/dist/tools/sandboxes.d.ts +1 -1
  31. package/dist/tools/sandboxes.js +342 -26
  32. package/dist/tools/sessions_admin.js +63 -23
  33. package/dist/tools/snapshots.js +41 -22
  34. package/dist/tools/ssh.d.ts +3 -3
  35. package/dist/tools/ssh.js +35 -9
  36. package/dist/tools/templates.d.ts +2 -1
  37. package/dist/tools/templates.js +36 -16
  38. package/dist/tools/titles.d.ts +8 -0
  39. package/dist/tools/titles.js +102 -0
  40. package/dist/tools/volumes.js +36 -11
  41. package/dist/tools/workspace.d.ts +9 -1
  42. package/dist/tools/workspace.js +29 -90
  43. package/package.json +12 -8
@@ -8,6 +8,19 @@ export declare const ok: (value: unknown) => {
8
8
  text: string;
9
9
  }[];
10
10
  };
11
+ /** First index ≥ i that starts a character: i itself unless i is inside one, then that character's end. */
12
+ export declare function utf8CharStart(buf: Buffer, i: number): number;
13
+ /** Largest end ≤ limit that does not split a character; always > start when limit > start. */
14
+ export declare function utf8CharEnd(buf: Buffer, start: number, limit: number): number;
15
+ /**
16
+ * Cap a text field at maxBytes without splitting a UTF-8 character. Returns the
17
+ * text unchanged when it fits; otherwise the head plus the original size.
18
+ */
19
+ export declare function capText(text: string, maxBytes: number): {
20
+ text: string;
21
+ truncated: boolean;
22
+ totalBytes: number;
23
+ };
11
24
  /** Shared env-map schema used by tools that accept environment variables. */
12
25
  export declare const envSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
13
26
  /** Shared session-id schema — every per-sandbox tool takes one of these.
@@ -33,3 +46,25 @@ export declare const pathSchema: z.ZodString;
33
46
  * those stay server-side.
34
47
  */
35
48
  export declare const slugSchema: z.ZodString;
49
+ /**
50
+ * Shared tag-list schema, matching the API's repeated-string constraint on
51
+ * sessions, snapshots, volumes and templates: ≤20 tags, each ≤32 chars of
52
+ * [a-z0-9_:.-] starting with a letter or digit.
53
+ */
54
+ export declare const tagsSchema: z.ZodOptional<z.ZodArray<z.ZodString>>;
55
+ /**
56
+ * Wire mapping for the tags/clear_tags pair shared by sessions, snapshots and
57
+ * volumes. proto3 drops an empty repeated field, so `[]` becomes clear_tags;
58
+ * a non-empty list together with clear_tags is rejected because the server
59
+ * applies clear_tags first and would silently discard the list.
60
+ */
61
+ export declare function tagsPatch(tags?: string[], clearTags?: boolean): {
62
+ tags?: string[];
63
+ clearTags?: true;
64
+ };
65
+ /** Free-text search across a list (server-side; API max 256 chars). */
66
+ export declare const searchSchema: z.ZodOptional<z.ZodString>;
67
+ /** Prefix a bare enum name the way protobuf JSON expects it (e.g. RUNNING → SESSION_STATE_RUNNING). */
68
+ export declare const protoEnum: (prefix: string, value: string) => string;
69
+ /** Common server-side list options shared by the sandbox, volume, template and preview-URL lists. */
70
+ export declare const listQuery: (search?: string, includeFacets?: boolean, sortDesc?: boolean) => Record<string, unknown>;
@@ -8,6 +8,8 @@ const PUBLIC_KEYS = {
8
8
  source_registry_workspace_id: "source_image_workspace_id",
9
9
  sourceRegistryRef: "sourceImage",
10
10
  source_registry_ref: "source_image",
11
+ registryImageName: "publishedImageName",
12
+ registry_image_name: "published_image_name",
11
13
  };
12
14
  /** Keep registry-backed implementation fields out of public MCP responses. */
13
15
  export function publicValue(value) {
@@ -21,6 +23,48 @@ export function publicValue(value) {
21
23
  export const ok = (value) => ({
22
24
  content: [{ type: "text", text: JSON.stringify(publicValue(value), null, 2) }],
23
25
  });
26
+ // UTF-8 boundary handling for byte-capped text. A position is "inside a
27
+ // character" only when a lead byte at most 3 bytes before it declares a
28
+ // sequence long enough to cover it. Stray continuation bytes (binary data,
29
+ // invalid UTF-8) are not inside anything, so a cut lands exactly there. Start
30
+ // and end use the same rule, so consecutive pages tile the file with no gap or
31
+ // overlap, on valid UTF-8 and on binary alike.
32
+ const isContinuation = (b) => (b & 0xc0) === 0x80;
33
+ /** Sequence length a lead byte declares (1 for ASCII and invalid leads). */
34
+ const utf8SeqLen = (b) => (b >= 0xf0 && b <= 0xf7 ? 4 : b >= 0xe0 && b <= 0xef ? 3 : b >= 0xc0 && b <= 0xdf ? 2 : 1);
35
+ /** Start of the character covering i, or -1 when i is a character start or a stray byte. */
36
+ function coveringLead(buf, i, floor) {
37
+ if (i >= buf.length || !isContinuation(buf[i]))
38
+ return -1;
39
+ for (let back = 1; back <= 3 && i - back >= floor; back++) {
40
+ const b = buf[i - back];
41
+ if (!isContinuation(b))
42
+ return utf8SeqLen(b) > back ? i - back : -1;
43
+ }
44
+ return -1;
45
+ }
46
+ /** First index ≥ i that starts a character: i itself unless i is inside one, then that character's end. */
47
+ export function utf8CharStart(buf, i) {
48
+ const lead = coveringLead(buf, i, 0);
49
+ return lead < 0 ? i : Math.min(lead + utf8SeqLen(buf[lead]), buf.length);
50
+ }
51
+ /** Largest end ≤ limit that does not split a character; always > start when limit > start. */
52
+ export function utf8CharEnd(buf, start, limit) {
53
+ if (limit >= buf.length)
54
+ return buf.length;
55
+ const lead = coveringLead(buf, limit, start + 1);
56
+ return lead < 0 ? limit : lead;
57
+ }
58
+ /**
59
+ * Cap a text field at maxBytes without splitting a UTF-8 character. Returns the
60
+ * text unchanged when it fits; otherwise the head plus the original size.
61
+ */
62
+ export function capText(text, maxBytes) {
63
+ const buf = Buffer.from(text, "utf8");
64
+ if (buf.length <= maxBytes)
65
+ return { text, truncated: false, totalBytes: buf.length };
66
+ return { text: buf.subarray(0, utf8CharEnd(buf, 0, maxBytes)).toString("utf8"), truncated: true, totalBytes: buf.length };
67
+ }
24
68
  /** Shared env-map schema used by tools that accept environment variables. */
25
69
  export const envSchema = z.record(z.string(), z.string()).optional().describe("Environment variables as a key→value object.");
26
70
  /** Shared session-id schema — every per-sandbox tool takes one of these.
@@ -58,3 +102,37 @@ export const slugSchema = z
58
102
  .max(63)
59
103
  .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "lowercase letters, digits, and hyphens; cannot start or end with a hyphen")
60
104
  .describe("Subdomain slug for the preview URL (3-63 chars, lowercase letters/digits/hyphens, no leading/trailing hyphen).");
105
+ /**
106
+ * Shared tag-list schema, matching the API's repeated-string constraint on
107
+ * sessions, snapshots, volumes and templates: ≤20 tags, each ≤32 chars of
108
+ * [a-z0-9_:.-] starting with a letter or digit.
109
+ */
110
+ export const tagsSchema = z
111
+ .array(z.string().max(32).regex(/^[a-z0-9][a-z0-9_:.-]*$/, "lowercase letters, digits, and _:.- ; must start with a letter or digit"))
112
+ .max(20)
113
+ .optional()
114
+ .describe("Tags (≤20, each ≤32 chars of a-z 0-9 _ : . -).");
115
+ /**
116
+ * Wire mapping for the tags/clear_tags pair shared by sessions, snapshots and
117
+ * volumes. proto3 drops an empty repeated field, so `[]` becomes clear_tags;
118
+ * a non-empty list together with clear_tags is rejected because the server
119
+ * applies clear_tags first and would silently discard the list.
120
+ */
121
+ export function tagsPatch(tags, clearTags) {
122
+ if (clearTags && tags && tags.length) {
123
+ 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.");
124
+ }
125
+ if (clearTags || (tags !== undefined && tags.length === 0))
126
+ return { clearTags: true };
127
+ return tags && tags.length ? { tags } : {};
128
+ }
129
+ /** Free-text search across a list (server-side; API max 256 chars). */
130
+ export const searchSchema = z.string().max(256).optional();
131
+ /** Prefix a bare enum name the way protobuf JSON expects it (e.g. RUNNING → SESSION_STATE_RUNNING). */
132
+ export const protoEnum = (prefix, value) => `${prefix}_${value}`;
133
+ /** Common server-side list options shared by the sandbox, volume, template and preview-URL lists. */
134
+ export const listQuery = (search, includeFacets, sortDesc) => ({
135
+ ...(search && search.trim() ? { search: search.trim() } : {}),
136
+ ...(includeFacets ? { includeFacets: true } : {}),
137
+ ...(sortDesc ? { sortDesc: true } : {}),
138
+ });
@@ -0,0 +1,38 @@
1
+ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { z } from "zod";
3
+ import type { TenkiClient } from "../client.js";
4
+ export declare const policyNameSchema: z.ZodString;
5
+ export declare const httpRuleSchema: z.ZodObject<{
6
+ domains: z.ZodArray<z.ZodString>;
7
+ methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
8
+ path_exact: z.ZodOptional<z.ZodString>;
9
+ path_prefix: z.ZodOptional<z.ZodString>;
10
+ path_regex: z.ZodOptional<z.ZodString>;
11
+ }, z.core.$strict>;
12
+ export type HttpRule = z.infer<typeof httpRuleSchema>;
13
+ export declare const httpRuleToWire: (r: HttpRule) => Record<string, unknown>;
14
+ export declare const allowDomainsSchema: z.ZodArray<z.ZodString>;
15
+ export declare const allowCidrsSchema: z.ZodArray<z.ZodString>;
16
+ export declare const interceptHttpsSchema: z.ZodBoolean;
17
+ export declare const httpRulesSchema: z.ZodArray<z.ZodObject<{
18
+ domains: z.ZodArray<z.ZodString>;
19
+ methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
20
+ path_exact: z.ZodOptional<z.ZodString>;
21
+ path_prefix: z.ZodOptional<z.ZodString>;
22
+ path_regex: z.ZodOptional<z.ZodString>;
23
+ }, z.core.$strict>>;
24
+ export declare const allowedPortsSchema: z.ZodArray<z.ZodNumber>;
25
+ export interface EgressBody {
26
+ allow_domains?: string[];
27
+ allow_cidrs?: string[];
28
+ intercept_https?: boolean;
29
+ http_rules?: HttpRule[];
30
+ allowed_ports?: number[];
31
+ }
32
+ /**
33
+ * Map an egress body to SessionEgressPolicy JSON. `requireComplete` applies the
34
+ * checks the API runs on a policy that stands alone; on create they are skipped
35
+ * when named policies are pinned, because the API merges them first.
36
+ */
37
+ export declare function egressBodyToWire(tool: string, b: EgressBody, requireComplete: boolean): Record<string, unknown> | undefined;
38
+ export declare function registerEgress(server: McpServer, client: TenkiClient): void;
@@ -0,0 +1,153 @@
1
+ import { z } from "zod";
2
+ import { ok } from "./common.js";
3
+ /**
4
+ * Named workspace egress policies (tenki-app #6069): reusable egress allowlists
5
+ * that tenki_create_sandbox pins by name via `egress_policies`. A session keeps
6
+ * the expansion it was created with; later edits or deletes do not change it.
7
+ * Wire shape: SessionEgressPolicy { allowDomains, allowCidrs, interceptHttps,
8
+ * httpRules[{ domains, methods, exact | prefix | regex }], allowedPorts } — the
9
+ * path oneof members are plain fields on the rule.
10
+ */
11
+ const POLICY_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,127}$/;
12
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
13
+ export const policyNameSchema = z
14
+ .string()
15
+ .regex(POLICY_NAME, "policy names: letters, digits, _ and -, starting with a letter or _, max 128");
16
+ const domainSchema = z.string().min(1).max(253);
17
+ const pathSchema = z.string().min(1).max(2048).regex(/^\//, "paths start with /");
18
+ export const httpRuleSchema = z
19
+ .object({
20
+ domains: z
21
+ .array(domainSchema)
22
+ .min(1)
23
+ .max(256)
24
+ .describe("Hosts the rule applies to: exact names, single-label '*.example.com' wildcards, or '*' for every allowed domain."),
25
+ methods: z
26
+ .array(z.string().min(1).max(32))
27
+ .max(16)
28
+ .optional()
29
+ .describe("HTTP methods (e.g. GET, POST; uppercased by the API). Omit to match every method."),
30
+ path_exact: pathSchema.optional().describe("Match only this escaped path (no query)."),
31
+ path_prefix: pathSchema.optional().describe("Match paths starting with this prefix."),
32
+ path_regex: z.string().min(1).max(1024).optional().describe("RE2 regex that must match the whole escaped path (no query)."),
33
+ })
34
+ .strict()
35
+ .refine((r) => [r.path_exact, r.path_prefix, r.path_regex].filter((p) => p !== undefined).length <= 1, {
36
+ message: "set at most one of path_exact, path_prefix, path_regex",
37
+ });
38
+ export const httpRuleToWire = (r) => ({
39
+ domains: r.domains,
40
+ ...(r.methods?.length ? { methods: r.methods } : {}),
41
+ ...(r.path_exact !== undefined ? { exact: r.path_exact } : {}),
42
+ ...(r.path_prefix !== undefined ? { prefix: r.path_prefix } : {}),
43
+ ...(r.path_regex !== undefined ? { regex: r.path_regex } : {}),
44
+ });
45
+ export const allowDomainsSchema = z
46
+ .array(domainSchema)
47
+ .max(256)
48
+ .describe("Allowed hosts: exact names or single-label '*.example.com' wildcards (≤256).");
49
+ export const allowCidrsSchema = z
50
+ .array(z.string().min(1).max(18))
51
+ .max(64)
52
+ .describe("Allowed IPv4 prefixes reachable without a name lookup (≤64; not 0.0.0.0/0).");
53
+ export const interceptHttpsSchema = z
54
+ .boolean()
55
+ .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.");
56
+ export const httpRulesSchema = z
57
+ .array(httpRuleSchema)
58
+ .max(64)
59
+ .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.");
60
+ export const allowedPortsSchema = z
61
+ .array(z.number().int().min(1).max(65535))
62
+ .max(64)
63
+ .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.");
64
+ /**
65
+ * Map an egress body to SessionEgressPolicy JSON. `requireComplete` applies the
66
+ * checks the API runs on a policy that stands alone; on create they are skipped
67
+ * when named policies are pinned, because the API merges them first.
68
+ */
69
+ export function egressBodyToWire(tool, b, requireComplete) {
70
+ const domains = b.allow_domains?.length ? b.allow_domains : undefined;
71
+ const cidrs = b.allow_cidrs?.length ? b.allow_cidrs : undefined;
72
+ const rules = b.http_rules?.length ? b.http_rules : undefined;
73
+ const ports = b.allowed_ports?.length ? b.allowed_ports : undefined;
74
+ if (requireComplete) {
75
+ if (!domains && !cidrs && (b.intercept_https || rules || ports))
76
+ throw new Error(`${tool}: an egress policy must list at least one allowed domain or CIDR.`);
77
+ if (b.intercept_https && !domains)
78
+ throw new Error(`${tool}: intercept_https requires at least one allowed domain.`);
79
+ if (rules && !b.intercept_https)
80
+ throw new Error(`${tool}: http_rules require intercept_https: true (without interception HTTPS requests would bypass them).`);
81
+ if (ports && !b.intercept_https)
82
+ throw new Error(`${tool}: allowed_ports require intercept_https: true (without interception other ports already follow the domain and CIDR allowlist).`);
83
+ }
84
+ if (!domains && !cidrs && !b.intercept_https && !rules && !ports)
85
+ return undefined;
86
+ return {
87
+ ...(domains ? { allowDomains: domains } : {}),
88
+ ...(cidrs ? { allowCidrs: cidrs } : {}),
89
+ ...(b.intercept_https ? { interceptHttps: true } : {}),
90
+ ...(rules ? { httpRules: rules.map(httpRuleToWire) } : {}),
91
+ ...(ports ? { allowedPorts: ports } : {}),
92
+ };
93
+ }
94
+ const workspaceIdSchema = z.string().optional().describe("Workspace (defaults to the key's workspace).");
95
+ const policyRefSchema = z.string().min(1).describe("Policy ID or name.");
96
+ const revisionSchema = z
97
+ .number()
98
+ .int()
99
+ .min(1)
100
+ .max(4294967295)
101
+ .describe("The policy's current revision (from tenki_get_egress_policy); a stale revision is refused with ABORTED.");
102
+ 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).";
103
+ export function registerEgress(server, client) {
104
+ const workspace = async (workspace_id) => {
105
+ const id = workspace_id ?? (await client.resolveOwner()).workspaceId;
106
+ return id ? { workspaceId: id } : {};
107
+ };
108
+ const body = (tool, b) => {
109
+ const egress = egressBodyToWire(tool, b, true);
110
+ if (!egress)
111
+ throw new Error(`${tool}: an egress policy must list at least one allowed domain or CIDR.`);
112
+ return egress;
113
+ };
114
+ 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}`, {
115
+ 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."),
116
+ allow_domains: allowDomainsSchema.optional(),
117
+ allow_cidrs: allowCidrsSchema.optional(),
118
+ intercept_https: interceptHttpsSchema.optional(),
119
+ http_rules: httpRulesSchema.optional(),
120
+ allowed_ports: allowedPortsSchema.optional(),
121
+ workspace_id: workspaceIdSchema,
122
+ }, async ({ name, workspace_id, ...b }) => ok(await client.control("CreateEgressPolicy", { ...(await workspace(workspace_id)), name, egress: body("tenki_create_egress_policy", b) })));
123
+ 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.", {
124
+ policy_id: policyRefSchema,
125
+ expected_revision: revisionSchema,
126
+ allow_domains: allowDomainsSchema.optional(),
127
+ allow_cidrs: allowCidrsSchema.optional(),
128
+ intercept_https: interceptHttpsSchema.optional(),
129
+ http_rules: httpRulesSchema.optional(),
130
+ allowed_ports: allowedPortsSchema.optional(),
131
+ workspace_id: workspaceIdSchema,
132
+ }, async ({ policy_id, expected_revision, workspace_id, ...b }) => ok(await client.control("UpdateEgressPolicy", {
133
+ ...(await workspace(workspace_id)),
134
+ policyId: policy_id,
135
+ expectedRevision: expected_revision,
136
+ egress: body("tenki_update_egress_policy", b),
137
+ })));
138
+ 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 })));
139
+ 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.", {
140
+ page_size: z.number().int().min(1).max(100).optional().describe("Max policies per page (≤100, default 50)."),
141
+ cursor: z.string().optional().describe("next_cursor from the previous page."),
142
+ workspace_id: workspaceIdSchema,
143
+ }, async ({ page_size, cursor, workspace_id }) => ok(await client.control("ListEgressPolicies", {
144
+ ...(await workspace(workspace_id)),
145
+ ...(page_size ? { pageSize: page_size } : {}),
146
+ ...(cursor ? { cursor } : {}),
147
+ })));
148
+ 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", {
149
+ ...(await workspace(workspace_id)),
150
+ policyId: policy_id,
151
+ expectedRevision: expected_revision,
152
+ })));
153
+ }
@@ -87,7 +87,7 @@ export function registerExec(server, client) {
87
87
  args: z.array(z.string()).optional().describe("Arguments."),
88
88
  cwd: z.string().optional().describe("Working directory (honored in-script)."),
89
89
  env: envSchema,
90
- timeout_seconds: z.number().int().positive().optional(),
90
+ 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."),
91
91
  max_output_bytes: z
92
92
  .number()
93
93
  .int()
@@ -1,9 +1,42 @@
1
1
  import { z } from "zod";
2
- import { ok, pathSchema, sessionIdSchema } from "./common.js";
2
+ import { ok, pathSchema, sessionIdSchema, utf8CharEnd, utf8CharStart } from "./common.js";
3
+ // Inline read budget, matching tenki_exec's per-stream default. The data
4
+ // plane's ReadFile has no range support, so the whole file still crosses the
5
+ // wire to this process; the cap bounds what is returned to the model.
6
+ const DEFAULT_READ_BYTES = 65_536;
7
+ const MAX_READ_BYTES = 1_048_576;
3
8
  /** Filesystem I/O against a sandbox's data plane. */
4
9
  export function registerFiles(server, client) {
5
- 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) }));
6
- 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)));
10
+ 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.", {
11
+ session_id: sessionIdSchema,
12
+ path: pathSchema,
13
+ offset: z.number().int().min(0).optional().describe("Byte offset to start reading at (default 0). Use nextOffset from a truncated response."),
14
+ max_bytes: z
15
+ .number()
16
+ .int()
17
+ .min(1024)
18
+ .max(MAX_READ_BYTES)
19
+ .optional()
20
+ .describe(`Maximum bytes of content to return (default ${DEFAULT_READ_BYTES}, max ${MAX_READ_BYTES}). Cuts never split a UTF-8 character.`),
21
+ }, async ({ session_id, path, offset, max_bytes }) => {
22
+ const buf = await client.readFileBytes(session_id, path);
23
+ const totalBytes = buf.length;
24
+ const requested = offset ?? 0;
25
+ if (requested > totalBytes) {
26
+ throw new Error(`offset ${requested} is past the end of ${path} (${totalBytes} bytes).`);
27
+ }
28
+ const start = utf8CharStart(buf, requested);
29
+ const end = utf8CharEnd(buf, start, start + (max_bytes ?? DEFAULT_READ_BYTES));
30
+ const truncated = end < totalBytes;
31
+ return ok({
32
+ path,
33
+ content: buf.subarray(start, end).toString("utf8"),
34
+ totalBytes,
35
+ ...(start > 0 || truncated ? { offset: start, bytesReturned: end - start } : {}),
36
+ ...(truncated ? { truncated: true, nextOffset: end } : {}),
37
+ });
38
+ });
39
+ 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)));
7
40
  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.", {
8
41
  session_id: sessionIdSchema,
9
42
  path: pathSchema.describe("Directory path, e.g. /home/tenki"),
@@ -18,9 +18,17 @@ export function registerFilesOps(server, client) {
18
18
  session_id: sessionIdSchema,
19
19
  path: pathSchema.describe("Directory path under /home/tenki, e.g. /home/tenki/project/out"),
20
20
  recursive: z.boolean().optional().describe("Create parent directories as needed (default false)."),
21
- }, async ({ session_id, path, recursive }) => ok(await client.data(session_id, "Mkdir", {
21
+ mode: z
22
+ .number()
23
+ .int()
24
+ .min(0)
25
+ .max(0o7777)
26
+ .optional()
27
+ .describe("Permission bits as a number (e.g. 448 for 0700). Default: the sandbox user's umask."),
28
+ }, async ({ session_id, path, recursive, mode }) => ok(await client.data(session_id, "Mkdir", {
22
29
  path,
23
30
  ...(recursive ? { recursive: true } : {}),
31
+ ...(mode !== undefined ? { mode } : {}),
24
32
  })));
25
33
  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).", {
26
34
  session_id: sessionIdSchema,
@@ -1,4 +1,3 @@
1
1
  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import type { TenkiClient } from "../client.js";
3
- /** Git operations inside a sandbox (one RPC dispatched by operation string). */
4
3
  export declare function registerGit(server: McpServer, client: TenkiClient): void;
package/dist/tools/git.js CHANGED
@@ -1,30 +1,92 @@
1
1
  import { z } from "zod";
2
- import { ok, sessionIdSchema } from "./common.js";
2
+ import { capText, ok, sessionIdSchema } from "./common.js";
3
3
  /**
4
- * The API validates `operation` against exactly this list (GitOperationRequest's
5
- * buf.validate `in` constraint) and the engine implements exactly these four —
6
- * anything else (status/add/commit/push/...) is rejected server-side. For other
7
- * git commands, run `git ...` via tenki_exec.
4
+ * Git inside a sandbox, one tool per operation. The API exposes a single
5
+ * GitOperation RPC whose `operation` must be clone, checkout, diff or log
6
+ * (GitOperationRequest's buf.validate `in` list) with a string→string args map;
7
+ * these tools give each operation typed arguments and an accurate read/write
8
+ * classification (diff/log are reads, clone/checkout change the filesystem).
9
+ * For any other git command (status, add, commit, push, ...) use tenki_exec.
10
+ *
11
+ * Arg keys are the ones the engine reads (tenki-app
12
+ * backend/internal/domain/sandbox/service/git_operation.go, buildGitOperationArgs):
13
+ * checkout/diff/log run `git -C <directory>` when `directory` is set — without
14
+ * it they run in /home/tenki, which is not a repository unless one was cloned
15
+ * there. Values are argv to the engine's command, never a shell string.
16
+ *
17
+ * The engine places repo, branch, directory, ref, range, base and head in
18
+ * git's argv without `--end-of-options`, so a value starting with `-` would be
19
+ * parsed as an option: `git diff --output=<file>` truncates a file and
20
+ * `git clone --upload-pack=<cmd>` runs a command. Those values are refused
21
+ * here — which is also what keeps tenki_git_diff / tenki_git_log read-only.
22
+ * `path` is safe: the engine always puts it after `--`.
8
23
  */
9
- const GIT_OPERATIONS = ["clone", "checkout", "diff", "log"];
10
- /** Git operations inside a sandbox (one RPC dispatched by operation string). */
24
+ // Inline output budget, matching tenki_exec and tenki_read_file.
25
+ const MAX_OUTPUT_BYTES = 65_536;
26
+ // The engine re-trims each value with Go's strings.TrimSpace, which also strips
27
+ // U+0085 (NEL) — JavaScript's trim() and \s do not — so "\u0085--output=x"
28
+ // would reach git as "--output=x". Refuse a '-' behind any such whitespace.
29
+ const noOption = (s) => !/^[\s\u0085]*-/.test(s);
30
+ const NO_OPTION_MSG = "must not start with '-' (git would read it as an option)";
31
+ /** A value the engine passes to git as a bare argument. */
32
+ const gitArg = (description) => z.string().trim().min(1).refine(noOption, NO_OPTION_MSG).describe(description);
33
+ 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();
34
+ /** How to get less output, per operation (only diff/log take narrowing args). */
35
+ const NARROW = {
36
+ diff: "Narrow it with path or range/base/head, or run git through tenki_exec and page its output.",
37
+ log: "Narrow it with max_count, path or range, or run git through tenki_exec and page its output.",
38
+ };
39
+ const NARROW_DEFAULT = "Run git through tenki_exec to page the full output.";
40
+ async function gitOperation(client, sessionId, operation, args) {
41
+ const stringArgs = Object.fromEntries(Object.entries(args)
42
+ .filter(([, v]) => v !== undefined)
43
+ .map(([k, v]) => [k, String(v)]));
44
+ const resp = await client.control("GitOperation", { sessionId, operation, args: stringArgs });
45
+ if (typeof resp?.output !== "string")
46
+ return ok(resp);
47
+ const capped = capText(resp.output, MAX_OUTPUT_BYTES);
48
+ if (!capped.truncated)
49
+ return ok(resp);
50
+ return ok({
51
+ ...resp,
52
+ output: capped.text,
53
+ truncated: true,
54
+ totalBytes: capped.totalBytes,
55
+ note: `Output truncated to ${MAX_OUTPUT_BYTES} bytes. ${NARROW[operation] ?? NARROW_DEFAULT}`,
56
+ });
57
+ }
11
58
  export function registerGit(server, client) {
12
- 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 ...`. " +
13
- "clone arg keys: repo (required, the URL), branch?, depth?, directory?. " +
14
- "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`). " +
15
- "For reference, their arg keys are — checkout: ref (required), create? ('true' = -b); diff: range? or base?+head?, path?; log: max_count?, range?, path?.", {
59
+ 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 ...`.", {
60
+ session_id: sessionIdSchema,
61
+ repo: gitArg("Repository URL to clone, e.g. https://github.com/octocat/Hello-World."),
62
+ branch: gitArg("Branch or tag to check out after cloning (git clone --branch).").optional(),
63
+ depth: z.number().int().positive().optional().describe("Create a shallow clone with this many commits (git clone --depth)."),
64
+ directory: gitArg("Directory to clone into, e.g. /home/tenki/myrepo. Defaults to the repository name under /home/tenki.").optional(),
65
+ }, async ({ session_id, repo, branch, depth, directory }) => gitOperation(client, session_id, "clone", { repo, branch, depth, directory }));
66
+ 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.", {
16
67
  session_id: sessionIdSchema,
17
- operation: z.enum(GIT_OPERATIONS).describe("One of: clone, checkout, diff, log (the API rejects anything else)."),
18
- // The wire type is map<string,string>, but the values models most want
19
- // to send as numbers or booleans (depth, max_count, create) are
20
- // accepted here and coerced — a client-side rejection of `create: true`
21
- // for a call that would serialize identically helps nobody.
22
- args: z
23
- .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
24
- .optional()
25
- .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?}."),
26
- }, async ({ session_id, operation, args }) => {
27
- const stringArgs = args ? Object.fromEntries(Object.entries(args).map(([k, v]) => [k, String(v)])) : undefined;
28
- return ok(await client.control("GitOperation", { sessionId: session_id, operation, ...(stringArgs ? { args: stringArgs } : {}) }));
68
+ ref: gitArg("Branch, tag or commit to check out, or the name of the branch to create when create is true."),
69
+ create: z.boolean().optional().describe("Create ref as a new branch from the current HEAD (git checkout -b). Default false."),
70
+ directory: directorySchema,
71
+ }, async ({ session_id, ref, create, directory }) => gitOperation(client, session_id, "checkout", { ref, create: create ? "true" : undefined, directory }));
72
+ 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.`, {
73
+ session_id: sessionIdSchema,
74
+ range: gitArg("Revision range, e.g. main..feature or HEAD~3. Cannot be combined with base/head.").optional(),
75
+ base: gitArg("Base ref to diff from (with head: git diff base..head; alone: git diff base).").optional(),
76
+ head: gitArg("Head ref to diff to (with base: git diff base..head; alone: git diff head).").optional(),
77
+ path: z.string().trim().min(1).optional().describe("Limit the diff to this file or directory, relative to the repository root."),
78
+ directory: directorySchema,
79
+ }, async ({ session_id, range, base, head, path, directory }) => {
80
+ if (range !== undefined && (base !== undefined || head !== undefined)) {
81
+ throw new Error("tenki_git_diff: pass either range or base/head, not both.");
82
+ }
83
+ return gitOperation(client, session_id, "diff", { range, base, head, path, directory });
29
84
  });
85
+ 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.`, {
86
+ session_id: sessionIdSchema,
87
+ 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."),
88
+ range: gitArg("Revision range, e.g. main..feature.").optional(),
89
+ path: z.string().trim().min(1).optional().describe("Only commits touching this file or directory, relative to the repository root."),
90
+ directory: directorySchema,
91
+ }, async ({ session_id, max_count, range, path, directory }) => gitOperation(client, session_id, "log", { max_count, range, path, directory }));
30
92
  }
@@ -1,4 +1,11 @@
1
1
  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import type { TenkiClient } from "../client.js";
3
- /** Port exposure / preview URLs. */
3
+ /**
4
+ * Port exposure. ExposePort / ListExposedPorts (and UnexposePort in previews.ts)
5
+ * are marked deprecated upstream (tenki-app #5663, 2026-09-15) in favour of the
6
+ * preview-URL RPCs; they still work — ExposePort now creates a preview URL and
7
+ * auto-mints a slug when none is given, which CreatePreviewUrl cannot do (slug
8
+ * is required there). Kept as the convenience path; descriptions steer callers
9
+ * who already have a slug to tenki_create_preview_url.
10
+ */
4
11
  export declare function registerPorts(server: McpServer, client: TenkiClient): void;
@@ -1,6 +1,27 @@
1
+ import { z } from "zod";
1
2
  import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
2
- /** Port exposure / preview URLs. */
3
+ /**
4
+ * Port exposure. ExposePort / ListExposedPorts (and UnexposePort in previews.ts)
5
+ * are marked deprecated upstream (tenki-app #5663, 2026-09-15) in favour of the
6
+ * preview-URL RPCs; they still work — ExposePort now creates a preview URL and
7
+ * auto-mints a slug when none is given, which CreatePreviewUrl cannot do (slug
8
+ * is required there). Kept as the convenience path; descriptions steer callers
9
+ * who already have a slug to tenki_create_preview_url.
10
+ */
3
11
  export function registerPorts(server, client) {
4
- 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 } : {}) })));
5
- 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 })));
12
+ 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.", {
13
+ session_id: sessionIdSchema,
14
+ port: portSchema,
15
+ slug: slugSchema.optional(),
16
+ expires_at: z
17
+ .string()
18
+ .optional()
19
+ .describe("Optional RFC-3339 timestamp at which the preview URL auto-expires. Omit to keep it until the sandbox ends."),
20
+ }, async ({ session_id, port, slug, expires_at }) => ok(await client.control("ExposePort", {
21
+ sessionId: session_id,
22
+ port,
23
+ ...(slug ? { slug } : {}),
24
+ ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
25
+ })));
26
+ 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 })));
6
27
  }