@bumpyclock/pi-tasque 0.1.0 → 0.2.0

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

@@ -0,0 +1,144 @@
+/**
+ * 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 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 ──────────────────────────────────────────────────────
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -1,17 +1,22 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	defineTool,
+	type AgentToolResult,
 	type ExtensionAPI,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
-import { runQueuedMutation } from "./mutation-queue.js";
-import { runTsqJson } from "./runner.js";
+import {
+	CHANGE_TASKS_PROMPT_GUIDELINES,
+	CHANGE_TASKS_PROMPT_SNIPPET,
+} from "../guidelines/internal-tools.js";
 import {
 	errorToolDetails,
 	okToolDetails,
 	textToolResult,
 } from "../shared/tool-result.js";
+import { runQueuedMutation } from "./mutation-queue.js";
+import { runTsqJson } from "./runner.js";
 
 export const TSQ_CHANGE_TOOL_NAME = "tsq_change";
 
@@ -34,27 +39,29 @@ export type TsqChangeAction = (typeof TSQ_CHANGE_ACTIONS)[number];
 export const TsqChangeParamsSchema = Type.Object(
 	{
 		action: StringEnum(TSQ_CHANGE_ACTIONS, {
-			description: "Durable Tasque mutation to run",
+			description: "Durable task mutation to run",
 		}),
 		title: Type.Optional(
 			Type.String({ description: "Task title (required for create)" }),
 		),
 		id: Type.Optional(
 			Type.String({
-				description: "Tasque task id for lifecycle/note/claim actions",
+				description: "Durable task id for lifecycle/note/claim actions",
 			}),
 		),
 		kind: Type.Optional(
-			Type.String({ description: "Tasque task kind (required for create)" }),
+			Type.String({ description: "Durable task kind (required for create)" }),
 		),
 		priority: Type.Optional(
-			Type.Integer({ description: "Tasque priority (required for create)" }),
+			Type.Integer({
+				description: "Durable task priority (required for create)",
+			}),
 		),
 		description: Type.Optional(
 			Type.String({ description: "Task description (create only)" }),
 		),
 		parent: Type.Optional(
-			Type.String({ description: "Parent Tasque task id (create only)" }),
+			Type.String({ description: "Parent durable task id (create only)" }),
 		),
 		planned: Type.Optional(
 			Type.Boolean({ description: "Mark created task planned" }),
@@ -121,61 +128,110 @@ export function registerTsqChangeTool(pi: ExtensionAPI): void {
 	pi.registerTool(
 		defineTool({
 			name: TSQ_CHANGE_TOOL_NAME,
-			label: "Tasque Change",
+			label: "Task Change",
 			description:
-				"Run minimal durable Tasque mutations. Supports create, note, done, reopen, defer, start, assignment-only claim, and block/order edge changes. No raw tsq passthrough.",
-			promptSnippet:
-				"tsq_change: mutate durable Tasque tasks only through approved lifecycle/note/edge actions.",
-			promptGuidelines: [
-				"Use tsq_change only for explicit durable Tasque mutations; do not use it as a raw tsq passthrough.",
-				"Use todo for current-session checklist steps; use tsq_change when durable Tasque state must change.",
-				"Use block/unblock for hard blockers and order/unorder for sequencing where one task should happen after another.",
-				"Use tsq_query with action deps or show to inspect durable graph state before or after edge changes.",
-			],
+				"Mutate durable tasks: lifecycle, notes, ownership, dependencies, and sequencing.",
+			promptSnippet: CHANGE_TASKS_PROMPT_SNIPPET,
+			promptGuidelines: CHANGE_TASKS_PROMPT_GUIDELINES,
 			parameters: TsqChangeParamsSchema,
 			executionMode: "sequential",
 
 			async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-				const command = buildMutationCommand(
-					params as Readonly<Record<string, unknown>>,
-				);
-				if (!command.ok) {
-					return validationErrorResult(command.message);
-				}
-
-				try {
-					const result = await runMutation(pi, ctx, command.argv, signal);
-					return textToolResult(
-						formatSuccess(command.action, params, result),
-						okToolDetails({
-							action: command.action,
-							argv: command.argv,
-							result,
-						}),
-					);
-				} catch (error) {
-					const message = getErrorMessage(error);
-					return textToolResult(
-						`Error: ${message}`,
-						errorToolDetails({
-							code: getErrorCode(error),
-							message,
-							details: {
-								action: command.action,
-								argv: command.argv,
-								error: serializeError(error),
-							},
-						}),
-					);
-				}
+				return executeTsqChange(pi, params as TsqChangeParams, signal, ctx);
 			},
 		}),
 	);
 }
 
+export async function executeTsqChange(
+	pi: ExtensionAPI,
+	params: TsqChangeParams,
+	signal: AbortSignal | undefined,
+	ctx: Pick<ExtensionContext, "cwd">,
+): Promise<AgentToolResult<TsqChangeDetails>> {
+	const command = buildMutationCommand(
+		params as Readonly<Record<string, unknown>>,
+	);
+	if (!command.ok) {
+		return validationErrorResult(command.message);
+	}
+
+	try {
+		const result = await runMutation(pi, ctx, command.argv, signal);
+		return textToolResult(
+			formatSuccess(command.action, params, result),
+			okToolDetails({
+				action: command.action,
+				argv: command.argv,
+				result,
+			}),
+		);
+	} catch (error) {
+		const message = getErrorMessage(error);
+		return textToolResult(
+			`Error: ${message}`,
+			errorToolDetails({
+				code: getErrorCode(error),
+				message,
+				details: {
+					action: command.action,
+					argv: command.argv,
+					error: serializeError(error),
+				},
+			}),
+		);
+	}
+}
+
+// --- mark_planned helper (tsq-5.2) ---
+
+export interface TsqMarkPlannedSuccessData {
+	readonly argv: readonly string[];
+	readonly result: unknown;
+}
+
+export type TsqMarkPlannedDetails = ReturnType<
+	typeof okToolDetails<TsqMarkPlannedSuccessData>
+>;
+
+export async function executeTsqMarkPlanned(
+	pi: ExtensionAPI,
+	taskId: string,
+	signal: AbortSignal | undefined,
+	ctx: Pick<ExtensionContext, "cwd">,
+): Promise<AgentToolResult<TsqMarkPlannedDetails>> {
+	const trimmed = taskId.trim();
+	if (trimmed.length === 0) {
+		return validationErrorResult("task id is required");
+	}
+
+	const argv = ["planned", trimmed];
+
+	try {
+		const result = await runMutation(pi, ctx, argv, signal);
+		return textToolResult(
+			`Marked ${trimmed} as planned`,
+			okToolDetails({ argv, result }),
+		);
+	} catch (error) {
+		const message = getErrorMessage(error);
+		return textToolResult(
+			`Error: ${message}`,
+			errorToolDetails({
+				code: getErrorCode(error),
+				message,
+				details: {
+					argv,
+					error: serializeError(error),
+				},
+			}),
+		);
+	}
+}
+
 function runMutation(
 	pi: ExtensionAPI,
-	ctx: ExtensionContext,
+	ctx: Pick<ExtensionContext, "cwd">,
 	argv: readonly string[],
 	signal: AbortSignal | undefined,
 ): Promise<unknown> {
@@ -192,7 +248,7 @@ function buildMutationCommand(
 	if (!isTsqChangeAction(action)) {
 		return {
 			ok: false,
-			message: "action must be a supported tsq_change action",
+			message: "action must be a supported durable task mutation",
 		};
 	}
 

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

@@ -5,6 +5,10 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
+import {
+	CLAIM_TASK_PROMPT_GUIDELINES,
+	CLAIM_TASK_PROMPT_SNIPPET,
+} from "../guidelines/internal-tools.js";
 import {
 	applyTaskMutation,
 	type Op,
@@ -24,7 +28,7 @@ export const TSQ_CLAIM_TOOL_NAME = "tsq_claim";
 
 export const TsqClaimParamsSchema = Type.Object(
 	{
-		id: Type.String({ description: "Named Tasque task id to claim." }),
+		id: Type.String({ description: "Named durable task id to claim." }),
 		assignee: Type.Optional(
 			Type.String({
 				description: "Agent or role claiming the task. Defaults to pi.",
@@ -38,8 +42,7 @@ export const TsqClaimParamsSchema = Type.Object(
 		),
 		requireSpec: Type.Optional(
 			Type.Boolean({
-				description:
-					"Require an attached Tasque spec before the claim succeeds.",
+				description: "Require an attached task spec before the claim succeeds.",
 			}),
 		),
 		createTodo: Type.Optional(
@@ -95,16 +98,10 @@ export function registerTsqClaimTool(pi: ExtensionAPI): void {
 	pi.registerTool(
 		defineTool({
 			name: TSQ_CLAIM_TOOL_NAME,
-			label: "Tasque Claim",
-			description:
-				"Claim a named durable Tasque task. Requires an explicit id; does not auto-select next ready work.",
-			promptSnippet:
-				"Use tsq_claim for named durable Tasque ownership. Provide id; assignee defaults to pi; start defaults to true.",
-			promptGuidelines: [
-				"Pass your own role/name as assignee when available, e.g. developer, worker, oracle.",
-				"Use createTodo only when you want one session todo linked to the claimed durable task.",
-				"Completing a linked session todo does not mark the Tasque task done; durable completion must be explicit.",
-			],
+			label: "Task Claim",
+			description: "Claim named durable task ownership.",
+			promptSnippet: CLAIM_TASK_PROMPT_SNIPPET,
+			promptGuidelines: CLAIM_TASK_PROMPT_GUIDELINES,
 			parameters: TsqClaimParamsSchema,
 			executionMode: "sequential",
 

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

@@ -5,6 +5,10 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
+import {
+	READ_TASKS_PROMPT_GUIDELINES,
+	READ_TASKS_PROMPT_SNIPPET,
+} from "../guidelines/internal-tools.js";
 import { truncatedTextToolResult } from "../shared/tool-result.js";
 import type { TruncatedText } from "../shared/truncation.js";
 import { runTsqJson } from "./runner.js";
@@ -40,12 +44,12 @@ export type TsqQueryAction = (typeof TSQ_QUERY_ACTIONS)[number];
 export const TsqQueryParamsSchema = Type.Object(
 	{
 		action: StringEnum(TSQ_QUERY_ACTIONS, {
-			description: "Read-only Tasque query to run.",
+			description: "Read-only durable task query to run.",
 		}),
 		id: Type.Optional(
 			Type.String({
 				description:
-					"Tasque task id. Required for show, show_with_spec, deps, and notes.",
+					"Durable task id. Required for show, spec details, deps, and notes.",
 			}),
 		),
 		lane: Type.Optional(
@@ -98,15 +102,10 @@ const DEFAULT_QUERY_TIMEOUT_MS = 10_000;
 export function registerTsqQueryTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: TSQ_QUERY_TOOL_NAME,
-		label: "Tasque Query",
-		description:
-			"Run read-only Tasque durable-task queries through tsq --format json. Does not mutate Tasque state.",
-		promptSnippet:
-			"Use tsq_query for fresh read-only Tasque task state such as doctor, ready/open lists, show, deps, notes, tree, and similar lookups.",
-		promptGuidelines: [
-			"tsq_query is read-only; use mutation tools for lifecycle or notes.",
-			"Use show_with_spec only when spec content is needed; regular show is more concise.",
-		],
+		label: "Task Query",
+		description: "Read durable task state. Does not mutate tasks.",
+		promptSnippet: READ_TASKS_PROMPT_SNIPPET,
+		promptGuidelines: READ_TASKS_PROMPT_GUIDELINES,
 		parameters: TsqQueryParamsSchema,
 		executionMode: "parallel",
 		async execute(
@@ -132,10 +131,11 @@ export async function executeTsqQuery(
 	AgentToolResult<TsqQueryDetails & { readonly truncation: TruncatedText }>
 > {
 	const argv = buildTsqQueryArgv(params);
-	const data = await runTsqJson<TsqQueryData>(pi, { cwd: ctx.cwd }, argv, {
+	const rawData = await runTsqJson<TsqQueryData>(pi, { cwd: ctx.cwd }, argv, {
 		timeout: DEFAULT_QUERY_TIMEOUT_MS,
 		...(signal === undefined ? {} : { signal }),
 	});
+	const data = normalizeQueryData(params, rawData);
 	const text = formatTsqQueryResult(params, data);
 
 	const details: TsqQueryDetails = {
@@ -197,6 +197,24 @@ export function buildTsqQueryArgv(params: TsqQueryParams): string[] {
 	}
 }
 
+function normalizeQueryData(
+	params: TsqQueryParams,
+	data: TsqQueryData,
+): TsqQueryData {
+	if (params.action !== "find_tree") {
+		return data;
+	}
+
+	const id = params.id?.trim();
+	if (id === undefined || id.length === 0) {
+		return data;
+	}
+
+	const found = findTaskTreeNode(getTreeRoots(data), id);
+	const filtered = found === undefined ? [] : [found];
+	return Array.isArray(data) ? filtered : { tree: filtered };
+}
+
 function formatTsqQueryResult(
 	params: TsqQueryParams,
 	data: TsqQueryData,
@@ -229,7 +247,7 @@ function formatDoctor(data: TsqQueryData): string {
 		? doctor.issues.length
 		: undefined;
 	const parts = [
-		"Tasque doctor",
+		"Task doctor",
 		formatMetric(doctor.tasks, "tasks"),
 		formatMetric(doctor.events, "events"),
 		issueCount === undefined ? undefined : `${issueCount} issues`,
@@ -242,7 +260,7 @@ function formatTaskList(
 	tasks: readonly TsqTask[],
 ): string {
 	const lines = [
-		`Tasque ${action}: ${formatCount(tasks.length, "task")}${formatLimitNotice(tasks.length)}`,
+		`Task ${action}: ${formatCount(tasks.length, "task")}${formatLimitNotice(tasks.length)}`,
 		...tasks.slice(0, MAX_RENDERED_ITEMS).map(formatTaskLine),
 	];
 	return lines.join("\n");
@@ -268,21 +286,19 @@ function formatShow(data: TsqQueryData): string {
 		]
 			.filter((part): part is string => part !== undefined)
 			.join(" · ");
-		return [`Tasque task: ${parts}: ${task.title}`, extra]
-			.filter(Boolean)
-			.join("\n");
+		return [`Task: ${parts}: ${task.title}`, extra].filter(Boolean).join("\n");
 	}
-	return "Tasque task: no task data returned";
+	return "Task: no task data returned";
 }
 
 function formatDeps(data: TsqQueryData): string {
 	const root = (data as Partial<{ root: TsqDepTreeNode }>).root;
 	if (root === undefined) {
-		return "Tasque deps: no dependency data returned";
+		return "Task deps: no dependency data returned";
 	}
 	const lines = flattenDepTree(root).slice(0, MAX_RENDERED_ITEMS);
 	return [
-		`Tasque deps: ${root.id}${formatLimitNotice(countDepTree(root))}`,
+		`Task deps: ${root.id}${formatLimitNotice(countDepTree(root))}`,
 		...lines.map(
 			({ node, indent }) =>
 				`${"  ".repeat(indent)}${formatTaskLine(node.task)}`,
@@ -295,7 +311,7 @@ function formatNotes(data: TsqQueryData): string {
 	const notes = notesData.notes ?? [];
 	const taskId = notesData.task_id ?? "task";
 	return [
-		`Tasque notes for ${taskId}: ${formatCount(notes.length, "note")}${formatLimitNotice(notes.length)}`,
+		`Task notes for ${taskId}: ${formatCount(notes.length, "note")}${formatLimitNotice(notes.length)}`,
 		...notes.slice(0, MAX_RENDERED_ITEMS).map((note) => {
 			const firstLine = note.text.split(/\r?\n/u)[0] ?? "";
 			return `${note.ts} ${note.actor}: ${truncateInline(firstLine, 120)}`;
@@ -307,7 +323,7 @@ function formatTree(data: TsqQueryData, label = "tree"): string {
 	const roots = getTreeRoots(data);
 	const flattened = roots.flatMap((root) => flattenTaskTree(root));
 	return [
-		`Tasque ${label}: ${formatCount(flattened.length, "task")}${formatLimitNotice(flattened.length)}`,
+		`Task ${label}: ${formatCount(flattened.length, "task")}${formatLimitNotice(flattened.length)}`,
 		...flattened
 			.slice(0, MAX_RENDERED_ITEMS)
 			.map(
@@ -321,7 +337,7 @@ function formatSimilar(data: TsqQueryData): string {
 	const similar = data as Partial<TsqSimilarData>;
 	const candidates = similar.candidates ?? [];
 	return [
-		`Tasque similar: ${formatCount(candidates.length, "candidate")}${formatLimitNotice(candidates.length)}`,
+		`Task similar: ${formatCount(candidates.length, "candidate")}${formatLimitNotice(candidates.length)}`,
 		...candidates.slice(0, MAX_RENDERED_ITEMS).map(formatCandidateLine),
 	].join("\n");
 }
@@ -342,6 +358,22 @@ function getTreeRoots(data: TsqQueryData): readonly TsqTaskTreeNode[] {
 	return Array.isArray(tree) ? tree.filter(isTaskTreeNode) : [];
 }
 
+function findTaskTreeNode(
+	roots: readonly TsqTaskTreeNode[],
+	id: string,
+): TsqTaskTreeNode | undefined {
+	for (const root of roots) {
+		if (root.task.id === id) {
+			return root;
+		}
+		const child = findTaskTreeNode(root.children, id);
+		if (child !== undefined) {
+			return child;
+		}
+	}
+	return undefined;
+}
+
 function hasTreeData(data: TsqQueryData): boolean {
 	return Array.isArray(data)
 		? data.some(isTaskTreeNode)
@@ -423,7 +455,7 @@ function validateDepth(depth: unknown): number | undefined {
 		return undefined;
 	}
 	if (typeof depth !== "number" || !Number.isInteger(depth) || depth < 1) {
-		throw new Error("tsq_query depth must be an integer >= 1");
+		throw new Error("task dependency depth must be an integer >= 1");
 	}
 	return depth;
 }
@@ -435,7 +467,7 @@ function requireString(
 ): string {
 	const trimmed = value?.trim();
 	if (trimmed === undefined || trimmed.length === 0) {
-		throw new Error(`tsq_query action ${action} requires ${field}`);
+		throw new Error(`task action ${action} requires ${field}`);
 	}
 	return trimmed;
 }