@tangle-network/agent-runtime 0.194.0 → 0.195.1

package/skills/agent-graphs/SKILL.md

@@ -1,139 +1,44 @@
 ---
 name: agent-graphs
-description: Author runGraph programs from AgentProfiles and versioned prompt directives.
+description: Author fixed AgentGraph roles with explicit delegation, analysis, completion, and budgets.
 ---
 
-# Agent graphs
+# Agent Graphs
 
-Use this skill when every role is known before execution and the relationship between roles must be reviewable as data.
-The output is an `AgentGraph` executed by `runGraph`, not a new coordinator or workflow framework.
+Use `runGraph` when roles are known before execution and their relationships must be explicit Runtime data.
+Use a smaller maintained composition when it provides the required behavior.
+Use dynamic supervision when the agent must discover or create roles while working.
+A request for review alone does not require a graph.
 
-## Choose the existing entry point
+Read the current [API decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md), [AgentGraph contract](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/graph.ts), and a relevant [runnable example](https://github.com/tangle-network/agent-runtime/tree/main/examples/graphs).
+These distinguish the fixed AgentGraph API from other graph or supervision contracts.
 
-| Need | Use |
-| --- | --- |
-| Known roles with versioned work and analysis instructions | `runGraph` |
-| A standard fixed shape such as parallel attempts, a chain, or a review panel | `fanout`, `pipeline`, `verify`, or `panel` |
-| A model decides which workers to create while it works | `supervise` |
-| One profile can complete the task directly | Run that profile without composition |
+## Author the required relationships
 
-Do not force a dynamic task into a static graph.
-Do not use a graph when a smaller shipped primitive already expresses the work.
+Define the artifact and independent completion check before choosing roles.
+Give each required role a complete AgentProfile and capabilities appropriate to its task.
+Preserve requested parallel instances and independent reviewers rather than collapsing their distinct work into a root prompt.
 
-### Strict authoring decisions (Do not under-graph)
+When authoring nodes, directives, traversal limits, or analyst routes, read [the graph contract](references/authoring.md).
+The runtime validates structure and prompt references before execution.
+Keep the shared budget, per-worker allocation, concurrency, and supported limits in their actual API fields.
+Use measured execution cost when available; do not turn a prior run into a universal minimum budget.
 
-- **Cheapness is not the dialect test:** Do not bail to `single-agent` just because a brief sounds trivial (e.g., "write a one-line file"). If the brief implies roles, observers, or a specific tight budget, author the graph.
-- **Identical-Role Parallelism:** If a brief requests N parallel instances of the same role, you MUST create N distinct worker nodes and N `delegates` edges. Do not collapse identical parallel workers into a single node.
-- **Mandatory Analysts:** If a brief requires independent observation, review, or post-settle findings (e.g., "neutral decider", "review by two perspectives", "watch the worker"), you MUST author `analyzes` edges. Do not omit analysts and attempt to merge their logic into the root's prompt.
-- **Caps are not stops:** Do not use an analysis edge `maxTraversals` cap as a global stop condition. To stop after N findings, use `deliverable.check` or `maxTraversals` on a `delegates` edge.
+## Prove the graph
 
-## Author the complete contract
+Use the maintained example pattern with injected test execution to check routes, directives, traversal limits, and both successful and rejected completion.
+Then exercise the intended backend, profiles, tools, and completion check on a real representative task.
+Offline control-flow tests do not establish that a real agent solves the task.
 
-An `AgentGraph` has four required fields: `nodes`, `edges`, `deliverable`, and `budget`.
-`runGraph(graph, options)` validates graph structure and prompt references before it spends compute.
+Inspect the terminal result, complete cost and token accounting, edge delivery records, exhausted edges, and journal evidence.
+An expected edge with zero traversals did not exercise its intended relationship.
+Unknown usage is missing evidence, not zero cost.
+A passing check proves only the outcome it actually tests.
 
-### Nodes
-
-Each node is `{ id, profile }`, where `profile` is a complete canonical `AgentProfile`.
-Set `profile.name` equal to `id` because Runtime uses that value to select and route the node.
-Put the standing role in `profile.prompt.systemPrompt` and capabilities in the profile's tools, MCP, resources, hooks, and subagents.
-Do not rebuild profile materialization in graph code.
-
-### Delegation edges
-
-A delegation edge is `{ kind: 'delegates', from, to, directive, maxTraversals? }`.
-The directive is a registered, versioned `PromptHandle`, such as `promptHandle('delegates/research-brief/v1')`.
-Each spawn and each later steer over the same edge consumes one traversal.
-The default cap is `defaultEdgeTraversalCap`; exhaustion refuses further delegation.
-
-The current graph form has one root and a static set of worker nodes.
-Every delegation edge starts at the root, and each worker has exactly one incoming delegation edge.
-Use a new directive version to change a brief instead of adding a second edge to the same worker.
-
-### Analysis edges
-
-An analysis edge is `{ kind: 'analyzes', analyst, over, to, directive, maxTraversals? }`.
-It runs after a listed worker settles and routes findings to one node.
-
-`analyst` has two supported forms:
-
-- A lens id from `options.analysts` runs a caller-supplied analysis function.
-- A graph node id runs that node's pinned `AgentProfile` as a tool-equipped analyst.
-
-An analyst node has no incoming delegation edge, so the root cannot hand it ordinary work.
-An id cannot be both a registered lens and an analyst node.
-`over` lists delegated worker nodes only; Runtime refuses the root and analyst nodes because neither settles as an ordinary worker.
-An analysis traversal cap records excess findings as `unpropagated`; it does not stop the run.
-
-### Completion and budget
-
-`deliverable.check(output)` is the independent completion test.
-It must accept a genuinely complete result and reject junk.
-Put the concrete mission in `deliverable.describe`; Runtime uses that text as the root's task.
-
-`budget` is one conserved pool for the full graph.
-Set `options.perWorker` explicitly from the actual executor cost.
-Size each allocation from measurements of the actual profile, mounted context, tools, and task shape when those measurements exist.
-Do not turn one run's cumulative spend into a universal harness minimum; Runtime enforces the caller's conserved pool, not guessed per-harness floors.
-Analyst nodes spend from the same pool and need the same honest accounting as ordinary workers.
-
-## Authoring procedure
-
-1. **Classify correctly:** Verify if this needs `single-agent`, `dynamic-workflow`, or a static `runGraph`. If independent review or parallel workers are requested, use `runGraph`.
-2. **Define completion first:** Write the completion test and its description.
-3. **Select entry point:** Choose the smallest shipped entry point from the table above.
-4. **Define Roles:** Give every distinct role one complete `AgentProfile`. If N parallel instances of a role are requested, create N nodes. Merge roles only if their standing prompts and capabilities are identical.
-5. **Register directives:** Register a versioned directive for every edge.
-6. **Delegate work:** Add one delegation edge per ordinary worker from the root.
-7. **Attach analysts:** Add `analyzes` edges only when findings must be produced independently after a worker settles. Do not skip this if the brief asked for a watcher/reviewer.
-8. **Size the pool:** Set budget, per-worker allocation, traversal caps, time, and concurrency from comparable measured runs when available.
-9. **Prove and inspect:** Run the structure offline, then run the real backend and inspect its result.
-
-## Prove the graph before spending
-
-Use an injected `brain` plus `makeWorkerAgent` to exercise graph structure without a network call.
-Cover invalid profiles, unknown directives, impossible analysis routes, traversal exhaustion, successful completion, and rejected junk.
-Start from the runnable programs in `examples/graphs/` rather than creating a second graph runner.
-
-Offline execution proves control flow only.
-A real task must still use the intended backend, profiles, tools, completion test, and budget before claiming the graph solves that task.
-
-## Read the complete result
-
-| Field | Meaning |
-| --- | --- |
-| `result.result.kind` and `reason` | Whether a result won and why execution ended |
-| `result.result.spentTotal` | Tokens and money, including whether each total is known |
-| `result.ledger` | Every delivered, stripped, empty, or unpropagated edge traversal with byte counts |
-| `result.exhaustedEdges` | Every edge whose cap was reached, including normal lifecycle endings |
-| Journal `edge` events | Durable copies of traversal evidence |
-
-Zero traversals on an expected edge means the graph did not exercise that relationship.
-`usdKnown: false` means cost is missing, not free.
-A passing completion test proves only what that test checks.
-
-## Common mistakes
-
-- Bailing to `single-agent` because a brief sounds trivial, instead of respecting requested roles.
-- Collapsing N requested parallel identical roles into a single worker node.
-- Skipping `analyzes` edges when an observer or reviewer is explicitly requested.
-- Putting the task only in a spawn prompt instead of `deliverable.describe`.
-- Giving a node a `profile.name` different from its id.
-- Delegating ordinary work to an analyst node.
-- Listing the root or an analyst node in `analyzes.over`.
-- Using an analysis cap as a stop condition.
-- Allowing a driver-authored spawn profile to add capabilities instead of defining them on the pinned node profile.
-- Reading only thrown cap errors and missing `result.exhaustedEdges` on budget or cancellation endings.
-- Treating unknown spend as zero.
-- Claiming recursive or runtime-discovered structure when the current graph is a static root with workers and analysts.
-
-## Improve only after measurement
-
-Runtime already optimizes one inline skill through `improve(profile, { surface: 'skills', skills: { resourceName }, ... })`.
-Put the exact skill bytes in `profile.resources.skills`, set `profile.resources.failOnError: true`, supply disjoint development and final-test tasks, and pass a complete Agent Eval optimization method.
-Do not create a graph-specific optimizer, campaign runner, candidate store, or promotion path.
+When measuring a proposed change to this skill, read [measurement](references/measurement.md) before reusing its historical cases or results.
+Ordinary graph construction does not require an optimization campaign.
 
 ## Then consider
 
-- `loop-writer` when the required dynamic structure still cannot be expressed by `supervise` or another shipped primitive; pass the exact missing behavior and the completion test.
-- `verify` before publishing a graph consumer; pass the real backend command, expected result fields, and failure cases.
+- `loop-writer` when a required dynamic policy cannot be expressed through existing Runtime APIs.
+- `verify` when the real task works and publishing or consumer integration checks remain.

package/skills/agent-graphs/references/authoring.md

@@ -0,0 +1,34 @@
+# AgentGraph authoring contract
+
+Use the current [graph types and validation](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/graph.ts) for exact fields.
+Start from a matching [example](https://github.com/tangle-network/agent-runtime/tree/main/examples/graphs) rather than copying a second graph runner.
+
+## Nodes and work
+
+AgentGraph requires nodes, edges, a deliverable, and a shared budget.
+Each node holds an id and a canonical AgentProfile; its profile name matches the node id for routing.
+Standing roles belong in the profile prompt, with explicit tools and resources.
+Put the concrete mission in the deliverable description and supply an independent completion check that rejects incomplete output.
+
+## Edges
+
+Delegation edges carry work from the root to a worker through registered prompt references.
+A worker has one incoming delegation edge in this fixed graph form.
+Keep the exact directive identity so recorded delivery can be traced to the text the worker received.
+Spawns and steers consume delegation traversals; inspect exhaustion rather than assuming all requested work ran.
+
+Analysis edges run after listed workers settle and route findings to their configured recipient.
+The analyst is either a registered analysis function or a graph node with a complete profile.
+An analyst node receives no ordinary delegation, and its id cannot also name a registered analysis function.
+Analysis targets list delegated workers, not the root or other analysts.
+
+Analysis traversal caps limit propagated findings; they do not stop the whole run.
+Use the deliverable check or an appropriate execution limit to terminate work.
+Analyst execution consumes the same shared budget as other workers.
+
+## Check the result
+
+Inspect delivered, stripped, empty, and unpropagated edge records and their byte counts.
+Read exhausted edges even when execution ended through completion, budget, or cancellation rather than a thrown error.
+Check journal records when recovery or auditability is part of the task.
+Preserve run, profile, directive, and artifact identity so a resumed or measured run cannot silently change its inputs.

package/skills/agent-graphs/references/measurement.md

@@ -0,0 +1,18 @@
+# Measuring changes to graph-authoring guidance
+
+The [case files](../cases) and [generation records](../generations) preserve previous experiments.
+Read their recorded limitations before reuse; historical scores do not describe the current skill or API.
+The generation records include an invalidated result and its reasons.
+
+Use the current Runtime improvement API and a complete Eval method.
+For the shared search and activation constraints, read [improvement and activation](../../build-with-agent-runtime/references/improvement.md).
+Deliver the exact candidate skill resource to the authoring agent and retain its identity in the run evidence.
+
+Check authored graph behavior through the actual graph implementation.
+A case should distinguish the required relationship and reject a plausible wrong graph, not reward preferred words or unnecessary graph complexity.
+Keep cases used to revise the skill separate from final decision cases.
+If a reference is conditionally required by the skill, make it reachable in the measured resource package and inspect whether it was read.
+
+Use real execution evidence when claiming improvement on a real backend.
+Offline graph execution tests structure only; it cannot establish agent quality, deployed reliability, or paid execution cost.
+Keep invalidated results as evidence without promoting their conclusions.

package/skills/build-with-agent-runtime/SKILL.md

@@ -1,136 +1,50 @@
 ---
 name: build-with-agent-runtime
-description: Choose and compose current runtime, eval, knowledge, and interface APIs before adding wrappers.
+description: Choose maintained runtime APIs and compose execution, evaluation, and controlled improvement.
 ---
 
-# Build with agent-runtime
+# Build with Agent Runtime
 
-Use this skill before writing product-local agent infrastructure.
-The goal is one portable agent definition, one execution path, one measurement system, and one reviewed activation path.
+Build on the maintained execution path while keeping product policy and storage in the consumer.
+Read the current [API decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md) and [package exports](https://github.com/tangle-network/agent-runtime/blob/main/package.json).
+Follow the chosen entrypoint to its implementation and nearest runnable example.
+For an existing consumer, confirm the actual installed package supports the chosen contract.
 
-## Read first
+## Choose by the required outcome
 
-1. Read `docs/canonical-api.md` for the current decision table.
-2. Check exports in `src/index.ts`, `src/runtime/index.ts`, `src/improvement/index.ts`, `src/intelligence/index.ts`, and `src/knowledge/index.ts`.
-3. Read the nearest runnable example.
-4. Treat source as authoritative when docs disagree, then correct the stale doc in the same change.
-
-## Ownership
+Use the existing entrypoint for one turn, a bounded task, fixed composition, dynamic supervision, or a measured improvement.
+Avoid copying the API catalog into product code or creating a wrapper that only renames it.
 
 | Concern | Owner |
 |---|---|
-| Portable prompt, skills, tools, MCP, hooks, subagents, model hints | `AgentProfile` from `@tangle-network/agent-interface` |
-| Agent execution, supervision, budgets, streaming, candidate execution | `@tangle-network/agent-runtime` |
-| Tasks, graders, search, paired statistics, cost and latency comparison | `@tangle-network/agent-eval` |
-| Sources, retrieval, citations, freshness, memory adapters, knowledge promotion | `@tangle-network/agent-knowledge` |
-| Product records, permissions, funding, UI, and atomic storage writes | The consuming product |
-
-Do not move shared measurement into Runtime or product code.
-Do not move product storage transactions into a provider-neutral package.
-
-## Choose the entry point
-
-| Need | Use |
-|---|---|
-| One product chat turn | `handleChatTurn(...)` |
-| One normalized streamed agent turn | `streamAgentTurn(...)` and `collectAgentTurn(...)` |
-| One task or multi-turn loop | `runAgentTask(...)`, `runAgentTaskStream(...)`, or `runAgentRounds(...)` |
-| Supervisor and workers | `supervise(...)` or `superviseSurface(...)` |
-| Static roles with versioned delegation and analysis directives | `runGraph(...)` |
-| Parallel work with a shared budget | `fanout(...)` |
-| Fixed composition | `pipeline(...)`, `panel(...)`, or `verify(...)` |
-| Product benchmark | `defineLeaderboard(...)` |
-| Profile matrix | `expandProfileAxes(...)` and `runProfileMatrix(...)` from agent-eval |
-| Search one agent surface | `improve(...)` |
-| Analyze traces through a measured proposal | `proposeAgentImprovement(...)` |
-| Review and authorize an exact proposal | `reviewAgentImprovementProposal(...)` and `createAgentImprovementActivation(...)` |
-| Apply or restore an approved candidate | `executeAgentImprovementActivation(...)` with a product transaction |
-| Build a knowledge candidate | `runKnowledgeImprovementJob(...)` |
-| Apply a knowledge candidate | `createKnowledgeImprovementActivationExecutor(...)` through the same activation path |
-| Observe and pull approved changes on a live agent | `withIntelligence(...)` |
-
-## Improvement flow
-
-`improve(profile, options)` searches one surface and returns a detached winner.
-It never changes a profile, document, repository, memory store, or knowledge base.
-
-For a profile field, pass one complete agent-eval `OptimizationMethod`, explicit train, selection, and final-test partitions, judges, and the candidate execution function.
-Use `officialGepa(...)` with an explicit recipe when upstream GEPA should own search.
-Use `officialSkillOpt(...)` when Microsoft's SkillOpt should own search.
-Both require `evaluationId`; change it whenever dispatch, judges, models, or scoring behavior changes.
-Resumable runs accept `never`, `if-compatible`, or `required` and reuse state only when agent-eval derives the same run identity.
-Runtime has no local prompt, skill, memory, or profile optimizer fallback.
-Code uses Runtime's isolated worktrees and returns a sealed patch candidate.
-Knowledge uses `runKnowledgeImprovementJob(...)` and returns paired snapshots.
-
-Use `proposeAgentImprovement(...)` for a production proposal.
-It performs these steps in order:
-
-1. Analyze completed traces.
-2. Search for a candidate on development tasks.
-3. Build the frozen baseline, candidate, and held-back work.
-4. Return only baseline, candidate, held-back tasks, and policy; Runtime adds the optimizer ancestry and seals the final experiment.
-5. Reject the experiment if its candidate differs from the search winner.
-6. Run baseline and candidate on the same held-back tasks.
-7. Produce findings, confidence intervals, quality, cost, latency, and a decision.
-
-After a person or tenant policy approves the proposal, call `createAgentImprovementActivation(...)` with target identities, funding owner, authority, intent, and expiry.
-Runtime derives the expected current digests from the measured experiment.
-Call `executeAgentImprovementActivation(...)` with one product-owned transaction that compares current state, writes every target atomically, and stores the result under the activation digest.
-Pass a read-only reconciliation function so retries can distinguish committed, uncommitted, and uncertain outcomes.
-
-Never apply a change from analyst confidence alone.
-Never measure one candidate and apply another.
-Never let search code write live state.
-Never treat a lost response as a failed write without reconciling it.
-
-## Surface rules
-
-- Prompt changes `profile.prompt` only and requires a complete method.
-- Skill optimization selects one inline skill by `skills.resourceName`, requires a complete method, and requires profile resources to fail closed.
-- Curated memory changes `profile.resources.instructions`; retrieval stores and memory databases belong in the knowledge flow.
-- Tools, MCP, hooks, subagents, curated memory, rollout policy, and whole-profile changes require a complete method.
-- Code candidates must come from the Runtime worktree path so patch identity and cleanup stay intact.
-- Workflow files are code surfaces. Parameter sweeps belong in a complete agent-eval method.
-- Knowledge candidates remain detached until the shared activation path applies or restores their frozen snapshots.
-
-## Product integration
-
-The product supplies only the pieces that vary by deployment:
+| Portable prompt, skills, tools, MCP, hooks, and model hints | AgentProfile from agent-interface |
+| Execution, supervision, budgets, streaming, and candidate execution | Agent-runtime |
+| Cases, grading, search, statistics, and comparison | Agent-eval |
+| Retrieval, citations, freshness, memory stores, and knowledge promotion | Agent-knowledge |
+| Users, permissions, funding, UI, persistence, and atomic writes | The product |
 
-- How traces and current profiles are loaded.
-- How exact candidate execution is placed on compute.
-- How proposal, review, activation, and result records are persisted.
-- How a target is changed atomically.
-- Who may approve, reject, request changes, fund, apply, or restore.
-- How those records and actions appear in the UI or API.
+Keep measurement in Eval and product storage transactions in the consumer.
+Use the same agent definition and execution path in the product and its evaluation.
 
-The product must not recreate candidate hashing, paired comparison, confidence intervals, review binding, expiry, retry identity, or result validation.
+## Integrate the selected capability
 
-## Do not duplicate
+Search for the existing product adapter and current package usage before adding infrastructure.
+Supply only the policy, storage, credential, and execution-placement boundaries the consumer needs.
+Preserve explicit failures, cost and usage capture, cancellation, and recovery behavior.
 
-- Do not write a provider-specific profile wrapper; extend `AgentProfile` and its materializer.
-- Do not write a second optimizer loop; pass a complete agent-eval method to `improve(...)`.
-- Do not use Runtime's code generator to approximate GEPA, SkillOpt, or another upstream profile optimizer.
-- Do not write a second candidate catalog; persist the immutable proposal records.
-- Do not let an analyst or adapter commit, push, open a pull request, or edit a live store.
-- Do not hand-roll SSE parsing, usage totals, profile matrices, bootstrap statistics, sandbox acquisition, or worktree cleanup.
-- Do not attach completed Runtime totals to an Eval campaign. Use `loopDispatch` or `loopCampaignDispatch` so admission and receipt capture surround the paid work.
-- Do not add a product-local approval format for knowledge, code, or profile changes.
+When changing prompts, skills, code, or knowledge through measured search, read [improvement and activation](references/improvement.md) before implementing that path.
+Ordinary execution work does not need an optimizer or activation workflow.
 
-## Finish
+## Prove the integration
 
-- The same agent definition runs in product and measurement paths.
-- The held-back tasks were not visible during search.
-- Candidate identity is checked before execution and again before activation.
-- Quality, cost, latency, sample count, and uncertainty are retained.
-- Rejection and request-changes are first-class outcomes.
-- Activation is authorized, expiring, idempotent, and reconcilable.
-- No customer write, message, trigger, or billing occurs in read-only proof mode.
-- Public examples, package exports, generated API docs, type checks, tests, build, and package verification pass.
+Run a real task through the selected backend and inspect its result and execution evidence.
+Test the changed contract's denial, failure, cancellation, or recovery cases as applicable.
+An in-process test proves only its own path; it does not prove a deployed sandbox path.
+Run the repository's required checks, public-import checks when exports change, and the consumer's affected flow.
+Report retained product adapters, adopted exports, observable results, and unchecked boundaries.
 
 ## Then consider
 
-- Use `build-with-agent-knowledge` when agents should improve retrieval, memory, or a knowledge base.
-- Use `critical-audit` when the change introduces or alters a public contract.
-- Use `verify` before publishing or adopting the package in a product.
+- `build-with-agent-knowledge` when the remaining work concerns retrieval or memory integration.
+- `critical-audit` when a changed public contract needs independent review.
+- `verify` when implementation is complete and release checks remain.

package/skills/build-with-agent-runtime/references/improvement.md

@@ -0,0 +1,32 @@
+# Measured improvement and activation
+
+Read the current [improvement exports](https://github.com/tangle-network/agent-runtime/blob/main/src/improvement/index.ts), [intelligence exports](https://github.com/tangle-network/agent-runtime/blob/main/src/intelligence/index.ts), and relevant sections of the [API decision table](https://github.com/tangle-network/agent-runtime/blob/main/docs/canonical-api.md).
+For knowledge changes, also read the [knowledge exports](https://github.com/tangle-network/agent-runtime/blob/main/src/knowledge/index.ts).
+Use the selected function's current types and maintained example rather than copying a method signature from this guide.
+
+## Search without changing the live system
+
+Use the existing improvement API and a complete Eval optimization method for the chosen surface.
+Keep development, selection, and final decision cases separate.
+Record the delivered profile resources and execution identity so resumed work cannot silently reuse incompatible measurements.
+Search returns a detached candidate; it cannot edit the live product, knowledge store, or repository.
+
+Prompt, tool, resource, and profile changes remain portable profile data.
+Code candidates use Runtime's isolated worktree and patch identity path.
+Knowledge candidates use the existing snapshot and promotion contract.
+Do not rebuild candidate hashing, statistics, or search history in the consumer.
+
+## Apply only the measured candidate
+
+Use the maintained proposal, review, and activation path.
+The proposal must compare the unchanged baseline and exact candidate on tasks hidden during search.
+Keep candidate identity checked before execution and before activation.
+Retain quality, cost, latency, sample count, uncertainty, and rejected outcomes.
+
+The product supplies authority, funding, target identities, persistence, and an atomic transaction.
+That transaction compares expected current state, writes the authorized targets, and records the activation outcome under its retry identity.
+Use read-only reconciliation to distinguish committed, uncommitted, and uncertain outcomes after a lost response.
+Preserve expiry and authority checks; review evidence does not itself grant write authority.
+
+Prove rejection, successful activation, expired or mismatched activation, and retry after an uncertain write.
+A read-only experiment must not send customer messages, mutate customer data, or incur product billing side effects.

package/skills/codemode/SKILL.md

@@ -1,49 +1,37 @@
 ---
 name: codemode
-description: Batch mechanical tool work as one program so loops and intermediates stay out of context.
+description: Batch mechanical tool work in code while preserving judgment, authorization, and accounting.
 ---
 
 # Codemode
 
-Use this policy when a task needs three or more mechanical tool or command calls whose intermediate results need no judgment.
-One call per model turn spends a round trip per step and pushes every intermediate value through the context window.
-Write one program instead: the loop, the branch, and the intermediates stay in the program, and only the decision-relevant summary returns.
+Batch stretches of mechanical tool work whose intermediate results require no judgment.
+Keep decisions that could change the plan in the agent's turn.
 
-This is the pattern the ecosystem calls code mode (Cloudflare's Code Mode, Anthropic's code execution with MCP, the CodeAct paper).
-In a coding harness you already have the whole capability: a shell, a filesystem, and the tools this profile grants.
+## Batch the work
 
-## Run The Work
+Identify independent calls and the points where an observed result must change the next action.
+Use the session's permitted execution tool to hold intermediate data in variables or workspace files.
+Return the decision-relevant values, failures, and artifact locations.
+Inspect every result; a successful batch must not hide a failed item.
+Retain results needed later instead of rerunning expensive work to recover them.
 
-1. List the calls the task needs and mark which results require your judgment.
-2. Put every judgment-free stretch into one script; keep each judgment point in your own turn.
-3. Hold intermediates in variables or files inside the workspace, never in your reply.
-4. Make the script print only the decision-relevant summary: counts, failures, the final value.
-5. Prefer one script that fans out over N items to N separate tool calls with identical shape.
-6. Stop batching the moment a result changes what you would do next; read it, decide, then batch again.
+Respect each tool's concurrency, cancellation, and authorization contract.
+A batch does not expand the permission of its individual operations.
+Meter paid operations on the owning execution path and preserve their usage records.
+Keep dependent actions sequential unless their contract supports safe composition.
 
-## Boundaries That Are Not Yours To Move
+## Runtime-supervised code
 
-Code may spawn or steer only through Runtime-provided API bindings such as `api.spawn_worker`.
-Never reach coordination verbs over HTTP or create a second scheduler; that bypasses the budget pool and journal.
-An operation that costs money must run where the runtime meters it; do not wrap metered work in a script that hides the spend.
-The lint on authored code refuses imports, `process`, and network access; it is a lint, not a sandbox, so treat generated code you did not review as untrusted.
+When configuring code execution for a Runtime supervisor, read [the execution boundary](references/runtime-execution.md).
+That branch supplies a generated API over Runtime's existing coordination tools and requires an explicit runner.
+For ordinary shell or session-tool batching, no additional runtime is needed.
 
-## Router-Brained Supervisors
-
-A raw chat model has no shell, so give it the runtime's code mode: pass `codeModeSupervisorTools()` as `resolveSupervisorTools` and the supervisor's tool surface becomes `search` and `execute`.
-`search` answers a TypeScript API generated from the live coordination grant; `execute` runs the model's program through a caller-supplied runner, and every `api.spawn_worker` call crosses the kernel's pool, authorization, and journal.
-Supply a jailed runner for an untrusted model: the in-process runner is not an isolation boundary.
-The lifecycle verbs (`submit_result`, `stop`, `ask_parent`) stay model tools: the program does the mechanics, the model keeps the judgment.
-
-## Common Mistakes
-
-- Batching a step whose output should have changed your plan, then discovering it three steps later.
-- Printing a whole dataset into the reply instead of writing it to a file and printing the summary.
-- Re-running an expensive script to re-read a value the first run already produced; write results to files.
-- Moving supervision into a script because the coordination verbs are reachable over local HTTP.
+Complete the requested work and inspect the resulting artifact.
+Code reduces mechanical round trips; it does not replace judgment or prove the quality of the result.
 
 ## Then consider
 
-- `supervise` when the batched work is really delegation to workers with their own judgment.
-- `agent-graphs` when the shape of the work is a fixed topology rather than one agent's loop.
-- `loop-writer` when no shipped composition API can express the control policy you need.
+- `supervise` when the work needs workers with their own judgment.
+- `agent-graphs` when fixed roles require explicit Runtime relationships and shared accounting.
+- `loop-writer` when no maintained composition expresses the required control policy.

package/skills/codemode/references/runtime-execution.md

@@ -0,0 +1,14 @@
+# Runtime code execution boundary
+
+Read [code-mode implementation and types](https://github.com/tangle-network/agent-runtime/blob/main/src/runtime/supervise/code-mode.ts) and its [contract tests](https://github.com/tangle-network/agent-runtime/blob/main/tests/kernel/code-mode.test.ts).
+Use `codeModeSupervisorTools(runner)` with an explicit `CodeModeRunner`; there is no default runner.
+For untrusted model output, supply a real isolated execution environment.
+The in-process runner and source lint are not security boundaries.
+
+The generated API follows the live coordination grant.
+Code can spawn or steer through Runtime-provided bindings such as `api.spawn_worker`; these retain authorization, shared budgets, and journal records.
+Direct coordination requests over HTTP or a second scheduler bypass that contract.
+
+Lifecycle decisions remain model tools: `submit_result`, `stop`, and `ask_parent` are outside the generated code API.
+Keep judgment in the model and mechanics in the program.
+Before broad use, exercise one allowed call, one denied call, a failed operation, and cancellation through the selected runner.

package/skills/generate-eval/SKILL.md

@@ -13,8 +13,9 @@ Do not use it for general coding quality or subjective output.
 - `TARGET`: a pinned package version, repository commit, or release.
 - `OUT`: the path for one candidate JSON object.
 
-Read `bench/src/generate-eval/schema.ts` and `bench/src/generate-eval/certify.ts` before authoring the candidate.
+Read the current [candidate schema](https://github.com/tangle-network/agent-runtime/blob/main/bench/src/generate-eval/schema.ts) and [execution checks](https://github.com/tangle-network/agent-runtime/blob/main/bench/src/generate-eval/certify.ts) before authoring the candidate.
 Those files define the current format and checks.
+Use a maintained target for new cases, then freeze its exact identity so later runs compare the same behavior.
 
 ## Build One Case