Files
pi-lgtm/src/index.ts
T
tintinweb 86d2b64779 v0.1.0
2026-03-12 00:47:54 +01:00

629 lines
25 KiB
TypeScript

/**
* pi-chonky-tasks — A pi extension providing Claude Code-style task tracking and coordination.
*
* Tools:
* TaskCreate — Create a structured task
* TaskList — List all tasks with status
* TaskGet — Get full task details
* TaskUpdate — Update task fields, status, dependencies
* TaskOutput — Get output from a background task process
* TaskStop — Stop a running background task process
*
* Commands:
* /tasks — Interactive task management menu
*/
import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
import { Type } from "@sinclair/typebox";
import { TaskStore } from "./task-store.js";
import { ProcessTracker } from "./process-tracker.js";
import { TaskWidget, type UICtx } from "./ui/task-widget.js";
// ---- Helpers ----
function textResult(msg: string) {
return { content: [{ type: "text" as const, text: msg }], details: undefined as any };
}
/** Task tool names — used to detect task tool usage for reminder suppression. */
const TASK_TOOL_NAMES = new Set(["TaskCreate", "TaskList", "TaskGet", "TaskUpdate", "TaskOutput", "TaskStop"]);
/** How many turns without task tool usage before injecting a reminder. */
const REMINDER_INTERVAL = 4;
const SYSTEM_REMINDER = `<system-reminder>
The task tools haven't been used recently. If you're working on tasks that would benefit from tracking progress, consider using TaskCreate to add new tasks and TaskUpdate to update task status (set to in_progress when starting, completed when done). Also consider cleaning up the task list if it has become stale. Only use these if relevant to the current work. This is just a gentle reminder - ignore if not applicable. Make sure that you NEVER mention this reminder to the user
</system-reminder>`;
export default function (pi: ExtensionAPI) {
// Initialize store: use PI_TASK_LIST_ID for shared/file-backed mode
const listId = process.env.PI_TASK_LIST_ID;
const store = new TaskStore(listId);
const tracker = new ProcessTracker();
const widget = new TaskWidget(store);
// ── Turn tracking for system-reminder injection ──
let currentTurn = 0;
let lastTaskToolUseTurn = 0;
let reminderInjectedThisCycle = false;
pi.on("turn_start", async () => {
currentTurn++;
});
// ── Token usage tracking ──
// Feed per-turn token counts from assistant messages into the widget.
pi.on("turn_end", async (event) => {
const msg = event.message as any;
if (msg?.role === "assistant" && msg.usage) {
widget.addTokenUsage(msg.usage.input ?? 0, msg.usage.output ?? 0);
}
});
// ── System-reminder injection via tool_result event ──
// Appends a <system-reminder> nudge to non-task tool results when tasks exist
// but task tools haven't been used recently (mimics Claude Code's behavior).
pi.on("tool_result", async (event) => {
// Task tool usage resets the reminder timer
if (TASK_TOOL_NAMES.has(event.toolName)) {
lastTaskToolUseTurn = currentTurn;
reminderInjectedThisCycle = false;
return {};
}
// Cheap checks first — avoid store.list() disk I/O when possible
if (currentTurn - lastTaskToolUseTurn < REMINDER_INTERVAL) return {};
if (reminderInjectedThisCycle) return {};
const tasks = store.list();
if (tasks.length === 0) return {};
// Append system-reminder to tool result content.
// Reset the baseline so the next reminder fires REMINDER_INTERVAL turns later.
reminderInjectedThisCycle = true;
lastTaskToolUseTurn = currentTurn;
return {
content: [...event.content, { type: "text" as const, text: SYSTEM_REMINDER }],
};
});
// ── Task state in system prompt ──
// Appends current task state to the system prompt on every agent loop.
// Ensures the LLM always has task awareness — especially important after
// context compaction, when prior task tool results may have been dropped.
pi.on("before_agent_start", async (event) => {
const tasks = store.list();
if (tasks.length === 0) return {};
const taskSummary = tasks.map(t => {
let line = `#${t.id} [${t.status}] ${t.subject}`;
if (t.owner) line += ` (${t.owner})`;
if (t.blockedBy.length > 0) {
const openBlockers = t.blockedBy.filter(bid => {
const blocker = store.get(bid);
return blocker && blocker.status !== "completed";
});
if (openBlockers.length > 0) {
line += ` [blocked by ${openBlockers.map(id => "#" + id).join(", ")}]`;
}
}
return line;
}).join("\n");
return {
systemPrompt: event.systemPrompt + `\n\n<task-state>\nCurrent tasks:\n${taskSummary}\n</task-state>`,
};
});
// Grab UI context from first tool execution
pi.on("tool_execution_start", async (_event, ctx) => {
widget.setUICtx(ctx.ui as UICtx);
widget.update();
});
// ──────────────────────────────────────────────────
// Tool 1: TaskCreate
// ──────────────────────────────────────────────────
pi.registerTool({
name: "TaskCreate",
label: "TaskCreate",
description: `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**: Detailed description of what needs to be done, including context and acceptance criteria
- **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
- Include enough detail in the description for another agent to understand and complete the task
- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
- Check TaskList first to avoid creating duplicate tasks`,
promptGuidelines: [
"When working on complex multi-step tasks, use TaskCreate to track progress and TaskUpdate to update status.",
"Mark tasks as in_progress before starting work and completed when done.",
"Use TaskList to check for available work after completing a task.",
],
parameters: Type.Object({
subject: Type.String({ description: "A brief title for the task" }),
description: Type.String({ description: "A detailed description of what needs to be done" }),
activeForm: Type.Optional(Type.String({ description: "Present continuous form shown in spinner when in_progress (e.g., 'Running tests')" })),
metadata: Type.Optional(Type.Record(Type.String(), Type.Any(), { description: "Arbitrary metadata to attach to the task" })),
}),
execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
const task = store.create(params.subject, params.description, params.activeForm, params.metadata);
widget.update();
return Promise.resolve(textResult(`Task #${task.id} created successfully: ${task.subject}`));
},
});
// ──────────────────────────────────────────────────
// Tool 2: TaskList
// ──────────────────────────────────────────────────
pi.registerTool({
name: "TaskList",
label: "TaskList",
description: `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.`,
parameters: Type.Object({}),
execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
const tasks = store.list();
if (tasks.length === 0) return Promise.resolve(textResult("No tasks found"));
// Sort: pending first (by ID), then in_progress (by ID), then completed (by ID)
const statusOrder: Record<string, number> = { pending: 0, in_progress: 1, completed: 2 };
const sorted = [...tasks].sort((a, b) => {
const so = (statusOrder[a.status] ?? 0) - (statusOrder[b.status] ?? 0);
if (so !== 0) return so;
return Number(a.id) - Number(b.id);
});
const lines = sorted.map(task => {
let line = `#${task.id} [${task.status}] ${task.subject}`;
if (task.owner) {
line += ` (${task.owner})`;
}
// Only show non-completed blockers
if (task.blockedBy.length > 0) {
const openBlockers = task.blockedBy.filter(bid => {
const blocker = store.get(bid);
return blocker && blocker.status !== "completed";
});
if (openBlockers.length > 0) {
line += ` [blocked by ${openBlockers.map(id => "#" + id).join(", ")}]`;
}
}
return line;
});
return Promise.resolve(textResult(lines.join("\n")));
},
});
// ──────────────────────────────────────────────────
// Tool 3: TaskGet
// ──────────────────────────────────────────────────
pi.registerTool({
name: "TaskGet",
label: "TaskGet",
description: `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.`,
parameters: Type.Object({
taskId: Type.String({ description: "The ID of the task to retrieve" }),
}),
execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
const task = store.get(params.taskId);
if (!task) return Promise.resolve(textResult(`Task not found`));
// Unescape literal \n sequences the LLM may have double-escaped in JSON
const desc = task.description.replace(/\\n/g, "\n");
const lines: string[] = [
`Task #${task.id}: ${task.subject}`,
`Status: ${task.status}`,
];
if (task.owner) {
lines.push(`Owner: ${task.owner}`);
}
lines.push(`Description: ${desc}`);
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 Promise.resolve(textResult(lines.join("\n")));
},
});
// ──────────────────────────────────────────────────
// Tool 4: TaskUpdate
// ──────────────────────────────────────────────────
pi.registerTool({
name: "TaskUpdate",
label: "TaskUpdate",
description: `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\` → \`in_progress\` → \`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"]}
\`\`\``,
parameters: Type.Object({
taskId: Type.String({ description: "The ID of the task to update" }),
status: Type.Optional(Type.Unsafe<"pending" | "in_progress" | "completed" | "deleted">({
anyOf: [
{ type: "string", enum: ["pending", "in_progress", "completed"] },
{ type: "string", const: "deleted" },
],
description: "New status for the task",
})),
subject: Type.Optional(Type.String({ description: "New subject for the task" })),
description: Type.Optional(Type.String({ description: "New description for the task" })),
activeForm: Type.Optional(Type.String({ description: "Present continuous form shown in spinner when in_progress" })),
owner: Type.Optional(Type.String({ description: "New owner for the task" })),
metadata: Type.Optional(Type.Record(Type.String(), Type.Any(), { description: "Metadata keys to merge into the task. Set a key to null to delete it." })),
addBlocks: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that this task blocks" })),
addBlockedBy: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that block this task" })),
}),
execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
const { taskId, ...fields } = params;
const { task, changedFields, warnings } = store.update(taskId, fields);
if (changedFields.length === 0 && !task) {
return Promise.resolve(textResult(`Task #${taskId} not found`));
}
// Update widget active task tracking
if (fields.status === "in_progress") {
widget.setActiveTask(taskId);
} else if (fields.status === "completed" || fields.status === "deleted") {
widget.setActiveTask(taskId, false);
}
widget.update();
let msg = `Updated task #${taskId} ${changedFields.join(", ")}`;
if (warnings.length > 0) {
msg += ` (warning: ${warnings.join("; ")})`;
}
return Promise.resolve(textResult(msg));
},
});
// ──────────────────────────────────────────────────
// Tool 5: TaskOutput
// ──────────────────────────────────────────────────
pi.registerTool({
name: "TaskOutput",
label: "TaskOutput",
description: `- 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`,
parameters: Type.Object({
task_id: Type.String({ description: "The task ID to get output from" }),
block: Type.Boolean({ description: "Whether to wait for completion", default: true }),
timeout: Type.Number({ description: "Max wait time in ms", default: 30000, minimum: 0, maximum: 600000 }),
}),
async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
const { task_id, block, timeout } = params;
const processOutput = tracker.getOutput(task_id);
if (!processOutput) {
throw new Error(`No background process for task ${task_id}`);
}
if (block && processOutput.status === "running") {
const result = await tracker.waitForCompletion(task_id, timeout ?? 30000, signal ?? undefined);
if (result) {
return textResult(
`Task #${task_id} (${result.status})${result.exitCode !== undefined ? ` exit code: ${result.exitCode}` : ""}\n\n${result.output}`,
);
}
}
return textResult(
`Task #${task_id} (${processOutput.status})${processOutput.exitCode !== undefined ? ` exit code: ${processOutput.exitCode}` : ""}\n\n${processOutput.output}`,
);
},
});
// ──────────────────────────────────────────────────
// Tool 6: TaskStop
// ──────────────────────────────────────────────────
pi.registerTool({
name: "TaskStop",
label: "TaskStop",
description: `
- 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`,
parameters: Type.Object({
task_id: Type.Optional(Type.String({ description: "The ID of the background task to stop" })),
shell_id: Type.Optional(Type.String({ description: "Deprecated: use task_id instead" })),
}),
async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
const taskId = params.task_id ?? params.shell_id;
if (!taskId) throw new Error("task_id is required");
const stopped = await tracker.stop(taskId);
if (!stopped) {
throw new Error(`No running background process for task ${taskId}`);
}
store.update(taskId, { status: "completed" });
widget.setActiveTask(taskId, false);
widget.update();
return textResult(`Task #${taskId} stopped successfully`);
},
});
// ──────────────────────────────────────────────────
// /tasks command
// ──────────────────────────────────────────────────
pi.registerCommand("tasks", {
description: "Manage tasks — view, create, clear completed",
handler: async (_args: string, ctx: ExtensionCommandContext) => {
const ui = ctx.ui;
const mainMenu = async (): Promise<void> => {
const tasks = store.list();
const taskCount = tasks.length;
const completedCount = tasks.filter(t => t.status === "completed").length;
const choices: string[] = [
`View all tasks (${taskCount})`,
"Create task",
];
if (completedCount > 0) choices.push(`Clear completed (${completedCount})`);
const choice = await ui.select("Tasks", choices);
if (!choice) return;
if (choice.startsWith("View")) {
await viewTasks();
} else if (choice === "Create task") {
await createTask();
} else if (choice.startsWith("Clear")) {
store.clearCompleted();
widget.update();
await mainMenu();
}
};
const viewTasks = async (): Promise<void> => {
const tasks = store.list();
if (tasks.length === 0) {
await ui.select("No tasks", ["← Back"]);
return mainMenu();
}
const statusIcon = (status: string) => {
switch (status) {
case "completed": return "✔";
case "in_progress": return "◼";
default: return "◻";
}
};
const choices = tasks.map(t =>
`${statusIcon(t.status)} #${t.id} [${t.status}] ${t.subject}`
);
choices.push("← Back");
const selected = await ui.select("Tasks", choices);
if (!selected || selected === "← Back") return mainMenu();
// Extract task ID from selection
const match = selected.match(/#(\d+)/);
if (match) await viewTaskDetail(match[1]);
else return viewTasks();
};
const viewTaskDetail = async (taskId: string): Promise<void> => {
const task = store.get(taskId);
if (!task) return viewTasks();
const actions: string[] = [];
if (task.status === "pending") {
actions.push("▸ Start (in_progress)");
}
if (task.status === "in_progress") {
actions.push("✓ Complete");
}
actions.push("✗ Delete");
actions.push("← Back");
const title = `#${task.id} [${task.status}] ${task.subject}\n${task.description}`;
const action = await ui.select(title, actions);
if (action === "▸ Start (in_progress)") {
store.update(taskId, { status: "in_progress" });
widget.setActiveTask(taskId);
widget.update();
return viewTasks();
} else if (action === "✓ Complete") {
store.update(taskId, { status: "completed" });
widget.setActiveTask(taskId, false);
widget.update();
return viewTasks();
} else if (action === "✗ Delete") {
store.update(taskId, { status: "deleted" });
widget.setActiveTask(taskId, false);
widget.update();
return viewTasks();
}
return viewTasks();
};
const createTask = async (): Promise<void> => {
const subject = await ui.input("Task subject");
if (!subject) return mainMenu();
const description = await ui.input("Task description");
if (!description) return mainMenu();
store.create(subject, description);
widget.update();
return mainMenu();
};
await mainMenu();
},
});
}