@dex-ai/tasks-extension 0.1.4

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@dex-ai/tasks-extension",
+  "version": "0.1.4",
+  "description": "Task management extension — tools, skill, and UI helpers for structured task tracking.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "skill"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2",
+    "@dex-ai/vue-tui": "^0.1.10",
+    "zod": "^3.23.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: task-management
+description: "Structured task tracking — create, update, reorder, and delete tasks with a real-time info panel. Use for multi-step, parallel, or sequenced work."
+---
+
+## Task Management
+
+The task system provides tools for tracking work items during a session.
+
+### When to Use
+
+- **Breaking a complex task into sequenced steps** — create tasks and mark them `in_progress`/`completed` as you go
+- **Parallel work** — create sibling tasks that can be done independently
+- **Dependency tracking** — use `parentId` to build subtask hierarchies; use `blocked` status for tasks waiting on others
+- **Session handoff** — before switching topics, ensure all tasks are properly statused so context is clear on resume
+
+### Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `task_create` | Create or update tasks. Pass an array of 1..N items; if an item has an `id` that already exists, it's updated. |
+| `task_update` | Change title, description, status, or priority |
+| `task_list` | View all tasks, optionally filtered by status or parent |
+| `task_delete` | Remove a task (optionally cascade to subtasks) |
+| `task_reorder` | Reposition or reparent a task |
+
+### Best Practices
+
+- **Create tasks proactively.** Before starting work, use `task_create` to define all the steps. This gives both you and the user visibility into the plan.
+- **Update status as you go.** Mark a task `in_progress` when starting work on it, `completed` when done, `blocked` if something external is needed.
+- **Upsert via `task_create`.** Pass existing task IDs back in the `tasks` array to update them in the same call as creating new ones.
+- **Use subtasks for breakdowns.** Complex tasks get a parent + children. Parent tracks the overall goal; children are specific implementation steps.
+- **Prioritize with `priority` field.** 0 = highest, 10 = lowest. Use lower numbers for critical-path items.
+- **Use `task_list`** to review current state before making updates.

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @dex-ai/tasks-extension — task management for Dex agents.
+ *
+ * Provides:
+ *   - 5 tools (task_create, task_update, task_list, task_delete, task_reorder)
+ *   - 1 skill (task-management)
+ *   - UI helpers for rendering task panels
+ *   - Shared types for consumers
+ *
+ * Usage:
+ *   import { tasksExtension } from '@dex-ai/tasks-extension';
+ *
+ *   const agent = await Agent.create({
+ *     extensions: [tasksExtension(), ...otherExtensions],
+ *   });
+ */
+
+import type { Extension, Skill } from "@dex-ai/sdk";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	makeCreateTool,
+	makeUpdateTool,
+	makeListTool,
+	makeDeleteTool,
+	makeReorderTool,
+} from "./tools";
+import { createTaskPanel } from "./panel";
+
+// Re-export everything
+export type { Task, TaskStatus, TaskEvent } from "./types";
+export { TASKS_STATE_KEY } from "./types";
+export {
+	computeHeader,
+	computeVisibleItems,
+	statusIcon,
+} from "./ui";
+export type { TaskPanelHeader, TaskPanelItem, TaskPanelList } from "./ui";
+export { createTaskPanel } from "./panel";
+
+/* ------------------------------------------------------------------ */
+/* Skill loader                                                        */
+/* ------------------------------------------------------------------ */
+
+function loadSkillContent(): string {
+	const skillPath = join(import.meta.dir, "..", "skill", "SKILL.md");
+	const raw = readFileSync(skillPath, "utf-8");
+	// Strip YAML frontmatter
+	return raw.replace(/^---[\s\S]*?---\s*/, "");
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Creates the task management extension with tools and skill.
+ */
+export function tasksExtension(): Extension & {
+	panel: ReturnType<typeof createTaskPanel>;
+} {
+	const skill: Skill = {
+		name: "task-management",
+		description:
+			"Structured task tracking — create, update, reorder, and delete tasks with a real-time info panel. Use for multi-step, parallel, or sequenced work.",
+		content: loadSkillContent(),
+	};
+
+	return {
+		name: "tasks",
+		description: "Task management tools for structured multi-step work.",
+		tools: [
+			makeCreateTool(),
+			makeUpdateTool(),
+			makeListTool(),
+			makeDeleteTool(),
+			makeReorderTool(),
+		],
+		skills: [skill],
+		panel: createTaskPanel(),
+	};
+}

package/src/panel.ts

@@ -0,0 +1,110 @@
+/**
+ * Task DynamicPanel — renders the task list in the ActivityPanel zone.
+ *
+ * Uses the WidgetNode/W builder from @dex-ai/vue-tui to produce a
+ * declarative UI tree that the TUI host renders.
+ */
+
+import {
+	W,
+	type WidgetNode,
+	type DynamicPanel,
+	type PanelContext,
+} from "@dex-ai/vue-tui";
+import type { Task } from "./types";
+import { TASKS_STATE_KEY } from "./types";
+import { computeHeader, computeVisibleItems, statusIcon } from "./ui";
+
+/**
+ * Create the tasks DynamicPanel.
+ * Displays active tasks in the activity zone with expand/collapse support.
+ */
+export function createTaskPanel(): DynamicPanel {
+	return {
+		id: "tasks",
+		label: "Tasks",
+		priority: 10, // Higher than default — tasks take precedence
+
+		visible(ctx: PanelContext): boolean {
+			const tasks =
+				(ctx.state.get(TASKS_STATE_KEY) as Task[] | undefined) ?? [];
+			return tasks.length > 0 && !tasks.every((t) => t.status === "completed");
+		},
+
+		render(ctx: PanelContext): WidgetNode | null {
+			const tasks =
+				(ctx.state.get(TASKS_STATE_KEY) as Task[] | undefined) ?? [];
+			if (tasks.length === 0) return null;
+
+			const header = computeHeader(tasks);
+			const expanded = ctx.state.get("tasks:expanded") !== false;
+
+			const children: WidgetNode[] = [];
+
+			// Header line: ● Current task - N/M complete  (ctrl+t)
+			if (header.allDone) {
+				children.push(
+					W.line([W.text("✓ all tasks complete", { color: "accent" })]),
+				);
+			} else {
+				children.push(
+					W.line([
+						W.text("●", { color: "accent" }),
+						W.text(` ${header.currentTitle}`, { color: "accent" }),
+						W.text(` - ${header.doneCount}/${header.totalCount} complete`, {
+							color: "accent",
+						}),
+						W.text("  (ctrl+t)", { dim: true }),
+					]),
+				);
+			}
+
+			// Expanded item list
+			if (expanded && !header.allDone) {
+				const { items, useCompact } = computeVisibleItems(tasks);
+				const doneCount = header.doneCount;
+
+				// Separator
+				children.push(
+					W.line([
+						W.text(
+							"- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -",
+							{ dim: true },
+						),
+					]),
+				);
+
+				// Compact mode: show done count
+				if (useCompact && doneCount > 0) {
+					children.push(
+						W.line([W.text(`  ✓ ${doneCount} done`, { dim: true })]),
+					);
+				}
+
+				// Task items
+				for (const item of items) {
+					const icon = statusIcon(item.task.status);
+					const isActive = item.task.status === "in_progress";
+					const isDone = item.task.status === "completed";
+					const isFailed = item.task.status === "failed";
+					const isBlocked = item.task.status === "blocked";
+
+					const titleText = item.task.title + (isBlocked ? " (blocked)" : "");
+					const dim = isDone || item.task.status === "pending" || isFailed;
+
+					children.push(
+						W.line([
+							W.text(
+								" ".repeat(item.indent) + icon,
+								isActive ? { color: "accent" } : { dim: true },
+							),
+							W.text(` ${titleText}`, dim ? { dim: true } : {}),
+						]),
+					);
+				}
+			}
+
+			return W.stack(children);
+		},
+	};
+}

package/src/tasks.test.ts

@@ -0,0 +1,386 @@
+/**
+ * Tests for the task management tools.
+ *
+ * We test the tool execute() functions directly by constructing a minimal
+ * GenerateContext with an agent context that has a Map for state.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { tasksExtension } from "./index";
+
+/* ------------------------------------------------------------------ */
+/* Helpers: minimal context mocks                                     */
+/* ------------------------------------------------------------------ */
+
+function mockGctx(state?: Map<string, unknown>) {
+	const agentState = state ?? new Map<string, unknown>();
+	return {
+		agent: {
+			state: agentState,
+		} as any,
+		state: new Map<string, unknown>(),
+		signal: undefined,
+		usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+		stepCount: 0,
+		maxSteps: 10,
+		content: [],
+	} as any;
+}
+
+/* ------------------------------------------------------------------ */
+/* Setup                                                              */
+/* ------------------------------------------------------------------ */
+
+let ext: ReturnType<typeof tasksExtension>;
+
+beforeEach(() => {
+	ext = tasksExtension();
+});
+
+function tool(name: string) {
+	return (ext.tools! as any[]).find((t: any) => t.name === name)!;
+}
+
+/* ------------------------------------------------------------------ */
+/* Tests: task_create (create + upsert)                               */
+/* ------------------------------------------------------------------ */
+
+describe("task_create", () => {
+	it("creates a single task", () => {
+		const t = tool("task_create");
+		const gctx = mockGctx();
+		const result = t.execute({ tasks: [{ title: "Write tests" }] }, gctx);
+		expect(result).toContain("Created 1");
+		expect(result).toContain("Write tests");
+
+		const tasks = gctx.agent.state.get("tasks") as any[];
+		expect(tasks).toHaveLength(1);
+		expect(tasks[0].title).toBe("Write tests");
+		expect(tasks[0].status).toBe("pending");
+		expect(tasks[0].priority).toBe(5);
+	});
+
+	it("creates multiple tasks", () => {
+		const t = tool("task_create");
+		const gctx = mockGctx();
+		const result = t.execute(
+			{
+				tasks: [
+					{ title: "Task A" },
+					{ title: "Task B", status: "in_progress" },
+					{ title: "Task C", priority: 1 },
+				],
+			},
+			gctx,
+		);
+		expect(result).toContain("Created 3");
+		const tasks = gctx.agent.state.get("tasks") as any[];
+		expect(tasks).toHaveLength(3);
+		expect(tasks[0].title).toBe("Task A");
+		expect(tasks[1].status).toBe("in_progress");
+		expect(tasks[2].priority).toBe(1);
+	});
+
+	it("generates unique IDs", () => {
+		const t = tool("task_create");
+		const gctx = mockGctx();
+		t.execute({ tasks: [{ title: "X" }, { title: "Y" }] }, gctx);
+		const tasks = gctx.agent.state.get("tasks") as any[];
+		expect(tasks[0].id).not.toBe(tasks[1].id);
+	});
+
+	it("updates existing task when id matches", () => {
+		const t = tool("task_create");
+		const gctx = mockGctx();
+		t.execute({ tasks: [{ title: "Original" }] }, gctx);
+		const [task] = gctx.agent.state.get("tasks") as any[];
+
+		const result = t.execute(
+			{ tasks: [{ id: task.id, title: "Updated", status: "completed" }] },
+			gctx,
+		);
+		expect(result).toContain("Updated 1");
+
+		const tasks = gctx.agent.state.get("tasks") as any[];
+		expect(tasks).toHaveLength(1);
+		expect(tasks[0].title).toBe("Updated");
+		expect(tasks[0].status).toBe("completed");
+	});
+
+	it("handles mixed create and update in one call", () => {
+		const t = tool("task_create");
+		const gctx = mockGctx();
+		t.execute({ tasks: [{ title: "Existing" }] }, gctx);
+		const [existing] = gctx.agent.state.get("tasks") as any[];
+
+		const result = t.execute(
+			{
+				tasks: [
+					{ id: existing.id, title: "Existing (done)", status: "completed" },
+					{ title: "Brand New" },
+				],
+			},
+			gctx,
+		);
+		expect(result).toContain("Created 1");
+		expect(result).toContain("Updated 1");
+
+		const tasks = gctx.agent.state.get("tasks") as any[];
+		expect(tasks).toHaveLength(2);
+		expect(tasks[0].title).toBe("Existing (done)");
+		expect(tasks[1].title).toBe("Brand New");
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Tests: task_update                                                 */
+/* ------------------------------------------------------------------ */
+
+describe("task_update", () => {
+	it("updates task fields", () => {
+		const t = tool("task_create");
+		const u = tool("task_update");
+		const gctx = mockGctx();
+		t.execute({ tasks: [{ title: "Original" }] }, gctx);
+		const [task] = gctx.agent.state.get("tasks") as any[];
+
+		const result = u.execute(
+			{
+				taskId: task.id,
+				title: "Updated",
+				status: "completed",
+				priority: 1,
+			},
+			gctx,
+		);
+		expect(result).toContain("Updated");
+		expect(result).toContain("completed");
+
+		const tasks = gctx.agent.state.get("tasks") as any[];
+		expect(tasks[0].title).toBe("Updated");
+		expect(tasks[0].status).toBe("completed");
+		expect(tasks[0].priority).toBe(1);
+	});
+
+	it("returns error for unknown task", () => {
+		const u = tool("task_update");
+		const result = u.execute({ taskId: "nonexistent" }, mockGctx());
+		expect(result).toContain("Error");
+		expect(result).toContain("not found");
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Tests: task_list                                                   */
+/* ------------------------------------------------------------------ */
+
+describe("task_list", () => {
+	it("returns 'no tasks' when empty", () => {
+		const l = tool("task_list");
+		const result = l.execute({}, mockGctx());
+		expect(result).toContain("No tasks");
+	});
+
+	it("lists tasks grouped by status", () => {
+		const c = tool("task_create");
+		const l = tool("task_list");
+		const gctx = mockGctx();
+		c.execute(
+			{
+				tasks: [
+					{ title: "Task A", status: "completed" },
+					{ title: "Task B", status: "in_progress" },
+					{ title: "Task C", status: "pending" },
+				],
+			},
+			gctx,
+		);
+
+		const result = l.execute({}, gctx);
+		expect(result).toContain("IN PROGRESS");
+		expect(result).toContain("PENDING");
+		expect(result).toContain("COMPLETED");
+		expect(result).toContain("Task A");
+		expect(result).toContain("Task B");
+		expect(result).toContain("Task C");
+	});
+
+	it("filters by status", () => {
+		const c = tool("task_create");
+		const l = tool("task_list");
+		const gctx = mockGctx();
+		c.execute(
+			{
+				tasks: [
+					{ title: "One", status: "completed" },
+					{ title: "Two", status: "pending" },
+				],
+			},
+			gctx,
+		);
+		const result = l.execute({ status: "completed" }, gctx);
+		expect(result).toContain("One");
+		expect(result).not.toContain("Two");
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Tests: task_delete                                                 */
+/* ------------------------------------------------------------------ */
+
+describe("task_delete", () => {
+	it("deletes a single task", () => {
+		const c = tool("task_create");
+		const d = tool("task_delete");
+		const gctx = mockGctx();
+		c.execute({ tasks: [{ title: "Delete me" }] }, gctx);
+		const [task] = gctx.agent.state.get("tasks") as any[];
+
+		const result = d.execute({ taskId: task.id }, gctx);
+		expect(result).toContain("Deleted 1 task(s)");
+		expect(gctx.agent.state.get("tasks")).toHaveLength(0);
+	});
+
+	it("cascade deletes subtasks", () => {
+		const c = tool("task_create");
+		const d = tool("task_delete");
+		const gctx = mockGctx();
+		c.execute({ tasks: [{ title: "Parent" }] }, gctx);
+		const [parent] = gctx.agent.state.get("tasks") as any[];
+		c.execute({ tasks: [{ title: "Child", parentId: parent.id }] }, gctx);
+
+		const result = d.execute({ taskId: parent.id, cascade: true }, gctx);
+		expect(result).toContain("Deleted 2 task(s)");
+		expect(gctx.agent.state.get("tasks")).toHaveLength(0);
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Tests: task_reorder                                                */
+/* ------------------------------------------------------------------ */
+
+describe("task_reorder", () => {
+	it("moves a task after another", () => {
+		const c = tool("task_create");
+		const r = tool("task_reorder");
+		const gctx = mockGctx();
+		c.execute(
+			{ tasks: [{ title: "A" }, { title: "B" }, { title: "C" }] },
+			gctx,
+		);
+		const tasks = gctx.agent.state.get("tasks") as any[];
+
+		const result = r.execute(
+			{ taskId: tasks[2].id, afterId: tasks[0].id },
+			gctx,
+		);
+		expect(result).toContain("Moved");
+
+		const reordered = gctx.agent.state.get("tasks") as any[];
+		expect(reordered[0].title).toBe("A");
+		expect(reordered[1].title).toBe("C");
+		expect(reordered[2].title).toBe("B");
+	});
+});
+
+/* ------------------------------------------------------------------ */
+/* Tests: UI helpers                                                  */
+/* ------------------------------------------------------------------ */
+
+import { computeHeader, computeVisibleItems, statusIcon } from "./ui";
+import type { Task } from "./types";
+
+function makeTask(overrides: Partial<Task> = {}): Task {
+	return {
+		id: "t1",
+		title: "Test task",
+		description: "",
+		status: "pending",
+		priority: 5,
+		parentId: null,
+		position: 0,
+		createdAt: 0,
+		updatedAt: 0,
+		...overrides,
+	};
+}
+
+describe("computeHeader", () => {
+	it("shows current in_progress task", () => {
+		const tasks = [
+			makeTask({
+				id: "t1",
+				title: "First",
+				status: "completed",
+				position: 0,
+			}),
+			makeTask({
+				id: "t2",
+				title: "Active",
+				status: "in_progress",
+				position: 1,
+			}),
+			makeTask({ id: "t3", title: "Later", status: "pending", position: 2 }),
+		];
+		const header = computeHeader(tasks);
+		expect(header.currentTitle).toBe("Active");
+		expect(header.doneCount).toBe(1);
+		expect(header.totalCount).toBe(3);
+		expect(header.allDone).toBe(false);
+	});
+
+	it("shows first pending when none in_progress", () => {
+		const tasks = [
+			makeTask({ id: "t1", title: "A", status: "pending", position: 0 }),
+			makeTask({ id: "t2", title: "B", status: "pending", position: 1 }),
+		];
+		const header = computeHeader(tasks);
+		expect(header.currentTitle).toBe("A");
+	});
+
+	it("shows allDone when all completed", () => {
+		const tasks = [
+			makeTask({ id: "t1", status: "completed", position: 0 }),
+			makeTask({ id: "t2", status: "completed", position: 1 }),
+		];
+		const header = computeHeader(tasks);
+		expect(header.allDone).toBe(true);
+		expect(header.doneCount).toBe(2);
+	});
+});
+
+describe("computeVisibleItems", () => {
+	it("returns root tasks with children indented", () => {
+		const tasks = [
+			makeTask({ id: "p1", title: "Parent", position: 0 }),
+			makeTask({ id: "c1", title: "Child", position: 1, parentId: "p1" }),
+		];
+		const { items } = computeVisibleItems(tasks);
+		expect(items).toHaveLength(2);
+		expect(items[0]!.indent).toBe(2);
+		expect(items[1]!.indent).toBe(4);
+	});
+
+	it("collapses completed in compact mode (>6 roots)", () => {
+		const tasks = Array.from({ length: 8 }, (_, i) =>
+			makeTask({
+				id: `t${i}`,
+				title: `Task ${i}`,
+				status: i < 3 ? "completed" : "pending",
+				position: i,
+			}),
+		);
+		const { useCompact, items } = computeVisibleItems(tasks);
+		expect(useCompact).toBe(true);
+		expect(items).toHaveLength(5);
+	});
+});
+
+describe("statusIcon", () => {
+	it("returns correct icons", () => {
+		expect(statusIcon("in_progress")).toBe("●");
+		expect(statusIcon("completed")).toBe("✓");
+		expect(statusIcon("failed")).toBe("x");
+		expect(statusIcon("pending")).toBe("○");
+		expect(statusIcon("blocked")).toBe("○");
+	});
+});

package/src/tools.ts

@@ -0,0 +1,429 @@
+/**
+ * Task Management Tools — create, update, list, delete, reorder tasks.
+ *
+ * Uses Zod schemas (same pattern as bash/read/write/edit tools) for:
+ * - Compile-time type inference
+ * - Runtime input validation
+ * - Proper JSON Schema generation via zod-to-json-schema
+ */
+
+import type { GenerateContext } from "@dex-ai/sdk";
+import type { AnyTool, ToolOutput } from "@dex-ai/sdk";
+import { z } from "zod";
+import type { Task, TaskStatus } from "./types";
+
+/* ------------------------------------------------------------------ */
+/* State helpers                                                       */
+/* ------------------------------------------------------------------ */
+
+const STATE_KEY = "tasks";
+
+function getTasks(gctx: GenerateContext): Task[] {
+	return (gctx.agent.state.get(STATE_KEY) as Task[]) ?? [];
+}
+
+function setTasks(gctx: GenerateContext, tasks: Task[]): void {
+	// Always set a new array reference so reactive UI frameworks detect the change
+	gctx.agent.state.set(STATE_KEY, [...tasks]);
+}
+
+let taskIdCounter = 0;
+function nextId(): string {
+	return `task_${++taskIdCounter}`;
+}
+
+/* ------------------------------------------------------------------ */
+/* Shared enums                                                       */
+/* ------------------------------------------------------------------ */
+
+const statusEnum = z.enum([
+	"pending",
+	"in_progress",
+	"completed",
+	"failed",
+	"blocked",
+]);
+
+/* ------------------------------------------------------------------ */
+/* Tool: task_create                                                  */
+/* ------------------------------------------------------------------ */
+
+const createParams = z.object({
+	tasks: z
+		.array(
+			z.object({
+				id: z
+					.string()
+					.optional()
+					.describe(
+						"Task ID. If provided and exists, the task is updated instead of created.",
+					),
+				title: z.string().min(1).describe("Task title"),
+				description: z.string().optional().describe("Optional description"),
+				status: statusEnum.optional(),
+				priority: z
+					.number()
+					.int()
+					.min(0)
+					.max(10)
+					.optional()
+					.describe("Priority 0-10 (0 = highest)"),
+				parentId: z.string().optional().describe("Parent task ID for subtasks"),
+			}),
+		)
+		.min(1)
+		.max(100)
+		.describe(
+			"Tasks to create or update. If an id matches an existing task, it is updated.",
+		),
+});
+
+type CreateParams = z.infer<typeof createParams>;
+
+export function makeCreateTool(): AnyTool {
+	return {
+		name: "task_create",
+		displayName: "Create Tasks",
+		visible: false,
+		description:
+			"Create one or more tasks. In 'single' mode returns the created task ID; in 'bulk' mode returns a summary. Use this to break work into manageable units.",
+		access: "write",
+		parameters: createParams,
+		execute(input: CreateParams, gctx) {
+			const existing = getTasks(gctx);
+			const created: Task[] = [];
+			const updated: Task[] = [];
+			const now = Date.now();
+			let maxPos = existing.reduce(
+				(m, t) => Math.max(m, t.position),
+				existing.length,
+			);
+
+			for (const t of input.tasks) {
+				// If id provided and exists, update in place
+				const existingIdx = t.id
+					? existing.findIndex((e) => e.id === t.id)
+					: -1;
+
+				if (existingIdx !== -1) {
+					const task = { ...existing[existingIdx]! };
+					task.title = t.title;
+					if (t.description !== undefined) task.description = t.description;
+					if (t.status !== undefined) task.status = t.status as TaskStatus;
+					if (t.priority !== undefined) task.priority = t.priority;
+					if (t.parentId !== undefined) task.parentId = t.parentId;
+					task.updatedAt = now;
+					existing[existingIdx] = task;
+					updated.push(task);
+				} else {
+					maxPos++;
+					const task: Task = {
+						id: t.id ?? nextId(),
+						title: t.title,
+						description: t.description ?? "",
+						status: (t.status as TaskStatus) ?? "pending",
+						priority: t.priority ?? 5,
+						parentId: t.parentId ?? null,
+						position: maxPos,
+						createdAt: now,
+						updatedAt: now,
+					};
+					created.push(task);
+					existing.push(task);
+				}
+			}
+
+			setTasks(gctx, existing);
+
+			const parts: string[] = [];
+			if (created.length) {
+				parts.push(
+					`Created ${created.length}: ${created.map((t) => `${t.id} "${t.title}"`).join(", ")}`,
+				);
+			}
+			if (updated.length) {
+				parts.push(
+					`Updated ${updated.length}: ${updated.map((t) => `${t.id} "${t.title}"`).join(", ")}`,
+				);
+			}
+			return parts.join(". ");
+		},
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool: task_update                                                  */
+/* ------------------------------------------------------------------ */
+
+const updateParams = z.object({
+	taskId: z.string().min(1).describe("ID of the task to update"),
+	title: z.string().min(1).optional().describe("New title"),
+	description: z.string().optional().describe("New description"),
+	status: statusEnum.optional().describe("New status"),
+	priority: z
+		.number()
+		.int()
+		.min(0)
+		.max(10)
+		.optional()
+		.describe("New priority 0-10"),
+});
+
+type UpdateParams = z.infer<typeof updateParams>;
+
+export function makeUpdateTool(): AnyTool {
+	return {
+		name: "task_update",
+		displayName: "Update Task",
+		visible: false,
+		description:
+			"Update one or more fields of an existing task (title, description, status, priority). Returns the updated task summary.",
+		access: "write",
+		parameters: updateParams,
+		execute(input: UpdateParams, gctx) {
+			const existing = getTasks(gctx);
+			const idx = existing.findIndex((t) => t.id === input.taskId);
+			if (idx === -1) {
+				return `Error: task "${input.taskId}" not found. Use task_list to see available tasks.`;
+			}
+
+			const task = { ...existing[idx]! };
+			const now = Date.now();
+			let changed = false;
+
+			if (input.title !== undefined) {
+				task.title = input.title;
+				changed = true;
+			}
+			if (input.description !== undefined) {
+				task.description = input.description;
+				changed = true;
+			}
+			if (input.status !== undefined) {
+				task.status = input.status as TaskStatus;
+				changed = true;
+			}
+			if (input.priority !== undefined) {
+				task.priority = input.priority;
+				changed = true;
+			}
+
+			if (changed) {
+				task.updatedAt = now;
+				existing[idx] = task;
+				setTasks(gctx, existing);
+			}
+
+			return `Updated ${task.id} — "${task.title}" [${task.status}]`;
+		},
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool: task_list                                                    */
+/* ------------------------------------------------------------------ */
+
+const listParams = z.object({
+	status: statusEnum.optional().describe("Filter by status"),
+	parentId: z
+		.string()
+		.optional()
+		.describe("Filter by parent. Use null for root tasks only, omit for all."),
+});
+
+type ListParams = z.infer<typeof listParams>;
+
+export function makeListTool(): AnyTool {
+	return {
+		name: "task_list",
+		displayName: "List Tasks",
+		visible: false,
+		description:
+			"List all tasks, optionally filtered by status or parent. Returns a formatted task board grouped by status.",
+		access: "read",
+		parameters: listParams,
+		execute(input: ListParams, gctx) {
+			const all = getTasks(gctx);
+			if (all.length === 0) {
+				return "No tasks created yet. Use task_create to add tasks.";
+			}
+
+			let filtered = [...all];
+
+			if (input.status) {
+				filtered = filtered.filter((t) => t.status === input.status);
+			}
+
+			if (input.parentId !== undefined) {
+				filtered = filtered.filter((t) => t.parentId === input.parentId);
+			}
+
+			// Sort by status group then position
+			const statusOrder: Record<TaskStatus, number> = {
+				in_progress: 0,
+				blocked: 1,
+				pending: 2,
+				completed: 3,
+				failed: 4,
+			};
+
+			filtered.sort(
+				(a, b) =>
+					(statusOrder[a.status] ?? 99) - (statusOrder[b.status] ?? 99) ||
+					a.position - b.position,
+			);
+
+			const lines: string[] = [];
+			let currentStatus: TaskStatus | null = null;
+
+			for (const task of filtered) {
+				if (task.status !== currentStatus) {
+					currentStatus = task.status;
+					const label =
+						task.status === "in_progress"
+							? "▶ IN PROGRESS"
+							: task.status === "pending"
+								? "○ PENDING"
+								: task.status === "completed"
+									? "✓ COMPLETED"
+									: task.status === "blocked"
+										? "⚠ BLOCKED"
+										: "✗ FAILED";
+					lines.push(`\n── ${label} ──`);
+				}
+				const parent = task.parentId ? ` [subtask of ${task.parentId}]` : "";
+				const prio = task.priority < 5 ? " ⚡" : "";
+				lines.push(
+					`  ${task.id}: ${task.title}${prio}${parent} — ${task.description || "(no description)"}`,
+				);
+			}
+
+			if (lines.length === 0) {
+				return "No tasks match the filter.";
+			}
+
+			return lines.join("\n");
+		},
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool: task_delete                                                  */
+/* ------------------------------------------------------------------ */
+
+const deleteParams = z.object({
+	taskId: z.string().min(1).describe("ID of the task to delete"),
+	cascade: z.boolean().optional().describe("Also delete all subtasks"),
+});
+
+type DeleteParams = z.infer<typeof deleteParams>;
+
+export function makeDeleteTool(): AnyTool {
+	return {
+		name: "task_delete",
+		displayName: "Delete Task",
+		visible: false,
+		description:
+			"Delete a task by ID. Use cascade=true to also delete all subtasks.",
+		access: "write",
+		parameters: deleteParams,
+		execute(input: DeleteParams, gctx) {
+			const existing = getTasks(gctx);
+			const idx = existing.findIndex((t) => t.id === input.taskId);
+			if (idx === -1) {
+				return `Error: task "${input.taskId}" not found.`;
+			}
+
+			const toRemove = new Set<string>([input.taskId]);
+
+			if (input.cascade) {
+				// Collect all descendants
+				const children = existing.filter((t) => t.parentId === input.taskId);
+				for (const child of children) {
+					toRemove.add(child.id);
+					const grandchildren = existing.filter((t) => t.parentId === child.id);
+					for (const gc of grandchildren) toRemove.add(gc.id);
+				}
+			}
+
+			const removed: Task[] = [];
+			const remaining = existing.filter((t) => {
+				if (toRemove.has(t.id)) {
+					removed.push(t);
+					return false;
+				}
+				return true;
+			});
+
+			setTasks(gctx, remaining);
+
+			return `Deleted ${removed.length} task(s): ${removed.map((t) => `${t.id} — "${t.title}"`).join(", ")}`;
+		},
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool: task_reorder                                                 */
+/* ------------------------------------------------------------------ */
+
+const reorderParams = z.object({
+	taskId: z.string().min(1).describe("ID of the task to move"),
+	afterId: z
+		.string()
+		.optional()
+		.describe("Place after this task ID. Omit to move to end."),
+	newParentId: z
+		.string()
+		.optional()
+		.describe("Move under a different parent (omit to keep current)."),
+});
+
+type ReorderParams = z.infer<typeof reorderParams>;
+
+export function makeReorderTool(): AnyTool {
+	return {
+		name: "task_reorder",
+		displayName: "Reorder Task",
+		visible: false,
+		description:
+			"Change a task's position and/or parent. Use afterId to place after a specific task, newParentId to reparent.",
+		access: "write",
+		parameters: reorderParams,
+		execute(input: ReorderParams, gctx) {
+			const existing = getTasks(gctx);
+			const taskIdx = existing.findIndex((t) => t.id === input.taskId);
+			if (taskIdx === -1) {
+				return `Error: task "${input.taskId}" not found.`;
+			}
+
+			const task = { ...existing[taskIdx]! };
+
+			// Update parent if provided
+			if (input.newParentId !== undefined) {
+				task.parentId = input.newParentId;
+			}
+
+			// Remove from current position
+			const without = existing.filter((t) => t.id !== input.taskId);
+
+			// Find insertion point
+			let insertAt = without.length; // end by default
+			if (input.afterId) {
+				const afterIdx = without.findIndex((t) => t.id === input.afterId);
+				if (afterIdx !== -1) {
+					insertAt = afterIdx + 1;
+				}
+			}
+
+			without.splice(insertAt, 0, task);
+
+			// Reassign positions
+			const reindexed = without.map((t, i) => ({ ...t, position: i }));
+			task.updatedAt = Date.now();
+
+			setTasks(gctx, reindexed);
+
+			return `Moved "${task.title}" to position ${insertAt + 1}${task.parentId ? ` under "${task.parentId}"` : ""}`;
+		},
+	};
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Task types — shared between tools, skill, and UI components.
+ */
+
+export type TaskStatus =
+	| "pending"
+	| "in_progress"
+	| "completed"
+	| "failed"
+	| "blocked";
+
+export interface Task {
+	id: string;
+	title: string;
+	description: string;
+	status: TaskStatus;
+	priority: number; // 0 = highest
+	parentId: string | null;
+	position: number;
+	createdAt: number;
+	updatedAt: number;
+}
+
+export interface TaskEvent {
+	type: "task-created" | "task-updated" | "task-deleted" | "task-reordered";
+	tasks: Task[];
+}
+
+/**
+ * The state key used to store tasks in agent.state.
+ * UI components should read from `agent.state.get(TASKS_STATE_KEY)`.
+ */
+export const TASKS_STATE_KEY = "tasks";

package/src/ui.ts

@@ -0,0 +1,108 @@
+/**
+ * Task panel UI helpers — pure logic for rendering the ActivityPanel.
+ *
+ * These functions compute what to display without any framework dependency.
+ * The Vue component (or any other renderer) calls these to get display data.
+ */
+
+import type { Task, TaskStatus } from "./types";
+
+/* ------------------------------------------------------------------ */
+/* Panel item for expanded list                                       */
+/* ------------------------------------------------------------------ */
+
+export interface TaskPanelItem {
+	task: Task;
+	indent: number;
+}
+
+/* ------------------------------------------------------------------ */
+/* Header computation                                                 */
+/* ------------------------------------------------------------------ */
+
+export interface TaskPanelHeader {
+	allDone: boolean;
+	currentTitle: string;
+	doneCount: number;
+	totalCount: number;
+}
+
+/**
+ * Compute the header line data for the tasks panel.
+ */
+export function computeHeader(tasks: Task[]): TaskPanelHeader {
+	const doneCount = tasks.filter((t) => t.status === "completed").length;
+	const totalCount = tasks.length;
+	const allDone = doneCount === totalCount && totalCount > 0;
+
+	const sorted = [...tasks].sort((a, b) => a.position - b.position);
+	const current =
+		sorted.find((t) => t.status === "in_progress") ??
+		sorted.find((t) => t.status === "pending");
+
+	return {
+		allDone,
+		currentTitle: current?.title ?? "",
+		doneCount,
+		totalCount,
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Expanded list computation                                          */
+/* ------------------------------------------------------------------ */
+
+const COMPACT_THRESHOLD = 6;
+
+export interface TaskPanelList {
+	useCompact: boolean;
+	items: TaskPanelItem[];
+}
+
+/**
+ * Compute the visible items for the expanded task list.
+ * In compact mode (>6 root tasks), completed tasks are collapsed.
+ */
+export function computeVisibleItems(tasks: Task[]): TaskPanelList {
+	const sorted = [...tasks].sort((a, b) => a.position - b.position);
+	const roots = sorted.filter((t) => !t.parentId);
+	const useCompact = roots.length > COMPACT_THRESHOLD;
+	const items: TaskPanelItem[] = [];
+
+	for (const root of roots) {
+		if (useCompact && root.status === "completed") continue;
+
+		items.push({ task: root, indent: 2 });
+
+		// Subtasks
+		const children = sorted.filter((t) => t.parentId === root.id);
+		for (const child of children) {
+			if (useCompact && child.status === "completed") continue;
+			items.push({ task: child, indent: 4 });
+		}
+	}
+
+	return { useCompact, items };
+}
+
+/* ------------------------------------------------------------------ */
+/* Status icon helper                                                 */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Returns the display icon for a given task status.
+ */
+export function statusIcon(status: TaskStatus): string {
+	switch (status) {
+		case "in_progress":
+			return "●";
+		case "completed":
+			return "✓";
+		case "failed":
+			return "x";
+		case "pending":
+		case "blocked":
+		default:
+			return "○";
+	}
+}