@senpi/runtime 3.0.6-dev.skill-manager-v2.20260629194505 → 3.0.9-dev.runtime-phase-2.20260707070820

package/dist/telemetry/metrics.js

@@ -0,0 +1,437 @@
+/**
+ * Manual OTel instruments, mirroring `tracing.ts`: obtained through the `@opentelemetry/api` proxy
+ * meter, so they no-op before the SDK initialises and resolve the real meter afterwards.
+ *
+ * One lazy cache stands up every instrument once: a name → instrument map per kind, fed by a spec
+ * table (description + unit). The instrument is created on first record (so it binds to the real
+ * meter after SDK init, not the no-op meter at module load) and cached thereafter. Every record
+ * helper is fully guarded — metrics must never throw into a caller path.
+ *
+ * GenAI instruments follow the GenAI semantic conventions; operational instruments mirror their
+ * event-family names (`scanner.*`, `runtime.*`), with attributes in the shared `senpi.*` namespace.
+ */
+import { metrics, } from "@opentelemetry/api";
+/** Instrumentation scope; matches the tracer/logger scope. */
+const METER_NAME = "senpi-trading-runtime";
+/** The single meter for our manual instruments. Resolves the no-op meter pre-init. */
+export function getMeter() {
+    return metrics.getMeter(METER_NAME);
+}
+/** Histograms: GenAI durations/usage + the operational latency histograms. */
+const HISTOGRAM_SPECS = {
+    "gen_ai.client.token.usage": {
+        description: "Number of input/output/cache tokens used by a GenAI request",
+        unit: "{token}",
+    },
+    "gen_ai.client.operation.duration": {
+        description: "Duration of a GenAI client operation",
+        unit: "s",
+    },
+    "gen_ai.execute_tool.duration": {
+        description: "Duration of a tool execution, by origin and outcome",
+        unit: "s",
+    },
+    "gen_ai.invoke_agent.duration": {
+        description: "Duration of a GenAI sub-agent invocation",
+        unit: "s",
+    },
+    "signal.queue_wait": {
+        description: "Time a signal waited in the serial queue before processing",
+        unit: "s",
+    },
+};
+/** Counters: throughput + failure counts. */
+const COUNTER_SPECS = {
+    "scanner.restarts": {
+        description: "Count of supervised-scanner restarts",
+        unit: "{restart}",
+    },
+    "tool.calls": {
+        description: "Count of tool calls, by name, origin, and outcome",
+        unit: "{call}",
+    },
+    "scanner.runs": { description: "Count of scanner runs, by outcome", unit: "{run}" },
+    "signal.intake": {
+        description: "Count of signal-intake dispositions at the HTTP boundary",
+        unit: "{signal}",
+    },
+    "signal.outcome": {
+        description: "Count of post-decision signal outcomes, by result",
+        unit: "{signal}",
+    },
+    "decision.made": { description: "Count of trade decisions, by mode and intent", unit: "{decision}" },
+    "order.submitted": {
+        description: "Count of venue order submissions, by outcome",
+        unit: "{order}",
+    },
+    "dsl.degradations": {
+        description: "Count of DSL exit-engine degradation events, by kind",
+        unit: "{event}",
+    },
+    "state.persist_failures": {
+        description: "Count of StateManager writes that failed to persist",
+        unit: "{failure}",
+    },
+    "clearinghouse.retries": {
+        description: "Count of clearinghouse-state fetch retries, by outcome — early data-layer degradation",
+        unit: "{retry}",
+    },
+    "runtime.heartbeat": {
+        description: "Per-runtime liveness tick, emitted every window; its absence detects a dead runtime",
+        unit: "{beat}",
+    },
+};
+/** Up/down counters: net-state gauges driven by paired edges. */
+const UPDOWN_SPECS = {
+    "scanner.degraded": {
+        description: "Net count of supervised scanners currently in the degraded (crash-loop) state",
+        unit: "{scanner}",
+    },
+};
+/** Observable gauges: read at collection time. */
+const GAUGE_SPECS = {
+    "runtime.queue_depth": {
+        description: "Depth of the runtime's serial signal-processing queue, read at collection time",
+        unit: "{signal}",
+    },
+    "dsl.active_positions": {
+        description: "Active DSL-managed positions, read at collection time, split by exit phase",
+        unit: "{position}",
+    },
+};
+const histogramCache = new Map();
+const counterCache = new Map();
+const upDownCache = new Map();
+const gaugeCache = new Map();
+function histogram(name) {
+    let inst = histogramCache.get(name);
+    if (!inst)
+        histogramCache.set(name, (inst = getMeter().createHistogram(name, HISTOGRAM_SPECS[name])));
+    return inst;
+}
+function counter(name) {
+    let inst = counterCache.get(name);
+    if (!inst)
+        counterCache.set(name, (inst = getMeter().createCounter(name, COUNTER_SPECS[name])));
+    return inst;
+}
+function upDownCounter(name) {
+    let inst = upDownCache.get(name);
+    if (!inst)
+        upDownCache.set(name, (inst = getMeter().createUpDownCounter(name, UPDOWN_SPECS[name])));
+    return inst;
+}
+function observableGauge(name) {
+    let inst = gaugeCache.get(name);
+    if (!inst)
+        gaugeCache.set(name, (inst = getMeter().createObservableGauge(name, GAUGE_SPECS[name])));
+    return inst;
+}
+/** Reset cached instruments (tests only). */
+export function __resetMetricsForTest() {
+    histogramCache.clear();
+    counterCache.clear();
+    upDownCache.clear();
+    gaugeCache.clear();
+}
+/** Drop undefined/null attributes so we never stamp hollow dimensions. */
+function defined(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v !== undefined && v !== null)
+            out[k] = v;
+    }
+    return out;
+}
+/** Elapsed seconds from a `Date.now()` start, clamped to non-negative. */
+export function elapsedSeconds(startMs) {
+    if (typeof startMs !== "number" || !Number.isFinite(startMs))
+        return undefined;
+    return Math.max(0, (Date.now() - startMs) / 1000);
+}
+/**
+ * Record token usage at chat finalize: one data point per token type present (input/output and, when
+ * the model reports them, cache_read/cache_write — the signal a silent context compaction otherwise
+ * hides). Skips a token type whose count is undefined.
+ */
+export function recordTokenUsage(dims, tokens) {
+    try {
+        const base = {
+            "gen_ai.operation.name": "chat",
+            "gen_ai.provider.name": dims.provider,
+            "gen_ai.request.model": dims.model,
+        };
+        const inst = histogram("gen_ai.client.token.usage");
+        const record = (count, type) => {
+            if (typeof count === "number" && Number.isFinite(count)) {
+                inst.record(count, defined({ ...base, "gen_ai.token.type": type }));
+            }
+        };
+        record(tokens.input, "input");
+        record(tokens.output, "output");
+        record(tokens.cacheRead, "cache_read");
+        record(tokens.cacheWrite, "cache_write");
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Record the chat operation duration (seconds); stamps `error.type` when set. */
+export function recordOperationDuration(seconds, dims) {
+    if (seconds === undefined)
+        return;
+    try {
+        histogram("gen_ai.client.operation.duration").record(seconds, defined({
+            "gen_ai.operation.name": "chat",
+            "gen_ai.provider.name": dims.provider,
+            "gen_ai.request.model": dims.model,
+            "error.type": dims.errorType,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+export function recordToolCall(dims) {
+    try {
+        const attrs = defined({
+            "gen_ai.tool.name": dims.toolName,
+            "senpi.tool.origin": dims.origin,
+            "senpi.tool.outcome": dims.outcome,
+            "error.type": dims.errorType,
+        });
+        counter("tool.calls").add(1, attrs);
+        if (typeof dims.durationSec === "number" && Number.isFinite(dims.durationSec)) {
+            histogram("gen_ai.execute_tool.duration").record(dims.durationSec, {
+                ...attrs,
+                "gen_ai.operation.name": "execute_tool",
+            });
+        }
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Record the sub-agent invocation duration (seconds); stamps `error.type` when set. */
+export function recordInvokeAgentDuration(seconds, dims) {
+    if (seconds === undefined)
+        return;
+    try {
+        histogram("gen_ai.invoke_agent.duration").record(seconds, defined({
+            "gen_ai.operation.name": "invoke_agent",
+            "gen_ai.agent.name": dims.agentName,
+            "error.type": dims.errorType,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+function scannerHealthAttrs(dims) {
+    return defined({
+        "senpi.scanner.name": dims.scannerName,
+        "senpi.strategy.address": dims.strategyAddress,
+    });
+}
+/** Count one supervised-scanner restart (the supervisor's `restarting` edge). */
+export function recordScannerRestart(dims) {
+    try {
+        counter("scanner.restarts").add(1, scannerHealthAttrs(dims));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/**
+ * Move the `scanner.degraded` state gauge: +1 on the healthy→degraded edge, −1 on degraded→recovered.
+ * The supervisor fires each edge once, so the net is the count of scanners currently degraded —
+ * alertable as `> 0` without a trace or log scan.
+ */
+export function recordScannerDegradedDelta(delta, dims) {
+    try {
+        upDownCounter("scanner.degraded").add(delta, scannerHealthAttrs(dims));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+// ─── Domain throughput + failure counters/histograms ────────────────────────
+// Each rides a value already measured at an existing event/span site; `errorType` reuses the shared
+// `errorTypeOf` convention. Dimensions are kept deliberately low-cardinality — no asset/id explosion.
+/** Count one scanner run by outcome (the run status). */
+export function recordScannerRun(dims) {
+    try {
+        counter("scanner.runs").add(1, defined({ "senpi.scanner.id": dims.scannerId, "senpi.scanner.outcome": dims.outcome }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Time a signal's wait in the serial queue before processing (seconds). */
+export function recordSignalQueueWait(seconds, dims) {
+    if (seconds === undefined)
+        return;
+    try {
+        histogram("signal.queue_wait").record(seconds, defined({ "senpi.scanner.id": dims.scannerId }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one signal-intake disposition at the HTTP boundary (accepted/rejected/expired/superseded/…). */
+export function recordSignalIntake(dims) {
+    try {
+        counter("signal.intake").add(1, defined({
+            // Stable registry name, never the ephemeral reminted scanner id — that id rotates on every
+            // relaunch and would spray unbounded label values into this aggregated counter.
+            "senpi.scanner.name": dims.scannerName,
+            "senpi.intake.disposition": dims.disposition,
+            "senpi.intake.reason_code": dims.reasonCode,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one post-decision signal outcome by result (accepted/rejected/blocked/error). */
+export function recordSignalOutcome(dims) {
+    try {
+        counter("signal.outcome").add(1, defined({
+            "senpi.outcome.result": dims.result,
+            "senpi.outcome.reason_code": dims.reasonCode,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one trade decision by mode/intent. */
+export function recordDecision(dims) {
+    try {
+        counter("decision.made").add(1, defined({
+            "senpi.decision.mode": dims.mode,
+            "senpi.decision.intent": dims.intent,
+            "senpi.decision.by_llm": dims.byLlm,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one venue order submission by outcome (placed/filled/failed). */
+export function recordOrder(dims) {
+    try {
+        counter("order.submitted").add(1, defined({
+            "senpi.asset": dims.asset,
+            "senpi.order.outcome": dims.outcome,
+            "senpi.order.reason": dims.reason,
+            "error.type": dims.errorType,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one DSL degradation event by kind (sl_sync/price_stale/handoff). */
+export function recordDslDegradation(dims) {
+    try {
+        counter("dsl.degradations").add(1, defined({
+            "senpi.dsl.failure": dims.failure,
+            "senpi.dsl.handoff_failure": dims.handoffFailure,
+            "error.type": dims.errorType,
+        }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one StateManager write that failed to persist. */
+export function recordStatePersistFailure() {
+    try {
+        counter("state.persist_failures").add(1);
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/** Count one clearinghouse-state fetch retry by outcome (`stale` | `unreadable` | `exhausted`). */
+export function recordClearinghouseRetry(outcome) {
+    try {
+        counter("clearinghouse.retries").add(1, defined({ "senpi.clearinghouse.outcome": outcome }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/**
+ * Emit one liveness tick for a runtime. Called once at start and then every window: the *absence* of
+ * ticks for a runtime (by wallet/group) is what detects a dead runtime or box — a down process can't
+ * emit a "down" event, only the gap in this positive signal is alertable.
+ */
+export function recordRuntimeHeartbeat(dims) {
+    try {
+        counter("runtime.heartbeat").add(1, defined({ "senpi.strategy.address": dims.strategyAddress, "senpi.group": dims.group }));
+    }
+    catch {
+        // Metrics must never break the caller.
+    }
+}
+/**
+ * Attach an observation callback to an observable gauge and return a disposer that detaches it.
+ * Registration and disposal both fail open (a no-op meter or a torn-down instrument never throws);
+ * the `observe` callback owns its own guard so a collection read can never throw.
+ */
+function registerGaugeCallback(name, observe) {
+    let gauge;
+    try {
+        gauge = observableGauge(name);
+        gauge.addCallback(observe);
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            gauge.removeCallback(observe);
+        }
+        catch {
+            // Disposal must never throw into the caller's stop path.
+        }
+    };
+}
+/**
+ * Register a runtime's queue depth as a callback on the shared `runtime.queue_depth` observable gauge,
+ * dimensioned by wallet so N runtimes in one process report distinct series. The callback reads the live
+ * depth at each collection. Returns a disposer the runtime must call on stop to drop its observation.
+ */
+export function registerQueueDepthGauge(source) {
+    return registerGaugeCallback("runtime.queue_depth", (result) => {
+        try {
+            result.observe(source.read(), defined({ "senpi.strategy.address": source.strategyAddress, "senpi.group": source.group }));
+        }
+        catch {
+            // Metrics must never break collection.
+        }
+    });
+}
+/**
+ * Register a runtime's active DSL-managed positions as a callback on the shared `dsl.active_positions`
+ * observable gauge, split by exit phase (`senpi.dsl.phase` 1|2) and dimensioned by wallet. Both phases
+ * are observed every collection (0 when empty) so the series stay live — a flat 0 (alive, no positions)
+ * reads differently from an absent series (a dead runtime). The callback reads the live counts at each
+ * collection. Returns a disposer the runtime must call on stop to drop its observation.
+ */
+export function registerDslActivePositionsGauge(source) {
+    return registerGaugeCallback("dsl.active_positions", (result) => {
+        try {
+            const { phase1, phase2 } = source.read();
+            const base = { "senpi.strategy.address": source.strategyAddress, "senpi.group": source.group };
+            result.observe(phase1, defined({ ...base, "senpi.dsl.phase": 1 }));
+            result.observe(phase2, defined({ ...base, "senpi.dsl.phase": 2 }));
+        }
+        catch {
+            // Metrics must never break collection.
+        }
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"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"}

package/dist/telemetry/otel-sdk.d.ts

@@ -0,0 +1,93 @@
+/**
+ * OpenTelemetry SDK stand-up: HyperDX's OTel distribution (`@hyperdx/node-opentelemetry`)
+ * — auto-instrumentation + uncaught-exception capture — against a self-hosted OTLP collector,
+ * with a process-stable resource-attribute set.
+ *
+ * Init runs from plugin `register()` (process scope): the agent hooks register there, before
+ * any runtime, and emit through this SDK's tracer. Only process-stable values ride the resource
+ * (`service.*`, `deployment.environment`, `user.id`), so init need not wait for a runtime.
+ *
+ * Gated by OTLP-config presence: inits iff an OTLP endpoint env is set (no enable flag, no
+ * localhost default). No endpoint ⇒ no SDK and the global tracer/logger no-op. If a non-noop
+ * global `TracerProvider` already exists (the gateway's `diagnostics-otel` owns it), we stand
+ * down and emit through the global API — one SDK per process, first writer wins.
+ *
+ * The package is imported dynamically: it reads `OTEL_EXPORTER_OTLP_*` at module-load and
+ * exposes no init() option for them, so the env must be set first. Under openclaw the operator
+ * sets all of these (the SDK derives none):
+ *   OTEL_EXPORTER_OTLP_ENDPOINT / _TRACES_ENDPOINT / _LOGS_ENDPOINT / _METRICS_ENDPOINT / _HEADERS
+ * See docs/runtime-docs/runtime-api.md (Tracing).
+ */
+/** True when any OTLP endpoint env is set — the gate for standing up the plugin's SDK. */
+export declare function isOtlpEndpointConfigured(): boolean;
+/**
+ * Whether {@link initOtelSdk} has completed. Code that loads `@hyperdx/node-opentelemetry`
+ * lazily (e.g. per-trace attribute stamping) gates on this so the package — which captures
+ * its OTLP transport env at module-load — never loads when telemetry is disabled or under test.
+ */
+export declare function isOtelInitialized(): boolean;
+/**
+ * Decode the `senpi_user_id` claim from a JWT without verifying its signature.
+ * Returns `undefined` for any non-JWT / malformed / missing-claim input; never throws.
+ *
+ * The claim name is assumed, not confirmed against a real token — if the id lives
+ * under a different claim (e.g. `sub`), this must change before `user.id` is trusted.
+ */
+export declare function decodeSenpiUserId(token: string | undefined): string | undefined;
+/** Attribute sources not carried by the {@link IdentityEnvelope}. */
+export interface OtelResourceExtras {
+    /** Process-level instance id → `service.instance.id` ({@link PROCESS_INSTANCE_ID}). */
+    readonly serviceInstanceId?: string;
+    /** → `service.version`. */
+    readonly serviceVersion?: string;
+    /** → `deployment.environment`. */
+    readonly deploymentEnvironment?: string;
+    /** Decoded `senpi_user_id` → `user.id`. */
+    readonly userId?: string;
+}
+/**
+ * Build the `OTEL_RESOURCE_ATTRIBUTES` value as a `key=value,key=value` string.
+ * Values are percent-encoded so spaces/commas stay valid; empty keys are omitted.
+ *
+ * SCOPING (multi-runtime): resource attributes are process-global and immutable
+ * after the first init(), but N runtimes (one per wallet) share one process — so
+ * only PROCESS-STABLE values belong here. We carry:
+ *   - service.name, service.version, deployment.environment — process-stable.
+ *   - service.instance.id — a PROCESS-level id ({@link PROCESS_INSTANCE_ID}), not
+ *     the per-runtime `IdentityEnvelope.bootId`.
+ *   - user.id — process-stable: single-tenant, one SENPI_API_KEY = one user for
+ *     the whole process, so it is the same across every runtime here.
+ *
+ * The per-runtime keys (senpi.strategy.address, senpi.recipe, senpi.recipe.version,
+ * senpi.runtime, senpi.group, senpi.config.hash) are deliberately OMITTED — on a process-global
+ * resource they would stamp the first runtime's value onto every other runtime's
+ * telemetry. They ride per-trace via `setTraceAttributes` and per-log via the logger's
+ * emit-time identity stamp (both reading the same per-runtime identity context).
+ */
+export declare function buildOtelResourceAttributes(serviceName: string, extras: OtelResourceExtras): string;
+export interface InitOtelSdkParams {
+    /** SENPI_API_KEY JWT (the MCP bearer) — decoded locally for `user.id`. */
+    readonly userToken?: string;
+    /** Plugin version → `service.version`. */
+    readonly serviceVersion: string;
+}
+/**
+ * Initialise the OTel SDK. Idempotent, side-effecting, and never crashes boot:
+ * no-ops when no OTLP endpoint is configured, when a real global TracerProvider
+ * already exists (the gateway owns it — we emit through the global API instead),
+ * when already initialised, or under test.
+ */
+export declare function initOtelSdk(params: InitOtelSdkParams): Promise<void>;
+/**
+ * Flush and stop the OTel SDK. Best-effort, idempotent, never throws.
+ *
+ * Required because {@link initOtelSdk} disables HyperDX's own SIGTERM handler
+ * (`stopOnTerminationSignals: false`) — that handler was the SDK's only on-exit
+ * flush, so without an explicit shutdown the span/log batch processors' buffers
+ * are dropped at process exit. The SDK is process-global (one per process,
+ * shared across all hosted runtimes), so this must be called ONCE at process /
+ * plugin teardown, after every span has been emitted — never per-runtime, which
+ * would cut off telemetry for sibling runtimes still running.
+ */
+export declare function shutdownOtelSdk(): Promise<void>;
+//# sourceMappingURL=otel-sdk.d.ts.map

package/dist/telemetry/otel-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/otel-sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH,0FAA0F;AAC1F,wBAAgB,wBAAwB,IAAI,OAAO,CAKlD;AAoGD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAkB/E;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,2BAA2B;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kCAAkC;IAClC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,kBAAkB,GACzB,MAAM,CAaR;AAED,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAKD;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuF1E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAcrD"}