@armoriq/sdk-dev 0.6.10 → 0.8.0

package/dist/session.js

@@ -18,12 +18,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArmorIQSession = void 0;
 exports.normalizeDefaultAction = normalizeDefaultAction;
 const crypto_1 = require("crypto");
-const config_1 = require("./config");
+const tool_push_1 = require("./tool_push");
+const tool_registry_1 = require("./tool_registry");
 const crypto_verify_1 = require("./crypto_verify");
 const exceptions_1 = require("./exceptions");
 const models_1 = require("./models");
 const plan_builder_1 = require("./plan_builder");
 const observability_1 = require("./observability");
+const _version_1 = require("./_version");
+function isValidUuid(value) {
+    return (typeof value === 'string' &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value));
+}
 /**
  * Normalize a policy-authoring default-enforcement-action value into the
  * SDK-facing terminal enum. Mirrors the backend's enforce-boundary normalization
@@ -54,72 +60,48 @@ const MULTIUSER_PLACEHOLDER = '__sdk_multiuser__';
 function realIdentity(value) {
     return !value || value === MULTIUSER_PLACEHOLDER ? undefined : value;
 }
+const AUDIT_LABEL = /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$/;
+const AUDIT_SECRET = /(?:\beyJ[A-Za-z0-9_-]{5,}\.|\b(?:ak|sk|pk|rk|ghp|github_pat)_[A-Za-z0-9_-]{8,}\b|bearer|secret|password|credential|private[_-]?key)/i;
+function safeAuditLabel(value) {
+    return typeof value === 'string' && AUDIT_LABEL.test(value) && !AUDIT_SECRET.test(value)
+        ? value
+        : 'unknown';
+}
+function auditPersistencePayload(input) {
+    const durationMs = typeof input.durationMs === 'number' &&
+        Number.isFinite(input.durationMs) &&
+        input.durationMs >= 0
+        ? input.durationMs
+        : null;
+    const action = safeAuditLabel(input.action);
+    return {
+        plan_id: safeAuditLabel(input.token?.planId),
+        step_index: Number.isFinite(input.stepIndex) && input.stepIndex >= 0 ? Math.floor(input.stepIndex) : 0,
+        action,
+        tool: action,
+        mcp: safeAuditLabel(input.mcp),
+        input: {},
+        status: input.status === 'success' || input.status === 'failed' || input.status === 'error'
+            ? input.status
+            : 'error',
+        duration_ms: durationMs,
+        is_delegated: typeof input.isDelegated === 'boolean' ? input.isDelegated : null,
+        executed_at: new Date().toISOString(),
+    };
+}
 /** The rule body of a policy snapshot entry, whichever shape it arrived in. */
 function ruleOf(entry) {
     if (!entry || typeof entry !== 'object')
         return entry;
     return entry.memberRule ?? entry.clientRule ?? entry.rules ?? entry;
 }
-const TRUNCATE_BYTES = 4 * 1024;
-function truncateForSpan(value) {
-    if (value === undefined || value === null)
-        return value;
-    let json;
-    try {
-        json = typeof value === 'string' ? value : JSON.stringify(value);
-    }
-    catch {
-        json = String(value);
-    }
-    const bytes = Buffer.byteLength(json, 'utf8');
-    if (bytes <= TRUNCATE_BYTES)
-        return value;
-    const sliced = json.slice(0, TRUNCATE_BYTES);
-    return `${sliced}…(truncated, original ${bytes} bytes)`;
-}
-function safeObs(fn) {
-    try {
-        return fn();
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.warn(`[armoriq] observability emit failed (continuing): ${msg}`);
-        return undefined;
-    }
-}
-function makeSpanRecord(ctx, name, attributes, status = 'ok', durationMs = null, parentSpanId) {
-    const now = new Date().toISOString();
-    return {
-        id: (0, crypto_1.randomUUID)(),
-        parentSpanId: parentSpanId ?? null,
-        sessionId: ctx.sessionId,
-        kind: 'span',
-        name,
-        startTime: now,
-        endTime: now,
-        durationMs,
-        status,
-        attributes,
-    };
-}
-function makeEventRecord(ctx, name, attributes, parentSpanId) {
-    const now = new Date().toISOString();
-    return {
-        id: (0, crypto_1.randomUUID)(),
-        parentSpanId: parentSpanId ?? null,
-        sessionId: ctx.sessionId,
-        kind: 'event',
-        name,
-        startTime: now,
-        endTime: now,
-        durationMs: 0,
-        status: 'ok',
-        attributes,
-    };
+function isCancellation(error) {
+    return (error instanceof Error && (error.name === 'AbortError' || /cancelled/i.test(error.message)));
 }
 class ArmorIQSession {
     userEmail;
     client;
+    pendingPolicyTelemetry = new Set();
     toolNameParser;
     defaultMcpName;
     validitySeconds;
@@ -142,11 +124,15 @@ class ArmorIQSession {
     // MCPs we have already tried to load semantic metadata for (see
     // warmToolMetadata) — one attempt each, whether it succeeded or not.
     metadataWarmed = new Set();
-    obs = null;
+    /** Native OTel bridge. It never changes the application's global provider. */
+    otel = null;
+    /** Pending delegation spans are ended only by the approval terminal path. */
+    pendingDelegationOperations = new Map();
+    delegationTerminalOperations = new Map();
+    completedDelegations = new Set();
     /**
      * This session's one stable observability session id — stamped onto every
-     * trace this session emits (via the recorder's `defaultSessionId`, see
-     * `ObservabilityConfig.sessionId`). Always a valid UUID; the backend's
+     * trace this session emits. Always a valid UUID; the backend's
      * `obs_sessions.id` column is UUID-typed, so a non-UUID id (e.g. the
      * legacy `contextId` default of the literal string `'default'`) can never
      * form a session and traces stamped with it can never be grouped.
@@ -157,19 +143,6 @@ class ArmorIQSession {
      *   3. A freshly minted `crypto.randomUUID()` (default — no arg needed).
      */
     sessionId;
-    /**
-     * Model A (trace-per-plan): the ONE active observability trace for the
-     * current plan. Every chokepoint (enforce/check/report/dispatch/...)
-     * records a container span under this trace via `ensurePlanTrace()`
-     * instead of opening its own trace — matching Langfuse/OTel's
-     * Session → Trace → Observation hierarchy (one IAP plan = one trace).
-     *
-     * Lifecycle: opened by `ensurePlanTrace()` (called from `startPlan()` or
-     * lazily by any chokepoint invoked before `startPlan()` — back-compat);
-     * ended by `endPlanTrace()`, called on the NEXT `startPlan()`, on
-     * `close()`/`dispose()`, and on `flushObservability()`.
-     */
-    activePlanTrace = null;
     constructor(client, opts) {
         this.client = client;
         const o = opts ?? {};
@@ -182,286 +155,60 @@ class ArmorIQSession {
         const granEnv = (typeof process !== 'undefined' && process.env?.ARMORIQ_REANCHOR_GRANULARITY) || '';
         this.reanchorGranularity =
             o.reanchorGranularity ?? (granEnv === 'deferred' ? 'deferred' : 'eager');
-        this.sessionId = (0, observability_1.isValidUuid)(o.sessionId)
+        this.sessionId = isValidUuid(o.sessionId)
             ? o.sessionId
-            : (0, observability_1.isValidUuid)(o.contextId)
+            : isValidUuid(o.contextId)
                 ? o.contextId
                 : (0, crypto_1.randomUUID)();
         const obsCfg = o.observability;
-        if (obsCfg?.enabled === false) {
-            this.obs = null;
-        }
-        else {
+        const nativeConfig = (0, observability_1.resolveOtelConfig)(obsCfg ?? {});
+        if (nativeConfig.enabled) {
             const internals = this.client._sessionInternals();
-            const endpoint = obsCfg?.endpoint ?? internals.backendEndpoint;
-            const apiKey = obsCfg?.apiKey ?? internals.apiKey;
-            const product = obsCfg?.product ?? config_1.DEFAULT_OBSERVABILITY_PRODUCT;
-            // Reuse the session's configured httpClient (consumer interceptors,
-            // test mocks) unless the caller explicitly overrides it via
-            // `observability.httpClient`. Without this, the shipper falls back to
-            // its own bare `axios.create(...)` and silently bypasses whatever
-            // transport the rest of the SDK uses — including test mocks, which
-            // then fire real network POSTs from the shipper's flush interval.
-            const httpClient = obsCfg?.httpClient ?? internals.httpClient;
-            // `internals.userId`/`internals.agentId` default to `''` (see the
-            // `ArmorIQClient` constructor) when the caller configured neither an
-            // option nor the corresponding env var, then to the multi-user
-            // placeholder — normalize both to `null` so an unconfigured identity
-            // reads as genuinely absent on the trace rather than shipping an empty
-            // string or a fake agent id.
-            const nonEmpty = (v) => realIdentity(v) ?? null;
-            // `internals.userId` is `client.userEmailOverride || client.userId`
-            // (client.ts) — an arbitrary identity string (often an email address,
-            // or the multi-user placeholder `'__sdk_multiuser__'`), NOT guaranteed
-            // to be a UUID. The observability trace's `userId` column/wire schema
-            // IS UUID-typed (`z.uuid()` on the backend) — forwarding a non-UUID
-            // value 400s the entire ingest batch at the shipper. Validate before
-            // forwarding; a non-UUID userId is dropped to `null` rather than
-            // breaking ingestion (`agentId` has no such constraint — see below).
-            const validUserId = (v) => (0, observability_1.isValidUuid)(v) ? v : null;
-            const merged = {
-                ...(0, config_1.defaultObservabilityConfig)(),
-                ...(obsCfg ?? {}),
-                enabled: true,
-                endpoint,
-                apiKey,
-                product,
-                httpClient,
-                // The session's one stable UUID — applied to every trace this
-                // recorder starts unless a chokepoint explicitly overrides it (none
-                // do; see the `startTrace(...)` call sites below, all of which now
-                // pass `this.sessionId` directly for clarity/back-compat).
-                sessionId: obsCfg?.sessionId ?? this.sessionId,
-                // Denormalize the client's configured user/agent identity onto every
-                // trace this recorder starts, unless the caller explicitly overrides
-                // via `observability.userId`/`observability.agentId`. `internals`
-                // already carries both (see `ArmorIQClient._sessionInternals()`);
-                // previously neither was forwarded here, so every SDK-emitted trace
-                // shipped with `agentId: null` even when the client was constructed
-                // with a real agent id. `agentId` is a free-form string on the wire
-                // (backend column is `text`, not a UUID FK) — no UUID validation
-                // required, unlike `sessionId`/`userId`.
-                userId: obsCfg?.userId ?? validUserId(internals.userId),
-                agentId: obsCfg?.agentId ?? nonEmpty(internals.agentId),
-            };
-            this.obs = new observability_1.ObservabilityRecorder(merged);
+            const runtime = new observability_1.ArmorIQTelemetryRuntime({
+                backendEndpoint: internals.backendEndpoint,
+                apiKey: internals.apiKey,
+                sdkVersion: _version_1.VERSION,
+                options: obsCfg,
+            });
+            this.otel = new observability_1.OtelSession(runtime, {
+                sessionId: this.sessionId,
+                traceName: 'armoriq.agent.run',
+                agentId: realIdentity(internals.agentId) ?? null,
+                // Never use a user email as an external Langfuse user id implicitly.
+                // Callers may opt in with an explicit safe `observability.userId`.
+                userId: obsCfg?.userId ?? null,
+            });
         }
     }
-    /**
-     * The session's `ObservabilityRecorder`, or `null` when observability is
-     * disabled for this session. Pass this explicitly to
-     * `summarizeTranscriptUsage(path, recorder, ctx)` / `client.captureTranscriptTokens({
-     * ..., observabilityRecorder, planTraceCtx })` so transcript-derived generation spans are
-     * attributed to the correct session — the SDK no longer keeps a
-     * process-global "active recorder" (see #4: concurrent sessions would
-     * otherwise misattribute usage to whichever session constructed last).
-     */
-    get observabilityRecorder() {
-        return this.obs;
+    /** Native request-scoped OTel bridge for framework adapters. */
+    get otelSession() {
+        return this.otel;
     }
     /**
-     * Model A (Task 4): the session's active plan trace context, or `null` if
-     * none is open yet (lazily opens on first use — same as every chokepoint).
-     * Pass this as `summarizeTranscriptUsage(path, session.observabilityRecorder,
-     * session.activePlanTraceContext)` (or via
-     * `client.captureTranscriptTokens({ ..., planTraceCtx: session.activePlanTraceContext })`)
-     * so transcript-derived generation spans nest under the SAME plan trace as
-     * every other chokepoint this session recorded, instead of opening a
-     * standalone `llm.usage.report` trace.
+     * Explicitly await the observability policy control-plane refresh. Request
+     * hooks must not call this: their native telemetry remains fail-open and
+     * latency-free while the SDK refreshes in the background.
      */
-    get activePlanTraceContext() {
-        return this.obs ? this.ensurePlanTrace() : null;
-    }
-    // ─── Model A: active-plan-trace lifecycle ──────────────────────
-    /**
-     * Return the session's active plan trace, lazily opening one if none is
-     * active. This is the ONE trace every chokepoint's container span nests
-     * under (Model A: trace-per-plan). Returns `null` when observability is
-     * disabled — every call site already treats a null ctx as "skip emit".
-     *
-     * Back-compat (plan §"Global Constraints"): a chokepoint invoked with no
-     * prior `startPlan()` (e.g. a standalone `enforceLocal()`/`report()` call)
-     * still needs to emit — so this opens a plan trace lazily on first use
-     * rather than requiring `startPlan()` to have run first.
-     */
-    ensurePlanTrace(name = 'iap.plan', attrs = {}) {
-        if (!this.obs)
-            return null;
-        if (this.activePlanTrace)
-            return this.activePlanTrace;
-        const ctx = safeObs(() => (0, observability_1.startTrace)(this.obs, name, attrs, this.sessionId)) ?? null;
-        this.activePlanTrace = ctx;
-        return ctx;
-    }
-    /**
-     * End the active plan trace (if any) and clear it. Called on the NEXT
-     * `startPlan()` (closing the PRIOR plan before opening a new one),
-     * `close()`/`dispose()`, and `flushObservability()` — so the in-flight
-     * plan trace always ships before the process exits or a new plan begins.
-     */
-    endPlanTrace(status = 'ok') {
-        if (!this.obs || !this.activePlanTrace)
-            return;
-        const ctx = this.activePlanTrace;
-        this.activePlanTrace = null;
-        safeObs(() => (0, observability_1.endTrace)(this.obs, ctx, { status }));
+    async refreshObservabilityPolicy() {
+        await this.otel?.refreshPolicy();
     }
     // ─── Plan capture ──────────────────────────────────────────────
     async reanchorCall(intentToken, plan, reason) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.reanchor',
-                attributes: { reason, planStepCount: plan?.steps?.length ?? null },
-            })) ?? undefined
-            : undefined;
-        let caught;
-        let trustId;
-        try {
-            const result = await this.client.reanchor(intentToken, plan, reason);
-            trustId = result?.trustId;
-            if (ctx) {
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.reanchor.delta', {
-                    kind: 'event',
-                    message: 'delta recorded',
-                    level: 'info',
-                    trustId: trustId ?? null,
-                }, spanId)));
-            }
-            return { trustId };
-        }
-        catch (err) {
-            caught = err;
-            if (ctx) {
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.reanchor.delta_failed', {
-                    kind: 'event',
-                    message: `delta failed: ${err.message}`,
-                    level: 'error',
-                }, spanId)));
-            }
-            throw err;
-        }
-        finally {
-            if (ctx) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'iap.reanchor.http', {
-                    kind: 'span',
-                    trustId: trustId ?? null,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }, caught ? 'error' : 'ok', computedDuration ?? null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: caught ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: caught instanceof Error ? caught.message : undefined,
-                    }));
-                }
-            }
-        }
+        const result = await this.client.reanchor(intentToken, plan, reason);
+        return { trustId: result?.trustId };
     }
     async getIntentTokenCall(planCapture, validitySeconds) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.intent_token.mint',
-                attributes: { planStepCount: planCapture?.plan?.steps?.length ?? null },
-            })) ?? undefined
-            : undefined;
-        let caught;
-        let token;
-        try {
-            token = await this.client.getIntentToken(planCapture, undefined, validitySeconds);
-            if (ctx) {
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.intent_token.minted', {
-                    kind: 'event',
-                    message: 'new intent token minted',
-                    level: 'info',
-                    tokenId: token?.tokenId ?? null,
-                    planId: token?.planId ?? null,
-                }, spanId)));
-            }
-            return token;
-        }
-        catch (err) {
-            caught = err;
-            throw err;
-        }
-        finally {
-            if (ctx) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'iap.intent_token.mint.http', {
-                    kind: 'span',
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }, caught ? 'error' : 'ok', computedDuration ?? null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: caught ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: caught instanceof Error ? caught.message : undefined,
-                    }));
-                }
-            }
-        }
+        return this.client.getIntentToken(planCapture, undefined, validitySeconds);
     }
     async startPlan(toolCalls, goal) {
-        const startNs = this.obs ? performance.now() : 0;
-        // Model A: close the PRIOR plan's trace (if any) before opening the new
-        // one — one IAP plan = one trace, so a new startPlan() is a plan
-        // boundary. Then open the new active plan trace and record a
-        // container span (`iap.plan.start`) for this call's own work, nested
-        // under it exactly like every other chokepoint's container span.
-        if (this.obs)
-            safeObs(() => this.endPlanTrace('ok'));
-        const ctx = this.obs
-            ? this.ensurePlanTrace('iap.plan', {
-                toolCount: toolCalls?.length ?? 0,
-                goal: goal ?? null,
-                mode: this.mode,
-            })
-            : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.plan.start',
-                attributes: {
-                    toolCount: toolCalls?.length ?? 0,
-                    goal: goal ?? null,
-                    mode: this.mode,
-                },
-            })) ?? undefined
-            : undefined;
-        let planTraceStatus = 'ok';
-        let planTraceError;
-        try {
-            const result = await this._startPlanImpl(toolCalls, goal, ctx);
-            if (ctx) {
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'iap.plan.grew', {
-                    kind: 'event',
-                    message: `plan captured: ${toolCalls?.length ?? 0} tool(s)`,
-                    level: 'info',
-                    toolCount: toolCalls?.length ?? 0,
-                })));
-            }
-            return result;
-        }
-        catch (err) {
-            planTraceStatus = 'error';
-            planTraceError = err.message;
-            throw err;
-        }
-        finally {
-            if (ctx && spanId) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                    status: planTraceStatus === 'error' ? 'error' : 'ok',
-                    durationMs: computedDuration,
-                    errorMessage: planTraceError,
-                }));
-            }
-        }
+        const result = await this._startPlanImpl(toolCalls, goal);
+        await this.otel?.startPlan({
+            itemCount: toolCalls.length,
+            planId: result.planId ?? result.tokenId,
+        });
+        return result;
     }
-    async _startPlanImpl(toolCalls, goal, _ctx) {
+    async _startPlanImpl(toolCalls, goal) {
         if (!toolCalls || toolCalls.length === 0) {
             throw new Error('startPlan called with no tool calls.');
         }
@@ -561,58 +308,21 @@ class ArmorIQSession {
         return token;
     }
     // ─── Policy enforcement ────────────────────────────────────────
-    /**
-     * `parentContainerSpanId` is an internal-only hook (not part of the public
-     * signature contract other SDK consumers rely on — it's simply an extra
-     * optional trailing arg) so `check()` can nest this call's container span
-     * under `iap.check`'s own container span instead of both sitting as
-     * siblings directly under the plan trace (Task 3 risk: "check → enforce
-     * double-open" — `iap.check`'s span wraps the dispatched enforce span,
-     * it never opens a second redundant plan trace or duplicate container).
-     */
-    enforceLocal(toolName, toolArgs, parentContainerSpanId) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.enforce.local',
-                attributes: { toolName, toolArgs: truncateForSpan(toolArgs) },
-                parentSpanId: parentContainerSpanId ?? null,
-            })) ?? undefined
-            : undefined;
-        let caught;
-        try {
-            return this._enforceLocalImpl(toolName, toolArgs, ctx, spanId);
-        }
-        catch (err) {
-            caught = err;
-            throw err;
-        }
-        finally {
-            if (ctx && spanId) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                    status: caught ? 'error' : 'ok',
-                    durationMs: computedDuration,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }));
-            }
-        }
+    enforceLocal(toolName, toolArgs) {
+        const decision = this._enforceLocalImpl(toolName, toolArgs);
+        this.trackPolicyTelemetry(this.recordPolicyDecision(toolName, toolArgs, decision));
+        return decision;
     }
-    _enforceLocalImpl(toolName, toolArgs, ctx, spanId) {
+    _enforceLocalImpl(toolName, toolArgs) {
         if (!this.currentToken) {
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: 'No intent token — call startPlan() first',
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', {}, spanId);
-            return r;
         }
         if (models_1.IntentToken.isExpired(this.currentToken)) {
-            const r = { allowed: false, action: 'block', reason: 'token-expired' };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', {}, spanId);
-            return r;
+            return { allowed: false, action: 'block', reason: 'token-expired' };
         }
         // The local decision is read from the token's policy fields, so the token
         // must be cryptographically authentic first - otherwise a forged token
@@ -622,22 +332,18 @@ class ArmorIQSession {
         // the token. Fail CLOSED if the key is unavailable or the signature is bad.
         const iapKey = this.client.iapPublicKeySync();
         if (!iapKey || !(0, crypto_verify_1.verifyEdDSAJwt)(this.currentToken.jwtToken ?? '', iapKey)) {
-            const r = { allowed: false, action: 'block', reason: 'token-signature-invalid' };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', {}, spanId);
-            return r;
+            return { allowed: false, action: 'block', reason: 'token-signature-invalid' };
         }
         const { mcp, action } = this.toolNameParser(toolName);
         const inPlan = this.declaredTools.has(toolName) ||
             this.declaredTools.has(action) ||
             this.declaredTools.has(`${mcp}__${action}`);
         if (!inPlan) {
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: `tool-not-in-plan: '${toolName}' was not declared in the captured plan`,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp }, spanId);
-            return r;
         }
         const pv = (this.currentToken.policyValidation ?? {});
         const snapshot = (this.currentToken.policySnapshot ?? []);
@@ -682,14 +388,12 @@ class ArmorIQSession {
                         : `Tool '${action}' is denied by policy`);
                 // Deny-precedence: an explicitly denied tool is never allowed, even when
                 // the default action is 'allow'. hold only if the policy default is hold.
-                const r = {
+                return {
                     allowed: false,
                     action: defaultAction === 'hold' ? 'hold' : 'block',
                     reason,
                     matchedPolicy: governingPolicyName,
                 };
-                this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
-                return r;
             }
         }
         // Honor the backend-baked resolved allow set: an explicit *empty*
@@ -697,42 +401,34 @@ class ArmorIQSession {
         // ⇒ deny-all, regardless of what any individual snapshot rule allows.
         const bakedAllowedTools = pv.allowed_tools;
         if (Array.isArray(bakedAllowedTools) && bakedAllowedTools.length === 0) {
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: `Tool '${action}' is not allowed by any policy in scope (empty resolved allow-list)`,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
-            return r;
         }
         if (governingRule) {
             const allowed = governingRule.allowedTools ?? [];
             if (Array.isArray(allowed) && allowed.length > 0) {
-                const ok = allowed.includes('*') ||
-                    allowed.includes(action) ||
-                    allowed.includes(toolName);
+                const ok = allowed.includes('*') || allowed.includes(action) || allowed.includes(toolName);
                 if (!ok) {
                     // Tool is outside this rule's explicit allow set. Fall back to the
                     // policy default action: an 'allow' default permits it, hold/block
                     // otherwise.
                     if (defaultAction === 'allow') {
-                        const r = {
+                        return {
                             allowed: true,
                             action: 'allow',
                             reason: `Allowed by default enforcement action for policy '${governingPolicyName}'`,
                             matchedPolicy: governingPolicyName,
                         };
-                        this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
-                        return r;
                     }
-                    const r = {
+                    return {
                         allowed: false,
                         action: defaultAction,
                         reason: `Tool '${action}' is not in the allowed tools for policy '${governingPolicyName}'`,
                         matchedPolicy: governingPolicyName,
                     };
-                    this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
-                    return r;
                 }
             }
         }
@@ -740,102 +436,83 @@ class ArmorIQSession {
             const thresholdDecision = this.evaluateAmountThreshold(governingRule, toolArgs, action, mcp);
             if (thresholdDecision) {
                 thresholdDecision.matchedPolicy = governingPolicyName;
-                this._emitEnforcePolicyCall(ctx, toolName, thresholdDecision, 'sdk-local', { mcp, policyValidation: pv }, spanId);
                 return thresholdDecision;
             }
         }
-        const r = {
+        return {
             allowed: true,
             action: 'allow',
             reason: 'Allowed by local policy evaluation',
             matchedPolicy: governingPolicyName,
         };
-        this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk-local', { mcp, policyValidation: pv }, spanId);
-        return r;
     }
-    _emitEnforcePolicyCall(ctx, toolName, result, source, extras, parentSpanId) {
-        if (!ctx || !this.obs)
-            return;
-        const decision = result.action === 'allow'
-            ? 'allow'
-            : result.action === 'hold'
-                ? 'hold'
-                : 'deny';
-        const enforcementAction = result.action;
-        safeObs(() => (0, observability_1.recordPolicyCall)(this.obs, ctx, {
-            policyId: null,
-            policyName: result.matchedPolicy ?? null,
-            decision,
-            reason: result.reason ?? null,
-            source,
-            input: { toolName },
-            output: {
-                allowed: result.allowed,
-                action: result.action,
-                matchedPolicy: result.matchedPolicy ?? null,
-                delegationId: result.delegationId ?? null,
-            },
-            policyHash: null,
-            policyVersion: null,
-            matchedRuleId: null,
-            dataClasses: [],
-            enforcementAction,
-            obligations: extras.obligations ?? result.obligations ?? [],
-            delegationId: result.delegationId ?? null,
-        }, parentSpanId));
+    /**
+     * A server named in the tool itself wins; the plan's action map only answers
+     * for unqualified names. The map keeps one server per action, so with
+     * `stripe__search` and `github__search` both planned it would otherwise send
+     * the last one for either call.
+     */
+    resolveMcp(toolName, mcp, action) {
+        if (toolName !== action)
+            return mcp;
+        return this.mcpByAction.get(action) ?? mcp;
     }
-    /** See `enforceLocal`'s doc comment re: `parentContainerSpanId` (internal-only hook for `check()`). */
-    async enforceSdk(toolName, toolArgs, userEmail, parentContainerSpanId) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.enforce.sdk',
-                attributes: { toolName, toolArgs: truncateForSpan(toolArgs), userEmail: userEmail ?? null },
-                parentSpanId: parentContainerSpanId ?? null,
-            })) ?? undefined
-            : undefined;
-        let caught;
+    /**
+     * The two fields the tool inventory attributes a call with. `wireName` is the
+     * name the framework dispatched, untouched. `mcpServer` is sent only when the
+     * SDK actually knows the server (the name carried it, or the bootstrap toolMap
+     * named it); a default fallback is a guess and is left out so the backend
+     * attributes from its own declarations.
+     */
+    /** `toolsSnapshotHash` when this client has an inventory; conmap answers `inventoryUnknown` if it holds no snapshot under it. */
+    snapshotHashField() {
         try {
-            return await this._enforceSdkImpl(toolName, toolArgs, userEmail, ctx, spanId);
+            const key = (0, tool_registry_1.agentKeyFor)(this.client);
+            return key ? { toolsSnapshotHash: (0, tool_registry_1.defaultToolRegistry)().snapshotHash(key) } : {};
         }
-        catch (err) {
-            caught = err;
-            throw err;
+        catch {
+            return {};
         }
-        finally {
-            if (ctx && spanId) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                    status: caught ? 'error' : 'ok',
-                    durationMs: computedDuration,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }));
-            }
+    }
+    inventoryFields(toolName, action, resolvedMcp) {
+        const fields = { wireName: toolName };
+        if (toolName !== action ||
+            (resolvedMcp && resolvedMcp !== this.defaultMcpName && resolvedMcp !== 'unknown')) {
+            fields.mcpServer = resolvedMcp;
         }
+        return fields;
+    }
+    async enforceSdk(toolName, toolArgs, userEmail) {
+        const decision = await this._enforceSdkImpl(toolName, toolArgs, userEmail);
+        await this.recordPolicyDecision(toolName, toolArgs, decision);
+        return decision;
     }
-    async _enforceSdkImpl(toolName, toolArgs, userEmail, ctx, spanId) {
+    async _enforceSdkImpl(toolName, toolArgs, userEmail) {
         if (!this.currentToken) {
             throw new Error(`enforceSdk("${toolName}") called before startPlan().`);
         }
         const { mcp, action } = this.toolNameParser(toolName);
-        const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+        const resolvedMcp = this.resolveMcp(toolName, mcp, action);
         const inPlan = this.declaredTools.has(toolName) ||
             this.declaredTools.has(action) ||
             this.declaredTools.has(`${resolvedMcp}__${action}`);
         if (!inPlan) {
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: `tool-not-in-plan: '${toolName}' was not declared in the captured plan`,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp }, spanId);
-            return r;
         }
         const internals = this.client._sessionInternals();
         try {
             const response = await internals.httpClient.post(`${internals.backendEndpoint}/iap/sdk/enforce`, {
+                // The server the call resolved to. Without it a policy rule bound to
+                // a server never matches, and shared tool names stay ambiguous to the
+                // inventory. Matches the Python SDK (armoriq-sdk-customer#139).
+                mcp: resolvedMcp,
                 tool: action,
+                ...this.inventoryFields(toolName, action, resolvedMcp),
+                ...this.snapshotHashField(),
                 arguments: toolArgs,
                 intent_token: this.currentToken.rawToken,
                 policy_snapshot: this.currentToken.policySnapshot,
@@ -846,11 +523,11 @@ class ArmorIQSession {
                 timeout: 10000,
             });
             const data = response.data ?? {};
+            if (data.inventoryUnknown === true)
+                (0, tool_push_1.requestPush)(this.client);
             const allowed = data.allowed === true;
             const actionDecision = data.enforcementAction ?? (allowed ? 'allow' : 'block');
-            const matched = typeof data.matchedPolicy === 'object'
-                ? data.matchedPolicy?.name
-                : data.matchedPolicy;
+            const matched = typeof data.matchedPolicy === 'object' ? data.matchedPolicy?.name : data.matchedPolicy;
             // Surface gating obligations metadata (additive). The backend has already
             // collapsed gating into allowed/action; obligations explain *why*.
             const obligations = Array.isArray(data.obligations)
@@ -864,77 +541,45 @@ class ArmorIQSession {
                     matchedPolicy: matched,
                     obligations,
                 };
-                this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp, obligations }, spanId);
                 return this.handleHold(toolName, toolArgs, r, userEmail);
             }
-            const r = {
+            return {
                 allowed,
                 action: actionDecision,
                 reason: data.reason ?? data.message,
                 matchedPolicy: matched,
                 obligations,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp, obligations }, spanId);
-            return r;
         }
         catch (e) {
             console.error(`enforceSdk() failed: ${e.message}. Blocking tool call (fail-closed).`);
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: `enforce-unavailable: ${e.message}`,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'sdk', { mcp: resolvedMcp }, spanId);
-            return r;
         }
     }
-    /** See `enforceLocal`'s doc comment re: `parentContainerSpanId` (internal-only hook for `check()`). */
-    async enforce(toolName, toolArgs, parentContainerSpanId) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.enforce.proxy',
-                attributes: { toolName, toolArgs: truncateForSpan(toolArgs) },
-                parentSpanId: parentContainerSpanId ?? null,
-            })) ?? undefined
-            : undefined;
-        let caught;
-        try {
-            return await this._enforceImpl(toolName, toolArgs, ctx, spanId);
-        }
-        catch (err) {
-            caught = err;
-            throw err;
-        }
-        finally {
-            if (ctx && spanId) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                    status: caught ? 'error' : 'ok',
-                    durationMs: computedDuration,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }));
-            }
-        }
+    async enforce(toolName, toolArgs) {
+        const decision = await this._enforceImpl(toolName, toolArgs);
+        await this.recordPolicyDecision(toolName, toolArgs, decision);
+        return decision;
     }
-    async _enforceImpl(toolName, toolArgs, ctx, spanId) {
+    async _enforceImpl(toolName, toolArgs) {
         if (!this.currentToken) {
             throw new Error(`enforce("${toolName}") called before startPlan().`);
         }
         const { mcp, action } = this.toolNameParser(toolName);
-        const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+        const resolvedMcp = this.resolveMcp(toolName, mcp, action);
         const inPlan = this.declaredTools.has(toolName) ||
             this.declaredTools.has(action) ||
             this.declaredTools.has(`${resolvedMcp}__${action}`);
         if (!inPlan) {
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: `tool-not-in-plan: '${toolName}' was not declared in the captured plan`,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
-            return r;
         }
         const internals = this.client._sessionInternals();
         try {
@@ -961,18 +606,16 @@ class ArmorIQSession {
             // Fail closed: only an explicit allow from a 2xx response permits the call.
             // Any error status (403 or otherwise) or an ambiguous body blocks.
             if (response.status >= 400) {
-                const r = {
+                return {
                     allowed: false,
                     action: data.action ?? 'block',
                     reason: data.reason ?? data.message ?? `enforce-rejected: HTTP ${response.status}`,
                     matchedPolicy: policyName,
                 };
-                this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
-                return r;
             }
             const allowedFlag = data.allowed === true;
             const actionDecision = data.enforcementAction ?? data.action ?? (allowedFlag ? 'allow' : 'block');
-            const r = {
+            return {
                 allowed: allowedFlag,
                 action: actionDecision,
                 reason: data.reason,
@@ -980,78 +623,82 @@ class ArmorIQSession {
                 matchedPolicy: policyName,
                 obligations: Array.isArray(data.obligations) ? data.obligations : [],
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
-            return r;
         }
         catch (e) {
             console.error(`enforce() failed: ${e.message}. Blocking tool call (fail-closed).`);
-            const r = {
+            return {
                 allowed: false,
                 action: 'block',
                 reason: `enforce-unavailable: ${e.message}`,
             };
-            this._emitEnforcePolicyCall(ctx, toolName, r, 'proxy', { mcp: resolvedMcp }, spanId);
-            return r;
         }
     }
-    async check(toolName, toolArgs, userEmail) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        // Task 3 risk — "check → enforce double-open": `check` opens its OWN
-        // `iap.check` container span (nested under the single active plan
-        // trace, never a second trace), then passes this span's id as the
-        // PARENT for whichever enforce* it dispatches into. The dispatched
-        // enforce's container span therefore nests under `iap.check`'s span —
-        // it does not open a redundant plan trace or a sibling/duplicate
-        // container span.
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.check',
-                attributes: {
-                    toolName,
-                    toolArgs: truncateForSpan(toolArgs),
-                    mode: this.mode,
-                    userEmail: userEmail ?? null,
-                },
-            })) ?? undefined
-            : undefined;
-        let caught;
-        try {
-            if (this.mode === 'sdk') {
-                return await this.enforceSdk(toolName, toolArgs, userEmail, spanId);
-            }
-            if (this.mode === 'local') {
-                await this.warmToolMetadata(toolName);
-                const decision = this.enforceLocal(toolName, toolArgs, spanId);
-                if (decision.action === 'hold') {
-                    return {
-                        ...decision,
-                        action: 'block',
-                        reason: (decision.reason ?? 'requires approval') +
-                            ' — switch ARMORIQ_MODE=proxy to enable approval workflows for this action.',
-                    };
-                }
-                return decision;
+    async check(toolName, toolArgs, userEmail, telemetry = {}) {
+        let decision;
+        if (this.mode === 'sdk') {
+            decision = await this._enforceSdkImpl(toolName, toolArgs, userEmail);
+        }
+        else if (this.mode === 'local') {
+            await this.warmToolMetadata(toolName);
+            decision = this._enforceLocalImpl(toolName, toolArgs);
+            if (decision.action === 'hold') {
+                decision = {
+                    ...decision,
+                    action: 'block',
+                    reason: (decision.reason ?? 'requires approval') +
+                        ' — switch ARMORIQ_MODE=proxy to enable approval workflows for this action.',
+                };
             }
-            const decision = await this.enforce(toolName, toolArgs, spanId);
-            if (decision.action !== 'hold')
-                return decision;
-            return this.handleHold(toolName, toolArgs, decision, userEmail);
-        }
-        catch (err) {
-            caught = err;
-            throw err;
         }
-        finally {
-            if (ctx && spanId) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                    status: caught ? 'error' : 'ok',
-                    durationMs: computedDuration,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }));
+        else {
+            decision = await this._enforceImpl(toolName, toolArgs);
+            if (decision.action === 'hold') {
+                decision = await this.handleHold(toolName, toolArgs, decision, userEmail);
             }
         }
+        if (telemetry.emitOtel !== false) {
+            await this.recordPolicyDecision(toolName, toolArgs, decision);
+        }
+        return decision;
+    }
+    async recordPolicyDecision(toolName, toolArgs, decision) {
+        if (!this.otel)
+            return;
+        const policy = decision;
+        const failed = typeof decision.reason === 'string' && decision.reason.startsWith('enforce-unavailable:');
+        const policyDecision = decision.allowed
+            ? 'allow'
+            : decision.action === 'hold'
+                ? 'hold'
+                : decision.action === 'block'
+                    ? 'block'
+                    : undefined;
+        await this.otel.recordPolicy({ toolName, arguments: toolArgs }, {
+            ...(!failed && policyDecision ? { decision: policyDecision } : {}),
+            policyName: decision.matchedPolicy,
+            ...(typeof policy.policyId === 'string' ? { policyId: policy.policyId } : {}),
+            ...(typeof policy.policyVersion === 'string'
+                ? { policyVersion: policy.policyVersion }
+                : {}),
+            ...(typeof policy.policySource === 'string' ? { policySource: policy.policySource } : {}),
+            ...(typeof policy.matchedRuleId === 'string'
+                ? { matchedRuleId: policy.matchedRuleId }
+                : {}),
+            policyReasonCode: decision.reason,
+            ...(failed ? { error: new Error('policy evaluation failed') } : {}),
+            ...(typeof policy.defaultAction === 'string'
+                ? { defaultAction: policy.defaultAction }
+                : {}),
+        });
+    }
+    trackPolicyTelemetry(operation) {
+        const tracked = operation
+            .catch(() => undefined)
+            .finally(() => this.pendingPolicyTelemetry.delete(tracked));
+        this.pendingPolicyTelemetry.add(tracked);
+    }
+    async drainPolicyTelemetry() {
+        await Promise.all([...this.pendingPolicyTelemetry]);
     }
     // ─── Report / dispatch ─────────────────────────────────────────
     async report(toolName, toolArgs, result, opts) {
@@ -1061,50 +708,28 @@ class ArmorIQSession {
                 ? Math.round(opts.durationMs)
                 : opts?.durationMs,
         };
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'tool.report',
-                attributes: {
-                    toolName,
-                    toolInput: truncateForSpan(toolArgs),
-                    status: o.status ?? 'success',
-                },
-            })) ?? undefined
-            : undefined;
         let reportStatus = 'ok';
         let reportError;
+        const reportItemOrdinal = this.stepIndex;
+        let reportOperation = this.operationForTool(toolName, undefined, reportItemOrdinal, o.operation);
         try {
             const { mcp, action } = this.toolNameParser(toolName);
-            const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+            const resolvedMcp = this.resolveMcp(toolName, mcp, action);
+            if (o.emitOtel !== false) {
+                reportOperation = this.operationForTool(toolName, resolvedMcp, reportItemOrdinal, o.operation);
+            }
             const internals = this.client._sessionInternals();
             try {
                 const token = this.currentToken;
-                const userEmail = this.userEmail ?? this.client.userEmailOverride;
-                let output = result;
-                if (typeof result === 'string')
-                    output = { text: result };
-                else if (result === null || result === undefined)
-                    output = {};
-                await internals.httpClient.post(`${internals.backendEndpoint}/iap/audit`, {
-                    token: token?.jwtToken ?? token?.tokenId ?? 'unknown',
-                    plan_id: token?.planId ?? token?.tokenId ?? 'unknown',
-                    step_index: this.stepIndex,
+                await internals.httpClient.post(`${internals.backendEndpoint}/iap/audit`, auditPersistencePayload({
+                    token,
+                    stepIndex: this.stepIndex,
                     action,
-                    tool: action,
                     mcp: resolvedMcp,
-                    input: toolArgs,
-                    output,
                     status: o.status ?? 'success',
-                    error_message: o.errorMessage,
-                    duration_ms: o.durationMs,
-                    is_delegated: o.isDelegated,
-                    delegated_by: o.delegatedBy,
-                    user_email: userEmail,
-                    delegated_to: o.delegatedTo,
-                    executed_at: new Date().toISOString(),
-                }, {
+                    durationMs: o.durationMs,
+                    isDelegated: o.isDelegated,
+                }), {
                     headers: { 'X-API-Key': internals.apiKey, 'Content-Type': 'application/json' },
                     timeout: 5000,
                 });
@@ -1120,49 +745,43 @@ class ArmorIQSession {
             throw err;
         }
         finally {
-            if (ctx) {
-                const computedDuration = o.durationMs ?? (startNs > 0 ? Math.round(performance.now() - startNs) : undefined);
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'tool.report', {
-                    kind: 'span',
+            if (o.emitOtel !== false) {
+                await this.otel?.recordTool({
                     toolName,
-                    toolInput: truncateForSpan(toolArgs),
-                    toolOutput: truncateForSpan(result),
-                    // `status` here is the caller-supplied tool outcome
-                    // ('success'|'failed'|'error' from ReportOptions), a distinct
-                    // side-channel signal from the top-level SpanRecord.status
-                    // ('ok'|'error'|'denied' span lifecycle status) below —
-                    // intentionally NOT a duplicate.
-                    status: o.status ?? 'success',
-                    errorMessage: o.errorMessage,
-                }, reportStatus === 'error' ? 'error' : 'ok', computedDuration ?? null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: reportStatus === 'error' ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: reportError,
-                    }));
-                }
+                    itemOrdinal: reportItemOrdinal,
+                    arguments: toolArgs,
+                    operation: reportOperation,
+                }, {
+                    outcome: reportStatus === 'ok' && (o.status ?? 'success') === 'success' ? 'success' : 'error',
+                    durationMs: o.durationMs,
+                    error: reportError,
+                    result,
+                });
             }
         }
     }
     async dispatch(toolName, toolArgs) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'tool.dispatch',
-                attributes: { toolName, toolInput: truncateForSpan(toolArgs) },
-            })) ?? undefined
-            : undefined;
         let dispatchResult;
         let dispatchStatus = 'ok';
         let dispatchError;
+        let nativeTool;
         try {
             if (!this.currentToken) {
                 throw new Error(`dispatch("${toolName}") called before startPlan().`);
             }
             const { mcp, action } = this.toolNameParser(toolName);
-            const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+            const resolvedMcp = this.resolveMcp(toolName, mcp, action);
+            nativeTool = await this.otel?.beginTool({
+                toolName: action,
+                itemOrdinal: this.stepIndex,
+                arguments: toolArgs,
+                operation: {
+                    category: 'mcp',
+                    name: 'mcp.execute',
+                    toolType: 'mcp',
+                    mcpServer: resolvedMcp,
+                },
+            });
             dispatchResult = await this.client.invoke(resolvedMcp, action, this.currentToken, toolArgs);
             this.stepIndex += 1;
             return dispatchResult?.result;
@@ -1173,46 +792,23 @@ class ArmorIQSession {
             throw err;
         }
         finally {
-            if (ctx) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'tool.dispatch', {
-                    kind: 'span',
-                    toolName,
-                    toolInput: truncateForSpan(toolArgs),
-                    result: truncateForSpan(dispatchResult),
-                }, dispatchStatus === 'error' ? 'error' : 'ok', computedDuration ?? null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: dispatchStatus === 'error' ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: dispatchError,
-                    }));
-                }
-            }
+            await this.otel?.endTool(nativeTool ?? { span: null, name: 'mcp.execute' }, {
+                outcome: dispatchStatus === 'ok' ? 'success' : 'error',
+                error: dispatchError,
+                ...(dispatchStatus === 'ok'
+                    ? { result: dispatchResult?.result }
+                    : {}),
+            });
         }
     }
     // ─── Helpers ────────────────────────────────────────────────────
     async handleHold(toolName, toolArgs, holdDecision, userEmail) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'delegation.hold',
-                attributes: {
-                    toolName,
-                    toolArgs: truncateForSpan(toolArgs),
-                    matchedPolicy: holdDecision.matchedPolicy ?? null,
-                },
-            })) ?? undefined
-            : undefined;
         let result;
-        let holdStatus = 'ok';
-        let holdError;
-        try {
+        {
             const internals = this.client._sessionInternals();
             const email = userEmail ?? internals.userId ?? 'unknown@armoriq';
             const { mcp, action } = this.toolNameParser(toolName);
-            const resolvedMcp = this.mcpByAction.get(action) ?? mcp;
+            const resolvedMcp = this.resolveMcp(toolName, mcp, action);
             const rawAmount = ArmorIQSession.extractAmount(toolArgs) ?? 0;
             const safeAmount = typeof rawAmount === 'number' && rawAmount >= 0.01 ? rawAmount : 0.01;
             try {
@@ -1263,6 +859,16 @@ class ArmorIQSession {
             catch (e) {
                 console.warn(`createDelegationRequest failed: ${e.message}`);
             }
+            if (delegationId) {
+                const operation = await this.otel?.beginOperation({
+                    category: 'delegation',
+                    name: 'delegation.wait',
+                    delegationId,
+                    delegationOutcome: 'pending',
+                });
+                if (operation?.span)
+                    this.pendingDelegationOperations.set(delegationId, operation);
+            }
             result = {
                 allowed: false,
                 action: 'hold',
@@ -1273,29 +879,6 @@ class ArmorIQSession {
             };
             return result;
         }
-        catch (err) {
-            holdStatus = 'error';
-            holdError = err.message;
-            throw err;
-        }
-        finally {
-            if (ctx) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'delegation.hold', {
-                    kind: 'span',
-                    delegationId: result?.delegationId ?? null,
-                    decision: result?.action ?? 'hold',
-                    errorMessage: holdError,
-                }, holdStatus === 'error' ? 'error' : 'ok', computedDuration ?? null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: holdStatus === 'error' ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: holdError,
-                    }));
-                }
-            }
-        }
     }
     /**
      * Poll a held delegation until it is decided; non-blocking (async).
@@ -1305,16 +888,13 @@ class ArmorIQSession {
      * timeout/interval are in seconds (mirrors the Python SDK await_approval).
      */
     async awaitApproval(delegationId, opts = {}) {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'delegation.poll',
-                attributes: { delegationId, timeout: opts.timeout ?? 300, interval: opts.interval ?? 5 },
-            })) ?? undefined
-            : undefined;
-        let caught;
-        let pollOutcome = 'timeout';
+        let delegationOutcome = 'expired';
+        const approvalStarted = performance.now();
+        const nativeApproval = await this.otel?.beginOperation({
+            category: 'approval',
+            name: 'approval.wait',
+            delegationId,
+        });
         try {
             const timeout = opts.timeout ?? 300;
             const interval = opts.interval ?? 5;
@@ -1322,19 +902,15 @@ class ArmorIQSession {
             const email = opts.userEmail || this.client.userId || 'unknown@armoriq';
             const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
             let waited = 0;
-            let pollCount = 0;
             while (waited < timeout) {
                 await sleep(interval);
                 waited += interval;
-                pollCount += 1;
                 let status;
                 try {
                     status = await this.client.getDelegationStatus(delegationId);
                 }
                 catch (e) {
-                    if (e instanceof exceptions_1.DelegationException &&
-                        e.statusCode &&
-                        transient.has(e.statusCode)) {
+                    if (e instanceof exceptions_1.DelegationException && e.statusCode && transient.has(e.statusCode)) {
                         const backoff = Math.min(interval * 2, 15);
                         await sleep(backoff);
                         waited += backoff;
@@ -1342,49 +918,108 @@ class ArmorIQSession {
                     }
                     throw e;
                 }
-                if (ctx) {
-                    safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeEventRecord(ctx, 'delegation.poll.tick', {
-                        kind: 'event',
-                        message: `poll #${pollCount} status=${status}`,
-                        level: 'info',
-                        delegationId,
-                    }, spanId)));
-                }
                 if (status === 'approved') {
                     await this.client.markDelegationExecuted(email, delegationId, this.currentToken?.planId);
-                    pollOutcome = 'approved';
+                    delegationOutcome = 'approved';
                     return 'approved';
                 }
                 if (status === 'rejected') {
-                    pollOutcome = 'rejected';
+                    delegationOutcome = 'denied';
                     return 'rejected';
                 }
+                if (status === 'cancelled') {
+                    delegationOutcome = 'cancelled';
+                    return 'timeout';
+                }
+                if (status === 'expired') {
+                    delegationOutcome = 'expired';
+                    return 'timeout';
+                }
             }
-            pollOutcome = 'timeout';
+            delegationOutcome = 'expired';
             return 'timeout';
         }
         catch (err) {
-            caught = err;
+            delegationOutcome = isCancellation(err) ? 'cancelled' : 'failed';
             throw err;
         }
         finally {
-            if (ctx) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'delegation.poll.terminal', {
-                    kind: 'span',
-                    delegationId,
-                    decision: pollOutcome,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }, caught ? 'error' : 'ok', computedDuration ?? null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: caught ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: caught instanceof Error ? caught.message : undefined,
-                    }));
+            const approvalOutcome = delegationOutcome;
+            await this.otel?.endOperation(nativeApproval ?? { span: null, name: 'approval.wait' }, {
+                category: 'approval',
+                name: 'approval.wait',
+                delegationId,
+                approvalOutcome,
+                approvalWaitMs: Math.max(0, Math.round(performance.now() - approvalStarted)),
+            });
+            await this.finalizeDelegationOperation(delegationId, delegationOutcome);
+        }
+    }
+    operationForTool(toolName, mcpServer, planItemOrdinal, override) {
+        if (override) {
+            return {
+                ...override,
+                mcpServer: override.mcpServer ?? mcpServer,
+                toolName,
+                planItemOrdinal,
+            };
+        }
+        return {
+            category: 'tool',
+            name: 'tool.execute',
+            toolType: 'function',
+            toolName,
+            planItemOrdinal,
+        };
+    }
+    async finalizeDelegationOperation(delegationId, delegationOutcome) {
+        if (this.completedDelegations.has(delegationId))
+            return;
+        const terminal = this.delegationTerminalOperations.get(delegationId);
+        if (terminal)
+            return terminal;
+        const finalization = (async () => {
+            const pending = this.pendingDelegationOperations.get(delegationId);
+            this.pendingDelegationOperations.delete(delegationId);
+            if (pending) {
+                try {
+                    // Span names are immutable: finish the measured wait as a wait, then
+                    // record the canonical terminal operation separately.
+                    await this.otel?.endOperation(pending, {
+                        category: 'delegation',
+                        name: 'delegation.wait',
+                        delegationId,
+                        delegationOutcome,
+                    });
+                }
+                finally {
+                    await this.otel?.recordOperation({
+                        category: 'delegation',
+                        name: 'delegation.complete',
+                        delegationId,
+                        delegationOutcome,
+                    });
                 }
             }
-        }
+            else {
+                await this.otel?.recordOperation({
+                    category: 'delegation',
+                    name: 'delegation.complete',
+                    delegationId,
+                    delegationOutcome,
+                });
+            }
+            try {
+                this.completedDelegations.add(delegationId);
+                if (this.completedDelegations.size > 256)
+                    this.completedDelegations.delete(this.completedDelegations.values().next().value);
+            }
+            finally {
+                this.delegationTerminalOperations.delete(delegationId);
+            }
+        })();
+        this.delegationTerminalOperations.set(delegationId, finalization);
+        return finalization;
     }
     static extractAmount(args) {
         if (!args || typeof args !== 'object')
@@ -1509,20 +1144,6 @@ class ArmorIQSession {
      *     reanchor is off
      */
     async flushReanchor() {
-        const startNs = this.obs ? performance.now() : 0;
-        const ctx = this.obs ? this.ensurePlanTrace() : null;
-        const spanId = ctx && this.obs
-            ? safeObs(() => (0, observability_1.openSpan)(this.obs, ctx, {
-                name: 'iap.reanchor.flush',
-                attributes: {
-                    hasPendingPlan: !!this.pendingReanchorPlan,
-                    hasToken: !!this.currentToken,
-                },
-            })) ?? undefined
-            : undefined;
-        let caught;
-        let fired = false;
-        let trustId;
         try {
             if (!this.pendingReanchorPlan) {
                 return { fired: false };
@@ -1538,34 +1159,13 @@ class ArmorIQSession {
             const planToFlush = this.pendingReanchorPlan;
             this.pendingReanchorPlan = undefined;
             const result = await this.reanchorCall(this.currentToken, planToFlush, 'flush at request boundary');
-            fired = true;
-            trustId = result.trustId;
-            return { fired: true, trustId };
+            return { fired: true, trustId: result.trustId };
         }
         catch (err) {
-            caught = err;
             const msg = err instanceof Error ? err.message : String(err);
             console.warn(`[armoriq] flushReanchor failed: ${msg}`);
             return { fired: false };
         }
-        finally {
-            if (ctx) {
-                const computedDuration = startNs > 0 ? Math.round(performance.now() - startNs) : undefined;
-                safeObs(() => (0, observability_1.recordSpan)(this.obs, ctx, makeSpanRecord(ctx, 'iap.reanchor.flush.result', {
-                    kind: 'span',
-                    fired,
-                    trustId: trustId ?? null,
-                    errorMessage: caught instanceof Error ? caught.message : undefined,
-                }, caught ? 'error' : 'ok', null, spanId)));
-                if (spanId) {
-                    safeObs(() => (0, observability_1.closeSpan)(this.obs, ctx, spanId, {
-                        status: caught ? 'error' : 'ok',
-                        durationMs: computedDuration,
-                        errorMessage: caught instanceof Error ? caught.message : undefined,
-                    }));
-                }
-            }
-        }
     }
     get currentTokenValue() {
         return this.currentToken;
@@ -1574,57 +1174,41 @@ class ArmorIQSession {
         return this.mode;
     }
     /**
-     * Force-flush all buffered observability traces/spans to the backend ingest
-     * endpoint. No-op when observability is disabled (`observability.enabled: false`).
+     * End the active native OTel plan span and force-flush its exporter.
+     * No-op when native observability is disabled.
      *
      * Call this at the request boundary (e.g. Stop hook in armorClaude, end of
-     * turn in ADK consumers) to guarantee all spans for the current session have
-     * been POSTed before the process exits. The underlying shipper retries with
-     * exponential backoff and **never throws** into the SDK consumer — a flush
-     * failure is logged and the spans are dropped.
+     * turn in ADK consumers) to make completed native spans available before the
+     * process exits. Export remains fail-open and does not change tool execution.
      */
     async flushObservability() {
-        if (!this.obs)
+        if (!this.otel)
             return;
-        // Model A: end the in-flight active plan trace FIRST so it's handed to
-        // the shipper's queue before we flush — otherwise an in-progress plan
-        // trace (no endTime yet) would be left behind in the ring buffer and
-        // never ship (see ObservabilityRecorder.flush()'s in-flight retention).
-        safeObs(() => this.endPlanTrace('ok'));
-        await (0, observability_1.flushObservability)(this.obs);
+        await this.drainPolicyTelemetry();
+        await this.otel.flush('ok');
     }
     /**
-     * Stop the session's observability lifecycle: clears the shipper's
-     * repeating flush interval (`setInterval`, see `ObservabilityShipper`) and
-     * performs one final drain/flush of anything still queued. Safe to call
-     * multiple times; a no-op when observability is disabled.
+     * Close the native OTel session: end any active plan and root spans, then
+     * perform the final exporter shutdown. Safe to call multiple times; a no-op
+     * when native observability is disabled.
      *
-     * **Required at session end.** Without calling this, the recorder's
-     * shipper keeps its interval timer alive indefinitely — in long-running
-     * processes this is a resource leak, and in tests it is why processes
-     * (and jest) can hang or emit "cannot log after tests done" / stray
-     * network activity after teardown. `flushObservability()` alone does NOT
-     * stop the interval — it only flushes; call `close()` (or `dispose()`) at
-     * the natural end of the session's lifetime (e.g. Stop hook in armorClaude,
-     * end of process, or end of a request/turn in ADK consumers) instead of
-     * (or in addition to) `flushObservability()`.
+     * Call `close()` (or `dispose()`) at the natural end of the session's
+     * lifetime, such as an adapter Stop hook or the end of a request/turn.
      *
      * NEVER throws — observability teardown failures must not propagate into
      * the SDK consumer, matching every other observability code path.
      */
-    async close(status = 'ok') {
-        if (!this.obs)
+    async close(status = 'ok', taskOutcome, content = {}) {
+        if (!this.otel)
             return;
-        // Model A: end the active plan trace before stopping the shipper so its
-        // final flush (inside obs.stop()) ships the completed plan trace rather
-        // than leaving it stranded in-flight.
-        safeObs(() => this.endPlanTrace(status));
         try {
-            await this.obs.stop();
+            await this.drainPolicyTelemetry();
+            await this.otel?.close(status, taskOutcome, content);
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.warn(`[armoriq] observability close() failed (continuing): ${msg}`);
+        finally {
+            this.pendingDelegationOperations.clear();
+            this.delegationTerminalOperations.clear();
+            this.completedDelegations.clear();
         }
     }
     /** Alias for `close()`. Use whichever reads better at the call site. */