@hasna/loops 0.3.37 → 0.3.39

package/dist/types.d.ts

@@ -43,6 +43,26 @@ export type ScheduleSpec = OnceSchedule | IntervalSchedule | CronSchedule | Dyna
 export interface RuntimePreflightPolicy {
     beforeRun?: boolean;
 }
+export interface OpenAutomationsRuntimeBinding {
+    integration: "open-automations";
+    role: "runtime";
+    handoff: "claim-queue";
+    queueOwner: "open-automations";
+    runtimeOwner: "open-loops";
+    statusCommand: "automations status";
+    claimCommand: "automations queue claim";
+    completeCommand: "automations queue complete";
+    failCommand: "automations queue fail";
+    eventHandoff: {
+        envelopeCommand: "automations webhooks event";
+        handlerCommand: "loops events handle generic";
+        pipeExample: string;
+        boundary: string;
+    };
+    requiredEnvironment: string[];
+    guarantees: string[];
+    nonGoals: string[];
+}
 export interface CommandTarget {
     type: "command";
     command: string;
@@ -51,6 +71,7 @@ export interface CommandTarget {
     shell?: boolean;
     env?: Record<string, string>;
     timeoutMs?: number;
+    idleTimeoutMs?: number;
     account?: AccountRef;
     preflight?: RuntimePreflightPolicy;
 }
@@ -94,6 +115,7 @@ export interface AgentTarget {
     authProfile?: string;
     extraArgs?: string[];
     timeoutMs?: number;
+    idleTimeoutMs?: number;
     configIsolation?: AgentConfigIsolation;
     permissionMode?: AgentPermissionMode;
     sandbox?: AgentSandbox;
@@ -115,6 +137,90 @@ export type LoopTarget = ExecutableTarget | WorkflowTarget;
 export type WorkflowStatus = "active" | "archived";
 export type WorkflowRunStatus = "running" | "succeeded" | "failed" | "timed_out" | "cancelled";
 export type WorkflowStepRunStatus = "pending" | "running" | "succeeded" | "failed" | "timed_out" | "skipped" | "cancelled";
+export type WorkflowInvocationSourceKind = "task" | "event" | "schedule" | "manual" | "pr" | "review" | "knowledge";
+export type WorkflowInvocationSubjectKind = "repo" | "pr" | "task" | "doc" | "run" | "metric";
+export type WorkflowInvocationIntent = "route" | "mutate" | "review" | "evaluate" | "report";
+export interface WorkflowInvocationRef {
+    kind: string;
+    id?: string;
+    path?: string;
+    url?: string;
+    dedupeKey?: string;
+    raw?: Record<string, unknown>;
+}
+export interface WorkflowInvocationScope {
+    projectPath?: string;
+    projectGroup?: string;
+    worktreePolicy?: AgentWorktreeMode;
+    permissions?: string;
+    accountPolicy?: string;
+    concurrencyGroup?: string;
+    [key: string]: unknown;
+}
+export interface WorkflowInvocationOutputPolicy {
+    report?: "always" | "on_change" | "on_failure";
+    createTask?: "never" | "on_actionable" | "on_failure" | "always";
+    [key: string]: unknown;
+}
+export interface WorkflowInvocation {
+    id: string;
+    workflowId?: string;
+    templateId?: string;
+    sourceRef: WorkflowInvocationRef;
+    subjectRef: WorkflowInvocationRef;
+    intent: WorkflowInvocationIntent;
+    scope?: WorkflowInvocationScope;
+    outputPolicy?: WorkflowInvocationOutputPolicy;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateWorkflowInvocationInput {
+    id?: string;
+    workflowId?: string;
+    templateId?: string;
+    sourceRef: WorkflowInvocationRef;
+    subjectRef: WorkflowInvocationRef;
+    intent: WorkflowInvocationIntent;
+    scope?: WorkflowInvocationScope;
+    outputPolicy?: WorkflowInvocationOutputPolicy;
+}
+export type WorkflowWorkItemStatus = "queued" | "deferred" | "admitted" | "running" | "succeeded" | "failed" | "dead_letter" | "cancelled";
+export interface WorkflowWorkItem {
+    id: string;
+    routeKey: string;
+    idempotencyKey: string;
+    invocationId: string;
+    sourceType: string;
+    sourceRef: string;
+    subjectRef: string;
+    projectKey?: string;
+    projectGroup?: string;
+    priority: number;
+    status: WorkflowWorkItemStatus;
+    attempts: number;
+    nextAttemptAt?: string;
+    leaseExpiresAt?: string;
+    workflowId?: string;
+    loopId?: string;
+    workflowRunId?: string;
+    lastReason?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UpsertWorkflowWorkItemInput {
+    routeKey: string;
+    idempotencyKey: string;
+    invocationId: string;
+    sourceType: string;
+    sourceRef: string;
+    subjectRef: string;
+    projectKey?: string;
+    projectGroup?: string;
+    priority?: number;
+    status?: Extract<WorkflowWorkItemStatus, "queued" | "deferred">;
+    nextAttemptAt?: string;
+    lastReason?: string;
+}
 export interface WorkflowStep {
     id: string;
     name?: string;
@@ -164,8 +270,11 @@ export interface WorkflowRun {
     workflowName: string;
     loopId?: string;
     loopRunId?: string;
+    invocationId?: string;
+    workItemId?: string;
     scheduledFor?: string;
     idempotencyKey?: string;
+    manifestPath?: string;
     goalRunId?: string;
     status: WorkflowRunStatus;
     startedAt?: string;

package/docs/USAGE.md

@@ -108,7 +108,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."
 ```
 
@@ -120,7 +120,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."
 ```
 
@@ -216,6 +216,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
@@ -225,7 +228,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
@@ -240,15 +243,23 @@ 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
+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'
 ```
 
-Task/event agent templates default to `worktreeMode=auto`. When `projectPath`
-is an existing git repository, OpenLoops inserts a `prepare-worktree` command
-step before the worker and runs the worker/verifier from a deterministic
-worktree under `~/.hasna/loops/worktrees/<repo>/<run>`. The generated agent
-target includes worktree metadata (`mode`, `cwd`, `path`, `branch`,
-`originalCwd`) so dry-runs and workflow inspection expose the exact checkout.
+Repo-mutating task/event routes should set `worktreeMode=required` so the
+workflow fails fast instead of falling back to the main checkout. When
+`projectPath` is an existing git repository, OpenLoops inserts a
+`prepare-worktree` command step before the worker and runs the worker/verifier
+from a deterministic worktree under `~/.hasna/loops/worktrees/<repo>/<run>`.
+The generated agent target includes worktree metadata (`mode`, `cwd`, `path`,
+`branch`, `originalCwd`) so dry-runs and workflow inspection expose the exact
+checkout.
 
 Use explicit main/default checkout mode only when the task truly requires it:
 
@@ -259,21 +270,23 @@ loops templates render todos-task-worker-verifier \
   --var worktreeMode=main
 ```
 
-Use `worktreeMode=required` when non-worktree execution should fail fast, or
+Use `worktreeMode=auto` only for compatibility or mixed routes where a
+non-git/non-mutating project is expected and the fallback is recorded. Use
 `worktreeMode=off` for non-git projects. `worktreeRoot` and
 `worktreeBranchPrefix` can override the storage root and branch prefix.
 
 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 \
-  --worktree-mode auto
+  --sandbox workspace-write \
+  --worktree-mode required
 ```
 
 Task routing is explicit opt-in. The handler skips the event without creating a
@@ -297,19 +310,40 @@ cat task-created-event.json | loops events handle todos-task \
   --max-active 12
 ```
 
-The limits count active routed worker/verifier workflow loops once per workflow.
+The limits count active admitted/running OpenLoops work items once per workflow.
 `--max-active-per-project` gates new work for the same project path,
 `--max-active-per-project-group` shares a pool across related projects such as
 `oss`, and `--max-active` is the global routed-workflow cap. Project matching
 uses the canonical git top-level path when available, so repo subdirectories
-share the same project cap. A throttled event is skipped with JSON evidence and
-`queuedAtSource=true` instead of creating another worker loop; the source task
-remains the durable queue item and should be replayed/drained later by the task
-scheduler. Re-delivering the event later is safe because event handlers dedupe
-by task/event id before rendering worktree plans or checking route limits. In
+share the same project cap. A throttled event records a deferred OpenLoops
+admission work item with JSON evidence instead of creating another worker loop.
+Re-delivering the event later is safe because handlers dedupe by the work-item
+idempotency key before rendering worktree plans or checking route limits. In
 dry-run mode, throttle counts are not evaluated because opening the live loop
 store can create or migrate the local database.
 
+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
+```
+
+When a workflow run starts from an admitted work item, OpenLoops writes a
+manifest under:
+
+```text
+.hasna/loops/runs/<project-slug>/<subject-key>/<run-id>/manifest.json
+```
+
+`subject-key` is a safe derived path segment (`kind-safeSlug-shortHash`), not
+the raw subject reference. The raw `subjectRef` is stored inside the manifest.
+
 When tasks were created while capacity was full, or when bulk producers created
 many tasks at once, use the drain command instead of replaying every webhook by
 hand. It scans `todos ready --json`, so tasks with incomplete dependencies,
@@ -329,7 +363,7 @@ loops events drain todos-task \
   --max-active-per-project 1 \
   --max-active-per-project-group 4 \
   --max-active 12 \
-  --worktree-mode auto \
+  --worktree-mode required \
   --evidence-dir /home/hasna/.hasna/loops/reports/task-drain
 ```
 
@@ -354,19 +388,26 @@ cat event.json | loops events handle generic \
   --provider codewith \
   --auth-profile-pool account004,account005,account006 \
   --permission-mode bypass \
-  --sandbox danger-full-access \
-  --project-path /path/to/repo
+  --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, including the worktree path and branch for
+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, including the worktree path and branch for
 git-backed tasks.
 
+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.
+
 ## 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.

package/package.json

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