@tangle-network/agent-runtime 0.8.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "Reusable runtime lifecycle for domain-specific agents.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -18,18 +18,42 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./platform": {
+      "types": "./dist/platform.d.ts",
+      "import": "./dist/platform.js",
+      "default": "./dist/platform.js"
+    },
+    "./analyst-loop": {
+      "types": "./dist/analyst-loop.d.ts",
+      "import": "./dist/analyst-loop.js",
+      "default": "./dist/analyst-loop.js"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js",
+      "default": "./dist/agent.js"
     }
   },
   "files": [
     "dist",
-    "README.md",
-    "docs"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepare": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src tests examples",
+    "lint:fix": "biome check --write src tests examples",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
-    "@tangle-network/agent-eval": "^0.24.0"
+    "@tangle-network/agent-eval": "^0.30.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.0",
@@ -39,20 +63,21 @@
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },
+  "pnpm": {
+    "minimumReleaseAge": 4320,
+    "minimumReleaseAgeExclude": [
+      "@tangle-network/agent-eval"
+    ],
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
   "engines": {
     "node": ">=20"
   },
   "license": "MIT",
+  "packageManager": "pnpm@10.28.0",
   "peerDependencies": {
     "@tangle-network/sandbox": "0.1.2"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "biome check src tests examples",
-    "lint:fix": "biome check --write src tests examples",
-    "typecheck": "tsc --noEmit"
   }
-}
+}

package/docs/domain-agent-runtime-integration-issues.md

@@ -1,165 +0,0 @@
-# Domain Agent Runtime Integration Issues
-
-GitHub issue creation was blocked in this environment: the GitHub connector returns 404 for the private repos and `gh` is not authenticated. These are the issue drafts to open once repository credentials are available.
-
-## tax-agent
-
-Title: Integrate tax evals with agent-runtime knowledge readiness
-
-`@tangle-network/agent-runtime@0.2.0` provides the shared task harness for domain agents: `runAgentTask`, typed runtime events, `KnowledgeRequirement`, readiness scoring, question/acquisition preflight hooks, and integration with `@tangle-network/agent-eval@0.20.0`.
-
-First local implementation:
-
-- Bump root `@tangle-network/agent-eval` to `0.20.0`.
-- Add root `@tangle-network/agent-runtime` `^0.2.0`.
-- Bump `server` `@tangle-network/agent-eval` to `0.20.0`.
-- Add `tests/eval/lib/agent-runtime.ts` with `buildTaxKnowledgeRequirements()` and `runTaxAgentTask()`.
-- Add `tests/eval/lib/agent-runtime.test.ts` covering missing-context blocking and ready-context execution.
-
-Remaining changes:
-
-- Wire the runtime helper into `tests/eval/lib/deterministic-tax-workflow-runner.ts`, `tests/eval/harness/run-product-eval.ts`, `tests/eval/harness/run-workspace-eval.ts`, `tests/eval/optimize.ts`, `tests/eval/lib/agent-eval-runtime.ts`, and `tests/eval/lib/trace-sync.ts`.
-- Canonicalize tax requirements for taxpayer facts, filing year, jurisdiction, source documents, workflow tools, entity classification, elections, accounting method, book/tax reconciliation, payroll, withholding, estimated payments, credits, nexus, apportionment, OCR confidence, current authority, and user-confirmed assumptions.
-- Persist runtime events into traces: `task_start`, `readiness_start/end`, `questions_start/end`, `acquisition_start/end`, `control_start/end`, and `task_end`.
-- Report readiness score, blocking gaps, acquisition mode, evidence IDs, blocked-before-execution status, and optimizer responsible surface.
-- Classify missing documents, missing jurisdiction, stale authority, bad retrieval, insufficient evidence, contradictory evidence, missing credentials, and ambiguous taxpayer intent as knowledge failures rather than prompt failures.
-- Feed gaps into multi-shot optimization as `knowledge-requirements`, `data-acquisition`, `retrieval-policy`, or `user-question-policy`.
-- Add tests for missing taxpayer facts, missing documents, missing jurisdiction, stale authority, and fully ready execution.
-
-## legal-agent
-
-Title: Integrate legal evals with agent-runtime knowledge readiness
-
-First local implementation:
-
-- Bump `@tangle-network/agent-eval` dev dependency to `^0.20.0`.
-- Add `@tangle-network/agent-runtime` dev dependency `^0.2.0`.
-- Add `tests/eval/lib/agent-runtime.ts` with `buildLegalKnowledgeRequirements()` and `runLegalAgentTask()`.
-- Add `tests/eval/lib/agent-runtime.test.ts` covering missing matter context and ready execution.
-
-Remaining changes:
-
-- Wire `runLegalAgentTask()` into `tests/eval/harness/run-product-eval.ts`, `tests/eval/harness/run-dual-agent-eval.ts`, `tests/eval/optimize.ts`, `tests/eval/lib/agent-eval-runtime.ts`, and `tests/eval/lib/trace-sync.ts`.
-- Canonicalize legal requirements for matter facts, parties, dates, jurisdiction, forum, venue, governing law, current authority, uploaded matter documents, knowledge-base search, client credentials, regulated industry constraints, deadlines, and user-approved assumptions.
-- Enforce knowledge-base retrieval before drafting or review, with retrieval evidence saved into the runtime bundle.
-- Persist runtime readiness metadata and events into trace sync and eval reports.
-- Classify missing facts, missing authority, stale law, bad retrieval, insufficient evidence, contradictory authority, missing credentials, and ambiguous user intent as knowledge failures.
-- Extend optimization ASI rows so legal reports recommend data acquisition or authority refresh before prompt rewrites.
-- Add tests for missing jurisdiction, stale authority, missing knowledge-base results, contradictory authority, and ready document review.
-
-## gtm-agent
-
-Title: Integrate GTM evals with agent-runtime knowledge readiness
-
-First local implementation:
-
-- Bump `@tangle-network/agent-eval` to `0.20.0`.
-- Add `@tangle-network/agent-runtime` `^0.2.0`.
-- Add `eval/agent-runtime.ts` with `buildGtmKnowledgeRequirements()` and `runGtmAgentTask()`.
-- Add `tests/agent-runtime.test.ts` covering missing company/connector context and ready execution.
-
-Remaining changes:
-
-- Wire `runGtmAgentTask()` into `eval/business-owner/live-flow.ts`, `eval/discover-brief/run.ts`, `eval/run.ts`, `eval/agent-eval-traces.ts`, and optimizer flows.
-- Canonicalize GTM requirements for company profile, product/offer, ICP/personas, channel history, CRM state, campaign history, analytics, performance metrics, positioning, competitors, integrations, credentials, and workspace vault knowledge.
-- Turn `knowledge/wiki/company.md`, `products.md`, `channels.md`, and `open-questions.md` into runtime evidence inputs.
-- Persist readiness events into existing trace helpers and reports.
-- Classify missing company data, missing market data, stale metrics, missing credentials, bad connector retrieval, insufficient evidence, contradictory positioning, and ambiguous business-owner intent as knowledge failures.
-- Feed knowledge gaps into optimization as data-acquisition/retrieval-policy/user-question-policy issues.
-- Add tests for missing ICP, missing product context, missing connectors, stale metrics, and ready discover-brief execution.
-
-## creative-agent
-
-Title: Integrate creative evals with agent-runtime knowledge readiness
-
-First local implementation:
-
-- Bump `@tangle-network/agent-eval` to `^0.20.0`.
-- Add `@tangle-network/agent-runtime` `^0.2.0`.
-- Add `eval/control/agent-runtime.ts` with `buildCreativeKnowledgeRequirements()` and `runCreativeAgentTask()`.
-- Add `tests/agent-runtime.test.ts` covering missing creative intent/rights and ready execution.
-
-Remaining changes:
-
-- Wire `runCreativeAgentTask()` into `eval/control/creative-onboarding.ts`, `eval/control/creative-workflow-optimization.ts`, `eval/control/creative-multishot-optimization.ts`, `eval/e2e/creative-product-harness.ts`, and trace/report code.
-- Canonicalize creative requirements for intent, audience, taste thesis, references, dislikes, brand system, source rights, generated asset policy, deliverable specs, channel constraints, localization, approval policy, feedback source, and revision budget.
-- Convert onboarding answers and approval feedback into runtime evidence and reusable knowledge requirements.
-- Persist readiness events in control/e2e traces and reports.
-- Classify missing creative intent, missing taste signal, missing brand assets, missing rights, stale source policy, bad asset retrieval, insufficient evidence, contradictory feedback, and ambiguous user intent as knowledge failures.
-- Feed approval/readiness gaps into multi-shot optimization as data or policy surfaces before prompt changes.
-- Add tests for missing intent, missing rights, missing approval policy, contradictory feedback, and ready workflow execution.
-
-## blueprint-agent
-
-Title: Integrate Blueprint benchmarks with agent-runtime knowledge readiness
-
-No implementation was requested for this pass. The repo should adopt the runtime boundary before deeper report polish so benchmark failures separate missing task-world knowledge from coding-agent failures.
-
-Remaining changes:
-
-- Add `@tangle-network/agent-runtime` to the workspace package(s) that own benchmark execution.
-- Keep existing benchmark database/report terms stable if they still say `vertical`; map to runtime `domain` metadata instead of forcing a broad rename.
-- Define Blueprint requirements for task brief, repo/source checkout, package manager, framework/language, build command, test command, sandbox availability, runtime environment, credentials/secrets, Tangle Blueprint SDK docs, template/plugin docs, deploy target, and benchmark scoring contract.
-- Wrap the benchmark product path with `runAgentTask` so readiness is scored before agent execution.
-- Persist runtime events into agent-eval traces and `bench-report`.
-- Add readiness sections to markdown/HTML/JSON reports: requirement table, missing evidence, acquisition plan, blocked-before-execution runs, and readiness deltas by run/version.
-- Map failures to `knowledge_readiness_blocked`, `missing_codebase_context`, `missing_runtime_context`, `missing_credentials`, `stale_external_data`, `bad_retrieval`, `insufficient_evidence`, `contradictory_evidence`, `reasoning_error`, `tool_selection_error`, `sandbox_failure`, and `budget_exceeded`.
-- Extend holdout/promotion gates so a prompt/topology change is not promoted when observed gain is actually due to different context acquisition.
-- Add tests for missing build command, missing SDK docs, missing sandbox, stale template docs, and fully ready benchmark execution.
-
-## agent-builder
-
-Title: Integrate agent-builder with agent-runtime knowledge readiness
-
-`agent-builder` is the meta-platform for creating, testing, deploying, researching, and monetizing domain-specific agents. It already has the strongest production loop among the app repos: Forge builder sims, per-agent scenarios, feedback trajectories, canaries, auto-research, multi-shot optimization, KB optimization, version history, sandbox execution, marketplace publishing, and Playwright-to-agent-eval reporting.
-
-The missing boundary is that generated agents and Forge runs do not yet have a first-class `agent-runtime` preflight. Failures caused by missing build spec context, missing user/business/domain data, unavailable integrations, missing secrets, stale KB evidence, sandbox/runtime gaps, or bad retrieval can still be absorbed as prompt/config failures.
-
-Package updates:
-
-- Upgrade `@tangle-network/agent-eval` from `^0.19.1` to `^0.20.0`.
-- Upgrade `@tangle-network/agent-knowledge` from `^1.0.0` to `^1.1.0`.
-- Add `@tangle-network/agent-runtime` `^0.2.0`.
-
-Required changes:
-
-- Add a server-side runtime module: `src/lib/.server/runtime/agent-builder-runtime.ts`, `src/lib/.server/runtime/requirements.ts`, and `src/lib/.server/runtime/events.ts`.
-- Expose helpers: `buildForgeKnowledgeRequirements(input)`, `buildPublishedAgentKnowledgeRequirements(input)`, `runForgeAgentTask(input)`, `runPublishedAgentTask(input)`, and `runtimeEventsToTraceMetadata(events)`.
-- Define Forge build requirements for creator intent, target user, domain/category, BuildSpec completeness and approval, expected artifact, success criteria, tools, integrations, APIs, credentials, secrets, sandbox availability, runtime image, repository/scaffold structure, generated agent config, pricing/marketplace/governance constraints, and user-approved assumptions.
-- Define generated-agent requirements for domain-specific user facts, company/business/product context, regulatory freshness, connected integrations, secrets, vault/knowledge pages, source freshness, scenario fixtures, and fallback policy.
-- Persist generated-agent runtime metadata with agent config/version metadata so forks and marketplace consumers inherit the right contract.
-- Wire `runAgentTask` into Forge builder sims: `src/lib/.server/eval/forge-builder-sim.ts`, `src/routes/api.agents.eval.builder-sim.ts`, and `src/routes/api.admin.builder-sim.run.ts`.
-- Wire scenario and eval runs through runtime: `src/routes/api.agents.$agentId.scenarios.run.ts`, `src/routes/api.agents.$agentId.eval.simulate.ts`, `src/routes/api.agents.$agentId.eval.refine.ts`, and `src/routes/api.agents.$agentId.eval.ts`.
-- Add readiness checks or metadata to production chat/sandbox chat: `src/routes/api.agents.$agentId.chat.ts`, `src/routes/api.agents.$agentId.sandbox.chat.ts`, and `src/routes/api.v1.agents.$slug.chat.completions.ts`.
-- Bridge `agent-knowledge@1.1.0` readiness with `src/routes/api.agents.$agentId.knowledge.index.ts`, `src/routes/api.agents.$agentId.knowledge.search.ts`, `src/routes/api.agents.$agentId.knowledge.discover.ts`, `src/routes/api.agents.$agentId.knowledge.write-blocks.ts`, and `src/lib/.server/kb/optimization.ts`.
-- Persist runtime events into trace/report surfaces: `src/lib/.server/eval/trace-store-d1.ts`, `src/lib/.server/eval/session.ts`, `src/lib/.server/eval/run-record-store.ts`, `src/lib/.server/eval/run-record-fields.ts`, and `e2e/reporters/agent-eval-reporter.ts`.
-- Preserve `task_start`, `readiness_start/end`, `questions_start/end`, `acquisition_start/end`, `control_start/end`, and `task_end`.
-- Report readiness score, blocking gaps, acquisition mode, evidence IDs, user questions, runtime status, and blocked-before-execution status.
-- Map failures to `knowledge_readiness_blocked`, `missing_user_data`, `missing_domain_data`, `missing_codebase_context`, `missing_runtime_context`, `missing_credentials`, `stale_external_data`, `bad_retrieval`, `insufficient_evidence`, `contradictory_evidence`, and `ambiguous_user_intent`.
-- Update `src/lib/.server/eval/failure-inspector.ts`, `src/lib/.server/eval/multi-shot-adapter.ts`, `src/lib/.server/eval/heuristic-researcher.ts`, `src/lib/.server/eval/auto-research-runner.ts`, and `src/lib/.server/eval/canary-cron.ts`.
-- Extend ASI responsible surfaces beyond `agent.config.systemPrompt`: `knowledge-requirements`, `data-acquisition`, `retrieval-policy`, `user-question-policy`, `runtime-environment`, `integration-policy`, `sandbox-policy`, and `agent.config.systemPrompt`.
-- Ensure auto-research does not mutate prompts when the dominant failure is missing KB pages, missing BuildSpec fields, missing secrets, unavailable sandbox, or stale evidence.
-- Persist runtime contracts across versions, publish, and forks: `src/lib/.server/versions.ts`, `src/routes/api.agents.$agentId.versions.ts`, `src/routes/api.agents.$agentId.versions.$versionId.revert.ts`, `src/routes/api.agents.$agentId.fork.ts`, `src/routes/api.agents.$agentId.fork.apply-update.ts`, and `src/routes/api.agents.$agentId.publish.ts`.
-- Add workbench/admin UI visibility for readiness on eval pages, research cycle pages, knowledge pages, chat/workbench blockers, and marketplace/published agent caveats. Do not expose private/secret requirement details to public consumers.
-
-Tests:
-
-- Forge sim blocks when BuildSpec or intent is incomplete.
-- Forge sim blocks or asks when required integration credentials are missing.
-- Scenario run records readiness metadata.
-- KB optimization reports no pages / too few labels as knowledge readiness failures.
-- Multi-shot ASI points to data-acquisition/retrieval-policy instead of `agent.config.systemPrompt` for missing knowledge.
-- Fork preserves runtime contract.
-- Public chat hides private/secret requirement details.
-- E2E reporter can include runtime readiness metadata.
-
-Acceptance criteria:
-
-- `agent-builder` depends on `agent-runtime@^0.2.0`, `agent-eval@^0.20.0`, and `agent-knowledge@^1.1.0`.
-- Forge builder sims run through `runAgentTask` or a thin typed wrapper.
-- Per-agent scenario/eval runs attach `KnowledgeReadinessReport` before execution.
-- KB search/optimization feeds readiness into runtime and traces.
-- Missing BuildSpec, missing credentials, missing KB pages, stale evidence, bad retrieval, and sandbox unavailability are classified as knowledge/runtime failures.
-- Multi-shot optimization can recommend acquisition/retrieval/user-question/runtime-policy changes instead of always mutating prompts.
-- Runtime requirements persist across config versions, publish, and fork flows.
-- Workbench/admin reports show readiness score, gaps, acquisition plan, runtime status, and blocked-before-execution runs.

package/docs/product-runtime-kernel.md

@@ -1,326 +0,0 @@
-# Product Runtime Kernel
-
-Status: complete. Implemented in `@tangle-network/agent-runtime@0.5.0`;
-validated, documented, and hardened through `0.5.2`.
-
-This document is the completion record for the production runtime kernel: what
-it is for, what is done, how it was validated, what is intentionally outside the
-public package, and how product repos should adopt it.
-
-## Purpose
-
-`agent-runtime` exists to make agent execution consistent across products and
-eval harnesses. It should own the contract for:
-
-- readiness gating before execution;
-- session create/resume for long-running coding harnesses;
-- backend-agnostic streaming;
-- sanitized product/eval telemetry;
-- durable evidence that can feed reports, failure classification, and
-  optimization.
-
-It should not be a decorative event logger around unrelated product code. If a
-product route still calls a backend directly, hand-rolls SSE, and only emits
-`start/end`, it is not getting the full value.
-
-## Runtime Flow
-
-```txt
-TaskSpec
-  -> knowledge readiness
-  -> optional ask/acquire/refresh
-  -> readiness decision
-  -> session create/resume
-  -> execution backend stream
-  -> normalized RuntimeStreamEvent
-  -> sanitized SSE / persisted session event history
-  -> final task status
-```
-
-## Definition of Done
-
-The kernel is complete when these are true:
-
-- A product route can call one runtime entry point, `runAgentTaskStream`, rather
-  than hand-rolling readiness + backend execution + SSE framing.
-- A coding harness can continue an existing workspace by passing `sessionId` and
-  `resume: true`.
-- A backend can be swapped without changing product stream consumers.
-- A failed backend emits structured failure events and gets a `stop()` callback
-  when available.
-- All UI/report telemetry has a safe sanitized representation by default.
-- Eval and optimization systems can distinguish missing context/runtime failure
-  from prompt/model reasoning failure.
-
-All kernel-side criteria are satisfied in `0.5.2`. Durable storage and UI
-rollout are product adoption tasks, not core package blockers.
-
-Completion verdict: passed. There are no open kernel blockers in this document.
-
-## Completed API Surface
-
-### Execution
-
-- `runAgentTaskStream(options)`
-  - Applies readiness before backend execution.
-  - Emits `task_start`, `readiness_start`, `readiness_end`.
-  - Stops before backend execution when blocking gaps remain.
-  - Creates or resumes a backend session.
-  - Normalizes backend output into `RuntimeStreamEvent`.
-  - Emits `backend_start`, `backend_end`, `task_end`, and `final`.
-  - Records backend stream events into an optional `RuntimeSessionStore`.
-  - Calls `backend.stop(session, reason)` on stream failure when a backend
-    supplies the hook.
-
-- `runAgentTask(options)`
-  - Existing control-loop path for eval-oriented agents.
-  - Still useful for deterministic eval/optimization harnesses that model
-    observe/validate/decide/act directly.
-
-### Stream Contract
-
-- `RuntimeStreamEvent`
-  - Readiness: `readiness_start`, `readiness_end`.
-  - Context collection: `questions_start`, `questions_end`,
-    `acquisition_start`, `acquisition_end`.
-  - Session: `session_created`, `session_resumed`.
-  - Backend lifecycle: `backend_start`, `backend_end`, `backend_error`.
-  - Product stream: `text_delta`, `reasoning_delta`, `tool_call`,
-    `tool_result`, `artifact`.
-  - Completion: `task_end`, `final`.
-
-### Sessions
-
-- `RuntimeSession`
-  - Stable `id`, backend kind, status, timestamps, optional `resumeToken`, and
-    metadata.
-
-- `RuntimeSessionStore`
-  - Minimal persistence contract: `get`, `put`, `appendEvent`, `listEvents`.
-  - Product repos should back this with D1/Postgres/Redis/etc. for real resume.
-
-- `InMemoryRuntimeSessionStore`
-  - Useful for tests, local demos, and short-lived worker processes.
-  - Not durable enough for production resume by itself.
-
-### Backend Abstraction
-
-- `AgentExecutionBackend`
-  - `start`, `resume`, `stream`, optional `stop`.
-  - SDK-agnostic: the package owns the contract, callers own concrete clients
-    and auth.
-
-- `createIterableBackend`
-  - Escape hatch for custom harnesses, browser agents, and test doubles.
-
-- `createSandboxPromptBackend`
-  - Wraps sandbox/sidecar clients that expose `streamPrompt`.
-  - Supports caller-provided session IDs and resume via backend `resume`.
-  - Maps common sandbox events to `text_delta`, `tool_call`, and `tool_result`.
-
-- `createOpenAICompatibleBackend`
-  - Wraps TCloud/OpenAI-compatible `/chat/completions` streaming APIs.
-  - Normalizes streamed content deltas into `text_delta`.
-  - Also covers [cli-bridge](https://github.com/drewstone/cli-bridge) and any
-    other OpenAI-compatible HTTP gateway — point `baseUrl` at the bridge's
-    `/v1` and use a `<harness>/<model>` string as `model`.
-
-### Sanitization and SSE
-
-- `sanitizeRuntimeStreamEvent(event, options)`
-  - Redacts task inputs, user answers, control payloads, metadata, artifact
-    URIs, and evidence IDs by default.
-  - Reveals payloads only through explicit diagnostic options.
-
-- `runtimeStreamServerSentEvent(event, options)`
-  - Encodes any sanitized runtime stream event as SSE.
-  - Prevents every product route from hand-rolling inconsistent framing.
-
-- Existing helpers remain:
-  - `sanitizeAgentRuntimeEvent`
-  - `createRuntimeEventCollector`
-  - `readinessServerSentEvent`
-  - `encodeServerSentEvent`
-
-## Validation Matrix
-
-Implemented test coverage in `tests/runtime.test.ts`:
-
-- Ready task runs through the existing control lifecycle.
-- Missing blocking knowledge stops before action.
-- Knowledge question/acquisition hooks refresh readiness before control.
-- Sanitized runtime telemetry redacts secrets by default.
-- Readiness decisions return stable `ready`, `blocked`, and `caveat` states.
-- SSE encoding strips unsafe control-field newlines.
-- Readiness SSE payloads use sanitized reports.
-- `runAgentTaskStream` blocks backend execution when readiness is missing.
-- Streaming backend creates a session, persists events, and resumes by
-  `sessionId`.
-- Sanitized tool-call stream events hide payloads by default and reveal them
-  only with `includeControlPayloads`.
-- Sandbox prompt events map to text/tool runtime stream events.
-- OpenAI-compatible streaming chat completions parse token deltas and produce a
-  final completed event.
-- Knowledge question preflight emits exactly one `questions_end`.
-- CLI bridge streams parse NDJSON events and include session/message payloads in
-  bridge requests.
-- Backend stream failure calls `backend.stop`, emits `backend_error`, and
-  returns a failed `final` event with partial text preserved.
-
-Release verification:
-
-- `pnpm test`
-- `pnpm typecheck`
-- `pnpm build`
-- Published to npm as `@tangle-network/agent-runtime@0.5.0`.
-- Documentation validation published in `@tangle-network/agent-runtime@0.5.1`.
-- Hardening validation published in `@tangle-network/agent-runtime@0.5.2`.
-
-## Completion Scorecard
-
-| Area | Status | Evidence |
-| --- | --- | --- |
-| Readiness gate | Complete | `runAgentTaskStream` blocks before backend execution when readiness is blocked. |
-| Stream contract | Complete | `RuntimeStreamEvent` covers readiness, session, backend, text, reasoning, tool, artifact, error, task end, final. |
-| Session resume contract | Complete | `RuntimeSession`, `RuntimeSessionStore`, `session_created`, `session_resumed`, `resumeToken`. |
-| Backend abstraction | Complete | `AgentExecutionBackend` with `start`, `resume`, `stream`, optional `stop`. |
-| Sandbox adapter | Complete | `createSandboxPromptBackend`; product proof in `agent-builder` PR #61. |
-| TCloud/OpenAI-compatible adapter | Complete | `createOpenAICompatibleBackend`; tested with streamed chat completions. Also serves cli-bridge (OpenAI-compatible) and any HTTP gateway. |
-| SSE framing | Complete | `runtimeStreamServerSentEvent`, newline-safe SSE encoder. |
-| Sanitization | Complete | Default redaction for task inputs, answers, payloads, metadata, URIs, evidence IDs. |
-| Failure handling | Complete | Backend exceptions produce `backend_error`, failed `task_end`, failed `final`, and call `stop` when supplied. |
-| Durable persistence | Contract complete, product-owned | `RuntimeSessionStore` interface exists; product repos must provide D1/Postgres/Redis implementations. |
-| UI rollout | Product-owned | Runtime emits stable events; product UIs decide rendering. |
-
-## Completion Boundaries
-
-The package is done when the reusable contract is complete. The package is not
-responsible for product-specific state, credentials, databases, or UX. Those are
-adoption responsibilities.
-
-### Complete in `agent-runtime`
-
-- Public task and stream contracts.
-- Readiness-gated streamed execution.
-- Session create/resume contract.
-- Backend abstraction and adapter factories.
-- Safe stream sanitization.
-- SSE encoding.
-- Failure normalization and backend stop hook.
-- Unit tests for the contract and shipped adapters.
-- NPM package publication.
-
-### Not Part of the Public Kernel
-
-- Product database migrations.
-- Product-specific session persistence.
-- Product-specific auth, secrets, billing, and rate limits.
-- UI components for resume/readiness.
-- Domain-specific knowledge requirements and tool policies.
-- Concrete private SDK client construction.
-
-These are not deferred kernel tasks. They are downstream integration tasks.
-
-## Critique
-
-The runtime kernel is now materially useful, but it is not magic. The most
-important limitations are deliberate:
-
-- It does not construct TCloud, sandbox, or CLI bridge clients. Product repos
-  own credentials and client lifecycle.
-- It does not persist sessions durably unless a product supplies a durable
-  `RuntimeSessionStore`.
-- It does not enforce all budgets/approvals/tool policies by itself yet. Those
-  still live in product adapters or `agent-eval` control loops.
-- It does not guarantee backend resume works if the underlying backend cannot
-  resume. It passes stable session IDs/resume tokens and records history; the
-  backend must honor them.
-- It does not replace domain-specific wrappers. Tax/legal/GTM/creative still
-  need their own requirements, tools, prompts, and report semantics.
-
-These constraints are correct for a public package. The core should define the
-contract and provide high-quality adapters, not absorb private product code.
-
-The main remaining architectural risk is misuse: product teams can still bypass
-the kernel and directly call sandbox/TCloud/CLI streams. Reviews should treat
-new hand-rolled readiness + stream loops as a smell unless the route has a
-specific reason to avoid runtime normalization.
-
-## Downstream Adoption Checklist
-
-For product routes:
-
-- Replace direct sandbox/CLI/TCloud stream loops with `runAgentTaskStream`.
-- Forward `runtimeStreamServerSentEvent(event)` to UI.
-- Preserve legacy UI events only as compatibility shims.
-- Store `RuntimeSession` and `RuntimeStreamEvent[]` in the product database.
-- Pass `sessionId` and `resume: true` for continuation.
-- Persist `final.status`, readiness decision, and backend kind in run records.
-- Assert in tests that blocked readiness does not call the backend.
-
-For coding harnesses:
-
-- Use `createSandboxPromptBackend`, `createOpenAICompatibleBackend` (also
-  covers cli-bridge and other OpenAI-compatible HTTP gateways), or a custom
-  `AgentExecutionBackend`.
-- Require a stable `sessionId` for any long-running workspace.
-- Surface `session_resumed` in telemetry so product/debug views can distinguish
-  continuation from a fresh run.
-- Treat missing session state as a recoverable backend/runtime failure, not a
-  prompt failure.
-- Implement `stop(session, reason)` for expensive or long-lived backends.
-
-For eval and optimization:
-
-- Attach readiness decisions and stream session metadata to `RunRecord.raw`.
-- Classify missing knowledge/runtime/session failures separately from prompt or
-  reasoning failures.
-- Do not optimize prompts when dominant failures are missing context, bad
-  retrieval, missing credentials, or broken backend resume.
-- Add report slices by `backend`, `session_resumed`, `backend_error`, and
-  `readiness_end.decision.status`.
-
-## Completed Downstream Proof
-
-`agent-builder` has a product-path proof in PR #61:
-
-- Bumps `@tangle-network/agent-runtime` to `^0.5.0`.
-- Routes sandbox chat through `runAgentTaskStream`.
-- Uses `createSandboxPromptBackend`.
-- Emits sanitized runtime stream SSE.
-- Adds runtime session IDs to the compatibility `done` event.
-
-That validates the package against a real sandbox-backed product route, not only
-unit tests.
-
-## Review Notes
-
-Validation found and fixed two issues before marking this complete:
-
-- The control-loop preflight path needed explicit coverage that
-  `questions_end` is emitted exactly once.
-- The CLI bridge parser claim needed hardening. `0.5.2` tested NDJSON bridge
-  streams instead of only SSE-style `data:` frames. `0.6.0` then removed the
-  bespoke `createCliBridgeBackend` entirely after confirming cli-bridge is
-  purely OpenAI-compatible at `/v1/chat/completions`; consumers now use
-  `createOpenAICompatibleBackend`.
-
-The doc now matches shipped behavior.
-
-## Downstream Rollout Plan
-
-This is downstream adoption work, not missing kernel work:
-
-1. Add durable `RuntimeSessionStore` implementations in product repos.
-2. Convert CLI bridge routes/harnesses to `createOpenAICompatibleBackend`
-   pointed at the bridge's `/v1` URL (cli-bridge is OpenAI-compatible).
-3. Convert simple TCloud chat routes to `createOpenAICompatibleBackend` where
-   useful.
-4. Store runtime stream events in product trace/run-record tables.
-5. Add UI affordances for session resume/continuation and readiness blockers.
-6. Extend failure classifiers to consume `RuntimeStreamEvent` evidence directly.
-
-The kernel is complete and ready for broad adoption. The next value comes from
-removing bespoke product stream loops and using the same runtime contract across
-product routes, coding harnesses, CLI bridge runs, evals, and optimization
-reports.