@tangle-network/agent-runtime 0.89.0 → 0.90.1

package/dist/intelligence.d.ts

@@ -1,6 +1,6 @@
-import { c as LoopTraceEvent } from './types-ESeMOj94.js';
-import { AgentProfileMcpServer } from '@tangle-network/agent-interface';
-import { T as ToolSpec } from './router-client-r8y_VFVM.js';
+import { d as LoopTraceEvent } from './types-SyuwunY_.js';
+import { AgentProfileDiff, AgentProfile, AgentProfileMcpServer } from '@tangle-network/agent-interface';
+import { b as ToolSpec } from './router-client-DJImUDlm.js';
 import '@tangle-network/agent-eval';
 import '@tangle-network/sandbox';
 
@@ -152,28 +152,29 @@ declare function resolveRedactor(redact: Redactor | false | undefined): Redactor
 
 /**
  *
- * Tangle Intelligence — the DELIVERY half of the loop (pull-by-default).
+ * Tangle Intelligence — the RECEIVE half of the loop (pull-by-default).
  *
- * The sibling Observe layer (`./index`) sends traces UP to the plane. This
+ * The sibling Observe path (`./index`) sends run records UP to the plane. This
  * module pulls certified artifacts DOWN: it reads the tenant's promoted,
- * gate-certified profile from the deployed Intelligence plane and folds it into
- * the running agent's prompt — so an approved improvement actually reaches the
- * agent. This is "shipping intelligence to people's agents", pull-by-default;
- * the push/Gated-PR opt-in composes on top of this.
+ * gate-certified profile from the deployed Intelligence plane so an approved
+ * improvement actually reaches the running agent. The pull carries three things
+ * the plane already composes:
+ *   - the certified PROMPT surface + prompt-folding artifacts (delivered into the
+ *     system prompt via {@link composeCertifiedPrompt} — the promoted prompt);
+ *   - the typed profile DIFFS the plane has promoted, each with its held-out
+ *     provenance (surfaced as PROPOSALS — never auto-applied at runtime);
+ *   - the composed `agentProfile` those diffs fold to, for inspection.
  *
  * Pull contract (deployed plane): GET /v1/profiles/:target/composed →
- *   { target, generatedAt, promptSurface: {surface,surfaceHash,version,lift}|null,
- *     artifacts: { <artifactType>: [{path,content,contentHash,version,lift,promotedAt}] } }
+ *   { target, generatedAt,
+ *     promptSurface: {surface,surfaceHash,version,lift}|null,
+ *     artifacts: { <artifactType>: [{path,content,contentHash,version,lift,promotedAt}] },
+ *     capabilities: [{id,iface:{surface},binding:{path,content},provenance}],
+ *     agentProfileDiffs: [{diff, provenance:{version,lift,contentHash,promotedAt}}],
+ *     agentProfile: AgentProfile|null }
  * Auth: Bearer <apiKey> (the one TANGLE_API_KEY shared by router + sandbox +
  * intelligence), resolved to a tenant by platform-api's key-verify S2S contract.
  *
- *   import { withCertifiedDelivery } from '@tangle-network/agent-runtime/intelligence'
- *
- *   export const agent = withCertifiedDelivery(
- *     async (input, applied) => myAgent(input, { systemPrompt: applied.composePrompt(BASE) }),
- *     { project: 'support-agent', target: 'support-agent' },
- *   )
- *
  * @experimental
  */
 
@@ -195,6 +196,39 @@ interface CertifiedPromptSurface {
     version: number | null;
     lift: string | null;
 }
+/** The held-out provenance the plane's certify step stamps on a promoted diff.
+ *  `lift` is the held-out gate lift (e.g. "+3.1pp"), never a within-run claim. */
+interface DiffProvenance {
+    version: number | null;
+    lift: string | null;
+    contentHash: string;
+    promotedAt: string;
+}
+/**
+ * A gate-certified profile diff the plane has already promoted, plus the
+ * held-out provenance it carries. This is the previously-DROPPED typed diff the
+ * composed endpoint returns; `withIntelligence` deserializes it and surfaces it
+ * as a PROPOSAL — a human, or the gated local `improve()` loop, turns a proposal
+ * into a shipped profile. It is NEVER auto-applied at runtime.
+ */
+interface ProposedProfileDiff {
+    diff: AgentProfileDiff;
+    provenance: DiffProvenance;
+}
+/** The composed endpoint's per-capability summary — the narrow shape on the
+ *  wire (id + surface + path/content + provenance). Distinct from the richer
+ *  `CertifiedCapability` the capability resolver lowers a manifest into. */
+interface CertifiedCapabilitySummary {
+    id: string;
+    iface: {
+        surface: string;
+    };
+    binding: {
+        path: string | null;
+        content: string;
+    };
+    provenance: DiffProvenance;
+}
 /** The composed certified profile — exactly the shape the plane's
  *  `GET /v1/profiles/:target/composed` returns. */
 interface CertifiedProfile {
@@ -202,6 +236,14 @@ interface CertifiedProfile {
     generatedAt: string;
     promptSurface: CertifiedPromptSurface | null;
     artifacts: Record<string, CertifiedArtifact[]>;
+    /** The typed profile diffs the plane has promoted, each with held-out
+     *  provenance. Surfaced as proposals; never auto-applied. Empty when none. */
+    agentProfileDiffs: ProposedProfileDiff[];
+    /** The composed capability summaries the plane returns. Empty when none. */
+    capabilities: CertifiedCapabilitySummary[];
+    /** The composed profile the promoted diffs fold to, for inspection. `null`
+     *  when no diffs are promoted. */
+    agentProfile: AgentProfile | null;
 }
 /** Typed outcome for the pull — inspect `succeeded` before `value`. A 404
  *  (nothing promoted yet) is a normal, non-error `succeeded: false`. */
@@ -228,6 +270,16 @@ interface PullCertifiedOptions {
      *  false` (the agent runs on its base surface). */
     timeoutMs?: number;
 }
+/** Resolve the ONE Intelligence base URL — the single knob both the send and
+ *  receive paths derive from. Env fallback: `TANGLE_INTELLIGENCE_URL`. */
+declare function resolveIntelligenceBaseUrl(baseUrl: string | undefined): string;
+/**
+ * Deserialize the composed-endpoint response into a `CertifiedProfile`. The
+ * previously-dropped `agentProfileDiffs`/`capabilities`/`agentProfile` are read
+ * here so they round-trip to the consumer; a plane that has not yet promoted any
+ * diffs simply yields empty arrays / a null profile (fail-closed, never a crash).
+ */
+declare function normalizeCertifiedProfile(raw: unknown): CertifiedProfile;
 /**
  * Pull the certified composed profile for a target. Fail-closed: a network
  * error or a non-2xx returns a typed `succeeded: false` (never throws), so a
@@ -242,13 +294,13 @@ declare function pullCertified(opts: PullCertifiedOptions): Promise<PullOutcome>
  * additions. Order is stable (prompt surface first, then artifact buckets in
  * `promptFoldTypes` order, then by path within a bucket) so the same profile
  * renders byte-identically each call. Returns `base` unchanged when there is no
- * usable certified content.
+ * usable certified content. Reads only the prompt-folding slice of a profile.
  */
-declare function composeCertifiedPrompt(base: string, certified: CertifiedProfile | null): string;
+declare function composeCertifiedPrompt(base: string, certified: Pick<CertifiedProfile, 'promptSurface' | 'artifacts'> | null): string;
 /** A cached, self-refreshing source of a target's certified prompt additions —
  *  the prompt-only delivery lane for callers that assemble their OWN system
  *  prompt (product chat routes) rather than wrapping an agent fn. Same
- *  fail-closed semantics as {@link withCertifiedDelivery}: pulls at most every
+ *  fail-closed semantics as {@link pullCertified}: pulls at most every
  *  `refreshMs`, coalesces concurrent pulls, keeps the last-known profile on a
  *  failed/404 pull, never throws, never blocks past the pull timeout. */
 interface CertifiedPromptSource {
@@ -269,46 +321,10 @@ interface CertifiedPromptSourceOptions extends PullCertifiedOptions {
 /**
  * Create the cached certified-prompt source — the ONE module-scope-cache +
  * coalesced-refresh + keep-last-known implementation. Product wiring uses this
- * rather than hand-rolling the same lines around `pullCertified`, and
- * {@link withCertifiedDelivery} is built on it.
+ * rather than hand-rolling the same lines around `pullCertified`. The
+ * `withIntelligence` hook rides this same source for its prompt delivery.
  */
 declare function createCertifiedPromptSource(opts: CertifiedPromptSourceOptions): CertifiedPromptSource;
-/** What the delivery wrapper hands the agent each run. */
-interface AppliedIntelligence {
-    /** The certified profile in effect (null when none promoted / pull failed —
-     *  fail-closed: the agent runs on its base surface). */
-    certified: CertifiedProfile | null;
-    /** Fold the certified prompt surface into a base system prompt. */
-    composePrompt(base: string): string;
-}
-/** An agent wrapped by {@link withCertifiedDelivery}: receives the input plus
- *  the certified intelligence delivered for this run. */
-type DeliveredAgent<I, O> = (input: I, applied: AppliedIntelligence) => Promise<O>;
-/** Delivery config = the Observe config plus the pull target + refresh cadence. */
-interface DeliveryConfig extends IntelligenceConfig {
-    /** Pull target. Defaults to `project`. */
-    target?: string;
-    /** Plane base URL for the pull (NOT the OTLP `endpoint`). Defaults to
-     *  `TANGLE_INTELLIGENCE_URL` then `https://intelligence.tangle.tools`. */
-    baseUrl?: string;
-    /** Min interval between certified-profile pulls. Default 5m. */
-    refreshMs?: number;
-    /** Per-pull timeout in ms (fail-closed on a hung plane). Default 10000. */
-    timeoutMs?: number;
-    /** fetch impl for the pull (tests). Defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-}
-/**
- * Wrap an agent so it (a) Observes each run via the shipped Observe client and
- * (b) RECEIVES the tenant's certified artifacts pulled from the deployed plane.
- * The certified profile is cached and refreshed at most every `refreshMs`; a
- * failed pull is fail-closed — the agent runs on its base surface and never
- * breaks because Intelligence is unreachable. When the plane promotes a new
- * gate-certified surface, the next refresh delivers it to the running agent.
- */
-declare function withCertifiedDelivery<I, O>(agent: DeliveredAgent<I, O>, config: DeliveryConfig): ((input: I) => Promise<O>) & {
-    refresh(): Promise<void>;
-};
 
 /**
  *
@@ -711,6 +727,98 @@ declare function composeCertifiedProfileFromWire(base: {
     systemPrompt: string;
 }, profile: CertifiedProfile | null, ctx?: ResolveCtx): Promise<ResolvedSurface>;
 
+/**
+ *
+ * `withIntelligence` — the ONE agent-runtime hook that unifies Tangle
+ * Intelligence send + receive.
+ *
+ * It does two things per call, both fail-open:
+ *   1. RECEIVE — pull the tenant's certified profile from the deployed plane
+ *      (cached + refreshed), hand the agent the certified prompt surface to fold
+ *      (`applied.composePrompt`) and the promoted, gate-certified profile DIFFS
+ *      as PROPOSALS (`applied.proposals` / `applied.applyProfile`).
+ *   2. SEND — serialize a typed {@link RunRecord} for the call through the shipped
+ *      OTLP builders to the plane's `/v1/otlp` ingest, best-effort.
+ *
+ * SAFETY — observe + deliver ONLY. This hook NEVER auto-applies a received diff
+ * at runtime. A promoted diff is surfaced as a proposal; a human, or the gated
+ * local `improve()` loop, turns a proposal into a shipped profile. That
+ * preserves the held-out invariant the plane enforces — a runtime that silently
+ * folded an un-gated diff into itself would defeat the very gate the diff cleared.
+ *
+ *   import { withIntelligence } from '@tangle-network/agent-runtime/intelligence'
+ *
+ *   export const agent = withIntelligence(
+ *     async (input, applied) => {
+ *       const out = await myAgent(input, { systemPrompt: applied.composePrompt(BASE) })
+ *       applied.record({ success: true, usage: { inferenceUsd: 0.002, intelligenceUsd: 0 } })
+ *       return out
+ *     },
+ *     { project: 'support-agent', target: 'support-agent' },
+ *   )
+ *
+ * @experimental
+ */
+
+/** What the hook hands the agent each run. Additive over the prompt-only
+ *  delivery: `composePrompt` folds the certified prompt surface (as before);
+ *  `proposals`/`applyProfile` surface the promoted profile DIFFS — never
+ *  auto-applied; `record` enriches the {@link RunRecord} that is sent. */
+interface AppliedIntelligence {
+    /** The certified profile in effect (null when none promoted / pull failed —
+     *  fail-closed: the agent runs on its base surface). */
+    certified: CertifiedProfile | null;
+    /** Fold the certified prompt surface into a base system prompt (the promoted
+     *  prompt). The consumer opts in by calling it. */
+    composePrompt(base: string): string;
+    /** The promoted, gate-certified profile diffs — surfaced for a human or the
+     *  gated `improve()` loop. NEVER auto-applied by this hook. Empty when none. */
+    proposals: ProposedProfileDiff[];
+    /** Fold every proposal into `base` via `applyAgentProfileDiff`, in promotion
+     *  order, and return the result. The caller invokes this EXPLICITLY (it is the
+     *  human/gated apply step) — the hook never calls it on the run path. */
+    applyProfile(base: AgentProfile): AgentProfile;
+    /** Enrich the {@link RunRecord} sent for this call — outcome, usage split,
+     *  model/provider, and the loop event stream. Optional; an un-recorded run
+     *  still sends input/output with an inference-only zero usage split. */
+    record(report: RunReport): void;
+}
+/** An agent wrapped by {@link withIntelligence}: receives the input plus the
+ *  intelligence delivered for this run. */
+type IntelligenceAgent<I, O> = (input: I, applied: AppliedIntelligence) => Promise<O>;
+/** `withIntelligence` config = the Observe config plus the pull target, refresh
+ *  cadence, and a proposals callback. One base URL (`baseUrl` /
+ *  `TANGLE_INTELLIGENCE_URL`) drives both the send and receive paths. */
+interface IntelligenceHookConfig extends IntelligenceConfig {
+    /** Pull target. Defaults to `project`. */
+    target?: string;
+    /** Min interval between certified-profile pulls. Default 5m. */
+    refreshMs?: number;
+    /** Per-pull timeout in ms (fail-closed on a hung plane). Default 10000. */
+    timeoutMs?: number;
+    /** fetch impl for the pull (tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Notified when a refresh delivers a NEW set of promoted proposals (by
+     *  provenance content hash). Surfaces diffs without auto-applying them. */
+    onProposals?: (proposals: ProposedProfileDiff[]) => void;
+}
+/** The wrapped agent — same `(input) => Promise<output>` shape, plus a manual
+ *  `refresh()` and a `proposals()` accessor for the currently-promoted diffs. */
+type IntelligenceWrapped<I, O> = ((input: I) => Promise<O>) & {
+    refresh(): Promise<void>;
+    proposals(): ProposedProfileDiff[];
+};
+/**
+ * Wrap an agent so it (a) RECEIVES the tenant's certified profile — the prompt
+ * surface to fold and the promoted profile diffs as proposals — and (b) SENDS a
+ * typed {@link RunRecord} per call to the plane. The pull is cached and refreshed
+ * at most every `refreshMs`; a failed pull is fail-closed (the agent runs on its
+ * base surface, never breaks because Intelligence is unreachable). The send is
+ * best-effort — an export failure never fails the agent's turn — while an error
+ * thrown by the agent itself propagates unchanged.
+ */
+declare function withIntelligence<I, O>(agent: IntelligenceAgent<I, O>, config: IntelligenceHookConfig): IntelligenceWrapped<I, O>;
+
 /**
  *
  * Tangle Intelligence SDK — the Observe + Mode-0 product layer.
@@ -751,6 +859,44 @@ interface UsageSplit {
     /** Intelligence-spawn spend in USD. Provably `0` at the OFF tier. */
     intelligenceUsd: number;
 }
+/**
+ * The typed record `withIntelligence` sends per call — serialized through the
+ * shipped OTLP builders to the plane's `/v1/otlp` ingest. `input`/`output` are
+ * redacted on export; the per-class `usage` split carries the billing proof;
+ * `loopEvents`, when present, export as the nested loop→round→iteration span
+ * tree under the same `traceId`.
+ */
+interface RunRecord {
+    runId: string;
+    traceId: string;
+    project: string;
+    target: string;
+    input: unknown;
+    output: unknown;
+    outcome: {
+        success?: boolean;
+        score?: number;
+        usage: UsageSplit;
+    };
+    model?: string;
+    provider?: string;
+    loopEvents?: LoopTraceEvent[];
+}
+/**
+ * What an agent reports (via `applied.record`) to enrich the {@link RunRecord}
+ * sent for its call. All optional — an un-recorded run still sends input/output
+ * with an inference-only zero usage split. `costUsd` without a split is treated
+ * as pure inference (the base stream).
+ */
+interface RunReport {
+    success?: boolean;
+    score?: number;
+    usage?: Partial<UsageSplit>;
+    costUsd?: number;
+    model?: string;
+    provider?: string;
+    loopEvents?: LoopTraceEvent[];
+}
 /** Repo coordinates a product may declare for the (later) Gated-PR mode. The
  *  Observe slice only records their PRESENCE for `doctor()`; it never touches
  *  the repo. */
@@ -773,12 +919,13 @@ interface IntelligenceConfig {
         overrides?: EffortOverrides;
     };
     /**
-     * OTLP ingest base. The underlying exporter appends `/v1/traces`, so point
-     * this at the OTLP route (e.g. `https://intelligence.tangle.tools/v1/otlp`).
-     * Reads `INTELLIGENCE_OTLP_ENDPOINT` then `OTEL_EXPORTER_OTLP_ENDPOINT` when
-     * omitted; absent all three, export is a no-op (best-effort by construction).
+     * The ONE Tangle Intelligence base URL — both the send (OTLP `/v1/otlp`) and
+     * receive (`/v1/profiles/:target/composed`) paths derive from it. Reads
+     * `TANGLE_INTELLIGENCE_URL` when omitted, else `https://intelligence.tangle.tools`.
+     * Send is best-effort and only ships when an `apiKey` is present (the tenant
+     * key the ingest requires); absent a key, export is a no-op.
      */
-    endpoint?: string;
+    baseUrl?: string;
     /**
      * Redaction hook run over every exported input/output. A function replaces
      * the default scrubber; `false` opts out entirely (raw fidelity, caller has
@@ -874,6 +1021,18 @@ interface IntelligenceClient {
      * Best-effort: export failures are swallowed. Returns the resolved `traceId`.
      */
     recordTrace(events: ReadonlyArray<LoopTraceEvent>, meta?: RecordTraceMeta): string;
+    /**
+     * Send one typed {@link RunRecord} — the run's flat span (input/output/outcome/
+     * usage/model/provider, redacted) plus, when `loopEvents` are present, the
+     * nested loop topology under the same `traceId`. Reuses the shipped
+     * `flatOtelSpan` + `buildLoopOtelSpans` builders (no second builder).
+     * Best-effort: export failures are swallowed. Returns the record's `traceId`.
+     */
+    exportRunRecord(record: RunRecord): string;
+    /** Mint a fresh run id (`run-<hex>`). */
+    freshRunId(): string;
+    /** Mint a fresh 32-hex trace id. */
+    freshTraceId(): string;
     /**
      * Network-free readiness report: which adoption modes are reachable given
      * this config. Observe is always reachable; Recommend needs outcomes; PR
@@ -902,26 +1061,11 @@ interface DoctorReport {
     };
 }
 /**
- * Create an Observe-mode Intelligence client. Resolves effort, endpoint, and
- * redactor up front; the exporter is built lazily and is `undefined` when no
- * endpoint is configured (export becomes a no-op — best-effort by
- * construction).
+ * Create an Observe-mode Intelligence client. Resolves effort, the base URL, and
+ * the redactor up front; the exporter is built lazily and is `undefined` when no
+ * `apiKey` is present (send becomes a no-op — the ingest requires a tenant key,
+ * and best-effort export must never spam an unauthenticated plane).
  */
 declare function createIntelligenceClient(config: IntelligenceConfig): IntelligenceClient;
-/** A generic agent: one async input → output. The shape `withTangleIntelligence`
- *  preserves exactly. */
-type Agent<TInput, TOutput> = (input: TInput) => Promise<TOutput>;
-/** Either a built client or the config to build one. */
-type ClientOrConfig = IntelligenceClient | IntelligenceConfig;
-/**
- * Wrap a generic `agent` with best-effort Observe-mode tracing, returning the
- * SAME shape. Each call runs the agent under a trace and exports one span; an
- * export failure is swallowed (the live agent never fails because Intelligence
- * is down) but an error from the agent itself propagates unchanged.
- *
- * At `effort: 'off'` this is pure passthrough plus best-effort telemetry —
- * zero intelligence spawns, `intelligenceUsd: 0` on the trace.
- */
-declare function withTangleIntelligence<TInput, TOutput>(agent: Agent<TInput, TOutput>, clientOrConfig: ClientOrConfig): Agent<TInput, TOutput>;
 
-export { type Agent, type AppliedIntelligence, type CapabilityAuth, type CapabilityInterface, type CapabilityManifest, CapabilityNotAdmittedError, type CapabilitySurface, type CertProvenance, type CertifiedArtifact, type CertifiedCapability, type CertifiedProfile, type CertifiedPromptSource, type CertifiedPromptSourceOptions, type CertifiedPromptSurface, type ClientOrConfig, type ContentRef, type CorpusAccess, type CredentialRef, type DeliveredAgent, type DeliveryBinding, type DeliveryBindingKind, type DeliveryConfig, type DoctorReport, type EffortOverrides, type EffortOverridesCompiled, type EffortSettings, type EffortTier, type HostSpec, type IntelligenceClient, type IntelligenceConfig, type JsonSchema, type ModeReadiness, type ProvisionedHost, type PullCertifiedOptions, type PullOutcome, type RecordTraceMeta, type Redactor, type RepoConfig, type ResolveCtx, type ResolvedHook, type ResolvedRetrieval, type ResolvedSubagent, type ResolvedSurface, type TraceHandle, type TraceMeta, type TraceOutcome, type UsageClass, type UsageSplit, compileEffort, composeCertifiedProfile, composeCertifiedProfileFromWire, composeCertifiedPrompt, createCertifiedPromptSource, createIntelligenceClient, defaultEffortTier, defaultRedactor, isIntelligenceOff, manifestFromProfile, pullCertified, resolveEffort, resolveRedactor, withCertifiedDelivery, withTangleIntelligence };
+export { type AppliedIntelligence, type CapabilityAuth, type CapabilityInterface, type CapabilityManifest, CapabilityNotAdmittedError, type CapabilitySurface, type CertProvenance, type CertifiedArtifact, type CertifiedCapability, type CertifiedCapabilitySummary, type CertifiedProfile, type CertifiedPromptSource, type CertifiedPromptSourceOptions, type CertifiedPromptSurface, type ContentRef, type CorpusAccess, type CredentialRef, type DeliveryBinding, type DeliveryBindingKind, type DiffProvenance, type DoctorReport, type EffortOverrides, type EffortOverridesCompiled, type EffortSettings, type EffortTier, type HostSpec, type IntelligenceAgent, type IntelligenceClient, type IntelligenceConfig, type IntelligenceHookConfig, type IntelligenceWrapped, type JsonSchema, type ModeReadiness, type ProposedProfileDiff, type ProvisionedHost, type PullCertifiedOptions, type PullOutcome, type RecordTraceMeta, type Redactor, type RepoConfig, type ResolveCtx, type ResolvedHook, type ResolvedRetrieval, type ResolvedSubagent, type ResolvedSurface, type RunRecord, type RunReport, type TraceHandle, type TraceMeta, type TraceOutcome, type UsageClass, type UsageSplit, compileEffort, composeCertifiedProfile, composeCertifiedProfileFromWire, composeCertifiedPrompt, createCertifiedPromptSource, createIntelligenceClient, defaultEffortTier, defaultRedactor, isIntelligenceOff, manifestFromProfile, normalizeCertifiedProfile, pullCertified, resolveEffort, resolveIntelligenceBaseUrl, resolveRedactor, withIntelligence };