Compose and supervise a bounded loop

Discover the current environment

1. Call orient {} and verify the intended principal and Mind.
2. Call list_skills {}, then get_skill {"name":"loop-composer"} if offered.
3. Call list_actions {} and use only its current action IDs, argument shapes, effects and dry-run support.
4. Call list_loops {}; inspect a possible existing loop with get_loop before creating a duplicate.

A missing operate_loops grant is a stop. Do not substitute a raw file write or automation to bypass it.

Exact lifecycle example

The following input to loop_compose is a fictional checklist. Its constant comparison checks the workflow mechanism only; it does not assess real work, call a model, use a donated action or demonstrate a business result. Once approved, it is designed to start a case every five minutes in shadow mode, and each case waits for a human confirmation. Because max_open_cases is 1 and a case may wait up to an hour, a new trigger starts nothing while a case is still open. Use it only for an explicitly authorised disposable test, then retire it.

{
  "name": "Fictional checklist practice",
  "description": "Disposable lifecycle example with no external action.",
  "spec": {
    "purpose": "Ask the owner to confirm a fictional checklist.",
    "version": 1,
    "supersedes": null,
    "trigger": {"every": "5m"},
    "inputs": [],
    "nodes": [
      {"node": "deterministic_check", "check": "equals",
       "subject": "fixture-ready", "expected": "fixture-ready",
       "on_fail": {"escalate": "Fixture not ready"}},
      {"node": "wait_human",
       "question": "Confirm this fictional checklist was reviewed.",
       "audience": "owner", "timeout": "1h",
       "on_timeout": {"escalate": "Checklist not confirmed"}},
      {"node": "complete_escalate", "outcome": "complete",
       "reason": "Fictional checklist confirmed", "escalate_to": "owner"}
    ],
    "quality": {"rubrics": [], "sample_rate": 1, "min_pass_rate": 1},
    "escalation": {"to": "owner", "channel": "queue", "max_open": 1,
                   "on_budget_exhausted": "fail"},
    "autonomy": {"effect_ceiling": "read_only", "auto_run_max": "read_only"},
    "budget": {"max_nodes_per_case": 5, "max_wall_clock": "2h",
               "max_spend_usd": 0, "max_open_cases": 1}
  }
}

Omit owner and rollout; the gateway supplies the caller and shadow mode. On a passing response retain loop_id, status, version and summary. Inspect the stored object using get_loop {"loop_id":"<returned id>"}.

Rehearsal, review and activation

For a real job, use only discovered actions. Rehearse an invoke_action with dry_run only where that action supports it; reads can still cause network activity or cost. loop_replay checks stored regression cases and is distinct from an action dry run. Superseding revisions need the applicable passing replay.

On a client that exposes these owner lifecycle actions, the exact act envelopes are:

{"action":"loop_replay","item_id":"<loop id>"}
{"action":"loop_approve","item_id":"<loop id>"}
{"action":"loop_activate","item_id":"<loop id>"}

Each line is a separate request, not a JSON array. Invoke only the applicable action after inspecting the preceding result and confirming authority. Approval does not activate, but it does let the loop start scheduled shadow runs: the dispatcher selects every approved loop in shadow or active rollout. A shadow case really performs read-only steps and quality checks (which can incur model cost) and holds back only actions that would change something. loop_activate moves the loop from shadow to active so those actions run for real within the loop’s autonomy limits (actions above those limits still wait for the owner); it is refused while the loop has an open case.

The tested hosted connector refuses loop lifecycle actions as unavailable. On that connection, stop at the stored proposal and hand the loop ID to an authorised operator. The Portal's loop page can approve, reject, pause, resume, retire, activate and demote a loop, but it has no replay; loop_replay is available only through a client that exposes act. Do not try a private endpoint or a different identity.

Observe and recover

A trigger starts a new case only while the loop has fewer open cases than budget.max_open_cases (default 1), including a case that is waiting on a person. A loop with consecutive failures also waits longer between attempts, from 30 seconds up to an hour. Read get_loop and inspect actual cases with get_case {"loop_id":"<loop id>","case_id":"<case id>"}. Identify each node's result, waits and terminal outcome. Use the supported approval card for a human wait after inspecting the exact requested work.

On failure or interruption, inspect the existing case and outputs before retrying. Use act {"action":"loop_pause","item_id":"<loop id>"} through an authorised supported lifecycle interface. Retire a disposable loop with loop_retire after reconciling open cases.

Verification boundary

This exact spec shape was accepted as proposed/shadow on a development build. Scheduled execution, owner-wait completion, retirement and donated-action integration were not proved through the tested hosted connector. A source-valid request is not a live case pass.

Related

Build your first recurring workflow with a loop · Agent interface reference