pi-taskflow 0.0.21 → 0.0.23

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;
@@ -206,7 +216,6 @@ async function runFlow(
 							},
 							done,
 							() => tui.terminal.rows,
-							tui.terminal,
 						);
 						const onAbort = () => done("reject");
 						signal?.addEventListener("abort", onAbort, { once: true });
@@ -293,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);
@@ -799,8 +823,13 @@ export default function (pi: ExtensionAPI) {
 					);
 					return;
 				}
-				const result = await ctx.ui.custom<RunHistoryResult | undefined>((_tui, theme, _kb, done) => {
-					return new RunHistoryComponent(runs, theme, (r) => done(r));
+				const result = await ctx.ui.custom<RunHistoryResult | undefined>((tui, theme, _kb, done) => {
+					const comp = new RunHistoryComponent(runs, theme, (r) => done(r), {
+						refresh: () => listRuns(ctx.cwd, 50),
+						requestRender: () => tui.requestRender(),
+						intervalMs: 1000,
+					});
+					return comp;
 				});
 				if (result?.action === "resume") {
 					if (ctx.isIdle()) {
@@ -908,6 +937,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/interpolate.ts

@@ -8,8 +8,11 @@
  *   {previous.output}   alias for the immediately-preceding completed phase output
  *   {item} / {item.f}   map loop variable (or custom name via phase.as)
  *
- * Unknown placeholders are left intact (with a recorded warning) rather than
- * throwing, so a partially-specified task still runs.
+ * Unknown placeholders are left intact rather than throwing, so a
+ * partially-specified task still runs. The unresolved refs are returned in
+ * `missing[]`; the runtime surfaces them as a phase warning (see
+ * `warnUnresolvedRefs` in runtime.ts) — logged and persisted to
+ * `PhaseState.warnings`.
  */
 
 export interface InterpolationContext {
@@ -123,13 +126,21 @@ export function safeParse(text: string): unknown {
 	} catch {
 		// noop
 	}
-	// Extract from a ```json fenced block
-	const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
-	if (fence) {
+	// Extract from fenced blocks. Outputs often contain multiple fences
+	// (e.g. a ```typescript evidence block before the ```json payload), so try
+	// every fence — json-tagged blocks first, then untagged/other blocks.
+	const fenceRe = /```(\w*)[ \t]*\r?\n?([\s\S]*?)```/g;
+	const fenced: { lang: string; body: string }[] = [];
+	let fm: RegExpExecArray | null;
+	while ((fm = fenceRe.exec(trimmed)) !== null) {
+		fenced.push({ lang: fm[1].toLowerCase(), body: fm[2].trim() });
+	}
+	const ordered = [...fenced.filter((b) => b.lang === "json"), ...fenced.filter((b) => b.lang !== "json")];
+	for (const block of ordered) {
 		try {
-			return JSON.parse(fence[1].trim());
+			return JSON.parse(block.body);
 		} catch {
-			// noop
+			// noop — try the next fence
 		}
 	}
 	// Extract the first balanced [...] or {...}

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 = "";

package/extensions/runs-view.ts

@@ -40,6 +40,19 @@ function isResumable(r: RunState): boolean {
 	return r.status === "paused" || r.status === "failed";
 }
 
+/** Detect whether a refreshed run list differs from the current one in any way
+ * the panel renders (status, updatedAt, phase progress, membership). */
+function hasChanged(prev: RunState[], next: RunState[]): boolean {
+	if (prev.length !== next.length) return true;
+	const byId = new Map(prev.map((r) => [r.runId, r]));
+	for (const n of next) {
+		const p = byId.get(n.runId);
+		if (!p) return true;
+		if (p.status !== n.status || p.updatedAt !== n.updatedAt) return true;
+	}
+	return false;
+}
+
 export class RunHistoryComponent {
 	private runs: RunState[];
 	private theme: Theme;
@@ -48,14 +61,62 @@ export class RunHistoryComponent {
 	private mode: "list" | "detail" = "list";
 	private cachedWidth?: number;
 	private cachedLines?: string[];
+	/** Live-refresh wiring: re-read run state from disk while the panel is open
+	 * so background (detached) runs show live progress without reopening. */
+	private timer?: ReturnType<typeof setInterval>;
+	private refresh?: () => RunState[];
+	private requestRender?: () => void;
 
-	constructor(runs: RunState[], theme: Theme, onDone: (result?: RunHistoryResult) => void) {
+	constructor(
+		runs: RunState[],
+		theme: Theme,
+		onDone: (result?: RunHistoryResult) => void,
+		/** Optional live-refresh hooks. When both are provided the panel polls
+		 * `refresh()` on an interval and calls `requestRender()` if anything changed. */
+		live?: { refresh: () => RunState[]; requestRender: () => void; intervalMs?: number },
+	) {
 		if (!runs.length) {
 			throw new Error("RunHistoryComponent requires at least one run");
 		}
 		this.runs = runs;
 		this.theme = theme;
 		this.onDone = onDone;
+		if (live) {
+			this.refresh = live.refresh;
+			this.requestRender = live.requestRender;
+			const intervalMs = Math.max(250, live.intervalMs ?? 1000);
+			this.timer = setInterval(() => this.poll(), intervalMs);
+			// Don't keep the event loop alive just for the panel refresh.
+			(this.timer as { unref?: () => void }).unref?.();
+		}
+	}
+
+	/** Re-read run state; if anything changed, refresh the cached render. */
+	private poll(): void {
+		if (!this.refresh) return;
+		let next: RunState[];
+		try {
+			next = this.refresh();
+		} catch {
+			return; // transient read/lock error — try again next tick
+		}
+		if (!next.length) return;
+		if (!hasChanged(this.runs, next)) return;
+		// Preserve the user's selection by runId across refreshes.
+		const selectedId = this.runs[this.selected]?.runId;
+		this.runs = next;
+		const idx = next.findIndex((r) => r.runId === selectedId);
+		this.selected = idx >= 0 ? idx : Math.min(this.selected, next.length - 1);
+		this.invalidate();
+		this.requestRender?.();
+	}
+
+	/** Stop the refresh timer when the panel closes. */
+	dispose(): void {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = undefined;
+		}
 	}
 
 	handleInput(data: string): void {
@@ -104,7 +165,8 @@ export class RunHistoryComponent {
 			for (const l of renderProgress(run, th).split("\n")) lines.push(truncateToWidth(l, width));
 			lines.push("");
 			const hint = isResumable(run) ? "Esc back · r resume" : "Esc back";
-			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}`, width));
+			const liveTag = this.timer && run.status === "running" ? th.fg("success", " ● live") : "";
+			lines.push(truncateToWidth(`  ${th.fg("dim", hint)}${liveTag}`, width));
 			lines.push("");
 			this.cachedWidth = width;
 			this.cachedLines = lines;
@@ -129,7 +191,11 @@ export class RunHistoryComponent {
 		});
 
 		lines.push("");
-		lines.push(truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}`, width));
+		const anyRunning = this.runs.some((r) => r.status === "running");
+		const liveHint = this.timer && anyRunning ? th.fg("success", " ● live") : "";
+		lines.push(
+			truncateToWidth(`  ${th.fg("dim", "↑↓ select · Enter details · r resume · q close")}${liveHint}`, width),
+		);
 		lines.push("");
 
 		this.cachedWidth = width;