@cat-factory/orchestration 0.159.2 → 0.161.0

package/dist/modules/debug/RunDebugService.js

@@ -0,0 +1,190 @@
+import { deriveSignals, foldLlmRollup, toDebugAgentContextDetail, toDebugAgentContextEntry, toDebugLlmCall, toDebugRunStep, toDebugRunSummary, } from './debug.logic.js';
+import { toDebugLlmCallMessagesView } from './promptMessages.js';
+/**
+ * Take one row more than the caller asked for, so "is there another page?" is answered by the
+ * query rather than by a second COUNT — and mint the next cursor from the LAST row actually
+ * returned, which is the row the next page must resume strictly after.
+ */
+function paginate(rows, limit, key, project) {
+    const hasMore = rows.length > limit;
+    const kept = hasMore ? rows.slice(0, limit) : rows;
+    const last = kept[kept.length - 1];
+    return {
+        items: kept.map(project),
+        // Never the PEEKED row: resuming strictly after it would skip it entirely.
+        nextCursor: hasMore && last ? key(last) : null,
+    };
+}
+export class RunDebugService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * One bounded page of the workspace's runs, newest first. The entry point for a client that
+     * holds no run id — "which of my runs failed in the last hour" — and the only read here that
+     * is not already scoped to a single run.
+     */
+    async listRuns(workspaceId, opts) {
+        const rows = await this.deps.executionRepository.listRecent(workspaceId, {
+            limit: opts.limit + 1,
+            cursor: opts.cursor,
+            statuses: opts.status ? [opts.status] : undefined,
+            since: opts.since,
+        });
+        return paginate(rows, opts.limit, (run) => ({ createdAt: run.createdAt ?? 0, id: run.id }), toDebugRunSummary);
+    }
+    /** The run itself, or null when the workspace has no such run. */
+    getRun(workspaceId, runId) {
+        return this.deps.executionRepository.get(workspaceId, runId);
+    }
+    /**
+     * Whether the workspace has this run — the 404 guard the per-run detail lists apply on
+     * every page. A probe rather than {@link RunDebugService.getRun}: the guard discards the
+     * run, and `get` JSON-decodes the heaviest row in the request to answer a boolean.
+     */
+    runExists(workspaceId, runId) {
+        return this.deps.executionRepository.exists(workspaceId, runId);
+    }
+    /**
+     * The run's diagnostic map. Composed from AGGREGATES ONLY — four counts and one GROUP BY,
+     * no prompt, response or context body — which is what makes it cheap enough to be the first
+     * call a debugging client always issues, and what lets its `sinks` block stop the caller
+     * issuing four detail requests to discover three of them are empty.
+     *
+     * Takes the already-loaded run rather than a run id: the caller has to load it anyway to
+     * decide whether the key may see it, and re-reading it here would be a second decode of the
+     * heaviest row in the request.
+     */
+    async overview(workspaceId, execution) {
+        const runId = execution.id;
+        // Independent aggregates over four separate stores — issued together rather than in
+        // sequence, since the overview's whole value proposition is that it is one cheap call.
+        const [summaries, contextCount, searchCount, logCounts] = await Promise.all([
+            this.deps.llmCallMetricRepository?.summarizeByExecution(workspaceId, runId) ?? [],
+            this.deps.agentContextSnapshotRepository?.countByExecution(workspaceId, runId) ?? 0,
+            this.deps.agentSearchQueryRepository?.countByExecution(workspaceId, runId) ?? 0,
+            // Total + failures in one aggregate pass — the overview always wants both.
+            this.deps.provisioningLogRepository?.countByExecution(workspaceId, runId) ?? {
+                total: 0,
+                failures: 0,
+            },
+        ]);
+        const { totals, byAgentKind, byPhase } = foldLlmRollup(summaries);
+        const steps = execution.steps.map(toDebugRunStep);
+        const sinks = {
+            // The LLM call count is FOLDED from the per-kind rollup rather than counted separately:
+            // the two would be the same COUNT over the same rows, and a second query could only
+            // disagree with the breakdown it sits next to.
+            llmCalls: { available: !!this.deps.llmCallMetricRepository, count: totals.calls },
+            agentContext: {
+                available: !!this.deps.agentContextSnapshotRepository,
+                count: contextCount,
+            },
+            searchQueries: { available: !!this.deps.agentSearchQueryRepository, count: searchCount },
+            provisioningLog: { available: !!this.deps.provisioningLogRepository, count: logCounts.total },
+        };
+        return {
+            kind: 'cat-factory.run-debug-overview',
+            version: 1,
+            generatedAt: this.deps.clock.now(),
+            run: toDebugRunSummary(execution),
+            steps,
+            diagnostics: execution.diagnostics ?? null,
+            sinks,
+            llm: { totals, byAgentKind, byPhase },
+            signals: deriveSignals({
+                execution,
+                steps,
+                totals,
+                byAgentKind,
+                sinks,
+                provisioningFailures: logCounts.failures,
+            }),
+        };
+    }
+    /** One bounded page of the run's recorded model calls. */
+    async listLlmCalls(workspaceId, runId, opts) {
+        const repo = this.deps.llmCallMetricRepository;
+        if (!repo)
+            return { items: [], nextCursor: null };
+        const rows = await repo.listPage(workspaceId, {
+            executionId: runId,
+            limit: opts.limit + 1,
+            cursor: opts.cursor,
+            agentKind: opts.agentKind,
+            phase: opts.phase,
+            outcome: opts.outcome,
+            order: opts.order,
+            bodyChars: opts.bodyChars,
+            contains: opts.contains,
+        });
+        return paginate(rows, opts.limit, (call) => ({ createdAt: call.createdAt, id: call.id }), (call) => toDebugLlmCall(call));
+    }
+    /** One recorded call with its bodies windowed, or null when the workspace has no such call. */
+    async getLlmCall(workspaceId, callId, opts = {}) {
+        const repo = this.deps.llmCallMetricRepository;
+        if (!repo)
+            return null;
+        if (opts.view === 'messages') {
+            // The parse needs the COMPLETE delta (a truncated JSON array parses as nothing), so this
+            // view reads the row whole and windows in the projection instead of in SQL. That trades
+            // one whole-row transfer from the store — bounded by the store's own per-body cap — for a
+            // response whose messages are budgeted independently; the HTTP payload stays bounded
+            // either way.
+            const row = await repo.get(workspaceId, callId);
+            return row ? toDebugLlmCallMessagesView(row, opts.bodyChars ?? 0, opts.bodyOffset ?? 0) : null;
+        }
+        const row = await repo.get(workspaceId, callId, {
+            chars: opts.bodyChars,
+            offset: opts.bodyOffset,
+        });
+        return row ? toDebugLlmCall(row, opts.bodyOffset ?? 0) : null;
+    }
+    /** One bounded page of the run's captured dispatches — identity and sizes, never bodies. */
+    async listAgentContext(workspaceId, runId, opts) {
+        const repo = this.deps.agentContextSnapshotRepository;
+        if (!repo)
+            return { items: [], nextCursor: null };
+        const rows = await repo.listIndex(workspaceId, {
+            executionId: runId,
+            limit: opts.limit + 1,
+            cursor: opts.cursor,
+            stepIndex: opts.stepIndex,
+        });
+        return paginate(rows, opts.limit, (row) => ({ createdAt: row.createdAt, id: row.id }), toDebugAgentContextEntry);
+    }
+    /** One captured dispatch with every body budgeted independently. */
+    async getAgentContext(workspaceId, snapshotId, bodyChars, bodyOffset = 0) {
+        const repo = this.deps.agentContextSnapshotRepository;
+        if (!repo)
+            return null;
+        const snapshot = await repo.get(workspaceId, snapshotId);
+        return snapshot ? toDebugAgentContextDetail(snapshot, bodyChars, bodyOffset) : null;
+    }
+    /** One bounded page of the web searches the run's agents performed. */
+    async listSearchQueries(workspaceId, runId, opts) {
+        const repo = this.deps.agentSearchQueryRepository;
+        if (!repo)
+            return { items: [], nextCursor: null };
+        const rows = await repo.listPage(workspaceId, {
+            executionId: runId,
+            limit: opts.limit + 1,
+            cursor: opts.cursor,
+        });
+        return paginate(rows, opts.limit, (row) => ({ createdAt: row.createdAt, id: row.id }), (row) => row);
+    }
+    /** One bounded page of the run's provisioning event log. */
+    async listProvisioningLog(workspaceId, runId, opts) {
+        const repo = this.deps.provisioningLogRepository;
+        if (!repo)
+            return { items: [], nextCursor: null };
+        const rows = await repo.list(workspaceId, {
+            executionId: runId,
+            limit: opts.limit + 1,
+            cursor: opts.cursor,
+        });
+        return paginate(rows, opts.limit, (row) => ({ createdAt: row.createdAt, id: row.id }), (row) => row);
+    }
+}
+//# sourceMappingURL=RunDebugService.js.map

package/dist/modules/debug/RunDebugService.js.map

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

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

@@ -0,0 +1,104 @@
+import type { AgentContextSnapshot, AgentContextSnapshotIndex, ExecutionInstance, LlmCallBodySlice, LlmCallMetricPage, LlmCallMetricSummary, PipelineStep } from '@cat-factory/kernel';
+import type { DebugAgentContextDetail, DebugAgentContextEntry, DebugLlmCall, DebugRunStep, DebugRunSummary, DebugSignal, DebugSinkStatus, DebugText, LlmExportInsight, LlmExportTotals, LlmPhaseInsight } from '@cat-factory/contracts';
+import { classifyCall, isWarningFinishReason } from '../observability/observability.logic.js';
+/** Cap on the container post-mortem inlined on a step (it is a log tail, not a document). */
+export declare const MAX_EVICTION_DETAIL_CHARS = 4000;
+/**
+ * Slice a stored body to a caller's window and SAY SO. The metadata matters more than the
+ * text: a bare truncated string reads exactly like a short one, so a model handed the first
+ * 2 kB of a 40 kB reply would confidently report that the agent said almost nothing.
+ *
+ * `budget` of 0 returns no text at all while still reporting the full size — that is the
+ * shape a sweep uses, and the reason a size-only page is still worth reading. `offset`
+ * starts the window later, which is how the tail of a large body is reached; past the end
+ * it returns an empty slice whose `offset` is clamped to the total, so
+ * `offset + chars <= totalChars` always holds.
+ *
+ * Budgets, offsets and sizes are CODE POINTS (see {@link codePointLength}), matching the
+ * SQL-sliced bodies — and the cut walks whole code points, so it can never split a
+ * surrogate pair and hand the caller a lone half of one.
+ */
+export declare function sliceText(text: string, budget: number, offset?: number): DebugText;
+/**
+ * Project a body the STORE already sliced. The repository returns `{ text, totalChars }`
+ * because it cut the body in SQL (so the untaken bytes never left the database); this only
+ * re-derives the fields the wire shape adds. Deliberately does NOT re-slice: `text` is
+ * already within the window, and slicing again would silently disagree with `totalChars`.
+ *
+ * `offset` is the window start the caller asked the store for (0 for a list slice), clamped
+ * to the total so an ask past the end reports where the body actually stops. A search's
+ * per-body `matchOffset` rides through untouched — null (no match in this body) and absent
+ * (no search ran) stay distinct on the wire.
+ *
+ * `chars` and the truncation check count CODE POINTS, because `totalChars` came from SQL
+ * `length()` which counts the same — a JS `.length` here reads a SQL-cut emoji-bearing body
+ * as untruncated (see {@link codePointLength}).
+ */
+export declare function toDebugText(slice: LlmCallBodySlice, offset?: number): DebugText;
+/** Project a persisted run onto the lean summary every debug list and overview leads with. */
+export declare function toDebugRunSummary(execution: ExecutionInstance): DebugRunSummary;
+/** Project one pipeline step onto the debug view (identity + clocks + container mortality). */
+export declare function toDebugRunStep(step: PipelineStep, index: number): DebugRunStep;
+/**
+ * Project a bounded call-page row onto the wire shape. `bodyOffset` is the window start the
+ * store's slices were taken at (a point read's `?bodyOffset=`; always 0 on a list row).
+ */
+export declare function toDebugLlmCall(call: LlmCallMetricPage, bodyOffset?: number): DebugLlmCall;
+/** Project a snapshot index row onto the wire shape. */
+export declare function toDebugAgentContextEntry(row: AgentContextSnapshotIndex): DebugAgentContextEntry;
+/**
+ * Project a whole snapshot onto the wire shape, budgeting EVERY body INDEPENDENTLY rather
+ * than against one shared allowance. A snapshot routinely holds one enormous injected file
+ * next to the prompts, and a shared budget spent in array order would leave the prompts — the
+ * thing a reader almost always came for — empty because a README came first.
+ */
+export declare function toDebugAgentContextDetail(snapshot: AgentContextSnapshot, bodyChars: number, bodyOffset?: number): DebugAgentContextDetail;
+/**
+ * Fold the store's `(agentKind, phase)` rollup cells into the run-level totals + the two
+ * breakdowns the overview reports. Built from {@link LlmCallMetricSummary} — the aggregate the
+ * store computes without touching a text column — rather than from the calls themselves, so a
+ * 3,000-call run costs one GROUP BY here instead of reading 3,000 rows to add them up in
+ * JavaScript.
+ *
+ * Both breakdowns are folds over the SAME cells (kernel's `foldRollupsBy*`), so they total
+ * identically to each other and to `totals` by construction — the alternative, one aggregate
+ * per axis, could only ever produce two answers to the same question.
+ *
+ * The per-kind output reuses the metrics EXPORT's shapes on purpose: both describe the same
+ * run's model activity, and two independently-derived totals would eventually disagree.
+ */
+export declare function foldLlmRollup(summaries: LlmCallMetricSummary[]): {
+    totals: LlmExportTotals;
+    byAgentKind: LlmExportInsight[];
+    byPhase: LlmPhaseInsight[];
+};
+/** What {@link deriveSignals} needs beyond the run itself. */
+export interface SignalInput {
+    execution: ExecutionInstance;
+    steps: DebugRunStep[];
+    totals: LlmExportTotals;
+    byAgentKind: LlmExportInsight[];
+    sinks: {
+        llmCalls: DebugSinkStatus;
+        agentContext: DebugSinkStatus;
+        searchQueries: DebugSinkStatus;
+        provisioningLog: DebugSinkStatus;
+    };
+    /** Provisioning attempts for this run recorded as failures. */
+    provisioningFailures: number;
+}
+/**
+ * Precompute the diagnostic hints the overview publishes. Every one of these is derivable by
+ * the caller from the same payload — which is exactly the point: a model that has to
+ * rediscover "13 of 40 calls were truncated" by arithmetic over a JSON blob will sometimes get
+ * it wrong and will always spend context getting it right. Ordered most-severe first, so a
+ * reader that truncates the list keeps what matters.
+ *
+ * Deliberately NOT a verdict. Each signal names one observation and its magnitude; nothing
+ * here claims to know why the run failed, because a wrong confident cause is worse for a
+ * debugging client than an ordered list of facts.
+ */
+export declare function deriveSignals(input: SignalInput): DebugSignal[];
+/** Re-exported so the service and its tests classify a call exactly as the SPA does. */
+export { classifyCall, isWarningFinishReason };
+//# sourceMappingURL=debug.logic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/debug/debug.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,WAAW,EACX,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,eAAe,EAChB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAEL,YAAY,EACZ,qBAAqB,EAGtB,MAAM,yCAAyC,CAAA;AAOhD,6FAA6F;AAC7F,eAAO,MAAM,yBAAyB,OAAQ,CAAA;AA+B9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,SAAS,CAiB7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAI,GAAG,SAAS,CAU1E;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,iBAAiB,GAAG,eAAe,CAY/E;AAED,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAwB9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,UAAU,SAAI,GAAG,YAAY,CAgCpF;AAED,wDAAwD;AACxD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,yBAAyB,GAAG,sBAAsB,CAa/F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,SAAI,GACb,uBAAuB,CAuBzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG;IAChE,MAAM,EAAE,eAAe,CAAA;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAA;IAC/B,OAAO,EAAE,eAAe,EAAE,CAAA;CAC3B,CAkEA;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,iBAAiB,CAAA;IAC5B,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,MAAM,EAAE,eAAe,CAAA;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAA;IAC/B,KAAK,EAAE;QACL,QAAQ,EAAE,eAAe,CAAA;QACzB,YAAY,EAAE,eAAe,CAAA;QAC7B,aAAa,EAAE,eAAe,CAAA;QAC9B,eAAe,EAAE,eAAe,CAAA;KACjC,CAAA;IACD,+DAA+D;IAC/D,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,CAkJ/D;AAED,wFAAwF;AACxF,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,CAAA"}