@comma-agents/core 2.0.0-rc.0

package/dist/tools/built-in/glob/glob.types.d.ts

@@ -0,0 +1,31 @@
+export interface GlobToolConfig {
+    /**
+     * Maximum number of matches returned. Excess entries are dropped and
+     * `data.truncated` is set. Default: 1000.
+     */
+    readonly maxResults?: number;
+    /**
+     * Maximum depth of directory traversal. Default: 32.
+     */
+    readonly maxDepth?: number;
+}
+export interface GlobData {
+    /** Glob pattern that was matched. */
+    readonly pattern: string;
+    /** Root directory that was searched (echoed input, normalized). */
+    readonly root: string;
+    /** Matched paths and details. */
+    readonly matches: readonly GlobMatch[];
+    /** True when the result was capped by `maxResults`. */
+    readonly truncated: boolean;
+}
+export interface GlobMatch {
+    /** Path relative to the workspace. */
+    readonly path: string;
+    /** Entry kind. */
+    readonly type: "file" | "directory" | "symlink";
+    /** Size in bytes. `0` for directories and symlinks. */
+    readonly size: number;
+    /** ISO-8601 modification timestamp. */
+    readonly mtime: string;
+}

package/dist/tools/built-in/glob/glob.utils.d.ts

@@ -0,0 +1,4 @@
+import type { GlobData } from "./glob.types";
+export declare function toForwardSlash(pathString: string): string;
+export declare function matchesAnyGlob(relPath: string, patterns: readonly string[]): boolean;
+export declare function formatGlobResults(data: GlobData): string;

package/dist/tools/built-in/glob/index.d.ts

@@ -0,0 +1,2 @@
+export { createGlobTool, globParams } from "./glob";
+export type { GlobData, GlobMatch, GlobToolConfig, } from "./glob.types";

package/dist/tools/built-in/launch-strategy/index.d.ts

@@ -0,0 +1,2 @@
+export { createLaunchStrategyTool } from "./launch-strategy";
+export type { LaunchStrategyData } from "./launch-strategy.types";

package/dist/tools/built-in/launch-strategy/launch-strategy.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { LaunchStrategyData } from "./launch-strategy.types";
+export declare const launchStrategyParams: z.ZodObject<{
+    name: z.ZodString;
+    input: z.ZodString;
+    modelOverride: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    input: string;
+    modelOverride?: string | undefined;
+}, {
+    name: string;
+    input: string;
+    modelOverride?: string | undefined;
+}>;
+/**
+ * Build the `launch_strategy` tool.
+ *
+ * Resolves `name` via {@link discoverStrategies}, then either delegates
+ * to the runtime-supplied {@link ToolContext.launchStrategy} handle (in
+ * the daemon, so nested agent activity is broadcast to the parent run)
+ * or falls back to an in-process `loadStrategyFromString` +
+ * `flow.call(input)` invocation when no handle is configured.
+ */
+export declare function createLaunchStrategyTool(): ToolDefinition<typeof launchStrategyParams, LaunchStrategyData>;

package/dist/tools/built-in/launch-strategy/launch-strategy.types.d.ts

@@ -0,0 +1,14 @@
+/** Structured payload returned by `launch_strategy.execute`. */
+export interface LaunchStrategyData {
+    /** The launched strategy's `name` field. */
+    readonly strategyName: string;
+    /** Absolute path to the strategy file that was launched. */
+    readonly path: string;
+    /**
+     * Final text produced by the sub-strategy's entry flow.
+     * Mirrors `AgentCallResult.text` from the underlying flow call.
+     */
+    readonly result: string;
+    /** Why the flow stopped, when reported by the underlying runtime. */
+    readonly finishReason?: string;
+}

package/dist/tools/built-in/list-directory/index.d.ts

@@ -0,0 +1,2 @@
+export { createListDirectoryTool } from "./list-directory";
+export type { ListDirectoryData, ListDirectoryEntry, ListDirectoryToolConfig, } from "./list-directory.types";

package/dist/tools/built-in/list-directory/list-directory.constants.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_ABSOLUTE_MAX_DEPTH = 32;
+export declare const DEFAULT_RECURSIVE_DEPTH = 8;
+export declare const DEFAULT_MAX_ENTRIES = 5000;

package/dist/tools/built-in/list-directory/list-directory.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { ListDirectoryData, ListDirectoryToolConfig } from "./list-directory.types";
+export declare const listDirectoryParams: z.ZodObject<{
+    path: z.ZodString;
+    recursive: z.ZodOptional<z.ZodBoolean>;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+    includeHidden: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    recursive?: boolean | undefined;
+    maxDepth?: number | undefined;
+    includeHidden?: boolean | undefined;
+}, {
+    path: string;
+    recursive?: boolean | undefined;
+    maxDepth?: number | undefined;
+    includeHidden?: boolean | undefined;
+}>;
+export declare function createListDirectoryTool(config?: ListDirectoryToolConfig): ToolDefinition<typeof listDirectoryParams, ListDirectoryData>;

package/dist/tools/built-in/list-directory/list-directory.types.d.ts

@@ -0,0 +1,41 @@
+export interface ListDirectoryToolConfig {
+    /**
+     * Hard cap on recursion depth. Calls passing a larger `maxDepth` are
+     * clamped to this value. Default: 32.
+     */
+    readonly absoluteMaxDepth?: number;
+    /**
+     * Default `maxDepth` when `recursive: true` is set without an explicit
+     * depth. Default: 8.
+     */
+    readonly defaultRecursiveDepth?: number;
+    /**
+     * Maximum number of entries returned. Excess entries are dropped and
+     * `data.truncated` is set. Default: 5000.
+     */
+    readonly maxEntries?: number;
+}
+export interface ListDirectoryData {
+    /** Directory that was listed (echoed input, normalized). */
+    readonly path: string;
+    /** Sorted entries. */
+    readonly entries: readonly ListDirectoryEntry[];
+    /** Effective recursion depth used for this call. */
+    readonly maxDepth: number;
+    /** True when the result was capped by `maxEntries`. */
+    readonly truncated: boolean;
+}
+export interface ListDirectoryEntry {
+    /** Basename of the entry. */
+    readonly name: string;
+    /** Path relative to the listed directory (forward-slash separated). */
+    readonly relativePath: string;
+    /** Entry kind. */
+    readonly type: "file" | "directory" | "symlink";
+    /** Size in bytes. `0` for directories and symlinks. */
+    readonly size: number;
+    /** ISO-8601 modification timestamp. */
+    readonly mtime: string;
+    /** Depth below the listed directory (1 = direct child). */
+    readonly depth: number;
+}

package/dist/tools/built-in/list-directory/list-directory.utils.d.ts

@@ -0,0 +1,4 @@
+import type { ListDirectoryData, ListDirectoryEntry } from "./list-directory.types";
+export declare function toForwardSlash(pathString: string): string;
+export declare function formatListing(data: ListDirectoryData): string;
+export declare function typeRank(type: ListDirectoryEntry["type"]): number;

package/dist/tools/built-in/list-skills/index.d.ts

@@ -0,0 +1,2 @@
+export { createListSkillsTool } from "./list-skills";
+export type { ListSkillsData, ListSkillsEntry } from "./list-skills.types";

package/dist/tools/built-in/list-skills/list-skills.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { ListSkillsData } from "./list-skills.types";
+export declare const listSkillsParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare function createListSkillsTool(): ToolDefinition<typeof listSkillsParams, ListSkillsData>;

package/dist/tools/built-in/list-skills/list-skills.types.d.ts

@@ -0,0 +1,10 @@
+export interface ListSkillsEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly origin: "global" | "project";
+    readonly sourcePath: string;
+}
+export interface ListSkillsData {
+    readonly skills: readonly ListSkillsEntry[];
+    readonly count: number;
+}

package/dist/tools/built-in/list-strategy/index.d.ts

@@ -0,0 +1,2 @@
+export { createListStrategyTool } from "./list-strategy";
+export type { ListStrategyData, ListStrategyEntry, } from "./list-strategy.types";

package/dist/tools/built-in/list-strategy/list-strategy.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { ListStrategyData } from "./list-strategy.types";
+export declare const listStrategyParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+/**
+ * Build the `list_strategy` tool.
+ *
+ * Enumerates every strategy that {@link discoverStrategies} can find on
+ * disk (bundled, cwd `.comma/strategies/`, cwd projects, data dir, data
+ * dir projects) and returns them in a structured payload plus a
+ * human-readable summary. Strategies that fail schema validation are
+ * not included; their paths are surfaced in `data.warnings`.
+ */
+export declare function createListStrategyTool(): ToolDefinition<typeof listStrategyParams, ListStrategyData>;

package/dist/tools/built-in/list-strategy/list-strategy.types.d.ts

@@ -0,0 +1,33 @@
+import type { DiscoveredStrategyOrigin } from "../../../strategy/discover/discover.types";
+/** A single entry in the `list_strategy` result. */
+export interface ListStrategyEntry {
+    /** Strategy `name` field. */
+    readonly name: string;
+    /** Strategy `description` field, when present. */
+    readonly description?: string;
+    /** Strategy `version` field. */
+    readonly version: string;
+    /** Absolute path to the strategy file on disk. */
+    readonly path: string;
+    /** Where the strategy was found. See {@link DiscoveredStrategyOrigin}. */
+    readonly origin: DiscoveredStrategyOrigin;
+    /** Project manifest path when the strategy is part of a project. */
+    readonly manifestPath?: string;
+    /** Human-readable label (project-qualified when applicable). */
+    readonly label: string;
+}
+/** Structured payload returned by `list_strategy.execute`. */
+export interface ListStrategyData {
+    /** Validated, ready-to-launch strategies in discovery-priority order. */
+    readonly strategies: readonly ListStrategyEntry[];
+    /** Total number of strategies returned. */
+    readonly count: number;
+    /**
+     * Files that were skipped during discovery (parse / schema errors).
+     * Surfaced for diagnostics; never includable in {@link strategies}.
+     */
+    readonly warnings: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
+}

package/dist/tools/built-in/load-skill/index.d.ts

@@ -0,0 +1,2 @@
+export { createLoadSkillTool } from "./load-skill";
+export type { LoadSkillData, LoadSkillParams } from "./load-skill.types";

package/dist/tools/built-in/load-skill/load-skill.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { LoadSkillData } from "./load-skill.types";
+export declare const loadSkillParams: z.ZodObject<{
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+}, {
+    name: string;
+}>;
+/**
+ * Create the `load_skill` tool.
+ *
+ * Reads from `ToolContext.skillRegistry`. When no registry is configured
+ * — for example, because the strategy loader found no skills directories
+ * — every call returns `skill_unavailable` with a helpful message rather
+ * than `not_found`, so the LLM can stop trying.
+ *
+ * @example
+ * ```ts
+ * const loadSkill = createLoadSkillTool();
+ * ```
+ */
+export declare function createLoadSkillTool(): ToolDefinition<typeof loadSkillParams, LoadSkillData>;

package/dist/tools/built-in/load-skill/load-skill.types.d.ts

@@ -0,0 +1,15 @@
+import type { z } from "zod";
+import type { loadSkillParams } from "./load-skill";
+export interface LoadSkillData {
+    /** The skill's identifier. */
+    readonly name: string;
+    /** The one-line description shown in the system prompt. */
+    readonly description: string;
+    /** Full markdown body of the skill (frontmatter stripped). */
+    readonly content: string;
+    /** Absolute path to the source `SKILL.md` for debugging / provenance. */
+    readonly sourcePath: string;
+    /** Whether the skill came from the global config dir or the project. */
+    readonly origin: "global" | "project";
+}
+export type LoadSkillParams = z.infer<typeof loadSkillParams>;

package/dist/tools/built-in/lsp-request/index.d.ts

@@ -0,0 +1,2 @@
+export { createLspRequestTool } from "./lsp-request";
+export type { LspRequestData } from "./lsp-request.types";

package/dist/tools/built-in/lsp-request/lsp-request.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../tool.types";
+import { lspRequestParams } from "./lsp-request.schema";
+import type { LspRequestData } from "./lsp-request.types";
+export declare function createLspRequestTool(): ToolDefinition<typeof lspRequestParams, LspRequestData>;

package/dist/tools/built-in/lsp-request/lsp-request.schema.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const lspRequestParams: z.ZodObject<{
+    method: z.ZodEnum<["textDocument/diagnostic", "textDocument/hover", "textDocument/definition", "textDocument/typeDefinition", "textDocument/implementation", "textDocument/references", "textDocument/documentSymbol", "workspace/symbol"]>;
+    languageId: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+    character: z.ZodOptional<z.ZodNumber>;
+    query: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    method: "textDocument/diagnostic" | "textDocument/hover" | "textDocument/definition" | "textDocument/typeDefinition" | "textDocument/implementation" | "textDocument/references" | "textDocument/documentSymbol" | "workspace/symbol";
+    path?: string | undefined;
+    languageId?: string | undefined;
+    line?: number | undefined;
+    character?: number | undefined;
+    query?: string | undefined;
+}, {
+    method: "textDocument/diagnostic" | "textDocument/hover" | "textDocument/definition" | "textDocument/typeDefinition" | "textDocument/implementation" | "textDocument/references" | "textDocument/documentSymbol" | "workspace/symbol";
+    path?: string | undefined;
+    languageId?: string | undefined;
+    line?: number | undefined;
+    character?: number | undefined;
+    query?: string | undefined;
+}>;

package/dist/tools/built-in/lsp-request/lsp-request.types.d.ts

@@ -0,0 +1,4 @@
+import type { LspMethod, LspResponse } from "../../../language";
+export interface LspRequestData extends LspResponse {
+    readonly method: LspMethod;
+}

package/dist/tools/built-in/move-file/index.d.ts

@@ -0,0 +1,2 @@
+export { createMoveFileTool } from "./move-file";
+export type { MoveFileData, MoveFileToolConfig } from "./move-file.types";

package/dist/tools/built-in/move-file/move-file.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { MoveFileData, MoveFileToolConfig } from "./move-file.types";
+declare const moveFileParams: z.ZodObject<{
+    fromPath: z.ZodString;
+    toPath: z.ZodString;
+    expectedSha256: z.ZodString;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    expectedSha256: string;
+    fromPath: string;
+    toPath: string;
+    overwrite?: boolean | undefined;
+}, {
+    expectedSha256: string;
+    fromPath: string;
+    toPath: string;
+    overwrite?: boolean | undefined;
+}>;
+export declare function createMoveFileTool(config?: MoveFileToolConfig): ToolDefinition<typeof moveFileParams, MoveFileData>;
+export {};

package/dist/tools/built-in/move-file/move-file.types.d.ts

@@ -0,0 +1,12 @@
+import type { AuditSink } from "../../io/audit.types";
+export interface MoveFileToolConfig {
+    readonly defaultAuditSink?: AuditSink;
+}
+export interface MoveFileData {
+    readonly moved: true;
+    readonly fromPath: string;
+    readonly toPath: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+    readonly overwroteTrashedTo?: string;
+}

package/dist/tools/built-in/read-file/index.d.ts

@@ -0,0 +1,2 @@
+export { createReadFileTool } from "./read-file";
+export type { ReadFileData, ReadFileToolConfig } from "./read-file.types";

package/dist/tools/built-in/read-file/read-file.constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_MAX_BYTES: number;

package/dist/tools/built-in/read-file/read-file.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { ReadFileData, ReadFileToolConfig } from "./read-file.types";
+export declare const readFileParams: z.ZodObject<{
+    path: z.ZodString;
+    startLine: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+    allowBinary: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+    maxBytes?: number | undefined;
+    allowBinary?: boolean | undefined;
+}, {
+    path: string;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+    maxBytes?: number | undefined;
+    allowBinary?: boolean | undefined;
+}>;
+/**
+ * Create the `read_file` tool.
+ *
+ * @param config - Optional configuration overriding the default max-bytes cap.
+ * @example
+ * ```ts
+ * const readFile = createReadFileTool();
+ * ```
+ */
+export declare function createReadFileTool(config?: ReadFileToolConfig): ToolDefinition<typeof readFileParams, ReadFileData>;

package/dist/tools/built-in/read-file/read-file.types.d.ts

@@ -0,0 +1,34 @@
+import type { NewlineStyle } from "../../io/newline";
+export interface ReadFileToolConfig {
+    /**
+     * Default cap on the UTF-8 byte length of returned `content`. Applied
+     * when the caller does not pass `maxBytes`. Defaults to 256 KiB.
+     */
+    readonly defaultMaxBytes?: number;
+}
+export interface ReadFileData {
+    /** UTF-8 content of the (possibly sliced) text file. Absent for binary reads. */
+    readonly content?: string;
+    /** Base64-encoded full content. Only present for `allowBinary: true` reads. */
+    readonly contentBase64?: string;
+    /** Encoding of `content` / `contentBase64`. */
+    readonly encoding: "utf8" | "base64";
+    /** 1-indexed start line of the returned slice (1 when no slicing applied). */
+    readonly startLine: number;
+    /** 1-indexed end line of the returned slice (inclusive). */
+    readonly endLine: number;
+    /** Total line count of the underlying file (post LF-normalization). */
+    readonly lineCount: number;
+    /** Size of the on-disk file in bytes. */
+    readonly sizeBytes: number;
+    /** SHA-256 of the **full** on-disk bytes. */
+    readonly sha256: string;
+    /** True when the returned content was capped by `maxBytes`. */
+    readonly truncated: boolean;
+    /** True when the file was detected as binary. */
+    readonly binary: boolean;
+    /** Newline style of the underlying file. Absent for binary reads. */
+    readonly newlineStyle?: NewlineStyle;
+    /** True when the file begins with a UTF-8 BOM. Absent for binary reads. */
+    readonly hasBom?: boolean;
+}

package/dist/tools/built-in/read-file/read-file.utils.d.ts

@@ -0,0 +1,14 @@
+import type { ReadFileData } from "./read-file.types";
+/**
+ * Format a short LLM-facing summary of a successful text read.
+ */
+export declare function formatTextSummary(filePath: string, data: Required<Pick<ReadFileData, "startLine" | "endLine" | "lineCount" | "sizeBytes" | "sha256">> & {
+    truncated: boolean;
+}): string;
+/**
+ * Truncate a UTF-8 string to at most `maxBytes` bytes without splitting a code point.
+ */
+export declare function truncateUtf8(content: string, maxBytes: number): {
+    content: string;
+    truncated: boolean;
+};

package/dist/tools/built-in/restore-file/index.d.ts

@@ -0,0 +1,2 @@
+export { createRestoreFileTool } from "./restore-file";
+export type { RestoreFileData } from "./restore-file.types";

package/dist/tools/built-in/restore-file/restore-file.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { RestoreFileData } from "./restore-file.types";
+declare const restoreFileParams: z.ZodObject<{
+    trashedPath: z.ZodString;
+    targetPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    trashedPath: string;
+    targetPath?: string | undefined;
+}, {
+    trashedPath: string;
+    targetPath?: string | undefined;
+}>;
+/** Create the `restore_file` tool. */
+export declare function createRestoreFileTool(): ToolDefinition<typeof restoreFileParams, RestoreFileData>;
+export {};

package/dist/tools/built-in/restore-file/restore-file.types.d.ts

@@ -0,0 +1,11 @@
+/** Structured payload returned by `restore_file`. */
+export interface RestoreFileData {
+    /** Always `true` on success. */
+    readonly restored: true;
+    /** Workspace-relative path where the file was restored. */
+    readonly path: string;
+    /** Absolute path of the trash archive this was restored from. */
+    readonly from: string;
+    /** Byte length of the restored content. */
+    readonly sizeBytes: number;
+}

package/dist/tools/built-in/run-command/index.d.ts

@@ -0,0 +1,2 @@
+export { createRunCommandTool } from "./run-command";
+export type { PlatformInfo, RunCommandData, RunCommandToolConfig, RunCommandToolConfigWithRequester, } from "./run-command.types";

package/dist/tools/built-in/run-command/run-command.constants.d.ts

@@ -0,0 +1,23 @@
+/** Default timeout: 60 seconds. */
+export declare const RUN_COMMAND_DEFAULT_TIMEOUT_MS = 60000;
+/** Hard cap on `timeoutMs`: 10 minutes. */
+export declare const RUN_COMMAND_MAX_TIMEOUT_MS: number;
+/** Maximum bytes captured from stdout before truncation flag is set. */
+export declare const RUN_COMMAND_MAX_STDOUT_BYTES = 1048576;
+/** Maximum bytes captured from stderr before truncation flag is set. */
+export declare const RUN_COMMAND_MAX_STDERR_BYTES = 1048576;
+/**
+ * Default deny patterns. Commands matching any of these are rejected
+ * outright with `permission_denied`. The patterns are intentionally
+ * conservative — they target catastrophic, irreversible operations.
+ */
+export declare const RUN_COMMAND_DEFAULT_DENY_PATTERNS: readonly RegExp[];
+/**
+ * Default approval-required patterns. Commands matching any of these
+ * route through the sandbox `PermissionRequester` with operation
+ * `"fs.exec"`. Empty by default — production deployments are expected
+ * to configure these on a per-environment basis.
+ */
+export declare const RUN_COMMAND_DEFAULT_REQUIRE_APPROVAL_PATTERNS: readonly RegExp[];
+/** Truncation marker appended to stdout/stderr when over the cap. */
+export declare const RUN_COMMAND_TRUNCATION_MARKER = "\n\u2026[output truncated by run_command]";

package/dist/tools/built-in/run-command/run-command.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { RunCommandData, RunCommandToolConfigWithRequester } from "./run-command.types";
+declare const runCommandParams: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    cwd?: string | undefined;
+    timeoutMs?: number | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    command: string;
+    cwd?: string | undefined;
+    timeoutMs?: number | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+export declare function createRunCommandTool(config?: RunCommandToolConfigWithRequester): ToolDefinition<typeof runCommandParams, RunCommandData>;
+export {};

package/dist/tools/built-in/run-command/run-command.types.d.ts

@@ -0,0 +1,81 @@
+import type { PermissionRequester } from "../../../sandbox/sandbox.types";
+/**
+ * Snapshot of the host platform captured when the tool factory is
+ * created. Surfaced in the tool description so the model knows which
+ * shell idioms (POSIX vs PowerShell, `brew` vs `apt`, etc.) apply.
+ */
+export interface PlatformInfo {
+    /** `process.platform` value (e.g. `"darwin"`, `"linux"`, `"win32"`). */
+    readonly platform: NodeJS.Platform;
+    /** Friendly OS name (e.g. `"macOS"`, `"Linux"`, `"Windows"`). */
+    readonly osName: string;
+    /** `os.release()` — kernel/build version string. */
+    readonly osRelease: string;
+    /** `process.arch` (e.g. `"arm64"`, `"x64"`). */
+    readonly arch: string;
+    /** Absolute path of the shell that will execute `command`. */
+    readonly shellPath: string;
+    /** Argv element used to invoke the shell with a command string. */
+    readonly shellFlag: string;
+    /** Runtime identifier: `"bun"` or `"node"` plus version. */
+    readonly runtime: string;
+}
+/** Configuration for `run_command`. */
+export interface RunCommandToolConfig {
+    /**
+     * Override the auto-detected platform info. Primarily intended for
+     * tests that need deterministic descriptions; production callers
+     * should leave this undefined.
+     */
+    readonly platformInfo?: PlatformInfo;
+    /**
+     * Regex patterns that mark commands as outright denied. Defaults to
+     * `RUN_COMMAND_DEFAULT_DENY_PATTERNS`. Provide `[]` to disable.
+     */
+    readonly denyPatterns?: readonly RegExp[];
+    /**
+     * Regex patterns that route commands through the sandbox
+     * PermissionRequester with operation `"fs.exec"`. Empty by default.
+     */
+    readonly requireApprovalPatterns?: readonly RegExp[];
+    /** Override stdout capture cap (bytes). */
+    readonly maxStdoutBytes?: number;
+    /** Override stderr capture cap (bytes). */
+    readonly maxStderrBytes?: number;
+    /** Override the default timeout (ms). */
+    readonly defaultTimeoutMs?: number;
+}
+/** Extended config that accepts an injected permission requester. */
+export interface RunCommandToolConfigWithRequester extends RunCommandToolConfig {
+    /**
+     * Permission requester invoked when the command matches a
+     * `requireApprovalPatterns` entry. If absent and an approval is
+     * required, the call fails closed with `permission_denied`.
+     */
+    readonly requestPermission?: PermissionRequester;
+}
+/** Structured payload returned by `run_command`. */
+export interface RunCommandData {
+    /** The command string as executed (echoed verbatim). */
+    readonly command: string;
+    /** Absolute cwd the command ran in. */
+    readonly cwd: string;
+    /** Exit code. `null` only when the process was killed before exiting. */
+    readonly exitCode: number | null;
+    /** Signal that terminated the process, if any (e.g. `"SIGTERM"`). */
+    readonly signal: NodeJS.Signals | null;
+    /** Captured stdout (UTF-8 decoded, truncated to `maxStdoutBytes`). */
+    readonly stdout: string;
+    /** Captured stderr (UTF-8 decoded, truncated to `maxStderrBytes`). */
+    readonly stderr: string;
+    /** True when stdout was truncated by the cap. */
+    readonly stdoutTruncated: boolean;
+    /** True when stderr was truncated by the cap. */
+    readonly stderrTruncated: boolean;
+    /** True when the command exceeded `timeoutMs`. */
+    readonly timedOut: boolean;
+    /** Wall-clock duration of the command in milliseconds. */
+    readonly durationMs: number;
+    /** Platform snapshot used by the tool — surfaced for the model. */
+    readonly platform: PlatformInfo;
+}