@bumpyclock/pi-tasque 0.1.0 → 0.2.1

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

@@ -0,0 +1,95 @@
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { errorToolDetails, textToolResult } from "../shared/tool-result.js";
+import {
+	collectHandoffStatus,
+	type HandoffCheckResult,
+} from "./handoff-guard.js";
+
+export async function executeHandoffCheck(
+	pi: ExtensionAPI,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+): Promise<AgentToolResult<unknown>> {
+	const result = await collectHandoffStatus({
+		pi,
+		cwd: ctx.cwd,
+		...(signal != null ? { signal } : {}),
+	});
+
+	if (!result.ok) {
+		return textToolResult(
+			`Error: ${result.message}`,
+			errorToolDetails({ code: result.code, message: result.message }),
+		);
+	}
+
+	return textToolResult(formatHandoffText(result), {
+		ok: true,
+		ready: result.ready,
+		...formatHandoffDetails(result),
+	});
+}
+
+function formatHandoffText(result: HandoffCheckResult & { ok: true }): string {
+	const lines: string[] = [
+		result.ready
+			? "Handoff ready: all session todos complete and linked tasks resolved."
+			: "Handoff not ready.",
+	];
+
+	if ("todoBlockers" in result && result.todoBlockers?.length) {
+		lines.push("", "Todo blockers:");
+		for (const b of result.todoBlockers) {
+			lines.push(`- #${b.todoId} "${b.subject}" — ${b.reason}`);
+		}
+	}
+
+	if ("linkedBlockers" in result && result.linkedBlockers?.length) {
+		lines.push("", "Linked task blockers:");
+		for (const b of result.linkedBlockers) {
+			lines.push(`- ${b.tsqId} (todo #${b.todoId}) — ${b.status}`);
+		}
+	}
+
+	if ("linkedWarnings" in result && result.linkedWarnings?.length) {
+		lines.push("", "Warnings:");
+		for (const w of result.linkedWarnings) {
+			lines.push(`- ${w.tsqId} (todo #${w.todoId}) — ${w.status}`);
+		}
+	}
+
+	if ("readErrors" in result && result.readErrors?.length) {
+		lines.push("", "Read errors:");
+		for (const e of result.readErrors) {
+			lines.push(`- ${e.tsqId} — ${e.code}: ${e.message}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function formatHandoffDetails(
+	result: HandoffCheckResult & { ok: true },
+): Record<string, unknown> {
+	const details: Record<string, unknown> = {};
+	if (result.projectRoot !== undefined) {
+		details.projectRoot = result.projectRoot;
+	}
+	if ("todoBlockers" in result && result.todoBlockers?.length) {
+		details.todoBlockers = result.todoBlockers;
+	}
+	if ("linkedBlockers" in result && result.linkedBlockers?.length) {
+		details.linkedBlockers = result.linkedBlockers;
+	}
+	if ("linkedWarnings" in result && result.linkedWarnings?.length) {
+		details.linkedWarnings = result.linkedWarnings;
+	}
+	if ("readErrors" in result && result.readErrors?.length) {
+		details.readErrors = result.readErrors;
+	}
+	return details;
+}

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

@@ -5,6 +5,11 @@ 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 { isRecord } from "../shared/error-utils.js";
 import { truncatedTextToolResult } from "../shared/tool-result.js";
 import type { TruncatedText } from "../shared/truncation.js";
 import { runTsqJson } from "./runner.js";
@@ -40,12 +45,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 +103,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 +132,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 +198,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 +248,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 +261,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 +287,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 +312,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 +324,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 +338,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 +359,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 +456,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 +468,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;
 }
@@ -490,7 +523,3 @@ function isTaskTreeNode(value: unknown): value is TsqTaskTreeNode {
 		isRecord(value) && isTsqTask(value.task) && Array.isArray(value.children)
 	);
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

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

@@ -0,0 +1,230 @@
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { errorToolDetails, textToolResult } from "../shared/tool-result.js";
+import { runQueuedMutation } from "./mutation-queue.js";
+import { runTsqJson } from "./runner.js";
+
+export type SpecMode = "show" | "check" | "set" | "update";
+
+export const SPEC_READ_MODES: readonly SpecMode[] = ["show", "check"];
+export const SPEC_WRITE_MODES: readonly SpecMode[] = ["set", "update"];
+
+export interface SpecParams {
+	readonly id: string | undefined;
+	readonly mode: SpecMode;
+	readonly text?: string | undefined;
+}
+
+export interface SpecSuccessDetails {
+	readonly ok: true;
+	readonly action: "spec";
+	readonly mode: SpecMode;
+	readonly argv: readonly string[];
+	readonly data: unknown;
+}
+
+export interface SpecCheckFailedDetails {
+	readonly ok: false;
+	readonly error: {
+		readonly code: "spec_check_failed";
+		readonly message: string;
+		readonly details: unknown;
+	};
+}
+
+export type SpecDetails = SpecSuccessDetails | SpecCheckFailedDetails;
+
+const DEFAULT_SPEC_TIMEOUT_MS = 10_000;
+
+export async function executeTsqSpec(
+	pi: ExtensionAPI,
+	params: SpecParams,
+	signal: AbortSignal | undefined,
+	ctx: Pick<ExtensionContext, "cwd">,
+): Promise<AgentToolResult<SpecDetails>> {
+	const validated = validateSpecParams(params);
+	if (!validated.ok) {
+		return textToolResult(
+			`Error: ${validated.message}`,
+			errorToolDetails({
+				code: "validation_error",
+				message: validated.message,
+			}) as unknown as SpecDetails,
+		);
+	}
+
+	const { argv, mode } = validated;
+	const isWrite = (SPEC_WRITE_MODES as readonly string[]).includes(mode);
+
+	try {
+		const data = isWrite
+			? await runQueuedMutation(ctx.cwd, () =>
+					runTsqJson(pi, { cwd: ctx.cwd }, argv, {
+						timeout: DEFAULT_SPEC_TIMEOUT_MS,
+						...(signal === undefined ? {} : { signal }),
+					}),
+				)
+			: await runTsqJson(pi, { cwd: ctx.cwd }, argv, {
+					timeout: DEFAULT_SPEC_TIMEOUT_MS,
+					...(signal === undefined ? {} : { signal }),
+				});
+
+		if (mode === "check" && isSpecCheckFailed(data)) {
+			return buildCheckFailedResult(data, argv);
+		}
+
+		return textToolResult(formatSpecSuccess(mode, data), {
+			ok: true,
+			action: "spec",
+			mode,
+			argv,
+			data,
+		} as SpecSuccessDetails);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const code = getErrorCode(error);
+		return textToolResult(
+			`Error: ${message}`,
+			errorToolDetails({
+				code,
+				message,
+				details: { action: "spec", mode, argv },
+			}) as unknown as SpecDetails,
+		);
+	}
+}
+
+type ValidationSuccess = {
+	readonly ok: true;
+	readonly mode: SpecMode;
+	readonly argv: string[];
+};
+type ValidationFailure = { readonly ok: false; readonly message: string };
+type ValidationResult = ValidationSuccess | ValidationFailure;
+
+export function validateSpecParams(params: SpecParams): ValidationResult {
+	const id = params.id?.trim();
+	if (id === undefined || id.length === 0) {
+		return { ok: false, message: "spec action requires id" };
+	}
+
+	const { mode } = params;
+	const isRead = (SPEC_READ_MODES as readonly string[]).includes(mode);
+	const isWrite = (SPEC_WRITE_MODES as readonly string[]).includes(mode);
+
+	if (!isRead && !isWrite) {
+		return {
+			ok: false,
+			message: `spec 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, mode, argv: buildSpecArgv(id, mode, params.text) };
+}
+
+export function buildSpecArgv(
+	id: string,
+	mode: SpecMode,
+	text: string | undefined,
+): string[] {
+	switch (mode) {
+		case "show":
+			return ["spec", id, "--show"];
+		case "check":
+			return ["spec", id, "--check"];
+		case "set":
+			return ["spec", id, "--force", `--text=${text!}`];
+		case "update":
+			return ["spec", id, "--update", `--text=${text!}`];
+	}
+}
+
+function isSpecCheckFailed(data: unknown): boolean {
+	if (typeof data !== "object" || data === null || Array.isArray(data)) {
+		return false;
+	}
+	return (data as Record<string, unknown>).ok === false;
+}
+
+function buildCheckFailedResult(
+	data: unknown,
+	argv: readonly string[],
+): AgentToolResult<SpecDetails> {
+	const record = data as Record<string, unknown>;
+	const diagnostics = record.diagnostics ?? record.issues ?? record;
+	const message =
+		typeof record.message === "string" ? record.message : "spec check failed";
+
+	return textToolResult(`Spec check failed: ${message}`, {
+		ok: false,
+		error: {
+			code: "spec_check_failed",
+			message,
+			details: { argv, diagnostics },
+		},
+	} as SpecCheckFailedDetails);
+}
+
+function formatSpecSuccess(mode: SpecMode, data: unknown): string {
+	switch (mode) {
+		case "show": {
+			const record = data as Record<string, unknown> | null;
+			const spec =
+				typeof record?.spec === "object" &&
+				record.spec !== null &&
+				!Array.isArray(record.spec)
+					? (record.spec as Record<string, unknown>)
+					: undefined;
+			const content =
+				typeof spec?.content === "string"
+					? spec.content
+					: typeof record?.content === "string"
+						? record.content
+						: undefined;
+			const path =
+				typeof spec?.path === "string"
+					? spec.path
+					: typeof record?.path === "string"
+						? record.path
+						: undefined;
+			if (content !== undefined) {
+				const header = path !== undefined ? `Spec (${path}):\n` : "Spec:\n";
+				return `${header}${content}`;
+			}
+			return "Spec: no content returned";
+		}
+		case "check":
+			return "Spec check passed";
+		case "set":
+			return "Spec attached";
+		case "update":
+			return "Spec updated";
+	}
+}
+
+function getErrorCode(error: unknown): string {
+	if (typeof error === "object" && error !== null && !Array.isArray(error)) {
+		const code = (error as Record<string, unknown>).code;
+		if (typeof code === "string") {
+			return code;
+		}
+	}
+	return "tsq_error";
+}