@bumpyclock/pi-tasque 0.1.0 → 0.2.1

package/src/durable-tasks/task-schema.ts

@@ -0,0 +1,193 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+import { BULK_ITEM_ACTIONS } from "./bulk-contract.js";
+
+export const TASK_TOOL_NAME = "task";
+
+export const TASK_ACTIONS = [
+	"doctor",
+	"find",
+	"show",
+	"deps",
+	"notes",
+	"similar",
+	"create",
+	"note",
+	"finish",
+	"reopen",
+	"defer",
+	"start",
+	"claim",
+	"block",
+	"unblock",
+	"order",
+	"unorder",
+	"spec",
+	"mark_planned",
+	"bulk",
+	"create_tree",
+	"handoff_check",
+	"link",
+	"list_links",
+	"promote",
+	"import",
+] as const;
+
+export const FIND_TARGETS = ["ready", "open"] as const;
+export const VIEW_MODES = ["list", "tree"] as const;
+export const SPEC_MODES = ["show", "check", "set", "update"] as const;
+export const BRIDGE_DESTINATIONS = ["todo"] as const;
+
+export type TaskAction = (typeof TASK_ACTIONS)[number];
+
+const BulkItemParamsSchema = Type.Object({
+	action: StringEnum(BULK_ITEM_ACTIONS, {
+		description:
+			"Bulk item action: start, finish, reopen, defer, note, or mark_planned.",
+	}),
+	task: Type.String({ description: "Durable task id for this bulk item." }),
+	because: Type.Optional(
+		Type.String({
+			description:
+				"Note/reason text. Required for note; optional for finish/defer.",
+		}),
+	),
+});
+
+const CreateTreeNodeParamsSchema = Type.Object({
+	title: Type.String({ description: "Durable task title for this node." }),
+	kind: Type.String({ description: "Durable task kind for this node." }),
+	priority: Type.Integer({
+		description: "Durable task priority for this node.",
+	}),
+	description: Type.Optional(
+		Type.String({ description: "Task description for this node." }),
+	),
+	planned: Type.Optional(
+		Type.Boolean({ description: "Mark this node planned." }),
+	),
+	needsPlan: Type.Optional(
+		Type.Boolean({ description: "Mark this node as needing planning." }),
+	),
+	children: Type.Optional(
+		Type.Array(
+			Type.Unknown({
+				description:
+					"Child create-tree nodes with the same shape: { title, kind, priority, description?, planned?, needsPlan?, children? }.",
+			}),
+			{ description: "Nested child task nodes." },
+		),
+	),
+});
+
+export const TaskParamsSchema = Type.Object(
+	{
+		action: StringEnum(TASK_ACTIONS, {
+			description: "Durable task action to run.",
+		}),
+		task: Type.Optional(
+			Type.String({
+				description: "Durable task id for existing tasks, or title for create.",
+			}),
+		),
+		tasks: Type.Optional(
+			StringEnum(FIND_TARGETS, {
+				description: "Task set for find actions.",
+			}),
+		),
+		view: Type.Optional(
+			StringEnum(VIEW_MODES, {
+				description: "Find output view.",
+			}),
+		),
+		lane: Type.Optional(
+			Type.String({ description: "Ready-task lane, e.g. planning or coding." }),
+		),
+		for: Type.Optional(
+			Type.String({ description: "Assignee or owner for claim/find/import." }),
+		),
+		query: Type.Optional(
+			Type.String({ description: "Search text for similar task lookup." }),
+		),
+		with: Type.Optional(
+			Type.Array(
+				Type.String({ description: "Extra context to include, e.g. spec." }),
+			),
+		),
+		kind: Type.Optional(Type.String({ description: "Durable task kind." })),
+		priority: Type.Optional(
+			Type.Integer({ description: "Durable task priority." }),
+		),
+		description: Type.Optional(
+			Type.String({ description: "Task description for create/promote." }),
+		),
+		under: Type.Optional(
+			Type.String({
+				description: "Parent durable task id for create/promote.",
+			}),
+		),
+		planned: Type.Optional(
+			Type.Boolean({ description: "Mark created/promoted task planned." }),
+		),
+		needsPlan: Type.Optional(
+			Type.Boolean({
+				description: "Mark created/promoted task as needing planning.",
+			}),
+		),
+		because: Type.Optional(
+			Type.String({
+				description: "Note or reason text for lifecycle actions.",
+			}),
+		),
+		by: Type.Optional(
+			Type.String({
+				description: "Blocking durable task id for block/unblock.",
+			}),
+		),
+		after: Type.Optional(
+			Type.String({
+				description: "Earlier durable task id for order/unorder.",
+			}),
+		),
+		start: Type.Optional(
+			Type.Boolean({
+				description: "Start task while claiming. Defaults true.",
+			}),
+		),
+		requireSpec: Type.Optional(
+			Type.Boolean({ description: "Require an attached spec before claim." }),
+		),
+		todo: Type.Optional(
+			Type.Union([
+				Type.Boolean({ description: "Create a linked todo for claim." }),
+				Type.Integer({ description: "Session todo id for link/promote." }),
+			]),
+		),
+		mode: Type.Optional(
+			StringEnum(SPEC_MODES, {
+				description: "Spec operation mode for spec action.",
+			}),
+		),
+		text: Type.Optional(
+			Type.String({
+				description: "Spec text content for spec set/update.",
+			}),
+		),
+		to: Type.Optional(
+			StringEnum(BRIDGE_DESTINATIONS, {
+				description: "Bridge destination for import.",
+			}),
+		),
+		items: Type.Optional(
+			Type.Array(BulkItemParamsSchema, {
+				description:
+					"Bulk lifecycle items. Each item has { action, task, because? }.",
+				minItems: 1,
+			}),
+		),
+		root: Type.Optional(CreateTreeNodeParamsSchema),
+	},
+	{ additionalProperties: false },
+);
+
+export type TaskParams = Static<typeof TaskParamsSchema>;

package/src/durable-tasks/task-tool.ts

@@ -0,0 +1,197 @@
+import {
+	defineTool,
+	type AgentToolResult,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { executeTaskBridge } from "../bridge/bridge-tool.js";
+import type { TaskBridgeHandlers } from "../bridge/types.js";
+import {
+	TASK_PROMPT_GUIDELINES,
+	TASK_PROMPT_SNIPPET,
+} from "../guidelines/task.js";
+import { isRecord } from "../shared/error-utils.js";
+import { errorToolDetails, textToolResult } from "../shared/tool-result.js";
+import { importTsqHandler } from "../bridge/import-tsq.js";
+import { promoteTodoHandler } from "../bridge/promote-todo.js";
+import type { BulkItem, CreateTreeNode } from "./bulk-contract.js";
+import { resolveProjectRoot } from "./project.js";
+import {
+	TASK_TOOL_NAME,
+	TaskParamsSchema,
+	type TaskAction,
+	type TaskParams,
+} from "./task-schema.js";
+import { actionUsesTasque, validateTaskParams } from "./task-validation.js";
+import {
+	toBridgeParams,
+	toChangeParams,
+	toClaimParams,
+	toQueryParams,
+} from "./task-mappers.js";
+import { executeBulk } from "./tools-bulk.js";
+import { executeTsqChange, executeTsqMarkPlanned } from "./tools-change.js";
+import { executeTsqClaim } from "./tools-claim.js";
+import { executeHandoffCheck } from "./tools-handoff.js";
+import { executeTsqQuery } from "./tools-query.js";
+import { executeTsqSpec, type SpecMode } from "./tools-spec.js";
+import { executeCreateTree } from "./tools-tree-create.js";
+
+// --- Re-exports for backward compatibility ---
+export { TASK_TOOL_NAME, TaskParamsSchema, type TaskParams, type TaskAction } from "./task-schema.js";
+
+const DEFAULT_HANDLERS: TaskBridgeHandlers = {
+	promote_todo: promoteTodoHandler,
+	import_tsq: importTsqHandler,
+};
+
+export function registerTaskTool(pi: ExtensionAPI): void {
+	pi.registerTool(
+		defineTool({
+			name: TASK_TOOL_NAME,
+			label: "Task",
+			description:
+				"Manage durable project tasks: find, show, create, claim, specs, bulk changes, handoff checks, lifecycle, dependencies, and todo links.",
+			promptSnippet: TASK_PROMPT_SNIPPET,
+			promptGuidelines: TASK_PROMPT_GUIDELINES,
+			parameters: TaskParamsSchema,
+			executionMode: "sequential",
+
+			async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+				return executeTaskTool(pi, params as TaskParams, signal, ctx);
+			},
+		}),
+	);
+}
+
+export async function executeTaskTool(
+	pi: ExtensionAPI,
+	params: TaskParams,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+): Promise<AgentToolResult<unknown>> {
+	const validation = validateTaskParams(params);
+	if (!validation.ok) {
+		return validationErrorResult(validation.message);
+	}
+
+	const needsProject = actionUsesTasque(params.action);
+	let projectRoot = ctx.cwd;
+	if (needsProject) {
+		try {
+			projectRoot = await resolveProjectRoot(
+				pi,
+				ctx.cwd,
+				signal === undefined ? {} : { signal },
+			);
+		} catch (error) {
+			return errorResult("project_root_error", getErrorMessage(error), {
+				action: params.action,
+				cwd: ctx.cwd,
+				error: serializeError(error),
+			});
+		}
+	}
+
+	const taskCtx = { ...ctx, cwd: projectRoot };
+	const result = await dispatchTaskAction(pi, params, signal, taskCtx);
+	return params.action === "handoff_check"
+		? result
+		: addProjectDetails(result, projectRoot);
+}
+
+async function dispatchTaskAction(
+	pi: ExtensionAPI,
+	params: TaskParams,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+): Promise<AgentToolResult<unknown>> {
+	switch (params.action) {
+		case "doctor":
+		case "find":
+		case "show":
+		case "deps":
+		case "notes":
+		case "similar":
+			return executeTsqQuery(pi, toQueryParams(params), signal, ctx);
+		case "create":
+		case "note":
+		case "finish":
+		case "reopen":
+		case "defer":
+		case "start":
+		case "block":
+		case "unblock":
+		case "order":
+		case "unorder":
+			return executeTsqChange(pi, toChangeParams(params), signal, ctx);
+		case "claim":
+			return executeTsqClaim(pi, toClaimParams(params), signal, ctx);
+		case "spec":
+			return executeTsqSpec(
+				pi,
+				{ id: params.task, mode: params.mode as SpecMode, text: params.text },
+				signal,
+				ctx,
+			);
+		case "mark_planned":
+			return executeTsqMarkPlanned(pi, params.task!, signal, ctx);
+		case "bulk":
+			return executeBulk(pi, params.items as BulkItem[], signal, ctx);
+		case "create_tree":
+			return executeCreateTree(pi, params.root as CreateTreeNode, signal, ctx);
+		case "handoff_check":
+			return executeHandoffCheck(pi, signal, ctx);
+		case "link":
+		case "list_links":
+		case "promote":
+		case "import":
+			return executeTaskBridge(
+				pi,
+				toBridgeParams(params),
+				signal,
+				ctx,
+				DEFAULT_HANDLERS,
+			);
+	}
+}
+
+function validationErrorResult(message: string): AgentToolResult<unknown> {
+	return errorResult("validation_error", message);
+}
+
+function errorResult(
+	code: string,
+	message: string,
+	details: Record<string, unknown> = {},
+): AgentToolResult<unknown> {
+	return textToolResult(
+		`Error: ${message}`,
+		errorToolDetails({ code, message, details }),
+	);
+}
+
+function addProjectDetails(
+	result: AgentToolResult<unknown>,
+	projectRoot: string,
+): AgentToolResult<unknown> {
+	const details = isRecord(result.details)
+		? { ...result.details, projectRoot }
+		: { projectRoot };
+	return { ...result, details };
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function serializeError(error: unknown): Record<string, unknown> {
+	if (error instanceof Error) {
+		return {
+			name: error.name,
+			message: error.message,
+			...(error.stack === undefined ? {} : { stack: error.stack }),
+		};
+	}
+	return { value: String(error) };
+}

package/src/durable-tasks/task-validation.ts

@@ -0,0 +1,123 @@
+import {
+	fieldRequired,
+	requireStringField,
+} from "../shared/validation.js";
+import {
+	validateBulkItems,
+	validateCreateTreeNode,
+} from "./bulk-contract.js";
+import type { TaskAction, TaskParams } from "./task-schema.js";
+
+export function validateTaskParams(
+	params: TaskParams,
+): { readonly ok: true } | { readonly ok: false; readonly message: string } {
+	switch (params.action) {
+		case "find":
+			if (params.view === "tree") return { ok: true };
+			if (params.tasks === undefined) return fieldRequired("tasks");
+			return { ok: true };
+		case "show":
+		case "deps":
+		case "notes":
+		case "note":
+		case "finish":
+		case "reopen":
+		case "defer":
+		case "start":
+		case "claim":
+		case "import":
+			return requireStringField(params.task, "task");
+		case "create": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			const kind = requireStringField(params.kind, "kind");
+			if (!kind.ok) return kind;
+			return typeof params.priority === "number"
+				? { ok: true }
+				: fieldRequired("priority");
+		}
+		case "similar":
+			return requireStringField(params.query, "query");
+		case "block":
+		case "unblock": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			return requireStringField(params.by, "by");
+		}
+		case "order":
+		case "unorder": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			return requireStringField(params.after, "after");
+		}
+		case "link": {
+			const todo = requireTodoId(params.todo);
+			if (!todo.ok) return todo;
+			return requireStringField(params.task, "task");
+		}
+		case "promote":
+			return requireTodoId(params.todo);
+		case "mark_planned":
+			return requireStringField(params.task, "task");
+		case "spec": {
+			const task = requireStringField(params.task, "task");
+			if (!task.ok) return task;
+			const mode = params.mode as string | undefined;
+			if (mode === undefined || mode.trim().length === 0)
+				return fieldRequired("mode");
+			const isRead = mode === "show" || mode === "check";
+			const isWrite = mode === "set" || mode === "update";
+			if (!isRead && !isWrite)
+				return {
+					ok: false,
+					message: "mode must be show, check, set, or update",
+				};
+			if (isRead && params.text !== undefined)
+				return {
+					ok: false,
+					message: `spec ${mode} does not accept text`,
+				};
+			if (isWrite) {
+				const text = params.text?.trim();
+				if (text === undefined || text.length === 0)
+					return {
+						ok: false,
+						message: `spec ${mode} requires text`,
+					};
+			}
+			return { ok: true };
+		}
+		case "bulk":
+			return validateBulkItems(params.items);
+		case "create_tree":
+			return validateCreateTreeNode(params.root);
+		case "handoff_check":
+		case "doctor":
+		case "list_links":
+			return { ok: true };
+	}
+}
+
+export function actionUsesTasque(action: TaskAction): boolean {
+	return (
+		action !== "link" && action !== "list_links" && action !== "handoff_check"
+	);
+}
+
+export function hasWith(params: TaskParams, value: string): boolean {
+	return Array.isArray(params.with) && params.with.includes(value);
+}
+
+export function getTodoId(
+	value: boolean | number | undefined,
+): number | undefined {
+	return typeof value === "number" ? value : undefined;
+}
+
+export function requireTodoId(
+	value: boolean | number | undefined,
+): { readonly ok: true } | { readonly ok: false; readonly message: string } {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1
+		? { ok: true }
+		: fieldRequired("todo");
+}

package/src/durable-tasks/tools-bulk.ts

@@ -0,0 +1,141 @@
+/**
+ * Bulk lifecycle executor for durable tasks (tsq-6.2).
+ *
+ * Runs validated BulkItem[] sequentially with fail-fast semantics.
+ * Reuses executeTsqChange / executeTsqMarkPlanned — no raw CLI argv
+ * in the public contract.
+ */
+
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { BulkItem, BulkItemAction, BulkResult } from "./bulk-contract.js";
+import { isRecord } from "../shared/error-utils.js";
+import type { StandardToolDetails } from "../shared/tool-result.js";
+import { okToolDetails, textToolResult } from "../shared/tool-result.js";
+import {
+	executeTsqChange,
+	executeTsqMarkPlanned,
+	type TsqChangeAction,
+} from "./tools-change.js";
+
+// ── Action mapping ─────────────────────────────────────────────────
+
+const BULK_TO_CHANGE_ACTION: Record<
+	Exclude<BulkItemAction, "mark_planned">,
+	TsqChangeAction
+> = {
+	start: "start",
+	finish: "done",
+	reopen: "reopen",
+	defer: "defer",
+	note: "note",
+};
+
+// ── Public executor ────────────────────────────────────────────────
+
+/**
+ * Execute a validated bulk lifecycle operation.
+ *
+ * Items run sequentially via the existing mutation queue.
+ * On first failure, remaining items are marked skipped (no rollback).
+ * Result details are always `ok: true` — failure info lives in `BulkResult.failed`.
+ */
+export async function executeBulk(
+	pi: ExtensionAPI,
+	items: readonly BulkItem[],
+	signal: AbortSignal | undefined,
+	ctx: Pick<ExtensionContext, "cwd">,
+): Promise<AgentToolResult<StandardToolDetails<BulkResult>>> {
+	const completed: string[] = [];
+	let failed: BulkResult["failed"];
+	const skipped: string[] = [];
+
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i]!;
+		const result = await executeOneItem(pi, item, signal, ctx);
+
+		if (isResultOk(result)) {
+			completed.push(item.task);
+		} else {
+			failed = { task: item.task, error: extractErrorMessage(result) };
+			for (let j = i + 1; j < items.length; j++) {
+				skipped.push(items[j]!.task);
+			}
+			break;
+		}
+	}
+
+	const bulkResult: BulkResult = {
+		completed,
+		...(failed !== undefined ? { failed } : {}),
+		skipped,
+	};
+
+	return textToolResult(
+		formatBulkText(bulkResult, items.length),
+		okToolDetails(bulkResult),
+	);
+}
+
+// ── Single-item dispatch ───────────────────────────────────────────
+
+function executeOneItem(
+	pi: ExtensionAPI,
+	item: BulkItem,
+	signal: AbortSignal | undefined,
+	ctx: Pick<ExtensionContext, "cwd">,
+): Promise<AgentToolResult<unknown>> {
+	if (item.action === "mark_planned") {
+		return executeTsqMarkPlanned(pi, item.task, signal, ctx);
+	}
+
+	const action = BULK_TO_CHANGE_ACTION[item.action];
+	const params = buildChangeParams(action, item);
+	return executeTsqChange(pi, params, signal, ctx);
+}
+
+function buildChangeParams(
+	action: TsqChangeAction,
+	item: BulkItem,
+): { action: TsqChangeAction; id: string; note?: string } {
+	if (item.because !== undefined) {
+		return { action, id: item.task, note: item.because };
+	}
+	return { action, id: item.task };
+}
+
+// ── Result inspection ──────────────────────────────────────────────
+
+function isResultOk(result: AgentToolResult<unknown>): boolean {
+	const d = result.details;
+	return isRecord(d) && d.ok === true;
+}
+
+function extractErrorMessage(result: AgentToolResult<unknown>): string {
+	const d = result.details;
+	if (isRecord(d) && isRecord(d.error)) {
+		const msg = d.error.message;
+		if (typeof msg === "string") return msg;
+	}
+	return "unknown error";
+}
+
+// ── Formatting ─────────────────────────────────────────────────────
+
+function formatBulkText(result: BulkResult, total: number): string {
+	if (result.failed === undefined) {
+		return `Bulk: ${result.completed.length}/${total} completed`;
+	}
+
+	const parts = [`Bulk: ${result.completed.length}/${total} completed`];
+	parts.push("1 failed");
+	if (result.skipped.length > 0) {
+		parts.push(`${result.skipped.length} skipped`);
+	}
+	return `${parts.join(", ")}. Failed: ${result.failed.task} \u2014 ${result.failed.error}`;
+}
+
+// ── Utilities ──────────────────────────────────────────────────────