pi-agent-flow 0.4.5 → 1.0.0

package/README.md

@@ -49,6 +49,8 @@ pi install .
 - **Cycle prevention** — blocks recursive delegation chains
 - **Flow discovery** — reads definitions from `~/.pi/agent/agents/` and `.pi/agents/`
 - **TUI rendering** — rich collapsed/expanded display in interactive mode
+- **Post-flow hooks** — automatic advisory messages after successful flows (e.g., code → review)
+- **Smooth streaming metrics** — context token counters increment tick-by-tick during active streaming instead of jumping at boundaries
 
 ---
 
@@ -113,6 +115,38 @@ flow [explore] accomplished
 
 ---
 
+## Post-Flow Hooks
+
+When certain flows complete successfully, the system can inject advisory messages suggesting follow-up flows. This keeps the agent on the optimal path without requiring the user to manually chain flows.
+
+### Built-in Hooks
+
+| Hook | Trigger | Advice |
+|------|---------|--------|
+| `code → review` | A `[code]` flow succeeds | *"Consider running a [review] flow to audit the changes…"* |
+| `debug → code` | A `[debug]` flow succeeds | *"The root cause has been identified. Consider running a [code] flow to implement the fix."* |
+
+Hooks are smart: if the agent already included the suggested flow in the same batch, the advisory is suppressed to avoid redundancy.
+
+### Extending
+
+Hooks are registered via `registerHook()` in `hooks.ts`. Each hook defines a trigger (flow type + success requirement) and an action that returns advisory text. The hook system mirrors the flow discovery pattern, making it easy to add domain-specific hints.
+
+Example — a custom `explore → architect` hook:
+
+```ts
+registerHook({
+  name: "my/explore-to-architect",
+  trigger: { flowTypes: ["explore"], onlyOnSuccess: true },
+  action: (ctx) => ({
+    content: "Consider running an [architect] flow to design a solution.",
+    priority: 10,
+  }),
+});
+```
+
+---
+
 ## Usage
 
 ### Single flow
@@ -143,6 +177,9 @@ flow [explore] accomplished
 | `--flow-max-depth [n]` | Maximum delegation depth | `3` |
 | `--flow-prevent-cycles` | Block cyclic delegation | `true` |
 | `--no-flow-prevent-cycles` | Disable cycle prevention | — |
+| `--flow-lite-model [model]` | Model for lite-tier flows (`explore`, `debug`) | — |
+| `--flow-flash-model [model]` | Model for flash-tier flows (`code`, `review`) | — |
+| `--flow-full-model [model]` | Model for full-tier flows (`brainstorm`, `architect`) | — |
 
 ### Environment variables (propagated to child processes)
 

package/agents.ts

@@ -17,6 +17,8 @@ import * as path from "node:path";
 
 export type FlowScope = "user" | "project" | "both" | "bundled" | "all";
 
+export type FlowTier = "lite" | "flash" | "full";
+
 export interface FlowConfig {
 	name: string;
 	description: string;
@@ -25,6 +27,7 @@ export interface FlowConfig {
 	thinking?: string;
 	maxDepth?: number;
 	inheritContext?: boolean;
+	tier?: FlowTier;
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -35,6 +38,24 @@ export interface FlowDiscoveryResult {
 	projectFlowsDir: string | null;
 }
 
+/** Determine the model tier for a given flow name. */
+export function getFlowTier(flowName: string): FlowTier {
+	const normalized = flowName.toLowerCase().trim();
+	switch (normalized) {
+		case "explore":
+		case "debug":
+			return "lite";
+		case "code":
+		case "review":
+			return "flash";
+		case "brainstorm":
+		case "architect":
+			return "full";
+		default:
+			return "flash";
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -169,6 +190,7 @@ function parseFlowFile(filePath: string, source: "user" | "project" | "bundled")
 		thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
 		maxDepth,
 		inheritContext,
+		tier: getFlowTier(name),
 		systemPrompt: body,
 		source,
 		filePath,

package/flow.ts

@@ -10,9 +10,9 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import type { FlowConfig } from "./agents.js";
+import { type FlowConfig, getFlowTier } from "./agents.js";
 import { parseFlowCliArgs } from "./runner-cli.js";
-import { processFlowJsonLine, drainStreamingText, drainStreamingEstimate } from "./runner-events.js";
+import { processFlowJsonLine, drainStreamingText, drainStreamingEstimate, drainCtxEstimate } from "./runner-events.js";
 import {
 	type SingleResult,
 	type FlowDetails,
@@ -33,14 +33,21 @@ const PI_OFFLINE_ENV = "PI_OFFLINE";
 type FlowUpdateCallback = (partial: AgentToolResult<FlowDetails>) => void;
 
 /**
- * Merge actual usage with streaming estimate.
+ * Merge actual usage with streaming estimates.
  * Uses Math.max for output to avoid double-counting.
+ * Uses Math.max for contextTokens so the ctx estimate (baseline + streaming)
+ * smoothly increments during active streaming.
  */
-function mergeStreamingUsage(actual: SingleResult["usage"], estimatedTokens: number): SingleResult["usage"] {
-	if (estimatedTokens <= 0) return actual;
+function mergeStreamingUsage(
+	actual: SingleResult["usage"],
+	estimatedOutputTokens: number,
+	ctxEstimate: number,
+): SingleResult["usage"] {
+	if (estimatedOutputTokens <= 0 && ctxEstimate <= 0) return actual;
 	return {
 		...actual,
-		output: Math.max(actual.output, estimatedTokens),
+		...(estimatedOutputTokens > 0 ? { output: Math.max(actual.output, estimatedOutputTokens) } : {}),
+		...(ctxEstimate > 0 ? { contextTokens: Math.max(actual.contextTokens, ctxEstimate) } : {}),
 	};
 }
 
@@ -94,6 +101,7 @@ function buildFlowArgs(
 	flow: FlowConfig,
 	intent: string,
 	forkSessionPath: string | null,
+	tieredModels?: { lite?: string; flash?: string; full?: string },
 ): string[] {
 	const args: string[] = [
 		"--mode",
@@ -108,7 +116,9 @@ function buildFlowArgs(
 		args.push("--session", forkSessionPath);
 	}
 
-	const model = flow.model ?? inheritedCliArgs.fallbackModel;
+	const tier = getFlowTier(flow.name);
+	const tierModel = tieredModels?.[tier] ?? inheritedCliArgs.tieredModels?.[tier];
+	const model = flow.model ?? tierModel ?? inheritedCliArgs.fallbackModel;
 	if (model) args.push("--model", model);
 
 	const thinking = flow.thinking ?? inheritedCliArgs.fallbackThinking;
@@ -165,6 +175,8 @@ export interface RunFlowOptions {
 	maxDepth: number;
 	/** Whether cycle prevention should be enforced in child processes. */
 	preventCycles: boolean;
+	/** Tiered model overrides (lite/flash/full). */
+	tieredModels?: { lite?: string; flash?: string; full?: string };
 	/** Abort signal for cancellation. */
 	signal?: AbortSignal;
 	/** Streaming update callback. */
@@ -210,6 +222,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		};
 	}
 
+	const resolvedModel = flow.model ?? inheritedCliArgs.fallbackModel;
 	const result: SingleResult = {
 		type: normalizedFlowName,
 		agentSource: flow.source,
@@ -218,13 +231,14 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 		messages: [],
 		stderr: "",
 		usage: emptyFlowUsage(),
-		model: flow.model,
+		model: resolvedModel,
 	};
 
 	const emitUpdate = () => {
 		const streaming = drainStreamingText(result);
 		const estimatedTokens = drainStreamingEstimate(result);
-		const mergedUsage = mergeStreamingUsage(result.usage, estimatedTokens);
+		const ctxEst = drainCtxEstimate(result);
+		const mergedUsage = mergeStreamingUsage(result.usage, estimatedTokens, ctxEst);
 		onUpdate?.({
 			content: [
 				{
@@ -250,6 +264,7 @@ export async function runFlow(opts: RunFlowOptions): Promise<SingleResult> {
 			flow,
 			intent,
 			forkSessionTmpPath,
+			opts.tieredModels,
 		);
 		let wasAborted = false;
 

package/hooks.ts

@@ -0,0 +1,105 @@
+/**
+ * Post-flow hook registry.
+ *
+ * Hooks inject advisory messages into flow tool results after execution.
+ * Built-in hooks fire automatically; user hooks can be registered via `registerHook()`.
+ */
+
+import {
+	type PostFlowHook,
+	type SingleResult,
+	isFlowSuccess,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Module-scoped hook registry
+// ---------------------------------------------------------------------------
+
+const hooks: PostFlowHook[] = [];
+
+/**
+ * Register or replace a hook by name.
+ * If a hook with the same name already exists, it is replaced.
+ */
+export function registerHook(hook: PostFlowHook): void {
+	const idx = hooks.findIndex((h) => h.name === hook.name);
+	if (idx >= 0) hooks[idx] = hook;
+	else hooks.push(hook);
+}
+
+/**
+ * Run all registered hooks against the given flow results.
+ * Returns an array of advisory strings sorted by priority.
+ */
+export function runHooks(
+	params: Array<{ type: string; intent: string }>,
+	results: SingleResult[],
+): string[] {
+	const messages: Array<{ priority: number; content: string }> = [];
+
+	for (const hook of hooks) {
+		const triggerTypes = new Set(
+			hook.trigger.flowTypes.map((t) => t.toLowerCase()),
+		);
+		const onlyOnSuccess = hook.trigger.onlyOnSuccess !== false;
+
+		const matching = results.filter((r) => triggerTypes.has(r.type));
+		if (matching.length === 0) continue;
+		if (onlyOnSuccess && !matching.every((r) => isFlowSuccess(r))) continue;
+
+		const result = hook.action({ results: matching, params });
+		if (result) {
+			messages.push({ priority: result.priority ?? 0, content: result.content });
+		}
+	}
+
+	messages.sort((a, b) => a.priority - b.priority);
+	return messages.map((m) => m.content);
+}
+
+/**
+ * Clear all registered hooks. For testing only.
+ */
+export function clearHooks(): void {
+	hooks.length = 0;
+}
+
+// ---------------------------------------------------------------------------
+// Built-in hooks
+// ---------------------------------------------------------------------------
+
+/** Suggest review flow after a successful code flow. */
+registerHook({
+	name: "pi-agent-flow/code-to-review",
+	trigger: { flowTypes: ["code"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const reviewWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "review",
+		);
+		if (reviewWasRequested) return null;
+
+		return {
+			content:
+				"Consider running a [review] flow to audit the changes for security, correctness, and code quality.",
+			priority: 10,
+		};
+	},
+});
+
+/** Suggest code flow after a successful debug flow. */
+registerHook({
+	name: "pi-agent-flow/debug-to-code",
+	trigger: { flowTypes: ["debug"], onlyOnSuccess: true },
+	action: (ctx) => {
+		const codeWasRequested = ctx.params.some(
+			(p) => p.type.toLowerCase() === "code",
+		);
+		if (codeWasRequested) return null;
+
+		return {
+			content:
+				"The root cause has been identified. Consider running a [code] flow to implement the fix.",
+			priority: 10,
+		};
+	},
+});

package/index.ts

@@ -8,8 +8,10 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { type FlowConfig, discoverFlows } from "./agents.js";
+import { loadFlowModels, type FlowModelConfig } from "./config.js";
 import { renderFlowCall, renderFlowResult } from "./render.js";
 import { getFlowSummaryText } from "./runner-events.js";
+import { runHooks } from "./hooks.js";
 import { mapFlowConcurrent, runFlow } from "./flow.js";
 import {
 	type SingleResult,
@@ -322,6 +324,44 @@ async function confirmProjectFlowsIfNeeded(
 	);
 }
 
+// ---------------------------------------------------------------------------
+// Reminder flow injection (sliding — always on latest user message)
+// ---------------------------------------------------------------------------
+
+const REMINDER_TEXT =
+	"\n\n[reminder_flow: If the answer is in context, reply; otherwise, delegate to the appropriate flow.]";
+
+function stripReminder(
+	content: string | { type: string; text?: string }[],
+): string | { type: string; text?: string }[] {
+	if (typeof content === "string") {
+		return content.replace(REMINDER_TEXT, "");
+	}
+	return content.map((c) => {
+		if (c.type === "text" && typeof c.text === "string") {
+			return { ...c, text: c.text.replace(REMINDER_TEXT, "") };
+		}
+		return c;
+	});
+}
+
+function appendReminder(
+	content: string | { type: string; text?: string }[],
+): string | { type: string; text?: string }[] {
+	if (typeof content === "string") {
+		return content + REMINDER_TEXT;
+	}
+	const copy = [...content];
+	const lastTextIdx = copy.map((c, i) => (c.type === "text" ? i : -1)).filter((i) => i !== -1).pop();
+	if (lastTextIdx === undefined) {
+		copy.push({ type: "text", text: REMINDER_TEXT });
+	} else {
+		const block = copy[lastTextIdx] as { type: "text"; text: string };
+		copy[lastTextIdx] = { ...block, text: block.text + REMINDER_TEXT };
+	}
+	return copy;
+}
+
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
@@ -335,12 +375,25 @@ export default function (pi: ExtensionAPI) {
 		description: "Block delegating to flows already in the current delegation stack (default: true).",
 		type: "boolean",
 	});
+	pi.registerFlag("flow-lite-model", {
+		description: "Model for lite-tier flows (explore, debug).",
+		type: "string",
+	});
+	pi.registerFlag("flow-flash-model", {
+		description: "Model for flash-tier flows (code, review).",
+		type: "string",
+	});
+	pi.registerFlag("flow-full-model", {
+		description: "Model for full-tier flows (brainstorm, architect).",
+		type: "string",
+	});
 
 	const depthConfig = resolveFlowDepthConfig(pi);
 	const { currentDepth, maxDepth, canDelegate, ancestorFlowStack, preventCycles } =
 		depthConfig;
 
 	let discoveredFlows: FlowConfig[] = [];
+	let flowModelConfig: FlowModelConfig = {};
 
 	// Auto-discover flows on session start
 	pi.on("session_start", async (_event, ctx) => {
@@ -348,6 +401,7 @@ export default function (pi: ExtensionAPI) {
 
 		const discovery = discoverFlows(ctx.cwd, "all");
 		discoveredFlows = discovery.flows;
+		flowModelConfig = loadFlowModels(ctx.cwd);
 	});
 
 	// Inject available flows into the system prompt
@@ -394,6 +448,30 @@ flow [type] accomplished
 		};
 	});
 
+	// Sliding reminder: strip from all earlier user messages, append to latest
+	pi.on("context", async (event) => {
+		const messages = event.messages;
+		const userIndices = messages
+			.map((m, i) => (m.role === "user" ? i : -1))
+			.filter((i) => i !== -1);
+
+		if (userIndices.length === 0) return undefined;
+
+		const lastUserIndex = userIndices[userIndices.length - 1];
+
+		const modified = messages.map((msg, idx) => {
+			if (msg.role !== "user") return msg;
+
+			const content = stripReminder(msg.content);
+			if (idx === lastUserIndex) {
+				return { ...msg, content: appendReminder(content) };
+			}
+			return { ...msg, content };
+		});
+
+		return { messages: modified };
+	});
+
 	// Register the flow tool
 	if (canDelegate) {
 		pi.registerTool({
@@ -415,6 +493,13 @@ flow [type] accomplished
 				const { flows } = discovery;
 				const makeDetails = makeFlowDetailsFactory(discovery.projectFlowsDir);
 
+				// Resolve tiered models: CLI flags override settings.json overrides parent --model
+				const tieredModels = {
+					lite: (pi.getFlag("flow-lite-model") as string | undefined) ?? flowModelConfig.lite,
+					flash: (pi.getFlag("flow-flash-model") as string | undefined) ?? flowModelConfig.flash,
+					full: (pi.getFlag("flow-full-model") as string | undefined) ?? flowModelConfig.full,
+				};
+
 				// Build fork session snapshot (shared across all flows that inherit context)
 				const forkSessionSnapshotJsonl = buildForkSessionSnapshotJsonl(
 					ctx.sessionManager,
@@ -514,6 +599,7 @@ flow [type] accomplished
 						parentFlowStack: ancestorFlowStack,
 						maxDepth: effectiveMaxDepth,
 						preventCycles,
+						tieredModels,
 						signal,
 						onUpdate: (partial) => {
 							if (partial.details?.results[0]) {
@@ -536,18 +622,24 @@ flow [type] accomplished
 					return `flow [${r.type}] ${status}\n\n${output}`;
 				});
 
+				// Post-flow hooks — inject advisory messages
+				const advisors = runHooks(params.flow, results);
+				const advisorBlock = advisors.length > 0
+					? "\n\n---\n\n💡 " + advisors.join("\n💡 ")
+					: "";
+
 				return {
 					content: [{
 						type: "text" as const,
-						text: `Flow: ${successCount}/${results.length} completed\n\n${flowReports.join("\n\n---\n\n")}`,
+						text: `Flow: ${successCount}/${results.length} completed\n\n${flowReports.join("\n\n---\n\n")}${advisorBlock}`,
 					}],
 					details: makeDetails(results),
 				};
 			},
 
 			renderCall: (args, theme) => renderFlowCall(args, theme),
-			renderResult: (result, { expanded }, theme) =>
-				renderFlowResult(result, expanded, theme),
+			renderResult: (result, { expanded }, theme, args) =>
+				renderFlowResult(result, expanded, theme, args),
 		});
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-flow",
-  "version": "0.4.5",
+  "version": "1.0.0",
   "description": "Flow-state delegation extension for Pi coding agent.",
   "type": "module",
   "main": "index.ts",
@@ -8,6 +8,7 @@
     "index.ts",
     "agents.ts",
     "flow.ts",
+    "hooks.ts",
     "runner-cli.js",
     "runner-events.js",
     "render.ts",

package/render-utils.ts

@@ -1,5 +1,5 @@
 /**
- * Pure utility functions for rendering — extracted for testability.
+ * Pure utility functions for rendering - extracted for testability.
  */
 
 import type { UsageStats } from "./types.js";
@@ -27,39 +27,37 @@ export function formatFixedTokens(count: number): string {
 }
 
 /**
- * Format flow type name to fixed width (10 chars) in lowercase with dot padding.
- * Examples: "debug" → "debug.....", "architect" → "architect.", "brainstorm" → "brainstorm"
+ * Format flow type name to fixed width (10 chars) in lowercase with space padding.
+ * Examples: "debug" → "debug     ", "architect" → "architect ", "brainstorm" → "brainstorm"
  */
 export function formatFlowTypeName(type: string): string {
 	const lower = type.toLowerCase();
 	const targetWidth = 10;
 	if (lower.length >= targetWidth) return lower.slice(0, targetWidth);
-	return lower + ".".repeat(targetWidth - lower.length);
+	return lower.padEnd(targetWidth, " ");
 }
 
 export function formatCompactStats(usage: Partial<UsageStats>, model?: string, maxWidth?: number): string {
 	const parts: string[] = [];
-	parts.push(`${formatFixedTokens(usage.input || 0)}↑`);
-	parts.push(`${formatFixedTokens(usage.output || 0)}↓`);
-	if (usage.cacheRead) parts.push(`cr:${formatFixedTokens(usage.cacheRead)}`);
-	if (usage.contextTokens && usage.contextTokens > 0) parts.push(`ctx:${formatFixedTokens(usage.contextTokens)}`);
+	parts.push(`↑ ${formatFixedTokens(usage.input || 0)}`);
+	parts.push(`↓ ${formatFixedTokens(usage.output || 0)}`);
+	parts.push(`act: ${formatFixedTokens(usage.toolCalls || 0)}`);
+	parts.push(`ctx: ${formatFixedTokens(usage.contextTokens || 0)}`);
 
-	let result = `[ ${parts.join(" ")} ]${model ? ` ─ ${model}` : ""}`;
+	let result = parts.join(" · ") + (model ? ` · ${model}` : "");
 
 	if (maxWidth && visibleLength(result) > maxWidth) {
 		// Drop model first
-		let narrow = `[ ${parts.join(" ")} ]`;
+		let narrow = parts.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
 		// Drop context tokens
-		const narrowParts = parts.slice();
-		const ctxIndex = narrowParts.findIndex((p) => p.startsWith("ctx:"));
-		if (ctxIndex !== -1) narrowParts.splice(ctxIndex, 1);
-		narrow = `[ ${narrowParts.join(" ")} ]`;
+		const narrowParts = parts.slice(0, 3); // up to act
+		narrow = narrowParts.join(" · ");
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
 		// Bare minimum (just input/output)
-		narrow = `[ ${parts[0]} ${parts[1]} ]`;
+		narrow = `${parts[0]} · ${parts[1]}`;
 		if (visibleLength(narrow) <= maxWidth) return narrow;
 
 		return truncateChars(result, maxWidth);
@@ -87,7 +85,7 @@ export function getTruncationBudget(prefixLength: number): number {
 	return Math.max(width - prefixLength, 1);
 }
 
-/** Fixed content budget for collapsed-line text (dir/exe/log). */
+/** Fixed content budget for collapsed-line text (dir/act/log). */
 export const CONTENT_MAX = 60;
 
 /**
@@ -102,19 +100,12 @@ export function contentBudget(prefixVisibleLen: number): number {
  * Truncate an ANSI-colored string to at most `max` visible characters,
  * preserving ANSI codes in the kept portions. Does not inject reset codes
  * — the caller is responsible for closing any open styles.
+ * 
+ * Refactored to perform head-truncation (start + ...) instead of middle-truncation.
  */
 function truncateAnsi(text: string, max: number): string {
 	if (visibleLength(text) <= max) return text;
 
-	if (max < 3) {
-		// Not enough room for '…' — just truncate without ellipsis
-		const { raw } = takeVisible(text, max);
-		return raw;
-	}
-
-	const head = Math.ceil(max * 0.6);
-	const tail = max - head - 1; // 1 = '…'.length
-
 	// Walk through the string, collecting raw chars until we've consumed
 	// `count` visible characters. ANSI sequences are copied through without
 	// counting toward the limit.
@@ -142,36 +133,19 @@ function truncateAnsi(text: string, max: number): string {
 		return { raw, consumed: visible };
 	}
 
-	// Take head from the start
-	const headResult = takeVisible(text, head);
-
-	// Take tail from the end (walk backwards)
-	function takeVisibleFromEnd(src: string, count: number): string {
-		let visible = 0;
-		let i = src.length - 1;
-		while (i >= 0 && visible < count) {
-			// Check if current char is end of an ANSI sequence
-			if (src[i] === "m") {
-				const escStart = src.lastIndexOf("\x1b[", i);
-				if (escStart !== -1 && escStart < i) {
-					const seq = src.slice(escStart, i + 1);
-					if (/^\x1b\[[0-9;]*m$/.test(seq)) {
-						// This is an ANSI sequence — don't count, skip past it
-						i = escStart - 1;
-						continue;
-					}
-				}
-			}
-			visible++;
-			i--;
-		}
-		// Extract the raw substring from (i+1) to end, including any trailing ANSI
-		return src.slice(i + 1);
+	if (max < 3) {
+		// Not enough room for '...' — just truncate without ellipsis
+		const { raw } = takeVisible(text, max);
+		return raw;
 	}
 
-	const tailRaw = takeVisibleFromEnd(text, tail);
+	const keep = max - 3; // 3 = '...'.length
+	const ellipsis = "...";
+
+// Take head from the start
+	const headResult = takeVisible(text, keep);
 
-	return headResult.raw + "\u2026" + tailRaw;
+	return headResult.raw + ellipsis;
 }
 
 export function truncateChars(text: string, max: number): string {

package/render.ts

@@ -22,7 +22,7 @@ import {
 	isFlowError,
 	isFlowSuccess,
 } from "./types.js";
-import { formatFixedTokens, formatCompactStats, formatFlowTypeName, truncateChars, contentBudget } from "./render-utils.js";
+import { formatCompactStats, formatFlowTypeName, truncateChars, contentBudget } from "./render-utils.js";
 
 function shortenPath(p: string): string {
 	const home = os.homedir();
@@ -126,11 +126,26 @@ export function renderFlowResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: unknown },
 	expanded: boolean,
 	theme: FlowTheme,
+	args?: Record<string, any>,
 ): Container | Text {
 	const details = result.details as FlowDetails | undefined;
 	const streamingText = result.content?.[0]?.type === "text" ? result.content[0].text : undefined;
 
 	if (!details || details.results.length === 0) {
+		// Ghost Dashboard: render a placeholder status line during the zero state
+		const flowRequest = args?.flow?.[0];
+		if (flowRequest) {
+			const ghostResult: SingleResult = {
+				type: flowRequest.type || "unknown",
+				agentSource: "user",
+				intent: flowRequest.intent || "Processing...",
+				exitCode: -1, // In progress
+				messages: [],
+				stderr: "",
+				usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0, toolCalls: 0 },
+			};
+			return renderFlowCollapsed(ghostResult, flowStatusIcon(ghostResult, theme), false, streamingText || "", theme);
+		}
 		return new Text(streamingText || "", 0, 0);
 	}
 
@@ -182,13 +197,8 @@ function renderFlowExpanded(
 		container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
 	}
 
-	// Stats: all-in-one bracket format with context inline
-	const statsParts: string[] = [];
-	statsParts.push(`${formatFixedTokens(r.usage.input || 0)}↑`);
-	statsParts.push(`${formatFixedTokens(r.usage.output || 0)}↓`);
-	if (r.usage.cacheRead) statsParts.push(`cr:${formatFixedTokens(r.usage.cacheRead)}`);
-	if (r.usage.contextTokens > 0) statsParts.push(`ctx:${formatFixedTokens(r.usage.contextTokens)}`);
-	const inlineStats = `[ ${statsParts.join(" ")} ]${r.model ? ` ─ ${r.model}` : ""}`;
+	// Stats: dashboard format
+	const inlineStats = formatCompactStats(r.usage, r.model);
 	container.addChild(new Text(theme.fg("dim", inlineStats), 0, 0));
 
 	// Intent
@@ -239,12 +249,12 @@ function renderFlowCollapsed(
 		container.addChild(new TruncatedText(`${theme.fg("dim", "├─ dir:")} ${theme.fg("dim", dirContent)}`, 0, 0));
 	}
 
-	// exe: line (last tool call)
+	// act: line (last tool call)
 	const lastTool = getLastToolCall(r.messages);
 	if (lastTool) {
-		const exeStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
-		const exeContent = truncateChars(exeStr, contentBudget(10));
-		container.addChild(new TruncatedText(`${theme.fg("dim", "├─ exe:")} ${exeContent}`, 0, 0));
+		const actStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
+		const actContent = truncateChars(actStr, contentBudget(10));
+		container.addChild(new TruncatedText(`${theme.fg("dim", "├─ act:")} ${actContent}`, 0, 0));
 	}
 
 	// log: line (last assistant text or streaming)
@@ -308,13 +318,8 @@ function renderMultiFlowExpanded(
 		// Per-flow header: ─── EXPLORER (no icon)
 		container.addChild(new Text(`${theme.fg("muted", "─── ")}${theme.fg("accent", typeName)}`, 0, 0));
 
-		// Stats: all-in-one bracket format with context inline
-		const flowParts: string[] = [];
-		flowParts.push(`${formatFixedTokens(r.usage.input || 0)}↑`);
-		flowParts.push(`${formatFixedTokens(r.usage.output || 0)}↓`);
-		if (r.usage.cacheRead) flowParts.push(`cr:${formatFixedTokens(r.usage.cacheRead)}`);
-		if (r.usage.contextTokens > 0) flowParts.push(`ctx:${formatFixedTokens(r.usage.contextTokens)}`);
-		const flowStats = `[ ${flowParts.join(" ")} ]${r.model ? ` ─ ${r.model}` : ""}`;
+		// Stats: dashboard format
+		const flowStats = formatCompactStats(r.usage, r.model);
 		container.addChild(new Text(theme.fg("dim", flowStats), 0, 0));
 
 		// Intent: just show text, no prefix
@@ -334,15 +339,10 @@ function renderMultiFlowExpanded(
 		}
 	}
 
-	// Total stats: all-in-one bracket format with context inline
+	// Total stats: dashboard format
 	const totalUsage = aggregateFlowUsage(results);
 	const totalModel = results[0]?.model;
-	const totalParts: string[] = [];
-	totalParts.push(`${formatFixedTokens(totalUsage.input || 0)}↑`);
-	totalParts.push(`${formatFixedTokens(totalUsage.output || 0)}↓`);
-	if (totalUsage.cacheRead) totalParts.push(`cr:${formatFixedTokens(totalUsage.cacheRead)}`);
-	if (totalUsage.contextTokens > 0) totalParts.push(`ctx:${formatFixedTokens(totalUsage.contextTokens)}`);
-	const totalStats = `[ ${totalParts.join(" ")} ]${totalModel ? ` ─ ${totalModel}` : ""}`;
+	const totalStats = formatCompactStats(totalUsage, totalModel);
 	container.addChild(new Spacer(1));
 	container.addChild(new Text(theme.fg("dim", totalStats), 0, 0));
 
@@ -380,12 +380,12 @@ function renderActivityPanel(
 			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "├─ dir:")} ${theme.fg("dim", dirContent)}`, 0, 0));
 		}
 
-		// exe: line (last tool call)
+		// act: line (last tool call)
 		const lastTool = getLastToolCall(r.messages);
 		if (lastTool) {
-			const exeStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
-			const exeContent = truncateChars(exeStr, contentBudget(10));
-			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "├─ exe:")} ${exeContent}`, 0, 0));
+			const actStr = formatFlowToolCall(lastTool.name, lastTool.args, theme.fg.bind(theme));
+			const actContent = truncateChars(actStr, contentBudget(10));
+			container.addChild(new TruncatedText(`${theme.fg("dim", indent + "├─ act:")} ${actContent}`, 0, 0));
 		}
 
 		// log: line (last assistant text)

package/runner-cli.js

@@ -48,6 +48,9 @@ export function parseFlowCliArgs(argv) {
   let fallbackThinking;
   let fallbackTools;
   let fallbackNoTools = false;
+  let tieredLiteModel;
+  let tieredFlashModel;
+  let tieredFullModel;
 
   let i = 2; // skip executable + script name
   while (i < argv.length) {
@@ -198,6 +201,27 @@ export function parseFlowCliArgs(argv) {
       continue;
     }
 
+    if (flagName === "--flow-lite-model") {
+      const [value, skip] = getValue();
+      if (value !== undefined) tieredLiteModel = value;
+      i += skip;
+      continue;
+    }
+
+    if (flagName === "--flow-flash-model") {
+      const [value, skip] = getValue();
+      if (value !== undefined) tieredFlashModel = value;
+      i += skip;
+      continue;
+    }
+
+    if (flagName === "--flow-full-model") {
+      const [value, skip] = getValue();
+      if (value !== undefined) tieredFullModel = value;
+      i += skip;
+      continue;
+    }
+
     if (inlineValue !== undefined) {
       alwaysProxy.push(flagName, inlineValue);
       i++;
@@ -221,5 +245,10 @@ export function parseFlowCliArgs(argv) {
     fallbackThinking,
     fallbackTools,
     fallbackNoTools,
+    tieredModels: {
+      lite: tieredLiteModel,
+      flash: tieredFlashModel,
+      full: tieredFullModel,
+    },
   };
 }

package/runner-events.js

@@ -63,6 +63,29 @@ function getStreamingEstimate(result) {
   return result.__streamingEstimate;
 }
 
+/**
+ * Lazily initialize ctx baseline tracking properties on the result object.
+ * - __ctxBaseline: last known real totalTokens from message_end
+ * - __ctxStreamingChars: cumulative output chars since last baseline reset
+ */
+function getCtxBaseline(result) {
+  if (!Object.prototype.hasOwnProperty.call(result, "__ctxBaseline")) {
+    Object.defineProperty(result, "__ctxBaseline", {
+      value: 0,
+      enumerable: false,
+      configurable: false,
+      writable: true,
+    });
+    Object.defineProperty(result, "__ctxStreamingChars", {
+      value: 0,
+      enumerable: false,
+      configurable: false,
+      writable: true,
+    });
+  }
+  return result.__ctxBaseline;
+}
+
 /**
  * Track streaming characters and estimate output tokens.
  * Called on every streaming delta.
@@ -71,6 +94,9 @@ function updateStreamingEstimate(result, deltaLength) {
   if (deltaLength <= 0) return;
   const est = getStreamingEstimate(result);
   est.chars += deltaLength;
+  // Also accumulate chars for ctx estimation (not drained on emit)
+  getCtxBaseline(result);
+  result.__ctxStreamingChars += deltaLength;
 }
 
 /**
@@ -84,6 +110,18 @@ export function drainStreamingEstimate(result) {
   return tokens;
 }
 
+/**
+ * Return the estimated context tokens: last known real totalTokens (baseline)
+ * plus any additional output tokens estimated since that baseline was set.
+ * Returns 0 before the first message_end when no baseline exists yet,
+ * in which case the caller should fall back to the streaming output estimate.
+ */
+export function drainCtxEstimate(result) {
+  getCtxBaseline(result);
+  const streamingTokens = Math.floor(result.__ctxStreamingChars / CHARS_PER_TOKEN);
+  return result.__ctxBaseline + streamingTokens;
+}
+
 /**
  * Accumulate a text or thinking delta into the streaming buffer.
  * Returns true if the caller should emit an update.
@@ -151,6 +189,10 @@ function addFlowAssistantMessage(result, message) {
     result.usage.cacheWrite += usage.cacheWrite || 0;
     result.usage.cost += usage.cost?.total || 0;
     result.usage.contextTokens = usage.totalTokens || 0;
+
+    // Snapshot ctx baseline for smooth streaming estimation
+    result.__ctxBaseline = usage.totalTokens || 0;
+    result.__ctxStreamingChars = 0;
   }
 
   // Count tool call parts in the message content

package/types.ts

@@ -183,3 +183,41 @@ export function getLastAssistantText(messages: Message[]): string {
 	}
 	return "";
 }
+
+// ---------------------------------------------------------------------------
+// Post-flow hook types
+// ---------------------------------------------------------------------------
+
+/** Condition that determines when a hook fires. */
+export interface PostFlowHookTrigger {
+	/** Case-insensitive flow type names that trigger this hook. */
+	flowTypes: string[];
+	/** Only fire when all matching results succeeded. Default: true. */
+	onlyOnSuccess?: boolean;
+}
+
+/** Context passed to a hook's action function. */
+export interface PostFlowHookContext {
+	/** Flow results that matched the trigger. */
+	results: SingleResult[];
+	/** Original flow request params. */
+	params: Array<{ type: string; intent: string }>;
+}
+
+/** Result returned by a hook's action function. */
+export interface PostFlowHookResult {
+	/** Advisory text to inject. */
+	content: string;
+	/** Ordering key; lower runs first. Default: 0. */
+	priority?: number;
+}
+
+/** A post-flow hook that injects advisory messages into tool results. */
+export interface PostFlowHook {
+	/** Unique name for dedup and debugging. */
+	name: string;
+	/** When to fire this hook. */
+	trigger: PostFlowHookTrigger;
+	/** Returns advisory text, or null to skip. */
+	action: (ctx: PostFlowHookContext) => PostFlowHookResult | null;
+}