@tangle-network/agent-runtime 6.0.8 → 8.0.0

package/CHANGELOG.md

@@ -1,3 +1,89 @@
+## 8.0.0
+
+`ProfileMaterializationReceipt` now requires `resources` when `status` is `known`. Consumers that construct these receipts must provide `MaterializedResources`: the observed resource values and their provenance, or `{ status: 'unknown', reason: '...' }` when no resource observation is available.
+
+## 7.0.5
+
+A control poll reads only new steer, cancel, and spawn-journal bytes. A quiet poll no longer rereads every worker and the whole journal.
+
+Preserve SearchSpec flow admission when its compiler supplies continuation options, including the original gate and root-driver refusals.
+
+## 7.0.4
+
+Authored and stored graphs retain an explicit portable continuation policy for harness-driven roots, including checked replay and content identity.
+
+## 7.0.3
+
+7.0.1 failed its Publish typecheck (#2475) and 7.0.2 failed the qualify suite: the `graph-check-nodes` assertion lacked the `secrets` that #2469 declared. The runtime code of 7.0.2 ships unchanged.
+
+## 7.0.2
+
+Graph check nodes in boxes run in the run owner's account: `RunGraphOptions.checkPlacement` is a `GraphCheckPlacement` whose `builderAccounts` is optional, the cross-account refusal stays with declared-check judges, secrets resolve only from the placement `env` (a record, or an async resolver called before each box run), and a check node's optional `resources` size a box with a durable home. Every resolved secret value in a check node's output becomes `[redacted:NAME]` before it reaches the receipt, the run's output or downstream `$GRAPH_EVIDENCE`.
+
+- `agent-runtime-mcp` serves a run directory's committed root stream through the `events_*` tools when `MCP_ENABLE_EVENTS=1` and `AGENT_RUNTIME_EVENTS_ROOT_STREAM=<runDir>`: the sequence is the line's own `seq`, which continues across drive attempts and processes, each record carries its `attempt`, a torn tail is never served, and the digest chain lets an observer detect rewritten history at its cursor. Removes the internal `submitAgentImprovementProposal` body left behind when its export was removed.
+
+## 7.0.1
+
+An unjudged check tells a barren root to end its turn. Own long work still waits inside the turn.
+
+A subscription seat with no receipt stays unpriced. No catalog estimate is written onto it.
+
+A provider root woken into a new harness session in its retained environment keeps its coordination tools. The environment is reloaded by id, and that handle holds none of the create input that carried the runtime MCP attachments, so a turn into a continued environment now restates the create-time `runtimeAttachments.mcp`.
+
+Materialization receipts now record the applied box sizes (`resources`) the created environment reported through its observation — with provenance (`origin`, `observedAt`) — or an explicit unknown naming why, never the create request. Bridge spawn admission reads the host executor's capacity gate from `GET /health` when the bridge reports it, so a spawn that would wait on the host semaphore and die as capacity is refused up front with the counters in the signal. Spawn admission settles exactly once, and provider `environmentReader` documents sidecar handling.
+
+A cancelled run stops starting checkpoint deletes, lookups, and capture-fork cleanup when its signal aborts.
+
+A retained run whose harness was SIGKILLed releases that execution before the next dispatch, so the replacement is admitted.
+
+Flow graphs gain check nodes (`{ id, check: { command, timeoutMs?, environment?, egress?, secrets? } }`): Runtime runs the command instead of an agent and settles `{ pass, exitCode, output, json }`, with evidence at `$GRAPH_EVIDENCE/<nodeId>.json`, journaled receipts, and box placement through `RunGraphOptions.checkPlacement`. Graph files and stored graphs gain `workspace: cwd | fresh`, resolved by `graphWorkspace`.
+
+Retained native inventory digests written as bare hex are admitted (runs no longer skip every file as unverifiable), and a root stream receipt now carries `subagentSessionIds`, the subagent sessions the harness's own `task` tool results named (#1264).
+
+A retained owner keeps its box when the final native session copy is incomplete (`nativeStore` not complete, or an `over_bound:` / `store_file_` reason) and journals `environment-teardown` with `destroyed: false` and that reason. Process I/O or event-log gaps alone still allow release to destroy the box.
+
+A retained run that stays at intent past the materialization bound fails with that stage instead of retrying the create with no environment.
+
+- `spawn_worker` accepts an optional `resources` request (`cpu`, `memoryMb`, `diskMb`, `gpu`) that sizes a provider worker's create over `defaults.resources`; the provider backend's `maxWorkerResources` is the ceiling, and a request above it (or with no ceiling) is refused before any create, naming the ceiling (#1277).
+- `fileEscalateQuestion(runDir, runId)` writes each `ask_parent` question to `questions/<id>.json` under the run, so an out-of-process observer can read it and answer with a root `writeWorkerSteer` (#1165).
+
+- `spawn_worker` admits `successorOf` for a worker that is still live, so a director that revises a stalled worker keeps the lineage on the `spawned` event; `successor-live` is no longer a refusal (#1588).
+- An AgentGraph `delegates` edge may start at any node that holds the spawn tool: the nested supervisor spawns only its own edges' targets, and the ledger row records the real `from` (#1774).
+- A buffered Router completion whose usage reports no cost takes the exact `x-tangle-cost-usd` charge, so router workers settle with known USD; a router-tools graph worker may declare the caller tools its backend supplies (`AgentProfile.tools`) (#1587).
+- A graph analyst node on a backend is no longer graded by the worker's deliverable check or the backend `validator`: an analyst that attacks the worker's output settles ungraded (#1775).
+- A manager whose profile declares coordination tools the run does not serve is refused with every unserved name, and the served list, in one error before its harness runs a turn (#1219).
+
+A settled record's `tree` and `spendGaps` read the whole spawn forest, so a nested driver's grandchildren appear in `tree.nodes` and stay nameable in `spendGaps` (`#1189`).
+
+- `scope.spawn` refuses a not-yet-executable profile with every missing field named in one rejection (`harness`, `model.default`, `model.provider`) instead of one field per call, and the `spawn_worker` tool description states the required execution fields (#1329).
+- A retained-run read that receives a gateway HTML error page (a Cloudflare 502) is classified as a transport failure carrying the HTTP status and a bounded excerpt, not a provider contract violation (#1203).
+- Driver-attempt records carry the deepest cause's redacted, frame-bounded stack, so a failure the messages alone cannot place still names its throw site; redaction runs per line, so a credential on the message line cannot erase the frames (#2347).
+- An unconfirmed checkpoint cleanup journals and settles with its reason — the provider's acknowledgement status or the delete's error text (#1594).
+
+A broken stream keeps the tokens its live events carried and the remainder that arrived only on the exact result. The iteration count stays the provider invocation and is marked unknown when that remainder is non-zero.
+
+The live graph viewer keeps serving when the host has no inotify watches left (ENOSPC) instead of ending the run it views; it falls back to its reconcile interval.
+
+A retained worker whose provider returns a different session settles down and keeps its environment, so the same key can be replaced with spawn_worker.
+
+## 7.0.0
+
+`reconcileUnconfirmedTeardowns` reads a settled run's unconfirmed environments by id and deletes only the ones the provider still holds. It returns confirmed, deleted, and unknown sets, and it refuses a live directory lock or a run with no settle record.
+
+Record usable token lower bounds with explicit unknown-attempt counts, requested models and observed provider models. The settle reader can project usage from preserved journals without rewriting the sealed result.
+
+CoordinationEvent includes the tool-timing event. Consumers with exhaustive coordination event switches must handle this variant. SupervisedResult retains its established union arms and adds optional measured usage; requested models and token lower bounds are available without guessing missing receipts.
+
+Keep conservative budget reservations out of terminal measured usage and validate settlement receipts and totals before publication. Missing usage and provider identity remain explicitly unknown.
+
+`agent-runtime-top` tells an empty workspace how to open a supervise run directory: `--web --root` on the directory that holds `observer.jsonl` or `spawn-journal.jsonl`.
+
+## Unreleased
+
+`profileChatClient` and `profileOptimizerModelCall` forward optional caller request headers on every Router turn. Runtime's content-type, authorization, idempotency-key, and x-correlation-id keep precedence.
+
+Every coordination tool call records server receive time, handler duration, and response size as a record-only `tool-timing` row in the coordination log.
+
 ## 6.0.8
 
 Preserve identity discovery from historical partial events while validating full event identities atomically in the public journal reader.

package/README.md

@@ -27,9 +27,21 @@ pnpm add @tangle-network/agent-runtime @tangle-network/agent-eval @tangle-networ
 
 Runtime keeps compact integration fixtures. Research questions and preregistrations belong in Discovery; reproducibility campaigns and long-horizon value evidence belong in Discovery Lab.
 
-## Quickstart: one exact offline run
+## Start here
 
-This is [`examples/quickstart/minimal.ts`](./examples/quickstart/minimal.ts). It runs without credentials.
+First adoption is one exact run with a result and an identity, then the coordinator you already have.
+
+The scripted quickstart below is that run: a scripted model, no credentials, and a printed decision. A real model is [`examples/delegate`](./examples/delegate), which exits until a router key is set. Durable storage is [`examples/runtime-run`](./examples/runtime-run) through the store adapter you pass; the checked example's adapter is in-process. Provider-owned durability is [`examples/retained-run`](./examples/retained-run). A workflow graph, a fleet topology, and the Intelligence adapter stay optional.
+
+This package runs the declared profile and records the attempt. `@tangle-network/agent-interface` is the profile contract. `@tangle-network/agent-eval` scores and compares. `@tangle-network/sandbox` owns the isolated box, and the Sandbox orchestrator owns session durability for that box. `@tangle-network/agent-knowledge` owns the source-backed knowledge base. `@tangle-network/agent-app` is the product shell for chat, billing, and the tool side channel, and it calls these exports. Discovery owns research campaigns and result archives. Who durably owns each record is [`docs/durability.md`](./docs/durability.md).
+
+The words profile, task, attempt, environment, and completion are the table below. A resumed task brings its settled record, artifacts, and identity. Harness continuation stays with the native session. A result lasts in the store configured for that run. An external effect the record leaves unconfirmed is reconciled at that effect's boundary.
+
+Discovery's runner is one consumer that keeps its own coordinator and imports the published `/kernel` and `/durable` subpaths. Agent App declares the runtime majors its chat shell accepts; a major outside that range is a change in Agent App.
+
+## Quickstart: scripted, no credentials
+
+[`examples/quickstart/minimal.ts`](./examples/quickstart/minimal.ts) is the scripted class named above. It runs without credentials.
 
 ```ts
 import type { AgentProfile } from '@tangle-network/agent-interface'
@@ -88,14 +100,20 @@ Runtime uses the same primitive for round batches and concurrent sandbox lineage
 | Word | Meaning |
 |---|---|
 | **profile** | The complete behavioral declaration: harness, provider/model, prompt, tools, MCP, permissions, resources, hooks, and subagents. |
+| **task** | The caller's unit of work, passed to `runAgentRounds` or returned by `runTaskQueue`'s `take`. |
+| **attempt** | One execution of that work: one driver attempt, or one fresh worker inside a round. |
+| **environment** | The provider box for an attempt, named by provider and environment id. No id means nothing was named. |
 | **worker** | An agent that performs one assigned unit of work. |
 | **driver / supervisor** | An agent or deterministic policy that observes work and decides what happens next. |
 | **verdict** | An independently produced validity/score record. |
 | **harness** | What drives the profile. `cli-base` is direct model execution; `claude-code`, `codex`, `opencode`, and `prime` run agent harnesses. The complete vocabulary is `HarnessType` in `@tangle-network/agent-interface`. |
-| **delivery** | A settled result that passed the caller's completion check. Settlement alone is not delivery. |
+| **completion** | The caller's check on the settled result. |
+| **delivery** | A settlement that passed that check. |
 
 ## Choose a front door
 
+The scripted quickstart is the first run. Open another row when its shape is the one you already have.
+
 | Front door | Use it for | Runnable example |
 |---|---|---|
 | `runAgentTaskStream` | one agent turn and a normalized event stream | [`stream-a-turn`](./examples/stream-a-turn) |
@@ -113,7 +131,7 @@ Five mechanisms continue interrupted work; choose by what died:
 - HTTP connection: reconnect with the same execution identity.
 - Same live box, next turn: continue the sandbox session.
 - Coordinator process: `supervise({ runDir })`.
-- User conversation: the conversation journal adapters exported at root.
+- User conversation: Agent App's turn store. `runConversation`, exported at the package root, runs in-process.
 - Initiating process: a retained run owned by the provider.
 
 ## Truthfulness before value
@@ -126,19 +144,12 @@ The provider's account owner binds that turn's credential; Runtime keeps the ori
 Exact replay retains the admitted request, including older admissions that relied on the creation-time profile.
 
 
-Those are **integration proofs**, not benchmark-value proofs.
-
-`pnpm verify:official-optimizers` verifies the official GEPA/Optimize Anything bridge, recipe identities, resume behavior, accounting, and package provenance on a controlled fixture. It does not claim to reproduce GEPA, Omni, AutoResearch, or Meta-Harness benchmark lift. Full benchmark reproduction belongs in Discovery Lab, using the benchmark's own evaluator, matched budgets, frozen partitions, and immutable receipts.
-
-The same boundary applies to trace analysts, Prime Agent RLM, and DSPy RLM: Runtime may expose the execution seam, but analyst quality and benchmark lift must be established outside this repository.
+Those gates are integration proofs. Benchmark reproduction, including the official optimizer bridge, is [`bench/HARNESS.md`](./bench/HARNESS.md). Analyst quality belongs outside this repository.
 
 ### The conformance manifest
 
 Each release candidate carries one manifest beside its packed archive: `agent-runtime-conformance-manifest.json`, uploaded with the `.tgz` by `publish.yml`.
 The same artifact retains the raw `cohort-report.json` used to verify that manifest.
-The release workflow validates the tag once, then checks the archive, official optimizers, and Bench concurrently against that commit.
-Publication requires all three checks and verifies the uploaded archive digest before publishing.
-
 
 `release/cohort.json` is the single source for the exact Interface, Eval, and Knowledge source releases used by CI and publication.
 Update each version and full source commit together when the dependency cohort changes.

package/dist/{activation-Cwy3_Qn_.js → activation-Ce4zUcu8.js}

@@ -1,6 +1,6 @@
-import { a as defaultStructuralRolloutPolicy } from "./structural-rollout-BwTwTUXF.js";
-import { B as verifyCanonicalCandidateDocument, L as immutableCandidateValue, N as canonicalCandidateDigest$1, P as canonicalCandidateDocument, R as omitTopLevelDigest } from "./workspace-streams-B7yNMahl.js";
-import { a as applyExactAgentProfileDiff, g as omitUndefinedObjectFields, i as agentCandidateProfileAsAgentProfile, v as parseExactAgentProfile } from "./profile-CNSQjOes.js";
+import { a as defaultStructuralRolloutPolicy } from "./structural-rollout-C1xxoWcN.js";
+import { B as verifyCanonicalCandidateDocument, L as immutableCandidateValue, N as canonicalCandidateDigest$1, P as canonicalCandidateDocument, R as omitTopLevelDigest } from "./workspace-streams-DA9R3j-p.js";
+import { a as applyExactAgentProfileDiff, g as omitUndefinedObjectFields, i as agentCandidateProfileAsAgentProfile, v as parseExactAgentProfile } from "./profile-CD25rTJF.js";
 import { agentImprovementActivationResultSchema, agentImprovementActivationSchema, agentImprovementProposalSchema, agentImprovementReviewSchema, agentProfileDiffSchema, agentProfileImprovementExecutionRefSchema, agentProfileImprovementExperimentSchema, agentProfileModelHintsSchema, agentProfileSchema, canonicalAgentProfileDigest, changedProfileImprovementSurfaces, defineAgentProfileDiff, diffAgentProfiles } from "@tangle-network/agent-interface";
 import { assertProposalFindings } from "@tangle-network/agent-eval/analyst";
 import { campaignSplitDigestFromIdentities } from "@tangle-network/agent-eval/campaign";
@@ -871,4 +871,4 @@ function sameOrderedValues(left, right) {
 }
 export { serializeRolloutPolicy as C, normalizeRolloutPolicy as S, agentImprovementTargetProfileDiffs as _, reviewAgentImprovementProposal as a, isAgentProfileMeasuredSurface as b, verifyAgentImprovementProposal as c, attachOptimizationActivationReceipt as d, createOptimizationActivationReceipt as f, agentImprovementProfileSurfaceInput as g, agentImprovementProfileSurfaceDigest as h, executeAgentImprovementActivation as i, verifyAgentImprovementReview as l, agentImprovementProfileDiffs as m, createAgentImprovementActivationResult as n, verifyAgentImprovementActivation as o, optimizationActivationReceiptFromMetadata as p, createAgentImprovementProposal as r, verifyAgentImprovementActivationResult as s, createAgentImprovementActivation as t, assertNoCallerOptimizationReceipt as u, assertProfileImprovementTargetsShareIdentity as v, structuralRolloutPolicyFromProfile as w, applyRolloutPolicyToProfile as x, isAgentImprovementProfileSurface as y };
 
-//# sourceMappingURL=activation-Cwy3_Qn_.js.map
+//# sourceMappingURL=activation-Ce4zUcu8.js.map