@osolmaz/pi-workflows 0.1.0

package/examples/workflows/elegant-solution.workflow.ts

@@ -0,0 +1,95 @@
+import { agent, checkpoint, decision, decisionEdge, defineWorkflow } from "@osolmaz/pi-workflows";
+
+const sameChoices = ["y", "n"] as const;
+
+/**
+ * Trigger this mid-conversation with /workflow elegant-solution once a
+ * problem has been discussed. It makes the model commit to the most elegant
+ * long-term production-ready solution, articulate the holy grail, and check
+ * whether the two match before implementing.
+ */
+export default defineWorkflow({
+  name: "elegant-solution",
+  title: "Elegant production-ready solution",
+  presentationPrompt: ({ state }) =>
+    state.status === "waiting"
+      ? [
+          "Explain the elegant proposal, the holy grail, the important gap, and the pragmatic path in plain language.",
+          "End by asking the user whether to implement the pragmatic path.",
+          `Proposal: ${JSON.stringify(state.outputs.propose)}`,
+          `Holy grail: ${JSON.stringify(state.outputs.holy_grail)}`,
+        ].join("\n")
+      : "Summarize what was implemented, what was tested, and what still needs verification.",
+  startAt: "propose",
+  nodes: {
+    propose: agent({
+      prompt: () =>
+        [
+          "Consider the problem discussed so far in this conversation.",
+          "What is the most elegant and long-term production-ready solution?",
+          "Think it through and commit to one concrete proposal.",
+        ].join("\n"),
+      expectedOutput: `{ "solution": "the proposed solution", "rationale": "why it is the most elegant long-term choice" }`,
+    }),
+    holy_grail: agent({
+      prompt: () =>
+        [
+          "Now set your previous proposal aside for a moment.",
+          "What is the holy grail for this problem?",
+          "Describe the ideal end state with no constraints on effort.",
+        ].join("\n"),
+      expectedOutput: `{ "holyGrail": "the ideal end state" }`,
+    }),
+    compare: decision({
+      choices: sameChoices,
+      question: ({ outputs }) =>
+        [
+          "Is the holy grail the same as what you proposed? Answer y or n.",
+          "",
+          `Proposal: ${JSON.stringify(outputs.propose)}`,
+          `Holy grail: ${JSON.stringify(outputs.holy_grail)}`,
+        ].join("\n"),
+    }),
+    implement: agent({
+      timeoutMs: 60 * 60_000,
+      statusDetail: "implementing",
+      prompt: ({ outputs }) =>
+        [
+          "The proposal matches the holy grail, so implement it now.",
+          "Implement the most elegant and long-term production-ready solution end-to-end.",
+          "Test as much as possible without destructive actions, and state what could not be verified locally.",
+          "",
+          `Proposal: ${JSON.stringify(outputs.propose)}`,
+        ].join("\n"),
+      expectedOutput: `{ "implemented": true, "summary": "what was built", "tested": "what was verified", "untested": "what still needs verification" }`,
+    }),
+    reconcile: agent({
+      prompt: ({ outputs }) =>
+        [
+          "The proposal and the holy grail differ.",
+          "Explain the gap and propose the pragmatic path: what to build now and how it evolves toward the holy grail.",
+          "",
+          `Proposal: ${JSON.stringify(outputs.propose)}`,
+          `Holy grail: ${JSON.stringify(outputs.holy_grail)}`,
+        ].join("\n"),
+      expectedOutput: `{ "gap": "how they differ", "path": "what to build now and how it evolves" }`,
+    }),
+    review: checkpoint({
+      summary: "human decides between proposal and holy grail path",
+      run: ({ outputs }) => outputs.reconcile,
+    }),
+  },
+  edges: [
+    { from: "propose", to: "holy_grail" },
+    { from: "holy_grail", to: "compare" },
+    decisionEdge({
+      from: "compare",
+      choices: sameChoices,
+      cases: {
+        y: "implement",
+        n: "reconcile",
+      },
+    }),
+    { from: "reconcile", to: "review" },
+  ],
+});

package/examples/workflows/shell.workflow.ts

@@ -0,0 +1,31 @@
+import { compute, defineWorkflow, shell } from "@osolmaz/pi-workflows";
+
+type ShellInput = {
+  text?: string;
+};
+
+/** One runtime-owned shell action returning structured JSON, no agent step. */
+export default defineWorkflow({
+  name: "shell",
+  startAt: "echo_text",
+  nodes: {
+    echo_text: shell({
+      exec: ({ input }) => ({
+        command: "printf",
+        args: ["%s", (input as ShellInput).text ?? "hello from pi-workflows"],
+        timeoutMs: 10_000,
+      }),
+      parse: (result) => ({
+        stdout: result.stdout,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+      }),
+    }),
+    finalize: compute({
+      run: ({ outputs }) => ({
+        echoed: (outputs.echo_text as { stdout: string }).stdout,
+      }),
+    }),
+  },
+  edges: [{ from: "echo_text", to: "finalize" }],
+});

package/examples/workflows/two-turn.workflow.ts

@@ -0,0 +1,64 @@
+import { agent, compute, defineWorkflow } from "@osolmaz/pi-workflows";
+
+type TwoTurnInput = {
+  topic?: string;
+};
+
+/**
+ * Multi-step agent work in the same pi conversation. Each step builds on the
+ * previous step's accepted output, and the model keeps its full session
+ * context (files it read, tools it ran) across steps.
+ */
+export default defineWorkflow({
+  name: "two-turn",
+  presentationPrompt:
+    "Present the final validation checklist clearly, including its concrete file references.",
+  startAt: "inspect",
+  nodes: {
+    inspect: agent({
+      prompt: ({ input }) => {
+        const topic =
+          (input as TwoTurnInput).topic ??
+          "How should we validate a new extension before shipping it?";
+        return [
+          "Inspect the current workspace before answering.",
+          "Read at least two files relevant to the topic (for example the package manifest and a source file).",
+          "",
+          `Topic: ${topic}`,
+        ].join("\n");
+      },
+      expectedOutput: `{ "findings": ["short finding", "short finding"], "repoSummary": "short paragraph" }`,
+    }),
+    draft: agent({
+      prompt: ({ outputs }) =>
+        [
+          "Build on your earlier inspection in this same conversation.",
+          "Write a short draft answer about the topic.",
+          "",
+          `Inspection: ${JSON.stringify(outputs.inspect)}`,
+        ].join("\n"),
+      expectedOutput: `{ "draft": "short paragraph" }`,
+    }),
+    checklist: agent({
+      prompt: ({ outputs }) =>
+        [
+          "Turn the draft into a concise validation checklist with concrete references.",
+          "",
+          `Draft: ${JSON.stringify(outputs.draft)}`,
+        ].join("\n"),
+      expectedOutput: `{ "checklist": ["item", "item"], "references": ["path", "path"] }`,
+    }),
+    finalize: compute({
+      run: ({ outputs }) => ({
+        inspection: outputs.inspect,
+        draft: outputs.draft,
+        checklist: outputs.checklist,
+      }),
+    }),
+  },
+  edges: [
+    { from: "inspect", to: "draft" },
+    { from: "draft", to: "checklist" },
+    { from: "checklist", to: "finalize" },
+  ],
+});

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@osolmaz/pi-workflows",
+  "version": "0.1.0",
+  "description": "Workflow engine, JSON control-flow tool, and live terminal viewer for the pi coding agent",
+  "keywords": [
+    "pi-package"
+  ],
+  "homepage": "https://github.com/osolmaz/pi-workflows#readme",
+  "bugs": {
+    "url": "https://github.com/osolmaz/pi-workflows/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osolmaz/pi-workflows.git"
+  },
+  "bin": {
+    "pi-workflows": "dist/viewer/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/workflows/index.d.ts",
+      "default": "./dist/workflows/index.js"
+    },
+    "./extension": {
+      "types": "./dist/extension/index.d.ts",
+      "default": "./dist/extension/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm run build && npm run test:coverage",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint --deny-warnings src test examples",
+    "prepare": "node scripts/prepare.mjs",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "jiti": "^2.7.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-istanbul": "^4.1.10",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "tsx": "^4.23.1",
+    "typebox": "^1.3.6",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ]
+  }
+}

package/src/extension/executor.ts

@@ -0,0 +1,251 @@
+import type {
+  AgentStepExecutor,
+  AgentStepRequest,
+  AgentStepSubmission,
+} from "../workflows/types.js";
+
+export type SubmissionResult =
+  | { accepted: true; message: string }
+  | { accepted: false; message: string };
+
+export type PromptDelivery = {
+  prompt: string;
+  /** True when the agent is known to be mid-run, so delivery must be queued. */
+  streaming: boolean;
+};
+
+export type ConversationStepExecutorOptions = {
+  /** Deliver a prompt into the pi conversation. */
+  sendPrompt: (delivery: PromptDelivery) => void;
+  /** Reminders sent when the agent settles without submitting. Default 2. */
+  maxNudges?: number;
+};
+
+type PendingStep = {
+  request: AgentStepRequest;
+  resolve: (submission: AgentStepSubmission) => void;
+  reject: (error: unknown) => void;
+  nudgesSent: number;
+  cleanup: () => void;
+  /** Resolves when this step stops being the pending step. */
+  cleared: Promise<void>;
+  markCleared: () => void;
+};
+
+const DEFAULT_MAX_NUDGES = 2;
+
+/**
+ * AgentStepExecutor that runs steps inside the current pi conversation. The
+ * engine hands it a prompt; it delivers the prompt as a user message and
+ * resolves once the model submits an accepted output through the `workflow`
+ * tool. If the agent settles without submitting, it nudges the model a
+ * bounded number of times before failing the step.
+ */
+export class ConversationStepExecutor implements AgentStepExecutor {
+  private readonly sendPrompt: (delivery: PromptDelivery) => void;
+  private readonly maxNudges: number;
+  private pending: PendingStep | null = null;
+  private streaming = false;
+  private heldByUser = false;
+
+  constructor(options: ConversationStepExecutorOptions) {
+    this.sendPrompt = options.sendPrompt;
+    this.maxNudges = options.maxNudges ?? DEFAULT_MAX_NUDGES;
+  }
+
+  /** Track agent streaming state (wire to agent_start / agent_settled). */
+  setStreaming(streaming: boolean): void {
+    this.streaming = streaming;
+  }
+
+  get pendingStepId(): string | null {
+    return this.pending?.request.contract.nodeId ?? null;
+  }
+
+  /**
+   * Hold the pending step for the user: no nudges are sent while held, so an
+   * escape-interrupted conversation stays quiet until the user resumes.
+   */
+  hold(): void {
+    this.heldByUser = true;
+  }
+
+  get held(): boolean {
+    return this.heldByUser;
+  }
+
+  /**
+   * Release a user hold. When a step is still pending, its prompt is
+   * re-delivered so the model picks the step back up.
+   */
+  release(): void {
+    if (!this.heldByUser) {
+      return;
+    }
+    this.heldByUser = false;
+    const pending = this.pending;
+    if (!pending) {
+      return;
+    }
+    try {
+      this.sendPrompt({ prompt: pending.request.prompt, streaming: this.streaming });
+    } catch (error) {
+      this.clearPending();
+      pending.reject(error);
+    }
+  }
+
+  async runAgentStep(request: AgentStepRequest, signal: AbortSignal): Promise<AgentStepSubmission> {
+    if (this.pending) {
+      throw new Error("Another workflow step is already awaiting output");
+    }
+    return await new Promise<AgentStepSubmission>((resolve, reject) => {
+      const onAbort = () => {
+        const reason: unknown = signal.reason ?? new Error("Workflow step aborted");
+        this.clearPending();
+        reject(reason);
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      let markCleared!: () => void;
+      const cleared = new Promise<void>((resolveCleared) => {
+        markCleared = resolveCleared;
+      });
+      this.pending = {
+        request,
+        resolve,
+        reject,
+        nudgesSent: 0,
+        cleanup: () => signal.removeEventListener("abort", onAbort),
+        cleared,
+        markCleared,
+      };
+      if (signal.aborted) {
+        onAbort();
+        return;
+      }
+      try {
+        this.sendPrompt({ prompt: request.prompt, streaming: this.streaming });
+      } catch (error) {
+        // A failed delivery must not leave the step installed, or every
+        // subsequent agent node would fail with "already awaiting output".
+        this.clearPending();
+        reject(error);
+      }
+    });
+  }
+
+  /** Called by the `workflow` tool when the model submits a step output. */
+  async submit(stepId: string, attemptId: string, output: unknown): Promise<SubmissionResult> {
+    const pending = this.pending;
+    if (!pending) {
+      return {
+        accepted: false,
+        message:
+          "No workflow step is awaiting output. Do not call the workflow tool outside an active workflow step.",
+      };
+    }
+    const expected = pending.request.contract.nodeId;
+    if (stepId !== expected) {
+      return {
+        accepted: false,
+        message: `Wrong step id ${JSON.stringify(stepId)}; the pending step is ${JSON.stringify(expected)}.`,
+      };
+    }
+    // Loops revisit the same node id, so a delayed duplicate submission from
+    // an earlier attempt would otherwise be accepted as this attempt's output.
+    const expectedAttempt = pending.request.contract.attemptId;
+    if (attemptId !== expectedAttempt) {
+      return {
+        accepted: false,
+        message: `Stale attempt id ${JSON.stringify(attemptId)} for step ${JSON.stringify(
+          stepId,
+        )}; the pending attempt is ${JSON.stringify(expectedAttempt)}. Use the attempt id from the latest step contract.`,
+      };
+    }
+    // Race validation against the step being cleared: a hung `validate`
+    // callback must not leave this tool call (and therefore pi) blocked after
+    // a timeout or cancel already resolved the run.
+    const result = await Promise.race([
+      pending.request.accept(output),
+      pending.cleared.then(() => null),
+    ]);
+    // The step may have timed out or been cancelled (and a newer step
+    // installed) while validation was awaited; a stale submission must not
+    // clear or resolve the newer pending step.
+    if (result === null || this.pending !== pending) {
+      return {
+        accepted: false,
+        message: `Step ${JSON.stringify(stepId)} is no longer awaiting output.`,
+      };
+    }
+    if (!result.ok) {
+      return {
+        accepted: false,
+        message: `Output rejected for step ${JSON.stringify(stepId)}: ${result.error}`,
+      };
+    }
+    this.clearPending();
+    pending.resolve({ output: result.value });
+    return {
+      accepted: true,
+      message: [
+        `Output accepted for step ${JSON.stringify(stepId)}.`,
+        "If the workflow continues, the next step arrives as a new user message. End your turn now.",
+      ].join(" "),
+    };
+  }
+
+  /**
+   * Called when the agent settles. Returns true when a nudge was sent, false
+   * when there was nothing to do. Fails the pending step once the nudge
+   * budget is exhausted.
+   */
+  handleAgentSettled(): boolean {
+    const pending = this.pending;
+    if (!pending) {
+      return false;
+    }
+    if (this.heldByUser) {
+      // The user interrupted deliberately; reminding the model now would
+      // steal the conversation back. The step waits for an explicit resume.
+      return false;
+    }
+    if (pending.nudgesSent >= this.maxNudges) {
+      this.clearPending();
+      pending.reject(
+        new Error(
+          `Agent settled ${pending.nudgesSent + 1} times without submitting step ${JSON.stringify(
+            pending.request.contract.nodeId,
+          )} via the workflow tool`,
+        ),
+      );
+      return false;
+    }
+    pending.nudgesSent += 1;
+    const { nodeId, attemptId } = pending.request.contract;
+    try {
+      this.sendPrompt({
+        prompt: [
+          `Reminder: workflow step ${JSON.stringify(nodeId)} is still awaiting your output.`,
+          "Complete it by calling the `workflow` tool with:",
+          `{"step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "output": <your result>}`,
+          `Expected output: ${pending.request.contract.expectedOutput ?? "a JSON object with your result"}`,
+        ].join("\n"),
+        streaming: this.streaming,
+      });
+    } catch (error) {
+      // No reminder turn was started, so nothing would settle the step; fail
+      // it promptly instead of waiting out the node timeout.
+      this.clearPending();
+      pending.reject(error);
+      return false;
+    }
+    return true;
+  }
+
+  private clearPending(): void {
+    this.pending?.cleanup();
+    this.pending?.markCleared();
+    this.pending = null;
+  }
+}