@roodriigoooo/pi-docket 0.4.0

package/extensions/checkpoint-summarizer.ts

@@ -0,0 +1,141 @@
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { gitSnapshotLabel } from "./git-context.js";
+import type { CheckpointMode, GitSnapshot } from "./types.js";
+
+export type CheckpointSummarizerConfig = {
+	enabled: boolean;
+	provider?: string;
+	model?: string;
+	maxOutputTokens: number;
+	maxInputChars: number;
+	timeoutMs: number;
+	systemPrompt?: string;
+};
+
+type CheckpointSummarizerInput = {
+	id: string;
+	mode: CheckpointMode;
+	note: string;
+	consumeOnUse: boolean;
+	cwd: string;
+	sourceSession?: string;
+	git?: GitSnapshot;
+	artifactsFile: string;
+	payload: Array<Record<string, unknown>>;
+	references: string;
+	activeModel: ExtensionCommandContext["model"];
+	modelRegistry: ExtensionCommandContext["modelRegistry"];
+	config: CheckpointSummarizerConfig;
+	overrides: { model?: string; maxOutputTokens?: number };
+};
+
+export type CheckpointSummarizer = {
+	summarize(input: CheckpointSummarizerInput): Promise<string>;
+};
+
+function truncate(text: string, max: number): string {
+	if (text.length <= max) return text;
+	return `${text.slice(0, max)}\n\n[Docket truncated ${text.length - max} chars]`;
+}
+
+function checkpointSystemPrompt(mode: CheckpointMode, maxOutputTokens: number): string {
+	const modeGuidance: Record<CheckpointMode, string> = {
+		handoff: "Preserve continuity for a fresh coding-agent session. Prioritize current goal, decisions, edited/important files, and next steps.",
+		compact: "Make the smallest useful continuation note. Ruthlessly remove transcript noise and low-value details.",
+		debug: "Focus on failing commands, error messages, hypotheses already tried, likely root causes, and safest next debugging steps.",
+		review: "Focus on review state: changed files, design decisions, risks, test status, and what a reviewer should inspect next.",
+	};
+	return [
+		"You are Docket, a context distillation assistant for Pi coding sessions.",
+		"Summarize session artifacts into a fresh-session checkpoint.",
+		"Optimize for fresh-session continuation, not transcript preservation.",
+		"Include only restart-critical context: goal, current state, decisions, failed attempts, dead ends, next steps, and references.",
+		"Prefer compact artifact references over pasted content; quote exact output only when it changes the next action.",
+		"Separate facts from hypotheses. Never present unknowns, guesses, or stale plans as decisions.",
+		"Make failure history explicit enough to avoid repeats, but remove redundant logs and low-signal output.",
+		"Do not produce a transcript search result or artifact dump.",
+		"Use compact markdown. Target the requested maximum output length.",
+		"Reference artifacts by IDs like [file:f12] or [command:c8] when useful instead of copying large excerpts.",
+		"If file-reference guidance is needed, say it once for the reference list, not once per file.",
+		"Never invent files, commands, decisions, or outcomes not present in artifacts.",
+		`Mode: ${mode}. ${modeGuidance[mode]}`,
+		`Maximum output tokens: ${maxOutputTokens}.`,
+	].join("\n");
+}
+
+function checkpointInput(input: CheckpointSummarizerInput): string {
+	return truncate([
+		`cwd: ${input.cwd}`,
+		input.sourceSession ? `sourceSession: ${input.sourceSession}` : undefined,
+		gitSnapshotLabel(input.git) ? `git: ${gitSnapshotLabel(input.git)}` : undefined,
+		`mode: ${input.mode}`,
+		input.note ? `userNote: ${input.note}` : undefined,
+		"",
+		"Write checkpoint markdown with these sections:",
+		"## Summary",
+		"## Decisions / constraints",
+		"## Current state",
+		"## Next steps",
+		"## Avoid repeating",
+		"## References",
+		"",
+		"References available:",
+		input.references,
+		"",
+		"Artifacts JSON:",
+		JSON.stringify(input.payload, null, 2),
+	].filter((line): line is string => line !== undefined).join("\n"), input.config.maxInputChars);
+}
+
+export function createCheckpointSummarizer(): CheckpointSummarizer {
+	return {
+		async summarize(input: CheckpointSummarizerInput): Promise<string> {
+			const maxOutputTokens = input.overrides.maxOutputTokens ?? input.config.maxOutputTokens;
+			const modelName = input.overrides.model ?? (input.config.provider && input.config.model ? `${input.config.provider}/${input.config.model}` : undefined);
+			const model = modelName
+				? (() => {
+					const [provider, ...rest] = modelName.split("/");
+					return provider && rest.length ? input.modelRegistry.find(provider, rest.join("/")) : undefined;
+				})()
+				: input.activeModel;
+			if (!model) throw new Error("No Docket summarizer model configured and no active model selected");
+
+			const auth = await input.modelRegistry.getApiKeyAndHeaders(model);
+			if (!auth.ok || !auth.apiKey) throw new Error(auth.ok ? `No API key for ${model.provider}` : auth.error);
+
+			const userMessage: Message = {
+				role: "user",
+				content: [{ type: "text", text: checkpointInput(input) }],
+				timestamp: Date.now(),
+			};
+			const response = await complete(
+				model,
+				{ systemPrompt: input.config.systemPrompt ?? checkpointSystemPrompt(input.mode, maxOutputTokens), messages: [userMessage] },
+				{ apiKey: auth.apiKey, headers: auth.headers, maxTokens: maxOutputTokens, timeoutMs: input.config.timeoutMs },
+			);
+			const summary = response.content.filter((c): c is { type: "text"; text: string } => c.type === "text").map((c) => c.text).join("\n").trim();
+			if (!summary) throw new Error("Docket summarizer returned empty checkpoint");
+
+			const lines: string[] = [];
+			lines.push(`# Docket checkpoint ${input.id}`);
+			lines.push("");
+			lines.push(`mode: ${input.mode}`);
+			lines.push("summary: llm");
+			lines.push(`cwd: ${input.cwd}`);
+			lines.push(`created: ${new Date().toISOString()}`);
+			if (input.sourceSession) lines.push(`sourceSession: ${input.sourceSession}`);
+			const gitLabel = gitSnapshotLabel(input.git);
+			if (gitLabel) lines.push(`git: ${gitLabel}`);
+			if (input.note) lines.push(`note: ${input.note}`);
+			if (input.consumeOnUse) lines.push("consumeOnUse: true");
+			lines.push(`artifacts: ${input.artifactsFile}`);
+			lines.push("");
+			lines.push(summary);
+			lines.push("");
+			lines.push("## Docket artifact references");
+			lines.push(input.references);
+			return lines.join("\n");
+		},
+	};
+}

package/extensions/docket-command-grammar.ts

@@ -0,0 +1,319 @@
+export type CheckpointCreateOptions = {
+	note: string;
+	consumeOnUse: boolean;
+	/** Opt-in: add a model-written prose summary on top of the deterministic bundle header. */
+	summarize: boolean;
+	model?: string;
+	maxOutputTokens?: number;
+};
+
+export type DocketIntent =
+	| { kind: "help"; advanced?: boolean }
+	| { kind: "browse"; mode?: "review" | "answers" | "log" }
+	| { kind: "clear" }
+	| { kind: "save"; options: CheckpointCreateOptions }
+	| { kind: "delete"; target: string | undefined; targetKind: "checkpoint" | "worker" }
+	| { kind: "list"; includeConsumed?: boolean; workers?: boolean; allProjects?: boolean }
+	| { kind: "load"; ref?: string; includeConsumed?: boolean; refKind: "checkpoint" | "worker" }
+	| { kind: "unload"; target: string; targetKind: "checkpoint" | "worker" | "all" }
+	| { kind: "spawn"; task: string; worktree?: boolean; fresh?: boolean; as?: string }
+	| { kind: "kinds" }
+	| { kind: "respawn"; target: string }
+	| { kind: "workers"; allProjects?: boolean }
+	| { kind: "verdict"; worker?: string }
+	| { kind: "tell"; worker: string; text?: string }
+	| { kind: "attach"; worker?: string }
+	| { kind: "worker-state"; state: "needs_input" | "ready" | "failed"; text?: string }
+	| { kind: "answers"; query?: string }
+	| { kind: "search"; query: string }
+	| { kind: "artifact"; action: "ref" | "inject-full" | "copy"; idOrRef: string };
+
+export type ParseResult =
+	| { ok: true; intent: DocketIntent }
+	| { ok: false; message: string; usage: string };
+
+export const DOCKET_COMMANDS = ["answers", "attach", "clear", "copy", "delete", "done", "fail", "help", "inject-full", "kinds", "list", "load", "log", "ref", "respawn", "save", "search", "spawn", "tell", "unload", "verdict", "wait", "workers"] as const;
+
+const WORKER_PREFIX = "w:";
+const WORKER_SHORT = /^w(\d+)$/i;
+
+function stripWorkerPrefix(value: string): { id: string; isWorker: boolean } {
+	if (value.startsWith(WORKER_PREFIX)) return { id: value.slice(WORKER_PREFIX.length), isWorker: true };
+	if (WORKER_SHORT.test(value)) return { id: value, isWorker: true };
+	return { id: value, isWorker: false };
+}
+
+const SAVE_USAGE = "/docket save [--once] [--summarize [--model <provider/model>] [--max-output <tokens>]] [--] [note]";
+const BOOLEAN_FLAGS = new Set(["--once", "--delete-on-use", "--summarize"]);
+const VALUE_FLAGS = new Set(["--model", "--max-output"]);
+
+export function docketUsage(advanced = false): string {
+	const primary = [
+		"Docket · core loop:",
+		"/docket                         open decision docket",
+		"/docket spawn [--fresh] [--as <kind>] <task>  start explicit background worker",
+		"/docket tell w<N> [text]        reply to a worker",
+		"/docket attach [w<N>]           print/copy tmux attach command for the shared worker session",
+		"/docket save [flags] [note]     save selected evidence as a zero-token bundle",
+		"/docket load [id|last|w<N>]     mount bundle/worker artifacts without model tokens",
+		"",
+		"more: /docket help advanced",
+	];
+	if (!advanced) return primary.join("\n");
+	return [
+		...primary,
+		"",
+		"Docket · advanced:",
+		"/docket answers [query]         browse assistant/worker answers",
+		"/docket log                     audit timeline grouped by episode",
+		"/docket search <query>          ranked artifact search",
+		"/docket workers [--all]         worker dashboard",
+		"/docket verdict [w<N>]          decide worker outcome (accept/reject/chat)",
+		"/docket kinds                   list registered worker kinds",
+		"/docket respawn <w<N>|all>      relaunch a worker whose tmux window died",
+		SAVE_USAGE,
+		"/docket load [id|last|w<N>] [--include-consumed]   mount bundle or worker artifacts (no model tokens)",
+		"/docket unload <id|w<N>|all>    drop a loaded slot",
+		"/docket delete [id|last|w<N>]",
+		"/docket list [--include-consumed] [--workers|--all]",
+		"/docket ref <artifact-id>       attach compact chip (@id) above editor",
+		"/docket inject-full <artifact-id>  attach full chip (@id*) above editor",
+		"/docket copy <artifact-id>      copy artifact to clipboard",
+		"/docket clear                   drop all pending chips",
+		"/docket wait <question>         worker fallback: ask parent for input",
+		"/docket done [summary]          worker fallback: mark output ready",
+		"/docket fail <reason>           worker fallback: mark work failed",
+	].join("\n");
+}
+
+function parseError(message: string, usage = docketUsage()): ParseResult {
+	return { ok: false, message, usage };
+}
+
+function tokenize(input: string): { ok: true; tokens: string[] } | { ok: false; message: string } {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: "'" | '"' | undefined;
+	let escaping = false;
+
+	for (const char of input) {
+		if (escaping) {
+			current += char;
+			escaping = false;
+			continue;
+		}
+		if (char === "\\") {
+			escaping = true;
+			continue;
+		}
+		if (quote) {
+			if (char === quote) quote = undefined;
+			else current += char;
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			quote = char;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+
+	if (escaping) current += "\\";
+	if (quote) return { ok: false, message: `Unclosed ${quote} quote` };
+	if (current) tokens.push(current);
+	return { ok: true, tokens };
+}
+
+function parseDeleteCommand(rest: string[]): ParseResult {
+	if (rest.length === 0) return { ok: true, intent: { kind: "delete", target: undefined, targetKind: "checkpoint" } };
+	if (rest.length > 1) return parseError("Usage: /docket delete [id|last|w:<worker>]");
+	const { id, isWorker } = stripWorkerPrefix(rest[0]!);
+	return { ok: true, intent: { kind: "delete", target: id, targetKind: isWorker ? "worker" : "checkpoint" } };
+}
+
+function requireArtifactArg(action: "ref" | "inject-full" | "copy", rest: string[]): ParseResult {
+	if (rest.length !== 1) return parseError(`Usage: /docket ${action} <artifact-id>`);
+	return { ok: true, intent: { kind: "artifact", action, idOrRef: rest[0]! } };
+}
+
+function parseSave(tokens: string[]): ParseResult {
+	let consumeOnUse = false;
+	let summarize = false;
+	let model: string | undefined;
+	let maxOutputTokens: number | undefined;
+	const noteParts: string[] = [];
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i]!;
+		if (token === "--") {
+			noteParts.push(...tokens.slice(i + 1));
+			break;
+		}
+		if (BOOLEAN_FLAGS.has(token)) {
+			if (token === "--once" || token === "--delete-on-use") consumeOnUse = true;
+			else summarize = true;
+			continue;
+		}
+		if (VALUE_FLAGS.has(token)) {
+			const value = tokens[++i];
+			if (!value) return parseError(`Missing value for ${token}`, SAVE_USAGE);
+			if (token === "--model") model = value;
+			else {
+				const parsed = Number(value);
+				if (!Number.isInteger(parsed) || parsed <= 0) return parseError("--max-output must be a positive integer", SAVE_USAGE);
+				maxOutputTokens = parsed;
+			}
+			// --model/--max-output only make sense with a summary; imply it.
+			summarize = true;
+			continue;
+		}
+		if (token.startsWith("--")) return parseError(`Unknown save flag: ${token}`, SAVE_USAGE);
+		noteParts.push(token);
+	}
+
+	return { ok: true, intent: { kind: "save", options: { note: noteParts.join(" "), consumeOnUse, summarize, model, maxOutputTokens } } };
+}
+
+export function parseDocketWorkerShellCommand(command: string): Extract<DocketIntent, { kind: "worker-state" }> | undefined {
+	const lines = command.trim().split(/\r?\n/).filter((line) => line.trim().length > 0);
+	if (lines.length !== 1) return undefined;
+	const line = lines[0]!.trim();
+	const match = line.match(/^\/?docket(?:\s+([\s\S]*))?$/);
+	if (!match) return undefined;
+	const parsed = parseDocketCommand(match[1] ?? "");
+	if (!parsed.ok || parsed.intent.kind !== "worker-state") return undefined;
+	return parsed.intent;
+}
+
+export function parseDocketCommand(args: string): ParseResult {
+	const tokenized = tokenize(args.trim());
+	if (!tokenized.ok) return parseError(tokenized.message);
+	const [command = "", ...rest] = tokenized.tokens;
+
+	if (command === "") return { ok: true, intent: { kind: "browse", mode: "review" } };
+	if (command === "log") return { ok: true, intent: { kind: "browse", mode: "log" } };
+	if (command === "help" || command === "--help" || command === "-h") {
+		const advanced = rest.some((token) => token === "advanced" || token === "--advanced" || token === "all" || token === "--all");
+		return { ok: true, intent: { kind: "help", ...(advanced ? { advanced: true } : {}) } };
+	}
+	if (command === "save") return parseSave(rest);
+	if (command === "delete") return parseDeleteCommand(rest);
+	if (command === "list") {
+		let includeConsumed = false;
+		let workers = false;
+		let allProjects = false;
+		const extras: string[] = [];
+		for (const token of rest) {
+			if (token === "--include-consumed") includeConsumed = true;
+			else if (token === "--workers") workers = true;
+			else if (token === "--all") { workers = true; allProjects = true; }
+			else extras.push(token);
+		}
+		if (extras.length > 0) return parseError("Usage: /docket list [--include-consumed] [--workers|--all]");
+		return { ok: true, intent: { kind: "list", includeConsumed, workers, ...(allProjects ? { allProjects } : {}) } };
+	}
+	if (command === "load") {
+		let includeConsumed = false;
+		const positional: string[] = [];
+		for (const token of rest) {
+			if (token === "--include-consumed") includeConsumed = true;
+			else positional.push(token);
+		}
+		if (positional.length > 1) return parseError("Usage: /docket load [id|last|w:<worker>] [--include-consumed]");
+		const raw = positional[0];
+		if (!raw) return { ok: true, intent: { kind: "load", ref: undefined, includeConsumed, refKind: "checkpoint" } };
+		const { id, isWorker } = stripWorkerPrefix(raw);
+		return { ok: true, intent: { kind: "load", ref: id, includeConsumed, refKind: isWorker ? "worker" : "checkpoint" } };
+	}
+	if (command === "unload") {
+		if (rest.length !== 1) return parseError("Usage: /docket unload <id|w:<worker>|all>");
+		const raw = rest[0]!;
+		if (raw === "all") return { ok: true, intent: { kind: "unload", target: "all", targetKind: "all" } };
+		const { id, isWorker } = stripWorkerPrefix(raw);
+		return { ok: true, intent: { kind: "unload", target: id, targetKind: isWorker ? "worker" : "checkpoint" } };
+	}
+	if (command === "spawn") {
+		let worktree = false;
+		let fresh = false;
+		let as: string | undefined;
+		const taskParts: string[] = [];
+		for (let i = 0; i < rest.length; i++) {
+			const token = rest[i]!;
+			if (token === "--worktree" || token === "-w") worktree = true;
+			else if (token === "--fresh") fresh = true;
+			else if (token === "--as" || token === "-a") {
+				const value = rest[++i];
+				if (!value) return parseError("Usage: /docket spawn [--fresh] [--as <kind>] <task>");
+				as = value;
+			} else if (token.startsWith("--as=")) {
+				as = token.slice("--as=".length);
+			} else {
+				taskParts.push(token);
+			}
+		}
+		if (taskParts.length === 0) return parseError("Usage: /docket spawn [--fresh] [--as <kind>] <task>");
+		return { ok: true, intent: { kind: "spawn", task: taskParts.join(" "), ...(worktree ? { worktree } : {}), ...(fresh ? { fresh } : {}), ...(as ? { as } : {}) } };
+	}
+	if (command === "workers") {
+		let allProjects = false;
+		const extras: string[] = [];
+		for (const token of rest) {
+			if (token === "--all") allProjects = true;
+			else extras.push(token);
+		}
+		if (extras.length > 0) return parseError("Usage: /docket workers [--all]");
+		return { ok: true, intent: { kind: "workers", ...(allProjects ? { allProjects } : {}) } };
+	}
+	if (command === "verdict") {
+		if (rest.length > 1) return parseError("Usage: /docket verdict [w<N>]");
+		return { ok: true, intent: { kind: "verdict", ...(rest[0] ? { worker: rest[0] } : {}) } };
+	}
+	if (command === "kinds") {
+		if (rest.length > 0) return parseError("Usage: /docket kinds");
+		return { ok: true, intent: { kind: "kinds" } };
+	}
+	if (command === "respawn") {
+		if (rest.length !== 1) return parseError("Usage: /docket respawn <w<N>|all>");
+		return { ok: true, intent: { kind: "respawn", target: rest[0]! } };
+	}
+	if (command === "tell") {
+		if (rest.length < 1) return parseError("Usage: /docket tell w<N> [text]");
+		return { ok: true, intent: { kind: "tell", worker: rest[0]!, text: rest.length > 1 ? rest.slice(1).join(" ") : undefined } };
+	}
+	if (command === "attach") {
+		if (rest.length === 0) return { ok: true, intent: { kind: "attach" } };
+		if (rest.length > 1) return parseError("Usage: /docket attach [w<N>]");
+		return { ok: true, intent: { kind: "attach", worker: rest[0]! } };
+	}
+	if (command === "wait") {
+		if (rest.length === 0) return parseError("Usage: /docket wait <question>");
+		return { ok: true, intent: { kind: "worker-state", state: "needs_input", text: rest.join(" ") } };
+	}
+	if (command === "done") {
+		return { ok: true, intent: { kind: "worker-state", state: "ready", text: rest.length ? rest.join(" ") : undefined } };
+	}
+	if (command === "fail") {
+		if (rest.length === 0) return parseError("Usage: /docket fail <reason>");
+		return { ok: true, intent: { kind: "worker-state", state: "failed", text: rest.join(" ") } };
+	}
+	if (command === "answers") {
+		return { ok: true, intent: { kind: "answers", query: rest.length ? rest.join(" ") : undefined } };
+	}
+	if (command === "clear") {
+		if (rest.length > 0) return parseError("Usage: /docket clear");
+		return { ok: true, intent: { kind: "clear" } };
+	}
+	if (command === "search") {
+		if (rest.length === 0) return parseError("Usage: /docket search <query>");
+		return { ok: true, intent: { kind: "search", query: rest.join(" ") } };
+	}
+	if (command === "ref" || command === "inject-full" || command === "copy") return requireArtifactArg(command, rest);
+	return parseError(`Unknown Docket command: ${command}`);
+}