agent.libx.js 0.86.0

package/dist/tools-Ch-OzOU8.d.ts

@@ -0,0 +1,255 @@
+import { IFilesystem, CommandExecutor } from '@livx.cc/wcli/core';
+
+/**
+ * Wire types mirroring ai.libx.js (OpenAI-style chat). We type the transport
+ * structurally via `ChatLike`, so an ai.libx.js `AIClient` is a drop-in — and a
+ * `FakeAIClient` works in tests — with no hard runtime dependency on ai.libx.js.
+ */
+type Role = 'system' | 'user' | 'assistant' | 'tool';
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** One part of a multimodal message (mirrors ai.libx.js ContentPart) — text or an image URL/data-URI. */
+interface ContentPart {
+    type: 'text' | 'image_url';
+    text?: string;
+    image_url?: {
+        url: string;
+    };
+}
+/** A message's content is either plain text or an array of multimodal parts (images + text). */
+type MessageContent = string | ContentPart[];
+interface Message {
+    role: Role;
+    content: MessageContent;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+/** Flatten any message content to its text (string as-is; parts → concatenated text) — for length
+ *  estimation, summaries, and display. Non-text parts (images) contribute a short placeholder. */
+declare function contentText(content: MessageContent | undefined): string;
+/** Build an image content part from a data-URI or http(s) URL. */
+declare function imagePart(url: string): ContentPart;
+interface Tool {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: object;
+    };
+}
+interface ChatResponse {
+    content: string;
+    finishReason?: string;
+    toolCalls?: ToolCall[];
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * One incremental event from a streamed `chat({stream:true})` call — mirrors
+ * ai.libx.js's `StreamChunk` (OpenAI-style): each chunk carries a `content`
+ * text delta; the terminal chunk carries `finishReason` and the accumulated
+ * `toolCalls`. Consuming the stream and folding the deltas reconstructs the
+ * same `ChatResponse` the non-stream path returns.
+ */
+interface StreamChunk {
+    content: string;
+    finishReason?: string;
+    index?: number;
+    toolCalls?: ToolCall[];
+    reasoningContent?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface ChatOptions {
+    model: string;
+    messages: Message[];
+    tools?: Tool[];
+    toolChoice?: unknown;
+    stream?: boolean;
+    /** Cancel the request/stream. Forwarded to providers that honor it; the Agent also stops consuming on abort. */
+    signal?: AbortSignal;
+    [k: string]: unknown;
+}
+/** Minimal shape of an ai.libx.js AIClient that the Agent drives. */
+interface ChatLike {
+    chat(options: ChatOptions): Promise<ChatResponse | AsyncIterable<StreamChunk>>;
+}
+
+/** A single planning item. `in_progress` should mark exactly the one task currently being worked on. */
+interface TodoItem {
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+/**
+ * `TodoWrite` tool — the agent's planning scratchpad for multi-step tasks.
+ * Use to lay out steps up front and keep them current (mark one `in_progress`,
+ * flip finished ones to `completed`). Each call REPLACES the whole list.
+ */
+declare const todoWriteTool: AgentTool;
+
+/**
+ * Sandbox background jobs — the in-process twin of `ShellJobRegistry` (src/tools.shell.ts), but for work
+ * that runs *inside* the sandbox rather than as an OS child process. Backs `bash({background:true})` and
+ * (later) background sub-agents.
+ *
+ * IMPORTANT — this is concurrency via async-I/O interleaving, NOT parallelism. The runtime is single
+ * threaded: a CPU-bound JS command still blocks. Real overlap only happens when a job *awaits* — i.e. a
+ * remote VFS backend (BodDbFilesystem, network per read) or a sub-agent (model calls). Over a pure in-mem
+ * MemFilesystem, backgrounding a fast command buys nothing (the tool description says so).
+ *
+ * The registry is kind-AGNOSTIC: it tracks any async producer's lifecycle + tail output. Overlay isolation
+ * and commit-on-success are the *producer's* responsibility (IoC), so the registry stays a pure tracker.
+ */
+type JobStatus = 'running' | 'done' | 'error' | 'killed';
+/** A producer: does the actual work, may stream progress via `onChunk`, returns its final text. */
+interface JobFn {
+    (ctx: {
+        signal: AbortSignal;
+        onChunk: (s: string) => void;
+    }): Promise<string>;
+}
+/** Per-session registry of in-process background jobs. Bounded tail buffer; abortable; drainable at turn end. */
+declare class SandboxJobRegistry {
+    private maxBuffer;
+    private jobs;
+    private seq;
+    constructor(maxBuffer?: number);
+    /** Start `fn` in the background and return a job id immediately (does not await completion). */
+    start(fn: JobFn, opts?: {
+        kind?: string;
+        label?: string;
+    }): string;
+    /** Tail output for a job (null = no such job, '' = job exists but no output yet). */
+    output(id: string): string | null;
+    status(id: string): {
+        status: JobStatus;
+        bytes: number;
+    } | null;
+    list(): Array<{
+        id: string;
+        kind: string;
+        label: string;
+        status: JobStatus;
+    }>;
+    /** Signal cancel (the producer decides what abort means — e.g. skip the overlay commit). */
+    kill(id: string): boolean;
+    killAll(): void;
+    /** Await every still-running job. Called at turn end so a job's committed writes aren't lost from view
+     *  just because the model didn't poll it. Returns the ids that were still running when drain began. */
+    drain(): Promise<string[]>;
+}
+/** Companion tools (JobOutput / JobStatus / JobKill) over a SandboxJobRegistry. */
+declare function makeJobTools(registry: SandboxJobRegistry): AgentTool[];
+
+/** A structured multiple-choice question the model can pose to a human. */
+interface UserQuestion {
+    question: string;
+    header?: string;
+    options: {
+        label: string;
+        description?: string;
+    }[];
+    multiSelect?: boolean;
+}
+/**
+ * The host / human-in-the-loop seam (the "third seam" beyond LLM + filesystem).
+ * Injected per host: a CLI reads stdin, a browser renders a dialog, edge/headless
+ * omits it. Unifies user-questions, permission/plan approvals, and notifications.
+ */
+type HostEvent = {
+    kind: 'text_delta';
+    message: string;
+} | {
+    kind: 'thinking_delta';
+    message: string;
+} | {
+    kind: 'tool_use';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: 'tool_result';
+    id: string;
+    output: string;
+    isError?: boolean;
+} | {
+    kind: 'tool_result_image';
+    id: string;
+    dataUrl: string;
+} | {
+    kind: string;
+    message: string;
+    data?: unknown;
+};
+interface HostBridge {
+    /** Ask the user a structured question; resolve to the chosen label(s) / free text. */
+    ask?(q: UserQuestion): Promise<string>;
+    /** Request approval for a sensitive action (permission 'ask' / plan approval). */
+    confirm?(prompt: string, meta?: {
+        tool: string;
+        input: unknown;
+    }): Promise<boolean>;
+    /** Emit a progress / notification event to the host UI (non-blocking). */
+    notify?(event: HostEvent): void;
+}
+interface ToolContext {
+    fs: IFilesystem;
+    exec: CommandExecutor;
+    /** path -> content snapshot at last Read/Edit; powers the read-before-edit staleness guard. */
+    readState: Map<string, string>;
+    /** optional host interaction channel; absent => autonomous/headless. */
+    host?: HostBridge;
+    /** optional run-cancellation signal (mirrors AgentOptions.signal); lets abort-aware tools
+     *  (e.g. the real shell) kill in-flight work when the run is cancelled. */
+    signal?: AbortSignal;
+    /** the agent's working todo list (TodoWrite planning aid); replaced wholesale per call. */
+    todos: TodoItem[];
+    /** optional syntax guardrail: if set, write-class tools refuse to persist a broken result. */
+    lint?: (path: string, content: string) => string | null;
+    /** optional model handle for tools that run their own LLM pass (e.g. Review, a self-critique).
+     *  Populated by the Agent from its own ai/model; absent => such tools degrade to a no-op. */
+    ai?: ChatLike;
+    model?: string;
+    /** optional sandbox background-job registry; enables `bash({background:true})`. Absent => no backgrounding. */
+    jobs?: SandboxJobRegistry;
+}
+interface AgentTool {
+    name: string;
+    description: string;
+    parameters: object;
+    run(args: any, ctx: ToolContext): Promise<string>;
+}
+/** Build a tool context bound to a filesystem backend (Mem / Disk / …) and an optional host. */
+declare function makeContext(fs: IFilesystem, host?: HostBridge): ToolContext;
+/** Convert AgentTools into the ai.libx.js `tools` array for chat(). */
+declare function toWireTools(tools: AgentTool[]): Tool[];
+/** Run any shell command line over the VFS (ls/cat/grep/find/head/tail/echo/mkdir/rm/mv/wc, pipes, redirects, &&/||/;). */
+declare const bashTool: AgentTool;
+/** Read a text file as 1-indexed numbered lines; arms the staleness guard for Edit. */
+declare const readTool: AgentTool;
+/** Replace an exact, unique substring; requires a prior Read and guards against stale edits. */
+declare const editTool: AgentTool;
+declare function defaultTools(): AgentTool[];
+/**
+ * The full catalog of selectable tools, keyed by name. The evolve loop's mutation
+ * surface picks from this registry; embedders can build a custom tool set by name.
+ */
+declare function toolRegistry(): Record<string, AgentTool>;
+/** Resolve a list of tool names against the registry (unknown names throw). */
+declare function toolsByName(names: string[]): AgentTool[];
+
+export { type AgentTool as A, type ChatLike as C, type HostBridge as H, type Message as M, type Role as R, SandboxJobRegistry as S, type TodoItem as T, type UserQuestion as U, type ChatOptions as a, type ChatResponse as b, type ContentPart as c, type HostEvent as d, type MessageContent as e, type StreamChunk as f, type Tool as g, type ToolCall as h, type ToolContext as i, bashTool as j, contentText as k, defaultTools as l, editTool as m, imagePart as n, makeContext as o, makeJobTools as p, todoWriteTool as q, readTool as r, toolRegistry as s, toWireTools as t, toolsByName as u };

package/dist/tools.shell.d.ts

@@ -0,0 +1,80 @@
+import { A as AgentTool } from './tools-Ch-OzOU8.js';
+import '@livx.cc/wcli/core';
+
+/** The slice of node's `child_process.spawn` we depend on — injectable so tests supply a fake. */
+type SpawnFn = (command: string, args: string[], options: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    signal?: AbortSignal;
+}) => SpawnedProcess;
+/** Minimal `ChildProcess` surface this tool uses. */
+interface SpawnedProcess {
+    stdout?: {
+        on(ev: 'data', cb: (chunk: any) => void): void;
+    } | null;
+    stderr?: {
+        on(ev: 'data', cb: (chunk: any) => void): void;
+    } | null;
+    on(ev: 'close', cb: (code: number | null) => void): void;
+    on(ev: 'error', cb: (err: Error) => void): void;
+    kill(signal?: string): void;
+}
+interface RealShellOptions {
+    /** Working directory the shell is bound to (typically a NodeDiskFilesystem `baseDir`). Required. */
+    cwd: string;
+    /** Override the spawner (tests inject a fake; default lazily imports node:child_process). */
+    spawn?: SpawnFn;
+    /** Per-command wall-clock cap (kill on overrun). Default 120s. */
+    timeoutMs?: number;
+    /** Extra env merged over the (optionally scrubbed) base env for the child. */
+    env?: Record<string, string>;
+    /** Strip likely-secret vars (API keys, tokens, cloud creds) from the child's env. Default ON.
+     *  The FS jail does NOT contain a real process, so this is the seam that keeps `echo $ANTHROPIC_API_KEY`
+     *  from leaking the host's secrets to a spawned command. `false` passes `process.env` through verbatim. */
+    redactEnv?: boolean;
+    /** Job registry enabling `Shell({background:true})` (long-running processes). Pair with `makeShellJobTools`. */
+    registry?: ShellJobRegistry;
+}
+type JobStatus = 'running' | 'exited' | 'killed' | 'error';
+interface ShellJobConfig {
+    cwd: string;
+    spawn?: SpawnFn;
+    env?: Record<string, string>;
+    redactEnv?: boolean;
+    /** Tail buffer cap per job (bytes); older output is dropped. Default 256 KB. */
+    maxBuffer?: number;
+    /** Kill all jobs on process exit (the CLI sets this; tests leave it off to avoid global handlers). */
+    killOnExit?: boolean;
+}
+/**
+ * Per-session registry of background `/bin/sh` jobs. Backs `Shell({background:true})` and the
+ * `ShellOutput`/`ShellStatus`/`ShellKill` tools. Output accumulates into a tail-capped ring so a
+ * chatty process can't OOM. Bounded + killable; the CLI wires `killOnExit` so children are reaped.
+ */
+declare class ShellJobRegistry {
+    private cfg;
+    private jobs;
+    private seq;
+    constructor(cfg: ShellJobConfig);
+    start(command: string): Promise<string>;
+    /** Current tail output for a job (null = no such job). */
+    output(id: string): string | null;
+    status(id: string): {
+        status: JobStatus;
+        exitCode?: number;
+        bytes: number;
+    } | null;
+    list(): Array<{
+        id: string;
+        command: string;
+        status: JobStatus;
+    }>;
+    kill(id: string): boolean;
+    killAll(): void;
+}
+/** Build an opt-in real-shell tool bound to `options.cwd`. */
+declare function makeRealShellTool(options: RealShellOptions): AgentTool;
+/** Build the background-job companion tools (ShellOutput / ShellStatus / ShellKill) over a registry. */
+declare function makeShellJobTools(registry: ShellJobRegistry): AgentTool[];
+
+export { type JobStatus, type RealShellOptions, type ShellJobConfig, ShellJobRegistry, type SpawnFn, type SpawnedProcess, makeRealShellTool, makeShellJobTools };