pi-taskflow 0.0.22 → 0.0.24

package/extensions/index.ts

@@ -44,6 +44,16 @@ import {
 } from "./store.ts";
 import { CacheStore } from "./cache.ts";
 import { safeParse } from "./interpolate.ts";
+import {
+	isValidKey,
+	queueSpawn,
+	readVisibleFindings,
+	readTree,
+	nodeDepth,
+	writeFinding,
+	writeReport,
+} from "./context-store.ts";
+import { MAX_DYNAMIC_NESTING } from "./schema.ts";
 
 interface TaskflowDetails {
 	state?: RunState;
@@ -73,8 +83,8 @@ const ShorthandStep = Type.Object(
 );
 
 const TaskflowParams = Type.Object({
-	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "cache-clear"] as const, {
-		description: "What to do: run a flow, save a definition, resume a paused run, list saved flows, list available agents, init model role configuration, or clear the cross-run memoization cache",
+	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "compile", "cache-clear"] as const, {
+		description: "What to do: run a flow, save a definition, resume a paused run, list saved flows, list available agents, init model role configuration, verify the DAG, compile the DAG to a Mermaid diagram + verification report, or clear the cross-run memoization cache",
 		default: "run",
 	}),
 	name: Type.Optional(Type.String({ description: "Name of a saved flow (for run/save without inline define)" })),
@@ -292,6 +302,21 @@ async function runFlow(
 }
 
 export default function (pi: ExtensionAPI) {
+	// ---- Dual identity ----------------------------------------------------
+	// When this extension is loaded INSIDE a subagent process that the taskflow
+	// runtime spawned with Shared Context Tree enabled, PI_TASKFLOW_CTX_DIR +
+	// PI_TASKFLOW_NODE_ID are present. In that case we register the ctx_* tools
+	// (the blackboard + supervision API) instead of the host `taskflow` tool —
+	// a subagent has no business orchestrating its own taskflows, and the host
+	// tool's heavy machinery is irrelevant there. When the env is absent we are
+	// the host: register `taskflow` + `/tf` exactly as before (zero change).
+	const ctxDir = process.env.PI_TASKFLOW_CTX_DIR;
+	const nodeId = process.env.PI_TASKFLOW_NODE_ID;
+	if (ctxDir && nodeId) {
+		registerCtxTools(pi, ctxDir, nodeId);
+		return;
+	}
+
 	// ---- Register per-saved-flow shortcut commands on session start ----
 	const registerSavedFlowCommands = (ctx: ExtensionContext) => {
 		const flows = listFlows(ctx.cwd);
@@ -377,6 +402,7 @@ export default function (pi: ExtensionAPI) {
 			"Every delegation is tracked (runId), resumable across sessions, and saveable as /tf:<name> via action=save.",
 			"Use action=agents to list the 18 built-in agents (executor, scout, planner, analyst, critic, reviewer, risk-reviewer, security-reviewer, plan-arbiter, final-arbiter, test-engineer, doc-writer, executor-code, executor-fast, executor-ui, recover, verifier, visual-explorer). Do NOT invent agent names.",
 			"Phase types: agent, parallel (static branches), map (dynamic fan-out over array), gate (VERDICT: PASS/BLOCK), reduce (aggregate from N), approval (human-in-the-loop), flow (run saved sub-flow), loop (iterate until condition/convergence/cap), tournament (N variants, judge picks best/aggregate).",
+			"Use action=compile to generate a Mermaid diagram + verification report from a saved or inline flow — 0 tokens.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
@@ -545,6 +571,46 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text", text: lines.join("\n") }], details: { action } satisfies TaskflowDetails };
 			}
 
+			if (action === "compile") {
+				const { compileTaskflow } = await import("./compile.ts");
+				// Resolve definition: inline define (object or JSON/fenced string) then saved name.
+				let def: Taskflow | undefined;
+				let resolvedDefine: unknown = params.define;
+				if (typeof resolvedDefine === "string") {
+					const parsed = safeParse(resolvedDefine);
+					if (parsed && typeof parsed === "object") resolvedDefine = parsed;
+				}
+				if (resolvedDefine) {
+					const d = resolvedDefine as Record<string, unknown>;
+					if (typeof d === "object" && d !== null && Array.isArray(d.phases)) {
+						def = d as unknown as Taskflow;
+					} else if (isShorthand(resolvedDefine)) {
+						try {
+							def = desugar(resolvedDefine) as Taskflow;
+						} catch (e) {
+							return errorResult(action, `Invalid shorthand: ${e instanceof Error ? e.message : String(e)}`);
+						}
+					}
+				} else if (params.name) {
+					const saved = getFlow(ctx.cwd, params.name);
+					if (saved) def = saved.def;
+				}
+				if (!def) {
+					return errorResult(action, "Provide 'define' (DSL) or 'name' (saved flow) to compile.");
+				}
+				// Schema validation first so a malformed graph gives a clean error
+				// rather than a half-rendered diagram.
+				const vr = validateTaskflow(def, { cwd: ctx.cwd ? String(ctx.cwd) : undefined });
+				if (!vr.ok) {
+					return errorResult(action, `Schema validation failed:\n${vr.errors.join("\n")}`);
+				}
+				const compiled = compileTaskflow(def);
+				return {
+					content: [{ type: "text", text: compiled.markdown }],
+					details: { action } satisfies TaskflowDetails,
+				};
+			}
+
 			if (action === "cache-clear") {
 				const removed = new CacheStore(ctx.cwd).clear();
 				return {
@@ -754,9 +820,9 @@ export default function (pi: ExtensionAPI) {
 
 	// ---- The /tf user command ----
 	pi.registerCommand("tf", {
-		description: "Taskflow: list | run <name> | show <name> | runs | init",
+		description: "Taskflow: list | run <name> | show <name> | compile <name> | runs | init",
 		getArgumentCompletions: (prefix) => {
-			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify"];
+			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify", "compile"];
 			const items = subs.map((s) => ({ value: s, label: s }));
 			const filtered = items.filter((i) => i.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -785,6 +851,33 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			if (sub === "compile") {
+				if (!arg) {
+					ctx.ui.notify("Usage: /tf compile <name> [lr|td]", "warning");
+					return;
+				}
+				// `arg` may carry an optional direction suffix: "<name> lr" / "<name> td".
+				const parts = arg.trim().split(/\s+/);
+				const flowName = parts[0];
+				const direction = parts[1]?.toLowerCase() === "lr" ? "LR" : "TD";
+				const flow = getFlow(ctx.cwd, flowName);
+				if (!flow) {
+					ctx.ui.notify(`Flow not found: ${flowName}`, "error");
+					return;
+				}
+				// Schema-validate before compiling so a malformed saved flow yields a
+				// clean error rather than a half-rendered diagram (mirrors the tool action).
+				const vr = validateTaskflow(flow.def, { cwd: ctx.cwd ? String(ctx.cwd) : undefined });
+				if (!vr.ok) {
+					ctx.ui.notify(`Schema validation failed:\n${vr.errors.join("\n")}`, "error");
+					return;
+				}
+				const { compileTaskflow } = await import("./compile.ts");
+				const compiled = compileTaskflow(flow.def, { direction });
+				ctx.ui.notify(compiled.markdown, compiled.verification.ok ? "info" : "warning");
+				return;
+			}
+
 			if (sub === "runs") {
 				const runs = listRuns(ctx.cwd, 50);
 				if (runs.length === 0) {
@@ -912,6 +1005,116 @@ export default function (pi: ExtensionAPI) {
 
 // --- helpers ---
 
+/**
+ * Register the Shared Context Tree tools inside a subagent process. These read
+ * & write the per-run blackboard at `ctxDir` on behalf of node `nodeId`.
+ *
+ * - ctx_read   : read findings visible to this node (own + ancestors + completed others)
+ * - ctx_write  : write a finding (last-write-wins per key) so siblings can reuse it
+ * - ctx_report : report a result upward to the parent
+ * - ctx_spawn  : queue child tasks the runtime picks up after this node finishes
+ */
+function registerCtxTools(pi: ExtensionAPI, ctxDir: string, nodeId: string) {
+	const textResult = (text: string, isError = false): ToolResult => ({
+		content: [{ type: "text", text }],
+		details: { action: "ctx" },
+		...(isError ? { isError: true } : {}),
+	});
+
+	pi.registerTool({
+		name: "ctx_read",
+		label: "Context Read",
+		description:
+			"Read shared findings from the taskflow blackboard (what sibling/ancestor agents already discovered). Pass a key to read one value, or omit to list all visible findings. Use this BEFORE re-reading files another agent may have already mapped.",
+		parameters: Type.Object({
+			key: Type.Optional(Type.String({ description: "Specific finding key to read; omit to get all visible findings." })),
+		}),
+		async execute(_id, params) {
+			try {
+				const out = readVisibleFindings(ctxDir, nodeId, params.key);
+				return textResult(typeof out === "string" ? out : JSON.stringify(out ?? null, null, 2));
+			} catch (e) {
+				return textResult(`ctx_read failed: ${e instanceof Error ? e.message : String(e)}`, true);
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "ctx_write",
+		label: "Context Write",
+		description:
+			"Write a finding to the shared taskflow blackboard so sibling/descendant agents can reuse it without re-reading files. Key must be [A-Za-z0-9._-] (<=128 chars). Value is any JSON. Last write wins per key.",
+		parameters: Type.Object({
+			key: Type.String({ description: "Finding key, e.g. 'endpoints' or 'auth.summary'." }),
+			value: Type.Unknown({ description: "The value to store (string, number, object, or array)." }),
+		}),
+		async execute(_id, params) {
+			if (!isValidKey(params.key)) {
+				return textResult(`ctx_write rejected: invalid key '${params.key}'.`, true);
+			}
+			try {
+				writeFinding(ctxDir, nodeId, params.key, params.value);
+				return textResult(`Stored finding '${params.key}'.`);
+			} catch (e) {
+				return textResult(`ctx_write failed: ${e instanceof Error ? e.message : String(e)}`, true);
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "ctx_report",
+		label: "Context Report",
+		description:
+			"Report your result upward to the parent task. Provide a concise summary and optional structured JSON. The parent (and downstream phases) will see this report.",
+		parameters: Type.Object({
+			summary: Type.String({ description: "Concise summary of what you accomplished / found." }),
+			structured: Type.Optional(Type.Unknown({ description: "Optional structured result (JSON)." })),
+		}),
+		async execute(_id, params) {
+			try {
+				writeReport(ctxDir, nodeId, params.summary, params.structured);
+				return textResult("Report recorded.");
+			} catch (e) {
+				return textResult(`ctx_report failed: ${e instanceof Error ? e.message : String(e)}`, true);
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "ctx_spawn",
+		label: "Context Spawn",
+		description:
+			"Delegate sub-tasks to NEW child agents. After you finish, the runtime runs each child (isolated context) and folds their reports back into your output. Use when you discover the work needs to fan out. Each assignment is EITHER {task, agent?} for one flat task, OR {subflow, defaultAgent?} where subflow is an inline plan {phases:[...]} (a dependency-bearing DAG: phases can use dependsOn / map / gate / reduce). Use a subflow when the delegated work itself has multiple coordinated steps.",
+		parameters: Type.Object({
+			assignments: Type.Array(
+				Type.Object({
+					task: Type.Optional(Type.String({ description: "A single child task prompt (use this OR subflow, not both)." })),
+					agent: Type.Optional(Type.String({ description: "Agent name for a flat task (optional)." })),
+					subflow: Type.Optional(Type.Unknown({ description: "An inline Taskflow plan {phases:[...]} or a bare phases array, run as a nested validated sub-flow." })),
+					defaultAgent: Type.Optional(Type.String({ description: "Fallback agent for subflow phases that don't name their own (optional)." })),
+				}),
+				{ description: "Child tasks to spawn (1..16). Each is a flat {task} or a {subflow} DAG." },
+			),
+		}),
+		async execute(_id, params) {
+			// Depth cap: walk the parent chain in the tree to find this node's depth.
+			try {
+				const depth = nodeDepth(readTree(ctxDir), nodeId);
+				if (depth >= MAX_DYNAMIC_NESTING) {
+					return textResult(
+						`ctx_spawn rejected: depth ${depth} >= MAX_DYNAMIC_NESTING (${MAX_DYNAMIC_NESTING}). Do the work yourself.`,
+						true,
+					);
+				}
+				const n = queueSpawn(ctxDir, nodeId, params.assignments);
+				return textResult(`Queued ${n} child task(s); they will run after you finish and their reports will be appended to your output.`);
+			} catch (e) {
+				return textResult(`ctx_spawn failed: ${e instanceof Error ? e.message : String(e)}`, true);
+			}
+		},
+	});
+}
+
 function errorResult(action: string, message: string): ToolResult {
 	return {
 		content: [{ type: "text", text: message }],

package/extensions/runner.ts

@@ -60,6 +60,14 @@ export interface RunOptions {
 	 * the prior behaviour (no idle timeout). Defaults to DEFAULT_IDLE_TIMEOUT_MS.
 	 */
 	idleTimeoutMs?: number;
+	/**
+	 * Shared Context Tree (opt-in). When set, the spawned subagent receives
+	 * PI_TASKFLOW_CTX_DIR + PI_TASKFLOW_NODE_ID in its environment and is loaded
+	 * with this extension via `--extension`, so it can register the ctx_* tools
+	 * (read/write/report/spawn) that read & write the per-run blackboard.
+	 */
+	ctxDir?: string;
+	nodeId?: string;
 }
 
 /**
@@ -71,6 +79,41 @@ export interface RunOptions {
  */
 const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
 
+/** The Shared Context Tree tool names a subagent may call when sharing is on. */
+export const CTX_TOOL_NAMES = ["ctx_read", "ctx_write", "ctx_report", "ctx_spawn"] as const;
+
+/**
+ * Guidance appended to a subagent's system prompt when the Shared Context Tree
+ * is enabled for its phase. Registering the ctx_* tools makes them AVAILABLE;
+ * this block is what makes the model actually USE them with the right discipline
+ * (read-before-you-explore; publish reusable findings; report up; delegate when
+ * work fans out). Kept short and imperative on purpose.
+ */
+export const CTX_TOOLS_GUIDANCE = [
+	"## Shared Context Tree (you are part of a coordinated team of agents)",
+	"",
+	"You are one agent in a tree working a shared goal, with a shared blackboard",
+	"and an upward report channel. Use these tools deliberately \u2014 they save tokens",
+	"and prevent the team from duplicating work:",
+	"",
+	"- ctx_read(key?): BEFORE exploring the codebase or re-reading files, call",
+	"  ctx_read with no arguments to see what teammates already discovered. If a",
+	"  finding you need already exists, REUSE it instead of re-deriving it.",
+	"- ctx_write(key, value): when you discover something other agents will likely",
+	"  need (a file map, an endpoint list, an interface, a config value), publish it",
+	"  under a short key (e.g. 'endpoints', 'db.schema'). Keep values concise and",
+	"  structured (JSON) so others can consume them directly.",
+	"- ctx_report(summary, structured?): when you finish, report your result upward",
+	"  so the parent task and downstream steps can see it. Lead with the outcome.",
+	"- ctx_spawn(assignments[]): if you discover the work should fan out into",
+	"  independent sub-tasks, delegate them as child agents. They run after you",
+	"  finish and their reports are folded back into your output. Only spawn when it",
+	"  genuinely parallelizes \u2014 otherwise just do the work yourself.",
+	"",
+	"Default habit: ctx_read first, do the work (reusing shared findings), ctx_write",
+	"anything reusable, then ctx_report your result.",
+].join("\n");
+
 export function isFailed(r: RunResult): boolean {
 	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
 }
@@ -281,6 +324,25 @@ function getPiInvocation(args: string[]): { command: string; args: string[] } {
 	return { command: "pi", args };
 }
 
+/**
+ * Resolve the path to this extension's entry file, so a spawned subagent can be
+ * launched with `--extension <path>` and register the ctx_* tools. Returns
+ * undefined if it cannot be resolved (the subagent then simply runs without the
+ * ctx tools — fail-open: context sharing degrades to "no sharing").
+ */
+export function ctxExtensionPath(): string | undefined {
+	const override = process.env.PI_TASKFLOW_EXT_PATH;
+	if (override) return override;
+	try {
+		const here = path.dirname(new URL(import.meta.url).pathname);
+		const entry = path.join(here, "index.ts");
+		if (fs.existsSync(entry)) return entry;
+	} catch {
+		/* fall through */
+	}
+	return undefined;
+}
+
 /**
  * Run a single subagent task. Resolves the agent from `agents` by name and
  * spawns an isolated pi process, returning structured output + usage.
@@ -310,7 +372,15 @@ export async function runAgentTask(
 
 	const model = opts.model ?? agent.model;
 	const thinking = opts.thinking ?? agent.thinking ?? globalThinking;
-	const tools = opts.tools ?? agent.tools;
+	const ctxEnabledEarly = Boolean(opts.ctxDir && opts.nodeId);
+	let tools = opts.tools ?? agent.tools;
+	// If the agent restricts tools to a whitelist, the ctx_* tools we register
+	// would be filtered out by `--tools` even though they're registered. When
+	// context sharing is on, extend the whitelist so the subagent can actually
+	// call them. (No whitelist = all tools available = nothing to do.)
+	if (ctxEnabledEarly && tools && tools.length > 0) {
+		tools = [...new Set([...tools, ...CTX_TOOL_NAMES])];
+	}
 
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
 	if (model) args.push("--model", model);
@@ -332,18 +402,40 @@ export async function runAgentTask(
 	};
 
 	try {
-		if (agent.systemPrompt.trim()) {
+		const ctxEnabled = Boolean(opts.ctxDir && opts.nodeId);
+		// Build the appended system prompt = the agent's own prompt PLUS, when the
+		// Shared Context Tree is enabled for this phase, a guidance block that tells
+		// the subagent the ctx_* tools exist and the discipline for using them.
+		// Without this the model only sees terse tool descriptions and rarely uses
+		// them proactively (capability != usage).
+		const appendedPrompt = [agent.systemPrompt.trim(), ctxEnabled ? CTX_TOOLS_GUIDANCE : ""]
+			.filter(Boolean)
+			.join("\n\n");
+		if (appendedPrompt) {
 			// Allocate the temp dir + path BEFORE any fallible I/O so that if
 			// writeFile throws, tmpPromptDir/tmpPromptPath are already set and
 			// the finally block can clean up the directory (F-004).
 			tmpPromptDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-taskflow-"));
 			const safeName = agent.name.replace(/[^\w.-]+/g, "_");
 			tmpPromptPath = path.join(tmpPromptDir, `prompt-${safeName}.md`);
-			await writePromptToTempFile(tmpPromptPath, agent.systemPrompt);
+			await writePromptToTempFile(tmpPromptPath, appendedPrompt);
 			args.push("--append-system-prompt", tmpPromptPath);
 		}
 		args.push(`Task: ${task}`);
 
+		// Shared Context Tree opt-in: load THIS extension into the subagent so it
+		// can register the ctx_* tools, and pass the blackboard dir + node id via
+		// env. `--extension` is the explicit, self-documenting fallback that does
+		// not rely on the subagent auto-discovering user/project extensions in
+		// `-p` mode. The env vars drive the dual-identity branch in index.ts.
+		const ctxEnv: Record<string, string> = {};
+		if (opts.ctxDir && opts.nodeId) {
+			const selfPath = ctxExtensionPath();
+			if (selfPath) args.push("--extension", selfPath);
+			ctxEnv.PI_TASKFLOW_CTX_DIR = opts.ctxDir;
+			ctxEnv.PI_TASKFLOW_NODE_ID = opts.nodeId;
+		}
+
 		let wasAborted = false;
 		let idleTimedOut = false;
 		let killedBySignal: string | undefined;
@@ -353,6 +445,7 @@ export async function runAgentTask(
 				cwd: opts.cwd ?? defaultCwd,
 				shell: false,
 				stdio: ["ignore", "pipe", "pipe"],
+				env: { ...process.env, ...ctxEnv },
 			});
 			if (proc.pid) activeChildren.add(proc.pid);
 			let buffer = "";