@tetral-ai/sdk 0.110.0-alpha.1

package/tools/agent-toolset/node.d.mts

@@ -0,0 +1,149 @@
+/**
+ * Node implementation of the `agent_toolset_20260401` tools — `bash`, `read`,
+ * `write`, `edit`, `glob`, `grep` — plus the workdir/skills
+ * {@link AgentToolContext}.
+ *
+ * This mirrors `@tetral-ai/sdk/tools/memory/node`: it is the explicit,
+ * Node-only entry point for these implementations. Importing it pulls in
+ * `node:child_process`, `node:fs`, etc., so it is kept separate from the rest of
+ * the SDK — depending on it is an opt-in.
+ *
+ * **Node 22+ is required** for this module: the `glob` tool uses the native
+ * `fs.glob`, added in Node 22. The rest of the SDK still supports Node 18+; only
+ * the agent toolset has this requirement.
+ *
+ * The result of {@link betaAgentToolset20260401} is a plain `BetaRunnableTool[]`;
+ * hand it to any tool runner — `client.beta.messages.toolRunner({ …, tools })`
+ * for the Messages API, or `client.beta.sessions.events.toolRunner({ …, tools })`
+ * for a managed-agents session:
+ *
+ * ```ts
+ * import { betaAgentToolset20260401 } from '@tetral-ai/sdk/tools/agent-toolset/node';
+ *
+ * const tools = betaAgentToolset20260401({ workdir: '/work' });
+ * const tools2 = betaAgentToolset20260401({ workdir: '/work' }).filter((t) => t.name !== 'bash');
+ * ```
+ *
+ * Trust model: the file tools confine to `workdir` (symlink-aware) and are safe
+ * without a sandbox; `bash` is unrestricted and should run inside one. See
+ * {@link AgentToolContext}.
+ */
+import type { Anthropic } from "../../client.mjs";
+import type { BetaRunnableTool } from "../../lib/tools/BetaRunnableTool.mjs";
+export { setupSkills, resolveSkillVersion, extractSkillArchive } from "./skills.mjs";
+/**
+ * Workdir + path-policy for the agent toolset.
+ *
+ * Trust model — two tiers:
+ *
+ * - The file tools ({@link betaReadTool}, {@link betaWriteTool},
+ *   {@link betaEditTool}, {@link betaGlobTool}, {@link betaGrepTool}) confine to
+ *   `workdir` unless `unrestrictedPaths` is set. {@link resolvePath}
+ *   canonicalizes the target (resolving every symlink, including the leaf)
+ *   before the check *and* returns that canonical path for the operation, so a
+ *   symlink inside the workdir that points outside it neither passes the check
+ *   nor gets followed afterwards — this is a real boundary, not a lexical hint
+ *   (modulo the residual TOCTOU noted on {@link resolvePath}).
+ * - {@link betaBashTool} runs an unrestricted `/bin/bash` and cannot be
+ *   confined. Run it — and, for defense in depth, the whole toolset — inside a
+ *   sandbox the host controls (e.g. a self-hosted environment runner).
+ */
+export interface AgentToolContext {
+    /** Base directory for resolving relative tool paths. */
+    workdir: string;
+    /**
+     * When `false` (default), the file tools reject paths that resolve outside
+     * `workdir` (symlinks resolved). Does **not** constrain {@link betaBashTool}.
+     */
+    unrestrictedPaths?: boolean;
+    /**
+     * Anthropic client. Optional — the bare toolset needs no client; it is only
+     * used by `setupSkills`, which (together with {@link AgentToolContext.sessionId})
+     * fetches the session's resolved agent and downloads each of its skills into
+     * `{workdir}/skills/<name>/`.
+     */
+    client?: Anthropic;
+    /** Session whose agent's skills `setupSkills` should download. */
+    sessionId?: string;
+    /**
+     * Optional environment for the bash subprocess. When unset, the bash tool
+     * inherits the process environment with SDK credential namespaces scrubbed.
+     * When provided, it FULLY REPLACES that default
+     * environment — the mapping is used verbatim and is NOT merged with or added
+     * to the scrubbed process environment. To keep the defaults plus extra vars,
+     * build the combined mapping yourself before passing it.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Size cap for the `read` and `edit` tools, which both load the whole file into
+     * memory. `undefined` (default) uses the built-in 256 KiB cap; a positive number
+     * sets a custom cap; `null` disables the cap entirely. Disabling it reintroduces
+     * the OOM risk on a model-controlled path, so pass `null` only when the sandbox
+     * can absorb arbitrarily large files. The non-regular-file (FIFO/device) guard
+     * always applies regardless of this value.
+     */
+    maxFileBytes?: number | null;
+}
+/**
+ * Returns the `agent_toolset_20260401` implementations bound to `ctx`. The
+ * result is a plain array of `BetaRunnableTool`; filter or extend it before
+ * handing it to a tool runner:
+ *
+ * ```ts
+ * const tools = [...betaAgentToolset20260401(ctx), myCustomTool];
+ * const tools = betaAgentToolset20260401(ctx).filter((t) => t.name !== 'grep');
+ * ```
+ *
+ * Concurrency note: `client.beta.sessions.events.toolRunner` dispatches a
+ * session's tool calls serially (the sessions API delivers one `agent.tool_use`
+ * at a time). `client.beta.messages.toolRunner` runs a turn's `tool.run` calls
+ * via `Promise.all`. The toolset below is safe under either model —
+ * {@link betaBashTool} serializes its persistent shell internally and the FS
+ * tools are independent per call — but {@link betaEditTool}/{@link betaWriteTool}
+ * cannot synchronize concurrent writes to the *same* file across processes, so a
+ * multi-edit turn touching one path is still subject to inherent FS lost-update
+ * races. Custom tools that close over mutable state should do their own queueing.
+ */
+export declare function betaAgentToolset20260401(ctx: AgentToolContext): BetaRunnableTool[];
+/**
+ * Resolve `p` against `ctx.workdir`. Absolute and relative inputs go through
+ * the same canonicalise-then-contain check — an absolute path that lands inside
+ * the workdir is permitted, only paths that resolve *outside* are rejected.
+ * Every symlink in `p` (including the leaf, even a dangling one) is resolved
+ * before the workdir check, and the resolved path is what the tool then operates
+ * on, so a symlink inside the workdir that points outside it can neither pass
+ * the check nor be followed afterwards. See the trust model on
+ * {@link AgentToolContext}.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; the same
+ * residual exposure exists in `tools/memory/node` and is why a sandbox is still
+ * recommended for the toolset as a whole.
+ */
+export declare function resolvePath(ctx: AgentToolContext, p: string): Promise<string>;
+/**
+ * A persistent /bin/bash process. State (cwd, env, background jobs) survives
+ * across exec() calls. Uses pipes rather than a PTY so input is never echoed.
+ */
+export declare class BashSession {
+    #private;
+    constructor(dir: string, env?: NodeJS.ProcessEnv);
+    /** Whether the underlying shell process has exited. */
+    get closed(): boolean;
+    exec(command: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal | null | undefined;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+    close(): void;
+}
+export declare function betaBashTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaReadTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaWriteTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaEditTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGlobTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGrepTool(ctx: AgentToolContext): BetaRunnableTool;
+//# sourceMappingURL=node.d.mts.map

package/tools/agent-toolset/node.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.mts","sourceRoot":"","sources":["../../src/tools/agent-toolset/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,yBAAqB;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,6CAAyC;AAMzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,qBAAiB;AA+BjF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CASlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AA0BD;;;GAGG;AACH,qBAAa,WAAW;;gBASV,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAA+B;IAyBpE,uDAAuD;IACvD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAkBK,IAAI,CACR,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;KAAO,GACzE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAkEhD,KAAK,IAAI,IAAI;CAkBd;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgEpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAiDpE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAqBrE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA8DpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgFpE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAmBpE"}

package/tools/agent-toolset/node.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Node implementation of the `agent_toolset_20260401` tools — `bash`, `read`,
+ * `write`, `edit`, `glob`, `grep` — plus the workdir/skills
+ * {@link AgentToolContext}.
+ *
+ * This mirrors `@tetral-ai/sdk/tools/memory/node`: it is the explicit,
+ * Node-only entry point for these implementations. Importing it pulls in
+ * `node:child_process`, `node:fs`, etc., so it is kept separate from the rest of
+ * the SDK — depending on it is an opt-in.
+ *
+ * **Node 22+ is required** for this module: the `glob` tool uses the native
+ * `fs.glob`, added in Node 22. The rest of the SDK still supports Node 18+; only
+ * the agent toolset has this requirement.
+ *
+ * The result of {@link betaAgentToolset20260401} is a plain `BetaRunnableTool[]`;
+ * hand it to any tool runner — `client.beta.messages.toolRunner({ …, tools })`
+ * for the Messages API, or `client.beta.sessions.events.toolRunner({ …, tools })`
+ * for a managed-agents session:
+ *
+ * ```ts
+ * import { betaAgentToolset20260401 } from '@tetral-ai/sdk/tools/agent-toolset/node';
+ *
+ * const tools = betaAgentToolset20260401({ workdir: '/work' });
+ * const tools2 = betaAgentToolset20260401({ workdir: '/work' }).filter((t) => t.name !== 'bash');
+ * ```
+ *
+ * Trust model: the file tools confine to `workdir` (symlink-aware) and are safe
+ * without a sandbox; `bash` is unrestricted and should run inside one. See
+ * {@link AgentToolContext}.
+ */
+import type { Anthropic } from "../../client.js";
+import type { BetaRunnableTool } from "../../lib/tools/BetaRunnableTool.js";
+export { setupSkills, resolveSkillVersion, extractSkillArchive } from "./skills.js";
+/**
+ * Workdir + path-policy for the agent toolset.
+ *
+ * Trust model — two tiers:
+ *
+ * - The file tools ({@link betaReadTool}, {@link betaWriteTool},
+ *   {@link betaEditTool}, {@link betaGlobTool}, {@link betaGrepTool}) confine to
+ *   `workdir` unless `unrestrictedPaths` is set. {@link resolvePath}
+ *   canonicalizes the target (resolving every symlink, including the leaf)
+ *   before the check *and* returns that canonical path for the operation, so a
+ *   symlink inside the workdir that points outside it neither passes the check
+ *   nor gets followed afterwards — this is a real boundary, not a lexical hint
+ *   (modulo the residual TOCTOU noted on {@link resolvePath}).
+ * - {@link betaBashTool} runs an unrestricted `/bin/bash` and cannot be
+ *   confined. Run it — and, for defense in depth, the whole toolset — inside a
+ *   sandbox the host controls (e.g. a self-hosted environment runner).
+ */
+export interface AgentToolContext {
+    /** Base directory for resolving relative tool paths. */
+    workdir: string;
+    /**
+     * When `false` (default), the file tools reject paths that resolve outside
+     * `workdir` (symlinks resolved). Does **not** constrain {@link betaBashTool}.
+     */
+    unrestrictedPaths?: boolean;
+    /**
+     * Anthropic client. Optional — the bare toolset needs no client; it is only
+     * used by `setupSkills`, which (together with {@link AgentToolContext.sessionId})
+     * fetches the session's resolved agent and downloads each of its skills into
+     * `{workdir}/skills/<name>/`.
+     */
+    client?: Anthropic;
+    /** Session whose agent's skills `setupSkills` should download. */
+    sessionId?: string;
+    /**
+     * Optional environment for the bash subprocess. When unset, the bash tool
+     * inherits the process environment with SDK credential namespaces scrubbed.
+     * When provided, it FULLY REPLACES that default
+     * environment — the mapping is used verbatim and is NOT merged with or added
+     * to the scrubbed process environment. To keep the defaults plus extra vars,
+     * build the combined mapping yourself before passing it.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Size cap for the `read` and `edit` tools, which both load the whole file into
+     * memory. `undefined` (default) uses the built-in 256 KiB cap; a positive number
+     * sets a custom cap; `null` disables the cap entirely. Disabling it reintroduces
+     * the OOM risk on a model-controlled path, so pass `null` only when the sandbox
+     * can absorb arbitrarily large files. The non-regular-file (FIFO/device) guard
+     * always applies regardless of this value.
+     */
+    maxFileBytes?: number | null;
+}
+/**
+ * Returns the `agent_toolset_20260401` implementations bound to `ctx`. The
+ * result is a plain array of `BetaRunnableTool`; filter or extend it before
+ * handing it to a tool runner:
+ *
+ * ```ts
+ * const tools = [...betaAgentToolset20260401(ctx), myCustomTool];
+ * const tools = betaAgentToolset20260401(ctx).filter((t) => t.name !== 'grep');
+ * ```
+ *
+ * Concurrency note: `client.beta.sessions.events.toolRunner` dispatches a
+ * session's tool calls serially (the sessions API delivers one `agent.tool_use`
+ * at a time). `client.beta.messages.toolRunner` runs a turn's `tool.run` calls
+ * via `Promise.all`. The toolset below is safe under either model —
+ * {@link betaBashTool} serializes its persistent shell internally and the FS
+ * tools are independent per call — but {@link betaEditTool}/{@link betaWriteTool}
+ * cannot synchronize concurrent writes to the *same* file across processes, so a
+ * multi-edit turn touching one path is still subject to inherent FS lost-update
+ * races. Custom tools that close over mutable state should do their own queueing.
+ */
+export declare function betaAgentToolset20260401(ctx: AgentToolContext): BetaRunnableTool[];
+/**
+ * Resolve `p` against `ctx.workdir`. Absolute and relative inputs go through
+ * the same canonicalise-then-contain check — an absolute path that lands inside
+ * the workdir is permitted, only paths that resolve *outside* are rejected.
+ * Every symlink in `p` (including the leaf, even a dangling one) is resolved
+ * before the workdir check, and the resolved path is what the tool then operates
+ * on, so a symlink inside the workdir that points outside it can neither pass
+ * the check nor be followed afterwards. See the trust model on
+ * {@link AgentToolContext}.
+ *
+ * Residual TOCTOU: a component could still be swapped for a symlink between this
+ * call and the eventual `fs` operation. Closing that fully needs per-component
+ * `O_NOFOLLOW`/`openat`, which Node does not expose ergonomically; the same
+ * residual exposure exists in `tools/memory/node` and is why a sandbox is still
+ * recommended for the toolset as a whole.
+ */
+export declare function resolvePath(ctx: AgentToolContext, p: string): Promise<string>;
+/**
+ * A persistent /bin/bash process. State (cwd, env, background jobs) survives
+ * across exec() calls. Uses pipes rather than a PTY so input is never echoed.
+ */
+export declare class BashSession {
+    #private;
+    constructor(dir: string, env?: NodeJS.ProcessEnv);
+    /** Whether the underlying shell process has exited. */
+    get closed(): boolean;
+    exec(command: string, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal | null | undefined;
+    }): Promise<{
+        output: string;
+        exitCode: number;
+    }>;
+    close(): void;
+}
+export declare function betaBashTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaReadTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaWriteTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaEditTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGlobTool(ctx: AgentToolContext): BetaRunnableTool;
+export declare function betaGrepTool(ctx: AgentToolContext): BetaRunnableTool;
+//# sourceMappingURL=node.d.ts.map

package/tools/agent-toolset/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/tools/agent-toolset/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,wBAAqB;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,4CAAyC;AAMzE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,oBAAiB;AA+BjF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CASlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AA0BD;;;GAGG;AACH,qBAAa,WAAW;;gBASV,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAA+B;IAyBpE,uDAAuD;IACvD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAkBK,IAAI,CACR,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;KAAO,GACzE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAkEhD,KAAK,IAAI,IAAI;CAkBd;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgEpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAiDpE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAqBrE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA8DpE;AAID,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAgFpE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAmBpE"}