@infinityi/engine-lib 1.0.0 → 1.4.0

package/dist/tools-shell/index.js

@@ -0,0 +1,327 @@
+import {
+  s
+} from "../index-mnx5mqbs.js";
+import"../index-4c15ysa8.js";
+import {
+  ShellPolicyError
+} from "../index-ajr3nk10.js";
+import {
+  defineTool
+} from "../index-a67ej96j.js";
+import"../index-37x76zdn.js";
+
+// src/tools-shell/events.ts
+var SHELL_EVENT = {
+  policy: "shell.policy",
+  approval: "shell.approval",
+  execStart: "shell.exec.start",
+  execChunk: "shell.exec.chunk",
+  execEnd: "shell.exec.end"
+};
+function emit(ctx, name, data) {
+  ctx.run?.emit({ type: "custom", name, data });
+}
+function emitPolicy(ctx, decision, req, reason) {
+  emit(ctx, SHELL_EVENT.policy, {
+    decision,
+    command: req.command,
+    args: req.args,
+    mode: req.mode,
+    ...reason !== undefined ? { reason } : {}
+  });
+}
+function emitApproval(ctx, status, req, reason) {
+  emit(ctx, SHELL_EVENT.approval, {
+    status,
+    command: req.command,
+    args: req.args,
+    cwd: req.cwd,
+    mode: req.mode,
+    ...reason !== undefined ? { reason } : {}
+  });
+}
+function emitExecStart(ctx, req) {
+  emit(ctx, SHELL_EVENT.execStart, {
+    command: req.command,
+    args: req.args,
+    cwd: req.cwd,
+    mode: req.mode,
+    timeoutMs: req.timeoutMs
+  });
+}
+function emitExecChunk(ctx, stream, text) {
+  emit(ctx, SHELL_EVENT.execChunk, { stream, text });
+}
+function emitExecEnd(ctx, result) {
+  emit(ctx, SHELL_EVENT.execEnd, {
+    command: result.command,
+    exitCode: result.exitCode,
+    signal: result.signal,
+    timedOut: result.timedOut,
+    durationMs: result.durationMs,
+    stdoutTruncated: result.stdoutTruncated,
+    stderrTruncated: result.stderrTruncated
+  });
+}
+function emitExecError(ctx, req, error) {
+  emit(ctx, SHELL_EVENT.execEnd, {
+    command: req.command,
+    exitCode: null,
+    signal: null,
+    timedOut: false,
+    error
+  });
+}
+
+// src/tools-shell/exec.ts
+async function collectStream(stream, which, maxBytes, onChunk) {
+  if (stream === undefined)
+    return { text: "", truncated: false };
+  const reader = stream.getReader();
+  const chunkDecoder = new TextDecoder;
+  const kept = [];
+  let keptBytes = 0;
+  let truncated = false;
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      if (value === undefined || value.length === 0)
+        continue;
+      if (onChunk !== undefined) {
+        onChunk({ stream: which, text: chunkDecoder.decode(value, { stream: true }) });
+      }
+      if (keptBytes < maxBytes) {
+        const remaining = maxBytes - keptBytes;
+        if (value.length <= remaining) {
+          kept.push(value);
+          keptBytes += value.length;
+        } else {
+          kept.push(value.subarray(0, remaining));
+          keptBytes = maxBytes;
+          truncated = true;
+        }
+      } else {
+        truncated = true;
+      }
+    }
+    if (onChunk !== undefined) {
+      const tail = chunkDecoder.decode();
+      if (tail.length > 0)
+        onChunk({ stream: which, text: tail });
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const buf = new Uint8Array(keptBytes);
+  let offset = 0;
+  for (const part of kept) {
+    buf.set(part, offset);
+    offset += part.length;
+  }
+  return { text: new TextDecoder().decode(buf), truncated };
+}
+async function execCommand(opts) {
+  const startedAt = Date.now();
+  const proc = Bun.spawn({
+    cmd: [opts.command, ...opts.args],
+    cwd: opts.cwd,
+    env: opts.env,
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  let timedOut = false;
+  let abortKill = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill("SIGKILL");
+  }, opts.timeoutMs);
+  const onAbort = () => {
+    abortKill = true;
+    proc.kill("SIGKILL");
+  };
+  if (opts.signal !== undefined) {
+    if (opts.signal.aborted)
+      onAbort();
+    else
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+  }
+  try {
+    const [out, err] = await Promise.all([
+      collectStream(proc.stdout, "stdout", opts.maxOutputBytes, opts.onChunk),
+      collectStream(proc.stderr, "stderr", opts.maxOutputBytes, opts.onChunk),
+      proc.exited
+    ]);
+    return {
+      command: opts.command,
+      args: opts.args,
+      cwd: opts.cwd,
+      exitCode: proc.exitCode,
+      signal: proc.signalCode ?? null,
+      timedOut,
+      durationMs: Date.now() - startedAt,
+      stdout: out.text,
+      stderr: err.text,
+      stdoutTruncated: out.truncated,
+      stderrTruncated: err.truncated
+    };
+  } finally {
+    clearTimeout(timer);
+    opts.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+// src/tools-shell/policy.ts
+import { isAbsolute, relative, resolve } from "node:path";
+function normalizeAllowedCwds(allowedCwds) {
+  if (!Array.isArray(allowedCwds) || allowedCwds.length === 0) {
+    throw new ShellPolicyError("shellTools: `allowedCwds` must be a non-empty array of absolute paths");
+  }
+  return allowedCwds.map((dir) => {
+    if (typeof dir !== "string" || !isAbsolute(dir)) {
+      throw new ShellPolicyError(`shellTools: allowedCwds entry must be an absolute path, got ${JSON.stringify(dir)}`);
+    }
+    return resolve(dir);
+  });
+}
+function resolveCwd(requested, allowedRoots) {
+  const base = allowedRoots[0];
+  const abs = requested === undefined ? base : resolve(base, requested);
+  for (const root of allowedRoots) {
+    const rel = relative(root, abs);
+    if (rel === "" || !rel.startsWith("..") && !isAbsolute(rel))
+      return abs;
+  }
+  return null;
+}
+function matchesPattern(pattern, command, commandLine) {
+  if (typeof pattern === "string")
+    return pattern === command;
+  pattern.lastIndex = 0;
+  return pattern.test(commandLine);
+}
+function classifyCommand(command, args, policy) {
+  if (policy === undefined)
+    return { allowed: true };
+  const commandLine = [command, ...args].join(" ");
+  if (policy.deny?.some((p) => matchesPattern(p, command, commandLine))) {
+    return { allowed: false, reason: `command "${command}" is denied by policy` };
+  }
+  if (policy.allow !== undefined) {
+    const ok = policy.allow.some((p) => matchesPattern(p, command, commandLine));
+    if (!ok) {
+      return { allowed: false, reason: `command "${command}" is not in the allow-list` };
+    }
+  }
+  return { allowed: true };
+}
+function filterEnv(processEnv, policy) {
+  const out = {};
+  const deny = new Set(policy?.deny ?? []);
+  for (const name of policy?.allow ?? []) {
+    if (deny.has(name))
+      continue;
+    const value = processEnv[name];
+    if (value !== undefined)
+      out[name] = value;
+  }
+  for (const [name, value] of Object.entries(policy?.extra ?? {})) {
+    if (deny.has(name))
+      continue;
+    out[name] = value;
+  }
+  return out;
+}
+
+// src/tools-shell/define.ts
+var DEFAULT_TIMEOUT_MS = 30000;
+var DEFAULT_MAX_TIMEOUT_MS = 600000;
+var DEFAULT_MAX_OUTPUT_BYTES = 1e5;
+var PARAMS = s.object({
+  command: s.string({ description: "Program to run (argv[0]). Not interpreted by a shell." }),
+  args: s.optional(s.array(s.string(), { description: "Arguments passed to the program." })),
+  cwd: s.optional(s.string({ description: "Working directory. Must resolve within an allowed root." })),
+  timeoutMs: s.optional(s.number({ int: true, description: "Kill the command after this many milliseconds." }))
+});
+function toDecision(value) {
+  return typeof value === "boolean" ? { approved: value } : value;
+}
+function shellTools(config) {
+  const allowedRoots = normalizeAllowedCwds(config.allowedCwds);
+  const defaultTimeout = config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxTimeout = config.maxTimeoutMs ?? DEFAULT_MAX_TIMEOUT_MS;
+  const maxOutputBytes = config.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const build = (mode) => {
+    const name = mode === "run" ? "run_command" : "spawn_command";
+    const description = mode === "run" ? "Run a command to completion and return its captured stdout, stderr, and exit code." : "Run a command to completion, streaming its output, and return its exit code.";
+    return defineTool({
+      name,
+      description,
+      parameters: PARAMS,
+      async execute(rawArgs, ctx) {
+        const args = rawArgs;
+        const cmdArgs = args.args ?? [];
+        const cwd = resolveCwd(args.cwd, allowedRoots);
+        if (cwd === null) {
+          const reason = `cwd ${JSON.stringify(args.cwd ?? ".")} is outside the allowed roots`;
+          emitPolicy(ctx, "deny", { command: args.command, args: cmdArgs, mode }, reason);
+          return { ok: false, error: reason };
+        }
+        const verdict = classifyCommand(args.command, cmdArgs, config.policy);
+        if (!verdict.allowed) {
+          emitPolicy(ctx, "deny", { command: args.command, args: cmdArgs, mode }, verdict.reason);
+          return { ok: false, error: verdict.reason ?? "command denied by policy" };
+        }
+        emitPolicy(ctx, "allow", { command: args.command, args: cmdArgs, mode });
+        const timeoutMs = Math.min(args.timeoutMs !== undefined && args.timeoutMs > 0 ? args.timeoutMs : defaultTimeout, maxTimeout);
+        const req = {
+          command: args.command,
+          args: cmdArgs,
+          cwd,
+          timeoutMs,
+          mode
+        };
+        if (config.requiresApproval?.(req) === true) {
+          emitApproval(ctx, "requested", req);
+          const decision = toDecision(config.approve === undefined ? false : await config.approve(req));
+          if (!decision.approved) {
+            emitApproval(ctx, "denied", req, decision.reason);
+            return {
+              ok: false,
+              error: decision.reason ?? `command "${args.command}" was not approved`
+            };
+          }
+          emitApproval(ctx, "approved", req, decision.reason);
+        }
+        const env = filterEnv(process.env, config.env);
+        emitExecStart(ctx, req);
+        let result;
+        try {
+          result = await execCommand({
+            command: req.command,
+            args: req.args,
+            cwd: req.cwd,
+            env,
+            timeoutMs,
+            maxOutputBytes,
+            ...ctx.signal !== undefined ? { signal: ctx.signal } : {},
+            ...mode === "spawn" ? { onChunk: (c) => emitExecChunk(ctx, c.stream, c.text) } : {}
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          const error = `failed to run "${req.command}": ${message}`;
+          emitExecError(ctx, req, error);
+          return { ok: false, error };
+        }
+        emitExecEnd(ctx, result);
+        return { ok: true, content: result };
+      }
+    });
+  };
+  return { runCommand: build("run"), spawnCommand: build("spawn") };
+}
+export {
+  shellTools,
+  SHELL_EVENT
+};

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

@@ -0,0 +1,42 @@
+/**
+ * Pure policy functions for the `tools-shell` module: working-directory
+ * allowlisting, environment filtering, and command allow/deny classification.
+ *
+ * Everything here is side-effect-free and independently unit-testable — no
+ * spawning, no filesystem access. The tool's `execute` composes these gates
+ * before any process is created.
+ *
+ * @module
+ */
+import type { EnvPolicy, ShellPolicy } from "./types";
+/** Validate `allowedCwds` at factory-build time; throws on misconfiguration. */
+export declare function normalizeAllowedCwds(allowedCwds: readonly string[]): string[];
+/**
+ * Resolve a requested cwd against the allowlist. Returns the absolute path when
+ * it is one of the allowed roots or a descendant; returns `null` when it
+ * escapes every root. `requested` is resolved relative to the *first* allowed
+ * root when given as a relative path, so a bare `"."` maps into the sandbox
+ * rather than the host process cwd.
+ *
+ * Containment is checked on **logical paths only** — symlinks are not resolved.
+ * A symlink placed inside an allowed root that points outside it (e.g.
+ * `/root/link -> /etc`) would pass this check. Hosts in security-sensitive
+ * contexts should pre-resolve their `allowedCwds` with `fs.realpathSync` and
+ * avoid placing outward-pointing symlinks inside their sandbox roots.
+ */
+export declare function resolveCwd(requested: string | undefined, allowedRoots: readonly string[]): string | null;
+/**
+ * Decide whether a command is permitted by the allow/deny policy. Deny wins:
+ * a command matching any `deny` entry is rejected even if also allowed. When
+ * `allow` is present, the command must match at least one allow entry.
+ */
+export declare function classifyCommand(command: string, args: readonly string[], policy: ShellPolicy | undefined): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * Build the environment for a spawned command from the host process env and an
+ * {@link EnvPolicy}. With no `allow` list, **no** inherited variables are passed
+ * (only `extra`). `deny` strips names even when allowed; `extra` is merged last.
+ */
+export declare function filterEnv(processEnv: Readonly<Record<string, string | undefined>>, policy: EnvPolicy | undefined): Record<string, string>;

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

@@ -0,0 +1,121 @@
+/**
+ * Public types for the optional `@infinityi/engine-lib/tools-shell` module.
+ *
+ * This module is **not** part of the core library surface and is never imported
+ * by `runAgent`. It is an opt-in tool factory for hosts (coding terminals, ops
+ * agents) that need controlled command execution. Configuration lives entirely
+ * host-side — the model only ever supplies a {@link CommandRequest}, never the
+ * cwd allowlist, env filter, or policy.
+ *
+ * @module
+ */
+/**
+ * A command the model asked to run, after schema validation but before any
+ * policy/approval gating. Passed to {@link ShellToolsConfig.requiresApproval}
+ * and {@link ShellToolsConfig.approve}, and echoed in policy/approval events.
+ */
+export interface CommandRequest {
+    /** Program to execute (argv[0]). */
+    readonly command: string;
+    /** Arguments passed to the program. */
+    readonly args: readonly string[];
+    /** Working directory the command will run in (already resolved to absolute). */
+    readonly cwd: string;
+    /** Effective timeout in milliseconds. */
+    readonly timeoutMs: number;
+    /** `"run_command"` (buffered) or `"spawn_command"` (streamed). */
+    readonly mode: "run" | "spawn";
+}
+/** The structured outcome of a command, returned as the tool's `content`. */
+export interface CommandResult {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** Process exit code, or `null` when killed by a signal (e.g. timeout). */
+    readonly exitCode: number | null;
+    /** Signal that killed the process, or `null`. */
+    readonly signal: string | null;
+    /** `true` when the process was killed because it exceeded its timeout. */
+    readonly timedOut: boolean;
+    /** Wall-clock duration in milliseconds. */
+    readonly durationMs: number;
+    /** Captured stdout (truncated to {@link ShellToolsConfig.maxOutputBytes}). */
+    readonly stdout: string;
+    /** Captured stderr (truncated to {@link ShellToolsConfig.maxOutputBytes}). */
+    readonly stderr: string;
+    /** `true` when stdout was truncated at the byte cap. */
+    readonly stdoutTruncated: boolean;
+    /** `true` when stderr was truncated at the byte cap. */
+    readonly stderrTruncated: boolean;
+}
+/** A pattern matched against a command — exact string (against argv[0]) or regex (against the full command line). */
+export type CommandPattern = string | RegExp;
+/** Allow/deny rules for which commands may run. Deny always wins. */
+export interface ShellPolicy {
+    /**
+     * If present, a command must match at least one entry to be permitted.
+     * Omitted → all commands are permitted unless denied.
+     */
+    readonly allow?: readonly CommandPattern[];
+    /** A command matching any entry is rejected, even if also allowed. */
+    readonly deny?: readonly CommandPattern[];
+}
+/** Inherited-environment filtering for spawned commands. */
+export interface EnvPolicy {
+    /**
+     * Names of process env vars to pass through. Omitted → **no** inherited vars
+     * are passed (safest default); only {@link EnvPolicy.extra} is provided.
+     */
+    readonly allow?: readonly string[];
+    /** Names always stripped, even if listed in {@link EnvPolicy.allow}. */
+    readonly deny?: readonly string[];
+    /** Extra vars merged on top of the (filtered) inherited set. */
+    readonly extra?: Readonly<Record<string, string>>;
+}
+/** A host's decision on an approval request. */
+export interface ApprovalDecision {
+    readonly approved: boolean;
+    /** Optional human-readable reason, surfaced in the approval event and on denial. */
+    readonly reason?: string;
+}
+/** Host-side configuration for {@link shellTools}. Never exposed to the model. */
+export interface ShellToolsConfig {
+    /**
+     * Absolute directory roots a command may run under. A request's `cwd` must
+     * resolve to one of these or a descendant. Required and non-empty — there is
+     * no implicit default, so a command can never run somewhere unintended.
+     *
+     * Containment is a logical-path check that does not resolve symlinks; in
+     * security-sensitive contexts pre-resolve these with `fs.realpathSync` and
+     * keep outward-pointing symlinks out of the roots.
+     */
+    readonly allowedCwds: readonly string[];
+    /** Inherited-env filtering. Defaults to "no inherited vars". */
+    readonly env?: EnvPolicy;
+    /** Command allow/deny rules. Omitted → all commands allowed. */
+    readonly policy?: ShellPolicy;
+    /**
+     * Flag a command as destructive / requiring approval before it runs. When it
+     * returns `true`, {@link ShellToolsConfig.approve} is consulted; if `approve`
+     * is absent or denies, the command never executes.
+     */
+    readonly requiresApproval?: (req: CommandRequest) => boolean;
+    /**
+     * Approval hook invoked only when {@link ShellToolsConfig.requiresApproval}
+     * returns `true`. Return `true`/`false` or an {@link ApprovalDecision}.
+     */
+    readonly approve?: (req: CommandRequest) => boolean | ApprovalDecision | Promise<boolean | ApprovalDecision>;
+    /** Timeout applied when the model omits `timeoutMs`. Defaults to 30_000. */
+    readonly defaultTimeoutMs?: number;
+    /** Upper bound clamping any model-supplied `timeoutMs`. Defaults to 600_000. */
+    readonly maxTimeoutMs?: number;
+    /** Byte cap per stream (stdout / stderr) before truncation. Defaults to 100_000. */
+    readonly maxOutputBytes?: number;
+}
+/** The pair of tool definitions returned by {@link shellTools}. */
+export interface ShellTools {
+    /** Buffered execution — awaits completion, returns captured output. */
+    readonly runCommand: import("../tools/types").ToolDefinition;
+    /** Streamed execution — emits output incrementally onto the run event stream. */
+    readonly spawnCommand: import("../tools/types").ToolDefinition;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Higher-level web/search tool definitions.
+ *
+ * These tools intentionally stay static: they do not execute JavaScript, do not
+ * launch a browser, and require an injected search provider for web search.
+ *
+ * @module
+ */
+import type { WebTools, WebToolsConfig } from "./types";
+/** Build the web/search tools bound to host HTTP and robots policy. */
+export declare function webTools(config: WebToolsConfig): WebTools;

package/dist/tools-web/html.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Static HTML parsing helpers for `tools-web`.
+ *
+ * LinkeDOM is used as a local DOM implementation. Scripts are not executed and
+ * no browser is launched.
+ *
+ * @module
+ */
+export interface ParsedPage {
+    readonly title?: string;
+    readonly text: string;
+    readonly links: readonly {
+        readonly url: string;
+        readonly text?: string;
+    }[];
+}
+/** Parse title, visible-ish text, and absolute links from a static HTML string. */
+export declare function parseStaticHtml(html: string, baseUrl: string, maxLinks?: number): ParsedPage;
+/** Parse an HTML document for Readability. */
+export declare function readabilityDocument(html: string): unknown;
+/** Collapse arbitrary text into a compact model-facing string. */
+export declare function compactText(text: string): string;

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

@@ -0,0 +1,21 @@
+/**
+ * `@infinityi/engine-lib/tools-web` - optional static web/search tools.
+ *
+ * This subpath builds on `tools-http` and remains opt-in. It ships no search
+ * vendor adapter and does not execute JavaScript or launch a browser.
+ *
+ * @example
+ * ```ts
+ * import { webTools } from "@infinityi/engine-lib/tools-web";
+ *
+ * const web = webTools({
+ *   allowPublicInternet: true,
+ *   robots: "enforce",
+ *   searchProvider,
+ * });
+ * ```
+ *
+ * @module
+ */
+export { webTools } from "./define";
+export type { Citation, RobotsPolicy, SearchProvider, SearchRequest, SearchResult, SourceMetadata, WebTools, WebToolsConfig, } from "./types";