@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/examples/workflows/autoimplement.workflow.ts

@@ -1,92 +1 @@
-import { agent, compute, decision, decisionEdge, defineWorkflow } from "@osolmaz/pi-workflows";
-
-type AutoimplementInput = {
-  task?: string;
-};
-
-const reviewChoices = ["clean", "issues_found"] as const;
-
-/**
- * Implement, verify, then loop a self-review until it comes back clean. The
- * decision edge routes `issues_found` back to the fix step, and the engine's
- * maxSteps guard bounds the loop.
- */
-export default defineWorkflow({
-  name: "autoimplement",
-  title: ({ input }) => {
-    const task = (input as AutoimplementInput).task;
-    return task ? `autoimplement: ${task.slice(0, 60)}` : undefined;
-  },
-  presentationPrompt:
-    "Summarize what was implemented, what verification passed, and any remaining limitation. Be concise and direct.",
-  maxSteps: 20,
-  startAt: "implement",
-  nodes: {
-    implement: agent({
-      timeoutMs: 60 * 60_000,
-      statusDetail: "implementing",
-      prompt: ({ input }) => {
-        const task =
-          (input as AutoimplementInput).task ?? "the plan discussed so far in this conversation";
-        return [
-          `Implement ${task} end-to-end.`,
-          "Aim for the most elegant, long-term production-ready solution without gold-plating.",
-        ].join("\n");
-      },
-      expectedOutput: `{ "summary": "what was implemented", "files": ["changed file", "changed file"] }`,
-    }),
-    verify: agent({
-      timeoutMs: 30 * 60_000,
-      statusDetail: "verifying",
-      prompt: () =>
-        [
-          "Verify the implementation.",
-          "Run the test suite plus any relevant builds, linters, or local smoke tests.",
-          "Do not run destructive commands.",
-        ].join("\n"),
-      expectedOutput: `{ "passed": true | false, "details": "what was run and what happened" }`,
-    }),
-    review: decision({
-      choices: reviewChoices,
-      question: ({ outputs }) =>
-        [
-          "Critically review your implementation as a strict reviewer.",
-          "Look for correctness bugs, missed requirements, and failing checks.",
-          "Pick `issues_found` if anything must be fixed, otherwise `clean`.",
-          "",
-          `Verification: ${JSON.stringify(outputs.verify)}`,
-        ].join("\n"),
-    }),
-    fix: agent({
-      timeoutMs: 30 * 60_000,
-      statusDetail: "fixing",
-      prompt: ({ outputs }) =>
-        [
-          "Fix the issues you found in review, then stop.",
-          "",
-          `Review: ${JSON.stringify(outputs.review)}`,
-        ].join("\n"),
-      expectedOutput: `{ "fixed": "what was changed" }`,
-    }),
-    finalize: compute({
-      run: ({ outputs }) => ({
-        implementation: outputs.implement,
-        verification: outputs.verify,
-        review: outputs.review,
-      }),
-    }),
-  },
-  edges: [
-    { from: "implement", to: "verify" },
-    { from: "verify", to: "review" },
-    decisionEdge({
-      from: "review",
-      choices: reviewChoices,
-      cases: {
-        clean: "finalize",
-        issues_found: "fix",
-      },
-    }),
-    { from: "fix", to: "verify" },
-  ],
-});
+export { autoimplementWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/examples/workflows/autoplan.workflow.ts

@@ -0,0 +1 @@
+export { autoplanWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/examples/workflows/human-decision.workflow.ts

@@ -0,0 +1,62 @@
+import {
+  choice,
+  compute,
+  defineHumanChoices,
+  defineWorkflow,
+  humanDecision,
+  humanDecisionEdge,
+  textInput,
+} from "@osolmaz/pi-workflows";
+
+const choices = defineHumanChoices({
+  continue: choice({ label: "Yes, continue" }),
+  stop: choice({ label: "No, stop" }),
+  replan: choice({
+    label: "Replan",
+    input: textInput({ name: "instructions", prompt: "What should change?" }),
+  }),
+});
+
+export default defineWorkflow({
+  name: "human-decision-example",
+  startAt: "proposal",
+  nodes: {
+    proposal: compute({
+      run: ({ input }) => ({
+        summary: "Apply the proposed workflow change.",
+        changes: ["Keep the durable subject.", "Show readable decision text."],
+        source: input,
+      }),
+    }),
+    approve: humanDecision({
+      audience: "operator",
+      choices,
+      request: ({ outputs }) => {
+        const proposal = outputs.proposal as { summary: string; changes: string[] };
+        return {
+          title: "Approve the proposal",
+          subject: proposal,
+          presentation: {
+            schema: "pi-workflows.decision-presentation.v1",
+            summary: proposal.summary,
+            blocks: [
+              { kind: "section", title: "Changes" },
+              { kind: "bullets", items: proposal.changes },
+            ],
+          },
+        };
+      },
+    }),
+    continued: compute({ run: ({ outputs }) => ({ status: "continue", answer: outputs.approve }) }),
+    stopped: compute({ run: ({ outputs }) => ({ status: "stop", answer: outputs.approve }) }),
+    replan: compute({ run: ({ outputs }) => ({ status: "replan", answer: outputs.approve }) }),
+  },
+  edges: [
+    { from: "proposal", to: "approve" },
+    humanDecisionEdge({
+      from: "approve",
+      choices,
+      cases: { continue: "continued", stop: "stopped", replan: "replan" },
+    }),
+  ],
+});

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "Pi Workflows"
-version = "0.9.1"
+version = "0.11.0"
 min_herdr_version = "0.7.0"
 description = "Open the active Pi Workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"
@@ -23,6 +23,7 @@
     "skills",
     "examples",
     "docs",
+    "schemas",
     "plugins/herdr",
     "herdr-plugin.toml",
     "README.md",
@@ -41,6 +42,10 @@
     "./controllers": {
       "types": "./dist/controllers/index.d.ts",
       "default": "./dist/controllers/index.js"
+    },
+    "./builtins": {
+      "types": "./dist/builtins/index.d.ts",
+      "default": "./dist/builtins/index.js"
     }
   },
   "publishConfig": {

package/schemas/decision-presentation-v1.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/decision-presentation-v1.schema.json",
+  "title": "Pi Workflows decision presentation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "summary", "blocks"],
+  "properties": {
+    "schema": { "const": "pi-workflows.decision-presentation.v1" },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 16000 },
+    "blocks": {
+      "type": "array",
+      "maxItems": 256,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "text"],
+            "properties": {
+              "kind": { "const": "paragraph" },
+              "text": { "type": "string", "minLength": 1, "maxLength": 16000 }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "title"],
+            "properties": {
+              "kind": { "const": "section" },
+              "title": { "type": "string", "minLength": 1, "maxLength": 16000 }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "items"],
+            "properties": {
+              "kind": { "const": "bullets" },
+              "items": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 256,
+                "items": { "type": "string", "minLength": 1, "maxLength": 16000 }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "items"],
+            "properties": {
+              "kind": { "const": "fields" },
+              "items": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 256,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["label", "value"],
+                  "properties": {
+                    "label": { "type": "string", "minLength": 1, "maxLength": 16000 },
+                    "value": { "type": "string", "minLength": 1, "maxLength": 16000 }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "text"],
+            "properties": {
+              "kind": { "const": "preformatted" },
+              "text": { "type": "string", "minLength": 1, "maxLength": 16000 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/schemas/human-decision-accepted-v1.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v1.schema.json",
+  "title": "Pi Workflows accepted human decision v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "response",
+    "source",
+    "idempotencyKey",
+    "acceptedAt",
+    "answerDigest"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-accepted.v1" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channel", "actorId", "eventId"],
+      "properties": {
+        "channel": { "type": "string" },
+        "actorId": { "type": "string" },
+        "eventId": { "type": "string" }
+      }
+    },
+    "idempotencyKey": { "type": "string" },
+    "acceptedAt": { "type": "string", "format": "date-time" },
+    "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+  }
+}

package/schemas/human-decision-accepted-v2.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v2.schema.json",
+  "title": "Pi Workflows accepted human decision v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
+    "revision",
+    "response",
+    "source",
+    "idempotencyKey",
+    "acceptedAt",
+    "answerDigest"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-accepted.v2" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "revision": { "type": "integer", "minimum": 1 },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channel", "actorId", "eventId"],
+      "properties": {
+        "channel": { "type": "string" },
+        "actorId": { "type": "string" },
+        "eventId": { "type": "string" }
+      }
+    },
+    "idempotencyKey": { "type": "string" },
+    "acceptedAt": { "type": "string", "format": "date-time" },
+    "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+  }
+}

package/schemas/human-decision-answer-attempt-v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-answer-attempt-v1.schema.json",
+  "title": "Pi Workflows human decision answer attempt v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "attemptId",
+    "attemptedAt",
+    "decisionId",
+    "requestDigest",
+    "choice",
+    "source",
+    "idempotencyKey"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-answer-attempt.v1" },
+    "attemptId": { "type": "string" },
+    "attemptedAt": { "type": "string", "format": "date-time" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "choice": { "type": "string" },
+    "input": { "type": "object", "additionalProperties": { "type": "string" } },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channel", "actorId", "eventId"],
+      "properties": {
+        "channel": { "type": "string" },
+        "actorId": { "type": "string" },
+        "eventId": { "type": "string" }
+      }
+    },
+    "idempotencyKey": { "type": "string" }
+  }
+}

package/schemas/human-decision-cancellation-v1.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-cancellation-v1.schema.json",
+  "title": "Pi Workflows human decision cancellation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "decisionId", "requestDigest", "cancelledAt", "reason"],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-cancellation.v1" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "cancelledAt": { "type": "string", "format": "date-time" },
+    "reason": { "enum": ["cancelled", "expired"] }
+  }
+}

package/schemas/human-decision-continuation-v1.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-continuation-v1.schema.json",
+  "title": "Pi Workflows human decision continuation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "decisionId", "requestDigest", "parentRunId", "runId", "createdAt"],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-continuation.v1" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "parentRunId": { "type": "string" },
+    "runId": { "type": "string" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  }
+}

package/schemas/human-decision-delivery-v1.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-delivery-v1.schema.json",
+  "title": "Pi Workflows human decision delivery v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "attemptId",
+    "decisionId",
+    "requestDigest",
+    "channel",
+    "state",
+    "createdAt"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-delivery.v1" },
+    "attemptId": { "type": "string" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "channel": { "type": "string" },
+    "state": { "enum": ["intent", "confirmed", "failed", "unknown"] },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": "string", "format": "date-time" },
+    "messageCount": { "type": "integer", "minimum": 0 },
+    "errorCode": { "type": "string" }
+  }
+}

package/schemas/human-decision-delivery-v2.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-delivery-v2.schema.json",
+  "title": "Pi Workflows human decision delivery v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "attemptId",
+    "decisionId",
+    "requestDigest",
+    "presentationDigest",
+    "channel",
+    "phase",
+    "state",
+    "createdAt"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-delivery.v2" },
+    "attemptId": { "type": "string" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "channel": { "type": "string" },
+    "phase": { "enum": ["intent", "part", "complete"] },
+    "state": { "enum": ["intent", "confirmed", "failed", "unknown"] },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": "string", "format": "date-time" },
+    "recipientIndex": { "type": "integer", "minimum": 1 },
+    "partIndex": { "type": "integer", "minimum": 1 },
+    "partCount": { "type": "integer", "minimum": 1, "maximum": 20 },
+    "contentDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "messageCount": { "type": "integer", "minimum": 0 },
+    "errorCode": { "type": "string" }
+  }
+}

package/schemas/human-decision-receipt-v1.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-receipt-v1.schema.json",
+  "title": "Pi Workflows redacted human decision receipt v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "nodeId",
+    "response",
+    "acceptedAt",
+    "answerDigest"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-receipt.v1" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "nodeId": { "type": "string" },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "acceptedAt": { "type": "string", "format": "date-time" },
+    "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+  }
+}

package/schemas/human-decision-receipt-v2.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-receipt-v2.schema.json",
+  "title": "Pi Workflows redacted human decision receipt v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
+    "revision",
+    "nodeId",
+    "response",
+    "acceptedAt",
+    "answerDigest"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-receipt.v2" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "revision": { "type": "integer", "minimum": 1 },
+    "nodeId": { "type": "string" },
+    "response": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["choice"],
+      "properties": {
+        "choice": { "type": "string" },
+        "input": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "acceptedAt": { "type": "string", "format": "date-time" },
+    "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+  }
+}

package/schemas/human-decision-request-v1.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-request-v1.schema.json",
+  "title": "Pi Workflows human decision request v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "runId",
+    "workflowName",
+    "nodeId",
+    "attemptId",
+    "audience",
+    "title",
+    "body",
+    "choices",
+    "createdAt"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-request.v1" },
+    "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "runId": { "type": "string" },
+    "workflowName": { "type": "string" },
+    "nodeId": { "type": "string" },
+    "attemptId": { "type": "string" },
+    "audience": { "type": "string" },
+    "title": { "type": "string", "minLength": 1 },
+    "body": true,
+    "choices": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1 },
+          "input": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "name", "prompt", "minLength", "maxLength"],
+            "properties": {
+              "kind": { "const": "text" },
+              "name": { "type": "string" },
+              "prompt": { "type": "string", "minLength": 1 },
+              "minLength": { "type": "integer", "minimum": 0 },
+              "maxLength": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" }
+  }
+}