catui-agent 1.0.0-beta.0

package/dist/core/sub-agent/sub-agent-runtime.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var s=(a,t)=>n(a,"name",{value:t,configurable:!0});class r{static{s(this,"SubAgentRuntime")}backend;activeAgents=new Map;constructor(t){this.backend=t}async spawn(t){const e=await this.backend.spawn(t);return this.activeAgents.set(e.id,e),e.result().finally(()=>{this.activeAgents.delete(e.id)}),e}getActiveAgents(){return Array.from(this.activeAgents.values())}async abortAll(){await Promise.all(Array.from(this.activeAgents.values()).map(t=>t.abort()))}async terminateAll(){await Promise.all(Array.from(this.activeAgents.values()).map(t=>t.terminate()))}}export{r as SubAgentRuntime};

package/dist/core/sub-agent/sub-agent-types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * [WHO]: SubAgent types - SubAgentSpec, SubAgentEvent, SubAgentHandle, SubAgentBackend, SubAgentResult
+ * [FROM]: Depends on @catui/agent-core, @catui/ai, core/tools
+ * [TO]: Consumed by ./sub-agent-runtime, ./sub-agent-backend, ./index.ts, extensions/builtin/subagent/*, extensions/builtin/team/*
+ * [HERE]: core/sub-agent/sub-agent-types.ts - SubAgent type definitions
+ * [COVENANT]: Change these types → update P1 architecture diagram
+ */
+import type { ImageContent, Model } from "@catui/ai/types";
+import type { AgentUsage } from "./agent-input-output.js";
+import type { Tool } from "../tools/index.js";
+/** Realtime lifecycle event emitted by a running SubAgent. */
+export type SubAgentEvent = {
+    type: "agent_start";
+    subAgentId: string;
+    timestamp: number;
+    agentType: string;
+    description: string;
+    isAsync: boolean;
+} | {
+    type: "message_update";
+    subAgentId: string;
+    timestamp: number;
+    text: string;
+    deltaType?: string;
+} | {
+    type: "message_end";
+    subAgentId: string;
+    timestamp: number;
+    text: string;
+} | {
+    type: "tool_start";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool_update";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    partialResult: unknown;
+} | {
+    type: "tool_end";
+    subAgentId: string;
+    timestamp: number;
+    toolName: string;
+    isError: boolean;
+} | {
+    type: "agent_end";
+    subAgentId: string;
+    timestamp: number;
+    success: boolean;
+    error?: string;
+};
+/**
+ * Specification for spawning a SubAgent.
+ */
+export interface SubAgentSpec {
+    /** Task prompt for the SubAgent */
+    prompt: string;
+    /** Tools available to the SubAgent (determined by caller, not guessed by core) */
+    tools: Tool[];
+    /** Working directory for the SubAgent (can be a worktree) */
+    cwd: string;
+    /** Agent type label for TUI display (e.g. "Explore", "Plan", "general-purpose") */
+    agentType?: string;
+    /** Human-readable description of the task (e.g. "search codebase") */
+    description?: string;
+    /** Whether this agent was launched as a background/async agent */
+    isAsync?: boolean;
+    /** Abort signal for stopping the SubAgent (required) */
+    signal: AbortSignal;
+    /** Optional timeout in milliseconds */
+    timeoutMs?: number;
+    /** Images to include in the prompt */
+    images?: ImageContent[];
+    /** Model to use (reuses main session's model and auth) */
+    model?: Model<any>;
+    /** Files to inject into the initial prompt as read-only context */
+    contextFiles?: string[];
+    /** Optional callback invoked after the run result is available */
+    exitHook?: (result: SubAgentResult) => Promise<void> | void;
+    /** Optional realtime observer for TUI/status integrations */
+    onEvent?: (event: SubAgentEvent) => void;
+}
+/**
+ * Result from a completed SubAgent run.
+ */
+export interface SubAgentResult {
+    /** Whether the run was successful */
+    success: boolean;
+    /** The response text from the SubAgent */
+    response?: string;
+    /** Error message if unsuccessful */
+    error?: string;
+    /** Total tokens consumed by the SubAgent */
+    totalTokens?: number;
+    /** Total number of tool calls made */
+    totalToolUseCount?: number;
+    /** Token usage breakdown */
+    usage?: AgentUsage;
+}
+/**
+ * Handle to a running SubAgent.
+ */
+export interface SubAgentHandle {
+    /** Unique identifier for this SubAgent */
+    readonly id: string;
+    /** Current status of the SubAgent */
+    readonly status: "running" | "done" | "aborted" | "error";
+    /**
+     * Wait for the SubAgent to complete and get its result.
+     * Resolves when the SubAgent finishes (successfully or with error).
+     */
+    result(): Promise<SubAgentResult>;
+    /**
+     * Abort the current turn (stops after current LLM response).
+     * The SubAgent may still be in "running" state if it can accept more turns.
+     */
+    abort(): Promise<void>;
+    /**
+     * Terminate the SubAgent completely.
+     * This stops all work and disposes of resources.
+     */
+    terminate(): Promise<void>;
+}
+/**
+ * Backend for spawning SubAgents.
+ * Core provides in-process backend; subprocess backend can be added in phase B.
+ */
+export interface SubAgentBackend {
+    /**
+     * Spawn a new SubAgent with the given specification.
+     * @param spec The SubAgent specification
+     * @returns A handle to the spawned SubAgent
+     */
+    spawn(spec: SubAgentSpec): Promise<SubAgentHandle>;
+}

package/dist/core/sub-agent/subprocess-backend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * [WHO]: SubprocessSubAgentBackend
+ * [FROM]: Depends on node:worker_threads, ./sub-agent-types
+ * [TO]: Consumed by SubAgentRuntime when caller wants crash isolation
+ * [HERE]: core/sub-agent/subprocess-backend.ts - Phase B B.6 multi-backend
+ *
+ * Crash-isolated SubAgent backend built on top of node:worker_threads.
+ *
+ * The worker thread runs the in-process backend in its own V8 isolate, so
+ * an unhandled error inside a teammate cannot tear down the main session.
+ * The Tool[] surface in `SubAgentSpec` is NOT serializable across the
+ * worker boundary, so the caller must pre-stage tools by name and resolve
+ * them inside the worker via `toolFactoryName`. For v1 we accept the same
+ * profiles the team extension already uses ("read-only" / "sandboxed").
+ *
+ * Status: SHIPPED with the worker harness in place; the worker entry
+ * itself is intentionally minimal (echo + abort) so the interface is real
+ * and exercisable. The full agent loop inside the worker is deferred to a
+ * follow-up because it requires re-creating the model registry inside the
+ * isolate, which is out of scope for the AgentTeam Phase B milestone.
+ *
+ * The backend therefore documents itself honestly: callers that need real
+ * LLM execution should keep using `InProcessSubAgentBackend`; callers that
+ * just need an isolated bash/echo worker can use this one today.
+ */
+import type { SubAgentBackend, SubAgentHandle, SubAgentSpec } from "./sub-agent-types.js";
+export interface SubprocessBackendOptions {
+    /** Override the worker entry path (for tests). */
+    workerEntry?: string;
+}
+export declare class SubprocessSubAgentBackend implements SubAgentBackend {
+    private readonly workerEntry;
+    constructor(options?: SubprocessBackendOptions);
+    spawn(spec: SubAgentSpec): Promise<SubAgentHandle>;
+}

package/dist/core/sub-agent/subprocess-backend.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var n=(a,e)=>w(a,"name",{value:e,configurable:!0});import{Worker as f}from"node:worker_threads";import{fileURLToPath as y}from"node:url";import{dirname as k,join as b}from"node:path";const h=k(y(import.meta.url));class S{static{n(this,"SubprocessSubAgentBackend")}workerEntry;constructor(e={}){this.workerEntry=e.workerEntry??b(h,"subprocess-worker.js")}async spawn(e){const i=crypto.randomUUID(),m={id:i,prompt:e.prompt,cwd:e.cwd,timeoutMs:e.timeoutMs},t=new f(this.workerEntry,{workerData:m});let c="running",o;const d=new Promise(l=>{const s=n((r,p)=>{o||(o=r,c=p,l(r))},"finish");t.on("message",r=>{r.type==="result"?s(r.payload??{success:!0},"done"):r.type==="error"&&s({success:!1,error:String(r.payload?.error??"Worker error")},"error")}),t.on("error",r=>{s({success:!1,error:r.message},"error")}),t.on("exit",r=>{o||s({success:!1,error:r===0?"Worker exited without result":`Worker exited with code ${r}`},"error")});const u=n(()=>{o||(t.postMessage({type:"abort"}),s({success:!1,error:"Aborted"},"aborted"),t.terminate().catch(()=>{}))},"onAbort");e.signal.aborted?u():e.signal.addEventListener("abort",u,{once:!0})});return{id:i,get status(){return c},async result(){return d},async abort(){o||(t.postMessage({type:"abort"}),await t.terminate().catch(()=>{}))},async terminate(){await t.terminate().catch(()=>{})}}}}export{S as SubprocessSubAgentBackend};

package/dist/core/sub-agent/subprocess-worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: Worker entry for SubprocessSubAgentBackend
+ * [FROM]: Depends on node:worker_threads
+ * [TO]: Spawned by SubprocessSubAgentBackend
+ * [HERE]: core/sub-agent/subprocess-worker.ts
+ *
+ * Minimal isolated worker. Receives a `WorkerSpec` via workerData, runs
+ * a trivial echo loop, and posts a `result` message back. This is the
+ * harness that proves the channel + abort + lifecycle wiring; full agent
+ * execution inside the worker is intentionally deferred (see backend doc).
+ */
+export {};

package/dist/core/sub-agent/subprocess-worker.js

@@ -0,0 +1 @@
+var p=Object.defineProperty;var s=(e,a)=>p(e,"name",{value:a,configurable:!0});import{parentPort as r,workerData as n}from"node:worker_threads";const o=n;let t=!1;r?.on("message",e=>{e.type==="abort"&&(t=!0)});async function c(){if(await new Promise(e=>setTimeout(e,10)),t){r?.postMessage({type:"error",payload:{error:"Aborted"}});return}r?.postMessage({type:"result",payload:{success:!0,response:`[subprocess-worker:${o.id}] received prompt of ${o.prompt.length} chars in cwd ${o.cwd}`}})}s(c,"run"),c().catch(e=>{r?.postMessage({type:"error",payload:{error:e instanceof Error?e.message:String(e)}})});

package/dist/core/theme-contract.d.ts

@@ -0,0 +1,32 @@
+/**
+ * [WHO]: Provides Theme, ThemeColor, ThemeBg, ColorMode — the structural theme contract
+ * [FROM]: No dependencies — pure type vocabulary owned by core
+ * [TO]: Consumed by core/export-html, core/extensions-host (ToolDefinition render hooks),
+ *       core/runtime (export bridge); the concrete `class Theme` in modes/interactive/theme
+ *       implements it. Resolves U2 (core must not import the modes/ UI layer for a type).
+ * [HERE]: core/theme-contract.ts - theme type seam (U2); the modes Theme class is its implementation
+ *
+ * Pure type-only module: lets core reference a theme's rendering surface without depending on
+ * the modes/interactive theme subsystem (which imports host config + does fs theme discovery).
+ */
+export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "bashMode";
+export type ThemeBg = "selectedBg" | "userMessageBg" | "customMessageBg" | "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+export type ColorMode = "truecolor" | "256color";
+export type ThinkingBorderLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/** A theme's rendering surface — what core needs to colorize text and render tool output. */
+export interface Theme {
+    readonly name?: string;
+    readonly sourcePath?: string;
+    fg(color: ThemeColor, text: string): string;
+    bg(color: ThemeBg, text: string): string;
+    bold(text: string): string;
+    italic(text: string): string;
+    underline(text: string): string;
+    inverse(text: string): string;
+    strikethrough(text: string): string;
+    getFgAnsi(color: ThemeColor): string;
+    getBgAnsi(color: ThemeBg): string;
+    getColorMode(): ColorMode;
+    getThinkingBorderColor(level: ThinkingBorderLevel): (str: string) => string;
+    getBashModeBorderColor(): (str: string) => string;
+}

package/dist/core/tools/bash.d.ts

@@ -0,0 +1,73 @@
+import type { AgentTool } from "@catui/agent-core";
+import { type Static } from "@sinclair/typebox";
+import { type TruncationResult } from "./truncate.js";
+declare const bashSchema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    run_in_background: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type BashToolInput = Static<typeof bashSchema>;
+export interface BashToolDetails {
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (e.g., SSH).
+ */
+export interface BashOperations {
+    /**
+     * Execute a command and stream output.
+     * @param command - The command to execute
+     * @param cwd - Working directory
+     * @param options - Execution options
+     * @returns Promise resolving to exit code (null if killed)
+     */
+    exec: (command: string, cwd: string, options: {
+        onData: (data: Buffer) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+export interface BashSpawnContext {
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+export interface BashToolOptions {
+    /** Custom operations for command execution. Default: local shell */
+    operations?: BashOperations;
+    /** Command prefix prepended to every command (e.g., "shopt -s expand_aliases" for alias support) */
+    commandPrefix?: string;
+    /** Hook to adjust command, cwd, or env before execution */
+    spawnHook?: BashSpawnHook;
+}
+export declare function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema>;
+/** Default bash tool using process.cwd() - for backwards compatibility */
+export declare const bashTool: AgentTool<import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    run_in_background: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    task_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>, any>;
+export interface BashSandboxOptions {
+    /** Additional patterns to block (in addition to default blocked patterns) */
+    additionalBlockedPatterns?: RegExp[];
+    /** Custom error message for blocked commands */
+    blockedMessage?: string;
+    /** Optional path allowlist hook for simple write commands. Defaults to denying all writes. */
+    allowWritePath?: (absolutePath: string) => boolean;
+}
+/**
+ * Create a sandboxed bash hook that blocks dangerous write operations.
+ * This is a defense-in-depth measure for read-only SubAgents.
+ */
+export declare function createSandboxHook(options?: BashSandboxOptions): BashSpawnHook;
+export {};

package/dist/core/tools/bash.js

@@ -0,0 +1,21 @@
+var J=Object.defineProperty;var g=(r,i)=>J(r,"name",{value:i,configurable:!0});import{randomBytes as I}from"node:crypto";import{createWriteStream as N,existsSync as Q}from"node:fs";import{tmpdir as V}from"node:os";import{isAbsolute as Z,join as U,resolve as j}from"node:path";import{Type as x}from"@sinclair/typebox";import{spawn as tt}from"child_process";import{getShellConfig as et,getShellEnv as z,killProcessTree as H}from"../platform/utils/shell.js";import{validatePositiveNumberOption as nt}from"./input-validation.js";import{DEFAULT_MAX_BYTES as P,DEFAULT_MAX_LINES as ot,formatSize as _,truncateTail as A}from"./truncate.js";function R(){const r=I(8).toString("hex");return U(V(),`catui-bash-${r}.log`)}g(R,"getTempFilePath");const X=120,W=new Map,it=x.Object({command:x.Optional(x.String({description:"Bash command to execute"})),timeout:x.Optional(x.Number({exclusiveMinimum:0,description:"Timeout in seconds (default: 120)"})),description:x.Optional(x.String({description:"Clear, concise description of what this command does"})),run_in_background:x.Optional(x.Boolean({description:"Run command in background, return immediately with task ID (default: false)"})),task_id:x.Optional(x.String({description:"Task ID to check status/get output for a background command"}))}),rt={exec:g((r,i,{onData:n,signal:e,timeout:s,env:o})=>new Promise((t,l)=>{const{shell:C,args:L}=et();if(!Q(i)){l(new Error(`Working directory does not exist: ${i}
+Cannot execute bash commands.`));return}const c=tt(C,[...L,r],{cwd:i,detached:!0,env:o??z(),stdio:["ignore","pipe","pipe"]});let y=!1,k;s!==void 0&&s>0&&(k=setTimeout(()=>{y=!0,c.pid&&H(c.pid)},s*1e3)),c.stdout&&c.stdout.on("data",n),c.stderr&&c.stderr.on("data",n),c.on("error",E=>{k&&clearTimeout(k),e&&e.removeEventListener("abort",S),l(E)});const S=g(()=>{c.pid&&H(c.pid)},"onAbort");e&&(e.aborted?S():e.addEventListener("abort",S,{once:!0})),c.on("close",E=>{if(k&&clearTimeout(k),e&&e.removeEventListener("abort",S),e?.aborted){l(new Error("aborted"));return}if(y){l(new Error(`timeout:${s}`));return}t({exitCode:E})})}),"exec")};function q(r,i,n){const e={command:r,cwd:i,env:{...z()}};return n?n(e):e}g(q,"resolveSpawnContext");function st(r,i){const n=i?.operations??rt,e=i?.commandPrefix,s=i?.spawnHook;return{name:"bash",label:"bash",description:`Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last ${ot} lines or ${P/1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Default timeout: ${X}s. Supports run_in_background for long-running commands.`,parameters:it,execute:g(async(o,{command:t,timeout:l,description:C,run_in_background:L,task_id:c},y,k)=>{if(nt("timeout",l),c){const f=W.get(c);if(!f)throw new Error(`Background task not found: ${c}`);if(f.status==="running")return{content:[{type:"text",text:`Task ${c} is still running.`}],details:void 0};let b="";try{const{readFileSync:m}=await import("node:fs");b=m(f.outputPath,"utf-8")}catch{b="(output unavailable)"}const u=A(b);let d=u.content||"(no output)";f.exitCode!==0&&f.exitCode!==null&&(d+=`
+
+Command exited with code ${f.exitCode}`),W.delete(c);const w=u.truncated?{truncation:u}:void 0;if(f.exitCode!==0&&f.exitCode!==null)throw new Error(d);return{content:[{type:"text",text:d}],details:w}}if(!t)throw new Error("command is required (or provide task_id to check a background task)");const S=l??X;if(L){const f=I(4).toString("hex"),b=R(),u={id:f,outputPath:b,status:"running",exitCode:null,startTime:Date.now()};W.set(f,u);const d=e?`${e}
+${t}`:t,w=q(d,r,s),m=N(b);return n.exec(w.command,w.cwd,{onData:g($=>m.write($),"onData"),timeout:S,env:w.env}).then(({exitCode:$})=>{m.end(),u.status=$===0?"completed":"failed",u.exitCode=$,u.endTime=Date.now()}).catch(()=>{m.end(),u.status="failed",u.exitCode=-1,u.endTime=Date.now()}),{content:[{type:"text",text:`Background task started: ${f}
+Output will be written to: ${b}
+Use task_id="${f}" to check status and retrieve output.`}],details:void 0}}const E=e?`${e}
+${t}`:t,O=q(E,r,s);return new Promise((f,b)=>{let u,d,w=0;const m=[];let $=0;const K=P*2,Y=g(p=>{if(w+=p.length,w>P&&!u){u=R(),d=N(u);for(const T of m)d.write(T)}for(d&&d.write(p),m.push(p),$+=p.length;$>K&&m.length>1;){const T=m.shift();$-=T.length}if(k){const h=Buffer.concat(m).toString("utf-8"),a=A(h);k({content:[{type:"text",text:a.content||""}],details:{truncation:a.truncated?a:void 0,fullOutputPath:u}})}},"handleData");n.exec(O.command,O.cwd,{onData:Y,signal:y,timeout:S,env:O.env}).then(({exitCode:p})=>{d&&d.end();const h=Buffer.concat(m).toString("utf-8"),a=A(h);let B=a.content||"(no output)",F;if(a.truncated){F={truncation:a,fullOutputPath:u};const M=a.totalLines-a.outputLines+1,D=a.totalLines;if(a.lastLinePartial){const G=_(Buffer.byteLength(h.split(`
+`).pop()||"","utf-8"));B+=`
+
+[Showing last ${_(a.outputBytes)} of line ${D} (line is ${G}). Full output: ${u}]`}else a.truncatedBy==="lines"?B+=`
+
+[Showing lines ${M}-${D} of ${a.totalLines}. Full output: ${u}]`:B+=`
+
+[Showing lines ${M}-${D} of ${a.totalLines} (${_(P)} limit). Full output: ${u}]`}p!==0&&p!==null?(B+=`
+
+Command exited with code ${p}`,b(new Error(B))):f({content:[{type:"text",text:B}],details:F})}).catch(p=>{d&&d.end();let h=Buffer.concat(m).toString("utf-8");if(p.message==="aborted")h&&(h+=`
+
+`),h+="Command aborted",b(new Error(h));else if(p.message.startsWith("timeout:")){const a=p.message.split(":")[1];h&&(h+=`
+
+`),h+=`Command timed out after ${a} seconds`,b(new Error(h))}else b(p)})})},"execute")}}g(st,"createBashTool");const wt=st(process.cwd()),ut=[/^\s*>|\s>|\s>>|\s&\d>/,/\brm\s+/,/\bmv\s+/,/\bcp\s+.*\s+\//,/\bgit\s+(commit|push|pull|add|checkout\s+[^-|]|reset|rebase\s+[^--]|merge)/,/\bmkdir\s+[^-]/,/\bchmod\s+/,/\bchown\s+/,/\bln\s+.*-s/,/\btee\s+/,/\bwget\s+.*-O/,/\bcurl\s+.*-o/];function $t(r){const i=[...ut,...r?.additionalBlockedPatterns??[]],n=r?.blockedMessage??"Write operations are not allowed in sandbox mode";return e=>{const s=e.command.trim(),o=lt(s,e.cwd);if(o===null)return{...e,command:`echo "${n}" >&2; exit 1`};if(o.length>0)return o.every(l=>r?.allowWritePath?.(l)===!0)?e:{...e,command:`echo "${n}" >&2; exit 1`};for(const t of i)if(t.test(s))return{...e,command:`echo "${n}" >&2; exit 1`};return e}}g($t,"createSandboxHook");function lt(r,i){if(/[;&|`$()]/.test(r))return null;const n=at(r);if(n.length===0)return[];const e=[];for(let o=0;o<n.length;o++){const t=n[o];if(t===">"||t===">>"||/^&?\d?>&?\d?$/.test(t)){const C=n[o+1];if(!C)return null;e.push(v(C,i)),o++;continue}const l=/^(?:\d?>|>>)(.+)$/.exec(t);if(l?.[1]){e.push(v(l[1],i));continue}}const s=n[0];if(s==="mkdir"){const o=n.slice(1).filter(t=>!t.startsWith("-"));if(o.length===0)return null;e.push(...o.map(t=>v(t,i)))}else if(s==="cp"||s==="mv"){const o=n.slice(1).filter(t=>!t.startsWith("-"));if(o.length<2)return null;e.push(v(o[o.length-1],i))}else if(s==="rm"){const o=n.slice(1).filter(t=>!t.startsWith("-"));if(o.length===0)return null;e.push(...o.map(t=>v(t,i)))}else if(s==="tee"){const o=n.slice(1).filter(t=>!t.startsWith("-"));if(o.length===0)return null;e.push(...o.map(t=>v(t,i)))}else if(s==="touch"){const o=n.slice(1).filter(t=>!t.startsWith("-"));if(o.length===0)return null;e.push(...o.map(t=>v(t,i)))}return e}g(lt,"extractSimpleWritePaths");function at(r){const i=[];let n="",e,s=!1;for(let o=0;o<r.length;o++){const t=r[o];if(s){n+=t,s=!1;continue}if(t==="\\"){const l=r[o+1];!e&&l&&(/\s/.test(l)||l==='"'||l==="'"||l==="\\")?s=!0:n+=t;continue}if(e){t===e?e=void 0:n+=t;continue}if(t==="'"||t==='"'){e=t;continue}if(/\s/.test(t)){n&&(i.push(n),n="");continue}n+=t}return n&&i.push(n),i}g(at,"tokenizeSimpleShell");function v(r,i){return j(Z(r)?r:U(i,r))}g(v,"resolveSandboxPath");export{wt as bashTool,st as createBashTool,$t as createSandboxHook};

package/dist/core/tools/edit-diff.d.ts

@@ -0,0 +1,58 @@
+export declare function detectLineEnding(content: string): "\r\n" | "\n";
+export declare function normalizeToLF(text: string): string;
+export declare function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string;
+/**
+ * Normalize text for fuzzy matching. Applies progressive transformations:
+ * - Strip trailing whitespace from each line
+ * - Normalize smart quotes to ASCII equivalents
+ * - Normalize Unicode dashes/hyphens to ASCII hyphen
+ * - Normalize special Unicode spaces to regular space
+ */
+export declare function normalizeForFuzzyMatch(text: string): string;
+export interface FuzzyMatchResult {
+    /** Whether a match was found */
+    found: boolean;
+    /** The index where the match starts (in the content that should be used for replacement) */
+    index: number;
+    /** Length of the matched text */
+    matchLength: number;
+    /** Whether fuzzy matching was used (false = exact match) */
+    usedFuzzyMatch: boolean;
+    /**
+     * The content to use for replacement operations.
+     * When exact match: original content. When fuzzy match: normalized content.
+     */
+    contentForReplacement: string;
+}
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+export declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
+/** Strip UTF-8 BOM if present, return both the BOM (if any) and the text without it */
+export declare function stripBom(content: string): {
+    bom: string;
+    text: string;
+};
+/**
+ * Generate a unified diff string with line numbers and context.
+ * Returns both the diff string and the first changed line number (in the new file).
+ */
+export declare function generateDiffString(oldContent: string, newContent: string, contextLines?: number): {
+    diff: string;
+    firstChangedLine: number | undefined;
+};
+export interface EditDiffResult {
+    diff: string;
+    firstChangedLine: number | undefined;
+}
+export interface EditDiffError {
+    error: string;
+}
+/**
+ * Compute the diff for an edit operation without applying it.
+ * Used for preview rendering in the TUI before the tool executes.
+ */
+export declare function computeEditDiff(path: string, oldText: string, newText: string, cwd: string): Promise<EditDiffResult | EditDiffError>;

package/dist/core/tools/edit-diff.js

@@ -0,0 +1,16 @@
+var C=Object.defineProperty;var d=(e,t)=>C(e,"name",{value:t,configurable:!0});import*as E from"diff";import{constants as N}from"fs";import{access as T,readFile as b}from"fs/promises";import{resolveToCwd as O}from"./path-utils.js";function P(e){const t=e.indexOf(`\r
+`),r=e.indexOf(`
+`);return r===-1||t===-1?`
+`:t<r?`\r
+`:`
+`}d(P,"detectLineEnding");function $(e){return e.replace(/\r\n/g,`
+`).replace(/\r/g,`
+`)}d($,"normalizeToLF");function W(e,t){return t===`\r
+`?e.replace(/\n/g,`\r
+`):e}d(W,"restoreLineEndings");function y(e){return e.split(`
+`).map(t=>t.trimEnd()).join(`
+`).replace(/[\u2018\u2019\u201A\u201B]/g,"'").replace(/[\u201C\u201D\u201E\u201F]/g,'"').replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g,"-").replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g," ")}d(y,"normalizeForFuzzyMatch");function M(e,t){const r=e.indexOf(t);if(r!==-1)return{found:!0,index:r,matchLength:t.length,usedFuzzyMatch:!1,contentForReplacement:e};const u=y(e),o=y(t),s=u.indexOf(o);return s===-1?{found:!1,index:-1,matchLength:0,usedFuzzyMatch:!1,contentForReplacement:e}:{found:!0,index:s,matchLength:o.length,usedFuzzyMatch:!0,contentForReplacement:u}}d(M,"fuzzyFindText");function R(e){return e.startsWith("\uFEFF")?{bom:"\uFEFF",text:e.slice(1)}:{bom:"",text:e}}d(R,"stripBom");function v(e,t,r=4){const u=E.diffLines(e,t),o=[],s=e.split(`
+`),S=t.split(`
+`),z=Math.max(s.length,S.length),m=String(z).length;let a=1,n=1,p=!1,h;for(let l=0;l<u.length;l++){const f=u[l],i=f.value.split(`
+`);if(i[i.length-1]===""&&i.pop(),f.added||f.removed){h===void 0&&(h=n);for(const g of i)if(f.added){const c=String(n).padStart(m," ");o.push(`+${c} ${g}`),n++}else{const c=String(a).padStart(m," ");o.push(`-${c} ${g}`),a++}p=!0}else{const g=l<u.length-1&&(u[l+1].added||u[l+1].removed);if(p||g){let c=i,x=0,F=0;p||(x=Math.max(0,i.length-r),c=i.slice(x)),!g&&c.length>r&&(F=c.length-r,c=c.slice(0,r)),x>0&&(o.push(` ${"".padStart(m," ")} ...`),a+=x,n+=x);for(const w of c){const L=String(a).padStart(m," ");o.push(` ${L} ${w}`),a++,n++}F>0&&(o.push(` ${"".padStart(m," ")} ...`),a+=F,n+=F)}else a+=i.length,n+=i.length;p=!1}}return{diff:o.join(`
+`),firstChangedLine:h}}d(v,"generateDiffString");async function j(e,t,r,u){const o=O(e,u);try{try{await T(o,N.R_OK)}catch{return{error:`File not found: ${e}`}}const s=await b(o,"utf-8"),{text:S}=R(s),z=$(S),m=$(t),a=$(r),n=M(z,m);if(!n.found)return{error:`Could not find the exact text in ${e}. The old text must match exactly including all whitespace and newlines.`};const p=y(z),h=y(m),l=p.split(h).length-1;if(l>1)return{error:`Found ${l} occurrences of the text in ${e}. The text must be unique. Please provide more context to make it unique.`};const f=n.contentForReplacement,i=f.substring(0,n.index)+a+f.substring(n.index+n.matchLength);return f===i?{error:`No changes would be made to ${e}. The replacement produces identical content.`}:v(f,i)}catch(s){return{error:s instanceof Error?s.message:String(s)}}}d(j,"computeEditDiff");export{j as computeEditDiff,P as detectLineEnding,M as fuzzyFindText,v as generateDiffString,y as normalizeForFuzzyMatch,$ as normalizeToLF,W as restoreLineEndings,R as stripBom};

package/dist/core/tools/edit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * [WHO]: EditTool, editTool, createEditTool, EditToolInput, EditOperations
+ * [FROM]: Depends on agent-core, node:fs, edit-diff.ts, path-utils.ts
+ * [TO]: Consumed by core/tools/index.ts
+ * [HERE]: core/tools/edit.ts - filesystem mutation via diff application; consumed by orchestrator
+ */
+import type { AgentTool } from "@catui/agent-core";
+import { type Static } from "@sinclair/typebox";
+declare const editSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    oldText: import("@sinclair/typebox").TString;
+    newText: import("@sinclair/typebox").TString;
+}>;
+export type EditToolInput = Static<typeof editSchema>;
+export interface EditToolDetails {
+    /** Unified diff of the changes made */
+    diff: string;
+    /** Line number of the first change in the new file (for editor navigation) */
+    firstChangedLine?: number;
+}
+/**
+ * Pluggable operations for the edit tool.
+ * Override these to delegate file editing to remote systems (e.g., SSH).
+ */
+export interface EditOperations {
+    /** Read file contents as a Buffer */
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Check if file is readable and writable (throw if not) */
+    access: (absolutePath: string) => Promise<void>;
+}
+export interface EditToolOptions {
+    /** Custom operations for file editing. Default: local filesystem */
+    operations?: EditOperations;
+    /** Optional guard called with the resolved absolute path before writing. */
+    beforeWrite?: (absolutePath: string) => void | Promise<void>;
+}
+export declare function createEditTool(cwd: string, options?: EditToolOptions): AgentTool<typeof editSchema>;
+/** Default edit tool using process.cwd() - for backwards compatibility */
+export declare const editTool: AgentTool<import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    oldText: import("@sinclair/typebox").TString;
+    newText: import("@sinclair/typebox").TString;
+}>, any>;
+export {};

package/dist/core/tools/edit.js

@@ -0,0 +1 @@
+var A=Object.defineProperty;var a=(t,s)=>A(t,"name",{value:s,configurable:!0});import{Type as u}from"@sinclair/typebox";import{constants as C}from"fs";import{access as I,readFile as K,stat as L,writeFile as k}from"fs/promises";import{fileStateCache as m}from"./file-state-cache.js";import{detectLineEnding as B,fuzzyFindText as D,generateDiffString as G,normalizeForFuzzyMatch as z,normalizeToLF as b,restoreLineEndings as H,stripBom as J}from"./edit-diff.js";import{resolveToCwd as S}from"./path-utils.js";const Q=u.Object({path:u.String({description:"Path to the file to edit (relative or absolute)"}),oldText:u.String({description:"Exact text to find and replace (must match exactly)"}),newText:u.String({description:"New text to replace the old text with"})}),V={readFile:a(t=>K(t),"readFile"),writeFile:a((t,s)=>k(t,s,"utf-8"),"writeFile"),access:a(t=>I(t,C.R_OK|C.W_OK),"access")};function X(t,s){const h=s?.operations??V;return{name:"edit",label:"edit",description:"Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits.",parameters:Q,validateInput:a(({path:x})=>{const r=S(x,t);if(!m.has(r))return`Cannot edit ${x}: file has not been read yet. Use the read tool first.`},"validateInput"),execute:a(async(x,{path:r,oldText:g,newText:O},e)=>{const n=S(r,t);return await s?.beforeWrite?.(n),new Promise(($,o)=>{if(e?.aborted){o(new Error("Operation aborted"));return}let c=!1;const i=a(()=>{c=!0,o(new Error("Operation aborted"))},"onAbort");e&&e.addEventListener("abort",i,{once:!0}),(async()=>{try{try{await h.access(n)}catch{e&&e.removeEventListener("abort",i),o(new Error(`File not found: ${r}`));return}const f=m.get(n);if(f){const q=await L(n);if(Math.floor(q.mtimeMs)>f.timestamp){m.delete(n),e&&e.removeEventListener("abort",i),o(new Error(`Cannot edit ${r}: file has been modified since it was last read. Use the read tool to re-read the file before editing.`));return}}if(c)return;const M=(await h.readFile(n)).toString("utf-8");if(c)return;const{bom:P,text:w}=J(M),R=B(w),E=b(w),v=b(g),W=b(O),d=D(E,v);if(!d.found){e&&e.removeEventListener("abort",i),o(new Error(`Could not find the exact text in ${r}. The old text must match exactly including all whitespace and newlines.`));return}const N=z(E),U=z(v),T=N.split(U).length-1;if(T>1){e&&e.removeEventListener("abort",i),o(new Error(`Found ${T} occurrences of the text in ${r}. The text must be unique. Please provide more context to make it unique.`));return}if(c)return;const l=d.contentForReplacement,p=l.substring(0,d.index)+W+l.substring(d.index+d.matchLength);if(l===p){e&&e.removeEventListener("abort",i),o(new Error(`No changes made to ${r}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`));return}const y=P+H(p,R);await h.writeFile(n,y);const _=await L(n);if(m.set(n,{content:y,timestamp:Math.floor(_.mtimeMs),offset:void 0,limit:void 0}),c)return;e&&e.removeEventListener("abort",i);const F=G(l,p);$({content:[{type:"text",text:`Successfully replaced text in ${r}.`}],details:{diff:F.diff,firstChangedLine:F.firstChangedLine}})}catch(f){e&&e.removeEventListener("abort",i),c||o(f)}})()})},"execute")}}a(X,"createEditTool");const ie=X(process.cwd());export{X as createEditTool,ie as editTool};

package/dist/core/tools/file-state-cache.d.ts

@@ -0,0 +1,30 @@
+export interface FileState {
+    /** File content at read time */
+    content: string;
+    /** mtimeMs from fs.stat(), floored to integer */
+    timestamp: number;
+    /** offset parameter used during read (1-indexed) */
+    offset: number | undefined;
+    /** limit parameter used during read */
+    limit: number | undefined;
+}
+/**
+ * LRU file state cache with no external dependencies.
+ * Uses Map insertion order (iterators return entries in insertion order)
+ * to implement LRU eviction — on every access the entry is deleted and
+ * re-inserted so it moves to the "newest" position.
+ */
+declare class FileStateCache {
+    private cache;
+    private totalBytes;
+    private normalizeKey;
+    get(key: string): FileState | undefined;
+    set(key: string, value: FileState): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+/** Singleton file state cache instance */
+export declare const fileStateCache: FileStateCache;
+export {};

package/dist/core/tools/file-state-cache.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var a=(h,e)=>r(h,"name",{value:e,configurable:!0});import{normalize as l,resolve as y}from"node:path";const f=100,u=25*1024*1024;class d{static{a(this,"FileStateCache")}cache=new Map;totalBytes=0;normalizeKey(e){return l(y(e))}get(e){const s=this.normalizeKey(e),t=this.cache.get(s);if(t)return this.cache.delete(s),this.cache.set(s,t),t}set(e,s){const t=this.normalizeKey(e),n=Buffer.byteLength(s.content),i=this.cache.get(t);for(i&&(this.totalBytes-=Buffer.byteLength(i.content),this.cache.delete(t));this.cache.size>=f||this.totalBytes+n>u;){const c=this.cache.keys().next().value;if(c===void 0)break;const o=this.cache.get(c);this.totalBytes-=Buffer.byteLength(o.content),this.cache.delete(c)}this.cache.set(t,s),this.totalBytes+=n}has(e){return this.cache.has(this.normalizeKey(e))}delete(e){const s=this.normalizeKey(e),t=this.cache.get(s);return t?(this.totalBytes-=Buffer.byteLength(t.content),this.cache.delete(s)):!1}clear(){this.cache.clear(),this.totalBytes=0}get size(){return this.cache.size}}const z=new d;export{z as fileStateCache};

package/dist/core/tools/find.d.ts

@@ -0,0 +1,46 @@
+/**
+ * [WHO]: FindTool, findTool, createFindTool, FindToolInput
+ * [FROM]: Depends on agent-core, node:child_process, node:fs, glob
+ * [TO]: Consumed by core/tools/index.ts
+ * [HERE]: core/tools/find.ts - file pattern matching via glob; consumed by orchestrator
+ */
+import type { AgentTool } from "@catui/agent-core";
+import { type Static } from "@sinclair/typebox";
+import { type TruncationResult } from "./truncate.js";
+declare const findSchema: import("@sinclair/typebox").TObject<{
+    pattern: import("@sinclair/typebox").TString;
+    path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type FindToolInput = Static<typeof findSchema>;
+export interface FindToolDetails {
+    truncation?: TruncationResult;
+    resultLimitReached?: number;
+}
+/**
+ * Pluggable operations for the find tool.
+ * Override these to delegate file search to remote systems (e.g., SSH).
+ */
+export interface FindOperations {
+    /** Check if path exists */
+    exists: (absolutePath: string) => Promise<boolean> | boolean;
+    /** Find files matching glob pattern. Returns relative paths. */
+    glob: (pattern: string, cwd: string, options: {
+        ignore: string[];
+        limit: number;
+    }) => Promise<string[]> | string[];
+}
+export interface FindToolOptions {
+    /** Custom operations for find. Default: local filesystem + fd */
+    operations?: FindOperations;
+}
+export declare function createFindTool(cwd: string, options?: FindToolOptions): AgentTool<typeof findSchema>;
+/** Default find tool using process.cwd() - for backwards compatibility */
+export declare const findTool: AgentTool<import("@sinclair/typebox").TObject<{
+    pattern: import("@sinclair/typebox").TString;
+    path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>, any>;
+export {};

package/dist/core/tools/find.js

@@ -0,0 +1,8 @@
+var k=Object.defineProperty;var d=(u,l)=>k(u,"name",{value:l,configurable:!0});import{Type as i}from"@sinclair/typebox";import{spawnSync as H}from"child_process";import{existsSync as W}from"fs";import{globSync as K}from"glob";import $ from"path";import{ensureTool as Y}from"../platform/utils/tools-manager.js";import{validateIntegerWindowOption as q}from"./input-validation.js";import{resolveToCwd as J}from"./path-utils.js";import{DEFAULT_MAX_BYTES as T,formatSize as G,truncateHead as C}from"./truncate.js";const Q=i.Object({pattern:i.String({description:"Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'"}),path:i.Optional(i.String({description:"Directory to search in (default: current directory)"})),limit:i.Optional(i.Integer({minimum:1,description:"Maximum number of results (default: 1000)"})),sort:i.Optional(i.String({description:"Sort results by: 'modified' (most recent first)"}))}),j=1e3,V={exists:W,glob:d((u,l,x)=>[],"glob")};function Z(u,l){const x=l?.operations;return{name:"find",label:"find",description:`Search for files by glob pattern. Returns matching file paths relative to the search directory. Respects .gitignore. Output is truncated to ${j} results or ${T/1024}KB (whichever is hit first).`,parameters:Q,isConcurrencySafe:!0,execute:d(async(tt,{pattern:A,path:z,limit:F,sort:B},c)=>(q({name:"limit",value:F,minimum:1}),new Promise((f,o)=>{if(c?.aborted){o(new Error("Operation aborted"));return}const m=d(()=>o(new Error("Operation aborted")),"onAbort");c?.addEventListener("abort",m,{once:!0}),(async()=>{try{const t=J(z||".",u),r=F??j,R=x??V;if(x?.glob){if(!await R.exists(t)){o(new Error(`Path not found: ${t}`));return}const n=await R.glob(A,t,{ignore:["**/node_modules/**","**/.git/**"],limit:r});if(c?.removeEventListener("abort",m),n.length===0){f({content:[{type:"text",text:"No files found matching pattern"}],details:void 0});return}const e=n.map(_=>_.startsWith(t)?_.slice(t.length+1):$.relative(t,_)),O=e.length>=r,s=e.join(`
+`),L=C(s,{maxLines:Number.MAX_SAFE_INTEGER});let P=L.content;const b={},w=[];O&&(w.push(`${r} results limit reached`),b.resultLimitReached=r),L.truncated&&(w.push(`${G(T)} limit reached`),b.truncation=L),w.length>0&&(P+=`
+
+[${w.join(". ")}]`),f({content:[{type:"text",text:P}],details:Object.keys(b).length>0?b:void 0});return}const I=await Y("fd",!0);if(!I){o(new Error("fd is not available and could not be downloaded"));return}const p=["--glob","--color=never","--hidden","--max-results",String(r)];B==="modified"&&p.push("--sort","modified");const y=new Set,M=$.join(t,".gitignore");W(M)&&y.add(M);try{const n=K("**/.gitignore",{cwd:t,dot:!0,absolute:!0,ignore:["**/node_modules/**","**/.git/**"]});for(const e of n)y.add(e)}catch{}for(const n of y)p.push("--ignore-file",n);p.push(A,t);const a=H(I,p,{encoding:"utf-8",maxBuffer:10*1024*1024});if(c?.removeEventListener("abort",m),a.error){o(new Error(`Failed to run fd: ${a.error.message}`));return}const E=a.stdout?.trim()||"";if(a.status!==0){const n=a.stderr?.trim()||`fd exited with code ${a.status}`;if(!E){o(new Error(n));return}}if(!E){f({content:[{type:"text",text:"No files found matching pattern"}],details:void 0});return}const D=E.split(`
+`),v=[];for(const n of D){const e=n.replace(/\r$/,"").trim();if(!e)continue;const O=e.endsWith("/")||e.endsWith("\\");let s=e;e.startsWith(t)?s=e.slice(t.length+1):s=$.relative(t,e),O&&!s.endsWith("/")&&(s+="/"),v.push(s)}const U=v.length>=r,X=v.join(`
+`),S=C(X,{maxLines:Number.MAX_SAFE_INTEGER});let N=S.content;const h={},g=[];U&&(g.push(`${r} results limit reached. Use limit=${r*2} for more, or refine pattern`),h.resultLimitReached=r),S.truncated&&(g.push(`${G(T)} limit reached`),h.truncation=S),g.length>0&&(N+=`
+
+[${g.join(". ")}]`),f({content:[{type:"text",text:N}],details:Object.keys(h).length>0?h:void 0})}catch(t){c?.removeEventListener("abort",m),o(t)}})()})),"execute")}}d(Z,"createFindTool");const lt=Z(process.cwd());export{Z as createFindTool,lt as findTool};