@hasna/loops 0.3.14 → 0.3.16

package/docs/USAGE.md

@@ -94,6 +94,23 @@ loops create agent supply-chain-watch \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
+Agent loops can also carry advisory per-session allowlist metadata:
+
+```bash
+loops create agent repo-check \
+  --provider codewith \
+  --every 15m \
+  --cwd /path/to/repo \
+  --prompt "Check the repo and report concrete failures." \
+  --allow-tool functions.exec_command \
+  --allow-command git,bun
+```
+
+These fields are stored on the loop target and exposed to the run environment
+as `LOOPS_AGENT_ALLOWED_TOOLS`, `LOOPS_AGENT_ALLOWED_COMMANDS`, and
+`LOOPS_AGENT_ALLOWLIST_ENFORCEMENT=metadata_only`. They are not enforced by
+OpenLoops yet; provider-native enforcement will be added separately.
+
 For `codewith` and `aicopilot` account isolation, register matching OpenAccounts tools first if they are not built in on the machine:
 
 ```bash
@@ -176,7 +193,7 @@ loops templates render todos-task-worker-verifier \
   --var taskTitle="Fix parser" \
   --var projectPath=/path/to/repo \
   --var provider=codewith \
-  --var authProfile=account005 \
+  --var authProfilePool=account004,account005,account006 \
   --var sandbox=danger-full-access
 loops templates create-workflow todos-task-worker-verifier \
   --var taskId=<task-id> \
@@ -196,18 +213,26 @@ schedules a deduped one-shot workflow loop:
 ```bash
 cat task-created-event.json | loops events handle todos-task \
   --provider codewith \
-  --auth-profile account005 \
+  --auth-profile-pool account004,account005,account006 \
   --permission-mode bypass \
   --sandbox danger-full-access
 ```
 
+Task routing is explicit opt-in. The handler skips the event without creating a
+workflow unless the event data or metadata has `route_enabled=true`,
+`automation.allowed=true`, or a task tag containing `auto:route`. It also skips
+blocked, completed/done, cancelled/canceled, failed, archived, manual,
+approval-required, or `no-auto` tasks. This guard exists even when the upstream
+`@hasna/events` webhook filter is misconfigured, so task existence alone is not
+permission to execute agent work.
+
 For other Hasna apps that expose `@hasna/events` webhooks, use the generic
 handler:
 
 ```bash
 cat event.json | loops events handle generic \
   --provider codewith \
-  --auth-profile account005 \
+  --auth-profile-pool account004,account005,account006 \
   --permission-mode bypass \
   --sandbox danger-full-access \
   --project-path /path/to/repo
@@ -215,9 +240,11 @@ cat event.json | loops events handle generic \
 
 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
-`--dry-run` to inspect the rendered workflow and loop input without storing
-anything.
+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.
 
 ## Transcript-Driven Loops
 
@@ -240,12 +267,45 @@ loops runs <id-or-name>
 loops pause <id-or-name>
 loops resume <id-or-name>
 loops stop <id-or-name>
+loops archive <id-or-name>
+loops unarchive <id-or-name>
 loops remove <id-or-name>
 loops run-now <id-or-name>
 ```
 
 Use `--json` for machine-readable output. Prompt bodies and run stdout/stderr are redacted by default in status output. `loops run-now` exits non-zero when the recorded run fails or times out.
 
+## Health And Expectations
+
+`loops health --json` summarizes the latest run for each loop and classifies
+agent-run failures for default-loop SLOs:
+
+```bash
+loops health --json
+loops expectations <loop-id-or-name> --json
+```
+
+The JSON contains the expectation result, bounded error/stdout/stderr evidence,
+a stable failure fingerprint, route metadata, and recommended task fields.
+OpenLoops does not mutate Todos from these commands. Until Todos has a native
+upsert command, consumers can use the included compatibility fallback:
+`todos search <dedupe-key>`, then `todos add ...` or `todos comment ...`.
+The planned native integration is represented in `futureNativeUpsert`.
+
+Failure classifications are: `rate_limit`, `auth`, `model_not_found`,
+`context_length`, `schema_response_format`, `node_init`, `timeout`, `sigsegv`,
+`skipped_previous_active`, and `unknown`.
+
+Archive loops when retiring old automation but preserving history:
+
+```bash
+loops archive <id-or-name>
+loops list --archived
+loops list --all
+```
+
+Archived loops are hidden from the default `loops list`, excluded from daemon scheduling and doctor preflight, and cannot be run manually until restored with `loops unarchive`. `loops remove` deletes the loop record; prefer `archive` for superseded loops that may need audit history.
+
 `loops run-now` reports the manual run source:
 
 - `source=ad_hoc`: the loop was not due yet, so OpenLoops created a one-off manual slot. This is a single immediate attempt and does not schedule retries or consume the future scheduled slot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/loops",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   "type": "module",
   "main": "dist/index.js",