next-observer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Tazetdinov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# next-observer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The observer for **[next-observe](https://www.npmjs.com/package/next-observe)**: an OTLP collector, a trace UI, an anomaly
+detector and AI agents (Google ADK) that investigate your Next.js app on their own. Run it with `npx` — it never goes
+into your app's dependencies.
+
+```bash
+npx next-observer dev          # observer + UI on http://127.0.0.1:4318, then `next dev` in the current directory
+```
+
+- **Trace UI** — list + waterfall, no Docker, no external backend
+- **Chat with agents** that query your telemetry: slow operations, regressions between deployments, failing operations
+  with exact errors, N+1 patterns — with evidence cards built from the data, not by the model
+- **Anomaly detector** that starts an investigation by itself when error rates or latency jump
+
+Requires Node.js 22.18+. The app is instrumented with `next-observe` (see its README).
+
+## Commands
+
+```bash
+next-observer dev [--root <dir>] [--port <n>] [-- <next dev args>]   # observer + next dev
+next-observer collector [--host <h>] [--port <n>] [--api-key <k>] [--demo]
+```
+
+Run them with `npx next-observer <command>`; installed globally (`npm i -g next-observer`) the command is also
+available as `nxo`.
+
+`next-observer collector` runs the observer alone — next to `next dev` in another terminal, or on a server for production.
+`--demo` preloads a sample "shop" scenario (a regression between versions, a failing endpoint, an N+1).
+
+## Models
+
+| `OBSERVE_AI` | Model |
+|---|---|
+| `mock` (default) | deterministic stand-in — the whole pipeline runs without tokens |
+| `real` | Gemini when `GEMINI_API_KEY` + `GEMINI_MODEL` are set, otherwise [Kitana](https://www.npmjs.com/package/@kitana-sdk/adk) (Claude / Codex CLI, Ollama, API keys) |
+
+## Your own specialists
+
+Put `observe.agents.ts` (or `.mts`, `.js`, `.mjs`) in the app root. A specialist with a built-in name
+(`latency_agent`, `error_agent`, `traffic_agent`) replaces it; a new name adds one. The orchestrator picks specialists by
+their `description`; the rules "facts from tools only" and "own tools only" are added to every instruction.
+
+```ts
+import { defineSpecialist } from 'next-observe/agents'
+
+export default [
+  defineSpecialist({
+    name: 'latency_agent',
+    description: 'Finds slow operations and the deployment that made them slow',
+    instruction: 'First call compare_versions; then open one slow trace and name the span with the highest selfMs.',
+    tools: ['compare_versions', 'search_traces', 'get_trace'],
+  }),
+]
+```
+
+Tools: `get_services`, `get_operation_stats`, `compare_versions`, `get_errors`, `search_traces`, `get_trace`.
+`next-observer` validates the file and lists the loaded specialists on start.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `OBSERVE_AI` | `mock` | `mock` \| `real` |
+| `OBSERVE_DETECTOR` | on | `off` disables the anomaly detector |
+| `OBSERVE_API_KEY` | — | require `x-api-key` on ingest and API |
+| `OBSERVE_PORT`, `OBSERVE_HOST`, `OBSERVE_ROOT` | `4318`, `127.0.0.1`, `.` | same as `--port`, `--host`, `--root` |
+
+Accepts OTLP/HTTP **JSON** (what `next-observe` sends); protobuf is planned.
+
+## Entry points
+
+| Import | For |
+|---|---|
+| `next-observer/collector` | `startCollector()`, storage, OTLP/JSON decoding |
+| `next-observer/debug` | agent tools as plain functions, `AnomalyDetector`, demo data |
+| `next-observer/agents` | ADK agents, chat handler, built-in specialists |
+
+## License
+
+MIT

package/dist/agents/cards.d.ts

@@ -0,0 +1,14 @@
+import type { EvidenceCard } from '../collector/chat.js';
+export declare const THRESHOLDS: {
+    /** p95 latest / previous version. */
+    regressionRatio: number;
+    /** errorRate latest − previous version. */
+    regressionErrorDelta: number;
+    errorRate: number;
+    /** One span's self time as a share of the whole trace. */
+    hotspotShare: number;
+    silentSeconds: number;
+};
+export declare function cardsFromResult(tool: string, args: Record<string, unknown>, result: unknown): EvidenceCard[];
+/** Same finding reported twice in one turn (e.g. two agents compared versions) shows once. */
+export declare function cardKey(card: EvidenceCard): string;

package/dist/agents/cards.js

@@ -0,0 +1,85 @@
+export const THRESHOLDS = {
+    /** p95 latest / previous version. */
+    regressionRatio: 1.5,
+    /** errorRate latest − previous version. */
+    regressionErrorDelta: 0.1,
+    errorRate: 0.05,
+    /** One span's self time as a share of the whole trace. */
+    hotspotShare: 0.5,
+    silentSeconds: 120,
+};
+function describeFilters(args) {
+    const parts = Object.entries(args)
+        .filter(([, v]) => v !== undefined && v !== '')
+        .map(([k, v]) => `${k}=${String(v)}`);
+    return parts.length ? `Traces · ${parts.join(', ')}` : 'Recent traces';
+}
+export function cardsFromResult(tool, args, result) {
+    switch (tool) {
+        case 'compare_versions': {
+            const { changes } = result;
+            return changes
+                .filter((c) => (c.p95Ratio ?? 0) >= THRESHOLDS.regressionRatio || c.errorRateDelta >= THRESHOLDS.regressionErrorDelta)
+                .map((c) => ({ kind: 'regression', service: c.service, operation: c.operation, from: c.from, to: c.to, p95Ratio: c.p95Ratio, errorRateDelta: c.errorRateDelta }));
+        }
+        case 'get_errors': {
+            const { errors } = result;
+            return errors
+                .filter((e) => (e.errorRate ?? 1) >= THRESHOLDS.errorRate)
+                .map((e) => ({
+                kind: 'errors',
+                service: e.service,
+                operation: e.operation,
+                errorRate: e.errorRate,
+                errors: e.errors,
+                message: e.topMessages[0]?.message ?? '(no message)',
+                traceIds: e.exampleTraceIds,
+            }));
+        }
+        case 'get_trace': {
+            const trace = result;
+            if (!('traceId' in trace) || trace.spans.length === 0)
+                return [];
+            const cards = trace.repeated.map((r) => ({ kind: 'n-plus-one', traceId: trace.traceId, parent: r.parent, operation: r.operation, count: r.count, totalMs: r.totalMs }));
+            const traceMs = trace.spans[0].durationMs;
+            const hottest = trace.spans
+                .filter((s) => s.depth > 0 && typeof s.attributes?.['code.filepath'] === 'string')
+                .sort((a, b) => b.selfMs - a.selfMs)[0];
+            if (hottest && traceMs > 0 && hottest.selfMs / traceMs >= THRESHOLDS.hotspotShare) {
+                cards.push({ kind: 'hotspot', traceId: trace.traceId, operation: hottest.name, selfMs: hottest.selfMs, traceMs, codeFile: String(hottest.attributes['code.filepath']) });
+            }
+            return cards;
+        }
+        case 'get_services': {
+            const { services } = result;
+            return services
+                .filter((s) => s.lastSpanSecondsAgo > THRESHOLDS.silentSeconds)
+                .map((s) => ({ kind: 'silent', service: s.name, lastSpanSecondsAgo: s.lastSpanSecondsAgo }));
+        }
+        case 'search_traces': {
+            const { traces } = result;
+            if (traces.length === 0)
+                return [];
+            return [{ kind: 'traces', label: describeFilters(args), traces: traces.slice(0, 5).map((t) => ({ traceId: t.traceId, root: t.root, durationMs: t.durationMs, errors: t.errors })) }];
+        }
+        default:
+            return [];
+    }
+}
+/** Same finding reported twice in one turn (e.g. two agents compared versions) shows once. */
+export function cardKey(card) {
+    switch (card.kind) {
+        case 'regression':
+        case 'errors':
+            return `${card.kind}:${card.service}:${card.operation}`;
+        case 'n-plus-one':
+            return `${card.kind}:${card.parent}:${card.operation}`;
+        case 'hotspot':
+            return `${card.kind}:${card.operation}:${card.codeFile}`;
+        case 'silent':
+            return `${card.kind}:${card.service}`;
+        case 'traces':
+            return `${card.kind}:${card.label}`;
+    }
+}
+//# sourceMappingURL=cards.js.map

package/dist/agents/cards.js.map

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

package/dist/agents/chat.d.ts

@@ -0,0 +1,21 @@
+import type { BaseLlm } from '@google/adk';
+import type { ChatHandler } from '../collector/chat.js';
+import type { StorageAdapter } from '../collector/types.js';
+import type { QueryOptions } from '../debug/queries.js';
+import type { SpecialistSpec } from './specialists.js';
+import { type Env } from './model.js';
+export interface ChatHandlerOptions {
+    storage: StorageAdapter;
+    env?: Env;
+    queryOptions?: QueryOptions;
+    /** An investigation that takes longer ends with an error event. Default 180 s — a CLI model can hang. */
+    timeoutMs?: number;
+    /** Overrides the model chosen from env (tests, custom providers). */
+    model?: BaseLlm | string;
+    /** Default: the built-in specialists; the CLI merges in the project's observe.agents file. */
+    specialists?: SpecialistSpec[];
+}
+export declare function createChatHandler(options: ChatHandlerOptions): Promise<{
+    mode: 'mock' | 'real';
+    handle: ChatHandler;
+}>;

package/dist/agents/chat.js

@@ -0,0 +1,83 @@
+import { cardKey, cardsFromResult } from './cards.js';
+import { createInvestigator } from './investigator.js';
+import { getModel, resolveAiMode } from './model.js';
+export async function createChatHandler(options) {
+    const env = options.env ?? process.env;
+    const mode = resolveAiMode(env);
+    const investigator = createInvestigator({
+        storage: options.storage,
+        model: options.model ?? (await getModel(env)),
+        queryOptions: options.queryOptions,
+        specialists: options.specialists,
+    });
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    // One question at a time per conversation: a second one would interleave with the first in the session history.
+    const busy = new Set();
+    const handle = async ({ question, sessionId: requested }, emit) => {
+        // Reserve synchronously, before any await: two requests for the same session must not both get through.
+        if (requested) {
+            if (busy.has(requested)) {
+                emit({ type: 'error', message: 'this chat is still answering the previous question' });
+                return;
+            }
+            busy.add(requested);
+        }
+        let sessionId = requested;
+        let investigation;
+        let timedOut = false;
+        let finished = false;
+        const send = (event) => {
+            if (!finished)
+                emit(event);
+        };
+        let timer;
+        const timeout = new Promise((resolve) => (timer = setTimeout(() => resolve('timeout'), timeoutMs)));
+        const shown = new Set();
+        const onResult = (step, result) => {
+            for (const card of cardsFromResult(step.tool, step.args, result)) {
+                const key = cardKey(card);
+                if (shown.has(key))
+                    continue;
+                shown.add(key);
+                send({ type: 'card', card });
+            }
+        };
+        try {
+            sessionId = await investigator.startSession(requested);
+            busy.add(sessionId);
+            emit({ type: 'status', mode, sessionId, text: 'Investigating…' });
+            const running = investigator.ask(question, { sessionId, onStep: (s) => send({ type: 'step', ...s }), onResult });
+            investigation = running;
+            const result = await Promise.race([running, timeout]);
+            if (result === 'timeout') {
+                timedOut = true;
+                send({ type: 'error', message: `investigation took longer than ${Math.round(timeoutMs / 1000)}s — try a narrower question` });
+            }
+            else if (result.error && !result.text) {
+                send({ type: 'error', message: result.error });
+            }
+            else {
+                send({ type: 'report', text: result.text || '(the agents returned no report)' });
+            }
+        }
+        catch (error) {
+            send({ type: 'error', message: error instanceof Error ? error.message : String(error) });
+        }
+        finally {
+            // A timed-out investigation keeps running and writing to the session: its late steps must not leak into this
+            // finished turn, and the session stays busy until it really ends.
+            finished = true;
+            clearTimeout(timer);
+            const release = () => {
+                if (sessionId)
+                    busy.delete(sessionId);
+            };
+            if (timedOut && investigation)
+                investigation.then(release, release);
+            else
+                release();
+        }
+    };
+    return { mode, handle };
+}
+//# sourceMappingURL=chat.js.map

package/dist/agents/chat.js.map

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

package/dist/agents/index.d.ts

@@ -0,0 +1,6 @@
+export { createInvestigator, isLeakedToolCall, type Investigator, type InvestigatorOptions, type InvestigationStep, type TranscriptEntry } from './investigator.js';
+export { getModel, resolveAiMode, type AiMode } from './model.js';
+export { MockLlm, MOCK_PREFIX } from './mock-llm.js';
+export { createChatHandler, type ChatHandlerOptions } from './chat.js';
+export { cardsFromResult, cardKey, THRESHOLDS } from './cards.js';
+export { BUILT_IN_SPECIALISTS, TOOL_NAMES, defineSpecialist, mergeSpecialists, type SpecialistSpec, type ToolName } from './specialists.js';

package/dist/agents/index.js

@@ -0,0 +1,8 @@
+// ADK agents over the telemetry tools (Gemini, Kitana or the mock model).
+export { createInvestigator, isLeakedToolCall } from './investigator.js';
+export { getModel, resolveAiMode } from './model.js';
+export { MockLlm, MOCK_PREFIX } from './mock-llm.js';
+export { createChatHandler } from './chat.js';
+export { cardsFromResult, cardKey, THRESHOLDS } from './cards.js';
+export { BUILT_IN_SPECIALISTS, TOOL_NAMES, defineSpecialist, mergeSpecialists } from './specialists.js';
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAA6F,MAAM,mBAAmB,CAAA;AACnK,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAe,MAAM,YAAY,CAAA;AACjE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAA2B,MAAM,WAAW,CAAA;AACtE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACjE,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAsC,MAAM,kBAAkB,CAAA"}

package/dist/agents/investigator.d.ts

@@ -0,0 +1,50 @@
+import { type BaseLlm } from '@google/adk';
+import type { StorageAdapter } from '../collector/types.js';
+import { type QueryOptions } from '../debug/queries.js';
+import { type SpecialistSpec } from './specialists.js';
+export interface InvestigationStep {
+    agent: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+/** What the orchestrator did, in order: specialist calls, their answers, its own text. */
+export interface TranscriptEntry {
+    kind: 'call' | 'result' | 'text';
+    agent: string;
+    content: string;
+}
+export interface InvestigatorOptions {
+    storage: StorageAdapter;
+    model: BaseLlm | string;
+    queryOptions?: QueryOptions;
+    /** Called for every tool call, specialists included — the chat shows these while the agents work. */
+    onStep?: (step: InvestigationStep) => void;
+    /** Default: the built-in latency, error and traffic specialists. */
+    specialists?: SpecialistSpec[];
+}
+/**
+ * A final text that starts like `{"tool_call": …}` is a tool call that leaked instead of a report. Seen in real runs:
+ * the model dropped a closing brace, the provider could not parse the call, and the raw JSON came back as text —
+ * so this checks the shape of the start, not whether the JSON is valid.
+ */
+export declare function isLeakedToolCall(text: string): boolean;
+export declare function createInvestigator(options: InvestigatorOptions): {
+    startSession: (sessionId?: string) => Promise<string>;
+    /**
+     * Runs one investigation; resolves with the final report and every tool call made on the way.
+     * Pass the sessionId from a previous answer to continue that conversation. Safe to call concurrently (per session: one at a time).
+     */
+    ask(question: string, call?: {
+        onStep?: (step: InvestigationStep) => void;
+        /** Called with each data tool's result — the chat builds evidence cards from these. */
+        onResult?: (step: InvestigationStep, result: unknown) => void;
+        sessionId?: string;
+    }): Promise<{
+        text: string;
+        sessionId: string;
+        steps: InvestigationStep[];
+        transcript: TranscriptEntry[];
+        error?: string;
+    }>;
+};
+export type Investigator = ReturnType<typeof createInvestigator>;

package/dist/agents/investigator.js

@@ -0,0 +1,123 @@
+// Orchestrator + specialist agents (Four Golden Signals split) over the telemetry tools from ../debug.
+import { AgentTool, FunctionTool, InMemorySessionService, LlmAgent, Runner } from '@google/adk';
+import { z } from 'zod';
+import { createAgentQueries } from '../debug/queries.js';
+import { BUILT_IN_SPECIALISTS, orchestratorInstruction, specialistInstruction } from './specialists.js';
+const since = z.number().positive().optional().describe('look back this many minutes (default 15)');
+const service = z.string().optional().describe('exact service name');
+const operation = z.string().optional().describe('substring of the operation name, case-insensitive');
+/**
+ * A final text that starts like `{"tool_call": …}` is a tool call that leaked instead of a report. Seen in real runs:
+ * the model dropped a closing brace, the provider could not parse the call, and the raw JSON came back as text —
+ * so this checks the shape of the start, not whether the JSON is valid.
+ */
+export function isLeakedToolCall(text) {
+    return /^\s*(?:```(?:json)?\s*)?\{\s*"tool_call"\s*:/.test(text);
+}
+const APP_NAME = 'next-observe';
+const USER_ID = 'next-observe';
+export function createInvestigator(options) {
+    const q = createAgentQueries(options.storage, options.queryOptions);
+    const specialists = options.specialists ?? BUILT_IN_SPECIALISTS;
+    // Conversation memory: ADK stores every question, specialist call and answer in the session; the orchestrator sees
+    // them on the next turn. Specialists (AgentTool) start fresh each time and get context via the orchestrator's request.
+    // In-memory: sessions end with the process.
+    const sessions = new InMemorySessionService();
+    /** Continues a session, or starts one (also when an id is unknown, e.g. after a restart). Returns the session id. */
+    async function startSession(sessionId) {
+        if (sessionId) {
+            const existing = await sessions.getSession({ appName: APP_NAME, userId: USER_ID, sessionId });
+            if (existing)
+                return existing.id;
+        }
+        return (await sessions.createSession({ appName: APP_NAME, userId: USER_ID, sessionId })).id;
+    }
+    // Agents are built per investigation so each ask() records into its own steps — concurrent chats don't mix.
+    function buildOrchestrator(record, recordResult) {
+        // Tools are created per agent so every step is attributed to the agent that made it.
+        function tool(agent, name, description, parameters, run) {
+            return new FunctionTool({
+                name,
+                description,
+                parameters,
+                execute: async (args) => {
+                    const step = { agent, tool: name, args: args };
+                    record(step);
+                    const result = await run(args);
+                    recordResult(step, result);
+                    return result;
+                },
+            });
+        }
+        const tools = (agent) => ({
+            get_services: tool(agent, 'get_services', 'Services, their deployed versions (in deploy order) and seconds since their last span.', z.object({}), () => q.getServices()),
+            get_operation_stats: tool(agent, 'get_operation_stats', 'Slowest operations by p95 with p50/p99 and error rate.', z.object({ service, operation, sinceMinutes: since }), (a) => q.getOperationStats(a)),
+            compare_versions: tool(agent, 'compare_versions', 'Latest deployed version vs the previous one per operation: p95 ratio and error-rate delta. Use it to name the deployment that caused a regression.', z.object({ service, operation, sinceMinutes: since }), (a) => q.compareVersions(a)),
+            get_errors: tool(agent, 'get_errors', 'Failing operations: error rate, top exception messages, example trace ids.', z.object({ service, operation, sinceMinutes: since }), (a) => q.getErrors(a)),
+            search_traces: tool(agent, 'search_traces', 'Recent traces matching filters, to get example trace ids.', z.object({ service, operation, minDurationMs: z.number().optional(), hasError: z.boolean().optional(), sinceMinutes: since }), (a) => q.searchTraces(a)),
+            get_trace: tool(agent, 'get_trace', 'One trace as a tree with self time, errors and code file paths; `repeated` lists ≥3 identical sibling calls (N+1); `nextInternalMs` is time inside Next.js itself (routing, rendering, dev compilation), not the app code.', z.object({ traceId: z.string().describe('32-char hex trace id from search_traces') }), (a) => q.getTrace(a)),
+        });
+        const agents = specialists.map((spec) => {
+            const available = tools(spec.name);
+            return new LlmAgent({
+                name: spec.name,
+                description: spec.description,
+                model: options.model,
+                instruction: specialistInstruction(spec),
+                tools: spec.tools.map((name) => available[name]),
+            });
+        });
+        const orchestrator = new LlmAgent({
+            name: 'orchestrator',
+            model: options.model,
+            instruction: orchestratorInstruction(specialists),
+            tools: agents.map((agent) => new AgentTool({ agent })),
+        });
+        return orchestrator;
+    }
+    return {
+        startSession,
+        /**
+         * Runs one investigation; resolves with the final report and every tool call made on the way.
+         * Pass the sessionId from a previous answer to continue that conversation. Safe to call concurrently (per session: one at a time).
+         */
+        async ask(question, call = {}) {
+            const sessionId = await startSession(call.sessionId);
+            const steps = [];
+            const record = (step) => {
+                steps.push(step);
+                options.onStep?.(step);
+                call.onStep?.(step);
+            };
+            const runner = new Runner({ agent: buildOrchestrator(record, (step, result) => call.onResult?.(step, result)), appName: APP_NAME, sessionService: sessions });
+            const transcript = [];
+            let text = '';
+            let failure;
+            for await (const event of runner.runAsync({ userId: USER_ID, sessionId, newMessage: { role: 'user', parts: [{ text: question }] } })) {
+                if (event.errorMessage)
+                    failure = event.errorMessage;
+                if (event.author !== 'orchestrator')
+                    continue;
+                for (const part of event.content?.parts ?? []) {
+                    if (part.functionCall) {
+                        const step = { agent: 'orchestrator', tool: part.functionCall.name ?? 'unknown', args: (part.functionCall.args ?? {}) };
+                        record(step);
+                        transcript.push({ kind: 'call', agent: step.tool, content: JSON.stringify(step.args) });
+                    }
+                    if (part.functionResponse) {
+                        transcript.push({ kind: 'result', agent: part.functionResponse.name ?? 'unknown', content: JSON.stringify(part.functionResponse.response ?? {}) });
+                    }
+                    if (part.text) {
+                        text = part.text;
+                        transcript.push({ kind: 'text', agent: 'orchestrator', content: part.text });
+                    }
+                }
+            }
+            if (isLeakedToolCall(text)) {
+                return { text: '', sessionId, steps, transcript, error: 'the agents did not finish the report (a tool call leaked instead) — the evidence cards above are still valid; ask again to continue' };
+            }
+            return { text, sessionId, steps, transcript, ...(failure ? { error: failure } : {}) };
+        },
+    };
+}
+//# sourceMappingURL=investigator.js.map

package/dist/agents/investigator.js.map

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

package/dist/agents/mock-llm.d.ts

@@ -0,0 +1,7 @@
+import { BaseLlm, type BaseLlmConnection, type LlmRequest, type LlmResponse } from '@google/adk';
+export declare const MOCK_PREFIX = "[mock]";
+export declare class MockLlm extends BaseLlm {
+    constructor();
+    generateContentAsync(request: LlmRequest): AsyncGenerator<LlmResponse, void>;
+    connect(): Promise<BaseLlmConnection>;
+}

package/dist/agents/mock-llm.js

@@ -0,0 +1,46 @@
+// Deterministic stand-in for a real model: exercises the whole agent pipeline (orchestrator → specialists → tools)
+// without network or tokens. Each turn it calls the next tool it hasn't called yet (one call per turn, like Kitana);
+// when none are left it answers with a "[mock]" summary of the tool results it saw.
+import { BaseLlm } from '@google/adk';
+export const MOCK_PREFIX = '[mock]';
+function questionOf(request) {
+    for (const content of [...request.contents].reverse()) {
+        const text = content.parts?.find((p) => p.text)?.text;
+        if (content.role === 'user' && text)
+            return text;
+    }
+    return '';
+}
+export class MockLlm extends BaseLlm {
+    constructor() {
+        super({ model: 'mock' });
+    }
+    async *generateContentAsync(request) {
+        // Only the current turn counts: with a session, earlier questions and their tool calls are in the history too.
+        const turnStart = request.contents.findLastIndex((c) => c.role === 'user' && c.parts?.some((p) => p.text));
+        const parts = request.contents.slice(Math.max(turnStart, 0)).flatMap((c) => c.parts ?? []);
+        const called = new Set(parts.map((p) => p.functionCall?.name).filter(Boolean));
+        const question = questionOf(request);
+        for (const tool of Object.values(request.toolsDict ?? {})) {
+            if (called.has(tool.name))
+                continue;
+            const declaration = tool._getDeclaration();
+            const required = declaration?.parameters?.required ?? declaration?.parametersJsonSchema?.required ?? [];
+            // Agent-as-tool takes the question as `request`; tools needing other required args (e.g. traceId) are skipped.
+            if (required.some((name) => name !== 'request'))
+                continue;
+            const args = required.includes('request') ? { request: question } : {};
+            yield { content: { role: 'model', parts: [{ functionCall: { name: tool.name, args } }] }, turnComplete: true };
+            return;
+        }
+        const results = parts
+            .filter((p) => p.functionResponse)
+            .map((p) => `${p.functionResponse.name}: ${JSON.stringify(p.functionResponse.response).slice(0, 400)}`);
+        const text = `${MOCK_PREFIX} ${results.length ? results.join(' | ') : `no tools; question was: ${question}`}`;
+        yield { content: { role: 'model', parts: [{ text }] }, turnComplete: true };
+    }
+    async connect() {
+        throw new Error('MockLlm does not support live connections');
+    }
+}
+//# sourceMappingURL=mock-llm.js.map

package/dist/agents/mock-llm.js.map

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

package/dist/agents/model.d.ts

@@ -0,0 +1,5 @@
+import type { BaseLlm } from '@google/adk';
+export type AiMode = 'mock' | 'real';
+export type Env = Record<string, string | undefined>;
+export declare function resolveAiMode(env: Env): AiMode;
+export declare function getModel(env?: Env): Promise<BaseLlm | string>;

package/dist/agents/model.js

@@ -0,0 +1,20 @@
+import { MockLlm } from './mock-llm.js';
+export function resolveAiMode(env) {
+    const mode = env.OBSERVE_AI ?? 'mock';
+    if (mode !== 'mock' && mode !== 'real')
+        throw new Error(`OBSERVE_AI must be "mock" or "real", got "${mode}"`);
+    return mode;
+}
+export async function getModel(env = process.env) {
+    if (resolveAiMode(env) === 'mock')
+        return new MockLlm();
+    if (env.GEMINI_API_KEY) {
+        if (!env.GEMINI_MODEL)
+            throw new Error('GEMINI_API_KEY is set but GEMINI_MODEL is not — set the Gemini model name to use');
+        return env.GEMINI_MODEL; // ADK resolves gemini-* names and reads GEMINI_API_KEY itself
+    }
+    // Optional peer dependency: only needed when running real agents without a Gemini key.
+    const { KitanaLlm } = await import('@kitana-sdk/adk');
+    return new KitanaLlm({ model: env.OBSERVE_KITANA_MODEL ?? 'auto' });
+}
+//# sourceMappingURL=model.js.map

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"}