@bumpyclock/pi-tasque 0.1.0 → 0.2.1

package/src/durable-tasks/tools-tree-create.ts

@@ -0,0 +1,221 @@
+/**
+ * Nested create_tree executor for the `task` tool.
+ *
+ * Walks a validated `CreateTreeNode` tree depth-first, creating each parent
+ * before its children and passing the generated parent id via `--parent`.
+ *
+ * Fail-fast: on the first creation failure the entire remaining tree is
+ * skipped — no orphan children are created. No rollback of already-created
+ * nodes.
+ */
+
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { CreateTreeNode, CreateTreeResult } from "./bulk-contract.js";
+import { runQueuedMutation } from "./mutation-queue.js";
+import { runTsqJson } from "./runner.js";
+import { asRecord } from "../shared/error-utils.js";
+import {
+	okToolDetails,
+	textToolResult,
+	type StandardToolDetails,
+} from "../shared/tool-result.js";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+interface CreatedEntry {
+	readonly id: string;
+	readonly title: string;
+}
+
+interface FailedEntry {
+	readonly title: string;
+	readonly error: string;
+}
+
+interface SkippedEntry {
+	readonly title: string;
+}
+
+/** Mutable accumulator threaded through the walk. */
+interface TreeWalkState {
+	readonly created: CreatedEntry[];
+	failed?: FailedEntry;
+	readonly skipped: SkippedEntry[];
+}
+
+export type CreateTreeDetails = ReturnType<
+	typeof okToolDetails<CreateTreeResult>
+>;
+
+// ── Public API ─────────────────────────────────────────────────────
+
+export async function executeCreateTree(
+	pi: ExtensionAPI,
+	root: CreateTreeNode,
+	signal: AbortSignal | undefined,
+	ctx: Pick<ExtensionContext, "cwd">,
+): Promise<AgentToolResult<StandardToolDetails<CreateTreeResult>>> {
+	const state: TreeWalkState = { created: [], skipped: [] };
+
+	await walkAndCreate(pi, ctx, signal, root, undefined, state);
+
+	const result: CreateTreeResult = {
+		created: state.created,
+		...(state.failed ? { failed: state.failed } : {}),
+		skipped: state.skipped,
+	};
+
+	return textToolResult(formatResultText(result), okToolDetails(result));
+}
+
+// ── Tree walk ──────────────────────────────────────────────────────
+
+async function walkAndCreate(
+	pi: ExtensionAPI,
+	ctx: Pick<ExtensionContext, "cwd">,
+	signal: AbortSignal | undefined,
+	node: CreateTreeNode,
+	parentId: string | undefined,
+	state: TreeWalkState,
+): Promise<void> {
+	// If a prior node already failed, skip this entire subtree.
+	if (state.failed) {
+		collectSkipped(node, state.skipped);
+		return;
+	}
+
+	const argv = buildCreateArgv(node, parentId);
+
+	let createdId: string;
+	try {
+		const result = await runMutation(pi, ctx, argv, signal);
+		const extracted = extractCreatedId(result, node.title);
+		createdId = extracted.id;
+		state.created.push({ id: extracted.id, title: extracted.title });
+	} catch (error) {
+		state.failed = { title: node.title, error: getErrorMessage(error) };
+		// Skip all children of this failed node
+		if (node.children) {
+			for (const child of node.children) {
+				collectSkipped(child, state.skipped);
+			}
+		}
+		return;
+	}
+
+	// Recurse into children with the newly created parent id.
+	if (node.children) {
+		for (const child of node.children) {
+			await walkAndCreate(pi, ctx, signal, child, createdId, state);
+		}
+	}
+}
+
+// ── CLI argv builder ───────────────────────────────────────────────
+
+function buildCreateArgv(
+	node: CreateTreeNode,
+	parentId: string | undefined,
+): string[] {
+	const argv = [
+		"create",
+		`--kind=${node.kind}`,
+		"-p",
+		String(node.priority),
+	];
+
+	if (node.description) {
+		argv.push(`--description=${node.description}`);
+	}
+	if (parentId) {
+		argv.push(`--parent=${parentId}`);
+	}
+	if (node.planned === true) {
+		argv.push("--planned");
+	} else if (node.needsPlan === true) {
+		argv.push("--needs-plan");
+	}
+
+	argv.push("--", node.title);
+	return argv;
+}
+
+// ── Mutation runner ────────────────────────────────────────────────
+
+function runMutation(
+	pi: ExtensionAPI,
+	ctx: Pick<ExtensionContext, "cwd">,
+	argv: readonly string[],
+	signal: AbortSignal | undefined,
+): Promise<unknown> {
+	const options = signal === undefined ? {} : { signal };
+	return runQueuedMutation(ctx.cwd, () =>
+		runTsqJson(pi, { cwd: ctx.cwd }, argv, options),
+	);
+}
+
+// ── Result extraction ──────────────────────────────────────────────
+
+function extractCreatedId(
+	result: unknown,
+	fallbackTitle: string,
+): { readonly id: string; readonly title: string } {
+	const root = asRecord(result);
+	const task = asRecord(root?.task) ?? root;
+
+	const id = typeof task?.id === "string" ? task.id : undefined;
+	if (!id) {
+		throw new Error("tsq create did not return a task id");
+	}
+
+	const title =
+		typeof task?.title === "string" ? task.title : fallbackTitle;
+	return { id, title };
+}
+
+// ── Skipped collector ──────────────────────────────────────────────
+
+function collectSkipped(
+	node: CreateTreeNode,
+	skipped: SkippedEntry[],
+): void {
+	skipped.push({ title: node.title });
+	if (node.children) {
+		for (const child of node.children) {
+			collectSkipped(child, skipped);
+		}
+	}
+}
+
+// ── Text formatting ────────────────────────────────────────────────
+
+function formatResultText(result: CreateTreeResult): string {
+	const lines: string[] = [];
+
+	if (result.created.length > 0) {
+		const noun = result.created.length === 1 ? "task" : "tasks";
+		lines.push(
+			`Created ${result.created.length} ${noun}: ${result.created.map((c) => c.id).join(", ")}`,
+		);
+	}
+
+	if (result.failed) {
+		lines.push(`Failed: "${result.failed.title}" — ${result.failed.error}`);
+	}
+
+	if (result.skipped.length > 0) {
+		lines.push(`${result.skipped.length} skipped`);
+	}
+
+	return lines.join("\n");
+}
+
+// ── Utilities ──────────────────────────────────────────────────────
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/guidelines/internal-tools.ts

@@ -0,0 +1,33 @@
+export const READ_TASKS_PROMPT_SNIPPET = "Read durable task state.";
+
+export const READ_TASKS_PROMPT_GUIDELINES = [
+	"Use task read actions for fresh durable task state; read actions do not mutate tasks.",
+	"Include spec content only when needed; regular task details are more concise.",
+];
+
+export const CHANGE_TASKS_PROMPT_SNIPPET = "Mutate durable tasks.";
+
+export const CHANGE_TASKS_PROMPT_GUIDELINES = [
+	"Use task mutations for explicit durable task changes; use `todo` for current-session checklist steps.",
+	"Use block/unblock for hard blockers and order/unorder for task sequencing.",
+	"Inspect task details or dependencies before and after graph changes when the relationship is not obvious.",
+];
+
+export const CLAIM_TASK_PROMPT_SNIPPET = "Claim durable task ownership.";
+
+export const CLAIM_TASK_PROMPT_GUIDELINES = [
+	"Pass your own role/name as assignee when available, e.g. developer, worker, oracle.",
+	"Create a linked todo only when you want one session todo for the claimed task.",
+	"Completing a linked todo does not mark the durable task done; durable completion must be explicit.",
+];
+
+export const TASK_TODO_BRIDGE_PROMPT_SNIPPET =
+	"Link session todos and durable tasks.";
+
+export const TASK_TODO_BRIDGE_PROMPT_GUIDELINES = [
+	"Use link to associate an existing todo with an existing durable task via todo metadata.",
+	"Use list links to inspect current todo ↔ durable task associations.",
+	"Use promote to create a durable task from a todo and link the promoted todo explicitly.",
+	"Use import to create or reuse session todos from durable task state and link them explicitly.",
+	"Todo completion does not mark a durable task done; durable completion stays explicit.",
+];

package/src/guidelines/task.ts

@@ -0,0 +1,5 @@
+export const TASK_PROMPT_SNIPPET = "Durable project tasks and todo links.";
+
+export const TASK_PROMPT_GUIDELINES = [
+	"Use `task` for durable project work that should survive compaction and session restarts; use `todo` for current-session checklist steps.",
+];

package/src/guidelines/todo.ts

@@ -0,0 +1,5 @@
+export const TODO_PROMPT_SNIPPET = "Current-session checklist for execution.";
+
+export const TODO_PROMPT_GUIDELINES = [
+	"Use `todo` for current-session checklist steps; use `task` for durable project work.",
+];

package/src/index.ts

@@ -1,21 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerTaskBridgeTool } from "./bridge/bridge-tool.js";
-import { importTsqHandler } from "./bridge/import-tsq.js";
-import { promoteTodoHandler } from "./bridge/promote-todo.js";
+import { registerTaskTool } from "./durable-tasks/task-tool.js";
 import { registerTasqueStatusLifecycle } from "./durable-tasks/status.js";
-import { registerTsqChangeTool } from "./durable-tasks/tools-change.js";
-import { registerTsqClaimTool } from "./durable-tasks/tools-claim.js";
-import { registerTsqQueryTool } from "./durable-tasks/tools-query.js";
 import { registerSessionTodoModule } from "./session-todos/todo.js";
 
 export default function piTasqueExtension(pi: ExtensionAPI): void {
 	registerSessionTodoModule(pi);
-	registerTsqQueryTool(pi);
-	registerTsqChangeTool(pi);
-	registerTsqClaimTool(pi);
-	registerTaskBridgeTool(pi, {
-		promote_todo: promoteTodoHandler,
-		import_tsq: importTsqHandler,
-	});
+	registerTaskTool(pi);
 	registerTasqueStatusLifecycle(pi);
 }

package/src/session-todos/state/replay.ts

@@ -33,8 +33,7 @@ const VALID_STATUSES = new Set<TaskStatus>([
 	"deleted",
 ]);
 
-const TASK_BRIDGE_REPLAY_TOOL_NAME = "task_bridge";
-const TSQ_CLAIM_REPLAY_TOOL_NAME = "tsq_claim";
+const DURABLE_TASK_REPLAY_TOOL_NAME = "task";
 const TASK_BRIDGE_MUTATION_ACTIONS = new Set(["promote_todo", "import_tsq"]);
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -226,11 +225,10 @@ function applyReplayableClaimTodo(state: TaskState, todo: Task): TaskState {
 
 /**
  * Rebuild todo state from the current session branch. The latest compatible
- * `todo` tool result wins; malformed snapshots are skipped. Successful
- * state-mutating `task_bridge` results replay their todo snapshot, while
- * successful `task_bridge link` results and successful `tsq_claim` createTodo
- * results are replayed onto the current todo snapshot so bridge metadata,
- * imports/promotions, and claim-created todos survive reload/branch replay.
+ * `todo` tool result wins; malformed snapshots are skipped. Successful durable
+ * `task` results replay todo snapshots, links, and claim-created todos so
+ * bridge metadata, imports/promotions, and claim-created todos survive
+ * reload/branch replay.
  */
 export function replayFromBranch(ctx: BranchContext): TaskState {
 	let result = emptyState();
@@ -248,7 +246,7 @@ export function replayFromBranch(ctx: BranchContext): TaskState {
 			continue;
 		}
 
-		if (message.toolName === TASK_BRIDGE_REPLAY_TOOL_NAME) {
+		if (message.toolName === DURABLE_TASK_REPLAY_TOOL_NAME) {
 			const snapshot = getReplayableBridgeTodoSnapshot(message.details);
 			if (snapshot !== undefined) {
 				result = snapshot;
@@ -256,12 +254,11 @@ export function replayFromBranch(ctx: BranchContext): TaskState {
 			}
 
 			const link = getReplayableBridgeLink(message.details);
-			if (link === undefined) continue;
-			result = applyReplayableBridgeLink(result, link);
-			continue;
-		}
+			if (link !== undefined) {
+				result = applyReplayableBridgeLink(result, link);
+				continue;
+			}
 
-		if (message.toolName === TSQ_CLAIM_REPLAY_TOOL_NAME) {
 			const todo = getReplayableClaimTodo(message.details);
 			if (todo === undefined) continue;
 			result = applyReplayableClaimTodo(result, todo);

package/src/session-todos/todo-overlay.ts

@@ -21,7 +21,7 @@ import type { TaskState } from "./state/state.js";
 import { getState } from "./state/store.js";
 import { formatOverlayTaskLine, formatStatusLabel } from "./view/format.js";
 
-const WIDGET_KEY = "rpiv-todos";
+const WIDGET_KEY = "pi-tasque-todos";
 const MAX_WIDGET_LINES = 12;
 const OVERLAY_HEADING = "Todos";
 const OVERLAY_MORE = "more";

package/src/session-todos/todo.ts

@@ -2,6 +2,11 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "../shared/error-utils.js";
+import {
+	TODO_PROMPT_GUIDELINES,
+	TODO_PROMPT_SNIPPET,
+} from "../guidelines/todo.js";
 import {
 	selectTasksByStatus,
 	selectTodoCounts,
@@ -32,17 +37,12 @@ import {
 const SECTION_PENDING = "── Pending ──";
 const SECTION_IN_PROGRESS = "── In Progress ──";
 const SECTION_COMPLETED = "── Completed ──";
-const TODO_AFFECTING_TOOLS = new Set(["todo", "task_bridge", "tsq_claim"]);
-
-export const TODO_PROMPT_SNIPPET =
-	"Manage current-session tactical todos for multi-step execution.";
+const TODO_AFFECTING_TOOLS = new Set(["todo", "task"]);
 
-export const TODO_PROMPT_GUIDELINES: string[] = [
-	"Use `todo` for current-session tactical work: inspect, edit, verify, and handoff steps for the task in front of you.",
-	"Use `todo` for session work, not durable backlog; use Tasque/tsq tools for durable ownership, specs, and cross-session work.",
-	"Mark one task in_progress before starting it, complete it when verified, and keep blocked or partial work out of completed.",
-	"Use blockedBy for session-local dependencies; list hides deleted tombstones unless includeDeleted is true.",
-];
+export {
+	TODO_PROMPT_GUIDELINES,
+	TODO_PROMPT_SNIPPET,
+} from "../guidelines/todo.js";
 
 export { isTransitionValid } from "./state/invariants.js";
 export { applyTaskMutation } from "./state/state-reducer.js";
@@ -75,7 +75,7 @@ export function registerTodoTool(pi: ExtensionAPI): void {
 		name: TOOL_NAME,
 		label: TOOL_LABEL,
 		description:
-			"Manage current-session todos for tactical execution. Actions: create, update, list, get, delete, clear. Use for this session's working checklist, not durable backlog.",
+			"Manage current-session todos for tactical execution. Actions: create, update, list, get, delete, clear. Use for this session's checklist; use task for durable project work.",
 		promptSnippet: TODO_PROMPT_SNIPPET,
 		promptGuidelines: TODO_PROMPT_GUIDELINES,
 		parameters: TodoParamsSchema,
@@ -233,7 +233,3 @@ function isSuccessfulToolExecutionResult(event: {
 	if (details.ok === false) return false;
 	return details.error === undefined;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/session-todos/tool/types.ts

@@ -79,7 +79,7 @@ export interface TaskMutationParams {
 
 // ---------------------------------------------------------------------------
 // TypeBox parameter schema — every `description` doubles as LLM-facing prompt
-// copy. Field order and wording stay compatible with rpiv-todo v1.
+// copy. Keep field order and wording stable for replay and agent ergonomics.
 // ---------------------------------------------------------------------------
 
 export const TodoParamsSchema = Type.Object({
@@ -92,10 +92,10 @@ export const TodoParamsSchema = Type.Object({
 		"clear",
 	] as const),
 	subject: Type.Optional(
-		Type.String({ description: "Task subject line (required for create)" }),
+		Type.String({ description: "Todo subject line (required for create)" }),
 	),
 	description: Type.Optional(
-		Type.String({ description: "Long-form task description" }),
+		Type.String({ description: "Long-form todo description" }),
 	),
 	activeForm: Type.Optional(
 		Type.String({
@@ -115,17 +115,17 @@ export const TodoParamsSchema = Type.Object({
 	),
 	addBlockedBy: Type.Optional(
 		Type.Array(Type.Number(), {
-			description: "Task ids to add to blockedBy (update only, additive merge)",
+			description: "Todo ids to add to blockedBy (update only, additive merge)",
 		}),
 	),
 	removeBlockedBy: Type.Optional(
 		Type.Array(Type.Number(), {
 			description:
-				"Task ids to remove from blockedBy (update only, additive merge)",
+				"Todo ids to remove from blockedBy (update only, additive merge)",
 		}),
 	),
 	owner: Type.Optional(
-		Type.String({ description: "Agent/owner assigned to this task" }),
+		Type.String({ description: "Agent/owner assigned to this todo" }),
 	),
 	metadata: Type.Optional(
 		Type.Record(Type.String(), Type.Unknown(), {
@@ -135,7 +135,7 @@ export const TodoParamsSchema = Type.Object({
 	),
 	id: Type.Optional(
 		Type.Number({
-			description: "Task id (required for update, get, delete)",
+			description: "Todo id (required for update, get, delete)",
 		}),
 	),
 	includeDeleted: Type.Optional(

package/src/shared/error-utils.ts

@@ -0,0 +1,29 @@
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	return value as Record<string, unknown>;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function copyKnownErrorFields(error: Error): Record<string, unknown> {
+	const record = error as unknown as Record<string, unknown>;
+	const output: Record<string, unknown> = {};
+	for (const key of [
+		"code",
+		"command",
+		"details",
+		"stderr",
+		"stdout",
+		"killed",
+		"args",
+	] as const) {
+		if (record[key] !== undefined) {
+			output[key] = record[key];
+		}
+	}
+	return output;
+}

package/src/shared/validation.ts

@@ -0,0 +1,25 @@
+export function definedParams<T>(params: Record<string, unknown>): T {
+	const output: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(params)) {
+		if (value !== undefined) {
+			output[key] = value;
+		}
+	}
+	return output as T;
+}
+
+export function fieldRequired(field: string): {
+	readonly ok: false;
+	readonly message: string;
+} {
+	return { ok: false, message: `${field} is required` };
+}
+
+export function requireStringField(
+	value: string | undefined,
+	field: string,
+): { readonly ok: true } | { readonly ok: false; readonly message: string } {
+	return typeof value === "string" && value.trim().length > 0
+		? { ok: true }
+		: fieldRequired(field);
+}