@loompad/cli 0.1.0 → 1.1.2

package/dist/observability/logs.js

@@ -0,0 +1,295 @@
+/**
+ * Loom → OpenTelemetry logs (OTLP/HTTP JSON, `/v1/logs`).
+ *
+ * Loom already has a log: the LoomEvent stream is the source of truth for the
+ * whole product. This ships it. Every agent message, tool call, file edit,
+ * decision, route step, budget pause and error becomes one OTLP log record with
+ * the same `service.name` as the spans, and — when the event happened inside a
+ * turn — the same `traceId`/`spanId`.
+ *
+ * That last part is the whole point. Without trace correlation this is just a
+ * second copy of the event log in a different database. With it, a slow turn
+ * in the trace view gets a "related logs" tab showing what the agent actually
+ * said and did while it was slow, and a log line has a link back to the span
+ * that produced it. Traces tell you a turn took 40s; logs tell you why.
+ *
+ * Same contract as the other two exporters: buffered, best-effort, never throws
+ * into the agent loop. Off with LOOM_OTEL_LOGS=0 (or any consent opt-out).
+ */
+import { encodeAttributes, postOtlp, resourceAttributes, } from "./otlp.js";
+/**
+ * OTLP SeverityNumber. The spec's named levels; we use four of them.
+ *
+ * Mapped honestly, which mostly means resisting the urge to inflate. An agent
+ * saying something is INFO, not DEBUG — it is the primary content of the
+ * product. A turn that failed is ERROR. Something a human needs to look at but
+ * that isn't a failure (blocked on input, over budget, a suggested handoff) is
+ * WARN. Adapter lifecycle chatter is DEBUG. Nothing is FATAL: Loom survives
+ * every event it logs, and a severity nobody can act on is noise with a red
+ * icon.
+ */
+export const SEVERITY = {
+    DEBUG: 5,
+    INFO: 9,
+    WARN: 13,
+    ERROR: 17,
+};
+const SEVERITY_TEXT = {
+    [SEVERITY.DEBUG]: "DEBUG",
+    [SEVERITY.INFO]: "INFO",
+    [SEVERITY.WARN]: "WARN",
+    [SEVERITY.ERROR]: "ERROR",
+};
+/**
+ * Longest body we will ship, in characters.
+ *
+ * An agent turn can produce a message with an entire file pasted into it. That
+ * is real data and we do not drop the record — but a megabyte of it per line
+ * will get the batch rejected by the collector's payload limit, taking the
+ * *other* records in the batch down with it. Cut it and say so in the body, so
+ * a reader can tell "this is all of it" from "there was more".
+ */
+const MAX_BODY_CHARS = 8192;
+/**
+ * A LoomEvent → the log record it should produce, or null for kinds that carry
+ * nothing a human would read.
+ *
+ * Pure, and exported so the mapping (and especially the severity mapping) is
+ * testable without a collector — same arrangement as `eventToSpan`.
+ */
+export function eventToLogRecord(event, ctx = {}) {
+    const p = event.payload ?? {};
+    const attributes = {
+        "loom.project": ctx.project,
+        "loom.chat": event.chat,
+        "loom.event.kind": event.kind,
+        "loom.event.id": event.id,
+        "gen_ai.agent.id": event.agentId,
+    };
+    const who = event.agentId || "loom";
+    switch (event.kind) {
+        case "message": {
+            const text = str(p.text);
+            if (!text)
+                return null;
+            // Reasoning is the model thinking out loud, not addressing anyone. Same
+            // severity, tagged so it can be filtered out of a "what did the agent
+            // say" view.
+            return rec(event, SEVERITY.INFO, text, { ...attributes, "loom.message.reasoning": p.reasoning === true });
+        }
+        case "tool_call": {
+            const tool = str(p.tool) || str(p.name) || "tool";
+            return rec(event, SEVERITY.INFO, `${who} called ${tool}${summarize(p.input ?? p.args ?? p.command)}`, {
+                ...attributes,
+                "gen_ai.tool.name": tool,
+            });
+        }
+        case "tool_result": {
+            const tool = str(p.tool) || str(p.name) || "tool";
+            const failed = p.error != null || p.isError === true || num(p.exitCode) === 1;
+            return rec(event, failed ? SEVERITY.WARN : SEVERITY.DEBUG, `${tool} returned${summarize(p.error ?? p.output ?? p.result)}`, { ...attributes, "gen_ai.tool.name": tool, "loom.tool.failed": failed });
+        }
+        case "file_edit": {
+            const path = str(p.path);
+            if (!path)
+                return null;
+            return rec(event, SEVERITY.INFO, `${who} edited ${path}`, {
+                ...attributes,
+                "loom.file.path": path,
+                "loom.file.tool": str(p.tool) || undefined,
+            });
+        }
+        case "decision": {
+            const text = str(p.text) || str(p.decision) || str(p.summary);
+            if (!text)
+                return null;
+            return rec(event, SEVERITY.INFO, `decision: ${text}`, {
+                ...attributes,
+                "loom.decision.kind": str(p.kind) || undefined,
+                "loom.decision.confidence": num(p.confidence),
+            });
+        }
+        case "handoff":
+            return rec(event, SEVERITY.INFO, `baton: ${str(p.from) || event.agentId || "?"} → ${str(p.to) || str(p.agent) || "?"}`, {
+                ...attributes,
+                "loom.handoff.from": str(p.from) || event.agentId || undefined,
+                "loom.handoff.to": str(p.to) || str(p.agent) || undefined,
+            });
+        case "suggestion":
+            return rec(event, SEVERITY.INFO, `suggested handoff to ${str(p.to) || str(p.agent) || "?"}`, attributes);
+        // Blocked on a human. Not a failure, but nothing moves until someone looks.
+        case "needs_input":
+            return rec(event, SEVERITY.WARN, `${who} needs input: ${str(p.question)}`, attributes);
+        case "run_complete": {
+            const ms = num(p.durationMs) ?? 0;
+            const failed = p.error != null;
+            return rec(event, failed ? SEVERITY.ERROR : SEVERITY.INFO, failed ? `${who} turn failed after ${ms}ms: ${str(p.error)}` : `${who} completed a turn in ${ms}ms`, {
+                ...attributes,
+                "gen_ai.request.model": str(p.model) || undefined,
+                "gen_ai.system": str(p.adapter) || undefined,
+                "loom.turn.duration_ms": ms,
+            });
+        }
+        case "route_started":
+        case "route_step":
+        case "route_paused":
+        case "route_resumed":
+        case "route_completed":
+        case "route_failed": {
+            const phase = event.kind.slice("route_".length);
+            const routeId = str(p.routeId) || str(p.id);
+            const failed = event.kind === "route_failed";
+            return rec(event, failed ? SEVERITY.ERROR : event.kind === "route_paused" ? SEVERITY.WARN : SEVERITY.INFO, `route ${routeId || "?"} ${phase}${failed ? `: ${str(p.error) || "route failed"}` : summarize(p.step ?? p.agent)}`, { ...attributes, "loom.route.id": routeId || undefined, "loom.route.phase": phase });
+        }
+        case "memory_add":
+        case "memory_update":
+        case "memory_forget": {
+            const op = event.kind.slice("memory_".length);
+            return rec(event, SEVERITY.INFO, `memory ${op}: ${str(p.text) || str(p.key) || str(p.kind)}`, {
+                ...attributes,
+                "loom.memory.op": op,
+                "loom.memory.scope": str(p.scope) || undefined,
+            });
+        }
+        case "error":
+            return rec(event, SEVERITY.ERROR, str(p.message) || "error", {
+                ...attributes,
+                "loom.error.detail": str(p.stderr) || str(p.detail) || undefined,
+            });
+        case "status": {
+            const state = str(p.state);
+            // The budget guard's two states are the reason status isn't all DEBUG: a
+            // paused agent is the single most confusing thing to debug from the
+            // outside ("why did nothing happen?"), and it deserves to be visible at
+            // WARN next to the turns that didn't run.
+            if (state === "budget_exceeded") {
+                return rec(event, SEVERITY.WARN, `${who} paused — spent $${fixed(p.spentTodayUsd)} against a $${fixed(p.budgetUsd)}/day budget`, {
+                    ...attributes,
+                    "loom.status.state": state,
+                    "loom.budget.usd": num(p.budgetUsd),
+                    "loom.budget.spent_today_usd": num(p.spentTodayUsd),
+                });
+            }
+            if (state === "budget_recovered") {
+                return rec(event, SEVERITY.INFO, `${who} back under budget — pause lifted`, {
+                    ...attributes,
+                    "loom.status.state": state,
+                    "loom.budget.paused_ms": num(p.pausedMs),
+                });
+            }
+            if (!state)
+                return null;
+            return rec(event, SEVERITY.DEBUG, `${who}: ${state}`, { ...attributes, "loom.status.state": state });
+        }
+        default:
+            // agent_join / role_change / turn_diff / memory_import and friends: real
+            // events, but with no body worth a line of their own. They are already on
+            // the span side; adding a "something happened" log record would only pad
+            // the log volume.
+            return null;
+    }
+}
+function rec(event, severityNumber, body, attributes) {
+    return {
+        timeUnixNano: BigInt(Math.max(0, Math.round(event.ts))) * 1000000n,
+        severityNumber,
+        body: truncate(body),
+        attributes,
+    };
+}
+/** Cut an over-long body and say by how much, rather than lying about length. */
+export function truncate(body, max = MAX_BODY_CHARS) {
+    if (body.length <= max)
+        return body;
+    return `${body.slice(0, max)}… [truncated ${body.length - max} chars]`;
+}
+/** A short parenthetical for a payload field, or nothing when there isn't one. */
+function summarize(v) {
+    const s = typeof v === "string" ? v : v == null ? "" : JSON.stringify(v);
+    if (!s)
+        return "";
+    return `: ${s.length > 200 ? `${s.slice(0, 200)}…` : s}`;
+}
+function fixed(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? n.toFixed(2) : "?";
+}
+function num(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+function str(v) {
+    return typeof v === "string" ? v : v == null ? "" : String(v);
+}
+/** Buffered OTLP log exporter. Mirrors LoomTelemetry's batching exactly. */
+export class LoomLogs {
+    cfg;
+    buffer = [];
+    timer = null;
+    logsUrl;
+    resource;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.logsUrl = `${cfg.endpoint}/v1/logs`;
+        this.resource = resourceAttributes(cfg);
+    }
+    get enabled() {
+        return this.cfg.logsEnabled && typeof globalThis.fetch === "function";
+    }
+    /** Buffer one record. No-op when logs are disabled. */
+    log(input) {
+        if (!this.enabled)
+            return;
+        const ts = input.timeUnixNano.toString();
+        this.buffer.push({
+            timeUnixNano: ts,
+            // When the event happened vs. when we saw it. Identical here — Loom
+            // observes its own events synchronously — but the field is required for
+            // a backend to order records, and omitting it makes it fall back to ingest
+            // time, which reorders a burst of turn output arbitrarily.
+            observedTimeUnixNano: ts,
+            severityNumber: input.severityNumber,
+            severityText: SEVERITY_TEXT[input.severityNumber] ?? "INFO",
+            body: { stringValue: input.body },
+            attributes: encodeAttributes(input.attributes),
+            ...(input.traceId ? { traceId: input.traceId } : {}),
+            ...(input.spanId ? { spanId: input.spanId } : {}),
+        });
+        if (this.buffer.length >= 64)
+            this.drain();
+        else
+            this.ensureTimer();
+    }
+    ensureTimer() {
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.drain();
+        }, 1500);
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    drain() {
+        if (this.buffer.length === 0)
+            return;
+        const logRecords = this.buffer;
+        this.buffer = [];
+        postOtlp(this.logsUrl, this.cfg.headers, {
+            resourceLogs: [
+                {
+                    resource: { attributes: this.resource },
+                    scopeLogs: [{ scope: { name: "loom" }, logRecords }],
+                },
+            ],
+        });
+    }
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.drain();
+    }
+}
+//# sourceMappingURL=logs.js.map

package/dist/observability/logs.js.map

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

package/dist/observability/metrics.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Loom → OpenTelemetry metrics (OTLP/HTTP JSON, `/v1/metrics`).
+ *
+ * Same shape as the trace exporter next door: aggregate in memory, flush on a
+ * short timer, POST, never throw. What differs is that a metric is a fold, not
+ * an event — several turns collapse into one datapoint — so this holds a small
+ * aggregation table keyed by metric name + attribute set instead of a list.
+ *
+ * Every number here is derived from a LoomEvent that actually happened. There
+ * is no periodic "emit 0 so the chart has a line" path, because a flat zero and
+ * "nothing happened" look identical on a graph and only one of them is true.
+ *
+ * ── Naming ──────────────────────────────────────────────────────────────────
+ * `gen_ai.*` names and attributes follow the OpenTelemetry GenAI semantic
+ * conventions (semantic-conventions-genai, the GenAI metrics doc split out of
+ * the main semconv repo): `gen_ai.client.token.usage` with a
+ * `gen_ai.token.type` of `input`/`output`, `gen_ai.client.operation.duration`
+ * in seconds, dimensioned by `gen_ai.operation.name`, `gen_ai.system` and
+ * `gen_ai.request.model`. `loom.*` names are ours — nothing in the convention
+ * covers batons, routes or a per-agent daily spend cap — and follow its style.
+ *
+ * One deliberate deviation: the convention models `gen_ai.client.token.usage`
+ * as a *histogram* (a distribution of tokens-per-request). Loom emits it as a
+ * monotonic sum. A histogram earns its keep when you want percentiles over many
+ * requests; Loom reports exactly one input/output pair per turn, and what
+ * anyone asks this data is "how many tokens did this agent burn today" — a sum
+ * answers that exactly, and a histogram's `sum` field only approximates it once
+ * you start dropping buckets. `gen_ai.client.operation.duration` stays a
+ * histogram, as specified, because turn latency genuinely is a distribution.
+ *
+ * ── Temporality ─────────────────────────────────────────────────────────────
+ * Delta, everywhere (AGGREGATION_TEMPORALITY_DELTA). Cumulative asks the
+ * *client* to remember every counter's running total for the life of the
+ * process and expects the backend to detect resets. Loom's daemon restarts
+ * whenever you edit a config or upgrade the CLI, so cumulative would mean a
+ * counter reset every few minutes — the exact case cumulative handles worst.
+ * Delta makes each export self-contained: what happened since the last flush,
+ * nothing remembered, nothing to reset. Collectors accept both.
+ */
+import { type AttrValue, type TelemetryConfig } from "./otlp.js";
+export type MetricAttributes = Record<string, AttrValue>;
+export declare class LoomMetrics {
+    private readonly cfg;
+    private series;
+    private timer;
+    private readonly metricsUrl;
+    private readonly resource;
+    /**
+     * Start of the current delta window. A delta datapoint's
+     * `startTimeUnixNano`..`timeUnixNano` must bracket exactly the interval the
+     * value accumulated over, and consecutive windows must not overlap — so this
+     * advances to the previous flush's end rather than being re-read from the
+     * clock each time.
+     */
+    private windowStartNs;
+    constructor(cfg: TelemetryConfig);
+    get enabled(): boolean;
+    /** Add to a monotonic counter. Negative or non-finite deltas are ignored. */
+    addCount(name: string, value: number, attributes: MetricAttributes, isInt?: boolean): void;
+    /** Record one observation into a histogram. */
+    record(name: string, value: number, attributes: MetricAttributes, bounds?: number[]): void;
+    /** Observe a gauge's current value, as of now. */
+    setGauge(name: string, value: number, attributes?: MetricAttributes): void;
+    flush(): void;
+    /**
+     * Build the OTLP payload for everything accumulated so far and clear the
+     * window. Exported for tests: asserting on the JSON we would send beats
+     * asserting on a mocked fetch, and the payload shape is the part a collector
+     * actually rejects.
+     */
+    collect(nowOverrideNs?: bigint): Record<string, unknown> | null;
+    private bag;
+    /**
+     * Refuse to open a new series past the cap.
+     *
+     * Metric attributes come from agent ids and model names, which are bounded in
+     * practice — but a misbehaving adapter reporting a unique model string per
+     * turn would otherwise turn this map into an unbounded leak and the backend's
+     * index into a mess. Dropping the *new* series keeps the ones already being
+     * measured intact and correct; the alternative (evicting) would silently
+     * discard counts that were already recorded.
+     */
+    private guardCardinality;
+    private ensureTimer;
+    private drain;
+}