pi-squad 0.17.2 → 0.19.0

package/src/skills/squad-plan/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: squad-plan
+description: Author valid pi-squad plans — inline task arrays and strict v1 file specifications. Use when creating a squad plan, writing a squad spec JSON, choosing between inline tasks and specFile, computing specSha256, or debugging squad validation errors (must be array, SPEC_MALFORMED, SPEC_HASH_MISMATCH, Plan rejected).
+---
+
+# Squad Plan Authoring
+
+Two ways to start a squad. Pick one:
+
+| Form | When |
+|---|---|
+| **Inline** `squad({ goal, tasks?, agents?, config? })` | Normal plans. Goal + tasks fit comfortably in a tool call. |
+| **File spec** `squad({ specFile, specSha256 })` | Large contracts, many tasks, exact-bytes requirements, or when your transport keeps mangling inline arguments. Children mechanically attest full spec reading. |
+
+## Planner rules (both forms)
+
+- 3–7 tasks is usually right (hard limit 128 in file specs; >9 warns).
+- First task(s) have empty `depends`. No cycles; every dependency must name an existing task id.
+- When tasks share an interface (API, schema, format), add a design/contract task first and make consumers depend on it.
+- Add a final QA/verification task for user-facing changes.
+- Task ids: short kebab-case (`setup-db`, `auth-middleware`). File specs enforce `^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$`.
+- Structure descriptions as: Goal (outcome first), Context (files to read), Output (deliverable), Boundaries (what must not change), Verify (proving command).
+- Every task's `agent` must name an existing agent definition (defaults: architect, backend, debugger, devops, docs, frontend, fullstack, qa, researcher, reviewer, security).
+- **Model/thinking come from configuration.** Omit inline `agents` overrides and keep file-spec entries at `{ "model": null, "thinking": null }` unless the user explicitly asked for a specific model or thinking level. Configured values resolve as: squad-plan override (only if set) → agent definition (`~/.pi/squad/agents/*.json` or project `.pi/squad/agents/`) → `/squad defaults` policy in `~/.pi/squad/settings.json`.
+
+## Inline form
+
+```json
+{
+  "goal": "Complete user outcome/acceptance contract, preserved for review",
+  "tasks": [
+    { "id": "api-contract", "title": "Define API contract", "agent": "architect", "depends": [] },
+    { "id": "build-api", "title": "Implement API", "agent": "backend", "depends": ["api-contract"],
+      "description": "Goal: ... Context: ... Output: ... Boundaries: ... Verify: ..." },
+    { "id": "qa", "title": "Verify end to end", "agent": "qa", "depends": ["build-api"] }
+  ],
+  "config": { "maxConcurrency": 2 }
+}
+```
+
+- `tasks`, `agents`, and `config` must be real JSON structures. If your transport stringifies them, pi-squad also accepts JSON-encoded strings for these three fields and decodes them — but prefer real structures.
+- Omitting `tasks` runs the planner agent on `goal`.
+- `Plan rejected:` errors list exact structural problems (duplicate ids, unknown dependency, cycle, no entry task). Fix and resubmit; warnings (`⚠️`) don't block.
+
+## File-spec form (strict v1)
+
+Validation is strict and fail-closed: unknown keys, missing keys, duplicate JSON keys, a UTF-8 BOM, invalid UTF-8, or a wrong hash all reject before anything is scheduled. **Every field below is required — including empty ones.**
+
+```json
+{
+  "schemaVersion": 1,
+  "goal": "Complete acceptance contract...",
+  "tasks": [
+    {
+      "id": "api-contract",
+      "title": "Define API contract",
+      "description": "Goal: ... Verify: ...",
+      "agent": "architect",
+      "depends": [],
+      "inheritContext": false,
+      "artifactRefs": []
+    }
+  ],
+  "agents": {
+    "architect": { "model": null, "thinking": null }
+  },
+  "config": { "maxConcurrency": 2, "autoUnblock": true, "maxRetries": 2 },
+  "artifacts": []
+}
+```
+
+Rules that trip people up:
+
+- Every agent used by a task must appear in `agents`, each entry exactly `{ "model": string|null, "thinking": null|"off"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max" }`. Use `null`/`null` (configured defaults) unless the user explicitly requested a specific model or thinking level.
+- `config` needs all three keys: `maxConcurrency` (1–64), `autoUnblock` (boolean), `maxRetries` (0–20).
+- Each task needs all seven keys, even when `description` is `""` and `artifactRefs` is `[]`.
+- No Base64 blobs or oversized embedded content (spec ≤ 1 MiB; embedded text budgets enforced). Reference big content via `artifacts`: absolute `path`, exact lowercase `sha256`, exact `bytes`, nonempty `purpose`.
+- `specSha256` is the SHA-256 of the exact file bytes, 64 lowercase hex chars. Write the file first, hash second, never edit afterward.
+
+## Workflow: write → validate → call
+
+1. Write the spec to a file (UTF-8, no BOM). Generate it with a script (`JSON.stringify`) rather than by hand to avoid duplicate keys and escaping mistakes.
+2. Validate with the bundled validator — it runs the exact same code the squad tool runs and prints the ready-to-use hash:
+
+```bash
+node <skill-dir>/validate-spec.mjs /path/to/spec.v1.json
+```
+
+On success it prints `VALID`, the `specSha256`, and the exact `squad(...)` call. On failure it prints the same `SPEC_MALFORMED`/`SPEC_TOO_LARGE`/`ARTIFACT_*` error the tool would return — fix and re-run.
+
+3. Call `squad({ specFile, specSha256 })` with the printed values. Do not restate the contract inline.
+
+## Error → fix map
+
+| Error | Fix |
+|---|---|
+| `tasks: must be array` (tool validation) | Transport stringified your array — send a real array, or pass the JSON string (accepted), or use a file spec. |
+| `SPEC_HASH_MISMATCH` | File changed after hashing, or hash uppercase/wrong. Re-run the validator; use its printed hash. |
+| `SPEC_MALFORMED: unknown/requires ...` | Add every required key exactly; remove extras. See the full example above. |
+| `SPEC_MALFORMED: duplicate task id / invalid dependency / cycle` | Fix the task graph; dependencies reference ids in this spec only. |
+| `SPEC_MALFORMED: task X uses undeclared agent Y` | Add Y to `agents` with `{ "model": null, "thinking": null }`. |
+| `SPEC_TOO_LARGE` | Move large content to `artifacts` (path + sha256 + bytes) and reference via `artifactRefs`. |
+| `Plan rejected:` (inline) | Structural plan errors listed verbatim — apply each fix. |

package/src/skills/squad-plan/validate-spec.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * validate-spec.mjs — validate a pi-squad strict v1 file spec and print the
+ * exact specSha256 to pass to the squad tool.
+ *
+ * Usage: node validate-spec.mjs <spec.v1.json>
+ *
+ * This runs the SAME validator the squad tool uses (src/file-spec.ts), so a
+ * VALID result here is exactly what squad({ specFile, specSha256 }) accepts.
+ */
+import { registerHooks } from "node:module";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+if (!process.features.typescript) {
+	console.error(
+		"This validator needs Node.js with type stripping: Node >= 23.6, or Node >= 22.6 run as\n" +
+		"  node --experimental-strip-types validate-spec.mjs <spec.v1.json>",
+	);
+	process.exit(2);
+}
+
+// The extension sources use ".js" specifiers resolved by Pi; map them to the
+// on-disk ".ts" files when loading the real validator outside Pi.
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		if (specifier.startsWith(".") && specifier.endsWith(".js")) {
+			try {
+				return nextResolve(specifier, context);
+			} catch {
+				return nextResolve(specifier.replace(/\.js$/, ".ts"), context);
+			}
+		}
+		return nextResolve(specifier, context);
+	},
+});
+
+const specArg = process.argv[2];
+if (!specArg) {
+	console.error("Usage: node validate-spec.mjs <spec.v1.json>");
+	process.exit(2);
+}
+const specPath = resolve(process.cwd(), specArg);
+
+const { prepareSpec } = await import(new URL("../../file-spec.ts", import.meta.url).href);
+
+try {
+	const raw = readFileSync(specPath);
+	const sha256 = createHash("sha256").update(raw).digest("hex");
+	// Validation with the self-computed hash: the hash gate passes trivially and
+	// every structural/strictness rule still runs.
+	const prepared = prepareSpec(specPath, sha256, process.cwd());
+	console.log("VALID");
+	console.log(`specFile:   ${specPath}`);
+	console.log(`specSha256: ${prepared.sha256}`);
+	console.log(`bytes:      ${prepared.raw.length}`);
+	console.log(`tasks:      ${prepared.spec.tasks.length}`);
+	console.log(`agents:     ${Object.keys(prepared.spec.agents).join(", ")}`);
+	console.log("");
+	console.log(`squad({ specFile: ${JSON.stringify(specPath)}, specSha256: ${JSON.stringify(prepared.sha256)} })`);
+} catch (error) {
+	console.error(`INVALID: ${error.message}`);
+	process.exit(1);
+}

package/src/skills/squad-supervisor/SKILL.md

@@ -29,6 +29,7 @@ Providing `tasks` yourself skips the planner agent — so you must apply its rul
 - When tasks share an interface (API endpoints, schema, data formats), create a design/contract task FIRST and make consumers depend on it
 - Include a final QA/verification task if there are user-facing changes
 - Required work only — no optional polish
+- Do NOT set agent `model`/`thinking` overrides unless the user explicitly asked for them — configured agent definitions and `/squad defaults` apply otherwise
 
 Plans are validated on submission: structural errors (unknown deps, cycles, duplicate IDs, no entry task) are rejected; rule violations come back as ⚠️ warnings in the tool response. **Act on the warnings** — fix them with `squad_modify` `add_task`, or note them for review time. Don't silently ignore them.
 

package/src/start-squad.ts

@@ -0,0 +1,176 @@
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { chunkRanges, type PreparedSpec } from "./file-spec.js";
+import { logError } from "./logger.js";
+import { validatePlan } from "./plan-rules.js";
+import { runPlanner } from "./planner.js";
+import { Scheduler } from "./scheduler.js";
+import { wireSchedulerEvents } from "./scheduler-runtime.js";
+import * as store from "./store.js";
+import type { PlannerOutput, Squad, SquadAgentEntry, SquadConfig, Task } from "./types.js";
+import { DEFAULT_SQUAD_CONFIG } from "./types.js";
+import { disabledToolResult, focusSquad, resolveSquadDefaults, runtime, schedulerSpawnContext, type InlineSquadStart } from "./runtime.js";
+
+// ============================================================================
+// Start Squad
+// ============================================================================
+
+export async function startSquad(
+	squadId: string,
+	params: InlineSquadStart,
+	cwd: string,
+	skillPaths: string[],
+	pi: ExtensionAPI,
+	sessionFile: string | null = null,
+	preparedSpec?: PreparedSpec,
+) {
+	let plan: PlannerOutput;
+
+	if (params.tasks && params.tasks.length > 0) {
+		// User provided a plan — use it directly
+		plan = {
+			agents: params.agents || {},
+			tasks: params.tasks.map((t) => ({
+				...t,
+				description: t.description || "",
+				depends: t.depends || [],
+			})),
+		};
+
+		// Validate agent names — remap unknown agents to fullstack
+		for (const task of plan.tasks) {
+			const agentDef = store.loadAgentDef(task.agent, cwd);
+			if (!agentDef || agentDef.disabled) {
+				if (preparedSpec) throw new Error(`SPEC_MALFORMED: assigned agent '${task.agent}' is missing or disabled`);
+				const original = task.agent;
+				task.agent = "fullstack";
+				task.description = `[Note: agent "${original}" not found, remapped to fullstack]\n\n${task.description}`;
+			}
+		}
+	} else {
+		// Run planner to generate task breakdown (squad default policy as fallback)
+		try {
+			const defaults = resolveSquadDefaults();
+			plan = await runPlanner({ goal: params.goal, cwd, fallbackModel: defaults.model, fallbackThinking: defaults.thinking });
+		} catch (error) {
+			// Throwing marks the tool result as an error for the LLM (returning isError is ignored in current pi)
+			throw new Error(`Failed to plan: ${(error as Error).message}`);
+		}
+	}
+
+	// A planner may take long enough for /squad disable to run concurrently.
+	// Re-check before publishing any squad or constructing a scheduler.
+	if (!runtime.squadEnabled) return disabledToolResult();
+
+	// Merge agent roster
+	const agents: Record<string, SquadAgentEntry> = { ...plan.agents };
+	if (params.agents) {
+		for (const [name, entry] of Object.entries(params.agents)) {
+			agents[name] = { ...agents[name], ...entry };
+		}
+	}
+
+	// Validate the plan — same enforcement for main-session and planner plans.
+	// Errors block squad creation; warnings are reported back to the plan author.
+	const validation = validatePlan(plan.tasks);
+	if (validation.errors.length > 0) {
+		throw new Error(
+			`Plan rejected:\n- ${validation.errors.join("\n- ")}\n\nFix the task list and call squad again.`,
+		);
+	}
+
+	// Create squad
+	const config: SquadConfig = {
+		...DEFAULT_SQUAD_CONFIG,
+		...(params.config?.maxConcurrency ? { maxConcurrency: params.config.maxConcurrency } : {}),
+		...(typeof params.config?.autoUnblock === "boolean" ? { autoUnblock: params.config.autoUnblock } : {}),
+		...(typeof params.config?.maxRetries === "number" ? { maxRetries: params.config.maxRetries } : {}),
+	};
+
+	const squad: Squad = {
+		id: squadId,
+		goal: params.goal,
+		status: "running",
+		created: store.now(),
+		cwd,
+		sessionFile,
+		agents,
+		config,
+		...(preparedSpec ? { spec: {
+			schemaVersion: 1 as const,
+			sha256: preparedSpec.sha256,
+			bytes: preparedSpec.raw.length,
+			path: path.join(store.getSquadDir(squadId), "spec", "spec.v1.json"),
+			chunkBytes: 32768 as const,
+			chunkCount: chunkRanges(preparedSpec.raw).length,
+		} } : {}),
+	};
+
+	// Materialize task state in memory so file squads can publish spec+squad+tasks atomically.
+	const initialTasks: Task[] = plan.tasks.map((taskDef) => {
+		const task: Task = {
+			id: taskDef.id,
+			title: taskDef.title,
+			description: taskDef.description,
+			agent: taskDef.agent,
+			status: taskDef.depends.length === 0 ? "pending" : "blocked",
+			depends: taskDef.depends,
+			...(taskDef.inheritContext ? { inheritContext: true } : {}),
+			created: store.now(),
+			started: null,
+			completed: null,
+			output: null,
+			error: null,
+			usage: { inputTokens: 0, outputTokens: 0, cost: 0, turns: 0 },
+		};
+		return task;
+	});
+
+	if (preparedSpec) store.publishFileSquad(squad, initialTasks, preparedSpec.raw);
+	else {
+		store.saveSquad(squad);
+		for (const task of initialTasks) store.createTask(squadId, task);
+	}
+
+	// Start scheduler
+	const scheduler = new Scheduler(squadId, skillPaths, schedulerSpawnContext);
+	runtime.schedulers.set(squadId, scheduler);
+	// Activate panel/widget/tool focus as one invariant.
+	focusSquad(squadId);
+
+	// Wire up completion/escalation notifications to main agent.
+	wireSchedulerEvents(pi, scheduler, squadId);
+
+	// Start scheduling — fire and forget, don't block the tool call.
+	// scheduler.start() spawns agents which can take seconds per agent.
+	// We must return immediately so the main agent's turn completes
+	// and the user regains interactive control.
+	scheduler.start().catch((err) => {
+		logError("squad", `Scheduler start error: ${(err as Error).message}`);
+	});
+
+	// Build response. File mode returns only the bounded descriptor; the canonical
+	// contract is never reflected back into the main model's transport.
+	const taskSummary = preparedSpec
+		? `Canonical spec: ${squad.spec!.path}\nSHA-256: ${squad.spec!.sha256}\nBytes: ${squad.spec!.bytes}\nTasks: ${plan.tasks.length}`
+		: plan.tasks
+			.map((t) => {
+				const deps = t.depends.length > 0 ? ` (depends: ${t.depends.join(", ")})` : "";
+				return `${t.id} → ${t.agent}: ${t.title}${deps}`;
+			})
+			.join("\n");
+
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text: `Squad "${squadId}" started with ${plan.tasks.length} tasks.\n\n${taskSummary}${
+					validation.warnings.length > 0
+						? `\n\n⚠️ Plan warnings (fix with squad_modify, or address at review):\n- ${validation.warnings.join("\n- ")}`
+						: ""
+				}\n\nAgents work in the background — you will be woken automatically when the squad completes, fails, or needs help. Report this plan to the user and END YOUR TURN now. Do NOT poll squad_status, do NOT sleep-wait, do NOT loop.`,
+			},
+		],
+		details: undefined,
+	};
+}

package/src/store.ts

@@ -12,7 +12,6 @@ import * as os from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import type {
 	AgentDef,
-	KnowledgeEntry,
 	Squad,
 	SquadContext,
 	Task,
@@ -103,14 +102,6 @@ export function getContextFilePath(squadId: string): string {
 	return path.join(getSquadDir(squadId), "context.json");
 }
 
-export function getKnowledgeDir(squadId: string): string {
-	return path.join(getSquadDir(squadId), "knowledge");
-}
-
-export function getMemoryFilePath(): string {
-	return path.join(getSquadRoot(), "memory.jsonl");
-}
-
 /** Resolve task dir, supporting nested subtasks via parentPath */
 export function getTaskDir(squadId: string, taskId: string, parentPath?: string): string {
 	const base = parentPath
@@ -649,28 +640,6 @@ export function saveContext(squadId: string, context: SquadContext): void {
 	writeJsonAtomic(getContextFilePath(squadId), context);
 }
 
-// ============================================================================
-// Knowledge
-// ============================================================================
-
-export function appendKnowledge(squadId: string, type: KnowledgeEntry["type"], entry: KnowledgeEntry): void {
-	const file = path.join(getKnowledgeDir(squadId), `${type}s.jsonl`);
-	appendJsonl(file, entry);
-}
-
-export function loadKnowledge(squadId: string, type: KnowledgeEntry["type"]): KnowledgeEntry[] {
-	const file = path.join(getKnowledgeDir(squadId), `${type}s.jsonl`);
-	return readJsonl<KnowledgeEntry>(file);
-}
-
-export function loadAllKnowledge(squadId: string): KnowledgeEntry[] {
-	return [
-		...loadKnowledge(squadId, "decision"),
-		...loadKnowledge(squadId, "convention"),
-		...loadKnowledge(squadId, "finding"),
-	].sort((a, b) => a.ts.localeCompare(b.ts));
-}
-
 // ============================================================================
 // Rework Helpers
 // ============================================================================
@@ -688,18 +657,6 @@ export function getRetryCount(squadId: string, taskId: string): number {
 	return findRetries(squadId, taskId).length;
 }
 
-// ============================================================================
-// Memory (cross-squad)
-// ============================================================================
-
-export function appendMemory(entry: KnowledgeEntry): void {
-	appendJsonl(getMemoryFilePath(), entry);
-}
-
-export function loadMemory(): KnowledgeEntry[] {
-	return readJsonl<KnowledgeEntry>(getMemoryFilePath());
-}
-
 // ============================================================================
 // Bootstrap — first-run agent initialization
 // ============================================================================