@bumpyclock/pi-tasque 0.1.0

package/src/durable-tasks/runner.ts

@@ -0,0 +1,234 @@
+import type {
+	ExecOptions,
+	ExecResult,
+	ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import {
+	TSQ_SCHEMA_VERSION,
+	type JsonValue,
+	type TsqEnvelope,
+	type TsqErr,
+} from "./types.js";
+
+export interface TsqRunContext {
+	readonly cwd: string;
+}
+
+export interface TsqRunOptions {
+	readonly timeout?: number;
+	readonly signal?: AbortSignal;
+}
+
+export class TsqCommandError extends Error {
+	override readonly name = "TsqCommandError";
+	readonly code: string;
+	readonly command: string;
+	readonly details?: JsonValue;
+	readonly envelope: TsqErr;
+
+	constructor(envelope: TsqErr) {
+		super(envelope.error.message);
+		this.code = envelope.error.code;
+		this.command = envelope.command;
+		this.envelope = envelope;
+		const { details } = envelope.error;
+		if (details !== undefined) {
+			this.details = details;
+		}
+	}
+}
+
+export class TsqProcessError extends Error {
+	override readonly name = "TsqProcessError";
+	readonly code: number;
+	readonly stderr: string;
+	readonly stdout: string;
+	readonly killed: boolean;
+	readonly args: readonly string[];
+	override readonly cause?: unknown;
+
+	constructor(result: ExecResult, args: readonly string[], cause?: unknown) {
+		super(buildProcessErrorMessage(result));
+		this.code = result.code;
+		this.stderr = result.stderr;
+		this.stdout = result.stdout;
+		this.killed = result.killed;
+		this.args = [...args];
+		if (cause !== undefined) {
+			this.cause = cause;
+		}
+	}
+}
+
+export async function runTsqJson<TData>(
+	pi: ExtensionAPI,
+	ctx: TsqRunContext,
+	args: readonly string[],
+	options: TsqRunOptions = {},
+): Promise<TData> {
+	const execArgs = buildJsonArgs(args);
+	const result = await pi.exec("tsq", execArgs, buildExecOptions(ctx, options));
+
+	if (result.killed) {
+		throw new TsqProcessError(result, execArgs);
+	}
+
+	let envelope: TsqEnvelope<unknown>;
+	try {
+		envelope = parseTsqEnvelope(result.stdout);
+	} catch (error) {
+		if (result.code !== 0) {
+			throw new TsqProcessError(result, execArgs, error);
+		}
+		throw error;
+	}
+
+	if (!envelope.ok) {
+		throw new TsqCommandError(envelope);
+	}
+
+	if (result.code !== 0) {
+		throw new TsqProcessError(result, execArgs);
+	}
+
+	return envelope.data as TData;
+}
+
+export function parseTsqEnvelope(stdout: string): TsqEnvelope<unknown> {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch {
+		throw new Error("tsq returned invalid JSON");
+	}
+
+	if (!isRecord(parsed)) {
+		throw new Error(
+			"tsq returned invalid JSON envelope: root must be an object",
+		);
+	}
+
+	if (!("schema_version" in parsed)) {
+		throw new Error(
+			"tsq returned invalid JSON envelope: schema_version is required",
+		);
+	}
+	if (parsed.schema_version !== TSQ_SCHEMA_VERSION) {
+		throw new Error(
+			`tsq returned unsupported schema version: ${String(parsed.schema_version)}`,
+		);
+	}
+
+	if (typeof parsed.command !== "string") {
+		throw new Error(
+			"tsq returned invalid JSON envelope: command must be a string",
+		);
+	}
+
+	if (typeof parsed.ok !== "boolean") {
+		throw new Error("tsq returned invalid JSON envelope: ok must be boolean");
+	}
+
+	if (parsed.ok) {
+		if (!("data" in parsed)) {
+			throw new Error(
+				"tsq returned invalid JSON envelope: data is required when ok is true",
+			);
+		}
+		return parsed as unknown as TsqEnvelope<unknown>;
+	}
+
+	if (!isRecord(parsed.error)) {
+		throw new Error(
+			"tsq returned invalid JSON envelope: error is required when ok is false",
+		);
+	}
+	if (typeof parsed.error.code !== "string") {
+		throw new Error(
+			"tsq returned invalid JSON envelope: error.code must be a string",
+		);
+	}
+	if (typeof parsed.error.message !== "string") {
+		throw new Error(
+			"tsq returned invalid JSON envelope: error.message must be a string",
+		);
+	}
+
+	return parsed as unknown as TsqEnvelope<unknown>;
+}
+
+function buildJsonArgs(args: readonly string[]): string[] {
+	let hasJsonFormat = false;
+	const separatorIndex = args.indexOf("--");
+	const optionEndIndex = separatorIndex === -1 ? args.length : separatorIndex;
+
+	for (let index = 0; index < optionEndIndex; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) {
+			continue;
+		}
+		if (arg === "--format") {
+			const value = args[index + 1];
+			if (value === "json") {
+				hasJsonFormat = true;
+				index += 1;
+				continue;
+			}
+			const received =
+				value === undefined ? "--format without a value" : `--format ${value}`;
+			throw new Error(buildFormatError(received));
+		}
+
+		if (arg.startsWith("--format=")) {
+			const value = arg.slice("--format=".length);
+			if (value === "json") {
+				hasJsonFormat = true;
+				continue;
+			}
+			throw new Error(buildFormatError(arg));
+		}
+	}
+
+	if (hasJsonFormat) {
+		return [...args];
+	}
+
+	if (separatorIndex === -1) {
+		return [...args, "--format", "json"];
+	}
+
+	return [
+		...args.slice(0, separatorIndex),
+		"--format",
+		"json",
+		...args.slice(separatorIndex),
+	];
+}
+
+function buildFormatError(received: string): string {
+	return `runTsqJson requires JSON format output; received ${received}`;
+}
+
+function buildExecOptions(
+	ctx: TsqRunContext,
+	options: TsqRunOptions,
+): ExecOptions {
+	return {
+		cwd: ctx.cwd,
+		...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+		...(options.signal === undefined ? {} : { signal: options.signal }),
+	};
+}
+
+function buildProcessErrorMessage(result: ExecResult): string {
+	const summary = result.stderr.trim() || result.stdout.trim();
+	const killed = result.killed ? " (killed)" : "";
+	if (summary.length === 0) {
+		return `tsq failed with exit code ${result.code}${killed}`;
+	}
+	return `tsq failed with exit code ${result.code}${killed}: ${summary}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/durable-tasks/status.ts

@@ -0,0 +1,184 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+	createTasqueStatusCache,
+	formatTasqueStatusText,
+	refreshTasqueStatusCache,
+	type TasqueStatusCache,
+} from "./cache.js";
+
+export const TASQUE_STATUS_KEY = "pi-tasque";
+
+const MUTATING_TOOL_NAMES = new Set(["tsq_change", "tsq_claim", "task_bridge"]);
+const DEFAULT_INTERVAL_MS = 60_000;
+
+export interface TasqueStatusLifecycleOptions {
+	readonly intervalMs?: number;
+	readonly refreshTimeoutMs?: number;
+	readonly now?: () => number;
+	readonly staleAfterMs?: number;
+}
+
+interface ToolExecutionEndLike {
+	readonly isError: boolean;
+	readonly toolName: string;
+	readonly result: unknown;
+}
+
+export function registerTasqueStatusLifecycle(
+	pi: ExtensionAPI,
+	options: TasqueStatusLifecycleOptions = {},
+): void {
+	let cache: TasqueStatusCache = createTasqueStatusCache();
+	let interval: ReturnType<typeof setInterval> | undefined;
+	let latestContext: ExtensionContext | undefined;
+	let refreshInFlight: Promise<void> | undefined;
+	let refreshInFlightGeneration: number | undefined;
+	let queuedRefreshContext: ExtensionContext | undefined;
+	let lifecycleGeneration = 0;
+	let statusActive = true;
+
+	async function refresh(ctx: ExtensionContext): Promise<void> {
+		if (!statusActive || !hasStatusUi(ctx)) {
+			return;
+		}
+
+		latestContext = ctx;
+		const generation = lifecycleGeneration;
+		if (
+			refreshInFlight !== undefined &&
+			refreshInFlightGeneration === generation
+		) {
+			queuedRefreshContext = ctx;
+			return refreshInFlight;
+		}
+
+		let refreshPromise: Promise<void>;
+		refreshPromise = refreshTasqueStatusCache(pi, { cwd: ctx.cwd }, cache, {
+			...(options.now === undefined ? {} : { now: options.now }),
+			...(options.refreshTimeoutMs === undefined
+				? {}
+				: { timeout: options.refreshTimeoutMs }),
+		})
+			.then((nextCache) => {
+				if (!statusActive || generation !== lifecycleGeneration) {
+					return;
+				}
+				cache = nextCache;
+				ctx.ui.setStatus(
+					TASQUE_STATUS_KEY,
+					formatTasqueStatusText(cache.state, {
+						...(options.now === undefined ? {} : { now: options.now }),
+						...(options.staleAfterMs === undefined
+							? {}
+							: { staleAfterMs: options.staleAfterMs }),
+					}),
+				);
+			})
+			.finally(async () => {
+				const isCurrentRefresh =
+					refreshInFlight === refreshPromise &&
+					refreshInFlightGeneration === generation;
+				if (isCurrentRefresh) {
+					refreshInFlight = undefined;
+					refreshInFlightGeneration = undefined;
+				}
+				if (
+					!isCurrentRefresh ||
+					!statusActive ||
+					generation !== lifecycleGeneration
+				) {
+					return;
+				}
+				const nextContext = queuedRefreshContext;
+				queuedRefreshContext = undefined;
+				if (nextContext === undefined) {
+					return;
+				}
+				await refresh(nextContext);
+			});
+
+		refreshInFlight = refreshPromise;
+		refreshInFlightGeneration = generation;
+		return refreshPromise;
+	}
+
+	function clearRefreshInterval(): void {
+		if (interval !== undefined) {
+			clearInterval(interval);
+			interval = undefined;
+		}
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		clearRefreshInterval();
+		if (!hasStatusUi(ctx)) {
+			return;
+		}
+		lifecycleGeneration += 1;
+		refreshInFlight = undefined;
+		refreshInFlightGeneration = undefined;
+		queuedRefreshContext = undefined;
+		statusActive = true;
+		latestContext = ctx;
+		interval = setInterval(() => {
+			const ctxForRefresh = latestContext;
+			if (ctxForRefresh !== undefined) {
+				void refresh(ctxForRefresh);
+			}
+		}, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+		await refresh(ctx);
+	});
+
+	pi.on("tool_execution_end", async (event, ctx) => {
+		if (!shouldRefreshAfterTool(event) || !hasStatusUi(ctx)) {
+			return;
+		}
+		await refresh(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		clearRefreshInterval();
+		lifecycleGeneration += 1;
+		latestContext = undefined;
+		refreshInFlight = undefined;
+		refreshInFlightGeneration = undefined;
+		queuedRefreshContext = undefined;
+		statusActive = false;
+		if (hasStatusUi(ctx)) {
+			ctx.ui.setStatus(TASQUE_STATUS_KEY, undefined);
+		}
+	});
+}
+
+function shouldRefreshAfterTool(event: ToolExecutionEndLike): boolean {
+	if (event.isError || !MUTATING_TOOL_NAMES.has(event.toolName)) {
+		return false;
+	}
+	return getDetailsOk(event.result) !== false;
+}
+
+function getDetailsOk(result: unknown): boolean | undefined {
+	if (!isRecord(result)) {
+		return undefined;
+	}
+	const details = result.details;
+	if (!isRecord(details)) {
+		return undefined;
+	}
+	return typeof details.ok === "boolean" ? details.ok : undefined;
+}
+
+function hasStatusUi(ctx: ExtensionContext): boolean {
+	return (
+		ctx.hasUI === true &&
+		isRecord(ctx.ui) &&
+		typeof ctx.ui.setStatus === "function"
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}