@infinityi/engine-lib 1.0.0 → 1.4.0

package/dist/tools-fs/policy.d.ts

@@ -0,0 +1,32 @@
+import type { FilesystemToolsConfig } from "./types";
+export interface AllowedRoot {
+    readonly logical: string;
+    readonly real: string;
+}
+export interface FilesystemPolicy {
+    readonly allowedRoots: readonly AllowedRoot[];
+    readonly defaultRoot: string;
+    readonly defaultRootReal: string;
+    readonly maxReadBytes: number;
+    readonly maxWriteBytes: number;
+    readonly maxEntries: number;
+    readonly maxResults: number;
+}
+export interface ResolvedPath {
+    readonly path: string;
+    readonly root: string;
+    readonly realPath?: string;
+}
+export declare class FilesystemAccessError extends Error {
+    constructor(message: string);
+}
+export declare function normalizePathForOutput(path: string): string;
+export declare function isInside(root: string, candidate: string): boolean;
+export declare function displayPath(root: string, path: string): string;
+export declare function normalizeFilesystemPolicy(config: FilesystemToolsConfig): FilesystemPolicy;
+export declare function resolvePath(policy: FilesystemPolicy, input: string | undefined, options?: {
+    readonly base?: string;
+    readonly mustExist?: boolean;
+    readonly forCreate?: boolean;
+}): Promise<ResolvedPath>;
+export declare function resolveRoot(policy: FilesystemPolicy, input: string | undefined): Promise<ResolvedPath>;

package/dist/tools-fs/schemas.d.ts

@@ -0,0 +1,31 @@
+import type { JsonSchema, Schema } from "../schema/types";
+import type { ApplyPatchArgs, DiffStatusArgs, EditRangeArgs, EditReplaceArgs, FindFilesArgs, OpenWindowArgs, ReadArgs, RepoMapArgs, SearchSemanticArgs, SearchTextArgs, SymbolsArgs, WriteFileArgs } from "./types";
+interface RawJsonSchema {
+    readonly type?: JsonSchema["type"];
+    readonly description?: string;
+    readonly properties?: Readonly<Record<string, RawJsonSchema>>;
+    readonly required?: readonly string[];
+    readonly items?: RawJsonSchema;
+    readonly enum?: ReadonlyArray<string | number>;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly oneOf?: readonly RawJsonSchema[];
+    readonly default?: unknown;
+    readonly additionalProperties?: boolean | RawJsonSchema;
+}
+export declare function toolSchema<T>(jsonSchema: RawJsonSchema): Schema<T>;
+export declare const SCHEMAS: {
+    readonly repoMap: Schema<RepoMapArgs>;
+    readonly findFiles: Schema<FindFilesArgs>;
+    readonly searchText: Schema<SearchTextArgs>;
+    readonly searchSemantic: Schema<SearchSemanticArgs>;
+    readonly symbols: Schema<SymbolsArgs>;
+    readonly read: Schema<ReadArgs>;
+    readonly openWindow: Schema<OpenWindowArgs>;
+    readonly editReplace: Schema<EditReplaceArgs>;
+    readonly editRange: Schema<EditRangeArgs>;
+    readonly applyPatch: Schema<ApplyPatchArgs>;
+    readonly writeFile: Schema<WriteFileArgs>;
+    readonly diffStatus: Schema<DiffStatusArgs>;
+};
+export {};

package/dist/tools-fs/search.d.ts

@@ -0,0 +1,45 @@
+export interface TextSearchResult {
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly preview: string;
+    readonly context: readonly {
+        readonly line: number;
+        readonly text: string;
+        readonly match: boolean;
+    }[];
+}
+export interface SemanticSearchResult {
+    readonly path: string;
+    readonly score: number;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly preview: string;
+    readonly symbol?: string;
+}
+export declare function searchText(root: string, options: {
+    readonly pattern: string;
+    readonly mode: "literal" | "regex";
+    readonly includeGlobs?: readonly string[];
+    readonly excludeGlobs?: readonly string[];
+    readonly caseSensitive: boolean;
+    readonly contextLines: number;
+    readonly maxResults: number;
+    readonly maxPreviewChars: number;
+}): Promise<{
+    readonly results: TextSearchResult[];
+    readonly backend: "ripgrep" | "node";
+    readonly truncated: boolean;
+}>;
+export declare function searchSemantic(root: string, options: {
+    readonly query: string;
+    readonly includeGlobs?: readonly string[];
+    readonly excludeGlobs?: readonly string[];
+    readonly granularity: "file" | "chunk" | "symbol";
+    readonly maxResults: number;
+    readonly maxPreviewChars: number;
+}): Promise<{
+    readonly results: SemanticSearchResult[];
+    readonly truncated: boolean;
+}>;
+export declare function parentDirectory(path: string): string;

package/dist/tools-fs/symbols.d.ts

@@ -0,0 +1,12 @@
+import type { FilesystemPolicy } from "./policy";
+import type { SymbolInfo, SymbolKind } from "./types";
+export declare function symbolsForFile(absPath: string, root: string, maxBytes: number, kinds?: readonly SymbolKind[]): Promise<SymbolInfo[]>;
+export declare function symbolsForPath(policy: FilesystemPolicy, input: string, options?: {
+    readonly recursive?: boolean;
+    readonly kinds?: readonly SymbolKind[];
+    readonly maxResults?: number;
+}): Promise<{
+    readonly results: SymbolInfo[];
+    readonly truncated: boolean;
+    readonly root: string;
+}>;

package/dist/tools-fs/types.d.ts

@@ -0,0 +1,151 @@
+import type { ToolContext, ToolDefinition } from "../tools/types";
+export interface ValidationCommandResult {
+    readonly ok: boolean;
+    readonly command: string;
+    readonly exitCode?: number | null;
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export interface ValidationCommandRequest {
+    readonly cwd: string;
+    readonly changedFiles: readonly string[];
+    readonly ctx: ToolContext;
+}
+export interface FilesystemToolsConfig {
+    /** Absolute directories that every filesystem operation must remain within. */
+    readonly allowedRoots: readonly string[];
+    /** Default workspace root. Relative paths resolve from here. Defaults to the first allowed root. */
+    readonly defaultRoot?: string;
+    readonly maxReadBytes?: number;
+    readonly maxWriteBytes?: number;
+    readonly maxEntries?: number;
+    readonly maxResults?: number;
+    /**
+     * Optional host hook for validation commands requested by edit tools.
+     * When omitted, requested commands are reported as skipped rather than run.
+     */
+    readonly runValidationCommand?: (command: string, request: ValidationCommandRequest) => ValidationCommandResult | Promise<ValidationCommandResult>;
+}
+export interface ValidationOptions {
+    readonly syntax?: boolean;
+    readonly format?: boolean;
+    readonly tests?: readonly string[];
+}
+export interface RepoMapArgs {
+    readonly root?: string;
+    readonly depth?: number;
+    readonly include_files?: boolean;
+    readonly include_symbols?: boolean;
+    readonly max_entries?: number;
+    readonly respect_gitignore?: boolean;
+}
+export interface FindFilesArgs {
+    readonly query: string;
+    readonly mode?: "auto" | "exact" | "glob" | "fuzzy" | "extension" | "regex";
+    readonly root?: string;
+    readonly include_hidden?: boolean;
+    readonly respect_gitignore?: boolean;
+    readonly max_results?: number;
+}
+export interface SearchTextArgs {
+    readonly pattern: string;
+    readonly mode?: "literal" | "regex";
+    readonly root?: string;
+    readonly include_globs?: readonly string[];
+    readonly exclude_globs?: readonly string[];
+    readonly case_sensitive?: boolean;
+    readonly context_lines?: number;
+    readonly max_results?: number;
+    readonly max_preview_chars?: number;
+    readonly use_index?: boolean;
+}
+export interface SearchSemanticArgs {
+    readonly query: string;
+    readonly root?: string;
+    readonly include_globs?: readonly string[];
+    readonly exclude_globs?: readonly string[];
+    readonly granularity?: "file" | "chunk" | "symbol";
+    readonly max_results?: number;
+    readonly max_preview_chars?: number;
+}
+export interface SymbolsArgs {
+    readonly path: string;
+    readonly recursive?: boolean;
+    readonly symbol_kinds?: readonly SymbolKind[];
+    readonly max_results?: number;
+}
+export type SymbolKind = "class" | "function" | "method" | "interface" | "type" | "variable" | "import" | "export";
+export interface ReadArgs {
+    readonly path: string;
+    readonly start_line?: number;
+    readonly end_line?: number;
+    readonly symbol?: string;
+    readonly max_bytes?: number;
+    readonly include_line_numbers?: boolean;
+    readonly collapse_imports?: boolean;
+    readonly collapse_comments?: boolean;
+}
+export interface OpenWindowArgs {
+    readonly path: string;
+    readonly anchor?: number | string;
+    readonly window_lines?: number;
+    readonly direction?: "center" | "next" | "prev";
+}
+export interface EditReplaceArgs {
+    readonly path: string;
+    readonly old_text: string;
+    readonly new_text: string;
+    readonly occurrence?: number;
+    readonly expected_file_version?: string;
+    readonly validate?: ValidationOptions;
+}
+export interface EditRangeArgs {
+    readonly path: string;
+    readonly start_line: number;
+    readonly end_line: number;
+    readonly new_text: string;
+    readonly expected_file_version: string;
+    readonly validate?: ValidationOptions;
+}
+export interface ApplyPatchArgs {
+    readonly patch: string;
+    readonly root?: string;
+    readonly dry_run?: boolean;
+    readonly expected_versions?: Readonly<Record<string, string>>;
+    readonly validate?: ValidationOptions;
+}
+export interface WriteFileArgs {
+    readonly path: string;
+    readonly content: string;
+    readonly mode?: "create_only" | "overwrite" | "append";
+    readonly expected_file_version?: string;
+    readonly create_dirs?: boolean;
+}
+export interface DiffStatusArgs {
+    readonly paths?: readonly string[];
+    readonly include_diff?: boolean;
+    readonly max_diff_chars?: number;
+    readonly context_lines?: number;
+}
+export interface SymbolInfo {
+    readonly path: string;
+    readonly name: string;
+    readonly kind: SymbolKind;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly signature?: string;
+}
+export interface FilesystemTools {
+    readonly repoMap: ToolDefinition<RepoMapArgs>;
+    readonly findFiles: ToolDefinition<FindFilesArgs>;
+    readonly searchText: ToolDefinition<SearchTextArgs>;
+    readonly searchSemantic: ToolDefinition<SearchSemanticArgs>;
+    readonly symbols: ToolDefinition<SymbolsArgs>;
+    readonly read: ToolDefinition<ReadArgs>;
+    readonly openWindow: ToolDefinition<OpenWindowArgs>;
+    readonly editReplace: ToolDefinition<EditReplaceArgs>;
+    readonly editRange: ToolDefinition<EditRangeArgs>;
+    readonly applyPatch: ToolDefinition<ApplyPatchArgs>;
+    readonly writeFile: ToolDefinition<WriteFileArgs>;
+    readonly diffStatus: ToolDefinition<DiffStatusArgs>;
+}

package/dist/tools-http/client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Low-level HTTP client for `tools-http`.
+ *
+ * It performs policy checks before every request and redirect target, follows
+ * redirects manually, uses Forge resilience for retry/timeout, and returns a
+ * compact parsed response.
+ *
+ * @module
+ */
+import type { HttpToolClient, HttpToolsConfig } from "./types";
+/** Create a policy-gated HTTP client. */
+export declare function createHttpToolClient(config: HttpToolsConfig): HttpToolClient;

package/dist/tools-http/define.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ready-made HTTP tool definitions.
+ *
+ * The factory is intentionally thin: host configuration is bound once, model
+ * arguments are validated through JSON Schema, and every expected failure is
+ * returned as a tool error.
+ *
+ * @module
+ */
+import type { HttpTools, HttpToolsConfig } from "./types";
+/** Build the `http_get` and `http_post` tools bound to host policy. */
+export declare function httpTools(config: HttpToolsConfig): HttpTools;

package/dist/tools-http/events.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Custom run events emitted by `@infinityi/engine-lib/tools-http`.
+ *
+ * Emission is a no-op outside `runAgent`, matching the other optional tool
+ * packs. Events are intentionally compact and avoid response bodies.
+ *
+ * @module
+ */
+import type { ToolContext } from "../tools/types";
+import type { HttpRequestResult } from "./types";
+/** Event names emitted by the HTTP tool module. */
+export declare const HTTP_EVENT: {
+    readonly policy: "http.policy";
+    readonly requestStart: "http.request.start";
+    readonly requestEnd: "http.request.end";
+};
+/** Surface a URL policy decision. */
+export declare function emitHttpPolicy(ctx: ToolContext | undefined, decision: "allow" | "deny", url: string, reason?: string): void;
+/** Surface the beginning of a logical HTTP request. */
+export declare function emitHttpRequestStart(ctx: ToolContext | undefined, method: string, url: string, timeoutMs: number): void;
+/** Surface the end of a logical HTTP request or a transport failure. */
+export declare function emitHttpRequestEnd(ctx: ToolContext | undefined, method: string, url: string, result: HttpRequestResult | undefined, error?: string): void;

package/dist/tools-http/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@infinityi/engine-lib/tools-http` - optional, policy-gated HTTP tools.
+ *
+ * This subpath is intentionally absent from the root barrel. Hosts must opt in
+ * and provide explicit network scope with either `allowedHosts` or
+ * `allowPublicInternet: true`.
+ *
+ * @example
+ * ```ts
+ * import { httpTools } from "@infinityi/engine-lib/tools-http";
+ *
+ * const http = httpTools({
+ *   allowedHosts: ["api.example.com"],
+ *   defaultHeaders: [{ name: "accept", value: "application/json" }],
+ * });
+ * ```
+ *
+ * @module
+ */
+export { createHttpToolClient } from "./client";
+export { httpTools } from "./define";
+export { HTTP_EVENT } from "./events";
+export { HttpPolicyError } from "./policy";
+export type { HeaderEntry, HostPattern, HttpClientRequest, HttpPolicy, HttpRequestResult, HttpRetryOptions, HttpToolClient, HttpTools, HttpToolsConfig, } from "./types";

package/dist/tools-http/index.js

@@ -0,0 +1,18 @@
+import {
+  HTTP_EVENT,
+  HttpPolicyError,
+  createHttpToolClient,
+  httpTools
+} from "../index-mr1hs98z.js";
+import"../index-k0q7x4mz.js";
+import"../index-zdggff0y.js";
+import"../index-4c15ysa8.js";
+import"../index-ajr3nk10.js";
+import"../index-a67ej96j.js";
+import"../index-37x76zdn.js";
+export {
+  httpTools,
+  createHttpToolClient,
+  HttpPolicyError,
+  HTTP_EVENT
+};

package/dist/tools-http/policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure policy helpers for `tools-http`.
+ *
+ * Host configuration is normalized eagerly by the factory/client. Per-request
+ * denials throw {@link HttpPolicyError}; ready-made tools catch these and
+ * return `{ ok: false, error }`.
+ *
+ * @module
+ */
+import type { HeaderEntry, HostPattern, HttpToolsConfig } from "./types";
+/** Host-side HTTP policy/configuration error. */
+export declare class HttpPolicyError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export interface NormalizedHttpConfig {
+    readonly allowPublicInternet: boolean;
+    readonly allowedHosts: readonly HostPattern[];
+    readonly deniedHosts: readonly HostPattern[];
+    readonly allowedProtocols: readonly string[];
+    readonly allowPrivateNetwork: boolean;
+    readonly allowCredentialedUrls: boolean;
+    readonly defaultHeaders: readonly HeaderEntry[];
+    readonly allowedRequestHeaders: ReadonlySet<string>;
+    readonly responseHeaderAllowlist: ReadonlySet<string>;
+    readonly defaultTimeoutMs: number;
+    readonly minTimeoutMs: number;
+    readonly maxTimeoutMs: number;
+    readonly maxResponseBytes: number;
+    readonly maxBodyChars: number;
+    readonly maxRedirects: number;
+    readonly retryMaxAttempts: number;
+    readonly retryInitialDelayMs: number;
+    readonly retryMaxDelayMs: number;
+    readonly retryUnsafeMethods: boolean;
+    readonly fetch: typeof fetch;
+}
+/** Normalize and validate host configuration. */
+export declare function normalizeHttpConfig(config: HttpToolsConfig): NormalizedHttpConfig;
+/** Clamp a caller/model-supplied number into a host-approved range. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Match a URL against a host policy pattern. */
+export declare function matchesHost(url: URL, pattern: HostPattern): boolean;
+/** Whether a hostname is an explicit private/local target. */
+export declare function isPrivateTarget(hostname: string): boolean;
+/** Validate one URL against the host-side HTTP policy. */
+export declare function assertUrlAllowed(url: URL, config: NormalizedHttpConfig): void;
+/** Convert model-supplied headers into the subset permitted by config. */
+export declare function buildRequestHeaders(config: NormalizedHttpConfig, modelHeaders: readonly HeaderEntry[] | undefined, contentType?: string, options?: {
+    includeConfiguredHeaders?: boolean;
+}): Headers;
+/** Return response headers filtered through the configured allowlist. */
+export declare function allowedResponseHeaders(headers: Headers, allowlist: ReadonlySet<string>): readonly HeaderEntry[];

package/dist/tools-http/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Public types for `@infinityi/engine-lib/tools-http`.
+ *
+ * The module is opt-in and host-configured: network scope, default headers,
+ * timeout limits, and response caps are all supplied by the application, not by
+ * the model. Per-call failures are returned as tool errors by the ready-made
+ * tools; the lower-level client throws ordinary errors for callers to handle.
+ *
+ * @module
+ */
+import type { ToolDefinition } from "../tools/types";
+/** A hostname policy entry. Strings support exact hosts, `host:port`, `*`, and `*.example.com`. */
+export type HostPattern = string | RegExp;
+/** A normalized HTTP header entry. */
+export interface HeaderEntry {
+    readonly name: string;
+    readonly value: string;
+}
+/** Host-side network policy for low-level HTTP access. */
+export interface HttpPolicy {
+    /**
+     * Hosts the tools may contact. Required unless
+     * {@link HttpToolsConfig.allowPublicInternet} is true.
+     */
+    readonly allowedHosts?: readonly HostPattern[];
+    /** Hosts denied even when otherwise allowed. Deny wins over allow. */
+    readonly deniedHosts?: readonly HostPattern[];
+    /** Allowed URL protocols. Defaults to `["https:", "http:"]`. */
+    readonly allowedProtocols?: readonly string[];
+    /** Allow private, loopback, link-local, multicast, and localhost targets. Defaults to false. */
+    readonly allowPrivateNetwork?: boolean;
+    /** Allow URLs with embedded username/password credentials. Defaults to false. */
+    readonly allowCredentialedUrls?: boolean;
+}
+/** Retry behavior for the HTTP client. */
+export interface HttpRetryOptions {
+    /** Maximum attempts for retry-enabled methods. Defaults to 3. */
+    readonly maxAttempts?: number;
+    /** Initial exponential backoff delay in ms. Defaults to 100. */
+    readonly initialDelayMs?: number;
+    /** Maximum exponential backoff delay in ms. Defaults to 2_000. */
+    readonly maxDelayMs?: number;
+    /** Retry POST/other unsafe methods too. Defaults to false. */
+    readonly retryUnsafeMethods?: boolean;
+}
+/** Configuration for {@link httpTools} and {@link createHttpToolClient}. */
+export interface HttpToolsConfig extends HttpPolicy {
+    /**
+     * Permit any public host. At least one of this or `allowedHosts` is required
+     * so hosts opt into network scope explicitly.
+     */
+    readonly allowPublicInternet?: boolean;
+    /** Headers supplied by the host on every request. */
+    readonly defaultHeaders?: readonly HeaderEntry[] | Readonly<Record<string, string>>;
+    /** Model-supplied request headers accepted by name. Defaults to none. */
+    readonly allowedRequestHeaders?: readonly string[];
+    /** Response headers exposed in results. Defaults to a compact safe allowlist. */
+    readonly responseHeaderAllowlist?: readonly string[];
+    /** Default per-attempt timeout. Defaults to 10_000ms. */
+    readonly defaultTimeoutMs?: number;
+    /** Minimum accepted timeout after clamping. Defaults to 100ms. */
+    readonly minTimeoutMs?: number;
+    /** Maximum accepted timeout after clamping. Defaults to 60_000ms. */
+    readonly maxTimeoutMs?: number;
+    /** Maximum bytes read from a response body. Defaults to 1_000_000. */
+    readonly maxResponseBytes?: number;
+    /** Maximum characters returned for parsed text bodies. Defaults to 20_000. */
+    readonly maxBodyChars?: number;
+    /** Maximum followed redirects. Defaults to 5. */
+    readonly maxRedirects?: number;
+    /** Retry configuration. GET retries are enabled by default. */
+    readonly retry?: HttpRetryOptions;
+    /** Inject a fetch implementation for tests or custom transports. */
+    readonly fetch?: typeof fetch;
+}
+/** A client request after tool argument mapping. */
+export interface HttpClientRequest {
+    readonly method: "GET" | "POST";
+    readonly url: string;
+    readonly headers?: readonly HeaderEntry[];
+    readonly body?: string;
+    readonly bodyJson?: unknown;
+    readonly contentType?: string;
+    readonly timeoutMs?: number;
+    readonly maxBytes?: number;
+    readonly maxBodyChars?: number;
+}
+/** Compact metadata and parsed body for a received HTTP response. */
+export interface HttpRequestResult {
+    readonly url: string;
+    readonly finalUrl: string;
+    readonly redirected: boolean;
+    readonly redirects: readonly string[];
+    readonly status: number;
+    readonly statusText: string;
+    readonly contentType?: string;
+    readonly headers: readonly HeaderEntry[];
+    readonly body?: string;
+    readonly bodyJson?: unknown;
+    readonly bodyOmitted: boolean;
+    readonly bodyTruncated: boolean;
+    readonly responseBytes: number;
+    readonly responseBytesTruncated: boolean;
+    readonly elapsedMs: number;
+}
+/** Low-level HTTP client backing both the HTTP and web tool packs. */
+export interface HttpToolClient {
+    request(req: HttpClientRequest, ctx?: import("../tools/types").ToolContext): Promise<HttpRequestResult>;
+    get(url: string, options?: Omit<HttpClientRequest, "method" | "url" | "body" | "bodyJson" | "contentType">, ctx?: import("../tools/types").ToolContext): Promise<HttpRequestResult>;
+    post(url: string, options?: Omit<HttpClientRequest, "method" | "url">, ctx?: import("../tools/types").ToolContext): Promise<HttpRequestResult>;
+}
+/** The ready-made HTTP tool definitions. */
+export interface HttpTools {
+    readonly httpGet: ToolDefinition;
+    readonly httpPost: ToolDefinition;
+}

package/dist/tools-shell/define.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `shellTools` — the optional, policy-gated command-execution tool factory.
+ *
+ * Returns two {@link ToolDefinition}s, `run_command` (buffered) and
+ * `spawn_command` (streamed), that share one execution pipeline:
+ *
+ *   validate cwd → classify command → (approval) → filter env → spawn → result
+ *
+ * Each gate emits a `custom` {@link RunEvent} so the host's existing
+ * subscribers/auditing see every policy decision, approval, and execution. A
+ * command never runs silently: a denied cwd, a denied command, or a withheld
+ * approval all return `{ ok: false, error }` *before* any process is created.
+ *
+ * @module
+ */
+import type { ShellToolsConfig, ShellTools } from "./types";
+/**
+ * Build a `run_command` / `spawn_command` pair bound to `config`.
+ *
+ * @throws {@link ShellPolicyError} if `allowedCwds` is empty or contains a
+ * non-absolute path (a host-side configuration fault, raised eagerly here).
+ */
+export declare function shellTools(config: ShellToolsConfig): ShellTools;

package/dist/tools-shell/events.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Helpers that surface shell policy / approval / execution metadata onto the
+ * run's event stream as generic `custom` {@link RunEvent}s.
+ *
+ * All events share the `"shell."` name prefix so subscribers can filter the
+ * module's traffic. Emission goes through {@link ToolContext.run} (the
+ * {@link RunBridge}) and is a no-op when the tool runs outside `runAgent`, so a
+ * tool invoked directly in a test still works without a run.
+ *
+ * @module
+ */
+import type { ToolContext } from "../tools/types";
+import type { CommandRequest, CommandResult } from "./types";
+/** Event names emitted by this module, under the shared `shell.` namespace. */
+export declare const SHELL_EVENT: {
+    readonly policy: "shell.policy";
+    readonly approval: "shell.approval";
+    readonly execStart: "shell.exec.start";
+    readonly execChunk: "shell.exec.chunk";
+    readonly execEnd: "shell.exec.end";
+};
+/** A policy decision (cwd allowlist or command allow/deny). */
+export declare function emitPolicy(ctx: ToolContext, decision: "allow" | "deny", req: Pick<CommandRequest, "command" | "args" | "mode">, reason?: string): void;
+/** An approval lifecycle update. */
+export declare function emitApproval(ctx: ToolContext, status: "requested" | "approved" | "denied", req: CommandRequest, reason?: string): void;
+/** Execution is about to begin. */
+export declare function emitExecStart(ctx: ToolContext, req: CommandRequest): void;
+/** A streamed output chunk (only `spawn_command` emits these). */
+export declare function emitExecChunk(ctx: ToolContext, stream: "stdout" | "stderr", text: string): void;
+/** Execution finished; carries the structured result summary. */
+export declare function emitExecEnd(ctx: ToolContext, result: CommandResult): void;
+/**
+ * Execution failed before producing a result (the process could not be
+ * spawned). Emits a closing `shell.exec.end` so subscribers that pair
+ * start/end events always see the span close, with `error` set and `exitCode`
+ * null to mark that the command never ran.
+ */
+export declare function emitExecError(ctx: ToolContext, req: CommandRequest, error: string): void;

package/dist/tools-shell/exec.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The process-execution primitive behind both shell tools: a single
+ * `Bun.spawn` wrapper that enforces a timeout, captures stdout/stderr with
+ * byte-bounded truncation, and reports the exit code / signal.
+ *
+ * It has no knowledge of policy, approval, or events — those are layered on in
+ * `define.ts`. The only difference between the buffered (`run_command`) and
+ * streamed (`spawn_command`) tools is the optional {@link ExecOptions.onChunk}
+ * callback, which fires per output chunk as it arrives.
+ *
+ * @module
+ */
+import type { CommandResult } from "./types";
+/** A streamed output chunk delivered to {@link ExecOptions.onChunk}. */
+export interface ExecChunk {
+    readonly stream: "stdout" | "stderr";
+    readonly text: string;
+}
+/** Inputs to {@link execCommand}. */
+export interface ExecOptions {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+    readonly timeoutMs: number;
+    readonly maxOutputBytes: number;
+    /** Called for each output chunk as it streams in (used by `spawn_command`). */
+    readonly onChunk?: (chunk: ExecChunk) => void;
+    /** Caller cancellation (the run's `AbortSignal`); kills the process if aborted. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Spawn a command and resolve with a structured {@link CommandResult}. Never
+ * rejects for a non-zero exit — a failed command is data the model should see.
+ * Rejects only if the process cannot be spawned at all (e.g. unknown program).
+ */
+export declare function execCommand(opts: ExecOptions): Promise<CommandResult>;

package/dist/tools-shell/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@infinityi/engine-lib/tools-shell` — an **optional** module providing safe,
+ * policy-gated command execution as ready-made tools.
+ *
+ * The core library ships no code-execution tools by design. This subpath is the
+ * opt-in exception for hosts that need it (coding terminals, ops agents): a
+ * single {@link shellTools} factory yields `run_command` (buffered) and
+ * `spawn_command` (streamed) tools wrapped in working-directory allowlists,
+ * environment filtering, command allow/deny policy, and optional approval
+ * hooks. Every decision is surfaced as a `custom` run event for auditing.
+ *
+ * @example
+ * ```ts
+ * import { shellTools } from "@infinityi/engine-lib/tools-shell";
+ * import { defineAgent } from "@infinityi/engine-lib/agent";
+ *
+ * const { runCommand } = shellTools({
+ *   allowedCwds: [process.cwd()],
+ *   policy: { deny: [/\brm\b/, /\bsudo\b/] },
+ *   env: { allow: ["PATH", "HOME"] },
+ * });
+ *
+ * const agent = defineAgent({ name: "ops", tools: [runCommand], ... });
+ * ```
+ *
+ * @module
+ */
+export { shellTools } from "./define";
+export { SHELL_EVENT } from "./events";
+export type { ApprovalDecision, CommandPattern, CommandRequest, CommandResult, EnvPolicy, ShellPolicy, ShellTools, ShellToolsConfig, } from "./types";