@xortex/xcode 3.0.0

package/tools/TaskCreateTool/TaskCreateTool.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import {
+  executeTaskCreatedHooks,
+  getTaskCreatedHookMessage,
+} from '../../utils/hooks.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import {
+  createTask,
+  deleteTask,
+  getTaskListId,
+  isTodoV2Enabled,
+} from '../../utils/tasks.js'
+import { getAgentName, getTeamName } from '../../utils/teammate.js'
+import { TASK_CREATE_TOOL_NAME } from './constants.js'
+import { DESCRIPTION, getPrompt } from './prompt.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    subject: z.string().describe('A brief title for the task'),
+    description: z.string().describe('What needs to be done'),
+    activeForm: z
+      .string()
+      .optional()
+      .describe(
+        'Present continuous form shown in spinner when in_progress (e.g., "Running tests")',
+      ),
+    metadata: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe('Arbitrary metadata to attach to the task'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    task: z.object({
+      id: z.string(),
+      subject: z.string(),
+    }),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const TaskCreateTool = buildTool({
+  name: TASK_CREATE_TOOL_NAME,
+  searchHint: 'create a task in the task list',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return DESCRIPTION
+  },
+  async prompt() {
+    return getPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'TaskCreate'
+  },
+  shouldDefer: true,
+  isEnabled() {
+    return isTodoV2Enabled()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.subject
+  },
+  renderToolUseMessage() {
+    return null
+  },
+  async call({ subject, description, activeForm, metadata }, context) {
+    const taskId = await createTask(getTaskListId(), {
+      subject,
+      description,
+      activeForm,
+      status: 'pending',
+      owner: undefined,
+      blocks: [],
+      blockedBy: [],
+      metadata,
+    })
+
+    const blockingErrors: string[] = []
+    const generator = executeTaskCreatedHooks(
+      taskId,
+      subject,
+      description,
+      getAgentName(),
+      getTeamName(),
+      undefined,
+      context?.abortController?.signal,
+      undefined,
+      context,
+    )
+    for await (const result of generator) {
+      if (result.blockingError) {
+        blockingErrors.push(getTaskCreatedHookMessage(result.blockingError))
+      }
+    }
+
+    if (blockingErrors.length > 0) {
+      await deleteTask(getTaskListId(), taskId)
+      throw new Error(blockingErrors.join('\n'))
+    }
+
+    // Auto-expand task list when creating tasks
+    context.setAppState(prev => {
+      if (prev.expandedView === 'tasks') return prev
+      return { ...prev, expandedView: 'tasks' as const }
+    })
+
+    return {
+      data: {
+        task: {
+          id: taskId,
+          subject,
+        },
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam(content, toolUseID) {
+    const { task } = content as Output
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: `Task #${task.id} created successfully: ${task.subject}`,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

package/tools/TaskCreateTool/constants.ts

@@ -0,0 +1 @@
+export const TASK_CREATE_TOOL_NAME = 'TaskCreate'

package/tools/TaskCreateTool/prompt.ts

@@ -0,0 +1,56 @@
+import { isAgentSwarmsEnabled } from '../../utils/agentSwarmsEnabled.js'
+
+export const DESCRIPTION = 'Create a new task in the task list'
+
+export function getPrompt(): string {
+  const teammateContext = isAgentSwarmsEnabled()
+    ? ' and potentially assigned to teammates'
+    : ''
+
+  const teammateTips = isAgentSwarmsEnabled()
+    ? `- Include enough detail in the description for another agent to understand and complete the task
+- New tasks are created with status 'pending' and no owner - use TaskUpdate with the \`owner\` parameter to assign them
+`
+    : ''
+
+  return `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${teammateContext}
+- 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
+${teammateTips}- Check TaskList first to avoid creating duplicate tasks
+`
+}

package/tools/TaskGetTool/TaskGetTool.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import {
+  getTask,
+  getTaskListId,
+  isTodoV2Enabled,
+  TaskStatusSchema,
+} from '../../utils/tasks.js'
+import { TASK_GET_TOOL_NAME } from './constants.js'
+import { DESCRIPTION, PROMPT } from './prompt.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    taskId: z.string().describe('The ID of the task to retrieve'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    task: z
+      .object({
+        id: z.string(),
+        subject: z.string(),
+        description: z.string(),
+        status: TaskStatusSchema(),
+        blocks: z.array(z.string()),
+        blockedBy: z.array(z.string()),
+      })
+      .nullable(),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const TaskGetTool = buildTool({
+  name: TASK_GET_TOOL_NAME,
+  searchHint: 'retrieve a task by ID',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return DESCRIPTION
+  },
+  async prompt() {
+    return PROMPT
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'TaskGet'
+  },
+  shouldDefer: true,
+  isEnabled() {
+    return isTodoV2Enabled()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.taskId
+  },
+  renderToolUseMessage() {
+    return null
+  },
+  async call({ taskId }) {
+    const taskListId = getTaskListId()
+
+    const task = await getTask(taskListId, taskId)
+
+    if (!task) {
+      return {
+        data: {
+          task: null,
+        },
+      }
+    }
+
+    return {
+      data: {
+        task: {
+          id: task.id,
+          subject: task.subject,
+          description: task.description,
+          status: task.status,
+          blocks: task.blocks,
+          blockedBy: task.blockedBy,
+        },
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam(content, toolUseID) {
+    const { task } = content as Output
+    if (!task) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: 'Task not found',
+      }
+    }
+
+    const lines = [
+      `Task #${task.id}: ${task.subject}`,
+      `Status: ${task.status}`,
+      `Description: ${task.description}`,
+    ]
+
+    if (task.blockedBy.length > 0) {
+      lines.push(`Blocked by: ${task.blockedBy.map(id => `#${id}`).join(', ')}`)
+    }
+    if (task.blocks.length > 0) {
+      lines.push(`Blocks: ${task.blocks.map(id => `#${id}`).join(', ')}`)
+    }
+
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: lines.join('\n'),
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

package/tools/TaskGetTool/constants.ts

@@ -0,0 +1 @@
+export const TASK_GET_TOOL_NAME = 'TaskGet'

package/tools/TaskGetTool/prompt.ts

@@ -0,0 +1,24 @@
+export const DESCRIPTION = 'Get a task by ID from the task list'
+
+export const PROMPT = `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.
+`

package/tools/TaskListTool/TaskListTool.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import {
+  getTaskListId,
+  isTodoV2Enabled,
+  listTasks,
+  TaskStatusSchema,
+} from '../../utils/tasks.js'
+import { TASK_LIST_TOOL_NAME } from './constants.js'
+import { DESCRIPTION, getPrompt } from './prompt.js'
+
+const inputSchema = lazySchema(() => z.strictObject({}))
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    tasks: z.array(
+      z.object({
+        id: z.string(),
+        subject: z.string(),
+        status: TaskStatusSchema(),
+        owner: z.string().optional(),
+        blockedBy: z.array(z.string()),
+      }),
+    ),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+export const TaskListTool = buildTool({
+  name: TASK_LIST_TOOL_NAME,
+  searchHint: 'list all tasks',
+  maxResultSizeChars: 100_000,
+  async description() {
+    return DESCRIPTION
+  },
+  async prompt() {
+    return getPrompt()
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  userFacingName() {
+    return 'TaskList'
+  },
+  shouldDefer: true,
+  isEnabled() {
+    return isTodoV2Enabled()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  renderToolUseMessage() {
+    return null
+  },
+  async call() {
+    const taskListId = getTaskListId()
+
+    const allTasks = (await listTasks(taskListId)).filter(
+      t => !t.metadata?._internal,
+    )
+
+    // Build a set of resolved task IDs for filtering
+    const resolvedTaskIds = new Set(
+      allTasks.filter(t => t.status === 'completed').map(t => t.id),
+    )
+
+    const tasks = allTasks.map(task => ({
+      id: task.id,
+      subject: task.subject,
+      status: task.status,
+      owner: task.owner,
+      blockedBy: task.blockedBy.filter(id => !resolvedTaskIds.has(id)),
+    }))
+
+    return {
+      data: {
+        tasks,
+      },
+    }
+  },
+  mapToolResultToToolResultBlockParam(content, toolUseID) {
+    const { tasks } = content as Output
+    if (tasks.length === 0) {
+      return {
+        tool_use_id: toolUseID,
+        type: 'tool_result',
+        content: 'No tasks found',
+      }
+    }
+
+    const lines = tasks.map(task => {
+      const owner = task.owner ? ` (${task.owner})` : ''
+      const blocked =
+        task.blockedBy.length > 0
+          ? ` [blocked by ${task.blockedBy.map(id => `#${id}`).join(', ')}]`
+          : ''
+      return `#${task.id} [${task.status}] ${task.subject}${owner}${blocked}`
+    })
+
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: lines.join('\n'),
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)

package/tools/TaskListTool/constants.ts

@@ -0,0 +1 @@
+export const TASK_LIST_TOOL_NAME = 'TaskList'

package/tools/TaskListTool/prompt.ts

@@ -0,0 +1,49 @@
+import { isAgentSwarmsEnabled } from '../../utils/agentSwarmsEnabled.js'
+
+export const DESCRIPTION = 'List all tasks in the task list'
+
+export function getPrompt(): string {
+  const teammateUseCase = isAgentSwarmsEnabled()
+    ? `- Before assigning tasks to teammates, to see what's available
+`
+    : ''
+
+  const idDescription = isAgentSwarmsEnabled()
+    ? '- **id**: Task identifier (use with TaskGet, TaskUpdate)'
+    : '- **id**: Task identifier (use with TaskGet, TaskUpdate)'
+
+  const teammateWorkflow = isAgentSwarmsEnabled()
+    ? `
+## Teammate Workflow
+
+When working as a teammate:
+1. After completing your current task, call TaskList to find available work
+2. Look for tasks with status 'pending', no owner, and empty blockedBy
+3. **Prefer tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+4. Claim an available task using TaskUpdate (set \`owner\` to your name), or wait for leader assignment
+5. If blocked, focus on unblocking tasks or notify the team lead
+`
+    : ''
+
+  return `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
+${teammateUseCase}- 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:
+${idDescription}
+- **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.
+${teammateWorkflow}`
+}