@hasna/loops 0.3.38 → 0.3.39

package/README.md

@@ -78,7 +78,7 @@ loops create agent supply-chain-watch \
   --provider codewith \
   --every 15m \
   --cwd /path/to/repo \
-  --sandbox danger-full-access \
+  --sandbox workspace-write \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
@@ -90,7 +90,7 @@ loops create agent supply-chain-watch \
   --auth-profile account001 \
   --every 15m \
   --cwd /path/to/repo \
-  --sandbox danger-full-access \
+  --sandbox workspace-write \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
@@ -212,6 +212,9 @@ Built-in templates turn common orchestration flows into reusable workflow JSON.
 `event-worker-verifier` handles any Hasna event envelope and then verifies the
 handling. `bounded-agent-worker-verifier` is for recurring bounded agent work:
 one worker runs a narrow objective, then a fresh verifier audits the result.
+The catalog also includes `task-lifecycle`, `pr-review`, `scheduled-audit`,
+`knowledge-refresh`, `report-only`, `incident-response`, and
+`deterministic-check-create-task` for common operator workflows.
 
 ```bash
 loops templates list
@@ -221,7 +224,7 @@ loops templates render todos-task-worker-verifier \
   --var projectPath=/path/to/repo \
   --var provider=codewith \
   --var authProfilePool=account004,account005,account006 \
-  --var sandbox=danger-full-access
+  --var sandbox=workspace-write
 loops templates create-workflow todos-task-worker-verifier \
   --var taskId=<task-id> \
   --var projectPath=/path/to/repo
@@ -236,20 +239,27 @@ loops templates render bounded-agent-worker-verifier \
   --var projectPath=/path/to/repo \
   --var provider=codewith \
   --var authProfilePool=account004,account005 \
-  --var sandbox=danger-full-access \
+  --var sandbox=workspace-write \
   --var worktreeMode=required
+loops templates render pr-review \
+  --var prUrl=https://github.com/hasna/loops/pull/123 \
+  --var projectPath=/path/to/repo
+loops templates render deterministic-check-create-task \
+  --var projectPath=/path/to/repo \
+  --var checkCommand='your deterministic check and todos upsert command'
 ```
 
 For event-driven task automation, `loops events handle todos-task` reads a
-Hasna event envelope from stdin or `HASNA_EVENT_JSON`, renders the template, and
-schedules a deduped one-shot workflow loop:
+Hasna event envelope from stdin or `HASNA_EVENT_JSON`, records a
+`WorkflowInvocation`, upserts an admission work item, and admits that work item
+into a deduped one-shot workflow loop when route capacity allows:
 
 ```bash
 cat task-created-event.json | loops events handle todos-task \
   --provider codewith \
   --auth-profile-pool account004,account005,account006 \
   --permission-mode bypass \
-  --sandbox danger-full-access \
+  --sandbox workspace-write \
   --worktree-mode required
 ```
 
@@ -261,18 +271,89 @@ cat event.json | loops events handle generic \
   --provider codewith \
   --auth-profile-pool account004,account005,account006 \
   --permission-mode bypass \
-  --sandbox danger-full-access \
+  --sandbox workspace-write \
   --project-path /path/to/repo \
   --worktree-mode required
 ```
 
 This is the intended deterministic-to-agentic path: a producer creates a todos
-task, `@hasna/events` delivers `task.created`, OpenLoops creates a worker and a
-verifier workflow, and the workflow updates todos with evidence. Use account
-pools so worker and verifier steps do not burn the same profile; OpenLoops picks
-deterministically and uses a different verifier profile when the pool has at
-least two entries. Use `--dry-run` to inspect the rendered workflow and loop
-input without storing anything.
+task, `@hasna/events` delivers `task.created`, OpenLoops records the invocation
+and admission item, OpenLoops creates a worker/verifier workflow when admitted,
+and the workflow updates todos with evidence. Use account pools so worker and
+verifier steps do not burn the same profile; OpenLoops picks deterministically
+and uses a different verifier profile when the pool has at least two entries.
+Use `--dry-run` to inspect the rendered invocation, work item, workflow, and
+loop input without storing anything.
+
+Generated worker/verifier workflows fail closed when `sandbox=danger-full-access`
+is requested without `manualBreakGlass=true`. Use `workspace-write` for
+unattended task/event routes. Full access is an explicit manual emergency path,
+not a default automation mode.
+
+Inspect route state with:
+
+```bash
+cat task-created-event.json | loops routes preview todos-task --sandbox workspace-write
+cat task-created-event.json | loops routes create todos-task --sandbox workspace-write
+loops routes drain todos-task --task-list oss --max-dispatch 2 --compact
+loops routes schedule todos-task route-drain-oss-5m --every 5m --task-list oss --max-dispatch 1 --compact
+loops routes list --route-key todos-task
+loops routes show <work-item-id>
+loops routes invocations
+```
+
+Workflow run manifests are written under
+`.hasna/loops/runs/<project-slug>/<subject-key>/<run-id>/manifest.json`.
+`subject-key` is a safe derived path segment, not the raw subject reference.
+
+## OpenAutomations Runtime Binding
+
+OpenLoops can be used as an execution runtime for deterministic OpenAutomations
+product automations, but it does not own the automation product surface.
+`@hasna/automations` owns automation specs, trigger materialization, product
+automation action queues, DLQ/replay, idempotency, approvals, and audit
+evidence. OpenLoops owns agent workflow invocation/admission/runs. OpenLoops
+only executes work that OpenAutomations has explicitly handed off; it does not
+make OpenAutomations the queue owner for todos task/PR/review agent workflows.
+
+The SDK exposes the boundary descriptor:
+
+```ts
+import { openAutomationsRuntimeBinding } from "@hasna/loops";
+
+const binding = openAutomationsRuntimeBinding();
+console.log(binding.handoff); // "claim-queue"
+console.log(binding.eventHandoff.handlerCommand); // "loops events handle generic"
+```
+
+The claim-queue handoff uses the OpenAutomations CLI or SDK:
+
+```bash
+automations queue claim --runner open-loops:<worker-id>
+automations queue complete <action-id> --runner open-loops:<worker-id>
+automations queue fail <action-id> --runner open-loops:<worker-id> --code <code> --message <message>
+```
+
+For explicit event workflow routing, OpenAutomations can export the normalized
+event envelope and OpenLoops can consume it through the existing generic event
+handler:
+
+```bash
+automations --json webhooks event <route> --body-json '<json>' \
+  | loops --json events handle generic
+```
+
+This is not automation materialization in OpenLoops. It is an explicit
+event-envelope workflow handoff: OpenAutomations owns deterministic automation
+specs, webhook normalization, queue state, approvals, DLQ, and replay; OpenLoops
+owns agent workflow invocation after the operator routes the envelope to
+`loops events handle generic`.
+
+Do not store automation specs in OpenLoops, infer automation triggers from event
+transport alone, or replace the OpenAutomations queue with loop/workflow rows.
+When a loop or workflow is used for execution, keep `HASNA_AUTOMATIONS_DIR`
+pointing at the owning OpenAutomations data root and preserve the runner id in
+completion/failure calls so OpenAutomations can enforce action leases.
 
 ## Transcript-Driven Loops