next-observer 0.0.0-stage → 0.1.1

package/dist/agents/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/agents/model.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAKvC,MAAM,UAAU,aAAa,CAAC,GAAQ;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,IAAI,MAAM,CAAA;IACrC,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,GAAG,CAAC,CAAA;IAC7G,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAG,GAAQ,OAAO,CAAC,GAAG;IACnD,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,OAAO,EAAE,CAAA;IACvD,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,YAAY;YAAE,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAA;QAC1H,OAAO,GAAG,CAAC,YAAY,CAAA,CAAC,8DAA8D;IACxF,CAAC;IACD,uFAAuF;IACvF,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAA;IACrD,OAAO,IAAI,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,oBAAoB,IAAI,MAAM,EAAE,CAAC,CAAA;AACrE,CAAC"}

package/dist/agents/specialists.d.ts

@@ -0,0 +1,20 @@
+export declare const TOOL_NAMES: readonly ['get_services', 'get_operation_stats', 'compare_versions', 'get_errors', 'search_traces', 'get_trace'];
+export type ToolName = (typeof TOOL_NAMES)[number];
+export interface SpecialistSpec {
+    /** snake_case, becomes the tool name the orchestrator calls. */
+    name: string;
+    /** What this specialist is for — the orchestrator picks specialists by it. */
+    description: string;
+    /** How the specialist works. Facts-only, own-tools-only and English rules are appended automatically. */
+    instruction: string;
+    tools: ToolName[];
+}
+/** Validates a specialist; use it in observe.agents.ts for type checking and early, readable errors. */
+export declare function defineSpecialist(spec: SpecialistSpec): SpecialistSpec;
+export declare const BUILT_IN_SPECIALISTS: SpecialistSpec[];
+/** Project specialists replace built-ins with the same name and are appended otherwise. */
+export declare function mergeSpecialists(builtIn: SpecialistSpec[], project: SpecialistSpec[]): SpecialistSpec[];
+export declare const FACTS_ONLY = "Use only facts returned by your tools; if a tool returned nothing relevant, say so \u2014 never guess causes.\nQuote exact numbers, operation names, versions and error messages. Answer in English.";
+export declare const OWN_TOOLS_ONLY = "You can only use the tools listed for you \u2014 never call other agents or tools that are not listed.\nIf you need data your tools cannot give, say what is missing in your answer.";
+export declare function specialistInstruction(spec: SpecialistSpec): string;
+export declare function orchestratorInstruction(specialists: SpecialistSpec[]): string;

package/dist/agents/specialists.js

@@ -0,0 +1,74 @@
+// Specialists as data: name, description, instruction and which telemetry tools they may use. The built-in three are
+// defaults; a project can replace one (same name) or add its own in observe.agents.ts — the workshop's "write your agent".
+export const TOOL_NAMES = ['get_services', 'get_operation_stats', 'compare_versions', 'get_errors', 'search_traces', 'get_trace'];
+const NAME = /^[a-z][a-z0-9_]{1,40}$/;
+/** Validates a specialist; use it in observe.agents.ts for type checking and early, readable errors. */
+export function defineSpecialist(spec) {
+    const where = typeof spec?.name === 'string' ? `specialist "${spec.name}"` : 'specialist';
+    if (typeof spec !== 'object' || spec === null)
+        throw new Error('a specialist must be an object');
+    if (typeof spec.name !== 'string' || !NAME.test(spec.name))
+        throw new Error(`${where}: name must be snake_case (a-z, 0-9, _), 2–41 characters`);
+    if (spec.name === 'orchestrator')
+        throw new Error(`${where}: "orchestrator" is reserved`);
+    for (const field of ['description', 'instruction']) {
+        if (typeof spec[field] !== 'string' || !spec[field].trim())
+            throw new Error(`${where}: ${field} must be a non-empty string`);
+    }
+    if (!Array.isArray(spec.tools) || spec.tools.length === 0)
+        throw new Error(`${where}: tools must list at least one of ${TOOL_NAMES.join(', ')}`);
+    const unknown = spec.tools.filter((t) => !TOOL_NAMES.includes(t));
+    if (unknown.length)
+        throw new Error(`${where}: unknown tools ${unknown.join(', ')} — available: ${TOOL_NAMES.join(', ')}`);
+    return { name: spec.name, description: spec.description.trim(), instruction: spec.instruction.trim(), tools: [...new Set(spec.tools)] };
+}
+export const BUILT_IN_SPECIALISTS = [
+    {
+        name: 'latency_agent',
+        description: 'Latency specialist: slow operations, p50/p95/p99, regressions between deployed versions, N+1 patterns.',
+        instruction: `You are a latency specialist. Find what is slow and why.
+Check compare_versions for regressions between deployments. For a slow trace, use search_traces then get_trace: high selfMs points at the code file; "repeated" means N+1.
+When asked where time is spent, always open at least one trace with get_trace — aggregates don't show structure.
+Distinguish external dependencies from internal code. Max 3 sentences.`,
+        tools: ['get_operation_stats', 'compare_versions', 'search_traces', 'get_trace'],
+    },
+    {
+        name: 'error_agent',
+        description: 'Error specialist: failing operations, error rates, exact exception messages, source vs downstream victims.',
+        instruction: `You are an error specialist. Report the failing operation, its error rate and the exact exception message.
+Use get_trace on an example trace to separate the source span from its downstream victims and to find the code file. Max 3 sentences.`,
+        tools: ['get_errors', 'search_traces', 'get_trace'],
+    },
+    {
+        name: 'traffic_agent',
+        description: 'Traffic specialist: which services report data, versions deployed, silent services (no traffic).',
+        instruction: `You are a traffic specialist. A service that stopped sending spans is more critical than errors — flag it immediately.
+Report which versions are deployed and whether traffic looks normal. Max 2 sentences.`,
+        tools: ['get_services', 'get_operation_stats'],
+    },
+];
+/** Project specialists replace built-ins with the same name and are appended otherwise. */
+export function mergeSpecialists(builtIn, project) {
+    const byName = new Map(builtIn.map((s) => [s.name, s]));
+    for (const spec of project)
+        byName.set(spec.name, spec);
+    return [...byName.values()];
+}
+export const FACTS_ONLY = `Use only facts returned by your tools; if a tool returned nothing relevant, say so — never guess causes.
+Quote exact numbers, operation names, versions and error messages. Answer in English.`;
+// Specialists run behind AgentTool with their own tools only; calling another agent from inside one cannot work.
+export const OWN_TOOLS_ONLY = `You can only use the tools listed for you — never call other agents or tools that are not listed.
+If you need data your tools cannot give, say what is missing in your answer.`;
+export function specialistInstruction(spec) {
+    return `${spec.instruction}\n${FACTS_ONLY}\n${OWN_TOOLS_ONLY}`;
+}
+export function orchestratorInstruction(specialists) {
+    const list = specialists.map((s) => `- ${s.name}: ${s.description}`).join('\n');
+    return `You coordinate an investigation of a Next.js app using these specialist agents:
+${list}
+Pick the specialists whose descriptions fit the question: failures first to the error specialist, slowness to the latency specialist,
+"nothing happens" to the traffic specialist. A broad or unclear question → call all of them. Then write one report for an
+on-call engineer at 3am: priority no-traffic > errors > latency, max 5 sentences, diagnosis only, never suggest automated fixes.
+Treat separate findings as separate problems unless a tool result shows they are connected. ${FACTS_ONLY}`;
+}
+//# sourceMappingURL=specialists.js.map

package/dist/agents/specialists.js.map

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

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { run } from './cli.js';
+let stopping = false;
+const shutdownSignal = new Promise((resolve) => {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            // Second Ctrl+C = don't wait for a graceful shutdown.
+            if (stopping)
+                process.exit(130);
+            stopping = true;
+            resolve(signal);
+        });
+    }
+});
+run(process.argv.slice(2), { env: process.env, cwd: process.cwd(), log: (line) => console.log(line), spawn, shutdownSignal }).then((code) => process.exit(code), (error) => {
+    console.error(error);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAE9B,IAAI,QAAQ,GAAG,KAAK,CAAA;AACpB,MAAM,cAAc,GAAG,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;IACrD,KAAK,MAAM,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAU,EAAE,CAAC;QACpD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,sDAAsD;YACtD,IAAI,QAAQ;gBAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAC/B,QAAQ,GAAG,IAAI,CAAA;YACf,OAAO,CAAC,MAAM,CAAC,CAAA;QACjB,CAAC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAC,CAAA;AAEF,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,IAAI,CAChI,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,KAAc,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CACF,CAAA"}

package/dist/cli.d.ts

@@ -0,0 +1,29 @@
+import type { ChildProcess, SpawnOptions } from 'node:child_process';
+type AgentsModule = typeof import('./agents/index.js');
+export declare const HELP = "Usage:\n  next-observer dev [--root <dir>] [--port <n>] [-- <next dev args>]\n      Start the collector and `next dev` for the app in <dir> (default: current directory).\n      Example: next-observer dev --root apps/web -- -p 3100\n\n  next-observer collector [--host <host>] [--port <n>] [--api-key <key>] [--demo]\n      Start only the collector (e.g. on a server). Reads OBSERVE_HOST, OBSERVE_PORT, OBSERVE_API_KEY.\n      --demo preloads the workshop \"shop\" scenario (a regression in v2, 30% inventory errors, an N+1).\n\nEnvironment: OBSERVE_ROOT, OBSERVE_PORT (default 4318), OBSERVE_HOST (default 127.0.0.1), OBSERVE_API_KEY,\n             OBSERVE_AI (mock | real), OBSERVE_DETECTOR (off to disable the anomaly detector)";
+export declare class CliError extends Error {
+}
+export type Env = Record<string, string | undefined>;
+export interface CliArgs {
+    command: 'dev' | 'collector' | 'help';
+    root: string;
+    port: number;
+    host: string;
+    apiKey?: string;
+    demo: boolean;
+    nextArgs: string[];
+}
+export declare function parseCliArgs(argv: string[], env: Env, cwd: string): CliArgs;
+export interface CliDeps {
+    env: Env;
+    cwd: string;
+    log: (line: string) => void;
+    spawn: (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+    /** Resolves when the CLI should stop (SIGINT/SIGTERM in real use). */
+    shutdownSignal: Promise<string>;
+    /** Loads the agents module; injectable for tests. */
+    loadAgents?: () => Promise<AgentsModule>;
+}
+export declare const AGENTS_FILES: string[];
+export declare function run(argv: string[], deps: CliDeps): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,231 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { MemoryStorage, startCollector } from './collector/index.js';
+import { seedDemo } from './debug/demo.js';
+import { AnomalyDetector } from './debug/detector.js';
+export const HELP = `Usage:
+  next-observer dev [--root <dir>] [--port <n>] [-- <next dev args>]
+      Start the collector and \`next dev\` for the app in <dir> (default: current directory).
+      Example: next-observer dev --root apps/web -- -p 3100
+
+  next-observer collector [--host <host>] [--port <n>] [--api-key <key>] [--demo]
+      Start only the collector (e.g. on a server). Reads OBSERVE_HOST, OBSERVE_PORT, OBSERVE_API_KEY.
+      --demo preloads the workshop "shop" scenario (a regression in v2, 30% inventory errors, an N+1).
+
+Environment: OBSERVE_ROOT, OBSERVE_PORT (default 4318), OBSERVE_HOST (default 127.0.0.1), OBSERVE_API_KEY,
+             OBSERVE_AI (mock | real), OBSERVE_DETECTOR (off to disable the anomaly detector)`;
+export class CliError extends Error {
+}
+export function parseCliArgs(argv, env, cwd) {
+    const separator = argv.indexOf('--');
+    const own = separator === -1 ? argv : argv.slice(0, separator);
+    const nextArgs = separator === -1 ? [] : argv.slice(separator + 1);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: own,
+            allowPositionals: true,
+            options: {
+                root: { type: 'string' },
+                port: { type: 'string' },
+                host: { type: 'string' },
+                'api-key': { type: 'string' },
+                demo: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (error) {
+        throw new CliError(error.message);
+    }
+    const { values, positionals } = parsed;
+    const command = values.help || positionals.length === 0 ? 'help' : positionals[0];
+    if (command !== 'dev' && command !== 'collector' && command !== 'help')
+        throw new CliError(`unknown command "${command}"`);
+    const rawPort = values.port ?? env.OBSERVE_PORT ?? '4318';
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new CliError(`invalid port "${rawPort}"`);
+    return {
+        command,
+        root: resolve(cwd, values.root ?? env.OBSERVE_ROOT ?? '.'),
+        port,
+        host: values.host ?? env.OBSERVE_HOST ?? '127.0.0.1',
+        apiKey: values['api-key'] ?? env.OBSERVE_API_KEY,
+        demo: values.demo ?? false,
+        nextArgs,
+    };
+}
+function resolveNextBin(root) {
+    if (!existsSync(join(root, 'package.json')))
+        throw new CliError(`no package.json in ${root} — pass --root <app dir>`);
+    try {
+        const nextPackage = createRequire(join(root, 'package.json')).resolve('next/package.json');
+        return join(dirname(nextPackage), 'dist', 'bin', 'next');
+    }
+    catch {
+        throw new CliError(`next is not installed in ${root} — run npm install there first`);
+    }
+}
+export const AGENTS_FILES = ['observe.agents.ts', 'observe.agents.mts', 'observe.agents.js', 'observe.agents.mjs'];
+/**
+ * The project's own specialists from observe.agents.* in the app root: `export default [defineSpecialist({…})]`.
+ * Same name as a built-in replaces it, a new name adds a specialist. Node ≥22.18 runs the .ts file as is (type stripping).
+ */
+async function loadProjectSpecialists(root, agents) {
+    const found = AGENTS_FILES.filter((name) => existsSync(join(root, name)));
+    if (found.length === 0)
+        return { specs: [] };
+    if (found.length > 1)
+        throw new CliError(`found ${found.join(' and ')} in ${root} — keep one`);
+    const file = found[0];
+    let exported;
+    // Next apps rarely have "type": "module", so Node warns that it reparses observe.agents.ts as ESM — noise, not a problem.
+    const emitWarning = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const code = rest[0]?.code;
+        if (code === 'MODULE_TYPELESS_PACKAGE_JSON' && String(warning).includes(file))
+            return;
+        return emitWarning.call(process, warning, ...rest);
+    });
+    try {
+        exported = (await import(pathToFileURL(join(root, file)).href)).default;
+    }
+    catch (error) {
+        const e = error;
+        if (e?.code === 'ERR_UNKNOWN_FILE_EXTENSION')
+            throw new CliError(`${file}: this Node.js cannot load TypeScript — use Node.js ≥22.18 or rename it to observe.agents.mjs`);
+        throw new CliError(`${file}: ${e?.message ?? String(error)}`);
+    }
+    finally {
+        process.emitWarning = emitWarning;
+    }
+    const list = Array.isArray(exported) ? exported : exported === undefined ? undefined : [exported];
+    if (!list)
+        throw new CliError(`${file}: export default an array of defineSpecialist({…})`);
+    const specs = [];
+    for (const item of list) {
+        try {
+            specs.push(agents.defineSpecialist(item));
+        }
+        catch (error) {
+            throw new CliError(`${file}: ${error.message}`);
+        }
+    }
+    const names = specs.map((s) => s.name);
+    const duplicate = names.find((name, i) => names.indexOf(name) !== i);
+    if (duplicate)
+        throw new CliError(`${file}: specialist "${duplicate}" is defined twice`);
+    return { file, specs };
+}
+function agentsLine(builtIn, file, project) {
+    const builtInNames = new Set(builtIn.map((s) => s.name));
+    const own = project.map((s) => (builtInNames.has(s.name) ? `${s.name} (replaces built-in)` : s.name));
+    const kept = builtIn.filter((s) => !project.some((p) => p.name === s.name)).map((s) => s.name);
+    return `  agents     ${file}: ${own.join(', ')}${kept.length ? `; built-in: ${kept.join(', ')}` : ''}`;
+}
+async function loadChat(storage, root, deps) {
+    const agents = await (deps.loadAgents ?? (() => import('./agents/index.js')))();
+    const project = await loadProjectSpecialists(root, agents);
+    const specialists = agents.mergeSpecialists(agents.BUILT_IN_SPECIALISTS, project.specs);
+    try {
+        const chat = await agents.createChatHandler({ storage, env: deps.env, specialists });
+        const hint = chat.mode === 'mock' ? '  (OBSERVE_AI=real for a real model)' : '';
+        const line = `  chat       ${chat.mode}${hint}`;
+        return { chat, line: project.file ? `${line}\n${agentsLine(agents.BUILT_IN_SPECIALISTS, project.file, project.specs)}` : line };
+    }
+    catch (error) {
+        throw new CliError(error.message);
+    }
+}
+async function start(args, deps) {
+    const storage = new MemoryStorage();
+    if (args.demo)
+        await seedDemo(storage);
+    const { chat, line: chatLine } = await loadChat(storage, args.root, deps);
+    const detector = deps.env.OBSERVE_DETECTOR === 'off' ? undefined : new AnomalyDetector();
+    const lines = [chatLine];
+    if (detector) {
+        const o = detector.options;
+        lines.push(`  detector   errors > ${o.errorRate * 100}%, slow (>${o.slowMs}ms) > ${o.slowRate * 100}%, silence > ${o.noTrafficMs / 1000}s → agents investigate on their own`);
+    }
+    else
+        lines.push('  detector   off (OBSERVE_DETECTOR=off)');
+    if (args.demo)
+        lines.push('  demo       "shop" scenario loaded: v1 → v2 regression, inventory errors, catalog N+1');
+    const line = lines.join('\n');
+    try {
+        const collector = await startCollector({ port: args.port, host: args.host, apiKey: args.apiKey, storage, chat, detector });
+        return { collector, chatLine: line };
+    }
+    catch (error) {
+        if (error.code === 'EADDRINUSE') {
+            throw new CliError(`port ${args.port} is already in use — is another next-observer running? Use --port <n>`);
+        }
+        throw error;
+    }
+}
+function banner(collector, extra = []) {
+    return [
+        'next-observer',
+        `  ui         ${collector.url}`,
+        `  collector  ${collector.url}  (OTLP: /v1/traces, API: /api/traces, /api/operations, /api/services)`,
+        ...extra,
+    ].join('\n');
+}
+async function runCollector(args, deps) {
+    const { collector, chatLine } = await start(args, deps);
+    deps.log(banner(collector, [chatLine, ...(args.apiKey ? ['  auth       x-api-key required'] : [])]));
+    await deps.shutdownSignal;
+    await collector.close();
+    return 0;
+}
+async function runDev(args, deps) {
+    const nextBin = resolveNextBin(args.root);
+    const { collector, chatLine } = await start(args, deps);
+    deps.log(banner(collector, [chatLine, `  app        ${['next dev', ...args.nextArgs].join(' ')} in ${args.root}`]));
+    const child = deps.spawn(process.execPath, [nextBin, 'dev', ...args.nextArgs], {
+        cwd: args.root,
+        stdio: 'inherit',
+        // Points both register() and the /__observe browser proxy (withObserve) at this collector.
+        // Next's global types make NODE_ENV required on ProcessEnv; a plain env map is what spawn really takes.
+        env: { ...deps.env, OBSERVE_ENDPOINT: collector.url },
+    });
+    const exited = new Promise((resolveExit) => {
+        child.once('exit', (code) => resolveExit(code ?? 0));
+        child.once('error', () => resolveExit(1));
+    });
+    const first = await Promise.race([exited.then((code) => ({ code })), deps.shutdownSignal.then(() => null)]);
+    let code;
+    if (first) {
+        code = first.code;
+    }
+    else {
+        if (child.exitCode === null)
+            child.kill('SIGTERM');
+        await exited;
+        code = 0;
+    }
+    await collector.close();
+    return code;
+}
+export async function run(argv, deps) {
+    try {
+        const args = parseCliArgs(argv, deps.env, deps.cwd);
+        if (args.command === 'help') {
+            deps.log(HELP);
+            return 0;
+        }
+        return await (args.command === 'dev' ? runDev(args, deps) : runCollector(args, deps));
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        deps.log(`next-observer: ${error.message}\n\n${HELP}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/collector/chat.d.ts

@@ -0,0 +1,93 @@
+import type { Anomaly } from '../debug/detector.js';
+export interface VersionStats {
+    version: string;
+    count: number;
+    p50Ms: number;
+    p95Ms: number;
+    errorRate: number;
+}
+/**
+ * Evidence cards are built by code from tool results — never written by the model — so they can't contain
+ * invented facts. The model writes the narrative report; the cards show the proof.
+ */
+export type EvidenceCard = {
+    kind: 'regression';
+    service: string;
+    operation: string;
+    from: VersionStats;
+    to: VersionStats;
+    p95Ratio: number | null;
+    errorRateDelta: number;
+} | {
+    kind: 'errors';
+    service: string;
+    operation: string;
+    errorRate: number | null;
+    errors: number;
+    message: string;
+    traceIds: string[];
+} | {
+    kind: 'n-plus-one';
+    traceId: string;
+    parent: string;
+    operation: string;
+    count: number;
+    totalMs: number;
+} | {
+    kind: 'hotspot';
+    traceId: string;
+    operation: string;
+    selfMs: number;
+    traceMs: number;
+    codeFile: string;
+} | {
+    kind: 'silent';
+    service: string;
+    lastSpanSecondsAgo: number;
+} | {
+    kind: 'traces';
+    label: string;
+    traces: {
+        traceId: string;
+        root: string;
+        durationMs: number;
+        errors: number;
+    }[];
+};
+export type ChatEvent = {
+    type: 'anomaly';
+    anomaly: Anomaly;
+} | {
+    type: 'status';
+    mode: 'mock' | 'real';
+    sessionId: string;
+    text: string;
+} | {
+    type: 'step';
+    agent: string;
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'card';
+    card: EvidenceCard;
+} | {
+    type: 'report';
+    text: string;
+} | {
+    type: 'error';
+    message: string;
+};
+export interface ChatRequest {
+    question: string;
+    /** From a previous `status` event: continue that conversation. Omitted → a new conversation. */
+    sessionId?: string;
+}
+/** Runs one chat turn, emitting events as it goes. Resolves when the turn is over. */
+export type ChatHandler = (request: ChatRequest, emit: (event: ChatEvent) => void) => Promise<void>;
+/** Server-pushed (SSE) event: part of a proactive turn started by the detector, not by a question. */
+export interface ProactiveEvent {
+    /** Increases by one per event; lets a reconnecting client skip the replayed ones it already has. */
+    seq: number;
+    turnId: string;
+    event: ChatEvent;
+}

package/dist/collector/chat.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chat.js.map

package/dist/collector/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../src/collector/chat.ts"],"names":[],"mappings":""}

package/dist/collector/decode.d.ts

@@ -0,0 +1,52 @@
+import type { NormalizedSpan } from './types.js';
+interface OtlpAnyValue {
+    stringValue?: string;
+    boolValue?: boolean;
+    intValue?: string | number;
+    doubleValue?: number;
+    bytesValue?: string;
+    arrayValue?: {
+        values?: OtlpAnyValue[];
+    };
+    kvlistValue?: {
+        values?: OtlpKeyValue[];
+    };
+}
+interface OtlpKeyValue {
+    key: string;
+    value?: OtlpAnyValue;
+}
+interface OtlpSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind?: number;
+    startTimeUnixNano: string | number;
+    endTimeUnixNano: string | number;
+    attributes?: OtlpKeyValue[];
+    events?: {
+        name: string;
+        timeUnixNano: string | number;
+        attributes?: OtlpKeyValue[];
+    }[];
+    status?: {
+        code?: number;
+        message?: string;
+    };
+}
+export interface OtlpTraceRequest {
+    resourceSpans?: {
+        resource?: {
+            attributes?: OtlpKeyValue[];
+        };
+        scopeSpans?: {
+            scope?: {
+                name?: string;
+            };
+            spans?: OtlpSpan[];
+        }[];
+    }[];
+}
+export declare function decodeOtlpJson(request: OtlpTraceRequest): NormalizedSpan[];
+export {};

package/dist/collector/decode.js

@@ -0,0 +1,59 @@
+const KINDS = ['unspecified', 'internal', 'server', 'client', 'producer', 'consumer'];
+const STATUSES = ['unset', 'ok', 'error'];
+function value(v) {
+    if (!v)
+        return null;
+    if (v.stringValue !== undefined)
+        return v.stringValue;
+    if (v.boolValue !== undefined)
+        return v.boolValue;
+    if (v.intValue !== undefined)
+        return Number(v.intValue);
+    if (v.doubleValue !== undefined)
+        return v.doubleValue;
+    if (v.bytesValue !== undefined)
+        return v.bytesValue;
+    if (v.arrayValue)
+        return (v.arrayValue.values ?? []).map(value);
+    if (v.kvlistValue)
+        return attributes(v.kvlistValue.values);
+    return null;
+}
+function attributes(list = []) {
+    return Object.fromEntries(list.map((kv) => [kv.key, value(kv.value)]));
+}
+// BigInt keeps nanosecond precision until the final division; Number(ns) would lose it.
+const nanosToMs = (ns) => Number(BigInt(ns) / 1000n) / 1000;
+export function decodeOtlpJson(request) {
+    const spans = [];
+    for (const rs of request.resourceSpans ?? []) {
+        const resource = attributes(rs.resource?.attributes);
+        const service = typeof resource['service.name'] === 'string' ? resource['service.name'] : 'unknown';
+        const serviceVersion = typeof resource['service.version'] === 'string' ? resource['service.version'] : null;
+        for (const ss of rs.scopeSpans ?? []) {
+            for (const s of ss.spans ?? []) {
+                // Duration is subtracted in nanoseconds: epoch-ms floats (~1.8e12) can't hold sub-µs differences.
+                const durationNs = BigInt(s.endTimeUnixNano) - BigInt(s.startTimeUnixNano);
+                spans.push({
+                    traceId: s.traceId,
+                    spanId: s.spanId,
+                    parentSpanId: s.parentSpanId || null,
+                    name: s.name,
+                    kind: KINDS[s.kind ?? 0] ?? 'unspecified',
+                    service,
+                    serviceVersion,
+                    scope: ss.scope?.name ?? null,
+                    startTimeMs: nanosToMs(s.startTimeUnixNano),
+                    durationMs: Number(durationNs) / 1e6,
+                    status: STATUSES[s.status?.code ?? 0] ?? 'unset',
+                    statusMessage: s.status?.message || null,
+                    attributes: attributes(s.attributes),
+                    resource,
+                    events: (s.events ?? []).map((e) => ({ name: e.name, timeMs: nanosToMs(e.timeUnixNano), attributes: attributes(e.attributes) })),
+                });
+            }
+        }
+    }
+    return spans;
+}
+//# sourceMappingURL=decode.js.map

package/dist/collector/decode.js.map

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

package/dist/collector/framework.d.ts

@@ -0,0 +1,7 @@
+import type { NormalizedSpan } from './types.js';
+/**
+ * Next.js internal steps of a request ("executing api route (app) …", "render route (app) …", "start response"): they
+ * carry `next.span_type` but are not the request's server span. They repeat the endpoint's and user code's numbers, so
+ * agents' aggregates skip them — otherwise one slow call shows up as three problems. Traces keep them for structure.
+ */
+export declare function isFrameworkSpan(span: Pick<NormalizedSpan, 'kind' | 'attributes'>): boolean;