@roodriigoooo/pi-docket 0.4.0

package/extensions/worker-kinds/patcher.md

@@ -0,0 +1,23 @@
+---
+name: patcher
+description: Edits files in the worker's worktree and proposes a change set for review.
+read_only: false
+default_worktree: true
+parent_seed: full
+can_spawn: scout
+layout: split-events
+---
+
+You are a patcher worker. The parent expects you to produce a coherent change set in your worker worktree that can be reviewed and promoted as a single unit.
+
+Make minimal, scoped edits. Prefer editing existing files over creating new ones. Keep diffs small. If you discover the task requires a much larger change than implied, stop and call `docket_wait`.
+
+When you finish, call `docket_done` with:
+- `outcome: completed` or `outcome: proposal`
+- a one- or two-sentence `summary`
+- `evidence` listing files changed and the gist of why
+- `recommended` action bullets for the parent (e.g. "review src/auth.ts:42", "run npm test")
+
+You may dispatch a scout child worker via `docket_spawn_child` to gather context before editing — use it sparingly and only when the parent's seeded context is missing something concrete.
+
+Never push, force-push, reset --hard, or run destructive git operations.

package/extensions/worker-kinds/scout.md

@@ -0,0 +1,17 @@
+---
+name: scout
+description: Fast read-only recon. Use for grep/find/ls style investigations.
+read_only: true
+default_worktree: false
+parent_seed: full
+max_artifacts: 80
+max_duration_sec: 120
+---
+
+You are a scout worker. Your job is to find things in the repository quickly and report back what you found, with concrete refs to files and line ranges.
+
+Stick to read-only tools: `grep`, `find`, `ls`, `read`. Do not edit files. Do not run anything that mutates state.
+
+Aim for a fast `docket_done` with `outcome: findings` (or `no_evidence` when scope is clear and nothing matched). Each evidence entry should be a concrete path or a one-line excerpt the parent can act on.
+
+If the task is vague or scope is unclear, call `docket_wait` early — don't burn cycles guessing.

package/extensions/worker-kinds.ts

@@ -0,0 +1,280 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
+
+export const DEFAULT_KIND_NAME = "default";
+
+export type WorkerParentSeedPolicy = "full" | "none";
+export type WorkerLayout = "single" | "split-events";
+export type WorkerThinking = "off" | "low" | "medium" | "high";
+
+export type WorkerKind = {
+	name: string;
+	description?: string;
+	model?: string;
+	thinking?: WorkerThinking;
+	readOnly: boolean;
+	defaultWorktree: boolean;
+	parentSeedPolicy: WorkerParentSeedPolicy;
+	maxArtifacts?: number;
+	maxDurationSec?: number;
+	canSpawn: string[];
+	guardrailsAppend?: string;
+	systemPrompt?: string;
+	layout: WorkerLayout;
+	source: "builtin" | "user" | "runtime";
+	sourcePath?: string;
+};
+
+export type WorkerKindRegistry = {
+	get(name: string | undefined): WorkerKind;
+	list(): WorkerKind[];
+	names(): string[];
+	register(kind: WorkerKind): () => void;
+	unregister(name: string): boolean;
+	reload(cwd: string): Promise<void>;
+	defaultKind(projectDefault?: string): WorkerKind;
+};
+
+const BUILTIN_DEFAULT: WorkerKind = {
+	name: DEFAULT_KIND_NAME,
+	description: "General-purpose Docket worker; matches pre-kinds behavior.",
+	readOnly: false,
+	defaultWorktree: true,
+	parentSeedPolicy: "full",
+	canSpawn: [],
+	layout: "single",
+	source: "builtin",
+};
+
+function csv(value: string | undefined): string[] {
+	if (!value) return [];
+	return value.split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function asBool(value: unknown, fallback: boolean): boolean {
+	if (typeof value === "boolean") return value;
+	if (typeof value !== "string") return fallback;
+	const lowered = value.trim().toLowerCase();
+	if (["true", "yes", "y", "1", "on"].includes(lowered)) return true;
+	if (["false", "no", "n", "0", "off"].includes(lowered)) return false;
+	return fallback;
+}
+
+function asInt(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return Math.floor(value);
+	if (typeof value !== "string") return undefined;
+	const parsed = Number(value.trim());
+	return Number.isFinite(parsed) ? Math.floor(parsed) : undefined;
+}
+
+function asSeedPolicy(value: unknown): WorkerParentSeedPolicy {
+	if (typeof value === "string") {
+		const lowered = value.trim().toLowerCase();
+		if (lowered === "none" || lowered === "fresh") return "none";
+	}
+	return "full";
+}
+
+function asLayout(value: unknown): WorkerLayout {
+	if (typeof value === "string" && value.trim().toLowerCase() === "split-events") return "split-events";
+	return "single";
+}
+
+function asThinking(value: unknown): WorkerThinking | undefined {
+	if (typeof value !== "string") return undefined;
+	const lowered = value.trim().toLowerCase();
+	if (["off", "low", "medium", "high"].includes(lowered)) return lowered as WorkerThinking;
+	return undefined;
+}
+
+function normalizeName(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9_-]/g, "");
+	return trimmed.length > 0 ? trimmed.slice(0, 32) : undefined;
+}
+
+export function parseWorkerKindMarkdown(text: string, source: WorkerKind["source"], sourcePath?: string): WorkerKind | undefined {
+	const parsed = parseFrontmatter<Record<string, unknown>>(text);
+	const fm = (parsed.frontmatter ?? {}) as Record<string, unknown>;
+	const name = normalizeName(typeof fm.name === "string" ? fm.name : undefined);
+	if (!name || name === DEFAULT_KIND_NAME) return undefined;
+	const body = (parsed.body ?? "").trim();
+	const description = typeof fm.description === "string" ? fm.description.trim() : undefined;
+	const model = typeof fm.model === "string" ? fm.model.trim() : undefined;
+	const thinking = asThinking(fm.thinking);
+	const readOnly = asBool(fm.read_only ?? fm.readonly ?? fm.readOnly, false);
+	const defaultWorktree = asBool(fm.default_worktree ?? fm.defaultWorktree ?? fm.worktree, true);
+	const parentSeedPolicy = asSeedPolicy(fm.parent_seed ?? fm.parentSeedPolicy ?? fm.seed);
+	const maxArtifacts = asInt(fm.max_artifacts ?? fm.maxArtifacts);
+	const maxDurationSec = asInt(fm.max_duration_sec ?? fm.maxDurationSec ?? fm.timeout);
+	const canSpawnRaw = fm.can_spawn ?? fm.canSpawn ?? fm.spawn_kinds ?? fm.subagent_agents;
+	const canSpawn = Array.isArray(canSpawnRaw) ? canSpawnRaw.map(String) : csv(typeof canSpawnRaw === "string" ? canSpawnRaw : undefined);
+	const guardrailsAppend = typeof fm.guardrails_append === "string" ? fm.guardrails_append : undefined;
+	const layout = asLayout(fm.layout);
+	return {
+		name,
+		...(description ? { description } : {}),
+		...(model ? { model } : {}),
+		...(thinking ? { thinking } : {}),
+		readOnly,
+		defaultWorktree,
+		parentSeedPolicy,
+		...(maxArtifacts !== undefined ? { maxArtifacts } : {}),
+		...(maxDurationSec !== undefined ? { maxDurationSec } : {}),
+		canSpawn: canSpawn.map(normalizeName).filter((value): value is string => typeof value === "string"),
+		...(guardrailsAppend ? { guardrailsAppend } : {}),
+		...(body.length > 0 ? { systemPrompt: body } : {}),
+		layout,
+		source,
+		...(sourcePath ? { sourcePath } : {}),
+	};
+}
+
+function bundledKindsDir(): string {
+	const extensionDir = path.dirname(fileURLToPath(import.meta.url));
+	return path.join(extensionDir, "worker-kinds");
+}
+
+function userKindsDir(cwd: string): string[] {
+	const out: string[] = [];
+	out.push(path.join(getAgentDir(), "docket", "worker-kinds"));
+	out.push(path.join(cwd, ".pi", "docket", "worker-kinds"));
+	return out;
+}
+
+async function readKindFiles(dir: string, source: WorkerKind["source"]): Promise<WorkerKind[]> {
+	let entries: string[];
+	try {
+		entries = await fs.readdir(dir);
+	} catch {
+		return [];
+	}
+	const out: WorkerKind[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".md")) continue;
+		const filePath = path.join(dir, entry);
+		try {
+			const text = await fs.readFile(filePath, "utf8");
+			const kind = parseWorkerKindMarkdown(text, source, filePath);
+			if (kind) out.push(kind);
+		} catch {
+			// skip broken files
+		}
+	}
+	return out;
+}
+
+export function createWorkerKindRegistry(): WorkerKindRegistry {
+	const kinds = new Map<string, WorkerKind>();
+	kinds.set(BUILTIN_DEFAULT.name, BUILTIN_DEFAULT);
+
+	const set = (kind: WorkerKind): void => {
+		kinds.set(kind.name, kind);
+	};
+
+	const reload = async (cwd: string): Promise<void> => {
+		// Preserve runtime-registered kinds across reload; refresh builtin + user kinds from disk.
+		const preservedRuntime: WorkerKind[] = [];
+		for (const k of kinds.values()) if (k.source === "runtime") preservedRuntime.push(k);
+		kinds.clear();
+		kinds.set(BUILTIN_DEFAULT.name, BUILTIN_DEFAULT);
+		const bundled = await readKindFiles(bundledKindsDir(), "builtin");
+		for (const k of bundled) set(k);
+		for (const dir of userKindsDir(cwd)) {
+			const userKinds = await readKindFiles(dir, "user");
+			for (const k of userKinds) set(k);
+		}
+		for (const k of preservedRuntime) set(k);
+	};
+
+	const reloadSync = (cwd: string): void => {
+		// Only used as a best-effort sync fallback. Reads bundled MDs from disk so the
+		// worker-side, which doesn't await config load, can still resolve its kind.
+		try {
+			const entries = fsSync.readdirSync(bundledKindsDir());
+			for (const entry of entries) {
+				if (!entry.endsWith(".md")) continue;
+				try {
+					const filePath = path.join(bundledKindsDir(), entry);
+					const text = fsSync.readFileSync(filePath, "utf8");
+					const kind = parseWorkerKindMarkdown(text, "builtin", filePath);
+					if (kind && !kinds.has(kind.name)) set(kind);
+				} catch { /* skip */ }
+			}
+		} catch { /* dir missing is fine */ }
+		try {
+			for (const dir of userKindsDir(cwd)) {
+				const entries = fsSync.readdirSync(dir);
+				for (const entry of entries) {
+					if (!entry.endsWith(".md")) continue;
+					try {
+						const filePath = path.join(dir, entry);
+						const text = fsSync.readFileSync(filePath, "utf8");
+						const kind = parseWorkerKindMarkdown(text, "user", filePath);
+						if (kind) set(kind);
+					} catch { /* skip */ }
+				}
+			}
+		} catch { /* skip */ }
+	};
+
+	return {
+		get(name: string | undefined): WorkerKind {
+			if (!name) return BUILTIN_DEFAULT;
+			return kinds.get(name) ?? BUILTIN_DEFAULT;
+		},
+		list(): WorkerKind[] {
+			return Array.from(kinds.values()).sort((a, b) => {
+				if (a.name === DEFAULT_KIND_NAME) return -1;
+				if (b.name === DEFAULT_KIND_NAME) return 1;
+				return a.name.localeCompare(b.name);
+			});
+		},
+		names(): string[] {
+			return Array.from(kinds.keys()).sort();
+		},
+		register(kind: WorkerKind): () => void {
+			const normalized = normalizeName(kind.name);
+			if (!normalized || normalized === DEFAULT_KIND_NAME) {
+				throw new Error(`Docket: invalid worker kind name "${kind.name}"`);
+			}
+			const normalizedKind: WorkerKind = { ...kind, name: normalized, source: kind.source ?? "runtime" };
+			set(normalizedKind);
+			return () => {
+				const current = kinds.get(normalized);
+				if (current && current === normalizedKind) kinds.delete(normalized);
+			};
+		},
+		unregister(name: string): boolean {
+			const normalized = normalizeName(name);
+			if (!normalized || normalized === DEFAULT_KIND_NAME) return false;
+			return kinds.delete(normalized);
+		},
+		reload,
+		defaultKind(projectDefault?: string): WorkerKind {
+			if (projectDefault) {
+				const explicit = kinds.get(normalizeName(projectDefault) ?? "");
+				if (explicit) return explicit;
+			}
+			return BUILTIN_DEFAULT;
+		},
+		// Expose sync fallback for the worker-side path that runs before config loads.
+		// Not part of the public type to avoid leaking blocking I/O affordances.
+		...({ _reloadSync: reloadSync } as Record<string, unknown>),
+	};
+}
+
+export function workerKindGuardrailsAppendix(kind: WorkerKind): string {
+	const parts: string[] = [];
+	if (kind.readOnly) parts.push("- This worker is **read-only** by configuration. Do not edit files. If the task requires edits, call `docket_wait` and ask the parent to spawn a writable worker instead.");
+	if (kind.maxArtifacts !== undefined) parts.push(`- Artifact cap for this kind: ${kind.maxArtifacts}. Stay focused.`);
+	if (kind.maxDurationSec !== undefined) parts.push(`- Soft time budget for this kind: ${kind.maxDurationSec}s. If you exceed it, call \`docket_done\` with partial findings rather than continuing silently.`);
+	if (kind.canSpawn.length > 0) parts.push(`- You may dispatch child workers via \`docket_spawn_child\` using only these kinds: ${kind.canSpawn.join(", ")}. Children inherit fleet/depth caps. Children's results return to you, not to the human user.`);
+	if (kind.guardrailsAppend) parts.push(kind.guardrailsAppend.trim());
+	if (kind.systemPrompt) parts.push(`\n${kind.systemPrompt.trim()}`);
+	if (parts.length === 0) return "";
+	return `\n\n## Kind-specific rules (kind: \`${kind.name}\`)\n\n${parts.join("\n")}\n`;
+}

package/extensions/worker-result.ts

@@ -0,0 +1,193 @@
+import { deriveWorkerState, workerActivityChip, workerDisplayName, workerQuestions, workerSourceLabel, workerStatusArtifact, workerTodoBoardLines, workerTodoSummary, type WorkerStatus } from "./background-work.js";
+import type { Artifact } from "./types.js";
+
+function firstLine(text: string | undefined): string | undefined {
+	const line = text?.split(/\r?\n/).map((part) => part.trim()).find(Boolean);
+	return line || undefined;
+}
+
+function truncate(text: string, max: number): string {
+	return text.length > max ? `${text.slice(0, Math.max(1, max - 1))}…` : text;
+}
+
+function latestArtifact(artifacts: Artifact[], kinds: Artifact["kind"][]): Artifact | undefined {
+	return artifacts
+		.filter((artifact) => kinds.includes(artifact.kind))
+		.sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0))[0];
+}
+
+export function isWorkerStatusArtifact(artifact: Artifact | undefined): boolean {
+	if (!artifact) return false;
+	return artifact.meta?.workerStatus !== undefined || artifact.ref.startsWith("worker-status:") || artifact.displayId === "status" || artifact.id === "status";
+}
+
+function workerAnswerArtifacts(artifacts: Artifact[]): Artifact[] {
+	return artifacts.filter((artifact) => !isWorkerStatusArtifact(artifact));
+}
+
+export function workerResultSummary(worker: WorkerStatus, artifacts: Artifact[] = []): string {
+	const state = deriveWorkerState(worker);
+	const question = workerQuestions(worker).map((item, index) => `${index + 1}. ${item.text}`).join(" ");
+	const answer = latestArtifact(workerAnswerArtifacts(artifacts), ["response", "code"]);
+	const failure = latestArtifact(workerAnswerArtifacts(artifacts), ["error"]);
+	return firstLine(
+		state === "needs_input" ? question :
+		state === "failed" ? worker.lastError ?? failure?.title ?? failure?.body :
+		worker.summary ?? answer?.title ?? answer?.body ?? workerTodoSummary(worker) ?? workerDisplayName(worker),
+	) ?? workerDisplayName(worker);
+}
+
+export function workerResultHeadline(worker: WorkerStatus, artifacts: Artifact[] = [], max = 72): string {
+	return truncate(workerResultSummary(worker, artifacts).replace(/\s+/g, " "), max);
+}
+
+export function workerResultArtifact(worker: WorkerStatus, artifacts: Artifact[] = []): Artifact | undefined {
+	const label = workerSourceLabel(worker);
+	const answer = latestArtifact(workerAnswerArtifacts(artifacts), ["response", "code", "error"]);
+	const status = artifacts.find((artifact) => artifact.meta?.workerId === worker.id && artifact.meta?.workerStatus)
+		?? artifacts.find((artifact) => artifact.displayId === `${label}.status` || artifact.id === `${label}.status` || artifact.id === "status")
+		?? workerStatusArtifact(worker);
+	return answer ?? status;
+}
+
+export function workerResultText(worker: WorkerStatus, artifacts: Artifact[] = [], maxBodyLines = 8): string {
+	const label = workerSourceLabel(worker);
+	const result = workerResultArtifact(worker, artifacts);
+	const resultIsStatus = isWorkerStatusArtifact(result);
+	const summary = workerResultSummary(worker, artifacts);
+	const body = !resultIsStatus ? result?.body?.split(/\r?\n/).slice(0, maxBodyLines).join("\n") : undefined;
+	const questions = workerQuestions(worker).map((item, index) => `${index + 1}. ${item.text}`).join("\n");
+	const todos = workerTodoBoardLines(worker, { includeHeader: true, maxItems: 8 });
+	return [
+		`${workerActivityChip(worker, { verbose: true })} ${summary}`,
+		body && body !== summary ? `answer:\n${body}` : undefined,
+		questions ? `needs input:\n${questions}` : undefined,
+		todos.length ? `progress:\n${todos.join("\n")}` : undefined,
+		`actions: /docket use ${label} · /docket ask ${label}`,
+		result && !resultIsStatus ? `ref: @${result.displayId}` : undefined,
+	].filter((line): line is string => line !== undefined).join("\n");
+}
+
+export type WorkerResultReportSection = "outcome" | "question" | "failure";
+
+export type WorkerResultReference = {
+	displayId: string;
+	kind: Artifact["kind"];
+	label: string;
+};
+
+export type WorkerResultReport = {
+	label: string;
+	state: ReturnType<typeof deriveWorkerState>;
+	stateLabel: string;
+	taskLabel: string;
+	progressLine: string;
+	changesLine: string;
+	primarySection: WorkerResultReportSection;
+	primaryBody: string;
+	recommendations: string[];
+	references: WorkerResultReference[];
+	nextActions: Array<{ key: string; label: string }>;
+	resultRef?: string;
+};
+
+const BULLET_RE = /^\s*(?:[-*•]|\d+[.)])\s+/;
+
+function extractBullets(text: string | undefined, max = 6): string[] {
+	if (!text) return [];
+	const out: string[] = [];
+	let inSection = false;
+	for (const raw of text.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (!line) { if (inSection) break; continue; }
+		if (/^(recommended|recommendations?|suggested|suggestions?):?$/i.test(line)) { inSection = true; continue; }
+		const match = line.match(BULLET_RE);
+		if (match) out.push(line.slice(match[0].length).trim());
+		else if (inSection) out.push(line);
+	}
+	return out.slice(0, max);
+}
+
+function fallbackSentences(text: string | undefined, max = 3): string[] {
+	if (!text) return [];
+	return text.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean).slice(0, max);
+}
+
+function workerProgressLine(worker: WorkerStatus): string {
+	const todos = worker.todos ?? [];
+	if (todos.length === 0) return "no todos";
+	const completed = todos.filter((t) => t.state === "completed").length;
+	const open = todos.length - completed;
+	if (open === 0) return `${completed}/${todos.length} todos complete`;
+	return `${completed}/${todos.length} todos · ${open} open`;
+}
+
+function workerChangesLine(artifacts: Artifact[]): string {
+	const changeSet = artifacts.find((a) => a.meta?.workerChangeSet === true);
+	const changedFiles = Array.isArray(changeSet?.meta?.changedFiles) ? changeSet.meta.changedFiles : undefined;
+	if (changedFiles?.length) return `${changedFiles.length} file${changedFiles.length === 1 ? "" : "s"}`;
+	const edited = artifacts.filter((a) => a.kind === "file" && (a.meta?.tool === "edit" || a.meta?.tool === "write"));
+	if (edited.length === 0) return "none";
+	if (edited.length === 1) return `1 file (${edited[0]!.title})`;
+	return `${edited.length} files`;
+}
+
+function workerReferences(label: string, artifacts: Artifact[], max = 4): WorkerResultReference[] {
+	const candidates = artifacts.filter((a) => !isWorkerStatusArtifact(a));
+	const order: Artifact["kind"][] = ["response", "code", "file", "command", "error"];
+	const grouped = order.flatMap((kind) => candidates.filter((a) => a.kind === kind));
+	const seen = new Set<string>();
+	const refs: WorkerResultReference[] = [];
+	for (const artifact of grouped) {
+		const id = `${label}.${artifact.displayId}`;
+		if (seen.has(id)) continue;
+		seen.add(id);
+		refs.push({ displayId: id, kind: artifact.kind, label: firstLine(artifact.title) ?? artifact.kind });
+		if (refs.length >= max) break;
+	}
+	return refs;
+}
+
+export function workerResultReport(worker: WorkerStatus, artifacts: Artifact[] = []): WorkerResultReport {
+	const label = workerSourceLabel(worker);
+	const state = deriveWorkerState(worker);
+	const result = workerResultArtifact(worker, artifacts);
+	const resultIsStatus = isWorkerStatusArtifact(result);
+	const summary = workerResultSummary(worker, artifacts);
+	const summarySource = worker.summary ?? (result && !resultIsStatus ? `${result.title}\n${result.body}` : undefined);
+	const recommendations = extractBullets(summarySource);
+	if (recommendations.length === 0 && state !== "needs_input" && state !== "failed") {
+		recommendations.push(...fallbackSentences(summarySource, 2).filter((s) => s !== summary));
+	}
+	const questions = workerQuestions(worker);
+	const primarySection: WorkerResultReportSection = state === "needs_input" ? "question" : state === "failed" ? "failure" : "outcome";
+	const primaryBody = primarySection === "question"
+		? questions.map((q, i) => `${i + 1}. ${q.text}`).join("\n") || summary
+		: primarySection === "failure"
+			? worker.lastError ?? summary
+			: summary;
+	const stateLabel = state === "ready_open_todos" ? "ready · open todos" : state === "needs_input" ? "needs reply" : state;
+	const nextActions: Array<{ key: string; label: string }> = [];
+	if (state === "needs_input") nextActions.push({ key: "c", label: "Reply" });
+	else if (state === "failed") nextActions.push({ key: "Enter", label: "Inspect failure" });
+	else nextActions.push({ key: "Enter", label: "Review answer" });
+	nextActions.push({ key: "c", label: state === "needs_input" ? "Send answer" : "Ask follow-up" });
+	nextActions.push({ key: "l", label: "Load into prompt" });
+	nextActions.push({ key: "a", label: "Attach tmux" });
+	nextActions.push({ key: "x", label: "Dismiss" });
+	const uniqueActions = nextActions.filter((entry, index, arr) => arr.findIndex((other) => other.key === entry.key && other.label === entry.label) === index);
+	return {
+		label,
+		state,
+		stateLabel,
+		taskLabel: worker.task,
+		progressLine: workerProgressLine(worker),
+		changesLine: workerChangesLine(artifacts),
+		primarySection,
+		primaryBody,
+		recommendations,
+		references: workerReferences(label, artifacts),
+		nextActions: uniqueActions,
+		...(result && !resultIsStatus ? { resultRef: `@${label}.${result.displayId}` } : {}),
+	};
+}