@cat-factory/orchestration 0.6.0

package/dist/modules/observability/LlmObservabilityService.d.ts

@@ -0,0 +1,121 @@
+import type { Clock, IdGenerator } from '@cat-factory/kernel';
+import type { LlmCallMetric, LlmCallMetricRepository, LlmCallMetricSummary, LlmTraceSink } from '@cat-factory/kernel';
+import type { LlmMetricsExport } from '@cat-factory/contracts';
+export interface LlmObservabilityServiceDependencies {
+    llmCallMetricRepository: LlmCallMetricRepository;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    /**
+     * Whether to persist the full prompt body with each metric. Defaults to true. When
+     * false, every numeric field (tokens, timing, finish reason, message/tool counts)
+     * is still recorded but the prompt is stored empty — for deployments that must not
+     * retain the complete prompts sent to the model. Governed by `LLM_RECORD_PROMPTS`.
+     */
+    recordPrompts?: boolean;
+    /**
+     * Optional external trace sink (e.g. Langfuse). When wired, every recorded call is
+     * ALSO emitted here as a generation — the same code path the inline executor's
+     * instrumented model provider feeds, so proxied and inline calls land in one place.
+     * Fan-out is best-effort and never blocks or breaks the local recording.
+     */
+    traceSink?: LlmTraceSink;
+}
+/**
+ * Defensive upper bound on a stored prompt/response body (characters). Real agent
+ * prompts sit far below this; the cap exists only so a pathological body can't blow
+ * past the store's per-row/value limit and make the whole metric fail to record
+ * (which would drop the call from observability entirely). A truncated-but-recorded
+ * body is strictly more useful than a silently dropped one.
+ */
+export declare const MAX_BODY_CHARS: number;
+/** Default cap on how many (newest) calls a list/export returns. */
+export declare const DEFAULT_LIST_LIMIT = 1000;
+/**
+ * Details of one proxied LLM call, handed in by the LLM proxy. The proxy owns the
+ * timing (it wraps the upstream call): {@link totalMs} is the end-to-end time it
+ * spent and {@link upstreamMs} the slice waiting on the model — the difference is
+ * transport/proxy overhead, derived here so the two can never disagree.
+ */
+export interface RecordLlmCallInput {
+    /**
+     * The call's id. The proxy mints it so the same id is carried on the live `llmCall`
+     * activity event AND this persisted row — the drill-down panel keys its lazy body
+     * load by it. Optional: when omitted the service mints one (existing callers).
+     */
+    id?: string;
+    workspaceId: string;
+    executionId: string | null;
+    agentKind: string;
+    provider: string;
+    model: string;
+    streaming: boolean;
+    messageCount: number;
+    toolCount: number;
+    requestMaxTokens: number | null;
+    promptTokens: number;
+    cachedPromptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    finishReason: string | null;
+    /** End-to-end time the proxy spent on the call (ms). */
+    totalMs: number;
+    /** Time spent waiting on the upstream model (ms). */
+    upstreamMs: number;
+    ok: boolean;
+    httpStatus: number | null;
+    errorMessage: string | null;
+    promptText: string;
+    responseText: string;
+    /** The model's reasoning/thinking trace, when emitted on a separate channel (else ''). */
+    reasoningText: string;
+}
+/**
+ * The LLM observability sink. The proxy meters every container-agent model call
+ * here; the engine rolls the per-run aggregates onto pipeline steps for the board,
+ * and a query endpoint lists the full per-call detail for the drill-down panel. It
+ * is the observability sibling of {@link SpendService} (which keeps only billed
+ * totals): this keeps the full prompt/response, the output-limit headroom and the
+ * transport-vs-execution latency split. Wired only when a metric repository is
+ * present, so tests and unconfigured facades are unaffected.
+ */
+export declare class LlmObservabilityService {
+    private readonly repository;
+    private readonly idGenerator;
+    private readonly clock;
+    private readonly recordPrompts;
+    private readonly traceSink?;
+    constructor({ llmCallMetricRepository, idGenerator, clock, recordPrompts, traceSink, }: LlmObservabilityServiceDependencies);
+    /**
+     * Persist one metered call, assigning its id + timestamp and deriving the overhead.
+     * When prompt recording is enabled, the prompt is stored as a DELTA against the
+     * previous call in the same `(execution, agentKind)` conversation — a container
+     * agent re-sends its whole growing history every call, so storing only the new
+     * messages collapses ~21× of redundant prompt bytes (see `computeStoredPrompt`). The
+     * full prompt is rebuilt on export. The chain-tip lookup is off the response path
+     * (the proxy records via `waitUntil`), so the extra read is free of user latency.
+     * When prompt recording is disabled (`recordPrompts: false`) the prompt body is
+     * stored empty and the chain-tip read is skipped entirely — the numeric telemetry is
+     * still recorded.
+     */
+    record(input: RecordLlmCallInput): Promise<void>;
+    /**
+     * Resolve this call's prompt to a delta against the chain tip of its
+     * `(workspace, execution, agentKind)` conversation (or the full array when it can't
+     * be chained). Only reached when prompt recording is enabled.
+     */
+    private computeStoredPromptForChain;
+    /**
+     * Calls recorded for a run, newest first (full prompt/response included), capped
+     * at {@link DEFAULT_LIST_LIMIT} so a long run can't produce an unbounded payload.
+     */
+    listByExecution(workspaceId: string, executionId: string, limit?: number): Promise<LlmCallMetric[]>;
+    /** Per-agent-kind aggregates for a run, for the board step rollups. */
+    summarizeByExecution(workspaceId: string, executionId: string): Promise<LlmCallMetricSummary[]>;
+    /**
+     * Build the LLM-friendly export for a run: a self-describing JSON bundle (totals +
+     * per-agent insights + every call, with derived ratios) meant to be handed to a
+     * model for analysis. Stamped with the service clock.
+     */
+    exportForExecution(workspaceId: string, executionId: string): Promise<LlmMetricsExport>;
+}
+//# sourceMappingURL=LlmObservabilityService.d.ts.map

package/dist/modules/observability/LlmObservabilityService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LlmObservabilityService.d.ts","sourceRoot":"","sources":["../../../src/modules/observability/LlmObservabilityService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EACV,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAI9D,MAAM,WAAW,mCAAmC;IAClD,uBAAuB,EAAE,uBAAuB,CAAA;IAChD,WAAW,EAAE,WAAW,CAAA;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,YAAY,CAAA;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAa,CAAA;AAQxC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAKtC;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,OAAO,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,EAAE,EAAE,OAAO,CAAA;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,0FAA0F;IAC1F,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAc;IAEzC,YAAY,EACV,uBAAuB,EACvB,WAAW,EACX,KAAK,EACL,aAAoB,EACpB,SAAS,GACV,EAAE,mCAAmC,EAMrC;IAED;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDrD;IAED;;;;OAIG;YACW,2BAA2B;IAYzC;;;OAGG;IACH,eAAe,CACb,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAA2B,GACjC,OAAO,CAAC,aAAa,EAAE,CAAC,CAE1B;IAED,uEAAuE;IACvE,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAE9F;IAED;;;;OAIG;IACG,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAG5F;CACF"}

package/dist/modules/observability/LlmObservabilityService.js

@@ -0,0 +1,140 @@
+import { buildLlmMetricsExport, computeStoredPrompt } from './observability.logic.js';
+/**
+ * Defensive upper bound on a stored prompt/response body (characters). Real agent
+ * prompts sit far below this; the cap exists only so a pathological body can't blow
+ * past the store's per-row/value limit and make the whole metric fail to record
+ * (which would drop the call from observability entirely). A truncated-but-recorded
+ * body is strictly more useful than a silently dropped one.
+ */
+export const MAX_BODY_CHARS = 512 * 1024;
+/** Cap a body to {@link MAX_BODY_CHARS}, marking where it was cut. */
+function clampBody(text) {
+    if (text.length <= MAX_BODY_CHARS)
+        return text;
+    return `${text.slice(0, MAX_BODY_CHARS)}\n…[truncated ${text.length - MAX_BODY_CHARS} chars]`;
+}
+/** Default cap on how many (newest) calls a list/export returns. */
+export const DEFAULT_LIST_LIMIT = 1000;
+/** What to store for a call's prompt when prompt recording is turned off: nothing. */
+const EMPTY_STORED_PROMPT = { promptText: '', promptPrefixCount: 0, promptHash: '' };
+/**
+ * The LLM observability sink. The proxy meters every container-agent model call
+ * here; the engine rolls the per-run aggregates onto pipeline steps for the board,
+ * and a query endpoint lists the full per-call detail for the drill-down panel. It
+ * is the observability sibling of {@link SpendService} (which keeps only billed
+ * totals): this keeps the full prompt/response, the output-limit headroom and the
+ * transport-vs-execution latency split. Wired only when a metric repository is
+ * present, so tests and unconfigured facades are unaffected.
+ */
+export class LlmObservabilityService {
+    repository;
+    idGenerator;
+    clock;
+    recordPrompts;
+    traceSink;
+    constructor({ llmCallMetricRepository, idGenerator, clock, recordPrompts = true, traceSink, }) {
+        this.repository = llmCallMetricRepository;
+        this.idGenerator = idGenerator;
+        this.clock = clock;
+        this.recordPrompts = recordPrompts;
+        this.traceSink = traceSink;
+    }
+    /**
+     * Persist one metered call, assigning its id + timestamp and deriving the overhead.
+     * When prompt recording is enabled, the prompt is stored as a DELTA against the
+     * previous call in the same `(execution, agentKind)` conversation — a container
+     * agent re-sends its whole growing history every call, so storing only the new
+     * messages collapses ~21× of redundant prompt bytes (see `computeStoredPrompt`). The
+     * full prompt is rebuilt on export. The chain-tip lookup is off the response path
+     * (the proxy records via `waitUntil`), so the extra read is free of user latency.
+     * When prompt recording is disabled (`recordPrompts: false`) the prompt body is
+     * stored empty and the chain-tip read is skipped entirely — the numeric telemetry is
+     * still recorded.
+     */
+    async record(input) {
+        const overheadMs = Math.max(0, input.totalMs - input.upstreamMs);
+        const stored = this.recordPrompts
+            ? await this.computeStoredPromptForChain(input)
+            : EMPTY_STORED_PROMPT;
+        const metric = {
+            createdAt: this.clock.now(),
+            ...input,
+            // Derived/bounded fields last, so they win over any same-named input field.
+            // `id` here (not above `...input`) so an absent `input.id` falls back to a mint
+            // rather than being spread in as `undefined`.
+            id: input.id ?? this.idGenerator.next('llm'),
+            overheadMs,
+            promptText: clampBody(stored.promptText),
+            promptPrefixCount: stored.promptPrefixCount,
+            promptHash: stored.promptHash,
+            responseText: clampBody(input.responseText),
+            reasoningText: clampBody(input.reasoningText),
+        };
+        await this.repository.record(metric);
+        // Fan out to the external trace sink (Langfuse), if wired. We send the FULL prompt
+        // (not the stored delta) so the trace is self-contained, honouring the same
+        // `recordPrompts` privacy switch as the local store. Best-effort and NON-blocking:
+        // dispatched without awaiting (like the inline feeder) so the sink's network round
+        // trip never extends the metering path, and isolated so a sink failure can't break
+        // local recording. The sink itself swallows + logs and bounds its own request.
+        if (this.traceSink) {
+            const endedAt = metric.createdAt;
+            try {
+                void Promise.resolve(this.traceSink.recordGeneration({
+                    workspaceId: input.workspaceId,
+                    executionId: input.executionId,
+                    agentKind: input.agentKind,
+                    provider: input.provider,
+                    model: input.model,
+                    startedAt: Math.max(0, endedAt - input.upstreamMs),
+                    endedAt,
+                    promptTokens: input.promptTokens,
+                    completionTokens: input.completionTokens,
+                    totalTokens: input.totalTokens,
+                    finishReason: input.finishReason,
+                    ok: input.ok,
+                    errorMessage: input.errorMessage,
+                    input: this.recordPrompts ? input.promptText : '',
+                    // Fall back to the reasoning trace when the turn produced no response text
+                    // (a thinking model that spent its budget reasoning) so the trace isn't blank.
+                    output: this.recordPrompts ? input.responseText || input.reasoningText : '',
+                })).catch(() => { });
+            }
+            catch {
+                // Swallowed: the sink itself logs; observability never breaks the proxy.
+            }
+        }
+    }
+    /**
+     * Resolve this call's prompt to a delta against the chain tip of its
+     * `(workspace, execution, agentKind)` conversation (or the full array when it can't
+     * be chained). Only reached when prompt recording is enabled.
+     */
+    async computeStoredPromptForChain(input) {
+        const prev = input.executionId != null
+            ? await this.repository.latestChainTip(input.workspaceId, input.executionId, input.agentKind)
+            : null;
+        return computeStoredPrompt(input.promptText, prev);
+    }
+    /**
+     * Calls recorded for a run, newest first (full prompt/response included), capped
+     * at {@link DEFAULT_LIST_LIMIT} so a long run can't produce an unbounded payload.
+     */
+    listByExecution(workspaceId, executionId, limit = DEFAULT_LIST_LIMIT) {
+        return this.repository.listByExecution(workspaceId, executionId, limit);
+    }
+    /** Per-agent-kind aggregates for a run, for the board step rollups. */
+    summarizeByExecution(workspaceId, executionId) {
+        return this.repository.summarizeByExecution(workspaceId, executionId);
+    }
+    /**
+     * Build the LLM-friendly export for a run: a self-describing JSON bundle (totals +
+     * per-agent insights + every call, with derived ratios) meant to be handed to a
+     * model for analysis. Stamped with the service clock.
+     */
+    async exportForExecution(workspaceId, executionId) {
+        const calls = await this.listByExecution(workspaceId, executionId);
+        return buildLlmMetricsExport(executionId, calls, this.clock.now());
+    }
+}
+//# sourceMappingURL=LlmObservabilityService.js.map

package/dist/modules/observability/LlmObservabilityService.js.map

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

package/dist/modules/observability/observability.logic.d.ts

@@ -0,0 +1,57 @@
+import { type LlmCallMetric } from '@cat-factory/kernel';
+import type { LlmMetricsExport } from '@cat-factory/contracts';
+export type LlmCallOutcome = 'ok' | 'warning' | 'error';
+/** Whether a finish reason is a (non-fatal) warning — output truncated or filtered. */
+export declare function isWarningFinishReason(finishReason: string | null): boolean;
+/**
+ * Classify a recorded call: a non-2xx/failed call is an `error`; a successful call
+ * cut short by the output limit or content filter is a `warning`; otherwise `ok`.
+ */
+export declare function classifyCall(metric: Pick<LlmCallMetric, 'ok' | 'finishReason'>): LlmCallOutcome;
+/**
+ * Fraction (0..1) of the output budget the largest single completion consumed, or
+ * null when the ceiling is unknown. 1 (or a `length` finish) means a call was
+ * truncated. Drives the board's "output-limit headroom" bar.
+ */
+export declare function outputHeadroomRatio(peakCompletionTokens: number, maxOutputTokens: number | null): number | null;
+/** Share of total latency spent in transport/proxy overhead (0..1), or null when no timing. */
+export declare function transportOverheadRatio(upstreamMs: number, overheadMs: number): number | null;
+/** The previous call's chain tip: enough to decide if the next call extends it. */
+export interface PromptChainTip {
+    /** The previous call's full message count (its `messageCount`). */
+    messageCount: number;
+    /** The previous call's {@link LlmCallMetric.promptHash} (hash of its full array). */
+    promptHash: string;
+}
+/** What to store for a call's prompt after delta compression. */
+export interface StoredPrompt {
+    promptText: string;
+    promptPrefixCount: number;
+    promptHash: string;
+}
+/** Fast, stable, dependency-free hash (FNV-1a, length-salted) for chain validation. */
+export declare function hashPrompt(text: string): string;
+/**
+ * Compute what to store for a call's prompt: the delta (new messages only) when this
+ * call provably extends the previous one in its chain, else the full array. The
+ * returned {@link StoredPrompt.promptHash} is always over the FULL array so the next
+ * call can chain onto this one. `fullPromptText` is the proxy's `JSON.stringify(messages)`.
+ */
+export declare function computeStoredPrompt(fullPromptText: string, prev: PromptChainTip | null): StoredPrompt;
+/**
+ * Rebuild each call's FULL prompt from the stored deltas. Calls are grouped by agent
+ * kind (each kind is its own conversation chain) and replayed oldest-first,
+ * accumulating the running message array; a call with `promptPrefixCount === 0` resets
+ * the chain. Best-effort: if a chain's head is missing (e.g. truncated by a list
+ * limit) a delta that can't be rebuilt is returned as-is. The returned calls preserve
+ * the input order, with `promptText` set to the full array and `promptPrefixCount` 0.
+ */
+export declare function reconstructPrompts(calls: LlmCallMetric[]): LlmCallMetric[];
+/**
+ * Build the LLM-friendly export bundle for a run from its recorded calls: a
+ * self-describing JSON document (totals + per-agent insights + every call, with
+ * derived ratios precomputed) meant to be handed straight to a model for analysis.
+ * Pure so it is unit-testable; `generatedAt` is injected (no clock here).
+ */
+export declare function buildLlmMetricsExport(executionId: string, storedCalls: LlmCallMetric[], generatedAt: number): LlmMetricsExport;
+//# sourceMappingURL=observability.logic.d.ts.map

package/dist/modules/observability/observability.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/observability/observability.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACpF,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAMhF,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvD,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAI1E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,cAAc,CAAC,GAAG,cAAc,CAI/F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,oBAAoB,EAAE,MAAM,EAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B,MAAM,GAAG,IAAI,CAGf;AAED,+FAA+F;AAC/F,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5F;AAkBD,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,cAAc,GAAG,IAAI,GAC1B,YAAY,CAkBd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAgC1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,aAAa,EAAE,EAC5B,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAwDlB"}

package/dist/modules/observability/observability.logic.js

@@ -0,0 +1,186 @@
+import { LLM_WARNING_FINISH_REASONS } from '@cat-factory/kernel';
+/** Whether a finish reason is a (non-fatal) warning — output truncated or filtered. */
+export function isWarningFinishReason(finishReason) {
+    return (finishReason != null && LLM_WARNING_FINISH_REASONS.includes(finishReason));
+}
+/**
+ * Classify a recorded call: a non-2xx/failed call is an `error`; a successful call
+ * cut short by the output limit or content filter is a `warning`; otherwise `ok`.
+ */
+export function classifyCall(metric) {
+    if (!metric.ok)
+        return 'error';
+    if (isWarningFinishReason(metric.finishReason))
+        return 'warning';
+    return 'ok';
+}
+/**
+ * Fraction (0..1) of the output budget the largest single completion consumed, or
+ * null when the ceiling is unknown. 1 (or a `length` finish) means a call was
+ * truncated. Drives the board's "output-limit headroom" bar.
+ */
+export function outputHeadroomRatio(peakCompletionTokens, maxOutputTokens) {
+    if (maxOutputTokens == null || maxOutputTokens <= 0)
+        return null;
+    return Math.min(1, peakCompletionTokens / maxOutputTokens);
+}
+/** Share of total latency spent in transport/proxy overhead (0..1), or null when no timing. */
+export function transportOverheadRatio(upstreamMs, overheadMs) {
+    const total = upstreamMs + overheadMs;
+    return total > 0 ? overheadMs / total : null;
+}
+/** Fast, stable, dependency-free hash (FNV-1a, length-salted) for chain validation. */
+export function hashPrompt(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        // FNV prime, kept in 32-bit range via Math.imul.
+        h = Math.imul(h, 0x01000193);
+    }
+    // Salt with the length so two same-hash-different-length strings can't collide.
+    return `${text.length.toString(36)}:${(h >>> 0).toString(36)}`;
+}
+function parseMessages(promptText) {
+    try {
+        const parsed = JSON.parse(promptText);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute what to store for a call's prompt: the delta (new messages only) when this
+ * call provably extends the previous one in its chain, else the full array. The
+ * returned {@link StoredPrompt.promptHash} is always over the FULL array so the next
+ * call can chain onto this one. `fullPromptText` is the proxy's `JSON.stringify(messages)`.
+ */
+export function computeStoredPrompt(fullPromptText, prev) {
+    const promptHash = hashPrompt(fullPromptText);
+    const full = parseMessages(fullPromptText);
+    // No previous tip, unparseable, or not actually longer ⇒ store the full array.
+    if (!full || !prev || prev.messageCount <= 0 || full.length < prev.messageCount) {
+        return { promptText: fullPromptText, promptPrefixCount: 0, promptHash };
+    }
+    // Only elide when the leading `prev.messageCount` messages match what the previous
+    // call stored (append-only). A mismatch (fresh conversation / compaction) ⇒ full.
+    const prefix = JSON.stringify(full.slice(0, prev.messageCount));
+    if (hashPrompt(prefix) !== prev.promptHash) {
+        return { promptText: fullPromptText, promptPrefixCount: 0, promptHash };
+    }
+    return {
+        promptText: JSON.stringify(full.slice(prev.messageCount)),
+        promptPrefixCount: prev.messageCount,
+        promptHash,
+    };
+}
+/**
+ * Rebuild each call's FULL prompt from the stored deltas. Calls are grouped by agent
+ * kind (each kind is its own conversation chain) and replayed oldest-first,
+ * accumulating the running message array; a call with `promptPrefixCount === 0` resets
+ * the chain. Best-effort: if a chain's head is missing (e.g. truncated by a list
+ * limit) a delta that can't be rebuilt is returned as-is. The returned calls preserve
+ * the input order, with `promptText` set to the full array and `promptPrefixCount` 0.
+ */
+export function reconstructPrompts(calls) {
+    // Order by time, then message count, then id. Records are written off the response
+    // path (`waitUntil`) so two calls can share a `createdAt` millisecond; `messageCount`
+    // is monotonic within an append-only chain, so it breaks such ties in true
+    // conversation order (id is the last resort when even that is equal).
+    const asc = [...calls].sort((a, b) => a.createdAt - b.createdAt || a.messageCount - b.messageCount || a.id.localeCompare(b.id));
+    const running = new Map();
+    const fullById = new Map();
+    for (const c of asc) {
+        const delta = parseMessages(c.promptText) ?? [];
+        let full;
+        if (c.promptPrefixCount > 0) {
+            const prev = running.get(c.agentKind) ?? [];
+            // Only rebuild when we actually hold the referenced prefix; else keep the delta.
+            full =
+                prev.length >= c.promptPrefixCount
+                    ? [...prev.slice(0, c.promptPrefixCount), ...delta]
+                    : delta;
+        }
+        else {
+            full = delta;
+        }
+        running.set(c.agentKind, full);
+        fullById.set(c.id, JSON.stringify(full));
+    }
+    return calls.map((c) => ({
+        ...c,
+        promptText: fullById.get(c.id) ?? c.promptText,
+        promptPrefixCount: 0,
+    }));
+}
+/**
+ * Build the LLM-friendly export bundle for a run from its recorded calls: a
+ * self-describing JSON document (totals + per-agent insights + every call, with
+ * derived ratios precomputed) meant to be handed straight to a model for analysis.
+ * Pure so it is unit-testable; `generatedAt` is injected (no clock here).
+ */
+export function buildLlmMetricsExport(executionId, storedCalls, generatedAt) {
+    // The export is a self-contained analysis bundle, so rebuild each call's full
+    // prompt from the stored deltas before assembling it.
+    const calls = reconstructPrompts(storedCalls);
+    const byKind = new Map();
+    for (const call of calls) {
+        const list = byKind.get(call.agentKind);
+        if (list)
+            list.push(call);
+        else
+            byKind.set(call.agentKind, [call]);
+    }
+    const insights = [...byKind.entries()].map(([agentKind, kindCalls]) => {
+        const promptTokens = sum(kindCalls, (c) => c.promptTokens);
+        const completionTokens = sum(kindCalls, (c) => c.completionTokens);
+        const peakCompletionTokens = kindCalls.reduce((m, c) => Math.max(m, c.completionTokens), 0);
+        const maxOutputTokens = maxNullable(kindCalls.map((c) => c.requestMaxTokens));
+        const upstreamMs = sum(kindCalls, (c) => c.upstreamMs);
+        const overheadMs = sum(kindCalls, (c) => c.overheadMs);
+        return {
+            agentKind,
+            calls: kindCalls.length,
+            promptTokens,
+            completionTokens,
+            peakCompletionTokens,
+            maxOutputTokens,
+            outputHeadroomRatio: outputHeadroomRatio(peakCompletionTokens, maxOutputTokens),
+            truncatedCalls: kindCalls.filter((c) => c.finishReason === 'length').length,
+            upstreamMs,
+            overheadMs,
+            transportOverheadRatio: transportOverheadRatio(upstreamMs, overheadMs),
+            errors: kindCalls.filter((c) => !c.ok).length,
+            warnings: kindCalls.filter((c) => c.ok && isWarningFinishReason(c.finishReason)).length,
+        };
+    });
+    const upstreamMs = sum(calls, (c) => c.upstreamMs);
+    const overheadMs = sum(calls, (c) => c.overheadMs);
+    return {
+        kind: 'cat-factory.llm-metrics-export',
+        version: 1,
+        executionId,
+        generatedAt,
+        totals: {
+            calls: calls.length,
+            promptTokens: sum(calls, (c) => c.promptTokens),
+            completionTokens: sum(calls, (c) => c.completionTokens),
+            upstreamMs,
+            overheadMs,
+            transportOverheadRatio: transportOverheadRatio(upstreamMs, overheadMs),
+            errors: calls.filter((c) => !c.ok).length,
+            warnings: calls.filter((c) => c.ok && isWarningFinishReason(c.finishReason)).length,
+            truncatedCalls: calls.filter((c) => c.finishReason === 'length').length,
+        },
+        insights,
+        calls,
+    };
+}
+function sum(items, pick) {
+    return items.reduce((acc, item) => acc + pick(item), 0);
+}
+function maxNullable(values) {
+    const present = values.filter((v) => v != null);
+    return present.length > 0 ? Math.max(...present) : null;
+}
+//# sourceMappingURL=observability.logic.js.map

package/dist/modules/observability/observability.logic.js.map

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

package/dist/modules/pipelines/PipelineService.d.ts

@@ -0,0 +1,54 @@
+import type { ClonePipelineInput, CreatePipelineInput, OrganizePipelineInput, UpdatePipelineInput } from '@cat-factory/contracts';
+import type { Pipeline } from '@cat-factory/kernel';
+import type { DatadogConnectionRepository, PipelineRepository, WorkspaceRepository } from '@cat-factory/kernel';
+import type { IdGenerator } from '@cat-factory/kernel';
+export interface PipelineServiceDependencies {
+    workspaceRepository: WorkspaceRepository;
+    pipelineRepository: PipelineRepository;
+    idGenerator: IdGenerator;
+    /**
+     * Resolves whether the workspace has any observability integration enabled (today: a
+     * Datadog connection). When absent (no observability persistence wired at all), the
+     * observability-gated step can never be added.
+     */
+    datadogConnectionRepository?: DatadogConnectionRepository;
+}
+/** Saved, reusable pipelines (the pipeline palette). */
+export declare class PipelineService {
+    private readonly workspaceRepository;
+    private readonly pipelineRepository;
+    private readonly idGenerator;
+    private readonly datadogConnectionRepository?;
+    constructor({ workspaceRepository, pipelineRepository, idGenerator, datadogConnectionRepository, }: PipelineServiceDependencies);
+    /**
+     * The post-release-health gate is only meaningful with an observability integration, so
+     * reject a chain that includes an ENABLED post-release-health step unless the workspace
+     * has one wired. Validated only when the chain/enable mask is being authored (create, or
+     * an update that changes them) so an unrelated edit to an existing pipeline never trips.
+     */
+    private assertObservabilityGatedStepAllowed;
+    private requireWorkspace;
+    list(workspaceId: string): Promise<Pipeline[]>;
+    create(workspaceId: string, input: CreatePipelineInput): Promise<Pipeline>;
+    /**
+     * Clone any pipeline (built-in or custom) into a new, editable copy. The copy keeps
+     * the source's steps / gates / thresholds / enable flags but is never `builtin`, so
+     * it can be edited — this is how a built-in template is "made editable".
+     */
+    clone(workspaceId: string, sourceId: string, input: ClonePipelineInput): Promise<Pipeline>;
+    /**
+     * Edit a custom pipeline in place. Only the supplied fields change; passing
+     * `agentKinds` replaces the whole chain and re-aligns the parallel arrays. Built-in
+     * catalog templates are read-only and reject this — clone them first.
+     */
+    update(workspaceId: string, id: string, input: UpdatePipelineInput): Promise<Pipeline>;
+    remove(workspaceId: string, id: string): Promise<void>;
+    /**
+     * Set a pipeline's organizational metadata (labels and/or archive state). This is the
+     * ONLY mutation allowed on a BUILT-IN pipeline — it touches the library view, not the
+     * pipeline's structure, so a built-in can be tagged or archived while staying read-only
+     * for its steps. Only the supplied fields change.
+     */
+    organize(workspaceId: string, id: string, input: OrganizePipelineInput): Promise<Pipeline>;
+}
+//# sourceMappingURL=PipelineService.d.ts.map

package/dist/modules/pipelines/PipelineService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PipelineService.d.ts","sourceRoot":"","sources":["../../../src/modules/pipelines/PipelineService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAuB,QAAQ,EAAc,MAAM,qBAAqB,CAAA;AAEpF,OAAO,KAAK,EACV,2BAA2B,EAC3B,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAWtD,MAAM,WAAW,2BAA2B;IAC1C,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,kBAAkB,EAAE,kBAAkB,CAAA;IACtC,WAAW,EAAE,WAAW,CAAA;IACxB;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,2BAA2B,CAAA;CAC1D;AAED,wDAAwD;AACxD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAA6B;IAE1E,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,2BAA2B,GAC5B,EAAE,2BAA2B,EAK7B;IAED;;;;;OAKG;YACW,mCAAmC;IAiBjD,OAAO,CAAC,gBAAgB;IAIlB,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGnD;IAEK,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsB/E;IAED;;;;OAIG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6B/F;IAED;;;;OAIG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuC3F;IAEK,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS3D;IAED;;;;;OAKG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAc/F;CACF"}