pi-agent-flow 0.1.0-alpha.1

package/runner-events.js

@@ -0,0 +1,156 @@
+/**
+ * Helpers for parsing Pi JSON mode events and summarizing flow results.
+ */
+
+function getSeenFlowMessageSignatures(result) {
+  if (!Object.prototype.hasOwnProperty.call(result, "__seenMessageSignatures")) {
+    Object.defineProperty(result, "__seenMessageSignatures", {
+      value: new Set(),
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+  return result.__seenMessageSignatures;
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries
+    .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`)
+    .join(",")}}`;
+}
+
+function getMessageSignature(message) {
+  return stableStringify(message);
+}
+
+function updateAssistantMetadata(result, message) {
+  if (!message || message.role !== "assistant") return;
+  if (!result.model && message.model) result.model = message.model;
+  if (message.stopReason) result.stopReason = message.stopReason;
+  if (message.errorMessage) result.errorMessage = message.errorMessage;
+}
+
+function addFlowAssistantMessage(result, message) {
+  if (!message || message.role !== "assistant") return false;
+
+  updateAssistantMetadata(result, message);
+
+  const signature = getMessageSignature(message);
+  const seen = getSeenFlowMessageSignatures(result);
+  if (seen.has(signature)) return false;
+  seen.add(signature);
+
+  result.messages.push(message);
+
+  result.usage.turns++;
+  const usage = message.usage;
+  if (usage) {
+    result.usage.input += usage.input || 0;
+    result.usage.output += usage.output || 0;
+    result.usage.cacheRead += usage.cacheRead || 0;
+    result.usage.cacheWrite += usage.cacheWrite || 0;
+    result.usage.cost += usage.cost?.total || 0;
+    result.usage.contextTokens = usage.totalTokens || 0;
+  }
+
+  // Count tool call parts in the message content
+  if (Array.isArray(message.content)) {
+    for (const part of message.content) {
+      if (part.type === "toolCall") {
+        result.usage.toolCalls++;
+      }
+    }
+  }
+
+  return true;
+}
+
+function addFlowAssistantMessages(result, messages) {
+  if (!Array.isArray(messages)) return false;
+  let changed = false;
+  for (const message of messages) {
+    if (addFlowAssistantMessage(result, message)) changed = true;
+  }
+  return changed;
+}
+
+export function processFlowEvent(event, result) {
+  if (!event || typeof event !== "object") return false;
+
+  switch (event.type) {
+    case "message_end":
+      return addFlowAssistantMessage(result, event.message);
+
+    case "turn_end":
+      return addFlowAssistantMessage(result, event.message);
+
+    case "agent_end":
+      result.sawAgentEnd = true;
+      return addFlowAssistantMessages(result, event.messages);
+
+    default:
+      return false;
+  }
+}
+
+export function processFlowJsonLine(line, result) {
+  if (!line.trim()) return false;
+
+  let event;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    return false;
+  }
+
+  return processFlowEvent(event, result);
+}
+
+export function getFlowFinalText(messages) {
+  if (!Array.isArray(messages)) return "";
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (!message || message.role !== "assistant" || !Array.isArray(message.content)) {
+      continue;
+    }
+
+    for (const part of message.content) {
+      if (part?.type === "text" && typeof part.text === "string" && part.text.length > 0) {
+        return part.text;
+      }
+    }
+  }
+
+  return "";
+}
+
+export function getFlowSummaryText(result) {
+  const finalText = getFlowFinalText(result?.messages);
+  if (finalText) return finalText;
+
+  if (typeof result?.errorMessage === "string" && result.errorMessage.trim()) {
+    return result.errorMessage.trim();
+  }
+
+  const isError =
+    (typeof result?.exitCode === "number" && result.exitCode > 0) ||
+    result?.stopReason === "error" ||
+    result?.stopReason === "aborted";
+
+  if (isError && typeof result?.stderr === "string" && result.stderr.trim()) {
+    return result.stderr.trim();
+  }
+
+  return "(no output)";
+}

package/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared type definitions for the flow-state delegation extension.
+ */
+
+import type { Message } from "@mariozechner/pi-ai";
+import { getFlowFinalText } from "./runner-events.js";
+
+/** Aggregated token usage from a flow run. */
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+	toolCalls: number;
+}
+
+/** Result of a single flow invocation. */
+export interface SingleResult {
+	type: string;
+	agentSource: "user" | "project" | "unknown";
+	intent: string;
+	exitCode: number;
+	messages: Message[];
+	stderr: string;
+	usage: UsageStats;
+	model?: string;
+	stopReason?: string;
+	errorMessage?: string;
+	sawAgentEnd?: boolean;
+}
+
+/** Metadata attached to every tool result for rendering. */
+export interface FlowDetails {
+	mode: "flow";
+	delegationMode: "fork";
+	projectAgentsDir: string | null;
+	results: SingleResult[];
+}
+
+/** A display-friendly representation of a message part. */
+export type DisplayItem =
+	| { type: "text"; text: string }
+	| { type: "toolCall"; name: string; args: Record<string, unknown> };
+
+/** Create an empty UsageStats object. */
+export function emptyFlowUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0, toolCalls: 0 };
+}
+
+/** Sum usage across multiple results. */
+export function aggregateFlowUsage(results: SingleResult[]): UsageStats {
+	const total = emptyFlowUsage();
+	for (const r of results) {
+		total.input += r.usage.input;
+		total.output += r.usage.output;
+		total.cacheRead += r.usage.cacheRead;
+		total.cacheWrite += r.usage.cacheWrite;
+		total.cost += r.usage.cost;
+		total.turns += r.usage.turns;
+		total.toolCalls += r.usage.toolCalls;
+	}
+	return total;
+}
+
+/** Whether the child emitted a final assistant text response. */
+export function hasFlowOutput(r: Pick<SingleResult, "messages">): boolean {
+	return getFlowFinalText(r.messages).trim().length > 0;
+}
+
+/** Whether the child semantically completed the run. */
+export function isFlowComplete(r: Pick<SingleResult, "messages" | "sawAgentEnd">): boolean {
+	return Boolean(r.sawAgentEnd) && hasFlowOutput(r);
+}
+
+/** Whether a result should be treated as successful by the wrapper/UI. */
+export function isFlowSuccess(r: SingleResult): boolean {
+	if (r.exitCode === -1) return false;
+	if (isFlowComplete(r)) return true;
+	return r.exitCode === 0 && r.stopReason !== "error" && r.stopReason !== "aborted";
+}
+
+/** Whether a result represents an error. */
+export function isFlowError(r: SingleResult): boolean {
+	if (r.exitCode === -1) return false;
+	return !isFlowSuccess(r);
+}
+
+/** Reconcile process exit status with semantic completion observed from Pi's event stream. */
+export function normalizeFlowResult(result: SingleResult, wasAborted: boolean): SingleResult {
+	const hasSemanticSuccess = isFlowComplete(result);
+
+	if (wasAborted) {
+		if (hasSemanticSuccess) {
+			result.exitCode = 0;
+			if (result.stopReason === "aborted") result.stopReason = undefined;
+			if (result.errorMessage === "Flow was aborted.") {
+				result.errorMessage = undefined;
+			}
+		} else {
+			result.exitCode = 130;
+			result.stopReason = "aborted";
+			result.errorMessage = "Flow was aborted.";
+			if (!result.stderr.trim()) result.stderr = "Flow was aborted.";
+		}
+		return result;
+	}
+
+	if (result.exitCode > 0) {
+		if (hasSemanticSuccess) {
+			result.exitCode = 0;
+			if (result.stopReason === "error") result.stopReason = undefined;
+			if (result.errorMessage === result.stderr.trim()) {
+				result.errorMessage = undefined;
+			}
+		} else {
+			if (!result.stopReason) result.stopReason = "error";
+			if (!result.errorMessage && result.stderr.trim()) {
+				result.errorMessage = result.stderr.trim();
+			}
+		}
+	}
+
+	return result;
+}
+
+/** Extract the last assistant text from a message history. */
+export function getFlowOutput(messages: Message[]): string {
+	return getFlowFinalText(messages);
+}
+
+/** Extract all display-worthy items from a message history. */
+export function getFlowDisplayItems(messages: Message[]): DisplayItem[] {
+	const items: DisplayItem[] = [];
+	for (const msg of messages) {
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text") {
+					items.push({ type: "text", text: part.text });
+				} else if (part.type === "toolCall") {
+					items.push({ type: "toolCall", name: part.name, args: part.arguments });
+				}
+			}
+		}
+	}
+	return items;
+}