@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/src/extension/session-events.ts

@@ -0,0 +1,119 @@
+export type PublicAssistantMessageEvent =
+  | { type: "start"; partial: unknown }
+  | { type: "text_start"; contentIndex: number; partial: unknown }
+  | { type: "text_delta"; contentIndex: number; delta: string; partial: unknown }
+  | { type: "text_end"; contentIndex: number; content: string; partial: unknown }
+  | { type: "thinking_start"; contentIndex: number; partial: unknown }
+  | { type: "thinking_delta"; contentIndex: number; delta: string; partial: unknown }
+  | { type: "thinking_end"; contentIndex: number; content: string; partial: unknown }
+  | { type: "toolcall_start"; contentIndex: number; partial: unknown }
+  | { type: "toolcall_delta"; contentIndex: number; delta: string; partial: unknown }
+  | { type: "toolcall_end"; contentIndex: number; toolCall: unknown; partial: unknown }
+  | { type: "done"; reason: "stop" | "length" | "toolUse"; message: unknown }
+  | { type: "error"; reason: "aborted" | "error"; error: unknown };
+
+export type TurnStartEventLike = { turnIndex: number };
+export type TurnEndEventLike = { turnIndex: number; message: unknown };
+export type MessageStartEventLike = { message: unknown };
+export type MessageUpdateEventLike = {
+  message: unknown;
+  assistantMessageEvent: PublicAssistantMessageEvent;
+};
+export type MessageEndEventLike = { message: unknown };
+export type ToolExecutionStartEventLike = {
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+};
+export type ToolExecutionUpdateEventLike = { toolCallId: string };
+export type ToolExecutionEndEventLike = {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError: boolean;
+};
+
+export type NormalizedAssistantEvent =
+  | { type: "start" }
+  | { type: "text_start"; contentIndex: number }
+  | { type: "text_delta"; contentIndex: number; delta: string }
+  | { type: "text_end"; contentIndex: number; content: string }
+  | { type: "thinking_start"; contentIndex: number }
+  | { type: "thinking_delta"; contentIndex: number; delta: string }
+  | { type: "thinking_end"; contentIndex: number; content: string }
+  | { type: "toolcall_start"; contentIndex: number }
+  | { type: "toolcall_delta"; contentIndex: number; delta: string }
+  | { type: "toolcall_end"; contentIndex: number; toolCall: unknown }
+  | { type: "done"; reason: "stop" | "length" | "toolUse" }
+  | { type: "error"; reason: "aborted" | "error" };
+
+/** Remove cumulative snapshots while preserving every semantic stream event. */
+export function normalizeAssistantEvent(
+  event: PublicAssistantMessageEvent,
+): NormalizedAssistantEvent {
+  switch (event.type) {
+    case "start":
+      return { type: event.type };
+    case "text_start":
+    case "thinking_start":
+    case "toolcall_start":
+      return { type: event.type, contentIndex: event.contentIndex };
+    case "text_delta":
+    case "thinking_delta":
+    case "toolcall_delta":
+      return { type: event.type, contentIndex: event.contentIndex, delta: event.delta };
+    case "text_end":
+    case "thinking_end":
+      return { type: event.type, contentIndex: event.contentIndex, content: event.content };
+    case "toolcall_end":
+      return {
+        type: event.type,
+        contentIndex: event.contentIndex,
+        toolCall: event.toolCall,
+      };
+    case "done":
+      return { type: event.type, reason: event.reason };
+    case "error":
+      return { type: event.type, reason: event.reason };
+    default: {
+      const exhaustive: never = event;
+      return exhaustive;
+    }
+  }
+}
+
+export function messageRole(message: unknown): string {
+  if (typeof message !== "object" || message === null || !("role" in message)) {
+    return "unknown";
+  }
+  const role = (message as { role?: unknown }).role;
+  return typeof role === "string" && role.length > 0 ? role : "unknown";
+}
+
+export function toolCallIdFromAssistantEvent(event: NormalizedAssistantEvent): string | null {
+  if (event.type !== "toolcall_end" || typeof event.toolCall !== "object" || !event.toolCall) {
+    return null;
+  }
+  const id = (event.toolCall as { id?: unknown }).id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+
+export function toolStartedPayload(event: ToolExecutionStartEventLike): Record<string, unknown> {
+  return { toolName: event.toolName, args: event.args };
+}
+
+export function toolFinishedPayload(event: ToolExecutionEndEventLike): Record<string, unknown> {
+  return { toolName: event.toolName, isError: event.isError, result: event.result };
+}
+
+export function turnFinishedPayload(
+  event: TurnEndEventLike,
+  messageId: string | undefined,
+  toolCallIds: string[],
+): Record<string, unknown> {
+  return {
+    turnIndex: event.turnIndex,
+    ...(messageId === undefined ? {} : { messageId }),
+    toolCallIds,
+  };
+}

package/src/extension/widget.ts

@@ -113,16 +113,24 @@ export function buildWidgetLines(
 /** The graph row the window should center on: the active or waiting node. */
 function focusLine(graph: string[], state: WorkflowRunState): number {
   const active = graph.findIndex((line) => stripAnsi(line).includes("◐"));
-  if (active !== -1) {
-    return active;
+  const focus =
+    active !== -1
+      ? active
+      : state.waitingOn
+        ? graph.findIndex((line) => stripAnsi(line).includes(state.waitingOn as string))
+        : -1;
+  if (focus === -1) {
+    return graph.length - 1;
   }
-  if (state.waitingOn) {
-    const waiting = graph.findIndex((line) => stripAnsi(line).includes(state.waitingOn as string));
-    if (waiting !== -1) {
-      return waiting;
-    }
+  let top = focus;
+  while (top > 0 && !/[┌┏]/u.test(stripAnsi(graph[top] ?? ""))) {
+    top -= 1;
   }
-  return graph.length - 1;
+  let bottom = focus;
+  while (bottom + 1 < graph.length && !/[└┗]/u.test(stripAnsi(graph[bottom] ?? ""))) {
+    bottom += 1;
+  }
+  return Math.floor((top + bottom) / 2);
 }
 
 /**
@@ -139,24 +147,18 @@ function windowLines(
   if (lines.length <= budget) {
     return { lines, scroll: 0, maxScroll: 0 };
   }
-  // First pass decides which markers exist; the second re-fits within the
-  // remaining space. A marker flag can only turn on (never off) in the
-  // second pass, so the result stays within budget.
-  let inner = budget;
-  for (let pass = 0; pass < 2; pass += 1) {
-    const start = clampStart(anchor, inner, lines.length, anchorIsStart);
-    inner = budget - (start > 0 ? 1 : 0) - (start + inner < lines.length ? 1 : 0);
-  }
+  // Reserve one combined overflow row, leaving seven rows for a complete
+  // full card even when the widget also has an error footer.
+  const inner = Math.max(1, budget - 1);
   const start = clampStart(anchor, inner, lines.length, anchorIsStart);
   const end = start + inner;
-  const out: string[] = [];
-  if (start > 0) {
-    out.push(ansi.dim(`↑ ${start} more`));
-  }
-  out.push(...lines.slice(start, end));
-  if (end < lines.length) {
-    out.push(ansi.dim(`↓ ${lines.length - end} more · shift+↑/↓ scroll`));
-  }
+  const above = start;
+  const below = Math.max(0, lines.length - end);
+  const out = lines.slice(start, end);
+  const directions = [above > 0 ? `↑ ${above}` : "", below > 0 ? `↓ ${below}` : ""]
+    .filter(Boolean)
+    .join(" · ");
+  out.push(ansi.dim(`${directions} more · shift+↑/↓ scroll`));
   return { lines: out, scroll: start, maxScroll: Math.max(0, lines.length - inner) };
 }
 

package/src/extension/workflow-tool.ts

@@ -0,0 +1,59 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type TSchema } from "typebox";
+
+const noExtraProperties = { additionalProperties: false } as const;
+
+export const WorkflowToolParameters: TSchema = Type.Union([
+  Type.Object(
+    {
+      action: StringEnum(["list"] as const),
+      offset: Type.Optional(Type.Integer({ minimum: 0, description: "Workflow list offset" })),
+    },
+    noExtraProperties,
+  ),
+  Type.Object(
+    {
+      action: StringEnum(["start"] as const),
+      workflow: Type.String({ description: "Discovered workflow name or workflow file path" }),
+      input: Type.Optional(Type.Unknown({ description: "Structured workflow input" })),
+    },
+    noExtraProperties,
+  ),
+  Type.Object(
+    {
+      action: StringEnum(["status"] as const),
+      runId: Type.Optional(Type.String({ description: "Run id; omit for the active run" })),
+    },
+    noExtraProperties,
+  ),
+  Type.Object({ action: StringEnum(["pause"] as const) }, noExtraProperties),
+  Type.Object({ action: StringEnum(["resume"] as const) }, noExtraProperties),
+  Type.Object({ action: StringEnum(["cancel"] as const) }, noExtraProperties),
+  Type.Object(
+    {
+      action: StringEnum(["answer"] as const),
+      input: Type.Unknown({ description: "Checkpoint answer" }),
+      runId: Type.Optional(Type.String({ description: "Waiting run id" })),
+    },
+    noExtraProperties,
+  ),
+  Type.Object(
+    {
+      action: StringEnum(["submit"] as const),
+      step: Type.String({ description: "Step id from the workflow step contract" }),
+      attempt: Type.String({ description: "Attempt id from the workflow step contract" }),
+      output: Type.Unknown({ description: "Step output matching the expected shape" }),
+    },
+    noExtraProperties,
+  ),
+]);
+
+export type WorkflowToolInput =
+  | { action: "list"; offset?: number }
+  | { action: "start"; workflow: string; input?: unknown }
+  | { action: "status"; runId?: string }
+  | { action: "pause" }
+  | { action: "resume" }
+  | { action: "cancel" }
+  | { action: "answer"; input: unknown; runId?: string }
+  | { action: "submit"; step: string; attempt: string; output: unknown };

package/src/host/processes.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Tracks headless child processes (spawned `pi --mode rpc` sessions) so a
+ * killed host never leaves orphans working. Children spawn in their own
+ * process group; the registry file lets a later host reap leftovers by
+ * killing the whole group. The file lives next to the project store and is
+ * only ever touched by one host at a time (the advisory lock ensures it).
+ */
+export class HostProcessRegistry {
+  private readonly filePath: string;
+  private readonly pids = new Set<number>();
+
+  constructor(storeDir: string) {
+    this.filePath = path.join(storeDir, "host.children.json");
+  }
+
+  register(pid: number): void {
+    this.pids.add(pid);
+    this.persist();
+  }
+
+  unregister(pid: number): void {
+    this.pids.delete(pid);
+    this.persist();
+  }
+
+  get size(): number {
+    return this.pids.size;
+  }
+
+  /** Kill every registered child's process group, escalating to SIGKILL. */
+  killAll(): void {
+    for (const pid of this.pids) {
+      killProcessGroup(pid, "SIGTERM");
+    }
+    for (const pid of this.pids) {
+      killProcessGroup(pid, "SIGKILL");
+    }
+    this.pids.clear();
+    this.persist();
+  }
+
+  /**
+   * Reap children recorded by a previous host that died without cleanup.
+   * Called once at host start, before the lock is taken.
+   */
+  reapOrphans(): number[] {
+    const recorded = this.readFile();
+    const reaped: number[] = [];
+    const stillAlive: number[] = [];
+    for (const pid of recorded) {
+      if (isAlive(pid)) {
+        killProcessGroup(pid, "SIGKILL");
+        reaped.push(pid);
+        if (isAlive(pid)) {
+          // A group kill that left the leader alive stays registered so a
+          // later start tries again instead of forgetting it.
+          stillAlive.push(pid);
+        }
+      }
+    }
+    this.pids.clear();
+    for (const pid of stillAlive) {
+      this.pids.add(pid);
+    }
+    this.persist();
+    return reaped;
+  }
+
+  private readFile(): number[] {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf8")) as unknown;
+      if (!Array.isArray(parsed)) {
+        return [];
+      }
+      return parsed.filter((pid): pid is number => Number.isSafeInteger(pid) && pid > 0);
+    } catch {
+      return [];
+    }
+  }
+
+  private persist(): void {
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+      // Write exactly the live set. Unioning with the previous file would
+      // resurrect exited pids, and a later host reaping them could kill an
+      // unrelated process group that reused one.
+      fs.writeFileSync(this.filePath, `${JSON.stringify([...this.pids])}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+    } catch {
+      // Registry bookkeeping is best-effort; orphan reaping is the backstop.
+    }
+  }
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function killProcessGroup(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // Already gone.
+    }
+  }
+}

package/src/host/rpc-bridge.ts

@@ -0,0 +1,44 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const RPC_SUBMISSION_PREFIX = "PI_WORKFLOWS_STEP_SUBMISSION ";
+
+/**
+ * Loaded into headless `pi --mode rpc` children spawned by the standalone
+ * host. The child has no workflow engine, so this bridge only registers the
+ * `workflow` tool and reports every submission to the host over stderr; the
+ * host validates against the engine and re-prompts on rejection.
+ */
+export default function piWorkflowsRpcBridge(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "workflow",
+    label: "Workflow",
+    description: [
+      "Submit the output for the pending workflow step with action submit.",
+      "Only call this tool when a workflow step contract in the conversation asks you to.",
+      "Pass the exact step id from the contract and your result as the output.",
+    ].join(" "),
+    parameters: Type.Object(
+      {
+        action: StringEnum(["submit"] as const),
+        step: Type.String({ description: "Step id from the workflow step contract" }),
+        attempt: Type.String({ description: "Attempt id from the workflow step contract" }),
+        output: Type.Unknown({ description: "Step output matching the expected shape" }),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_toolCallId, params) {
+      process.stderr.write(`${RPC_SUBMISSION_PREFIX}${JSON.stringify(params)}\n`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Submission recorded. Continue only when the workflow sends the next step.",
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}