polpo-ai 0.10.2 → 0.10.4

package/README.md

@@ -215,6 +215,43 @@ Use `type: "tool"` for deterministic sandbox/tool actions without an LLM turn, a
 
 Loop guards use Polpo's safe expression evaluator instead of JavaScript `eval` or `new Function`. Step outputs are available in the shared context bag by step id or `saveAs` path, e.g. `classify.route`, `review.approved`, or `timing.start`. `saveAs` writes context data; it does not create shell variables inside later `bash` commands. The OSS surface validates and round-trips the contract through core types, API schemas, SDK types, `polpo deploy`, and `polpo pull`.
 
+You can also keep loops as code and compile them to the same canonical contract:
+
+```ts
+// .polpo/loops/router-flow.ts
+import { defineProjectLoop } from "@polpo-ai/core/loop-code";
+
+export default defineProjectLoop({
+  version: "1",
+  kind: "graph",
+  name: "router-flow",
+  context: "shared",
+  start: "classify",
+  steps: {
+    classify: {
+      type: "agent",
+      systemPrompt: "Classify the incoming request.",
+      tools: ["read"],
+      next: "answer",
+    },
+    answer: {
+      type: "agent",
+      systemPrompt: "Answer using the selected route.",
+      tools: ["write"],
+      next: "end",
+    },
+  },
+});
+```
+
+CLI support:
+
+```bash
+polpo loops validate
+polpo loops compile .polpo/loops/router-flow.ts --out .polpo/loops/router-flow.json
+polpo deploy
+```
+
 Agent-direct chat can target a loop explicitly:
 
 ```json
@@ -227,6 +264,64 @@ Agent-direct chat can target a loop explicitly:
 
 At runtime, the selected project loop can narrow the effective prompt, tools, skills, model, reasoning, tool choice, and max turns per agent step. If a step omits `skills`, it inherits the agent-level `skills`. Project loop execution in chat completions uses the shared context graph: deterministic tool steps run first, store outputs in the context bag, and later agent steps receive that context as runtime data in their system prompt. Core keeps a compatibility normalizer for legacy inline `loops` + `pipeline` configs and ships a pure `PipelineExecutor` for sequential, tool, switch, parallel, and human nodes; hosts wire `runLoop`, `runTool`, and `handleHuman` callbacks to their concrete runtime.
 
+Project loops also support governance fields:
+
+```jsonc
+{
+  "version": "1",
+  "kind": "graph",
+  "name": "governed-build",
+  "context": "shared",
+  "hooks": {
+    "loop:start": [
+      { "tool": "unix_time", "saveAs": "timing.start" }
+    ],
+    "tool:after": [
+      { "tool": "audit_step", "input": { "level": "info" }, "saveAs": "audit.last", "onError": "continue" }
+    ],
+    "loop:end": [
+      { "tool": "unix_time", "saveAs": "timing.end" }
+    ]
+  },
+  "policies": [
+    {
+      "id": "only-safe-tools",
+      "hook": "tool:before",
+      "effect": "allow",
+      "when": "tool.name == 'read' || tool.name == 'grep' || tool.name == 'unix_time'"
+    },
+    {
+      "id": "deny-shell",
+      "hook": "tool:before",
+      "effect": "deny",
+      "when": "tool.name == 'bash'",
+      "message": "bash requires an explicit build loop"
+    }
+  ],
+  "start": "capture_start",
+  "steps": {
+    "capture_start": {
+      "type": "tool",
+      "tool": "unix_time",
+      "saveAs": "timing.start",
+      "next": "plan"
+    },
+    "plan": {
+      "type": "agent",
+      "systemPrompt": "Plan the work. Do not edit files.",
+      "tools": ["read", "grep"],
+      "next": "end"
+    }
+  }
+}
+```
+
+Lifecycle hooks are deterministic tool actions run by the host runtime at `loop:start`, `step:before`, `model:before`, `tool:before`, `tool:after`, `step:after`, `loop:transition`, and `loop:end`. Hook `when` guards are evaluated against the shared context plus lifecycle payload such as `step.name`, `step.type`, `tool.name`, `tool.input`, and `transition.from/to`. Hook outputs are saved into the context bag with `saveAs`; `onError: "continue"` turns a failed hook into trace-only telemetry, while the default is fail-closed.
+
+Policies are evaluated before hook actions at the same lifecycle point. `deny` fails the loop with `LoopPolicyDeniedError`, `approval` raises `LoopApprovalRequiredError`, and `allow` policies form an allow-list for that lifecycle point when at least one exists. If an allow-list is present and no allow rule matches, the loop is blocked.
+
+When the host wires `LoopRunStore`, chat completions create durable loop runs, append every `loop_trace` event, and return `loop_run_id`. When the host also wires `ApprovalStore`, approval policies create a pending approval request and mark the loop run as `awaiting_approval` with `approvalRequestId`. The SDK exposes `getLoopRuns()` and `getLoopRun(id)` for audit/history surfaces. Streaming completions still emit each trace incrementally.
+
 ## SDK
 
 ### Client SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polpo-ai",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "The open backend for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -66,10 +66,10 @@
     "nanoid": "^5.1.2",
     "yaml": "^2.7.0",
     "zod": "^4.3.6",
-    "@polpo-ai/llm": "0.10.2",
-    "@polpo-ai/vault-crypto": "0.10.2",
-    "@polpo-ai/core": "0.10.2",
-    "@polpo-ai/server": "0.10.2"
+    "@polpo-ai/core": "0.10.4",
+    "@polpo-ai/server": "0.10.4",
+    "@polpo-ai/llm": "0.10.4",
+    "@polpo-ai/vault-crypto": "0.10.4"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.6.2",
@@ -77,7 +77,7 @@
     "nodemailer": "^8.0.1",
     "playwright-core": "^1.52.0",
     "postgres": "^3.4.0",
-    "@polpo-ai/drizzle": "0.10.2"
+    "@polpo-ai/drizzle": "0.10.4"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",