@hasna/loops 0.3.56 → 0.3.57

package/README.md

@@ -41,6 +41,41 @@ bun link
 
 The CLI stores state in `~/.hasna/loops` by default. Set `LOOPS_DATA_DIR` to isolate state for tests or another profile.
 
+## MCP Server
+
+OpenLoops ships a stdio MCP server for safe loop and workflow inspection from
+MCP-capable agents:
+
+```bash
+loops-mcp list-tools
+loops-mcp
+```
+
+The package also exports the server factory for embedded hosts:
+
+```ts
+import { createLoopsMcpServer } from "@hasna/loops/mcp";
+```
+
+Available read tools include `loops_list`, `loops_show`, `loop_runs`,
+`loops_doctor`, `workflows_list`, `workflow_read`, and `workflow_validate`.
+Resources are available at `loops://runtime` and `loops://tools`.
+Those tools use the same `Store`, public redaction helpers, and workflow parser
+as the CLI and SDK, so read output and validation behavior stay aligned across
+surfaces.
+
+Mutation tools are disabled by default. Start the server with
+`LOOPS_MCP_ALLOW_MUTATIONS=true` only for a trusted local MCP host that should be
+allowed to change loop state. Even then, mutation tools require exact
+confirmation strings: `loop_pause`, `loop_resume`, `loop_run_now`,
+`loop_create_command`, and `loop_create_workflow`. MCP `loop_run_now` schedules
+the loop for immediate daemon pickup; inline execution remains CLI-only.
+
+Keep host-affecting or long-running operations on the CLI: daemon
+start/stop/install/logs, inline `run-now`, `tick`, loop removal/archive
+maintenance, workflow create/migrate/cancel/recover, agent loop creation,
+template materialization, and event-route drains.
+
 ## Create Loops
 
 Run a deterministic command every minute:
@@ -94,6 +129,20 @@ loops create agent supply-chain-watch \
   --prompt "Check for suspicious dependency or supply-chain changes. Report only concrete findings."
 ```
 
+Run an OpenCode loop with an explicit provider/model. OpenCode reads
+`~/.config/opencode/config.json` when no model is supplied, so OpenLoops rejects
+OpenCode agent targets without `--model` instead of inheriting a stale or
+machine-specific default.
+
+```bash
+loops create agent opencode-smoke \
+  --provider opencode \
+  --model openrouter/google/gemini-2.5-flash \
+  --at "$(date -u -d '+1 minute' +%Y-%m-%dT%H:%M:%SZ)" \
+  --cwd /path/to/repo \
+  --prompt "Reply with exactly OK."
+```
+
 For `codewith` and `aicopilot` account isolation, register matching OpenAccounts tools first if they are not built in on the machine:
 
 ```bash
@@ -166,6 +215,11 @@ loops create agent repo-fixer \
 
 Goal planning and validation use the Vercel AI SDK with `@openrouter/ai-sdk-provider`. Set `OPENROUTER_API_KEY`; optionally set `LOOPS_GOAL_BASE_URL` to point at a local gateway compatible with OpenRouter. Goal context is passed to wrapped commands and agents as `LOOPS_GOAL_ID`, `LOOPS_GOAL_OBJECTIVE`, and `LOOPS_GOAL_NODE_KEY`.
 
+If a resumed goal plan has no runnable nodes, failed run output includes a
+structured `diagnostics` object with the concrete blocker and `owner`
+(`goal`, `goal-plan`, or `goal-plan-node`) so scheduled workflow loops do not
+end as opaque blocked plans.
+
 Inspect configured and runtime goal state:
 
 ```bash
@@ -238,8 +292,8 @@ loops create workflow repo-morning-loop --workflow repo-morning --cron "0 8 * *
 
 Use `recover` only for interrupted `running` workflow runs whose recorded child
 process is gone. Terminal `timed_out` task/event workflow runs are audit
-history; requeue them through the original task/event route after fixing the
-cause.
+history; use `loops routes requeue <work-item-id> --reason "<cause fixed>"`
+after fixing the cause, then redeliver or drain the original task/event route.
 
 Workflow specs are stored separately from loops. A loop can schedule a workflow, but workflow runs and step runs have their own durable rows and events. Steps run in dependency order and a scheduled workflow run is idempotent per loop slot.
 
@@ -309,11 +363,14 @@ registry.
 
 Timeout policy is explicit. Deterministic command/check steps should normally
 keep finite `timeoutMs`/`idleTimeoutMs` guards so broken shell work cannot run
-forever. Agentic work steps default to no timeout in built-in worker/verifier
-and task-lifecycle templates; use `timeoutMs: null` in workflow JSON, or
-`--timeout none` / `--timeout unlimited` for CLI-created targets, when a step
-may need hours or days. Use a positive numeric `timeoutMs` only when an agentic
-step is intentionally bounded.
+forever. Agentic work steps default to no wall-clock timeout in built-in
+worker/verifier and task-lifecycle templates; use `timeoutMs: null` in workflow
+JSON, or `--timeout none` / `--timeout unlimited` for CLI-created targets, when
+a step may need hours or days. Verifier/evaluator steps add a 15 minute
+`idleTimeoutMs` watchdog by default so a verifier cannot hang silently after the
+worker finishes; pass `--verifier-idle-timeout none` or template variable
+`verifierIdleTimeoutMs=none` only when another heartbeat is guaranteed. Use a
+positive numeric `timeoutMs` only when an agentic step is intentionally bounded.
 
 To migrate existing workflow loops, do not edit `workflow_specs.steps_json`
 directly because historical workflow runs must keep pointing at their original
@@ -329,7 +386,8 @@ with the requested agent timeout policy, retargets only future executions of
 eligible non-running workflow loops, and leaves terminal timed-out workflow runs
 as audit history. Use `loops workflows recover` only for interrupted `running`
 workflow runs whose recorded child process is gone; terminal `timed_out` runs
-must be requeued by re-delivering or draining the original task/event route.
+must be requeued with `loops routes requeue <work-item-id> --reason "<cause fixed>"` before
+re-delivering or draining the original task/event route.
 
 ```json
 {
@@ -402,15 +460,60 @@ cat task-created-event.json | loops events handle todos-task \
   --worktree-mode required
 ```
 
+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. Terminal route work items such as
+failed, dead-letter, cancelled, or succeeded history stay deduped until an
+operator runs `loops routes requeue <work-item-id> --reason "<cause fixed>"`.
+The next route-created output records `requeue` evidence with the previous work
+item id, previous attempts, operator reason, new attempt, workflow id, and loop
+id.
+
+Task route drains can select providers from task metadata instead of running one
+fixed provider/account pool for the whole drain. Add one or more
+`--provider-rule field=value:provider[:profile1,profile2]` flags; the first
+matching rule wins. Rule profiles become a Codewith auth-profile pool for
+`provider=codewith` and an OpenAccounts account pool for other providers. Tasks
+can also carry `provider_hint`/`route_provider`, `auth_profile_pool`, or
+`account_pool` metadata. Dry-run, drain evidence, and route invocation scope
+include `providerRouting` so operators can see why a provider/account was
+selected.
+
+```bash
+loops routes drain todos-task \
+  --dry-run \
+  --provider-rule area=frontend:claude:claude-ui-a,claude-ui-b \
+  --provider-rule area=backend:codewith:account004,account005 \
+  --worktree-mode required
+```
+
+PR approval or merge tasks that need a branch-protection review must carry
+explicit non-author GitHub reviewer evidence before a worker is created. When a
+task has a PR reference plus `reviewDecision=REVIEW_REQUIRED`,
+`mergeStateStatus=BLOCKED`, branch-protection review language, or similar
+approval/merge intent, routing is skipped unless `--github-reviewer`,
+`--github-reviewer-pool`, or task metadata such as `github_reviewer` /
+`github_reviewer_pool` names at least one GitHub login different from the PR
+author. This blocks self-review routes before they can spawn an impossible
+worker, and dry-run/admission JSON includes `prReviewRouting` evidence.
+
 By default, `todos-task` routes use `todos-task-worker-verifier` for backwards
 compatibility. Use `--template task-lifecycle` to run the full triage ->
 planner -> worker -> verifier lifecycle. The route rejects unrelated templates
 such as `pr-review` so a todos task cannot accidentally use the wrong contract.
+The default worker/verifier template starts with a deterministic
+`source-task-gate` command that runs `todos --project <source-store> --json
+inspect <task-id>` before the worker. If the routed source task cannot be
+resolved in the intended Todos store, the workflow fails before repo-mutating
+agent work starts.
 The lifecycle template adds deterministic gates after triage and planning. If
 either step marks the task blocked, omits its contextual
 `openloops:triage=go task=<id> event=<event-id>` /
 `openloops:planner=go task=<id> event=<event-id>` marker comment, or the task
-is no-auto/manual/approval-required, the worker step is not started. Use
+is blocked/completed/done/cancelled/failed/archived/no-auto/manual/
+approval-required, the worker step is not started. Use
 `--triage-auth-profile`, `--planner-auth-profile`, `--worker-auth-profile`, and
 `--verifier-auth-profile` when exact Codewith profiles are needed, or use
 `--auth-profile-pool` for deterministic role rotation.
@@ -460,6 +563,7 @@ 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 requeue <work-item-id> --reason "fixed upstream blocker"
 loops routes invocations
 ```
 
@@ -549,6 +653,72 @@ 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.
 
+### Planned Workflow Upsert SDK
+
+External compilers such as `@hasna/actions` and `@hasna/automations` should not
+write OpenLoops SQLite rows directly. The stable contract should be an
+idempotent CLI/SDK upsert that accepts a fully rendered one-shot workflow loop
+request and returns durable refs.
+
+Proposed SDK shape:
+
+```ts
+type WorkflowUpsertRequest = {
+  idempotencyKey: string;
+  source: { kind: "action" | "automation" | "event"; id: string; dedupeKey?: string };
+  subject: { kind: "repo" | "task" | "pr" | "run"; id?: string; path?: string; url?: string };
+  workflow: { name: string; description?: string; steps: WorkflowStepInput[] };
+  loop: { name: string; schedule: { type: "once"; at: string }; machine?: LoopMachineRef };
+  route?: { projectPath?: string; projectGroup?: string; concurrencyGroup?: string };
+  execution?: AutomationExecutionPolicy;
+  mode?: "dry-run" | "preflight" | "commit";
+  dispatch?: "schedule" | "run-now" | "none";
+};
+
+type WorkflowUpsertResult = {
+  ok: boolean;
+  dryRun: boolean;
+  idempotencyKey: string;
+  specHash: string;
+  refs: {
+    workflowId?: string;
+    loopId?: string;
+    invocationId?: string;
+    workItemId?: string;
+    runId?: string;
+    manifestPath?: string;
+  };
+  action: "created" | "updated" | "reused" | "rejected";
+  preflight?: { ok: boolean; checks: unknown[]; error?: string };
+};
+```
+
+Required semantics:
+
+- `mode="dry-run"` validates, canonicalizes, hashes, and returns the same JSON
+  shape without mutating OpenLoops state.
+- `mode="preflight"` additionally checks provider binaries, machine routing,
+  accounts/auth profiles, prompt files, and workflow target compatibility before
+  commit.
+- `mode="commit"` is idempotent on `idempotencyKey` plus `specHash`: identical
+  requests return existing refs; changed specs create a new workflow version or
+  one-shot loop while preserving previous run history.
+- `dispatch="schedule"` stores a one-shot loop for the daemon; `run-now` claims
+  an immediate manual slot; `none` only materializes refs for another owner to
+  trigger later.
+- All persisted output is redacted before storage, and returned refs are enough
+  for the caller to inspect, cancel, replay, or resolve the run without querying
+  SQLite directly.
+
+See `docs/AUTOMATION_RUNTIME_DESIGN.md` for the planned DLQ/dead-letter
+lifecycle, including `loops dlq list/show/replay/resolve`, idempotent replay
+keys, and compatibility rules for `@hasna/actions`.
+
+The same design doc also defines the planned strict automation execution mode:
+minimal env inheritance, scoped secret refs, enforced allowlists,
+redaction-before-persistence, and provider-safe defaults for automation-created
+work.
+
 ## Transcript-Driven Loops
 
 OpenLoops can turn long-form media or meeting transcripts into recurring workflow work when paired with `iapp-transcriber`. The template at `docs/workflows/transcript-feedback-to-loops.json` transcribes an authorized media URL, asks an agent to extract recurring loop candidates, authors workflow specs, and validates generated workflows before scheduling. Copy it into the target repo, replace `/path/to/repo` with that repo's absolute path, and provide `TRANSCRIBER_SOURCE_URL` through the runner environment or a private, uncommitted workflow copy before storing or scheduling it. Do not commit private or signed media URLs.
@@ -608,10 +778,14 @@ directory stay as tasks and record an `auto_route_skipped_reason`. Without
 `--auto-route`, the command only creates or updates deduped tasks.
 
 `hygiene names` reports canonical `machine-*` or `repo-<name>-*` loop names and
-renames only with `--apply`. Apply mode writes a SQLite backup under
-`<LOOPS_DATA_DIR>/backups` before changing loop names. `hygiene duplicates`
-groups loops with the same normalized name, cwd, and schedule. `hygiene scripts`
-inventories loops whose command still references `~/.hasna/loops/scripts`.
+renames only with `--apply`. Cadence/timer suffixes such as `-5m`, `-15m`,
+`-6h`, `-hourly`, and `-daily` are removed from canonical names; cadence belongs
+in the schedule metadata and the human `loops list` `cadence=` column. Apply
+mode writes a SQLite backup under `<LOOPS_DATA_DIR>/backups` before changing loop
+names. New loops get a compact default description with Why/How/Outcome text
+unless the operator supplies `--description`. `hygiene duplicates` groups loops
+with the same normalized name, cwd, and schedule. `hygiene scripts` inventories
+loops whose command still references `~/.hasna/loops/scripts`.
 `hygiene route-tasks` upserts deduped Todos tasks for hygiene findings with
 stable fingerprints and `no_tmux_dispatch=true` metadata. Route commands use a
 package-managed cursor under `<LOOPS_DATA_DIR>/route-cursors.json` so bounded
@@ -694,7 +868,7 @@ The adapters intentionally use provider command surfaces instead of pretending e
 
 - Claude uses `claude -p --output-format json` and safe-mode/local setting sources by default.
 - Codewith uses `codewith --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories.
-- AI Copilot and OpenCode use `run --format json --pure`.
+- AI Copilot and OpenCode use `run --format json --pure`. OpenCode requires an explicit provider/model id because ambient OpenCode config is machine-specific.
 - Cursor is CLI-first for now via the standalone `agent -p` binary. OpenLoops no longer falls back to `cursor agent`; install the standalone Cursor Agent CLI so preflight and scheduled runs use the same executable.
 - Codex uses `codex --ask-for-approval never exec --json --ephemeral --skip-git-repo-check`, with `--add-dir` for explicit extra writable directories where supported.
 - Agent prompts are sent through child stdin instead of argv so prompt bodies do not appear in process listings.