feat(intelligence): withIntelligence hook — unify send/receive, fix dropped typed diffs

docs/api/index.md

@@ -4436,7 +4436,7 @@ Bearer key — tenant is resolved server-side from it. Reads TANGLE_API_KEY.
 
 Defined in: [otel-export.ts:599](https://github.com/tangle-network/agent-runtime/blob/main/src/otel-export.ts#L599)
 
-Intelligence base. Reads INTELLIGENCE_BASE env, else prod.
+Intelligence base. Reads TANGLE_INTELLIGENCE_URL env, else prod.
 
 ##### idempotencyKey?
 

docs/api/primitive-catalog.md

@@ -198,7 +198,7 @@ Import from `@tangle-network/agent-runtime/agent` — 48 exports.
 
 ### Intelligence SDK — Observe + provable-OFF billing
 
-Import from `@tangle-network/agent-runtime/intelligence` — 63 exports.
+Import from `@tangle-network/agent-runtime/intelligence` — 68 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -207,35 +207,39 @@ Import from `@tangle-network/agent-runtime/intelligence` — 63 exports.
 | `composeCertifiedProfileFromWire` | function | Lower a plane `CertifiedProfile` straight into a `ResolvedSurface` via |
 | `composeCertifiedPrompt` | function | Fold the certified prompt surface (and any certified prompt-folding artifacts: |
 | `createCertifiedPromptSource` | function | Create the cached certified-prompt source — the ONE module-scope-cache + |
-| `createIntelligenceClient` | function | Create an Observe-mode Intelligence client. Resolves effort, endpoint, and |
+| `createIntelligenceClient` | function | Create an Observe-mode Intelligence client. Resolves effort, the base URL, and |
 | `defaultRedactor` | function | The built-in redactor. Walks objects and arrays; replaces values under |
 | `isIntelligenceOff` | function | True when these settings admit NO intelligence spawn — the passthrough |
 | `manifestFromProfile` | function | Lower the EXISTING plane wire (`CertifiedProfile`) into a `CapabilityManifest`. |
+| `normalizeCertifiedProfile` | function | Deserialize the composed-endpoint response into a `CertifiedProfile`. The |
 | `pullCertified` | function | Pull the certified composed profile for a target. Fail-closed: a network |
 | `resolveEffort` | function | Compile a named tier (plus optional per-field overrides) into the flat |
+| `resolveIntelligenceBaseUrl` | function | Resolve the ONE Intelligence base URL — the single knob both the send and |
 | `resolveRedactor` | function | Resolve the redactor a client uses. A caller-supplied hook replaces the |
-| `withCertifiedDelivery` | function | Wrap an agent so it (a) Observes each run via the shipped Observe client and |
-| `withTangleIntelligence` | function | Wrap a generic `agent` with best-effort Observe-mode tracing, returning the |
+| `withIntelligence` | function | Wrap an agent so it (a) RECEIVES the tenant's certified profile — the prompt |
 | `defaultEffortTier` | const | The default tier when a client declares no effort. `'standard'` turns |
 | `CapabilityNotAdmittedError` | class | A binding kind whose resolver case is typed but not yet admitted (rag-index, |
-| `AppliedIntelligence` | interface | What the delivery wrapper hands the agent each run. |
+| `AppliedIntelligence` | interface | What the hook hands the agent each run. Additive over the prompt-only |
 | `CapabilityManifest` | interface | The strict generalization of `CertifiedProfile`. `promptSurface` is kept |
 | `CertifiedArtifact` | interface | A promoted, certified artifact (one entry in the composed profile). |
 | `CertifiedCapability` | interface | One certified unit of agent power. |
+| `CertifiedCapabilitySummary` | interface | The composed endpoint's per-capability summary — the narrow shape on the |
 | `CertifiedProfile` | interface | The composed certified profile — exactly the shape the plane's |
 | `CertifiedPromptSource` | interface | A cached, self-refreshing source of a target's certified prompt additions — |
 | `CertifiedPromptSourceOptions` | interface | Options for {@link createCertifiedPromptSource} — the pull coordinates plus |
 | `CertifiedPromptSurface` | interface | The active promoted prompt surface for a target. |
 | `CertProvenance` | interface | The certify lane's held-out lift travelling WITH delivery. The shipped |
 | `CredentialRef` | interface | A named secret a binding requires — declared, never carried. |
-| `DeliveryConfig` | interface | Delivery config = the Observe config plus the pull target + refresh cadence. |
+| `DiffProvenance` | interface | The held-out provenance the plane's certify step stamps on a promoted diff. |
 | `DoctorReport` | interface | The `doctor()` readiness report — Mode-readiness without any network call. |
 | `EffortOverridesCompiled` | interface | The run-config overrides an `EffortSettings` compiles to — the bridge between the |
 | `EffortSettings` | interface | The flat, resolved settings a tier compiles to. Every field is individually |
 | `HostSpec` | interface | The host a `process-on-infra` binding provisions before its inner binding. |
 | `IntelligenceClient` | interface | The Observe-mode Intelligence client. |
 | `IntelligenceConfig` | interface | Client configuration. `project` + `apiKey` are the Observe minimum; the |
+| `IntelligenceHookConfig` | interface | `withIntelligence` config = the Observe config plus the pull target, refresh |
 | `ModeReadiness` | interface | One mode's readiness verdict. |
+| `ProposedProfileDiff` | interface | A gate-certified profile diff the plane has already promoted, plus the |
 | `ProvisionedHost` | interface | A live, provisioned host the resolver tore up for a `process-on-infra` arm. |
 | `RecordTraceMeta` | interface | Metadata for {@link IntelligenceClient.recordTrace}. |
 | `RepoConfig` | interface | Repo coordinates a product may declare for the (later) Gated-PR mode. The |
@@ -244,22 +248,23 @@ Import from `@tangle-network/agent-runtime/intelligence` — 63 exports.
 | `ResolvedRetrieval` | interface | One retrieval handle. The agent never learns vector vs graph vs index. |
 | `ResolvedSubagent` | interface | One resolved subagent — folded into `AgentProfile.subagents`. |
 | `ResolvedSurface` | interface | What `composeCertifiedProfile` produces. Every binding fans into the same |
+| `RunRecord` | interface | The typed record `withIntelligence` sends per call — serialized through the |
+| `RunReport` | interface | What an agent reports (via `applied.record`) to enrich the {@link RunRecord} |
 | `TraceHandle` | interface | The trace handle a `traceRun` body records into. `recordOutput` captures the |
 | `TraceMeta` | interface | Metadata describing one traced run. `runId`/`traceId` default to fresh ids. |
 | `TraceOutcome` | interface | The resolved outcome of one traced run, surfaced on the export span and |
 | `UsageSplit` | interface | The per-class cost split carried by every trace and outcome. `off` ⇒ |
-| `Agent` | type | A generic agent: one async input → output. The shape `withTangleIntelligence` |
 | `CapabilityAuth` | type | How a binding authenticates at resolve time. Declared as a REQUIREMENT in the |
 | `CapabilityInterface` | type | What the agent consumes. CLOSED — a new runtime kind NEVER extends this. Each |
 | `CapabilitySurface` | type | Every interface surface tag — the closed set the resolver fans into slots. |
-| `ClientOrConfig` | type | Either a built client or the config to build one. |
 | `ContentRef` | type | Where a capability's bytes live. A leaked manifest carries no live secret and |
 | `CorpusAccess` | type | Corpus access an intelligence tier permits. `'off'` reads and writes |
-| `DeliveredAgent` | type | An agent wrapped by {@link withCertifiedDelivery}: receives the input plus |
 | `DeliveryBinding` | type | How a capability is backed. OPEN tagged union — THE extension point. All arms |
 | `DeliveryBindingKind` | type | Every binding kind — the open set the resolver dispatches over. |
 | `EffortOverrides` | type | Per-field overrides applied on top of a tier preset. Any subset of the |
 | `EffortTier` | type | The named effort tiers, lowest to highest. `'off'` is the honest floor |
+| `IntelligenceAgent` | type | An agent wrapped by {@link withIntelligence}: receives the input plus the |
+| `IntelligenceWrapped` | type | The wrapped agent — same `(input) => Promise<output>` shape, plus a manual |
 | `JsonSchema` | type | A JSON Schema object describing a tool's parameters. Kept structural — the |
 | `PullOutcome` | type | Typed outcome for the pull — inspect `succeeded` before `value`. A 404 |
 | `Redactor` | type | A redactor maps an arbitrary trace value to a safe-to-export value. Pure; |

docs/archive/go-live-plan.md

@@ -31,7 +31,7 @@ The two replicated survivors, with provenance:
 | Certification rigor predicts transfer | Only a full-statistical-gate-certified artifact transfers: holdout cert-vs-prose **+31.7pp CI[+13.3,+48.3]** and **+36.7pp CI[+11.7,+66.7]**, twice | E3d (5-run, agent-lab) |
 | The cost flywheel | Certified memory + compression **HOLD quality at −12% to −31% cost**; steer+compress promoted ×2 on AIME; author lands near-parity at 30–55% cost, replicated ×3 | E3/E3b/E3d, cost-arc, powered run |
 
-**Mandatory provenance rider on every public claim** (both survivors are measured on EOPS/AIME via the agent-lab harness, **not yet through `withTangleIntelligence` in a product**):
+**Mandatory provenance rider on every public claim** (both survivors are measured on EOPS/AIME via the agent-lab harness, **not yet through `withIntelligence` in a product**):
 > *"Demonstrated on internal benchmarks; in-product replication in progress."*
 
 ---
@@ -89,7 +89,7 @@ This is where "take risks" stops. Boldness is allowed in *speed, scope, and dogf
 
 **First customer: gtm.tangle.tools** (NOT Harvey). Already deployed on agent-runtime, already on the platform billing rail, richest live tool surface, friendliest checks, named first in the playbook. Harvey is **external** — repo access + contract + trust risk *before the wrapper has ever run in production.* Harvey/legal is case study #2.
 
-**First PR / first turn (the go-live proof):** wrap gtm's production `handleChatTurn` with `withTangleIntelligence` in Observe mode, ship **one real user turn**, confirm the trace lands in `/v1/traces` AND live chat is unaffected when that endpoint is down. That single live trace + survived-outage = go-live.
+**First PR / first turn (the go-live proof):** wrap gtm's production `handleChatTurn` with `withIntelligence` in Observe mode, ship **one real user turn**, confirm the trace lands in `/v1/traces` AND live chat is unaffected when that endpoint is down. That single live trace + survived-outage = go-live.
 
 **Harvest, don't rebuild:** cherry-pick `origin/examples/tangle-intelligence-export` (`8fa16af`, 122 LOC) into `examples/intelligence-drop-in/`; reconcile `origin/feat/observe-closed-loop` (`37e373f`) into the Phase-1 PR. Both branches exist (verified) — pay the re-discovery tax once.
 
@@ -113,7 +113,7 @@ Ship Observe to gtm **only when all green:**
 ## 6. THE #1 BUILD AND THE #1 EXPERIMENT
 
 **#1 BUILD — `src/intelligence/index.ts` + the conserved-pool usd split.**
-`createIntelligenceClient` + `withTangleIntelligence(agent, config)` + `traceRun(meta, fn)` — a thin best-effort layer over the shipped `createOtelExporter` + the Mode-0 sandbox-stream base. Add the `./intelligence` export. **Cap at Observe + intelligence-off; do NOT bundle loops.** Bundle the `{inferenceUsd, intelligenceUsd}` split with it — without it there is no honest OFF tier, no billing boundary, no metered baseline for the cost claim. Everything in §4 depends on this one PR.
+`createIntelligenceClient` + `withIntelligence(agent, config)` + `traceRun(meta, fn)` — a thin best-effort layer over the shipped `createOtelExporter` + the Mode-0 sandbox-stream base. Add the `./intelligence` export. **Cap at Observe + intelligence-off; do NOT bundle loops.** Bundle the `{inferenceUsd, intelligenceUsd}` split with it — without it there is no honest OFF tier, no billing boundary, no metered baseline for the cost claim. Everything in §4 depends on this one PR.
 
 **#1 EXPERIMENT — E4: does the cost flywheel COMPOUND, or is it one-shot selection?**
 The surviving thesis hinges on this. Every cost win so far is single-step and partly *selection, not accumulation* (E3c/E3d killed in-stream admission). "Cost keeps falling as the certified store grows" is **unmeasured** (no E4 doc exists yet — it's the designed-not-launched NEXT in `current.json`).

docs/canonical-api.md

@@ -109,8 +109,8 @@ A general "loop" primitive is the single most common modelling error in this rep
 | Run a coding task INSIDE the agent's OWN sandbox session (a sibling box, fresh branch, validated patch) | `detachedSessionDelegate({ sandboxClient \| executor, workerProfile? })` — `/mcp` (pass the worker `AgentProfile`; omit for a minimal model-only default) | a hardcoded coder profile baked into the delegate; `delegate()` (that spawns workers in a *chosen* backend, not the agent's own session) |
 | Have a **supervisor spawn + live-drive workers in a backend you choose** and observe/steer/resume them | the **coordination MCP** — `createCoordinationTools` / `serveCoordinationMcp` over a live `Scope`; each worker's leaf is `createExecutor({ backend })` — `/mcp`,`/loops` | `detachedSessionDelegate` — own-sandbox-session only, one-shot, no live steer/recursion/conserved-budget |
 | Stand up a vertical agent in the eval loop | `defineAgent(manifest)` + `createSurfaceImprovementAdapter` — `/agent` | a per-vertical manifest parser, surface-validator, or bespoke `ImprovementAdapter` |
-| Turn intelligence/observation OFF (prove inference-only billing) | `withTangleIntelligence(agent, { effort: 'off' })` — `/intelligence` | a custom trace-wrapper or hand-rolled effort/tier config |
-| Fold **certified prompt additions into a system prompt you assemble yourself** (product chat routes) | `createCertifiedPromptSource({ target })` → `source.compose(base)` — `/intelligence` (cached, coalesced, fail-closed; `withCertifiedDelivery` rides the same source) | a module-scope cache + refresh-window + keep-last-known loop around `pullCertified` in product wiring |
+| Observe + deliver Intelligence on a live agent (send RunRecords + receive certified profile/diffs) | `withIntelligence(agent, { project, target })` — `/intelligence` (proposals surfaced, never auto-applied; `effort: 'off'` proves inference-only billing) | a custom trace-wrapper, a second receive path, or hand-rolled effort/tier config |
+| Fold **certified prompt additions into a system prompt you assemble yourself** (product chat routes) | `createCertifiedPromptSource({ target })` → `source.compose(base)` — `/intelligence` (cached, coalesced, fail-closed; `withIntelligence` rides the same source) | a module-scope cache + refresh-window + keep-last-known loop around `pullCertified` in product wiring |
 | Improve a KB with runtime agents, candidate workspaces, readiness checks, and measured supervised spend | `runKnowledgeImprovementJob(options)` from `/knowledge` | hand-wiring `improveKnowledgeBase` + a supervised updater + a readiness callback in every product |
 
 For the full export inventory (every primitive, its import path, its summary — generated, never stale), see `docs/api/primitive-catalog.md`; for per-symbol signatures, the per-module `docs/api/` pages. For the recursive atom (recursion · isolated-or-collaborative artifact · conserved budget · analysts) and the two-timescale architecture, see `docs/architecture.md`. For the genome→run→optimize→ship spine in depth, `docs/concepts.md` + `docs/learning-flywheel.md`. For the Intelligence SDK (Observe + the provable-OFF billing boundary), `docs/intelligence-sdk.md`.