@tangle-network/agent-runtime 0.194.0 → 0.195.1

package/skills/loop-writer/SKILL.md

@@ -1,103 +1,49 @@
 ---
 name: loop-writer
-description: Write a custom control policy only when current runtime composition APIs cannot express it.
+description: Build a custom execution policy only when maintained Runtime composition cannot express it.
 ---
 
 # Loop Writer
 
-Use this only for a control policy that the shipped high-level APIs cannot express.
-Read `docs/canonical-api.md`, current exports, the implementation, and the nearest test before writing code.
-Do not copy signatures from this skill.
+Use this for a required execution policy that maintained Runtime APIs cannot express.
+Read the [current decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md), [exports](https://github.com/tangle-network/agent-runtime/blob/main/package.json), selected implementation, and nearest test.
+If an existing entrypoint fits, use it and stop.
+A wrapper that only renames inputs or outputs does not justify a custom loop.
 
-## Choose The Existing Path First
+## Define the missing behavior
 
-| Need | Existing path |
-|---|---|
-| One product chat turn | `handleChatTurn(...)` |
-| One task or bounded multi-turn task | `runAgentTask(...)` or `runAgentTaskStream(...)` |
-| Two or more actors taking turns | `defineConversation(...)` and `runConversation(...)` |
-| A driver coordinating workers | `supervise(...)` or `superviseSurface(...)` |
-| Parallel or fixed composition | `fanout(...)`, `pipeline(...)`, `panel(...)`, `verify(...)`, or `loopUntil(...)` |
-| Parallel repository workers with isolated branches | `worktreeFanout(...)` |
-| Repeated work in a graded tool environment | `runAgentic(...)` |
-| Equal-budget comparison over that environment | `runBenchmark(...)` |
-| Low-level round policy with custom planning and stopping | `runAgentRounds(...)` |
+Name the consumer, required decision, and why existing composition cannot express it.
+Reuse Runtime's execution, accounting, cancellation, questions, and recovery contracts.
+The custom policy chooses work and continuation from the task and checked prior outcomes.
+It must not introduce another scheduler or measurement system.
 
-If an existing row fits, use it and stop.
-Do not create another wrapper solely to rename inputs or results.
+Keep planning separate from consequential writes.
+The caller owns credentials, persistence, and authority; executors return observed artifacts; independent checks decide whether those artifacts satisfy the task.
+A model score cannot override failed objective checks, denied actions, or service failures.
 
-## Custom Loop Contract
+## Preserve observable state
 
-A custom loop has five explicit parts:
+Represent successful delivery, exhausted resources, cancellation, unresolved questions, execution failure, and interrupted recovery where they apply.
+Keep measurement and service errors distinct from agent failure.
+Retain task and attempt identities, artifacts, spend, and the reason for continuing or stopping.
+Resume from durable facts and reconcile uncertain writes before retrying.
 
-```text
-task -> plan work -> execute attempts -> check outcomes -> continue or stop
-```
+Steering and questions use the existing typed events and delivery records.
+Keep unanswered required questions visible.
+Parallel workers receive isolated state or an explicit shared-mutation contract.
+Children remain within parent authority and the same accounting and cancellation rules.
 
-Keep ownership separate:
+## Prove the policy
 
-- The driver chooses work and termination from task plus prior outcomes.
-- Executors run attempts and return observed artifacts.
-- Objective checks determine whether an artifact is usable.
-- Trace emission records plans, attempts, tool effects, checks, spend, and decisions.
-- The caller owns policy, budgets, credentials, persistence, and side-effect authority.
+Test the custom decision on a representative real task.
+Exercise its relevant failure and recovery paths, including rejected output followed by correction, resource exhaustion, cancellation, and duplicate-side-effect prevention.
+Use existing contract tests for unchanged Runtime behavior; add checks that distinguish the new policy.
 
-The driver must not mutate product state while planning.
-An LLM score must not override failed builds, tests, missing evidence, denied permissions, or service errors.
-
-## Required States
-
-Model every terminal and resumable state explicitly:
-
-- succeeded with the accepted artifact;
-- exhausted by rounds, tokens, money, time, or concurrency;
-- cancelled by the caller;
-- blocked on a question or permission;
-- failed before an attempt;
-- failed during execution or checking;
-- interrupted with enough durable state to resume safely.
-
-Use stable run, attempt, task, and parent IDs.
-Persist the accepted artifact, every attempted artifact identity, spend, and final reason.
-Resume from durable facts, not an in-memory counter or summary alone.
-
-## Steering And Questions
-
-Steering is a typed input to a running or replacement attempt.
-Record who sent it, why, which evidence motivated it, whether delivery succeeded, and which attempt consumed it.
-
-Questions are explicit events.
-Route them to the responsible parent or user, preserve unanswered blockers, and fail closed when a required answer is unavailable.
-Do not bury a permission request in free-form worker output.
-
-## Parallel And Recursive Work
-
-Give parallel workers isolated state unless shared mutation is the point of the task.
-For repository changes, use one worktree per worker and explicit merge outcomes.
-For external writes, use idempotency keys and product-owned transactions.
-
-Recursive supervisors use the same budget, cancellation, trace, question, and completion contracts at every depth.
-Do not grant a child more authority than its parent.
-
-## Tests
-
-Cover:
-
-- success on the first and later rounds;
-- invalid output followed by a corrected attempt;
-- every budget limit;
-- abort propagation to in-flight work;
-- service and check failures remaining distinct from agent failure;
-- unresolved blocking questions;
-- interrupted run recovery without duplicate side effects;
-- deterministic replay of decisions from saved outcomes where supported.
-
-## Completion
-
-The change is complete when the public entrypoint is smaller than the policy it replaces, all states above are observable, a real task exercises the custom behavior, and package typecheck, tests, build, docs, and package verification pass.
+Complete when the required behavior works through its public entrypoint, final and resumable states remain observable, and the relevant package and consumer checks pass.
+Report the exact missing capability supplied, retained Runtime contracts, real result, and limits.
 
 ## Then consider
 
 - `critical-audit` when the loop changes a public contract or authority boundary.
-- `eval-engineering` when the loop's stopping condition needs a new evaluation case.
-- `verify` before publishing the package.
+- `eval-engineering` when the stopping condition lacks an adequate evaluation case.
+- `verify` when implementation is complete and release checks remain.

package/skills/supervise/SKILL.md

@@ -1,110 +1,58 @@
 ---
 name: supervise
-description: Author and drive recursive AgentProfiles with durable assignments, evidence, and recovery.
+description: Author and drive recursive AgentProfiles with explicit capabilities, evidence, and recovery.
 ---
 
 # Supervise
 
 Use this when Runtime coordination tools are attached.
-Author agents that can perform the work, then drive them from checked evidence.
-
-## Keep policy in its owner
-
-Put research choices, methods, revision rules, and scientific stopping conditions in each profile's prompt.
-Runtime owns recursion depth, the shared budget, cancellation, concurrency, journals, retries, and recovery.
-
-`AgentProfile` has no `policy`, `budget`, `continuity`, `key`, or `deliverable` field.
-Pass budget, continuity, and assignment keys to `spawn_worker`.
-The caller configures the root budget and completion check in `SuperviseOptions`.
-Do not claim a limit is enforced because it appears in prompt text or metadata.
-
-## Author a descendant
-
-Write a valid `AgentProfile`, not a prose description of one.
-Use only fields the selected backend can materialize.
-
-```json
-{
-  "name": "source-skeptic-v1",
-  "description": "Challenge one candidate claim against primary evidence.",
-  "prompt": {
-    "systemPrompt": "Return a claim table with source locations, contradictions, unknowns, and a reproducible rejection check."
-  },
-  "model": {
-    "default": "<allowed-model-id>",
-    "reasoningEffort": "xhigh"
-  },
-  "tools": {
-    "agent_runtime_coordination_spawn_worker": true,
-    "agent_runtime_coordination_await_event": true
-  },
-  "resources": {
-    "failOnError": true,
-    "skills": [
-      {
-        "kind": "inline",
-        "name": "profile-authoring/SKILL.md",
-        "content": "<the complete profile-authoring skill text>"
-      }
-    ]
-  }
-}
-```
-
-The example shows placement, not required values.
-Every agent is the same `AgentProfile` shape.
-An agent becomes a recursive lead only by declaring `agent_runtime_coordination_spawn_worker: true`.
-Declare each other Runtime verb it will use, such as `await_event`, `steer_agent`, or `read_journal`.
-Runtime mounts only the declared bare verbs through its coordination surface; the provider receives a profile projection without Runtime-owned declarations.
-Metadata can describe the work, but it never grants execution authority.
-Every profile that can spawn workers carries the complete profile-authoring skill in `resources.skills`.
-Make that resource an immutable inline snapshot or a pinned reference, and set `resources.failOnError: true`.
-This is taught through the profile, not injected or enforced by Runtime: the authored profile remains the complete record of why it can delegate.
-Omit Runtime coordination tools for a leaf.
-
-The task argument names the concrete artifact and a check that can fail.
-The profile names how the agent works and which capabilities it receives.
-Together they must leave no acceptance criterion for the worker to invent.
-
-## Drive the tree
-
-1. Split the objective into independent checked artifacts.
-2. Start each new assignment with a stable semantic `key` and a deliberate per-spawn `budget`.
-3. Fill available parallel capacity while `freeSlots > 0` and distinct useful assignments remain.
-4. Pull settlements and findings with `await_event`.
-   A bounded wait returns control; it does not prove failure.
-5. Inspect a quiet or `stalled` worker with `observe_agent`.
-   Steer only when its recorded work shows a wrong path, missing requirement, or useful new evidence.
-6. Check every settled artifact before using it.
-   Feed accepted results, contradictions, and negative results into the next profile or task revision.
-7. After a refusal or failed check, preserve the attempt and author a materially changed profile or assignment.
-8. Use `continuity: 'resume'` only to continue the most recent settled worker with the same profile name.
-   A resume is a new execution and cannot carry a run-once `key`.
-9. After recovery, call `read_journal` and reconcile Runtime's restored roster, settlements, questions, findings, and spend before spawning.
-   Completed keys resolve to their committed results; do not replace them.
-
-Do not add a deadline because a worker is quiet.
-Stop research only at checked success, a declared resource limit, cancellation, or a demonstrated dead end.
+Author agents that can perform the required work, then direct them from checked evidence.
+
+## Author complete agents
+
+Put research choices, methods, revision rules, and stopping criteria in each profile's prompt.
+Runtime owns shared budgets, recursion limits, concurrency, cancellation, journals, and recovery.
+The caller configures root execution through [SuperviseOptions](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/supervise.ts).
+Per-assignment budgets, continuity, and keys belong to the [coordination tools](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts), not invented profile fields.
+
+An agent receives recursive authority by declaring `agent_runtime_coordination_spawn_worker: true` in its tools.
+Declare each other Runtime tool it needs explicitly.
+Metadata describes work; it does not grant authority.
+Every profile that can spawn workers carries the complete `profile-authoring/SKILL.md` resource, using an immutable snapshot and `resources.failOnError: true`.
+The authored profile must explain its own ability to delegate; Runtime does not invent that policy.
+
+When creating or changing a descendant profile, read [profile authoring](references/profile-authoring.md) for the exact contract and resource placement.
+The task names the concrete artifact and completion check; the profile names the method and granted capabilities.
+
+## Direct the work
+
+1. Split the objective into independent artifacts with checkable outcomes.
+2. Start each assignment with a stable semantic key and a deliberate budget.
+   Fill available capacity while distinct useful assignments remain.
+3. Pull settlements, findings, and questions with `await_event`.
+   A bounded wait returning does not establish failure.
+4. Inspect quiet or stalled workers with `observe_agent` before steering them.
+   Correct an observed wrong path, missing requirement, or new evidence.
+5. Check each returned artifact before using it.
+   Preserve failed attempts and change the profile or assignment when evidence supports another attempt.
+6. After recovery, reconcile the journal, roster, settlements, questions, findings, and spend before creating replacements.
+
+Use `continuity: 'resume'` to continue the most recent settled worker with that profile name.
+A resumed assignment is a new execution and cannot carry a run-once key.
+Completed keys resolve to committed results; an uncertain prior dispatch must be reconciled before replacement.
+Stop at checked success, an authorized resource limit, cancellation, or a demonstrated dead end.
+A quiet worker alone is not a reason to invent a deadline.
 
 ## Accept delivery
 
 Inspect the artifact and its independent completion result.
-Preserve exact profile identities, assignment keys, parent-child links, continuations, costs, failures, and unknown accounting.
-Worker prose cannot promote its own result.
-
-Use `submit_result` only when the attached completion check can validate this agent's own artifact.
-Calling `stop` ends coordination; it does not turn missing evidence into success.
-
-## Exact contracts
-
-When a field is unclear, read the owner instead of inventing it:
-
-- [`AgentProfile`](https://github.com/tangle-network/agent-sdk/blob/main/packages/agent-interface/src/agent-profile.ts) and its [exact schema](https://github.com/tangle-network/agent-sdk/blob/main/packages/agent-interface/src/profile-schema.ts) own authored fields.
-- [`spawn_worker` tool schema](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts) owns per-assignment arguments.
-- [`SuperviseOptions`](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/supervise.ts) owns root execution policy.
+Preserve profile identities, assignment keys, parent-child links, continuations, costs, failures, and missing accounting.
+Worker prose cannot approve its own result.
+Use `submit_result` only when the attached check can validate this agent's artifact.
+Calling `stop` ends coordination; it does not establish completion.
 
 ## Then consider
 
-- `build-with-agent-runtime` when a product must configure the Runtime-owned limits and adapters.
+- `build-with-agent-runtime` when the product must change Runtime limits or adapters.
 - `eval-engineering` when no existing check can separate success from failure.
-- `verify` after every required artifact passes its independent check.
+- `verify` when required artifacts pass and delivery checks remain.

package/skills/supervise/references/profile-authoring.md

@@ -0,0 +1,19 @@
+# Author a descendant profile
+
+Read the current [AgentProfile contract](https://github.com/tangle-network/agent-sdk/blob/main/packages/agent-interface/src/agent-profile.ts) and [profile schema](https://github.com/tangle-network/agent-sdk/blob/main/packages/agent-interface/src/profile-schema.ts).
+For Runtime arguments and accepted tool names, inspect the [coordination schema](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts).
+Use only fields that the selected backend can materialize.
+
+Give the profile a distinct name, a standing prompt, and the capabilities its assignment requires.
+Use model hints supported by the actual backend and the task's authorized execution configuration.
+A leaf needs no coordination grants.
+An agent that delegates declares the relevant Runtime coordination tools and receives the complete profile-authoring instructions as a skill resource.
+Use an immutable inline resource or a resolvable immutable reference with resource errors set to fail closed.
+A missing authoring resource must not silently produce a less capable worker.
+
+The profile describes how the agent works; the assignment describes the current artifact and acceptance check.
+Keep budgets, continuity mode, assignment keys, and root completion configuration in their Runtime-owned arguments.
+Do not claim a limit is enforced because prompt text asks for it.
+
+Confirm the materialized profile retains its instructions, resource bytes, and permitted tools before a large recursive run.
+Check that a child cannot gain authority beyond its parent's grant.