@bumpyclock/pi-tasque 0.1.0

package/src/bridge/promote-todo.ts

@@ -0,0 +1,331 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { runQueuedMutation } from "../durable-tasks/mutation-queue.js";
+import { runTsqJson } from "../durable-tasks/runner.js";
+import { cloneTaskState } from "../session-todos/state/state.js";
+import { applyTaskMutation } from "../session-todos/state/state-reducer.js";
+import { commitState, getState } from "../session-todos/state/store.js";
+import type { Task } from "../session-todos/tool/types.js";
+import {
+	errorToolDetails,
+	okToolDetails,
+	textToolResult,
+} from "../shared/tool-result.js";
+import type {
+	PromoteTodoBridgeParams,
+	TaskBridgeDetails,
+	TaskBridgeHandlerContext,
+} from "./types.js";
+
+const DEFAULT_KIND = "task";
+const DEFAULT_PRIORITY = 2;
+const DEFAULT_PROMOTED_BY = "pi";
+const PROMOTION_NOTE_PREFIX = "Promoted from pi-tasque session todo #";
+
+interface ValidPromotionParams {
+	readonly todoId: number;
+	readonly kind: string;
+	readonly priority: number;
+	readonly description?: string;
+	readonly parent?: string;
+	readonly planned?: boolean;
+	readonly needsPlan?: boolean;
+	readonly promotedBy: string;
+}
+
+export async function promoteTodoHandler(
+	params: PromoteTodoBridgeParams,
+	ctx: TaskBridgeHandlerContext,
+): Promise<AgentToolResult<TaskBridgeDetails>> {
+	const validation = validateParams(params);
+	if (!validation.ok) {
+		return errorResult("validation_error", validation.message);
+	}
+
+	const todo = findPromotableTodo(validation.value.todoId);
+	if (!todo.ok) {
+		return errorResult("validation_error", todo.message);
+	}
+
+	const similarArgv = ["find", "similar", todo.value.subject];
+	let similarResult: unknown;
+	try {
+		similarResult = await runTsqJson(ctx.pi, { cwd: ctx.cwd }, similarArgv, {
+			...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+		});
+	} catch (error) {
+		return errorResult(getErrorCode(error), getErrorMessage(error), {
+			action: "promote_todo",
+			argv: { similar: similarArgv },
+			error: serializeError(error),
+		});
+	}
+	const similarCandidates = extractSimilarCandidates(similarResult);
+
+	const createArgv = buildCreateArgv(todo.value, validation.value);
+	let createResult: unknown;
+	try {
+		createResult = await runQueuedMutation(ctx.cwd, () =>
+			runTsqJson(ctx.pi, { cwd: ctx.cwd }, createArgv, {
+				...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+			}),
+		);
+	} catch (error) {
+		return errorResult(getErrorCode(error), getErrorMessage(error), {
+			action: "promote_todo",
+			similarCandidates,
+			argv: { similar: similarArgv, create: createArgv },
+			error: serializeError(error),
+		});
+	}
+
+	const tsqId = extractCreatedTaskId(createResult);
+	if (tsqId === undefined) {
+		return errorResult(
+			"invalid_tsq_response",
+			"tsq create response did not include a task id",
+			{
+				action: "promote_todo",
+				similarCandidates,
+				argv: { similar: similarArgv, create: createArgv },
+				result: createResult,
+			},
+		);
+	}
+
+	const noteText = `${PROMOTION_NOTE_PREFIX}${validation.value.todoId}`;
+	const noteArgv = ["note", tsqId, "--", noteText];
+	let noteResult: unknown;
+	const warnings: string[] = [];
+	try {
+		noteResult = await runQueuedMutation(ctx.cwd, () =>
+			runTsqJson(ctx.pi, { cwd: ctx.cwd }, noteArgv, {
+				...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+			}),
+		);
+	} catch (error) {
+		warnings.push(
+			`Failed to add promotion note to ${tsqId}: ${getErrorMessage(error)}`,
+		);
+	}
+
+	const promotedAt = new Date().toISOString();
+	const updateResult = applyTaskMutation(getState(), "update", {
+		id: validation.value.todoId,
+		status: "completed",
+		metadata: {
+			tsqId,
+			promotedAt,
+			promotedBy: validation.value.promotedBy,
+		},
+	});
+	if (updateResult.op.kind === "error") {
+		return errorResult("todo_update_failed", updateResult.op.message, {
+			action: "promote_todo",
+			tsqId,
+			similarCandidates,
+			argv: { similar: similarArgv, create: createArgv, note: noteArgv },
+			createResult,
+			noteResult,
+			warnings,
+		});
+	}
+	commitState(updateResult.state);
+	const todoSnapshot = cloneTaskState(updateResult.state);
+	const updatedTodo = todoSnapshot.tasks.find(
+		(task) => task.id === validation.value.todoId,
+	);
+
+	const content = [`Promoted todo #${validation.value.todoId} to ${tsqId}`];
+	if (warnings.length > 0) {
+		content.push(...warnings.map((warning) => `Warning: ${warning}`));
+	}
+
+	return textToolResult(
+		content.join("\n"),
+		okToolDetails(
+			{
+				action: "promote_todo" as const,
+				todo: updatedTodo,
+				tsqId,
+				todoSnapshot,
+				similarCandidates,
+				createResult,
+				noteResult,
+				argv: {
+					similar: similarArgv,
+					create: createArgv,
+					note: noteArgv,
+				},
+			},
+			warnings.length === 0 ? {} : { warnings },
+		),
+	);
+}
+
+function validateParams(
+	params: PromoteTodoBridgeParams,
+):
+	| { readonly ok: true; readonly value: ValidPromotionParams }
+	| { readonly ok: false; readonly message: string } {
+	const todoId = params.todoId;
+	if (typeof todoId !== "number" || !Number.isInteger(todoId) || todoId < 1) {
+		return { ok: false, message: "todoId is required" };
+	}
+
+	const kind = params.kind === undefined ? DEFAULT_KIND : params.kind.trim();
+	if (kind.length === 0) {
+		return { ok: false, message: "kind must be a non-empty string" };
+	}
+
+	const priority = params.priority ?? DEFAULT_PRIORITY;
+	if (!Number.isInteger(priority)) {
+		return { ok: false, message: "priority must be an integer" };
+	}
+
+	const planned = params.planned;
+	const needsPlan = params.needsPlan;
+	if (planned === true && needsPlan === true) {
+		return {
+			ok: false,
+			message: "planned and needsPlan cannot both be true",
+		};
+	}
+
+	const promotedBy =
+		normalizeOptionalString(params.assignee) ?? DEFAULT_PROMOTED_BY;
+	const description = normalizeOptionalString(params.description);
+	const parent = normalizeOptionalString(params.parent);
+
+	return {
+		ok: true,
+		value: {
+			todoId,
+			kind,
+			priority,
+			promotedBy,
+			...(description === undefined ? {} : { description }),
+			...(parent === undefined ? {} : { parent }),
+			...(planned === undefined ? {} : { planned }),
+			...(needsPlan === undefined ? {} : { needsPlan }),
+		},
+	};
+}
+
+function findPromotableTodo(
+	todoId: number,
+):
+	| { readonly ok: true; readonly value: Task }
+	| { readonly ok: false; readonly message: string } {
+	const todo = getState().tasks.find((task) => task.id === todoId);
+	if (todo === undefined) {
+		return { ok: false, message: `todo #${todoId} not found` };
+	}
+	if (todo.status === "deleted") {
+		return { ok: false, message: `todo #${todoId} is deleted` };
+	}
+	return { ok: true, value: todo };
+}
+
+function buildCreateArgv(todo: Task, params: ValidPromotionParams): string[] {
+	const argv = [
+		"create",
+		`--kind=${params.kind}`,
+		"-p",
+		String(params.priority),
+	];
+	const description =
+		params.description ?? normalizeOptionalString(todo.description);
+	if (description !== undefined) {
+		argv.push(`--description=${description}`);
+	}
+	if (params.parent !== undefined) {
+		argv.push(`--parent=${params.parent}`);
+	}
+	if (params.planned === true) {
+		argv.push("--planned");
+	} else if (params.needsPlan === true) {
+		argv.push("--needs-plan");
+	}
+	argv.push("--", todo.subject);
+	return argv;
+}
+
+function normalizeOptionalString(
+	value: string | undefined,
+): string | undefined {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function extractSimilarCandidates(result: unknown): readonly unknown[] {
+	if (Array.isArray(result)) return result;
+	if (isRecord(result) && Array.isArray(result.candidates)) {
+		return result.candidates;
+	}
+	return [];
+}
+
+function extractCreatedTaskId(result: unknown): string | undefined {
+	if (!isRecord(result)) return undefined;
+	const directId =
+		readNonEmptyString(result.id) ?? readNonEmptyString(result.task_id);
+	if (directId !== undefined) return directId;
+	if (isRecord(result.task)) {
+		return (
+			readNonEmptyString(result.task.id) ??
+			readNonEmptyString(result.task.task_id)
+		);
+	}
+	return undefined;
+}
+
+function readNonEmptyString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function errorResult(
+	code: string,
+	message: string,
+	details?: unknown,
+): AgentToolResult<TaskBridgeDetails> {
+	return textToolResult(
+		`Error: ${message}`,
+		errorToolDetails({
+			code,
+			message,
+			...(details === undefined ? {} : { details }),
+		}),
+	);
+}
+
+function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+
+function getErrorCode(error: unknown): string {
+	if (isRecord(error) && typeof error.code === "string") {
+		return error.code;
+	}
+	return "tsq_error";
+}
+
+function serializeError(error: unknown): unknown {
+	if (error instanceof Error) {
+		return {
+			name: error.name,
+			message: error.message,
+			...(isRecord(error) && typeof error.code === "string"
+				? { code: error.code }
+				: {}),
+		};
+	}
+	return error;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/bridge/types.ts

@@ -0,0 +1,156 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { Task, TaskStatus } from "../session-todos/tool/types.js";
+import type { StandardToolDetails } from "../shared/tool-result.js";
+
+export const TASK_BRIDGE_TOOL_NAME = "task_bridge";
+
+export const TASK_BRIDGE_ACTIONS = [
+	"link",
+	"list_links",
+	"promote_todo",
+	"import_tsq",
+] as const;
+
+export type TaskBridgeAction = (typeof TASK_BRIDGE_ACTIONS)[number];
+
+export const TaskBridgeParamsSchema = Type.Object(
+	{
+		action: StringEnum(TASK_BRIDGE_ACTIONS, {
+			description:
+				"Explicit bridge operation between session todo state and durable Tasque tasks.",
+		}),
+		todoId: Type.Optional(
+			Type.Integer({
+				description:
+					"Session todo id. Required for link and promote_todo actions.",
+				minimum: 1,
+			}),
+		),
+		tsqId: Type.Optional(
+			Type.String({
+				description:
+					"Durable Tasque task id. Required for link and import_tsq actions.",
+			}),
+		),
+		assignee: Type.Optional(
+			Type.String({
+				description:
+					"Agent/owner name used by promote_todo/import_tsq bridge actions.",
+			}),
+		),
+		owner: Type.Optional(
+			Type.String({
+				description: "Todo owner used by import_tsq bridge action.",
+			}),
+		),
+		kind: Type.Optional(
+			Type.String({
+				description: "Tasque task kind used by promote_todo bridge action.",
+			}),
+		),
+		priority: Type.Optional(
+			Type.Integer({
+				description: "Tasque priority used by promote_todo bridge action.",
+			}),
+		),
+		description: Type.Optional(
+			Type.String({
+				description: "Description override used by promote_todo bridge action.",
+			}),
+		),
+		parent: Type.Optional(
+			Type.String({
+				description:
+					"Parent Tasque task id used by promote_todo bridge action.",
+			}),
+		),
+		planned: Type.Optional(
+			Type.Boolean({
+				description: "Planning flag used by promote_todo bridge action.",
+			}),
+		),
+		needsPlan: Type.Optional(
+			Type.Boolean({
+				description: "Planning flag used by promote_todo bridge action.",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export type TaskBridgeParams = Static<typeof TaskBridgeParamsSchema>;
+
+export interface TaskBridgeLink {
+	readonly todoId: number;
+	readonly todoSubject: string;
+	readonly todoStatus: Exclude<TaskStatus, "deleted">;
+	readonly tsqId: string;
+}
+
+export interface TaskBridgeTodoSnapshot {
+	readonly tasks: readonly Task[];
+	readonly nextId: number;
+}
+
+export interface LinkBridgeParams extends TaskBridgeParams {
+	readonly action: "link";
+	readonly todoId?: number;
+	readonly tsqId?: string;
+}
+
+export interface ListLinksBridgeParams extends TaskBridgeParams {
+	readonly action: "list_links";
+}
+
+export interface PromoteTodoBridgeParams extends TaskBridgeParams {
+	readonly action: "promote_todo";
+	readonly todoId?: number;
+}
+
+export interface ImportTsqBridgeParams extends TaskBridgeParams {
+	readonly action: "import_tsq";
+	readonly tsqId?: string;
+}
+
+export type TaskBridgeSuccessData =
+	| {
+			readonly action: "link";
+			readonly link: TaskBridgeLink;
+			readonly todo: Task;
+	  }
+	| {
+			readonly action: "list_links";
+			readonly links: readonly TaskBridgeLink[];
+	  }
+	| {
+			readonly action: "promote_todo" | "import_tsq";
+			readonly todoSnapshot?: TaskBridgeTodoSnapshot;
+			readonly [key: string]: unknown;
+	  };
+
+export type TaskBridgeDetails = StandardToolDetails<TaskBridgeSuccessData>;
+
+export interface TaskBridgeHandlerContext {
+	readonly pi: ExtensionAPI;
+	readonly cwd: string;
+	readonly signal?: AbortSignal;
+	readonly extensionContext: ExtensionContext;
+}
+
+export type TaskBridgeActionHandler<TParams extends TaskBridgeParams> = (
+	params: TParams,
+	ctx: TaskBridgeHandlerContext,
+) =>
+	| AgentToolResult<TaskBridgeDetails>
+	| Promise<AgentToolResult<TaskBridgeDetails>>;
+
+export interface TaskBridgeHandlers {
+	readonly promote_todo?: TaskBridgeActionHandler<PromoteTodoBridgeParams>;
+	readonly import_tsq?: TaskBridgeActionHandler<ImportTsqBridgeParams>;
+}

package/src/durable-tasks/cache.ts

@@ -0,0 +1,167 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runTsqJson, type TsqRunContext } from "./runner.js";
+
+export interface TasqueStatusCacheState {
+	readonly readyCoding: number;
+	readonly readyPlanning: number;
+	readonly inProgressMine: number;
+	readonly refreshedAt: number | undefined;
+	readonly error: string | undefined;
+}
+
+export interface TasqueStatusCache {
+	readonly state: TasqueStatusCacheState;
+}
+
+export interface TasqueStatusRefreshOptions {
+	readonly now?: () => number;
+	readonly timeout?: number;
+	readonly signal?: AbortSignal;
+}
+
+export interface TasqueStatusFormatOptions {
+	readonly now?: () => number;
+	readonly staleAfterMs?: number;
+}
+
+const DEFAULT_REFRESH_TIMEOUT_MS = 4_000;
+const DEFAULT_STALE_AFTER_MS = 120_000;
+const MAX_ERROR_LENGTH = 80;
+
+export function createTasqueStatusCache(
+	state: Partial<TasqueStatusCacheState> = {},
+): TasqueStatusCache {
+	return {
+		state: {
+			readyCoding: state.readyCoding ?? 0,
+			readyPlanning: state.readyPlanning ?? 0,
+			inProgressMine: state.inProgressMine ?? 0,
+			refreshedAt: state.refreshedAt,
+			error: state.error,
+		},
+	};
+}
+
+export async function refreshTasqueStatusCache(
+	pi: ExtensionAPI,
+	ctx: TsqRunContext,
+	cache: TasqueStatusCache,
+	options: TasqueStatusRefreshOptions = {},
+): Promise<TasqueStatusCache> {
+	const now = options.now ?? Date.now;
+	const timeout = options.timeout ?? DEFAULT_REFRESH_TIMEOUT_MS;
+	const runOptions = {
+		timeout,
+		...(options.signal === undefined ? {} : { signal: options.signal }),
+	};
+
+	try {
+		await runTsqJson<unknown>(pi, ctx, ["doctor"], runOptions);
+		const [readyCoding, readyPlanning, inProgressMine] = await Promise.all([
+			runTsqJson<unknown>(
+				pi,
+				ctx,
+				["find", "ready", "--lane", "coding"],
+				runOptions,
+			),
+			runTsqJson<unknown>(
+				pi,
+				ctx,
+				["find", "ready", "--lane", "planning"],
+				runOptions,
+			),
+			runTsqJson<unknown>(
+				pi,
+				ctx,
+				["find", "in-progress", "--assignee", "pi"],
+				runOptions,
+			),
+		]);
+
+		return createTasqueStatusCache({
+			readyCoding: countTasks(readyCoding),
+			readyPlanning: countTasks(readyPlanning),
+			inProgressMine: countTasks(inProgressMine),
+			refreshedAt: now(),
+			error: undefined,
+		});
+	} catch (error) {
+		return createTasqueStatusCache({
+			...cache.state,
+			error: getErrorMessage(error),
+		});
+	}
+}
+
+export function formatTasqueStatusText(
+	state: TasqueStatusCacheState,
+	options: TasqueStatusFormatOptions = {},
+): string {
+	if (state.error !== undefined) {
+		return `tsq: stale · ${state.error}`;
+	}
+
+	if (state.refreshedAt === undefined) {
+		return "tsq: loading";
+	}
+
+	const now = options.now ?? Date.now;
+	const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+	const ageMs = Math.max(0, now() - state.refreshedAt);
+	const counts = formatCounts(state);
+
+	if (ageMs > staleAfterMs) {
+		return `tsq: stale ${formatAge(ageMs)} · ${counts}`;
+	}
+
+	return `tsq: ${counts} · ${formatAge(ageMs)}`;
+}
+
+function formatCounts(state: TasqueStatusCacheState): string {
+	return `coding ${state.readyCoding} · planning ${state.readyPlanning} · mine ${state.inProgressMine}`;
+}
+
+function countTasks(data: unknown): number {
+	if (Array.isArray(data)) {
+		return data.length;
+	}
+	if (!isRecord(data)) {
+		return 0;
+	}
+	if (Array.isArray(data.tasks)) {
+		return data.tasks.length;
+	}
+	if (Array.isArray(data.tree)) {
+		return data.tree.length;
+	}
+	return 0;
+}
+
+function formatAge(ageMs: number): string {
+	const seconds = Math.floor(ageMs / 1_000);
+	if (seconds < 60) {
+		return `${seconds}s`;
+	}
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) {
+		return `${minutes}m`;
+	}
+	const hours = Math.floor(minutes / 60);
+	return `${hours}h`;
+}
+
+function getErrorMessage(error: unknown): string {
+	const message = error instanceof Error ? error.message : String(error);
+	return truncateInline(message.replace(/\s+/gu, " ").trim(), MAX_ERROR_LENGTH);
+}
+
+function truncateInline(text: string, maxLength: number): string {
+	if (text.length <= maxLength) {
+		return text;
+	}
+	return `${text.slice(0, Math.max(0, maxLength - 1))}…`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/durable-tasks/mutation-queue.ts

@@ -0,0 +1,30 @@
+type MutationFunction<T> = () => T | Promise<T>;
+
+const queueTailsByCwd = new Map<string, Promise<void>>();
+
+export function runQueuedMutation<T>(
+	cwd: string,
+	fn: MutationFunction<T>,
+): Promise<T> {
+	const previousTail = queueTailsByCwd.get(cwd) ?? Promise.resolve();
+	const operation = previousTail.then(fn, fn);
+	const tail = operation.then(
+		() => undefined,
+		() => undefined,
+	);
+
+	queueTailsByCwd.set(cwd, tail);
+
+	void tail.finally(() => {
+		if (queueTailsByCwd.get(cwd) === tail) {
+			queueTailsByCwd.delete(cwd);
+		}
+	});
+
+	return operation;
+}
+
+/** @internal Exposed for queue cleanup tests. */
+export function getQueuedMutationCwdCount(): number {
+	return queueTailsByCwd.size;
+}