@loompad/cli 0.1.0 → 1.1.1

package/dist/observability/insights.js

@@ -0,0 +1,319 @@
+/**
+ * Observatory insights, read back from the backend's ClickHouse store: the spans
+ * behind the Span Replay viewer and the Trace Waterfall, the per-agent burn-rate
+ * series, and a deterministic 0–100 Agent Health Score. All of it is derived from
+ * the same real gen_ai spans Loom exports — nothing here is synthetic.
+ *
+ * The scoring (`healthScore`) is a pure function so it is unit-tested without a
+ * live ClickHouse, and it is the same math the UI badges render.
+ */
+import { SERVICE_NAME, SPAN_TABLE, chLiteral, chQuery } from "./clickhouse.js";
+const SELECT = `
+  toString(trace_id) AS traceId, toString(span_id) AS spanId,
+  toUnixTimestamp64Milli(timestamp) AS ts, name,
+  round(duration_nano / 1e6) AS ms, status_code AS code, status_message AS msg,
+  attributes_string['gen_ai.agent.id']       AS agent,
+  attributes_string['gen_ai.system']         AS ade,
+  attributes_string['gen_ai.request.model']  AS model,
+  attributes_string['loom.handoff.from']     AS handoffFrom,
+  attributes_string['loom.handoff.to']       AS handoffTo,
+  toFloat64(attributes_number['gen_ai.usage.cost_usd'])     AS cost,
+  toUInt32(attributes_number['gen_ai.usage.input_tokens'])  AS tin,
+  toUInt32(attributes_number['gen_ai.usage.output_tokens']) AS tout`;
+const SERVICE = `\`resource_string_service$$name\` = '${chLiteral(SERVICE_NAME)}'`;
+function rowToSpan(r) {
+    return {
+        traceId: String(r.traceId ?? ""),
+        spanId: String(r.spanId ?? ""),
+        ts: Number(r.ts ?? 0),
+        name: String(r.name ?? ""),
+        ms: Number(r.ms ?? 0),
+        code: Number(r.code ?? 0),
+        msg: String(r.msg ?? ""),
+        agent: String(r.agent ?? ""),
+        ade: String(r.ade ?? ""),
+        model: String(r.model ?? ""),
+        tin: Number(r.tin ?? 0),
+        tout: Number(r.tout ?? 0),
+        cost: Number(r.cost ?? 0),
+        handoffFrom: String(r.handoffFrom ?? ""),
+        handoffTo: String(r.handoffTo ?? ""),
+    };
+}
+/** Recent spans for a project (optionally one agent), newest first. */
+export async function fetchSpans(project, opts = {}) {
+    const proj = chLiteral(project);
+    const limit = Math.min(500, Math.max(1, opts.limit ?? 200));
+    const agentFilter = opts.agent ? `AND attributes_string['gen_ai.agent.id'] = '${chLiteral(opts.agent)}'` : "";
+    const sql = `SELECT ${SELECT} FROM ${SPAN_TABLE}
+    WHERE ${SERVICE} AND attributes_string['loom.project'] = '${proj}' ${agentFilter}
+    ORDER BY timestamp DESC LIMIT ${limit}`;
+    return (await chQuery(sql)).map(rowToSpan);
+}
+/** How many error spans an agent has emitted since `sinceMs` — the self-heal recheck signal. */
+export async function recentAgentErrors(project, agent, sinceMs) {
+    const proj = chLiteral(project);
+    const a = chLiteral(agent);
+    const sinceSec = Math.floor(Math.max(0, sinceMs) / 1000);
+    const sql = `SELECT count() AS n FROM ${SPAN_TABLE}
+    WHERE ${SERVICE} AND attributes_string['loom.project'] = '${proj}'
+      AND attributes_string['gen_ai.agent.id'] = '${a}'
+      AND status_code = 2
+      AND timestamp >= toDateTime(${sinceSec})`;
+    const rows = await chQuery(sql);
+    return Number(rows[0]?.n ?? 0);
+}
+/** Every span in one trace, oldest first — the waterfall's rows. */
+export async function traceSpans(traceId) {
+    const t = chLiteral(traceId);
+    if (!t)
+        return [];
+    const sql = `SELECT ${SELECT} FROM ${SPAN_TABLE}
+    WHERE ${SERVICE} AND trace_id = '${t}' ORDER BY timestamp ASC LIMIT 300`;
+    return (await chQuery(sql)).map(rowToSpan);
+}
+/**
+ * Fallback: derive InsightSpans from the local event log — the same data the
+ * backend gets — so the Observatory's replay/health/waterfall still work when
+ * ClickHouse is down or the agent hasn't exported anything yet.
+ */
+export function insightSpansFromLog(events, agent) {
+    const out = [];
+    for (const e of events) {
+        const p = (e.payload ?? {});
+        const mine = e.agentId === agent || p.to === agent || p.from === agent;
+        if (agent && !mine)
+            continue;
+        const common = { traceId: "", spanId: String(e.id), ts: e.ts, ade: "", model: String(p.model ?? ""), handoffFrom: "", handoffTo: "" };
+        if (e.kind === "run_complete") {
+            out.push({ ...common, name: "gen_ai.agent.turn", ms: Number(p.durationMs ?? 0), code: p.error ? 2 : 1, msg: String(p.error ?? ""),
+                agent: e.agentId ?? "", tin: Number(p.inputTokens ?? 0), tout: Number(p.outputTokens ?? 0), cost: Number(p.costUsd ?? 0) });
+        }
+        else if (e.kind === "error") {
+            out.push({ ...common, name: "loom.error", ms: 0, code: 2, msg: String(p.message ?? "error"), agent: e.agentId ?? "", tin: 0, tout: 0, cost: 0 });
+        }
+        else if (e.kind === "handoff") {
+            out.push({ ...common, name: "loom.baton.handoff", ms: 0, code: 1, msg: `${p.from ?? "?"} -> ${p.to ?? "?"}`,
+                agent: e.agentId ?? "", tin: 0, tout: 0, cost: 0, handoffFrom: String(p.from ?? ""), handoffTo: String(p.to ?? "") });
+        }
+    }
+    return out.sort((a, b) => b.ts - a.ts);
+}
+/** Per-agent cost over time, bucketed — the burn-rate sparkline's data + a linear projection. */
+export async function burnSeries(project, opts = {}) {
+    const proj = chLiteral(project);
+    const hours = Math.min(720, Math.max(1, opts.hours ?? 24));
+    const nBuckets = Math.min(60, Math.max(2, opts.buckets ?? 12));
+    const stepSec = Math.max(60, Math.round((hours * 3600) / nBuckets));
+    const sql = `SELECT
+      toUnixTimestamp(toStartOfInterval(timestamp, INTERVAL ${stepSec} SECOND)) AS bucket,
+      attributes_string['gen_ai.agent.id'] AS agent,
+      sum(toFloat64(attributes_number['gen_ai.usage.cost_usd'])) AS cost
+    FROM ${SPAN_TABLE}
+    WHERE ${SERVICE} AND attributes_string['loom.project'] = '${proj}'
+      AND name = 'gen_ai.agent.turn'
+      AND timestamp >= now() - INTERVAL ${hours} HOUR
+    GROUP BY bucket, agent ORDER BY bucket ASC`;
+    const rows = await chQuery(sql);
+    const map = new Map();
+    for (const r of rows) {
+        const t = Number(r.bucket ?? 0) * 1000;
+        const agent = String(r.agent ?? "unknown");
+        const cost = Number(r.cost ?? 0);
+        const b = map.get(t) ?? { t, byAgent: {}, total: 0 };
+        b.byAgent[agent] = (b.byAgent[agent] ?? 0) + cost;
+        b.total += cost;
+        map.set(t, b);
+    }
+    const buckets = [...map.values()].sort((a, b) => a.t - b.t);
+    const totalUsd = buckets.reduce((a, b) => a + b.total, 0);
+    const ratePerHour = totalUsd / hours;
+    return { hours, buckets, totalUsd, ratePerHour, projected24h: ratePerHour * 24 };
+}
+/* ------------------------------------------------------------------------- *
+ * Metrics read-back
+ *
+ * Loom exports loom.turns, loom.handoffs, loom.cost.usd, loom.agents.active,
+ * gen_ai.client.token.usage and a gen_ai.client.operation.duration histogram
+ * (observability/metrics.ts). Reading them back closes the loop: the same
+ * numbers the Observatory shows can be checked against what the backend stored.
+ *
+ * The backend splits a metric across two tables, confirmed by DESCRIBE on the
+ * live stack:
+ *   distributed_time_series_v4 — one row per (fingerprint, hour) carrying the
+ *     metadata and label maps: metric_name, type, unit, temporality, attrs
+ *     (metric attributes), resource_attrs, labels (a JSON string).
+ *   distributed_samples_v4     — the actual points: metric_name, fingerprint,
+ *     unix_milli, value.
+ * `fingerprint` is the join key: it identifies one label set, i.e. one series.
+ * ------------------------------------------------------------------------- */
+/**
+ * The metric tables the collector writes into. Defaults are that layout;
+ * both are overridable for a backend that stores its metrics elsewhere.
+ */
+export const METRIC_SAMPLES_TABLE = process.env.LOOM_METRIC_SAMPLES_TABLE || "signoz_metrics.distributed_samples_v4";
+export const METRIC_SERIES_TABLE = process.env.LOOM_METRIC_SERIES_TABLE || "signoz_metrics.distributed_time_series_v4";
+/**
+ * A histogram does not exist under its own name in ClickHouse — the OTLP
+ * exporter fans it out into suffixed sums/gauges. Asking for
+ * "gen_ai.client.operation.duration" therefore has to expand to the real names,
+ * or the query silently returns nothing.
+ *
+ * `.bucket` is deliberately excluded: it is one series per histogram boundary
+ * (le="0.005", le="0.01", …), which is a dozen lines of noise on a chart and
+ * never what a caller asking for "the duration metric" means. A caller that
+ * genuinely wants buckets can name `...duration.bucket` explicitly, which the
+ * exact-name path below still honours.
+ */
+const HISTOGRAM_SUFFIXES = ["sum", "count", "min", "max"];
+/** Expand each requested name to itself plus its histogram parts, deduped. */
+export function expandMetricNames(names) {
+    const out = new Set();
+    for (const raw of names) {
+        const n = chLiteral(String(raw ?? "").trim());
+        if (!n)
+            continue;
+        out.add(n);
+        // Suffixing a non-histogram name is harmless — nothing matches it.
+        if (!HISTOGRAM_SUFFIXES.some((s) => n.endsWith(`.${s}`)) && !n.endsWith(".bucket")) {
+            for (const s of HISTOGRAM_SUFFIXES)
+                out.add(`${n}.${s}`);
+        }
+    }
+    return [...out];
+}
+/** Drop the backend's internal label keys (`__name__`, `__temporality__`, …). */
+function cleanLabels(v) {
+    const out = {};
+    if (v && typeof v === "object") {
+        for (const [k, val] of Object.entries(v)) {
+            if (k.startsWith("__"))
+                continue;
+            out[k] = String(val ?? "");
+        }
+    }
+    return out;
+}
+/**
+ * Build the SQL for a metric series query — split out so the join, the project
+ * filter and the bucketing are testable without a live ClickHouse.
+ *
+ * Note what the inner subquery does *not* do: filter time_series_v4 by
+ * unix_milli. That column is floored to the hour there, so a naive
+ * `>= sinceMs` would drop the metadata row for a series whose hour started
+ * before the window and take the whole series with it. The metric_name +
+ * project filters already narrow it to a handful of fingerprints, so the time
+ * filter belongs on the samples side only, where it is exact.
+ *
+ * The GROUP BY inside the subquery collapses the one-row-per-hour duplication;
+ * without it the join would multiply every sample by the number of hours the
+ * series has existed.
+ */
+export function buildMetricQuery(names, opts) {
+    const proj = chLiteral(opts.project ?? "");
+    const step = Math.max(1000, Math.round(opts.stepMs ?? 60_000));
+    const since = Math.max(0, Math.round(opts.sinceMs ?? Date.now() - 6 * 3600_000));
+    const list = expandMetricNames(names)
+        .map((n) => `'${n}'`)
+        .join(", ");
+    return `SELECT
+      any(s.s_metric) AS metric, any(s.s_type) AS type, any(s.s_unit) AS unit,
+      any(s.s_temporality) AS temporality, any(s.s_attrs) AS labels,
+      toString(sm.fingerprint) AS fingerprint,
+      intDiv(sm.unix_milli, ${step}) * ${step} AS t,
+      sum(sm.value) AS vsum, avg(sm.value) AS vavg, max(sm.value) AS vmax, count() AS n
+    FROM ${METRIC_SAMPLES_TABLE} AS sm
+    INNER JOIN (
+      SELECT fingerprint,
+        any(metric_name) AS s_metric, any(type) AS s_type, any(unit) AS s_unit,
+        any(temporality) AS s_temporality, any(attrs) AS s_attrs
+      FROM ${METRIC_SERIES_TABLE}
+      WHERE metric_name IN (${list})
+        AND resource_attrs['service.name'] = '${chLiteral(SERVICE_NAME)}'
+        AND attrs['loom.project'] = '${proj}'
+      GROUP BY fingerprint
+    ) AS s ON s.fingerprint = sm.fingerprint
+    WHERE sm.metric_name IN (${list}) AND sm.unix_milli >= ${since}
+    GROUP BY fingerprint, t
+    ORDER BY metric ASC, fingerprint ASC, t ASC`;
+}
+/** Fold the flat (series, bucket) rows into one entry per series, points ordered. */
+export function rowsToSeries(rows) {
+    const byFp = new Map();
+    for (const r of rows) {
+        const fp = String(r.fingerprint ?? "");
+        const type = String(r.type ?? "");
+        let s = byFp.get(fp);
+        if (!s) {
+            s = {
+                metric: String(r.metric ?? ""),
+                type,
+                unit: String(r.unit ?? ""),
+                temporality: String(r.temporality ?? ""),
+                labels: cleanLabels(r.labels),
+                fingerprint: fp,
+                prefer: type === "Gauge" ? "avg" : "sum",
+                points: [],
+            };
+            byFp.set(fp, s);
+        }
+        s.points.push({
+            t: Number(r.t ?? 0),
+            sum: Number(r.vsum ?? 0),
+            avg: Number(r.vavg ?? 0),
+            max: Number(r.vmax ?? 0),
+            n: Number(r.n ?? 0),
+        });
+    }
+    for (const s of byFp.values())
+        s.points.sort((a, b) => a.t - b.t);
+    return [...byFp.values()].sort((a, b) => a.metric.localeCompare(b.metric) || a.fingerprint.localeCompare(b.fingerprint));
+}
+/**
+ * Read named metrics back for one project, one entry per distinct label set.
+ * Throws if ClickHouse is unreachable — like logs, there is no local substitute
+ * for a metric the backend never received, and the route reports that honestly.
+ */
+export async function fetchMetricSeries(names, opts) {
+    if (!expandMetricNames(names).length)
+        return [];
+    return rowsToSeries(await chQuery(buildMetricQuery(names, opts)));
+}
+/** The metrics Loom actually emits — the default set when a caller names none. */
+export const LOOM_METRIC_NAMES = [
+    "loom.turns",
+    "loom.handoffs",
+    "loom.cost.usd",
+    "loom.agents.active",
+    "gen_ai.client.token.usage",
+    "gen_ai.client.operation.duration",
+];
+const isErr = (s) => s.code === 2 || s.name === "loom.error" || s.name === "loom.route.failed";
+/**
+ * A deterministic 0–100 health score from an agent's own spans. Four penalty
+ * buckets subtract from 100:
+ *   errorRate (≤40) — share of spans that errored
+ *   latency   (≤25) — share of turns slower than 30s
+ *   tokenBloat(≤20) — average input tokens above an 80k comfort line
+ *   recency   (≤15) — how recently the last error fired (fades over 30 min)
+ * Pure: same input, same score — this is what the UI badge shows.
+ */
+export function healthScore(spans, now = Date.now()) {
+    const turns = spans.filter((s) => s.name === "gen_ai.agent.turn");
+    const errs = spans.filter(isErr).sort((a, b) => b.ts - a.ts);
+    const nTurns = turns.length;
+    const errorRate = spans.length ? Math.round((errs.length / spans.length) * 40) : 0;
+    const slow = turns.filter((t) => t.ms > 30_000).length;
+    const latency = nTurns ? Math.round(Math.min(1, slow / nTurns) * 25) : 0;
+    const avgIn = nTurns ? turns.reduce((a, t) => a + t.tin, 0) / nTurns : 0;
+    const tokenBloat = Math.round(Math.min(1, Math.max(0, (avgIn - 80_000) / 120_000)) * 20);
+    let recency = 0;
+    if (errs[0]) {
+        const ageMin = (now - errs[0].ts) / 60_000;
+        recency = Math.round(Math.max(0, 1 - ageMin / 30) * 15);
+    }
+    const score = Math.max(0, Math.min(100, 100 - errorRate - latency - tokenBloat - recency));
+    const grade = score >= 80 ? "healthy" : score >= 50 ? "degraded" : "unhealthy";
+    return { score, grade, turns: nTurns, errorCount: errs.length, buckets: { errorRate, latency, tokenBloat, recency } };
+}
+//# sourceMappingURL=insights.js.map

package/dist/observability/insights.js.map

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

package/dist/observability/logs-query.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Reading Loom's own logs back out of the telemetry backend.
+ *
+ * Loom already *emits* structured logs over OTLP (see observability/logs.ts).
+ * This is the other half: the query that lets the Observatory show an agent what
+ * it actually said, correlated to the span it said it in.
+ *
+ * Two things make this different from the span read-back in insights.ts:
+ *
+ *  1. There is NO local fallback. Spans have one — `insightSpansFromLog` derives
+ *     equivalent spans from the event log, because a span is a summary of an
+ *     event Loom already has on disk. A log line is not: severity, body and the
+ *     trace/span correlation only exist once the log record has been built and
+ *     shipped. Reconstructing something log-shaped from the event log would be
+ *     inventing data, so when ClickHouse is unreachable the caller reports
+ *     `from: "unavailable"` and the UI says so plainly.
+ *
+ *  2. The identity filter is doubled up. `resources_string['service.name']`
+ *     pins us to Loom (rather than any other service shipping to the same
+ *     backend), and `attributes_string['loom.project']` pins us to one project.
+ *     Confirmed against the live table: Loom sets loom.project as a *record*
+ *     attribute, not a resource attribute, so it lands in attributes_string —
+ *     one daemon's logs would otherwise leak into another project's view.
+ */
+/**
+ * The log store. Columns confirmed with DESCRIBE against a live 25.12 instance.
+ * As with the span table, this is the layout the collector writes into and is
+ * overridable for a backend that stores its logs elsewhere.
+ */
+export declare const LOG_TABLE: string;
+/**
+ * A log line, normalised for the UI.
+ *
+ * `ts` is milliseconds (the column is UInt64 *nanoseconds*, hence the intDiv).
+ * `traceId`/`spanId` are already lowercase hex Strings in v2 — no unhex/hex
+ * dance like the trace tables need — and are empty strings when the record was
+ * emitted outside a span, which is normal for status lines.
+ */
+export type InsightLog = {
+    ts: number;
+    severity: string;
+    /** OTel severity_number (1–24). Kept so the UI can sort/threshold without parsing text. */
+    severityNumber: number;
+    body: string;
+    traceId: string;
+    spanId: string;
+    agent: string;
+    /** loom.event.kind — which event produced the line (run_complete, status, message, ...). */
+    kind: string;
+    /** loom.chat — the conversation the line belongs to. */
+    chat: string;
+};
+export type FetchLogsOpts = {
+    project: string;
+    agent?: string;
+    /** One or more severity_text values, comma-separated and case-insensitive ("error,warn"). */
+    severity?: string;
+    /** Pin to a single trace — the log side of the Trace Waterfall. */
+    traceId?: string;
+    /** Case-insensitive substring match on the body. */
+    search?: string;
+    limit?: number;
+};
+/**
+ * Build the SQL for a log query. Split out from the fetch so the WHERE clause —
+ * where a missing project filter would be a real leak — is unit-testable without
+ * a live ClickHouse.
+ *
+ * Every interpolated value goes through `chLiteral`, which strips anything
+ * outside `[\w.\-:/ ]`. That is deliberately blunt: it also removes `%` and `_`,
+ * so a search term can never turn into a LIKE wildcard, and quotes can never
+ * escape the literal. The cost is that punctuation in a search term is dropped
+ * rather than matched, which for substring search over log bodies is a fine
+ * trade.
+ */
+export declare function buildLogsQuery(opts: FetchLogsOpts): string;
+/**
+ * Recent log lines for one project, newest first. Throws if ClickHouse is
+ * unreachable — the caller turns that into `from: "unavailable"` rather than
+ * substituting anything made up.
+ */
+export declare function fetchLogs(opts: FetchLogsOpts): Promise<InsightLog[]>;

package/dist/observability/logs-query.js

@@ -0,0 +1,102 @@
+/**
+ * Reading Loom's own logs back out of the telemetry backend.
+ *
+ * Loom already *emits* structured logs over OTLP (see observability/logs.ts).
+ * This is the other half: the query that lets the Observatory show an agent what
+ * it actually said, correlated to the span it said it in.
+ *
+ * Two things make this different from the span read-back in insights.ts:
+ *
+ *  1. There is NO local fallback. Spans have one — `insightSpansFromLog` derives
+ *     equivalent spans from the event log, because a span is a summary of an
+ *     event Loom already has on disk. A log line is not: severity, body and the
+ *     trace/span correlation only exist once the log record has been built and
+ *     shipped. Reconstructing something log-shaped from the event log would be
+ *     inventing data, so when ClickHouse is unreachable the caller reports
+ *     `from: "unavailable"` and the UI says so plainly.
+ *
+ *  2. The identity filter is doubled up. `resources_string['service.name']`
+ *     pins us to Loom (rather than any other service shipping to the same
+ *     backend), and `attributes_string['loom.project']` pins us to one project.
+ *     Confirmed against the live table: Loom sets loom.project as a *record*
+ *     attribute, not a resource attribute, so it lands in attributes_string —
+ *     one daemon's logs would otherwise leak into another project's view.
+ */
+import { SERVICE_NAME, chLiteral, chQuery } from "./clickhouse.js";
+/**
+ * The log store. Columns confirmed with DESCRIBE against a live 25.12 instance.
+ * As with the span table, this is the layout the collector writes into and is
+ * overridable for a backend that stores its logs elsewhere.
+ */
+export const LOG_TABLE = process.env.LOOM_LOG_TABLE || "signoz_logs.distributed_logs_v2";
+const SELECT = `
+  intDiv(timestamp, 1000000) AS ts,
+  severity_text AS severity,
+  toUInt16(severity_number) AS severityNumber,
+  body,
+  trace_id AS traceId,
+  span_id AS spanId,
+  attributes_string['gen_ai.agent.id']  AS agent,
+  attributes_string['loom.event.kind']  AS kind,
+  attributes_string['loom.chat']        AS chat`;
+/** Same shape as insights.ts's SERVICE guard, but logs keep resource attrs in a Map. */
+const SERVICE = `resources_string['service.name'] = '${chLiteral(SERVICE_NAME)}'`;
+function rowToLog(r) {
+    return {
+        ts: Number(r.ts ?? 0),
+        severity: String(r.severity ?? ""),
+        severityNumber: Number(r.severityNumber ?? 0),
+        body: String(r.body ?? ""),
+        traceId: String(r.traceId ?? ""),
+        spanId: String(r.spanId ?? ""),
+        agent: String(r.agent ?? ""),
+        kind: String(r.kind ?? ""),
+        chat: String(r.chat ?? ""),
+    };
+}
+/**
+ * Build the SQL for a log query. Split out from the fetch so the WHERE clause —
+ * where a missing project filter would be a real leak — is unit-testable without
+ * a live ClickHouse.
+ *
+ * Every interpolated value goes through `chLiteral`, which strips anything
+ * outside `[\w.\-:/ ]`. That is deliberately blunt: it also removes `%` and `_`,
+ * so a search term can never turn into a LIKE wildcard, and quotes can never
+ * escape the literal. The cost is that punctuation in a search term is dropped
+ * rather than matched, which for substring search over log bodies is a fine
+ * trade.
+ */
+export function buildLogsQuery(opts) {
+    const proj = chLiteral(opts.project ?? "");
+    const limit = Math.min(1000, Math.max(1, opts.limit ?? 200));
+    const where = [SERVICE, `attributes_string['loom.project'] = '${proj}'`];
+    if (opts.agent)
+        where.push(`attributes_string['gen_ai.agent.id'] = '${chLiteral(opts.agent)}'`);
+    if (opts.traceId)
+        where.push(`trace_id = '${chLiteral(opts.traceId)}'`);
+    // severity_text is LowCardinality(String) and Loom writes it upper-case, but
+    // callers type "error". Compare upper-cased on both sides so either works.
+    const sevs = (opts.severity ?? "")
+        .split(",")
+        .map((s) => chLiteral(s.trim()).toUpperCase())
+        .filter(Boolean);
+    if (sevs.length)
+        where.push(`upper(severity_text) IN (${sevs.map((s) => `'${s}'`).join(", ")})`);
+    // positionCaseInsensitive rather than ILIKE: no wildcard semantics to smuggle
+    // in, and it reads as "contains" which is what the search box promises.
+    const q = chLiteral((opts.search ?? "").trim());
+    if (q)
+        where.push(`positionCaseInsensitive(body, '${q}') > 0`);
+    return `SELECT ${SELECT} FROM ${LOG_TABLE}
+    WHERE ${where.join("\n      AND ")}
+    ORDER BY timestamp DESC LIMIT ${limit}`;
+}
+/**
+ * Recent log lines for one project, newest first. Throws if ClickHouse is
+ * unreachable — the caller turns that into `from: "unavailable"` rather than
+ * substituting anything made up.
+ */
+export async function fetchLogs(opts) {
+    return (await chQuery(buildLogsQuery(opts))).map(rowToLog);
+}
+//# sourceMappingURL=logs-query.js.map

package/dist/observability/logs-query.js.map

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

package/dist/observability/logs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 type { LoomEvent } from "../types.js";
+import { type AttrValue, type TelemetryConfig } 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 declare const SEVERITY: {
+    readonly DEBUG: 5;
+    readonly INFO: 9;
+    readonly WARN: 13;
+    readonly ERROR: 17;
+};
+export type LogRecordInput = {
+    timeUnixNano: bigint;
+    severityNumber: number;
+    body: string;
+    attributes: Record<string, AttrValue>;
+    traceId?: string;
+    spanId?: string;
+};
+/**
+ * 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 declare function eventToLogRecord(event: LoomEvent, ctx?: {
+    project?: string;
+}): LogRecordInput | null;
+/** Cut an over-long body and say by how much, rather than lying about length. */
+export declare function truncate(body: string, max?: number): string;
+/** Buffered OTLP log exporter. Mirrors LoomTelemetry's batching exactly. */
+export declare class LoomLogs {
+    private readonly cfg;
+    private buffer;
+    private timer;
+    private readonly logsUrl;
+    private readonly resource;
+    constructor(cfg: TelemetryConfig);
+    get enabled(): boolean;
+    /** Buffer one record. No-op when logs are disabled. */
+    log(input: LogRecordInput): void;
+    private ensureTimer;
+    private drain;
+    flush(): void;
+}