@hasna/loops 0.3.53 → 0.3.55

package/README.md

@@ -101,6 +101,51 @@ accounts tools add codewith --label "Codewith" --env-var CODEWITH_HOME --bin cod
 accounts tools add aicopilot --label "AI Copilot" --env-var AICOPILOT_CONFIG_DIR --bin aicopilot
 ```
 
+## Prompt Files
+
+Use prompt files for production agent prompts instead of long inline strings.
+
+```bash
+mkdir -p ~/.hasna/loops/prompts
+$EDITOR ~/.hasna/loops/prompts/repo-morning-check.md
+
+loops create agent morning-check \
+  --provider codewith \
+  --auth-profile account001 \
+  --cron "0 8 * * *" \
+  --cwd /path/to/repo \
+  --prompt-file ~/.hasna/loops/prompts/repo-morning-check.md
+```
+
+Workflow JSON also supports `promptFile` on agent targets. Relative paths
+resolve from the workflow JSON file's directory:
+
+```json
+{
+  "name": "repo-morning",
+  "steps": [
+    {
+      "id": "review",
+      "target": {
+        "type": "agent",
+        "provider": "codewith",
+        "cwd": "/path/to/repo",
+        "promptFile": "prompts/repo-morning-review.md"
+      }
+    }
+  ]
+}
+```
+
+OpenLoops records `promptSource` metadata and redacts prompt bodies in public
+CLI output by default, including `templates render`. Use
+`~/.hasna/loops/prompts/<stable-name>.md` as the default prompt store for
+production loops.
+
+Reusable custom templates cannot contain `promptFile`. Keep prompt files in
+direct workflow JSON or agent loop creation; use template variables only for
+non-secret routing/configuration data.
+
 ## Goals
 
 Add `--goal` to wrap a command, agent, or workflow loop in an AI-SDK orchestration layer. OpenLoops asks the configured model to create a flat DAG plan, executes ready nodes by calling the underlying target, then runs an adversarial achievement audit before marking the goal complete.
@@ -191,6 +236,11 @@ loops workflows recover <workflow-run-id>
 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.
+
 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.
 
 For command steps, `command` is the executable when `shell` is not true. Put flags in `args`:
@@ -257,6 +307,30 @@ Custom reusable workflow templates live under the OpenLoops app data directory:
 showing, and rendering templates never executes workflow steps or mutates the
 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.
+
+To migrate existing workflow loops, do not edit `workflow_specs.steps_json`
+directly because historical workflow runs must keep pointing at their original
+spec. Use the append-only migrator:
+
+```bash
+loops workflows migrate-agent-timeouts --loop <loop-id-or-name>
+loops workflows migrate-agent-timeouts --loop <loop-id-or-name> --apply
+```
+
+The command dry-runs by default. With `--apply`, it creates a new workflow spec
+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.
+
 ```json
 {
   "id": "custom-report",
@@ -265,8 +339,7 @@ registry.
   "kind": "workflow",
   "variables": [
     { "name": "objective", "required": true, "description": "Report objective." },
-    { "name": "projectPath", "required": true, "description": "Working directory." },
-    { "name": "timeoutMs", "default": "300000", "type": "number" }
+    { "name": "projectPath", "required": true, "description": "Working directory." }
   ],
   "workflow": {
     "name": "custom-report-${objective}",
@@ -281,9 +354,9 @@ registry.
           "configIsolation": "safe",
           "permissionMode": "bypass",
           "sandbox": "workspace-write",
-          "timeoutMs": "${timeoutMs}"
+          "timeoutMs": null
         },
-        "timeoutMs": "${timeoutMs}"
+        "timeoutMs": null
       }
     ]
   }