feat(runtime): certified-profile delivery — approve→running-agent, profile-wide

[drewstone]

What

The delivery truck for Tangle Intelligence: closes the output end of the loop. Today an approved improvement moves a registry pointer and ships nothing (the composed-profile endpoint had zero consumers). This wires the shared agent-app runtime to pull a tenant's certified AgentProfile and apply it to the running agent — approve → next turn uses it, no redeploy.

How

• createAgentRuntime gains an opt-in composeProfile transform over the resolved profile surfaces. Substrate boundary preserved: the substrate-free core takes a generic injected transform and never imports agent-runtime.
• New createCertifiedDelivery({ target }) (separate module, imports @tangle-network/agent-runtime/intelligence): pulls GET /v1/profiles/:target/composed, cached + refreshed, fail-closed (plane down → base surfaces, agent never breaks).

Profile-WIDE, not prompt-only

Per the correction — delivery applies the whole profile, not just the system prompt:

• prompt-surface + skill → folded into the system prompt.
• tool artifacts → extraTools (the advertised tool set rebuilds when delivered tools change; executor wired by the product). Pass-through until a tool artifact carries a runnable def.
• mcp/memory/rag (file/server artifacts) → delivered via the sandbox-provisioning seam; the full certified profile is exposed via current() for it.

Blast radius + safety

One change → every product on createAgentRuntime (tax/legal/gtm/creative + future) can opt into delivery with one config field. Opt-in, so zero behavior change for products that don't pass composeProfile (covered by a test).

Tests

12/12 (5 delivery: fold prompt+skill, pass-through tools, fail-closed 404, unreachable, cache; 2 new seam: transform applied to prompt+tools, and unchanged without it; 5 existing). Typecheck clean.

Scope

Runtime layer; no auth/billing/lifecycle surface. Independent of chore/canonical-tool-loop (which only touches agent.test.ts).

[tangletools]

✅ Auto-approved PR — ff53e21d

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-14T13:33:31Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	3 (3 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	306.4s (2 bridge agents)
Total	306.4s

💰 Value — sound-with-nits

Adds a clean, opt-in certified-profile delivery seam (composeProfile) to createAgentRuntime plus a cached, fail-closed createCertifiedDelivery wrapper around the agent-runtime Intelligence primitives — good change, but the new @tangle-network/agent-runtime/intelligence subpath import needs t

• What it does: createAgentRuntime gains an optional composeProfile(base) => ResolvedAgentProfile transform that is applied each turn to determine the effective systemPrompt and advertised extraTools (src/runtime/agent.ts:79-87, src/runtime/agent.ts:172-178). A new createCertifiedDelivery({ target }) module pulls GET /v1/profiles/:target/composed from the Intelligence plane, caches it with a refresh i
• Goals it achieves: Closes the output end of the Tangle Intelligence loop: after an improvement is approved and promoted, the running agent picks it up on the next turn without a redeploy. It does this profile-wide (prompt + skills + tool advertisement), keeps the substrate-free runtime core free of @tangle-network/agent-runtime imports, and makes delivery opt-in so existing products see zero behavior change.
• Assessment: Coherent and well-fitted to the repo's architecture. It follows the engine-as-peer-dependency rule (agent.ts stays substrate-free; certified-delivery.ts owns the single agent-runtime import), composes by seam rather than domain, is additive under the existing ./runtime export, and is fail-closed. The streamTurnFor memoization by extraTools identity (src/runtime/agent.ts:154-167) is the right
• Better / existing approach: none — this is the right approach. The Intelligence primitives (pullCertified, composeCertifiedPrompt, CertifiedProfile) already live in the substrate peer (@tangle-network/agent-runtime/intelligence), and the change correctly wraps them rather than reimplementing. The generic composeProfile transform keeps the substrate-free core decoupled. I checked src/runtime/surface-profile.ts (su

🎯 Usefulness — sound-with-nits

A coherent, opt-in delivery seam for certified profiles that plugs cleanly into createAgentRuntime; no dead surface, but two minor robustness/ergonomics rough edges.

• Integration: The new API is exported from src/runtime/index.ts:5 and wired into createAgentRuntime through the composeProfile option (src/runtime/agent.ts:87, src/runtime/agent.ts:172-177). No in-repo caller exists yet, but it is reachable through the /runtime subpath (package.json:60-64), and the intended callers are the product runtimes built on createAgentRuntime. Verified that the substrate import @tangle-
• Fit with existing patterns: It follows the codebase's seam pattern: createAgentRuntime is the shared factory, composeProfile is an injected transform, and the core stays substrate-free (src/runtime/agent.ts:80-86). It does not compete with src/runtime/surface-profile.ts (per-surface MCP/prompt overlays) because certified delivery is a global profile transform, not a surface overlay. It also does not duplicate withCertifiedDe
• Real-world viability: Fail-closed behavior is correct: pullCertified catches network errors and 404s, and the agent falls back to base surfaces (src/runtime/certified-delivery.test.ts:54-69). Concurrent turns are de-duplicated via an inflight promise (src/runtime/certified-delivery.ts:73-89). Targeted tests pass (src/runtime/agent.test.ts and src/runtime/certified-delivery.test.ts, 12/12). Two minor issues: refresh upd

💰 Value Audit

🟡 New agent-runtime subpath import is not externalized in tsup.config.ts [against-grain] ``

The new module imports from @tangle-network/agent-runtime/intelligence (src/runtime/certified-delivery.ts:26-30), but tsup.config.ts:41 only externalizes the exact package @tangle-network/agent-runtime and the separate subpath @tangle-network/agent-integrations/catalog. The codebase's existing pattern is to list each subpath import explicitly; without adding @tangle-network/agent-runtime/intelligence to the external array, the build may try to bundle a peer-dependency subpath. Fix: a

🎯 Usefulness Audit

🟡 lastPullAt advances even on failed pulls [robustness] ``

In src/runtime/certified-delivery.ts:81, lastPullAt = Date.now() runs before the outcome is inspected. After a transient network error, refresh() will be skipped for refreshMs even though no certified profile was loaded. Consider moving the timestamp update inside the success path or tracking lastSuccessAt separately so the agent recovers faster from a blip. (The substrate's own withCertifiedDelivery has the same behavior, so this is inherited, not new.)

🟡 streamTurn memo relies on extraTools reference identity [ergonomics] ``

src/runtime/agent.ts:161-166 rebuilds createOpenAICompatStreamTurn only when extraTools !== activeExtraTools. A composeProfile implementation that defensively returns [...base.extraTools] when nothing changed will cause a rebuild every turn. Either document that transforms should preserve reference identity when unchanged, or compare by deep-equality/shallow content.

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260614T134507Z}

[tangletools]

✅ No Blockers — ff53e21d

Readiness 79/100 · Confidence 65/100 · 3 findings (1 medium, 2 low)

deepseek: Correctness 79 · Security 79 · Testing 79 · Architecture 79

Full multi-shot audit completed 1/1 planned shots over 5 changed files. Global verifier still owns final merge decision.

🟠 MEDIUM certified-delivery.ts placed under substrate-free /runtime subpath, adds agent-runtime/intelligence import — src/runtime/certified-delivery.ts

AGENTS.md invariant #4 states /runtime imports nothing from engine packages. The existing barrel (src/runtime/index.ts) already imports from @tangle-network/agent-runtime for loop aliases (acknowledged with ⚠️ in the module map), but certified-delivery.ts:26-30 adds a second import from @tangle-network/agent-runtime/intelligence. This means any consumer of @tangle-network/agent-app/runtime now transitively pulls in the /intelligence subpath export. The module doc at line 22-23 acknowledges the boundary explicitly ('Substrate boundary: THIS module imports @tangle-network/agent-runtime'). Per AGENTS.md rule #5 (additive subpaths), this should be

🟡 LOW streamTurnFor identity check will cause per-turn rebuild once certified tools are delivered — src/runtime/agent.ts

At agent.ts:161-167, the streamTurnFor memoization uses extraTools !== activeExtraTools — reference identity. Currently certified-delivery passes through base.extraTools (always the same baseExtraTools reference), so identity stays stable. But once certified-delivery starts appending certified tool artifacts (creating new arrays), every turn will see a new array reference, and buildStreamTurn will re-run every turn, defeating the memoization. The comment at line 154-156 acknowledges this is 'on the cache-refresh cadence — not per turn' but the identity check doesn't implement that cadence — it checks the passed array reference which changes each turn. The

🟡 LOW refresh() has no defensive catch — relies entirely on pullCertified never throwing — src/runtime/certified-delivery.ts

At certified-delivery.ts:85-89, refresh() does try { await inflight } finally { inflight = null } with no catch block. If pullCertified ever throws (instead of returning { succeeded: false }), the error propagates through refresh() → composeProfile() → resolveProfile() → run()/stream(), crashing the entire agent turn. The test at certified-delivery.test.ts:62-70 proves that with the current pullCertified implementation, network errors are caught internally and don't throw. But this is an implicit cross-package contract — a future agent-runtime change that throws instead of returning a failure outcome would silently break all consumers. The fail-closed contract advertised in the module doc ('it never breaks because Intelligence is down') should be enforced defensively

---

_{tangletools · 2026-06-14T13:47:54Z · trace}