catui-agent 1.0.0-beta.0

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

@@ -0,0 +1,22 @@
+var w=Object.defineProperty;var k=(r,a)=>w(r,"name",{value:a,configurable:!0});import{Type as b}from"@sinclair/typebox";import{Container as p,Text as l}from"@catui/tui";import{listTasks as m}from"../task-store.js";import{DEFAULT_TASK_LIST_ID as h}from"../task-types.js";const T=b.Object({});function v(){return{name:"TaskList",label:"List Tasks",description:"List all tasks in the task list with their status and dependencies.",parameters:T,renderCall:k((r,a)=>{const s=new p;return s.addChild(new l(a.fg("toolTitle",a.bold("TaskList")),0,0)),s.addChild(new l(a.fg("muted","  Retrieving all tasks..."),0,0)),s},"renderCall"),renderResult:k((r,a,s)=>{const i=new p,o=r.details;if(o?.error)i.addChild(new l(s.fg("error","  "+o.error),0,0));else if(o?.tasks&&o.tasks.length>0){i.addChild(new l(s.fg("success",`  ${o.tasks.length} task(s):`),0,0));for(const e of o.tasks){const n=e.status==="completed"?"success":e.status==="in_progress"?"accent":"muted",c=s.fg(n,e.status),u=e.owner?s.fg("muted",` (${e.owner})`):"",t=e.blockedBy.length>0?s.fg("warning",` [blocked by ${e.blockedBy.map(d=>`#${d}`).join(", ")}]`):"";i.addChild(new l(`  #${e.id} ${c} ${s.fg("text",e.subject)}${u}${t}`,0,0))}}else{const e=r.content?.filter(n=>n.type==="text").map(n=>n.type==="text"?n.text:"").join(`
+`);e&&i.addChild(new l(s.fg("toolOutput",e),0,0))}return i},"renderResult"),guidance:`Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task
+- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+
+## Output
+
+Returns a summary of each task:
+- **id**: Task identifier (use with TaskGet, TaskUpdate)
+- **subject**: Brief description of the task
+- **status**: 'pending', 'in_progress', or 'completed'
+- **owner**: Agent ID if assigned, empty if available
+- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+
+Use TaskGet with a specific task ID to view full details including description and comments.`,async execute(r,a,s,i,o){try{const e=(await m(o.agentDir,h)).filter(t=>!t.metadata?._internal);if(e.length===0)return{content:[{type:"text",text:"No tasks found"}],details:{tasks:[]}};const n=new Set(e.filter(t=>t.status==="completed").map(t=>t.id)),c=e.map(t=>({id:t.id,subject:t.subject,status:t.status,owner:t.owner,blockedBy:t.blockedBy.filter(d=>!n.has(d))}));return{content:[{type:"text",text:c.map(t=>{const d=t.owner?` (${t.owner})`:"",f=t.blockedBy.length>0?` [blocked by ${t.blockedBy.map(g=>`#${g}`).join(", ")}]`:"";return`#${t.id} [${t.status}] ${t.subject}${d}${f}`}).join(`
+`)}],details:{tasks:c}}}catch(e){const n=e instanceof Error?e.message:String(e);return{content:[{type:"text",text:`Error: ${n}`}],details:{error:n}}}}}}k(v,"createTaskListTool");export{v as createTaskListTool};

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

@@ -0,0 +1,32 @@
+/**
+ * [WHO]: TaskOutput tool - retrieves task details and current state
+ * [FROM]: Claude Code TaskOutputTool (1:1 port, simplified for state-managed tasks)
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/task-output-tool.ts
+ *
+ * NOTE: CC's TaskOutputTool handles background shell/agent output with blocking.
+ * In Catui there are no background processes, so this is a simplified version
+ * that returns the task's current state and description.
+ */
+import type { Static } from "@sinclair/typebox";
+import type { AgentToolResult } from "@catui/agent-core";
+import type { ExtensionContext } from "../../../../core/extensions-host/types.js";
+declare const taskOutputSchema: import("@sinclair/typebox").TObject<{
+    task_id: import("@sinclair/typebox").TString;
+    block: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type TaskOutputInput = Static<typeof taskOutputSchema>;
+export declare function createTaskOutputTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        task_id: import("@sinclair/typebox").TString;
+        block: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>;
+    guidance: string;
+    execute(_toolCallId: string, params: TaskOutputInput, _signal: AbortSignal | undefined, _onUpdate: undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};

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

@@ -0,0 +1,10 @@
+var i=Object.defineProperty;var n=(o,s)=>i(o,"name",{value:s,configurable:!0});import{Type as e}from"@sinclair/typebox";import{getTask as u}from"../task-store.js";import{DEFAULT_TASK_LIST_ID as c}from"../task-types.js";const l=e.Object({task_id:e.String({description:"The task ID to get output from"}),block:e.Optional(e.Boolean({description:"Whether to wait for completion (default: true). In Catui, this is a no-op since tasks are state-managed.",default:!0})),timeout:e.Optional(e.Number({description:"Max wait time in ms (default: 30000). In Catui, this is a no-op.",default:3e4,minimum:0,maximum:6e5}))});function g(){return{name:"TaskOutput",label:"Task Output",description:"Retrieve the current state and details of a task. In Catui, tasks are state-managed (no background processes), so this returns the task's current status and description.",parameters:l,guidance:`DEPRECATED: Prefer using the Read tool on the task's output file path instead. Background tasks return their output file path in the tool result, and you receive a <task-notification> with the same path when the task completes -- Read that file directly.
+
+- Retrieves output from a running or completed task (background shell, agent, or remote session)
+- Takes a task_id parameter identifying the task
+- Returns the task output along with status information
+- Use block=true (default) to wait for task completion
+- Use block=false for non-blocking check of current status
+- Task IDs can be found using the /tasks command
+- Works with all task types: background shells, async agents, and remote sessions`,async execute(o,s,d,p,r){try{const t=await u(r.agentDir,c,s.task_id);if(!t)return{content:[{type:"text",text:`No task found with ID: ${s.task_id}`}],details:{retrieval_status:"not_ready",task:null}};const a=t.status==="completed";return{content:[{type:"text",text:[`Task #${t.id}: ${t.subject}`,`Status: ${t.status}`,`Description: ${t.description}`,t.owner?`Owner: ${t.owner}`:null,t.activeForm?`Active form: ${t.activeForm}`:null].filter(Boolean).join(`
+`)}],details:{retrieval_status:a?"success":t.status==="in_progress"?"not_ready":"success",task:{task_id:t.id,task_type:"task",status:t.status,description:t.description,output:t.description}}}}catch(t){const a=t instanceof Error?t.message:String(t);return{content:[{type:"text",text:`Error: ${a}`}],details:{retrieval_status:"not_ready",task:null,error:a}}}}}}n(g,"createTaskOutputTool");export{g as createTaskOutputTool};

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

@@ -0,0 +1,31 @@
+/**
+ * [WHO]: TaskStop tool - marks a task as completed (Catui has no background processes)
+ * [FROM]: Depends on @sinclair/typebox, ../task-store, ../task-types
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/task-stop-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 taskStopSchema: import("@sinclair/typebox").TObject<{
+    task_id: import("@sinclair/typebox").TString;
+}>;
+export type TaskStopInput = Static<typeof taskStopSchema>;
+export declare function createTaskStopTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        task_id: 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: TaskStopInput, _signal: AbortSignal | undefined, _onUpdate: undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};

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

@@ -0,0 +1,5 @@
+var k=Object.defineProperty;var d=(o,t)=>k(o,"name",{value:t,configurable:!0});import{Type as c}from"@sinclair/typebox";import{Container as l,Text as r}from"@catui/tui";import{getTask as p,updateTask as g}from"../task-store.js";import{DEFAULT_TASK_LIST_ID as u}from"../task-types.js";const f=c.Object({task_id:c.String({description:"The ID of the task to stop/complete"})});function m(){return{name:"TaskStop",label:"Stop Task",description:"Stop a running task by marking it as completed. In Catui, tasks are state-managed (no background processes), so this is equivalent to setting status=completed.",parameters:f,renderCall:d((o,t)=>{const a=o,s=new l;return s.addChild(new r(t.fg("toolTitle",t.bold("TaskStop")),0,0)),s.addChild(new r(t.fg("muted","  Stopping task #")+t.fg("text",a.task_id??"?"),0,0)),s},"renderCall"),renderResult:d((o,t,a)=>{const s=new l,n=o.details;if(n?.error)s.addChild(new r(a.fg("error","  "+n.error),0,0));else if(n?.success)s.addChild(new r(a.fg("success","  Task #")+a.fg("text",n.task_id??"?")+a.fg("success"," stopped"),0,0));else{const e=o.content?.filter(i=>i.type==="text").map(i=>i.type==="text"?i.text:"").join(`
+`);e&&s.addChild(new r(a.fg("toolOutput",e),0,0))}return s},"renderResult"),guidance:`- Stops a running background task by its ID
+- Takes a task_id parameter identifying the task to stop
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running task`,async execute(o,t,a,s,n){try{const e=await p(n.agentDir,u,t.task_id);return e?e.status==="completed"?{content:[{type:"text",text:`Task #${t.task_id} is already completed`}],details:{success:!0,task_id:t.task_id,message:"Already completed"}}:(await g(n.agentDir,u,t.task_id,{status:"completed"}),{content:[{type:"text",text:`Successfully stopped task: ${t.task_id} (${e.subject})`}],details:{message:`Successfully stopped task: ${t.task_id} (${e.subject})`,task_id:t.task_id,task_type:"task",command:e.subject}}):{content:[{type:"text",text:`No task found with ID: ${t.task_id}`}],details:{success:!1,task_id:t.task_id,error:"Task not found"}}}catch(e){const i=e instanceof Error?e.message:String(e);return{content:[{type:"text",text:`Error: ${i}`}],details:{success:!1,task_id:t.task_id,error:i}}}}}}d(m,"createTaskStopTool");export{m as createTaskStopTool};

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

@@ -0,0 +1,47 @@
+/**
+ * [WHO]: TaskUpdate tool - updates a task's fields, status, and block relationships
+ * [FROM]: Depends on @sinclair/typebox, ../task-store, ../task-types
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/task-update-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 taskUpdateSchema: import("@sinclair/typebox").TObject<{
+    taskId: import("@sinclair/typebox").TString;
+    subject: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    activeForm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<string>[]>>;
+    owner: 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>>;
+    addBlocks: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    addBlockedBy: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+}>;
+export type TaskUpdateInput = Static<typeof taskUpdateSchema>;
+export declare function createTaskUpdateTool(): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        taskId: import("@sinclair/typebox").TString;
+        subject: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        activeForm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<string>[]>>;
+        owner: 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>>;
+        addBlocks: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        addBlockedBy: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<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: TaskUpdateInput, _signal: AbortSignal | undefined, _onUpdate: undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};

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

@@ -0,0 +1,77 @@
+var b=Object.defineProperty;var g=(c,e)=>b(c,"name",{value:e,configurable:!0});import{Type as t}from"@sinclair/typebox";import{Container as p,Text as k}from"@catui/tui";import{blockTask as w,deleteTask as I,getTask as T,updateTask as m,listTasks as v}from"../task-store.js";import{DEFAULT_TASK_LIST_ID as j,TaskStatusValues as B}from"../task-types.js";const S=t.Object({taskId:t.String({description:"The ID of the task to update"}),subject:t.Optional(t.String({description:"New subject for the task"})),description:t.Optional(t.String({description:"New description for the task"})),activeForm:t.Optional(t.String({description:'Present continuous form shown in spinner when in_progress (e.g., "Running tests")'})),status:t.Optional(t.Union([...B,"deleted"].map(c=>t.Literal(c)),{description:"New status for the task. Use 'deleted' to remove the task."})),owner:t.Optional(t.String({description:"New owner for the task"})),metadata:t.Optional(t.Record(t.String(),t.Unknown(),{description:"Metadata keys to merge into the task. Set a key to null to delete it."})),addBlocks:t.Optional(t.Array(t.String(),{description:"Task IDs that this task blocks"})),addBlockedBy:t.Optional(t.Array(t.String(),{description:"Task IDs that block this task"}))});function O(){return{name:"TaskUpdate",label:"Update Task",description:"Update a task's fields, status, metadata, and block relationships. Use status='deleted' to remove a task.",parameters:S,renderCall:g((c,e)=>{const a=c,i=new p;if(i.addChild(new k(e.fg("toolTitle",e.bold("TaskUpdate")),0,0)),i.addChild(new k(e.fg("muted","  Task #")+e.fg("text",a.taskId??"?"),0,0)),a.status){const o=a.status==="completed"?"success":a.status==="deleted"?"error":"accent";i.addChild(new k(e.fg("muted","  Status \u2192 ")+e.fg(o,a.status),0,0))}return a.subject&&i.addChild(new k(e.fg("muted","  Subject: ")+e.fg("text",a.subject),0,0)),i},"renderCall"),renderResult:g((c,e,a)=>{const i=new p,o=c.details;if(o?.error)i.addChild(new k(a.fg("error","  "+o.error),0,0));else if(o?.deleted)i.addChild(new k(a.fg("success","  Task deleted"),0,0));else if(o?.task)i.addChild(new k(a.fg("success",`  Task #${o.task.id} updated`)+a.fg("muted"," \u2014 ")+a.fg("text",o.task.subject),0,0));else{const d=c.content?.filter(s=>s.type==="text").map(s=>s.type==="text"?s.text:"").join(`
+`);d&&i.addChild(new k(a.fg("toolOutput",d),0,0))}return i},"renderResult"),guidance:`Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to \`deleted\` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: \`pending\` \u2192 \`in_progress\` \u2192 \`completed\`
+
+Use \`deleted\` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using \`TaskGet\` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+\`\`\`json
+{"taskId": "1", "status": "in_progress"}
+\`\`\`
+
+Mark task as completed after finishing work:
+\`\`\`json
+{"taskId": "1", "status": "completed"}
+\`\`\`
+
+Delete a task:
+\`\`\`json
+{"taskId": "1", "status": "deleted"}
+\`\`\`
+
+Claim a task by setting owner:
+\`\`\`json
+{"taskId": "1", "owner": "my-name"}
+\`\`\`
+
+Set up task dependencies:
+\`\`\`json
+{"taskId": "2", "addBlockedBy": ["1"]}
+\`\`\``,async execute(c,e,a,i,o){try{const d=j,s=await T(o.agentDir,d,e.taskId);if(!s)return{content:[{type:"text",text:`Task #${e.taskId} not found`}],details:{success:!1,taskId:e.taskId,updatedFields:[],error:"Task not found"}};const l=[],u={};if(e.subject!==void 0&&e.subject!==s.subject&&(u.subject=e.subject,l.push("subject")),e.description!==void 0&&e.description!==s.description&&(u.description=e.description,l.push("description")),e.activeForm!==void 0&&e.activeForm!==s.activeForm&&(u.activeForm=e.activeForm,l.push("activeForm")),e.owner!==void 0&&e.owner!==s.owner&&(u.owner=e.owner,l.push("owner")),e.metadata!==void 0){const n={...s.metadata??{}};for(const[r,f]of Object.entries(e.metadata))f===null?delete n[r]:n[r]=f;u.metadata=n,l.push("metadata")}if(e.status!==void 0){if(e.status==="deleted"){const n=await I(o.agentDir,d,e.taskId);return{content:[{type:"text",text:n?`Deleted task #${e.taskId}`:`Failed to delete task #${e.taskId}`}],details:{success:n,taskId:e.taskId,updatedFields:n?["deleted"]:[],statusChange:n?{from:s.status,to:"deleted"}:void 0}}}e.status!==s.status&&(u.status=e.status,l.push("status"))}if(Object.keys(u).length>0&&await m(o.agentDir,d,e.taskId,u),e.addBlocks&&e.addBlocks.length>0){const n=e.addBlocks.filter(r=>!s.blocks.includes(r));for(const r of n)await w(o.agentDir,d,e.taskId,r);n.length>0&&l.push("blocks")}if(e.addBlockedBy&&e.addBlockedBy.length>0){const n=e.addBlockedBy.filter(r=>!s.blockedBy.includes(r));for(const r of n)await w(o.agentDir,d,r,e.taskId);n.length>0&&l.push("blockedBy")}const y=e.status!==void 0&&e.status!==s.status&&e.status!=="deleted"?{from:s.status,to:e.status}:void 0;let h=`Updated task #${e.taskId} ${l.join(", ")}`;if(u.status==="completed"){const n=await v(o.agentDir,d);n.every(f=>f.status==="completed")&&n.length>=3&&!n.some(f=>/verif/i.test(f.subject))&&(h+=`
+
+NOTE: You just closed out 3+ tasks and none of them was a verification step. Before writing your final summary, verify your work.`)}return{content:[{type:"text",text:h}],details:{success:!0,taskId:e.taskId,updatedFields:l,statusChange:y}}}catch(d){const s=d instanceof Error?d.message:String(d);return{content:[{type:"text",text:`Error: ${s}`}],details:{success:!1,taskId:e.taskId,updatedFields:[],error:s}}}}}}g(O,"createTaskUpdateTool");export{O as createTaskUpdateTool};

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

@@ -0,0 +1,34 @@
+/**
+ * [WHO]: ToolSearch tool - discovers tools by keyword search
+ * [FROM]: Claude Code ToolSearchTool + prompt.ts (1:1 port)
+ * [TO]: Consumed by task extension via registerTool()
+ * [HERE]: extensions/builtin/task/task-tools/tool-search-tool.ts
+ */
+import type { Static } from "@sinclair/typebox";
+import type { AgentToolResult } from "@catui/agent-core";
+import type { ExtensionContext } from "../../../../core/extensions-host/types.js";
+declare const toolSearchSchema: import("@sinclair/typebox").TObject<{
+    query: import("@sinclair/typebox").TString;
+    max_results: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type ToolSearchInput = Static<typeof toolSearchSchema>;
+/**
+ * @param getAllTools - function returning all available tools (from ExtensionAPI.getAllTools)
+ */
+export declare function createToolSearchTool(getAllTools: () => Array<{
+    name: string;
+    description: string;
+    parameters: unknown;
+    searchHint?: string;
+}>): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        query: import("@sinclair/typebox").TString;
+        max_results: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    }>;
+    guidance: string;
+    execute(_toolCallId: string, params: ToolSearchInput, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<unknown>>;
+};
+export {};

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

@@ -0,0 +1,14 @@
+var b=Object.defineProperty;var h=(n,r)=>b(n,"name",{value:r,configurable:!0});import{Type as y}from"@sinclair/typebox";const O="ToolSearch",C=y.Object({query:y.String({description:'Query to find deferred tools. Use "select:<tool_name>" for direct selection, or keywords to search.'}),max_results:y.Optional(y.Number({description:"Maximum number of results to return (default: 5)",default:5}))}),M=`Fetches full schema definitions for deferred tools so they can be called.
+
+`,k=`Deferred tools appear by name in tool search results.
+
+`,N=` Until fetched, only the name is known \u2014 there is no parameter schema, so the tool cannot be invoked. This tool takes a query, matches it against the deferred tool list, and returns the matched tools' complete JSONSchema definitions inside a <functions> block. Once a tool's schema appears in that result, it is callable exactly like any tool defined at the top of the prompt.
+
+Result format: each matched tool appears as one <function>{"description": "...", "name": "...", "parameters": {...}}</function> line inside the <functions> block \u2014 the same encoding as the tool list at the top of this prompt.
+
+Query forms:
+- "select:Read,Edit,Grep" \u2014 fetch these exact tools by name
+- "notebook jupyter" \u2014 keyword search, up to max_results best matches
+- "+slack send" \u2014 require "slack" in the name, rank by remaining terms`,S=M+k+N;function $(n){return n.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}h($,"escapeRegExp");function T(n){if(n.startsWith("mcp__")){const a=n.replace(/^mcp__/,"").toLowerCase();return{parts:a.split("__").flatMap(u=>u.split("_")).filter(Boolean),full:a.replace(/__/g," ").replace(/_/g," "),isMcp:!0}}const r=n.replace(/([a-z])([A-Z])/g,"$1 $2").replace(/_/g," ").toLowerCase().split(/\s+/).filter(Boolean);return{parts:r,full:r.join(" "),isMcp:!1}}h(T,"parseToolName");function P(n){const r=new Map;for(const a of n)r.has(a)||r.set(a,new RegExp(`\\b${$(a)}\\b`));return r}h(P,"compileTermPatterns");function q(n,r,a){const f=n.toLowerCase().trim(),u=r.find(e=>e.name.toLowerCase()===f);if(u)return[u.name];if(f.startsWith("mcp__")&&f.length>5){const e=r.filter(t=>t.name.toLowerCase().startsWith(f)).slice(0,a).map(t=>t.name);if(e.length>0)return e}const x=f.split(/\s+/).filter(e=>e.length>0),o=[],c=[];for(const e of x)e.startsWith("+")&&e.length>1?o.push(e.slice(1)):c.push(e);const g=o.length>0?[...o,...c]:x,_=P(g);let p=r;return o.length>0&&(p=r.filter(e=>{const t=T(e.name),l=e.description.toLowerCase(),d=e.searchHint?.toLowerCase()??"";return o.every(s=>{const i=_.get(s);return t.parts.includes(s)||t.parts.some(m=>m.includes(s))||i.test(l)||d&&i.test(d)})})),p.map(e=>{const t=T(e.name),l=e.description.toLowerCase(),d=e.searchHint?.toLowerCase()??"";let s=0;for(const i of g){const m=_.get(i);t.parts.includes(i)?s+=t.isMcp?12:10:t.parts.some(L=>L.includes(i))&&(s+=t.isMcp?6:5),t.full.includes(i)&&s===0&&(s+=3),d&&m.test(d)&&(s+=4),m.test(l)&&(s+=2)}return{name:e.name,score:s}}).filter(e=>e.score>0).sort((e,t)=>t.score-e.score).slice(0,a).map(e=>e.name)}h(q,"searchToolsWithKeywords");function j(n){return{name:O,label:"Search Tools",description:"Discover available tools by keyword search or direct selection. Use select:<tool_name> for direct selection, or keywords to search tool names and descriptions.",parameters:C,guidance:S,async execute(r,a,f,u,x){try{const o=n(),{query:c,max_results:g=5}=a,_=c.match(/^select:(.+)$/i);if(_){const e=_[1].split(",").map(s=>s.trim()).filter(Boolean),t=[],l=[];for(const s of e){const i=o.find(m=>m.name.toLowerCase()===s.toLowerCase());i?t.includes(i.name)||t.push(i.name):l.push(s)}if(t.length===0)return{content:[{type:"text",text:`No matching tools found for: ${l.join(", ")}`}],details:{matches:[],query:c,total_deferred_tools:o.length}};let d=`Selected tools: ${t.join(", ")}`;return l.length>0&&(d+=`
+Not found: ${l.join(", ")}`),{content:[{type:"text",text:d}],details:{matches:t,query:c,total_deferred_tools:o.length}}}const p=q(c,o,g);return p.length===0?{content:[{type:"text",text:"No matching deferred tools found"}],details:{matches:[],query:c,total_deferred_tools:o.length}}:{content:[{type:"text",text:p.map(e=>{const t=o.find(l=>l.name===e);return t?`- ${e}: ${t.description}`:`- ${e}`}).join(`
+`)}],details:{matches:p,query:c,total_deferred_tools:o.length}}}catch(o){const c=o instanceof Error?o.message:String(o);return{content:[{type:"text",text:`Error: ${c}`}],details:{matches:[],query:a.query,error:c}}}}}}h(j,"createToolSearchTool");export{j as createToolSearchTool};

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

@@ -0,0 +1,30 @@
+/**
+ * [WHO]: Task type definitions (Task, TaskStatus)
+ * [FROM]: Inspired by Claude Code utils/tasks.ts
+ * [TO]: Consumed by task-store.ts, all task-tools
+ * [HERE]: extensions/builtin/task/task-types.ts - type definitions for task system
+ */
+import { type Static } from "@sinclair/typebox";
+export declare const TaskStatusValues: readonly ["pending", "in_progress", "completed"];
+export type TaskStatus = (typeof TaskStatusValues)[number];
+export declare const TaskUpdateStatusValues: readonly ["pending", "in_progress", "completed", "deleted"];
+export type TaskUpdateStatus = (typeof TaskUpdateStatusValues)[number];
+export declare const TaskSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    subject: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TString;
+    activeForm: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    owner: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"pending" | "in_progress" | "completed">[]>;
+    blocks: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    blockedBy: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>>;
+}>;
+export type Task = Static<typeof TaskSchema>;
+/** Default task list ID for standalone sessions */
+export declare const DEFAULT_TASK_LIST_ID = "tasklist";
+/**
+ * Sanitize a string for safe use in file paths.
+ * Only allows alphanumeric characters, hyphens, and underscores.
+ */
+export declare function sanitizePathComponent(input: string): string;

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

@@ -0,0 +1 @@
+var a=Object.defineProperty;var n=(e,o)=>a(e,"name",{value:o,configurable:!0});import{Type as t}from"@sinclair/typebox";const r=["pending","in_progress","completed"],p=[...r,"deleted"],c=t.Object({id:t.String(),subject:t.String(),description:t.String(),activeForm:t.Optional(t.String()),owner:t.Optional(t.String()),status:t.Union(r.map(e=>t.Literal(e))),blocks:t.Array(t.String()),blockedBy:t.Array(t.String()),metadata:t.Optional(t.Record(t.String(),t.Unknown()))}),S="tasklist";function l(e){return e.replace(/[^a-zA-Z0-9_-]/g,"-")}n(l,"sanitizePathComponent");export{S as DEFAULT_TASK_LIST_ID,c as TaskSchema,r as TaskStatusValues,p as TaskUpdateStatusValues,l as sanitizePathComponent};

package/dist/extensions/builtin/teach/README.md

@@ -0,0 +1,197 @@
+# Teach Extension
+
+> P2 | Guided knowledge teaching extension for Catui
+
+## Overview
+
+The teach extension provides guided, source-verified learning for any topic. It implements a progressive teaching methodology with analogies, source verification, and learning progress tracking.
+
+## Features
+
+- **Progressive Teaching**: Hook → Level 1 → Level 2 → Level 3 → Bridge → Takeaways
+- **Source Verification**: Every fact has a verifiable source with confidence level
+- **Learning Styles**: Quick Overview, Deep Dive, Focused Skill, Holistic
+- **Learner Level Detection**: Adapts to L0-L3 levels automatically
+- **Session Memory**: Tracks glossary, depth, coverage, and questions
+- **Learning Records**: Persists progress to `.catui/teach/`
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Extension entry point, registers /teach command and teach tool |
+| `teach-runtime.ts` | Core teaching state machine |
+| `teach-prompts.ts` | Prompt templates for each teaching level |
+| `teach-format.ts` | Output formatting utilities |
+| `teach-types.ts` | TypeScript type definitions |
+| `teach-i18n.ts` | Internationalization (en/zh) |
+| `teach-persistence.ts` | Learning record and mission persistence |
+| `references/analogy-library.md` | Curated analogies for common concepts |
+| `references/teaching-template.md` | Lesson structure templates |
+| `references/learning-paths.md` | Structured curricula for different levels |
+| `references/source-verification.md` | Source citation rules and hierarchy |
+
+## Usage
+
+### Command
+
+```
+/teach <topic>
+```
+
+Example:
+```
+/teach how to cook pasta
+/teach React hooks
+/teach machine learning basics
+```
+
+### Tool
+
+The agent can use the `teach` tool:
+
+```json
+{
+  "name": "teach",
+  "parameters": {
+    "topic": "cooking pasta",
+    "action": "start"
+  }
+}
+```
+
+Actions:
+- `start`: Begin teaching a new topic
+- `respond`: Process user's response
+- `status`: Get current teaching state
+
+## Teaching Flow
+
+### Phase 1: Mission Discovery
+
+Understand the learner's goals:
+- Why do they want to learn this?
+- What do they already know?
+- What's their success criteria?
+
+### Phase 2: Learning Style Selection
+
+Choose the appropriate depth:
+- **Quick Overview** (10-15 min): Just the essentials
+- **Deep Dive** (30-60 min): Comprehensive understanding
+- **Focused Skill** (20-30 min): Master one specific thing
+- **Holistic** (multiple sessions): Become an expert
+
+### Phase 3: Progressive Teaching
+
+Teach layer by layer:
+- **Hook** (Level 0): Why should you care?
+- **Level 1**: One-sentence version + core analogy
+- **Level 2**: How it works + example
+- **Level 3**: Deep dive + real scenario
+- **Bridge**: What this means for you
+- **Takeaways**: 3 core points
+
+### Phase 4: Progress Tracking
+
+Save learning records and suggest next steps.
+
+## Source Verification
+
+Every factual claim must include:
+- Source name and URL
+- Confidence level (⭐⭐⭐⭐⭐)
+- Verification method
+
+Source hierarchy:
+1. ⭐⭐⭐⭐⭐ Official documentation, peer-reviewed papers
+2. ⭐⭐⭐⭐ Recognized experts, established institutions
+3. ⭐⭐⭐ Community sources (Stack Overflow, Reddit)
+4. ⭐⭐ Blog posts, tutorials
+5. ⭐ User-generated content
+
+## Learner Level Detection
+
+The extension automatically detects the learner's level:
+
+| Level | Signals | Adaptation |
+|-------|---------|------------|
+| L0 零基础 | "What is", "completely不懂" | All life analogies, no technical terms |
+| L1 入门 | Knows basic concepts | Bridge from known concepts |
+| L2 进阶 | Knows core concepts | Use real examples |
+| L3 熟练 | Asks about details/principles | Direct discussion of architecture |
+
+## Learning Paths
+
+Structured curricula for different levels:
+- **Path A**: Foundations (L0 → L1)
+- **Path B**: Practical Skills (L1 → L2)
+- **Path C**: Deep Understanding (L2 → L3)
+
+See `references/learning-paths.md` for details.
+
+## Persistence
+
+Learning records are saved to:
+```
+.catui/teach/
+├── records/          # Learning records
+├── missions/         # Mission documents
+└── glossary.json     # Term glossary
+```
+
+## Integration
+
+### With Agent
+
+The teach extension integrates with the agent through:
+- `/teach` command registration
+- `teach` tool for agent use
+- Teach renderer for custom message display
+
+### With Other Extensions
+
+- Uses `interview` tool for mission discovery
+- Uses `link-world` for source verification (when available)
+- Uses session persistence for learning records
+
+## Configuration
+
+No special configuration required. The extension:
+- Auto-detects locale from settings
+- Uses workspace path for persistence
+- Adapts to learner level automatically
+
+## Development
+
+### Adding New Analogies
+
+Edit `references/analogy-library.md` to add new analogies.
+
+### Adding New Learning Paths
+
+Edit `references/learning-paths.md` to add new paths.
+
+### Customizing Prompts
+
+Edit `teach-prompts.ts` to customize teaching prompts.
+
+### Adding Languages
+
+Edit `teach-i18n.ts` to add new language support.
+
+## Dependencies
+
+- `core/extensions-host/types.ts`: Extension API
+- `core/session/session-manager.ts`: Session persistence (optional)
+- `node:fs`, `node:path`: File operations for persistence
+
+## Version History
+
+- **v1.0.0** (2026-06-10): Initial release
+  - Progressive teaching flow
+  - Source verification
+  - Learning style selection
+  - Learner level detection
+  - Session memory
+  - Learning record persistence

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

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: teachExtension - registers /teach command, teaching state machine, and renderer
+ * [FROM]: Depends on core/extensions-host/types, teach-runtime.ts, teach-format.ts, teach-i18n.ts
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/builtin/teach/index.ts - guided knowledge teaching extension
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+import { TeachRuntime } from "./teach-runtime.js";
+declare const TEACH_CUSTOM_TYPE = "teach";
+declare const TEACH_VERSION = "1.0.0";
+export default function teachExtension(api: ExtensionAPI): Promise<void>;
+export { TeachRuntime, TEACH_CUSTOM_TYPE, TEACH_VERSION };

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

@@ -0,0 +1,6 @@
+var w=Object.defineProperty;var u=(r,e)=>w(r,"name",{value:e,configurable:!0});import{Type as a}from"@sinclair/typebox";import{Box as y,Container as T,Spacer as C,Text as S}from"@catui/tui";import{formatTeachResult as d}from"./teach-format.js";import{detectTeachLocale as v}from"./teach-i18n.js";import{TeachRuntime as h}from"./teach-runtime.js";const l="teach",x="1.0.0";let L="en";const g=new WeakMap,U=a.Object({topic:a.String({description:"The topic to teach"}),action:a.Union([a.Literal("start"),a.Literal("respond"),a.Literal("status")],{description:"Action to perform"}),response:a.Optional(a.String({description:"User's response (for respond action)"}))});function f(r){let e=g.get(r);return e||(e=new h,e.initialize(r.cwd),g.set(r,e)),e}u(f,"getRuntime");async function _(r){L=v(),r.registerCommand("teach",{description:"Learn something new with guided, source-verified teaching",handler:u(async(e,t)=>{const c=e.trim();if(!c){t.ui.notify(`Usage: /teach <topic>
+
+Example: /teach how to cook pasta`,"warning");return}const i=await f(t).startTeaching(t,c),s=d(i);t.ui.notify(s,"info")},"handler")}),r.registerTool({name:"teach",label:"Teach",description:"Teach the user about a topic with guided, source-verified instruction. Use this when the user wants to learn something new. Supports progressive teaching with analogies and source verification.",parameters:U,isConcurrencySafe:!1,guidance:"Use the teach tool when the user wants to learn something. Start with action='start', then use action='respond' for subsequent interactions.",async execute(e,t,c,p,i){const s=f(i),o=u((n,m)=>({content:[{type:"text",text:d(n)}],details:{result:n,state:s.getState(),action:m}}),"makeResult");switch(t.action){case"start":{const n=await s.startTeaching(i,t.topic);return o(n,"start")}case"respond":{if(!t.response)return o({type:"error",message:"No response provided"},"respond");const n=await s.processResponse(i,t.response);return o(n,"respond")}case"status":{const n=s.getState();return n?{content:[{type:"text",text:`Current topic: ${n.topic}
+Phase: ${n.phase}
+Level: ${n.currentLevel}`}],details:{result:{type:"info",message:"Status retrieved"},state:n,action:"status"}}:o({type:"info",message:"No active session"},"status")}default:return o({type:"error",message:`Unknown action: ${t.action}`},t.action)}}}),r.registerMessageRenderer(l,(e,t,c)=>{const p=typeof e.content=="string"?e.content:e.content.filter(o=>o.type==="text").map(o=>o.text).join(`
+`),i=new y(1,1,o=>c.bg("customMessageBg",o));i.addChild(new S(c.fg("dim",p),0,0));const s=new T;return s.addChild(new C(1)),s.addChild(i),s}),r.on("resources_discover",()=>({skillPaths:[]}))}u(_,"teachExtension");export{l as TEACH_CUSTOM_TYPE,x as TEACH_VERSION,h as TeachRuntime,_ as default};