@tangle-network/agent-runtime 0.87.0 → 0.88.0

package/skills/loop-writer/SKILL.md

@@ -30,6 +30,7 @@ The driver owns strategy.
 | Review from several lenses | `panel` |
 | Simulated user/product eval | `defineConversation` + `runConversation` |
 | Dynamic topology / drivers of drivers | `Scope` or sandbox driver + `createCoordinationTools` |
+| **A coded multi-round loop spawned + steered like a worker** | `defineLoop` + `loopChild` (the loop atom) |
 | Mutate a shared repo | git branch/clone loop with typed merge outcomes |
 
 If a fixed combinator solves it, do not use a dynamic driver.
@@ -114,6 +115,78 @@ When the driver lives in a sandbox, expose the same verbs through
 `steer_worker`, `list_questions`, `answer_question`, `ask_parent`, `stop`, and
 optional analyst tools.
 
+## The Loop Atom — a coded loop spawned like a worker
+
+When the loop itself is the reusable unit (a research loop, a verify loop, an
+evolve loop), make it a spawnable atom instead of a hand-driver. `defineLoop`
+authors the body; the runtime owns the round ceiling, the conserved budget, the
+gate, and steer-between-rounds. A supervisor spawns / observes / steers it with
+the SAME coordination verbs as a worker.
+
+Two ways to author the round. **`agents`** — a MULTI-AGENT loop as a declarative
+CHAIN (the common case): an ordered list of named agents piped each round,
+`task -> agents[0] -> agents[1] -> ... -> out`, each agent's return feeding the next
+as `prior`. "Two agents" is self-evident from the list — no bespoke `runTwoAgent...`
+function. **`round`** — freeform code for any other topology (fan-out, dynamic
+routing). Provide exactly one.
+
+```ts
+// A two-agent research loop as a CHAIN: proposer drafts, verifier checks the draft.
+const research = defineLoop('research', {
+  maxRounds: 3,
+  agents: [
+    { name: 'proposer', run: async ({ scope, steer }, _prior) => {
+        const w = scope.spawn(researcher, { steer }, { budget: perRound, label: 'propose' })
+        if (!w.ok) throw new Error(w.reason)
+        return await scope.next()                    // the draft
+    } },
+    { name: 'verifier', run: async ({ scope }, draft) => {
+        const w = scope.spawn(verifier, { draft }, { budget: perRound, label: 'verify' })
+        if (!w.ok) throw new Error(w.reason)
+        return await scope.next()                    // the verified result -> round out
+    } },
+  ],
+  check: (out) => readinessPasses(out),              // the deployable completion oracle
+})
+
+// Spawn it exactly like a worker (role:'loop' resolves to the loop-executor).
+const r = scope.spawn(loopChild(research, journal), task, { budget, label: 'research-loop' })
+// Wire once at the top: createInMemoryRunContext({ withDriver: true, withLoop: true }).
+```
+
+TOPOLOGY: `agents` is a sequential CHAIN only. It is NOT parallel and NOT a graph —
+the loop's nested `scope.next()` is one shared queue, so parallel agents would steal
+each other's settlements. For fan-out (a panel of critics, best-of-N), dynamic
+routing, or any non-linear shape, use the freeform `round`: spawn every handle first,
+then drain N times, or branch on the data yourself. `fanout`/`panel`/`pipeline` cover
+the reactive-layer parallel case.
+
+Rules: the loop is code, not the model's judgment — that is what makes maxRounds,
+the budget, and the gate ENFORCED rather than hoped-for. Give the loop a real
+`check` (an executable oracle, never a self-judged score). Budget nests: the pool
+reserves each spawn's full ceiling until it settles, so pool > loop > per-round.
+
+### Codemode — an LLM authors the loop at runtime
+
+When the supervisor should WRITE the loop for a novel goal (not pick a hand-built
+one), use `authorLoop` — the codemode seam over the atom, the sibling of
+`authorStrategy`. It shows the model `loopAuthorContract` (the exact `defineLoop`
+module shape, exported so a skill/GEPA pass can evolve it), extracts the fenced
+module, lints it with `assertStrategyContract` (only the loops import; no
+require/eval/fetch/process/node builtins), writes it, dynamic-imports it, and
+validates the default export is a `LoopDef` — ready for `loopChild`.
+
+```ts
+const { loop } = await authorLoop({ chat, goal, maxRounds, outDir, fallbackModel })
+const spawned = scope.spawn(loopChild(loop, journal), task, { budget, label: 'authored-loop' })
+```
+
+Safety is structural, same as `authorStrategy`: the authored body can be WRONG
+but cannot overspend (conserved pool), cannot skip the check (the runtime gates
+it), and cannot reach outside the loops surface (the lint). Do not build a
+per-product loop-code generator or a VM sandbox around authored loops — `authorLoop`
+is that seam.
+
 ## Role Boundaries
 
 - **Verifier**: executable shippability gate; controls accept/reject.