catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/security-audit/interface.d.ts

@@ -0,0 +1,167 @@
+/**
+ * [WHO]: SecurityCheckResult, AuditEvent, LogQueryOptions, SecurityStats, SecurityEngine
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by extension entry point (./index.ts)
+ * [HERE]: extensions/builtin/security-audit/interface.ts -
+ */
+/**
+ * Security check result levels
+ */
+export type SecurityLevel = "safe" | "warning" | "dangerous";
+/**
+ * Security check result
+ */
+export interface SecurityCheckResult {
+    /** Whether the operation is allowed */
+    allowed: boolean;
+    /** Security level of the operation */
+    level: SecurityLevel;
+    /** Reason for the result */
+    reason?: string;
+    /** Whether user confirmation is required */
+    requiresConfirm?: boolean;
+    /** Matched pattern if any */
+    pattern?: string;
+}
+/**
+ * Audit event types
+ */
+export type AuditEventType = "command" | "file_read" | "file_write" | "file_edit" | "network" | "extension" | "session_start" | "session_end";
+/**
+ * Audit event status
+ */
+export type AuditEventStatus = "allowed" | "blocked" | "warning" | "confirmed";
+/**
+ * Audit event record
+ */
+export interface AuditEvent {
+    /** Unique event ID */
+    id: string;
+    /** Event timestamp */
+    timestamp: string;
+    /** Event type */
+    type: AuditEventType;
+    /** Operation performed */
+    operation: string;
+    /** Target path or command */
+    target: string;
+    /** Working directory */
+    cwd: string;
+    /** Security level */
+    level: SecurityLevel;
+    /** Event status */
+    status: AuditEventStatus;
+    /** Reason if blocked/warning */
+    reason?: string;
+    /** Pattern matched */
+    pattern?: string;
+    /** Whether user confirmed */
+    userConfirmed?: boolean;
+    /** Duration in milliseconds */
+    duration?: number;
+}
+/**
+ * Query options for retrieving audit logs
+ */
+export interface LogQueryOptions {
+    /** Start date */
+    startDate?: Date;
+    /** End date */
+    endDate?: Date;
+    /** Event types to include */
+    types?: AuditEventType[];
+    /** Security levels to include */
+    levels?: SecurityLevel[];
+    /** Maximum results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Security statistics
+ */
+export interface SecurityStats {
+    /** Total events in period */
+    totalEvents: number;
+    /** Events by type */
+    byType: Record<AuditEventType, number>;
+    /** Events by level */
+    byLevel: Record<SecurityLevel, number>;
+    /** Events by status */
+    byStatus: Record<AuditEventStatus, number>;
+    /** Most common dangerous patterns */
+    dangerousPatterns: Array<{
+        pattern: string;
+        count: number;
+    }>;
+    /** Period start */
+    periodStart: string;
+    /** Period end */
+    periodEnd: string;
+}
+/**
+ * Standardized security engine interface
+ * This interface can be implemented by different security levels:
+ * - Light Audit: Just logging
+ * - Med Secure: Detection + warning
+ * - Heavy Guard: Full interception
+ */
+export interface SecurityEngine {
+    /**
+     * Check if a command is safe to execute
+     */
+    checkCommand(command: string, cwd: string): SecurityCheckResult;
+    /**
+     * Check if a file operation is allowed
+     */
+    checkFileOperation(operation: "read" | "write" | "edit", path: string): SecurityCheckResult;
+    /**
+     * Record an audit event
+     */
+    log(event: Omit<AuditEvent, "id" | "timestamp">): AuditEvent;
+    /**
+     * Query audit logs
+     */
+    queryLogs(options?: LogQueryOptions): AuditEvent[];
+    /**
+     * Get security statistics
+     */
+    getStats(options?: LogQueryOptions): SecurityStats;
+    /**
+     * Clear audit logs
+     */
+    clearLogs(): void;
+    /**
+     * Export logs to JSON
+     */
+    exportLogs(format?: "json" | "html"): string;
+}
+/**
+ * Security configuration
+ */
+export interface SecurityConfig {
+    /** Whether security audit is enabled */
+    enabled: boolean;
+    /** Security mode */
+    mode: "audit" | "confirm" | "strict";
+    /** Enable logging */
+    enableLogging: boolean;
+    /** Enable danger detection */
+    enableDetection: boolean;
+    /** Enable interception (requires user confirm) */
+    enableInterception: boolean;
+    /** Enable whitelist */
+    enableWhitelist: boolean;
+    /** Dangerous command patterns */
+    dangerousPatterns: string[];
+    /** Sensitive file paths */
+    sensitivePaths: string[];
+    /** Whitelisted commands */
+    whitelist: string[];
+    /** Maximum log entries to keep */
+    maxLogEntries: number;
+}
+/**
+ * Default security configuration
+ */
+export declare const DEFAULT_SECURITY_CONFIG: SecurityConfig;

package/dist/extensions/builtin/security-audit/interface.js

@@ -0,0 +1 @@
+const s={enabled:!0,mode:"audit",enableLogging:!0,enableDetection:!0,enableInterception:!1,enableWhitelist:!1,dangerousPatterns:["rm\\s+-rf","rmdir\\s+/s","del\\s+/s","rmdir\\s+/s","sudo\\s+","chmod\\s+777","chown\\s+","kill\\s+-9","pkill\\s+-9","killall\\s+","curl\\s+.*\\|\\s*sh","wget\\s+.*\\|\\s*sh","Invoke-Expression.*WebRequest","git\\s+push\\s+--force","git\\s+push\\s+-f","docker\\s+rm\\s+-f","docker\\s+run\\s+--rm","systemctl\\s+stop","systemctl\\s+restart"],sensitivePaths:["~/.ssh/","/.ssh/","~/.aws/","~/.azure/","~/.gcloud/",".env",".env.local",".env.production","/etc/passwd","/etc/shadow","/etc/sudoers",".git/config"],whitelist:["git status","git diff","git log","git branch","npm install","npm run","pnpm install","pnpm run","yarn","ls","cat","grep"],maxLogEntries:1e4};export{s as DEFAULT_SECURITY_CONFIG};

package/dist/extensions/builtin/soul/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Soul extension entrypoint
+ * [FROM]: Depends on core/extensions-host/types.js
+ * [TO]: Consumed by builtin-extensions.ts as default extension
+ * [HERE]: extensions/builtin/soul/index.ts - keeps the built-in Soul entrypoint while delegating prompt injection and evolution to AgentSession
+ *
+ * Features:
+ * - Preserves the built-in Soul extension slot
+ * - Avoids creating duplicate SoulManager instances in the extension layer
+ * - Leaves stable prompt injection and interaction recording to core/runtime/agent-session.ts
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function soulExtension(_pi: ExtensionAPI): Promise<void>;

package/dist/extensions/builtin/soul/index.js

@@ -0,0 +1 @@
+var e=Object.defineProperty;var o=(n,t)=>e(n,"name",{value:t,configurable:!0});async function i(n){}o(i,"soulExtension");export{i as default};

package/dist/extensions/builtin/subagent/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: SubAgent extension, registers /subagent commands and message renderer
+ * [FROM]: Depends on @catui/tui, core/extensions-host/types, ./subagent-runner, ./subagent-parser, ./subagent-types
+ * [TO]: Consumed by builtin-extensions.ts as default extension
+ * [HERE]: extensions/builtin/subagent/index.ts - entry point for subagent extension
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function subagentExtension(api: ExtensionAPI): Promise<void>;

package/dist/extensions/builtin/subagent/index.js

@@ -0,0 +1,8 @@
+var g=Object.defineProperty;var c=(t,d)=>g(t,"name",{value:d,configurable:!0});import{Box as b,Container as m,Spacer as w,Text as k}from"@catui/tui";import{SubAgentRunner as y}from"./subagent-runner.js";import{buildSubAgentHelp as S,parseSubAgentCommand as f}from"./subagent-parser.js";const i="subagent",P=[{value:"run",label:"run",description:"Start a background helper task"},{value:"stop",label:"stop",description:"Stop the current helper task"},{value:"status",label:"status",description:"Show current helper task status"},{value:"report",label:"report",description:"Show the latest helper report"},{value:"apply",label:"apply",description:"Copy isolated changes into this workspace"},{value:"help",label:"help",description:"Show helper commands"}],A=[{value:"--write",label:"--write",description:"Allow changes in an isolated workspace"}];let h=null,n=null;function v(){return h||(h=new y),h}c(v,"getRunner");async function T(t){t.registerMessageRenderer(i,(r,l,o)=>{const a=typeof r.content=="string"?r.content:r.content.filter(e=>e.type==="text").map(e=>e.text).join(`
+`),u=new b(1,1,e=>o.bg("customMessageBg",e));u.addChild(new k(o.fg("customMessageText",a),0,0));const s=new m;return s.addChild(new w(1)),s.addChild(u),s});const d=["subagent","subagent:run","subagent:stop","subagent:status","subagent:report","subagent:apply"];for(const r of d)t.registerCommand(r,{description:M(r),getArgumentCompletions:c((l,o)=>$(r,l,o),"getArgumentCompletions"),handler:c(async(l,o)=>{const a=f(r,l);if(!a){o.ui.notify("Invalid /subagent command. Use /subagent for usage.","error");return}const u=v();switch(a.command){case"help":{t.sendMessage({customType:i,content:S(),display:!0});break}case"run":{if(!a.task){o.ui.notify("Usage: /subagent:run <task> [--write]","error");return}const s=o.model;t.sendMessage({customType:i,content:`Starting SubAgent run (${a.options?.write?"isolated write workspace":"read-only"})...
+
+Task: ${a.task}${s?`
+Model: ${s.id??s.name??"unknown"}`:""}`,display:!0});try{const e=await u.run(a.task,{runRole:a.options?.write?"implement":"research",model:s,cwd:o.cwd});n=e;const p=[e.success?`SubAgent run completed in ${Math.round(e.duration/1e3)}s.`:"SubAgent run failed.","",e.summary||"(no summary)"];e.workspacePath&&p.push("",`Workspace: ${e.workspacePath}`),e.patchPath&&p.push(`Patch: ${e.patchPath}`),e.reportPath&&p.push(`Report: ${e.reportPath}`),e.patchPreview&&p.push("","Patch Preview:",e.patchPreview),e.workspacePath&&!e.appliedAt&&p.push("Confirm write-back with /subagent:apply"),t.sendMessage({customType:i,content:p.join(`
+`),display:!0,details:e})}catch(e){const p=e instanceof Error?e.message:String(e);o.ui.notify(`Error: ${p}`,"error")}break}case"stop":{await u.stop(),t.sendMessage({customType:i,content:"Stopping SubAgent run...",display:!0});break}case"status":{t.sendMessage({customType:i,content:u.getStatusText(),display:!0});break}case"report":{if(!n){t.sendMessage({customType:i,content:"No SubAgent report available.",display:!0});break}const s=["Last SubAgent Report:","",`Run ID: ${n.runId}`,`Duration: ${Math.round(n.duration/1e3)}s`,`Success: ${n.success?"Yes":"No"}`,...n.workspacePath?[`Workspace: ${n.workspacePath}`]:[],...n.patchPath?[`Patch: ${n.patchPath}`]:[],...n.reportPath?[`Report: ${n.reportPath}`]:[],...n.appliedAt?[`Applied: ${new Date(n.appliedAt).toISOString()}`]:[],"","Summary:",n.summary||"(no summary)",...n.patchPreview?["","Patch Preview:",n.patchPreview]:[]];t.sendMessage({customType:i,content:s.join(`
+`),display:!0,details:n});break}case"apply":{const s=await u.applyLatest();n=s;const e=["Applied isolated SubAgent changes to the main workspace.","",...s.changedFiles.length>0?s.changedFiles.map(p=>`- ${p}`):["- (no changed files)"],...s.reportPath?["",`Report: ${s.reportPath}`]:[]];t.sendMessage({customType:i,content:e.join(`
+`),display:!0,details:s});break}}},"handler")})}c(T,"subagentExtension");function $(t,d,r){if(t==="subagent:run"&&r&&r.tokenIndex>0)return null;const l=d.trim().toLowerCase(),a=(t==="subagent"?P:t==="subagent:run"?A:[]).filter(u=>u.value.startsWith(l));return a.length>0?a.map(u=>({...u})):null}c($,"getArgumentCompletions");function M(t){switch(t){case"subagent:run":return"Start a background helper task (/subagent:run <task> [--write])";case"subagent:stop":return"Stop the active background helper task";case"subagent:status":return"Show current background helper status";case"subagent:report":return"Show the latest background helper report";case"subagent:apply":return"Apply the latest isolated write run to the main workspace";default:return"Run or inspect a background helper task"}}c(M,"getCommandDescription");export{T as default};

package/dist/extensions/builtin/subagent/subagent-parser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * [WHO]: parseSubAgentCommand, buildSubAgentHelp, SubAgentSubcommand, ParsedSubAgentCommand
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by ./index.ts
+ * [HERE]: extensions/builtin/subagent/subagent-parser.ts - command parser for /subagent
+ */
+export type SubAgentSubcommand = "run" | "stop" | "status" | "report" | "apply" | "help";
+export interface ParsedSubAgentCommand {
+    command: SubAgentSubcommand;
+    task?: string;
+    options?: {
+        write?: boolean;
+    };
+}
+/**
+ * Parse a registered /subagent command invocation.
+ * Primary syntax follows the phase-A plan:
+ *   /subagent
+ *   /subagent:run <task> [--write]
+ *   /subagent:stop
+ *   /subagent:status
+ *   /subagent:report
+ *
+ * The root command still accepts legacy space-style args for compatibility.
+ */
+export declare function parseSubAgentCommand(commandName: string, args?: string): ParsedSubAgentCommand | null;
+/**
+ * Build help text for /subagent commands.
+ */
+export declare function buildSubAgentHelp(): string;

package/dist/extensions/builtin/subagent/subagent-parser.js

@@ -0,0 +1,15 @@
+var a=Object.defineProperty;var n=(r,e)=>a(r,"name",{value:e,configurable:!0});function o(r,e=""){const t=e.trim();switch(r){case"subagent":return!t||t==="help"?{command:"help"}:t==="stop"?{command:"stop"}:t==="status"?{command:"status"}:t==="report"?{command:"report"}:t==="apply"?{command:"apply"}:t.startsWith("run ")?u(t.slice(4)):null;case"subagent:run":return u(t);case"subagent:stop":return{command:"stop"};case"subagent:status":return{command:"status"};case"subagent:report":return{command:"report"};case"subagent:apply":return{command:"apply"};default:return null}}n(o,"parseSubAgentCommand");function u(r){let e=r.trim();if(!e)return null;const t={};return e.includes("--write")&&(t.write=!0,e=e.replace(/--write/g,"").trim()),e?{command:"run",task:e,options:t}:null}n(u,"parseRunArgs");function p(){return`
+SubAgent Commands:
+  /subagent                  - Show this help
+  /subagent:run <task>       - Start a SubAgent run (read-only)
+  /subagent:run <task> --write - Start with isolated write access
+  /subagent:stop             - Stop current run
+  /subagent:status           - Show current run status
+  /subagent:report           - Show last run report
+  /subagent:apply            - Apply the last isolated write run to the main workspace
+
+Examples:
+  /subagent:run Analyze the codebase structure
+  /subagent:run Implement login feature --write
+  /subagent:apply
+`.trim()}n(p,"buildSubAgentHelp");export{p as buildSubAgentHelp,o as parseSubAgentCommand};

package/dist/extensions/builtin/subagent/subagent-runner.d.ts

@@ -0,0 +1,49 @@
+/**
+ * [WHO]: SubAgentRunner class - spawns and manages SubAgents
+ * [FROM]: Depends on node:fs/promises, node:path, core/sub-agent, core/workspace, core/tools, ./subagent-types
+ * [TO]: Consumed by ./index.ts
+ * [HERE]: extensions/builtin/subagent/subagent-runner.ts - SubAgent orchestration logic
+ */
+import type { Model } from "@catui/ai/types";
+import type { SubAgentRunReport, SubAgentRunState } from "./subagent-types.js";
+/**
+ * SubAgent Runner - handles spawning and managing SubAgents.
+ */
+export declare class SubAgentRunner {
+    private runtime;
+    private worktreeManager;
+    private currentState;
+    private abortController;
+    private activeWorkspace;
+    private currentBaseCwd;
+    constructor();
+    /**
+     * Start a new SubAgent run.
+     * @param task The task description
+     * @param options.runRole Worker role: "research" (read-only) or "implement" (can write)
+     * @param options.model Model to use (reuses main session's model and auth)
+     */
+    run(task: string, options?: {
+        runRole?: "research" | "implement";
+        model?: Model<any>;
+        cwd?: string;
+        timeoutMs?: number;
+    }): Promise<SubAgentRunReport>;
+    applyLatest(): Promise<SubAgentRunReport>;
+    /**
+     * Stop the current run.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the current run state.
+     */
+    getState(): SubAgentRunState | null;
+    /**
+     * Get status text for display.
+     */
+    getStatusText(): string;
+    private createReadOnlyTools;
+    private createSandboxedTools;
+    private writeReport;
+    private readPatchPreview;
+}

package/dist/extensions/builtin/subagent/subagent-runner.js

@@ -0,0 +1,8 @@
+var y=Object.defineProperty;var k=(w,e)=>y(w,"name",{value:e,configurable:!0});import{mkdir as P,readFile as v,writeFile as A}from"node:fs/promises";import{join as p}from"node:path";import{SubAgentRuntime as C,InProcessSubAgentBackend as W}from"../../../core/sub-agent/index.js";import{createAgentSession as $}from"../../../core/runtime/sdk.js";import{WorktreeManager as T}from"../../../core/workspace/index.js";import{createBashTool as S,createCodingTools as M,createReadOnlyTools as R,createSandboxHook as f}from"../../../core/tools/index.js";class j{static{k(this,"SubAgentRunner")}runtime;worktreeManager;currentState=null;abortController=null;activeWorkspace=null;currentBaseCwd=null;constructor(){this.runtime=new C(new W($)),this.worktreeManager=new T}async run(e,t){if(this.currentState&&(this.currentState.phase==="planning"||this.currentState.phase==="research"||this.currentState.phase==="implementing"||this.currentState.phase==="reviewing"))throw new Error("A SubAgent run is already active. Stop it before starting a new one.");const r=crypto.randomUUID();this.abortController=new AbortController;const s=t?.cwd??process.cwd();this.currentBaseCwd=s;const o=t?.runRole??"research";this.currentState={runId:r,phase:"planning",startTime:Date.now(),workers:[]};try{let a=null;o==="implement"&&(a=await this.worktreeManager.createGitWorktree(void 0,s),this.activeWorkspace=a);const i=a?.path??s,b=o==="research"?this.createReadOnlyTools(i):this.createSandboxedTools(i);this.currentState.phase=o==="research"?"research":"implementing";const d=`${o}-worker-1`;this.currentState.workers.push({id:d,role:o==="research"?"Research Worker":"Implementation Worker",status:"running"});const m=await this.runtime.spawn({prompt:e,tools:b,cwd:i,signal:this.abortController.signal,model:t?.model,timeoutMs:t?.timeoutMs}),u=this.currentState.workers.find(h=>h.id===d);u&&(u.handle=m);const n=await m.result();u.status=n.success?"done":n.error==="Aborted"?"aborted":"error";let l=n.error??"No result";n.success&&n.response?l=n.response:n.success&&(l="Task completed successfully");const g=a?await this.worktreeManager.listChangedFiles(a):[],c={runId:r,summary:l,findings:[],changedFiles:g,duration:Date.now()-this.currentState.startTime,success:n.success,workspacePath:a?.path};if(a&&g.length>0){const h=p(s,".catui","subagent-runs",`${r}.patch`);await this.worktreeManager.writePatch(a,h)&&(c.patchPath=h,c.patchPreview=await this.readPatchPreview(h))}return c.reportPath=await this.writeReport(s,c),this.currentState.report=c,this.currentState.phase="done",this.currentState.error=n.error,c}catch(a){this.currentState.phase="error",this.currentState.error=a instanceof Error?a.message:String(a);const i={runId:r,summary:this.currentState.error,findings:[],changedFiles:[],duration:Date.now()-this.currentState.startTime,success:!1};return i.reportPath=await this.writeReport(s,i),this.currentState.report=i,i}finally{const a=!!this.currentState?.report?.workspacePath&&this.currentState.report.success;this.activeWorkspace&&!a&&await this.worktreeManager.dispose(this.activeWorkspace),a||(this.activeWorkspace=null,this.currentBaseCwd=null)}}async applyLatest(){const e=this.currentState?.report;if(!e||!this.activeWorkspace||!this.currentBaseCwd)throw new Error("No isolated SubAgent run is waiting to be applied.");if(!e.success)throw new Error("The last SubAgent run did not complete successfully.");if(e.appliedAt)throw new Error("The last SubAgent run has already been applied.");const t=await this.worktreeManager.applyChanges(this.activeWorkspace,this.currentBaseCwd);return e.changedFiles=t.map(r=>r.path),e.appliedAt=Date.now(),e.summary=`${e.summary}
+
+Applied ${t.length} file change(s) to the main workspace.`,e.reportPath=await this.writeReport(this.currentBaseCwd,e),await this.worktreeManager.dispose(this.activeWorkspace),this.activeWorkspace=null,this.currentBaseCwd=null,e}async stop(){this.abortController&&this.abortController.abort(),await this.runtime.terminateAll(),this.activeWorkspace&&(await this.worktreeManager.dispose(this.activeWorkspace),this.activeWorkspace=null),this.currentBaseCwd=null,this.currentState&&(this.currentState.phase="error",this.currentState.error="Stopped by user",this.currentState.workers.forEach(e=>{e.status="aborted"}))}getState(){return this.currentState}getStatusText(){const e=this.currentState;if(!e)return"No active SubAgent run.";const t=[`Run ID: ${e.runId}`,`Phase: ${e.phase}`,`Duration: ${Math.round((Date.now()-e.startTime)/1e3)}s`,"","Workers:"];for(const r of e.workers)t.push(`  - ${r.role}: ${r.status}`);return e.error&&t.push("",`Error: ${e.error}`),e.report?.workspacePath&&!e.report.appliedAt&&(t.push("","Pending write-back: run /subagent:apply to copy changes into the main workspace."),e.report.patchPreview&&t.push("","Patch Preview:",e.report.patchPreview)),t.join(`
+`)}createReadOnlyTools(e){const t=R(e),r=S(e,{spawnHook:f()});return[...t.filter(s=>s.name!=="bash"),r]}createSandboxedTools(e){const t=M(e),r=S(e,{spawnHook:f()});return[...t.filter(s=>s.name!=="bash"),r]}async writeReport(e,t){const r=p(e,".catui","subagent-runs");await P(r,{recursive:!0});const s=p(r,`${t.runId}.md`),o=[`# SubAgent Run ${t.runId}`,"",`- Success: ${t.success?"Yes":"No"}`,`- Duration: ${Math.round(t.duration/1e3)}s`,`- Workspace: ${t.workspacePath??"(main workspace / read-only)"}`,`- Patch: ${t.patchPath??"(none)"}`,`- Applied: ${t.appliedAt?new Date(t.appliedAt).toISOString():"No"}`,"","## Summary","",t.summary||"(no summary)","","## Changed Files","",...t.changedFiles.length>0?t.changedFiles.map(a=>`- ${a}`):["- (none)"],...t.patchPreview?["","## Patch Preview","","```diff",t.patchPreview,"```"]:[],...t.workspacePath&&!t.appliedAt?["","## Next Step","","Review the patch and run `/subagent:apply` to write these changes back."]:[]];return await A(s,`${o.join(`
+`)}
+`,"utf-8"),s}async readPatchPreview(e){try{return(await v(e,"utf-8")).split(`
+`).slice(0,80).join(`
+`).trim()||void 0}catch{return}}}export{j as SubAgentRunner};

package/dist/extensions/builtin/subagent/subagent-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * [WHO]: SubAgent types - SubAgentPhase, SubAgentWorkerStatus, SubAgentRunState, SubAgentRunReport
+ * [FROM]: Depends on core/sub-agent for SubAgentHandle
+ * [TO]: Consumed by ./index.ts, ./subagent-runner.ts, ./subagent-parser.ts
+ * [HERE]: extensions/builtin/subagent/subagent-types.ts - type definitions for SubAgent extension
+ */
+import type { SubAgentHandle } from "../../../core/sub-agent/index.js";
+/**
+ * SubAgent run phases.
+ */
+export type SubAgentPhase = "idle" | "planning" | "research" | "implementing" | "reviewing" | "done" | "error";
+/**
+ * SubAgent worker status.
+ */
+export type SubAgentWorkerStatus = "pending" | "running" | "done" | "error" | "aborted";
+/**
+ * SubAgent worker info.
+ */
+export interface SubAgentWorkerInfo {
+    id: string;
+    role: string;
+    status: SubAgentWorkerStatus;
+    handle?: SubAgentHandle;
+}
+/**
+ * SubAgent run state.
+ */
+export interface SubAgentRunState {
+    /** Unique run ID */
+    runId: string;
+    /** Current phase */
+    phase: SubAgentPhase;
+    /** Start time */
+    startTime: number;
+    /** Workers and their statuses */
+    workers: SubAgentWorkerInfo[];
+    /** Final report if completed */
+    report?: SubAgentRunReport;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * SubAgent run report.
+ */
+export interface SubAgentRunReport {
+    runId: string;
+    summary: string;
+    findings: string[];
+    changedFiles: string[];
+    duration: number;
+    success: boolean;
+    reportPath?: string;
+    workspacePath?: string;
+    patchPath?: string;
+    patchPreview?: string;
+    appliedAt?: number;
+}

package/dist/extensions/builtin/task/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: taskExtension - registers TaskCreate, TaskGet, TaskUpdate, TaskList, TaskStop, TaskOutput, ToolSearch
+ * [FROM]: Depends on core/extensions-host/types, ./task-store, ./task-tools
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/builtin/task/index.ts - task management and tool discovery extension
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function taskExtension(api: ExtensionAPI): Promise<void>;

package/dist/extensions/builtin/task/index.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var r=(o,e)=>t(o,"name",{value:e,configurable:!0});import{createTaskCreateTool as T}from"./task-tools/task-create-tool.js";import{createTaskGetTool as l}from"./task-tools/task-get-tool.js";import{createTaskUpdateTool as s}from"./task-tools/task-update-tool.js";import{createTaskListTool as m}from"./task-tools/task-list-tool.js";import{createTaskStopTool as a}from"./task-tools/task-stop-tool.js";import{createTaskOutputTool as c}from"./task-tools/task-output-tool.js";import{createToolSearchTool as i}from"./task-tools/tool-search-tool.js";async function f(o){o.registerTool(T()),o.registerTool(l()),o.registerTool(s()),o.registerTool(m()),o.registerTool(a()),o.registerTool(c()),o.registerTool(i(()=>o.getAllTools()))}r(f,"taskExtension");export{f as default};

package/dist/extensions/builtin/task/task-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * [WHO]: Task store - CRUD operations with disk persistence
+ * [FROM]: Inspired by Claude Code utils/tasks.ts
+ * [TO]: Consumed by all task tools
+ * [HERE]: extensions/builtin/task/task-store.ts - task state management with atomic file writes
+ */
+import type { Task } from "./task-types.js";
+type TaskUpdateListener = () => void;
+/** Subscribe to task update notifications. Returns unsubscribe function. */
+export declare function onTasksUpdated(listener: TaskUpdateListener): () => void;
+export declare function getTasksDir(agentDir: string, taskListId?: string): string;
+/**
+ * Create a new task. Returns the created task with assigned ID.
+ */
+export declare function createTask(agentDir: string, taskListId: string, taskData: Omit<Task, "id">): Promise<Task>;
+/**
+ * Get a task by ID. Returns null if not found.
+ */
+export declare function getTask(agentDir: string, taskListId: string, taskId: string): Promise<Task | null>;
+/**
+ * Update a task. Merges partial updates into existing task.
+ * Returns the updated task, or null if not found.
+ */
+export declare function updateTask(agentDir: string, taskListId: string, taskId: string, updates: Partial<Omit<Task, "id">>): Promise<Task | null>;
+/**
+ * Delete a task. Updates high water mark to prevent ID reuse.
+ * Also cleans up blocks/blockedBy references from other tasks.
+ */
+export declare function deleteTask(agentDir: string, taskListId: string, taskId: string): Promise<boolean>;
+/**
+ * List all tasks in a task list.
+ */
+export declare function listTasks(agentDir: string, taskListId: string): Promise<Task[]>;
+/**
+ * Add a block relationship: fromTask blocks toTask.
+ */
+export declare function blockTask(agentDir: string, taskListId: string, fromTaskId: string, toTaskId: string): Promise<boolean>;
+/**
+ * Reset a task list - clears all tasks but preserves high water mark.
+ */
+export declare function resetTaskList(agentDir: string, taskListId: string): Promise<void>;
+export {};

package/dist/extensions/builtin/task/task-store.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var i=(t,n)=>g(t,"name",{value:n,configurable:!0});import{mkdir as F,readdir as p,readFile as b,rename as S,unlink as x,writeFile as B}from"node:fs/promises";import{join as u}from"node:path";import{sanitizePathComponent as W,DEFAULT_TASK_LIST_ID as P}from"./task-types.js";const y=new Set;function l(){for(const t of y)try{t()}catch{}}i(l,"notifyTasksUpdated");function R(t){return y.add(t),()=>{y.delete(t)}}i(R,"onTasksUpdated");const _=".highwatermark";function s(t,n=P){return u(t,"tasks",W(n))}i(s,"getTasksDir");function f(t,n,e){return u(s(t,n),`${W(e)}.json`)}i(f,"getTaskPath");function j(t,n){return u(s(t,n),_)}i(j,"getHighWaterMarkPath");async function H(t,n){const e=`${t}.tmp`;await B(e,JSON.stringify(n,null,2),"utf-8"),await S(e,t)}i(H,"atomicWriteJson");async function m(t,n){try{const e=await b(j(t,n),"utf-8"),r=parseInt(e.trim(),10);return isNaN(r)?0:r}catch{return 0}}i(m,"readHighWaterMark");async function M(t,n,e){await B(j(t,n),String(e),"utf-8")}i(M,"writeHighWaterMark");async function A(t,n){const e=s(t,n);return await F(e,{recursive:!0}),e}i(A,"ensureTasksDir");async function N(t,n){const e=s(t,n);let r;try{r=await p(e)}catch{return 0}let c=0;for(const a of r){if(!a.endsWith(".json"))continue;const o=parseInt(a.replace(".json",""),10);!isNaN(o)&&o>c&&(c=o)}return c}i(N,"findHighestTaskIdFromFiles");async function U(t,n){const[e,r]=await Promise.all([N(t,n),m(t,n)]);return Math.max(e,r)}i(U,"findHighestTaskId");async function $(t,n,e){await A(t,n);const r=await U(t,n),c=String(r+1),a={id:c,...e},o=f(t,n,c);return await H(o,a),l(),a}i($,"createTask");async function h(t,n,e){const r=f(t,n,e);try{const c=await b(r,"utf-8"),a=JSON.parse(c);return!a.id||!a.subject||!a.status?null:a}catch{return null}}i(h,"getTask");async function k(t,n,e,r){const c=await h(t,n,e);if(!c)return null;const a={...c,...r,id:e},o=f(t,n,e);return await H(o,a),l(),a}i(k,"updateTask");async function z(t,n,e){const r=f(t,n,e);try{const c=parseInt(e,10);if(!isNaN(c)){const o=await m(t,n);c>o&&await M(t,n,c)}await x(r),l();const a=await E(t,n);for(const o of a){const d=o.blocks.filter(w=>w!==e),T=o.blockedBy.filter(w=>w!==e);(d.length!==o.blocks.length||T.length!==o.blockedBy.length)&&await k(t,n,o.id,{blocks:d,blockedBy:T})}return!0}catch{return!1}}i(z,"deleteTask");async function E(t,n){const e=s(t,n);let r;try{r=await p(e)}catch{return[]}const c=r.filter(o=>o.endsWith(".json")).map(o=>o.replace(".json",""));return(await Promise.all(c.map(o=>h(t,n,o)))).filter(o=>o!==null)}i(E,"listTasks");async function C(t,n,e,r){const[c,a]=await Promise.all([h(t,n,e),h(t,n,r)]);return!c||!a?!1:(c.blocks.includes(r)||await k(t,n,e,{blocks:[...c.blocks,r]}),a.blockedBy.includes(e)||await k(t,n,r,{blockedBy:[...a.blockedBy,e]}),!0)}i(C,"blockTask");async function G(t,n){const e=s(t,n),r=await N(t,n);if(r>0){const a=await m(t,n);r>a&&await M(t,n,r)}let c;try{c=await p(e)}catch{return}for(const a of c)a.endsWith(".json")&&!a.startsWith(".")&&await x(u(e,a)).catch(()=>{});l()}i(G,"resetTaskList");export{C as blockTask,$ as createTask,z as deleteTask,h as getTask,s as getTasksDir,E as listTasks,R as onTasksUpdated,G as resetTaskList,k as updateTask};

package/dist/extensions/builtin/task/task-tools/task-create-tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * [WHO]: TaskCreate tool - creates a new task in the task list
+ * [FROM]: Depends on @sinclair/typebox, ../task-store, ../task-types
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/task-create-tool.ts
+ */
+import type { Static } from "@sinclair/typebox";
+import type { AgentToolResult } from "@catui/agent-core";
+import type { ExtensionContext } from "../../../../core/extensions-host/types.js";
+import { type Component } from "@catui/tui";
+import type { Theme } from "../../../../core/theme-contract.js";
+declare const taskCreateSchema: import("@sinclair/typebox").TObject<{
+    subject: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TString;
+    activeForm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+}>;
+export type TaskCreateInput = Static<typeof taskCreateSchema>;
+export declare function createTaskCreateTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        subject: import("@sinclair/typebox").TString;
+        description: import("@sinclair/typebox").TString;
+        activeForm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+    }>;
+    renderCall: (args: unknown, theme: Theme) => Component;
+    renderResult: (result: AgentToolResult<unknown>, _opts: {
+        expanded: boolean;
+        isPartial: boolean;
+    }, theme: Theme) => Component;
+    guidance: string;
+    execute(_toolCallId: string, params: TaskCreateInput, _signal: AbortSignal | undefined, _onUpdate: undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};

package/dist/extensions/builtin/task/task-tools/task-create-tool.js

@@ -0,0 +1,40 @@
+var u=Object.defineProperty;var c=(r,t)=>u(r,"name",{value:t,configurable:!0});import{Type as n}from"@sinclair/typebox";import{Container as l,Text as d}from"@catui/tui";import{createTask as p}from"../task-store.js";import{DEFAULT_TASK_LIST_ID as h}from"../task-types.js";const k=n.Object({subject:n.String({description:"A brief title for the task"}),description:n.String({description:"What needs to be done"}),activeForm:n.Optional(n.String({description:'Present continuous form shown in spinner when in_progress (e.g., "Running tests")'})),metadata:n.Optional(n.Record(n.String(),n.Unknown(),{description:"Arbitrary metadata to attach to the task"}))});function w(){return{name:"TaskCreate",label:"Create Task",description:"Create a new task in the task list.",parameters:k,renderCall:c((r,t)=>{const e=r,i=new l;if(i.addChild(new d(t.fg("toolTitle",t.bold("TaskCreate")),0,0)),i.addChild(new d(t.fg("muted","  Subject: ")+t.fg("text",e.subject??""),0,0)),e.description){const o=e.description.length>200?e.description.slice(0,200)+"...":e.description;i.addChild(new d(t.fg("muted","  ")+t.fg("toolOutput",o),0,0))}return i},"renderCall"),renderResult:c((r,t,e)=>{const i=new l,o=r.details;if(o?.error)i.addChild(new d(e.fg("error","  "+o.error),0,0));else if(o?.task)i.addChild(new d(e.fg("success",`  Task #${o.task.id} created`)+e.fg("muted"," \u2014 ")+e.fg("text",o.task.subject),0,0));else{const s=r.content?.filter(a=>a.type==="text").map(a=>a.type==="text"?a.text:"").join(`
+`);s&&i.addChild(new d(e.fg("toolOutput",s),0,0))}return i},"renderResult"),guidance:`Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+- Plan mode - When using plan mode, create a task list to track the work
+- User explicitly requests todo list - When the user directly asks you to use the todo list
+- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+- After receiving new instructions - Immediately capture user requirements as tasks
+- When you start working on a task - Mark it as in_progress BEFORE beginning work
+- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+- There is only a single, straightforward task
+- The task is trivial and tracking it provides no organizational benefit
+- The task can be completed in less than 3 trivial steps
+- The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task Fields
+
+- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+- **description**: What needs to be done
+- **activeForm** (optional): Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.
+
+All tasks are created with status \`pending\`.
+
+## Tips
+
+- Create tasks with clear, specific subjects that describe the outcome
+- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
+- Check TaskList first to avoid creating duplicate tasks`,async execute(r,t,e,i,o){try{const s=await p(o.agentDir,h,{subject:t.subject,description:t.description,activeForm:t.activeForm,status:"pending",owner:void 0,blocks:[],blockedBy:[],metadata:t.metadata});return{content:[{type:"text",text:`Task #${s.id} created successfully: ${s.subject}`}],details:{task:{id:s.id,subject:s.subject}}}}catch(s){const a=s instanceof Error?s.message:String(s);return{content:[{type:"text",text:`Error: Failed to create task: ${a}`}],details:{error:a}}}}}}c(w,"createTaskCreateTool");export{w as createTaskCreateTool};

package/dist/extensions/builtin/task/task-tools/task-get-tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * [WHO]: TaskGet tool - retrieves a task by ID
+ * [FROM]: Depends on @sinclair/typebox, ../task-store, ../task-types
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/task-get-tool.ts
+ */
+import type { Static } from "@sinclair/typebox";
+import type { AgentToolResult } from "@catui/agent-core";
+import type { ExtensionContext } from "../../../../core/extensions-host/types.js";
+import { type Component } from "@catui/tui";
+import type { Theme } from "../../../../core/theme-contract.js";
+declare const taskGetSchema: import("@sinclair/typebox").TObject<{
+    taskId: import("@sinclair/typebox").TString;
+}>;
+export type TaskGetInput = Static<typeof taskGetSchema>;
+export declare function createTaskGetTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        taskId: import("@sinclair/typebox").TString;
+    }>;
+    renderCall: (args: unknown, theme: Theme) => Component;
+    renderResult: (result: AgentToolResult<unknown>, _opts: {
+        expanded: boolean;
+        isPartial: boolean;
+    }, theme: Theme) => Component;
+    guidance: string;
+    execute(_toolCallId: string, params: TaskGetInput, _signal: AbortSignal | undefined, _onUpdate: undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};

package/dist/extensions/builtin/task/task-tools/task-get-tool.js

@@ -0,0 +1,23 @@
+var u=Object.defineProperty;var l=(r,i)=>u(r,"name",{value:i,configurable:!0});import{Type as c}from"@sinclair/typebox";import{Container as k,Text as n}from"@catui/tui";import{getTask as f}from"../task-store.js";import{DEFAULT_TASK_LIST_ID as p}from"../task-types.js";const g=c.Object({taskId:c.String({description:"The ID of the task to retrieve"})});function w(){return{name:"TaskGet",label:"Get Task",description:"Retrieve a task by its ID, showing full details including blocks/blockedBy.",parameters:g,renderCall:l((r,i)=>{const s=r,o=new k;return o.addChild(new n(i.fg("toolTitle",i.bold("TaskGet")),0,0)),o.addChild(new n(i.fg("muted","  Task #")+i.fg("text",s.taskId??"?"),0,0)),o},"renderCall"),renderResult:l((r,i,s)=>{const o=new k,d=r.details;if(d?.error)o.addChild(new n(s.fg("error","  "+d.error),0,0));else if(d?.taskNull)o.addChild(new n(s.fg("muted","  Task not found"),0,0));else if(d?.task){const t=d.task,e=t.status==="completed"?"success":t.status==="in_progress"?"accent":"muted";if(o.addChild(new n(s.fg("toolTitle",`  #${t.id}`)+" "+s.fg("text",t.subject),0,0)),o.addChild(new n(s.fg("muted","  Status: ")+s.fg(e,t.status),0,0)),t.description){const a=t.description.length>300?t.description.slice(0,300)+"...":t.description;o.addChild(new n(s.fg("muted","  ")+s.fg("toolOutput",a),0,0))}t.blockedBy.length>0&&o.addChild(new n(s.fg("warning",`  Blocked by: ${t.blockedBy.map(a=>`#${a}`).join(", ")}`),0,0)),t.blocks.length>0&&o.addChild(new n(s.fg("muted",`  Blocks: ${t.blocks.map(a=>`#${a}`).join(", ")}`),0,0))}else{const t=r.content?.filter(e=>e.type==="text").map(e=>e.type==="text"?e.text:"").join(`
+`);t&&o.addChild(new n(s.fg("toolOutput",t),0,0))}return o},"renderResult"),guidance:`Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements
+
+## Output
+
+Returns full task details:
+- **subject**: Task title
+- **description**: Detailed requirements and context
+- **status**: 'pending', 'in_progress', or 'completed'
+- **blocks**: Tasks waiting on this one to complete
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+
+- After fetching a task, verify its blockedBy list is empty before beginning work.
+- Use TaskList to see all tasks in summary form.`,async execute(r,i,s,o,d){try{const t=await f(d.agentDir,p,i.taskId);if(!t)return{content:[{type:"text",text:"Task not found"}],details:{task:null}};const e=[`Task #${t.id}: ${t.subject}`,`Status: ${t.status}`,`Description: ${t.description}`];return t.owner&&e.push(`Owner: ${t.owner}`),t.activeForm&&e.push(`Active form: ${t.activeForm}`),t.blockedBy.length>0&&e.push(`Blocked by: ${t.blockedBy.map(a=>`#${a}`).join(", ")}`),t.blocks.length>0&&e.push(`Blocks: ${t.blocks.map(a=>`#${a}`).join(", ")}`),{content:[{type:"text",text:e.join(`
+`)}],details:{task:{id:t.id,subject:t.subject,description:t.description,status:t.status,blocks:t.blocks,blockedBy:t.blockedBy}}}}catch(t){const e=t instanceof Error?t.message:String(t);return{content:[{type:"text",text:`Error: ${e}`}],details:{error:e}}}}}}l(w,"createTaskGetTool");export{w as createTaskGetTool};

package/dist/extensions/builtin/task/task-tools/task-list-tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * [WHO]: TaskList tool - lists all tasks in the task list
+ * [FROM]: Depends on @sinclair/typebox, ../task-store, ../task-types
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/task-list-tool.ts
+ */
+import type { Static } from "@sinclair/typebox";
+import type { AgentToolResult } from "@catui/agent-core";
+import type { ExtensionContext } from "../../../../core/extensions-host/types.js";
+import { type Component } from "@catui/tui";
+import type { Theme } from "../../../../core/theme-contract.js";
+declare const taskListSchema: import("@sinclair/typebox").TObject<{}>;
+export type TaskListInput = Static<typeof taskListSchema>;
+export declare function createTaskListTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{}>;
+    renderCall: (_args: unknown, theme: Theme) => Component;
+    renderResult: (result: AgentToolResult<unknown>, _opts: {
+        expanded: boolean;
+        isPartial: boolean;
+    }, theme: Theme) => Component;
+    guidance: string;
+    execute(_toolCallId: string, _params: TaskListInput, _signal: AbortSignal | undefined, _onUpdate: undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};