@cat-factory/contracts 0.6.0

package/dist/notifications.js

@@ -0,0 +1,125 @@
+import * as v from 'valibot';
+import { mergeAssessmentSchema } from './merge.js';
+import { onCallAssessmentSchema, releaseSignalSchema } from './release.js';
+// ---------------------------------------------------------------------------
+// Notification wire contracts. A notification is a first-class, human-actionable
+// item surfaced on the board that is NOT a mid-pipeline gate (those are
+// Decisions / approval gates parked inside a running pipeline). Notifications
+// outlive the run that raised them and are resolved out-of-band:
+//   - `merge_review`     — a `merger` agent scored a PR outside the task's
+//                          auto-merge thresholds; a human decides whether to merge.
+//   - `pipeline_complete`— a pipeline with no `merger` step finished; a human
+//                          confirms the work as complete (and merges the PR).
+//   - `ci_failed`        — the `ci-fixer` agent exhausted its attempt budget and
+//                          CI is still red; a human takes over.
+//   - `test_failed`      — the `fixer` agent exhausted its attempt budget (or there
+//                          was no PR branch to fix) and the `tester` still withholds
+//                          its greenlight; a human takes over.
+//   - `requirement_review`— a requirements-review agent raised findings on a task
+//                          (gaps / clarifications / risks); product people + the
+//                          task's creator are told to go react to them. Purely
+//                          informational (no typed side-effect — `act` just marks
+//                          it read), unlike the engineering notifications above.
+//   - `clarity_review`    — a clarity-review (bug-report triage) agent raised findings
+//                          on a bug task; same informational shape as `requirement_review`.
+//   - `release_regression`— the post-release-health gate detected a Datadog monitor/SLO
+//                          regression after deploy and the `on-call` agent investigated;
+//                          a human decides whether to revert the PR or acknowledge. Carries
+//                          the on-call assessment + the regressed signals in its payload.
+//   - `decision_required`— an iterative gate parked on a human decision after spending
+//                          its automatic budget (a quality companion at its rework cap,
+//                          or the requirements reviewer at its iteration cap). Without
+//                          this the three-choice decision is reachable only by drilling
+//                          into the parked step, so the run looks silently stuck; acting
+//                          on it opens that step's decision surface.
+//
+// In-app delivery is the only channel today, but the core models delivery behind
+// a `NotificationChannel` port so email / Slack channels can be added later
+// without touching the call sites that raise notifications.
+// ---------------------------------------------------------------------------
+/**
+ * The kind of human-actionable event a notification represents. A closed set so
+ * the frontend can switch on it to render the right action; extending it is a
+ * one-line change here plus a handler in the worker's `act` route.
+ */
+export const notificationTypeSchema = v.picklist([
+    'merge_review',
+    'pipeline_complete',
+    'ci_failed',
+    'test_failed',
+    'requirement_review',
+    'clarity_review',
+    'release_regression',
+    'decision_required',
+]);
+/**
+ * Lifecycle of a notification: `open` until a human engages, terminal `acted`
+ * once its action ran (merged, confirmed, retried…), or `dismissed` when waved
+ * off. Only `open` notifications surface on the board.
+ */
+export const notificationStatusSchema = v.picklist(['open', 'acted', 'dismissed']);
+/**
+ * How urgently a notification is rendered. A notification starts `normal` (the
+ * inbox's usual per-type color) and is escalated to `urgent` (red) by the periodic
+ * sweep once it has been waiting for a human longer than the workspace's
+ * `waitingEscalationMinutes` threshold. This is the run-timing signal that replaced
+ * the old hard "decision timeout" auto-fail: runs now wait indefinitely, and the
+ * notification colour — not a killed run — conveys that a human is overdue.
+ */
+export const notificationSeveritySchema = v.picklist(['normal', 'urgent']);
+/**
+ * Optional structured detail a notification carries for rendering its card —
+ * e.g. a `merge_review` carries the agent's assessment + the PR it concerns. Kept
+ * deliberately small and additive so new notification types can attach their own
+ * context without a schema migration.
+ */
+export const notificationPayloadSchema = v.object({
+    /** The `merger` agent's assessment, on a `merge_review`. */
+    assessment: v.optional(mergeAssessmentSchema),
+    /** Web URL of the PR the notification concerns, when one is known. */
+    prUrl: v.optional(v.string()),
+    /** The pipeline run that raised it, for display ("from the Full build run"). */
+    pipelineName: v.optional(v.string()),
+    /** Number of open findings, on a `requirement_review`. */
+    findingCount: v.optional(v.number()),
+    /** The `on-call` agent's assessment, on a `release_regression`. */
+    onCallAssessment: v.optional(onCallAssessmentSchema),
+    /** The monitors/SLOs that regressed, on a `release_regression`. */
+    releaseSignals: v.optional(v.array(releaseSignalSchema)),
+    /** Web URL of a proposed revert PR the human can open/merge, when known. */
+    revertUrl: v.optional(v.string()),
+    /**
+     * Internal user id (`usr_*`) of the member this notification is directed at — the
+     * task's responsible product person on a `requirement_review`. The inbox highlights
+     * it as "for you"; the notification stays workspace-visible to everyone.
+     */
+    targetUserId: v.optional(v.nullable(v.string())),
+});
+/** A human-actionable item surfaced on the board. */
+export const notificationSchema = v.object({
+    id: v.string(),
+    type: notificationTypeSchema,
+    status: notificationStatusSchema,
+    /**
+     * Render urgency (see {@link notificationSeveritySchema}). Absent ⇒ `normal`. Flipped
+     * to `urgent` by the escalation sweep once it has waited past the workspace threshold.
+     */
+    severity: v.optional(notificationSeveritySchema),
+    /** The block (task/frame) the notification is about; null for workspace-wide. */
+    blockId: v.nullable(v.string()),
+    /** The execution run that raised it, when applicable. */
+    executionId: v.nullable(v.string()),
+    /** Short headline shown on the card. */
+    title: v.string(),
+    /** Longer prose body / context. */
+    body: v.string(),
+    /** Optional structured detail for rendering (see {@link notificationPayloadSchema}). */
+    payload: v.optional(v.nullable(notificationPayloadSchema)),
+    createdAt: v.number(),
+    /** When it left `open` (acted/dismissed); null while open. */
+    resolvedAt: v.nullable(v.number()),
+});
+// ---- Request bodies -------------------------------------------------------
+/** How a human resolved a notification from its card. */
+export const resolveNotificationActionSchema = v.picklist(['act', 'dismiss']);
+//# sourceMappingURL=notifications.js.map

package/dist/notifications.js.map

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

package/dist/observability.d.ts

@@ -0,0 +1,271 @@
+import * as v from 'valibot';
+/** One proxied LLM call, with its full prompt/response and timing breakdown. */
+export declare const llmCallMetricSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly workspaceId: v.StringSchema<undefined>;
+    readonly executionId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly agentKind: v.StringSchema<undefined>;
+    readonly provider: v.StringSchema<undefined>;
+    readonly model: v.StringSchema<undefined>;
+    /** When the call completed (epoch ms). */
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly streaming: v.BooleanSchema<undefined>;
+    readonly messageCount: v.NumberSchema<undefined>;
+    /** Tools offered to the model (0 = the agent could not edit anything). */
+    readonly toolCount: v.NumberSchema<undefined>;
+    /** The `max_tokens` the request asked for (the output ceiling), or null. */
+    readonly requestMaxTokens: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly promptTokens: v.NumberSchema<undefined>;
+    /** Prompt tokens served from the provider's prompt cache (subset of promptTokens). */
+    readonly cachedPromptTokens: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+    readonly completionTokens: v.NumberSchema<undefined>;
+    readonly totalTokens: v.NumberSchema<undefined>;
+    /** Upstream finish reason (`stop` | `length` | `tool_calls` | `content_filter` | …). */
+    readonly finishReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Time waiting on the model (ms) — the actual execution. */
+    readonly upstreamMs: v.NumberSchema<undefined>;
+    /** Transport/proxy overhead (ms). */
+    readonly overheadMs: v.NumberSchema<undefined>;
+    /** End-to-end time the proxy spent on the call (ms). */
+    readonly totalMs: v.NumberSchema<undefined>;
+    readonly ok: v.BooleanSchema<undefined>;
+    readonly httpStatus: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly errorMessage: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The request messages serialised as JSON, stored as a DELTA — only the messages
+     * this call appended beyond `promptPrefixCount` (the full array when that is 0).
+     * The export rebuilds the full prompt from a chain's deltas.
+     */
+    readonly promptText: v.StringSchema<undefined>;
+    /**
+     * Leading messages elided from `promptText` (stored by an earlier call in the same
+     * conversation). 0 ⇒ `promptText` is the full array. Optional/defaulted so exports
+     * predating delta storage still parse.
+     */
+    readonly promptPrefixCount: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+    /** Hash of the call's full messages array (chain key for the next call's delta). */
+    readonly promptHash: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    /** The full assistant response text. */
+    readonly responseText: v.StringSchema<undefined>;
+    /**
+     * The model's reasoning / "thinking" trace on a separate channel, when emitted
+     * (empty for non-reasoning models). Optional/defaulted so exports predating reasoning
+     * capture still parse.
+     */
+    readonly reasoningText: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type LlmCallMetric = v.InferOutput<typeof llmCallMetricSchema>;
+/**
+ * The compact per-call summary pushed live over the workspace event stream (the
+ * `llmCall` {@link WorkspaceEvent}). It is {@link llmCallMetricSchema} WITHOUT the
+ * heavy text bodies (`promptText`/`responseText`) and the delta bookkeeping
+ * (`promptPrefixCount`/`promptHash`), so a stalled-driver "is the agent still
+ * calling the model?" view updates in real time without shipping prompt bytes over
+ * the socket. The drill-down panel lazy-loads the full bodies for an expanded row
+ * from `GET /executions/:id/llm-metrics` (the persisted store), keyed by the shared
+ * call `id`.
+ */
+export declare const llmCallActivitySchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly workspaceId: v.StringSchema<undefined>;
+    readonly executionId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly agentKind: v.StringSchema<undefined>;
+    readonly provider: v.StringSchema<undefined>;
+    readonly model: v.StringSchema<undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly streaming: v.BooleanSchema<undefined>;
+    readonly messageCount: v.NumberSchema<undefined>;
+    readonly toolCount: v.NumberSchema<undefined>;
+    readonly requestMaxTokens: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly promptTokens: v.NumberSchema<undefined>;
+    readonly cachedPromptTokens: v.NumberSchema<undefined>;
+    readonly completionTokens: v.NumberSchema<undefined>;
+    readonly totalTokens: v.NumberSchema<undefined>;
+    readonly finishReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly upstreamMs: v.NumberSchema<undefined>;
+    readonly overheadMs: v.NumberSchema<undefined>;
+    readonly totalMs: v.NumberSchema<undefined>;
+    readonly ok: v.BooleanSchema<undefined>;
+    readonly httpStatus: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly errorMessage: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type LlmCallActivity = v.InferOutput<typeof llmCallActivitySchema>;
+/** Response of `GET /workspaces/:ws/executions/:id/llm-metrics` (drill-down panel). */
+export declare const llmMetricsResponseSchema: v.ObjectSchema<{
+    readonly executionId: v.StringSchema<undefined>;
+    readonly calls: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly workspaceId: v.StringSchema<undefined>;
+        readonly executionId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly agentKind: v.StringSchema<undefined>;
+        readonly provider: v.StringSchema<undefined>;
+        readonly model: v.StringSchema<undefined>;
+        /** When the call completed (epoch ms). */
+        readonly createdAt: v.NumberSchema<undefined>;
+        readonly streaming: v.BooleanSchema<undefined>;
+        readonly messageCount: v.NumberSchema<undefined>;
+        /** Tools offered to the model (0 = the agent could not edit anything). */
+        readonly toolCount: v.NumberSchema<undefined>;
+        /** The `max_tokens` the request asked for (the output ceiling), or null. */
+        readonly requestMaxTokens: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly promptTokens: v.NumberSchema<undefined>;
+        /** Prompt tokens served from the provider's prompt cache (subset of promptTokens). */
+        readonly cachedPromptTokens: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+        readonly completionTokens: v.NumberSchema<undefined>;
+        readonly totalTokens: v.NumberSchema<undefined>;
+        /** Upstream finish reason (`stop` | `length` | `tool_calls` | `content_filter` | …). */
+        readonly finishReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Time waiting on the model (ms) — the actual execution. */
+        readonly upstreamMs: v.NumberSchema<undefined>;
+        /** Transport/proxy overhead (ms). */
+        readonly overheadMs: v.NumberSchema<undefined>;
+        /** End-to-end time the proxy spent on the call (ms). */
+        readonly totalMs: v.NumberSchema<undefined>;
+        readonly ok: v.BooleanSchema<undefined>;
+        readonly httpStatus: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly errorMessage: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The request messages serialised as JSON, stored as a DELTA — only the messages
+         * this call appended beyond `promptPrefixCount` (the full array when that is 0).
+         * The export rebuilds the full prompt from a chain's deltas.
+         */
+        readonly promptText: v.StringSchema<undefined>;
+        /**
+         * Leading messages elided from `promptText` (stored by an earlier call in the same
+         * conversation). 0 ⇒ `promptText` is the full array. Optional/defaulted so exports
+         * predating delta storage still parse.
+         */
+        readonly promptPrefixCount: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+        /** Hash of the call's full messages array (chain key for the next call's delta). */
+        readonly promptHash: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        /** The full assistant response text. */
+        readonly responseText: v.StringSchema<undefined>;
+        /**
+         * The model's reasoning / "thinking" trace on a separate channel, when emitted
+         * (empty for non-reasoning models). Optional/defaulted so exports predating reasoning
+         * capture still parse.
+         */
+        readonly reasoningText: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    }, undefined>, undefined>;
+}, undefined>;
+export type LlmMetricsResponse = v.InferOutput<typeof llmMetricsResponseSchema>;
+/**
+ * A single per-agent-kind insight in the LLM-friendly export: the same rollup the
+ * board step shows, plus derived ratios so an analysing model needs no arithmetic.
+ */
+export declare const llmExportInsightSchema: v.ObjectSchema<{
+    readonly agentKind: v.StringSchema<undefined>;
+    readonly calls: v.NumberSchema<undefined>;
+    readonly promptTokens: v.NumberSchema<undefined>;
+    readonly completionTokens: v.NumberSchema<undefined>;
+    readonly peakCompletionTokens: v.NumberSchema<undefined>;
+    readonly maxOutputTokens: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** peakCompletionTokens / maxOutputTokens, 0..1; null when the ceiling is unknown. */
+    readonly outputHeadroomRatio: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly truncatedCalls: v.NumberSchema<undefined>;
+    readonly upstreamMs: v.NumberSchema<undefined>;
+    readonly overheadMs: v.NumberSchema<undefined>;
+    /** overheadMs / (upstreamMs + overheadMs), 0..1; the share spent in transport. */
+    readonly transportOverheadRatio: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    readonly errors: v.NumberSchema<undefined>;
+    readonly warnings: v.NumberSchema<undefined>;
+}, undefined>;
+export type LlmExportInsight = v.InferOutput<typeof llmExportInsightSchema>;
+/**
+ * LLM-friendly export of a run's model activity: a self-describing, structured JSON
+ * bundle (totals + per-agent insights + every call) intended to be handed straight
+ * to a model for analysis ("why did this run truncate / spend / stall?"). Field
+ * names and derived ratios are explicit so no external context is needed.
+ */
+export declare const llmMetricsExportSchema: v.ObjectSchema<{
+    /** Schema marker so a consuming model knows the shape. */
+    readonly kind: v.LiteralSchema<"cat-factory.llm-metrics-export", undefined>;
+    readonly version: v.LiteralSchema<1, undefined>;
+    readonly executionId: v.StringSchema<undefined>;
+    readonly generatedAt: v.NumberSchema<undefined>;
+    readonly totals: v.ObjectSchema<{
+        readonly calls: v.NumberSchema<undefined>;
+        readonly promptTokens: v.NumberSchema<undefined>;
+        readonly completionTokens: v.NumberSchema<undefined>;
+        readonly upstreamMs: v.NumberSchema<undefined>;
+        readonly overheadMs: v.NumberSchema<undefined>;
+        /** Share of total latency spent in transport/proxy (0..1), or null with no timing. */
+        readonly transportOverheadRatio: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly errors: v.NumberSchema<undefined>;
+        readonly warnings: v.NumberSchema<undefined>;
+        readonly truncatedCalls: v.NumberSchema<undefined>;
+    }, undefined>;
+    readonly insights: v.ArraySchema<v.ObjectSchema<{
+        readonly agentKind: v.StringSchema<undefined>;
+        readonly calls: v.NumberSchema<undefined>;
+        readonly promptTokens: v.NumberSchema<undefined>;
+        readonly completionTokens: v.NumberSchema<undefined>;
+        readonly peakCompletionTokens: v.NumberSchema<undefined>;
+        readonly maxOutputTokens: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        /** peakCompletionTokens / maxOutputTokens, 0..1; null when the ceiling is unknown. */
+        readonly outputHeadroomRatio: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly truncatedCalls: v.NumberSchema<undefined>;
+        readonly upstreamMs: v.NumberSchema<undefined>;
+        readonly overheadMs: v.NumberSchema<undefined>;
+        /** overheadMs / (upstreamMs + overheadMs), 0..1; the share spent in transport. */
+        readonly transportOverheadRatio: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly errors: v.NumberSchema<undefined>;
+        readonly warnings: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly calls: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly workspaceId: v.StringSchema<undefined>;
+        readonly executionId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly agentKind: v.StringSchema<undefined>;
+        readonly provider: v.StringSchema<undefined>;
+        readonly model: v.StringSchema<undefined>;
+        /** When the call completed (epoch ms). */
+        readonly createdAt: v.NumberSchema<undefined>;
+        readonly streaming: v.BooleanSchema<undefined>;
+        readonly messageCount: v.NumberSchema<undefined>;
+        /** Tools offered to the model (0 = the agent could not edit anything). */
+        readonly toolCount: v.NumberSchema<undefined>;
+        /** The `max_tokens` the request asked for (the output ceiling), or null. */
+        readonly requestMaxTokens: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly promptTokens: v.NumberSchema<undefined>;
+        /** Prompt tokens served from the provider's prompt cache (subset of promptTokens). */
+        readonly cachedPromptTokens: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+        readonly completionTokens: v.NumberSchema<undefined>;
+        readonly totalTokens: v.NumberSchema<undefined>;
+        /** Upstream finish reason (`stop` | `length` | `tool_calls` | `content_filter` | …). */
+        readonly finishReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Time waiting on the model (ms) — the actual execution. */
+        readonly upstreamMs: v.NumberSchema<undefined>;
+        /** Transport/proxy overhead (ms). */
+        readonly overheadMs: v.NumberSchema<undefined>;
+        /** End-to-end time the proxy spent on the call (ms). */
+        readonly totalMs: v.NumberSchema<undefined>;
+        readonly ok: v.BooleanSchema<undefined>;
+        readonly httpStatus: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        readonly errorMessage: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The request messages serialised as JSON, stored as a DELTA — only the messages
+         * this call appended beyond `promptPrefixCount` (the full array when that is 0).
+         * The export rebuilds the full prompt from a chain's deltas.
+         */
+        readonly promptText: v.StringSchema<undefined>;
+        /**
+         * Leading messages elided from `promptText` (stored by an earlier call in the same
+         * conversation). 0 ⇒ `promptText` is the full array. Optional/defaulted so exports
+         * predating delta storage still parse.
+         */
+        readonly promptPrefixCount: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+        /** Hash of the call's full messages array (chain key for the next call's delta). */
+        readonly promptHash: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        /** The full assistant response text. */
+        readonly responseText: v.StringSchema<undefined>;
+        /**
+         * The model's reasoning / "thinking" trace on a separate channel, when emitted
+         * (empty for non-reasoning models). Optional/defaulted so exports predating reasoning
+         * capture still parse.
+         */
+        readonly reasoningText: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    }, undefined>, undefined>;
+}, undefined>;
+export type LlmMetricsExport = v.InferOutput<typeof llmMetricsExportSchema>;
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAQ5B,gFAAgF;AAChF,eAAO,MAAM,mBAAmB;;;;;;;IAO9B,0CAA0C;;;;IAI1C,0EAA0E;;IAE1E,4EAA4E;;;IAG5E,sFAAsF;;;;IAItF,wFAAwF;;IAExF,6DAA6D;;IAE7D,qCAAqC;;IAErC,wDAAwD;;;;;IAKxD;;;;OAIG;;IAEH;;;;OAIG;;IAEH,oFAAoF;;IAEpF,wCAAwC;;IAExC;;;;OAIG;;aAEH,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;aA0BhC,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,uFAAuF;AACvF,eAAO,MAAM,wBAAwB;;;;;;;;;QAzFnC,0CAA0C;;;;QAI1C,0EAA0E;;QAE1E,4EAA4E;;;QAG5E,sFAAsF;;;;QAItF,wFAAwF;;QAExF,6DAA6D;;QAE7D,qCAAqC;;QAErC,wDAAwD;;;;;QAKxD;;;;WAIG;;QAEH;;;;WAIG;;QAEH,oFAAoF;;QAEpF,wCAAwC;;QAExC;;;;WAIG;;;aAgDH,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;IAOjC,sFAAsF;;;;;IAKtF,kFAAkF;;;;aAIlF,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IACjC,0DAA0D;;;;;;;;;;;QAWxD,sFAAsF;;;;;;;;;;;;;QA9BxF,sFAAsF;;;;;QAKtF,kFAAkF;;;;;;;;;;;;QA/GlF,0CAA0C;;;;QAI1C,0EAA0E;;QAE1E,4EAA4E;;;QAG5E,sFAAsF;;;;QAItF,wFAAwF;;QAExF,6DAA6D;;QAE7D,qCAAqC;;QAErC,wDAAwD;;;;;QAKxD;;;;WAIG;;QAEH;;;;WAIG;;QAEH,oFAAoF;;QAEpF,wCAAwC;;QAExC;;;;WAIG;;;aAoGH,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA"}

package/dist/observability.js

@@ -0,0 +1,152 @@
+import * as v from 'valibot';
+// Wire contracts for LLM observability — the per-call detail behind the board's
+// step rollups (see `stepMetricsSchema` in entities). The proxy records one of
+// these per model call (full prompt + response, output-limit headroom, the
+// transport-vs-execution latency split); the drill-down panel lists them and the
+// export endpoint returns an LLM-analysable bundle.
+/** One proxied LLM call, with its full prompt/response and timing breakdown. */
+export const llmCallMetricSchema = v.object({
+    id: v.string(),
+    workspaceId: v.string(),
+    executionId: v.nullable(v.string()),
+    agentKind: v.string(),
+    provider: v.string(),
+    model: v.string(),
+    /** When the call completed (epoch ms). */
+    createdAt: v.number(),
+    streaming: v.boolean(),
+    messageCount: v.number(),
+    /** Tools offered to the model (0 = the agent could not edit anything). */
+    toolCount: v.number(),
+    /** The `max_tokens` the request asked for (the output ceiling), or null. */
+    requestMaxTokens: v.nullable(v.number()),
+    promptTokens: v.number(),
+    /** Prompt tokens served from the provider's prompt cache (subset of promptTokens). */
+    cachedPromptTokens: v.optional(v.number(), 0),
+    completionTokens: v.number(),
+    totalTokens: v.number(),
+    /** Upstream finish reason (`stop` | `length` | `tool_calls` | `content_filter` | …). */
+    finishReason: v.nullable(v.string()),
+    /** Time waiting on the model (ms) — the actual execution. */
+    upstreamMs: v.number(),
+    /** Transport/proxy overhead (ms). */
+    overheadMs: v.number(),
+    /** End-to-end time the proxy spent on the call (ms). */
+    totalMs: v.number(),
+    ok: v.boolean(),
+    httpStatus: v.nullable(v.number()),
+    errorMessage: v.nullable(v.string()),
+    /**
+     * The request messages serialised as JSON, stored as a DELTA — only the messages
+     * this call appended beyond `promptPrefixCount` (the full array when that is 0).
+     * The export rebuilds the full prompt from a chain's deltas.
+     */
+    promptText: v.string(),
+    /**
+     * Leading messages elided from `promptText` (stored by an earlier call in the same
+     * conversation). 0 ⇒ `promptText` is the full array. Optional/defaulted so exports
+     * predating delta storage still parse.
+     */
+    promptPrefixCount: v.optional(v.number(), 0),
+    /** Hash of the call's full messages array (chain key for the next call's delta). */
+    promptHash: v.optional(v.string(), ''),
+    /** The full assistant response text. */
+    responseText: v.string(),
+    /**
+     * The model's reasoning / "thinking" trace on a separate channel, when emitted
+     * (empty for non-reasoning models). Optional/defaulted so exports predating reasoning
+     * capture still parse.
+     */
+    reasoningText: v.optional(v.string(), ''),
+});
+/**
+ * The compact per-call summary pushed live over the workspace event stream (the
+ * `llmCall` {@link WorkspaceEvent}). It is {@link llmCallMetricSchema} WITHOUT the
+ * heavy text bodies (`promptText`/`responseText`) and the delta bookkeeping
+ * (`promptPrefixCount`/`promptHash`), so a stalled-driver "is the agent still
+ * calling the model?" view updates in real time without shipping prompt bytes over
+ * the socket. The drill-down panel lazy-loads the full bodies for an expanded row
+ * from `GET /executions/:id/llm-metrics` (the persisted store), keyed by the shared
+ * call `id`.
+ */
+export const llmCallActivitySchema = v.object({
+    id: v.string(),
+    workspaceId: v.string(),
+    executionId: v.nullable(v.string()),
+    agentKind: v.string(),
+    provider: v.string(),
+    model: v.string(),
+    createdAt: v.number(),
+    streaming: v.boolean(),
+    messageCount: v.number(),
+    toolCount: v.number(),
+    requestMaxTokens: v.nullable(v.number()),
+    promptTokens: v.number(),
+    // Always supplied by the proxy emit (unlike the persisted metric, which defaults it
+    // for rows that predate delta storage), so it is required here — matching the SPA's
+    // `LlmCallActivity` type, which derives it as a required field from `LlmCallMetric`.
+    cachedPromptTokens: v.number(),
+    completionTokens: v.number(),
+    totalTokens: v.number(),
+    finishReason: v.nullable(v.string()),
+    upstreamMs: v.number(),
+    overheadMs: v.number(),
+    totalMs: v.number(),
+    ok: v.boolean(),
+    httpStatus: v.nullable(v.number()),
+    errorMessage: v.nullable(v.string()),
+});
+/** Response of `GET /workspaces/:ws/executions/:id/llm-metrics` (drill-down panel). */
+export const llmMetricsResponseSchema = v.object({
+    executionId: v.string(),
+    calls: v.array(llmCallMetricSchema),
+});
+/**
+ * A single per-agent-kind insight in the LLM-friendly export: the same rollup the
+ * board step shows, plus derived ratios so an analysing model needs no arithmetic.
+ */
+export const llmExportInsightSchema = v.object({
+    agentKind: v.string(),
+    calls: v.number(),
+    promptTokens: v.number(),
+    completionTokens: v.number(),
+    peakCompletionTokens: v.number(),
+    maxOutputTokens: v.nullable(v.number()),
+    /** peakCompletionTokens / maxOutputTokens, 0..1; null when the ceiling is unknown. */
+    outputHeadroomRatio: v.nullable(v.number()),
+    truncatedCalls: v.number(),
+    upstreamMs: v.number(),
+    overheadMs: v.number(),
+    /** overheadMs / (upstreamMs + overheadMs), 0..1; the share spent in transport. */
+    transportOverheadRatio: v.nullable(v.number()),
+    errors: v.number(),
+    warnings: v.number(),
+});
+/**
+ * LLM-friendly export of a run's model activity: a self-describing, structured JSON
+ * bundle (totals + per-agent insights + every call) intended to be handed straight
+ * to a model for analysis ("why did this run truncate / spend / stall?"). Field
+ * names and derived ratios are explicit so no external context is needed.
+ */
+export const llmMetricsExportSchema = v.object({
+    /** Schema marker so a consuming model knows the shape. */
+    kind: v.literal('cat-factory.llm-metrics-export'),
+    version: v.literal(1),
+    executionId: v.string(),
+    generatedAt: v.number(),
+    totals: v.object({
+        calls: v.number(),
+        promptTokens: v.number(),
+        completionTokens: v.number(),
+        upstreamMs: v.number(),
+        overheadMs: v.number(),
+        /** Share of total latency spent in transport/proxy (0..1), or null with no timing. */
+        transportOverheadRatio: v.nullable(v.number()),
+        errors: v.number(),
+        warnings: v.number(),
+        truncatedCalls: v.number(),
+    }),
+    insights: v.array(llmExportInsightSchema),
+    calls: v.array(llmCallMetricSchema),
+});
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

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

package/dist/personal-subscriptions.d.ts

@@ -0,0 +1,66 @@
+import * as v from 'valibot';
+/**
+ * The personal password that gates the second encryption layer (8–256 chars). Restricted
+ * to printable ASCII so the same value can ride **raw** in the `X-Personal-Password`
+ * request header (see below) when unlocking a run — HTTP header values must be Latin-1, so
+ * a non-ASCII password could not be sent without encoding. Never stored server-side.
+ */
+export declare const personalPasswordSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 8, undefined>, v.MaxLengthAction<string, 256, undefined>, v.RegexAction<string, "Password must use printable ASCII characters (no tabs/newlines).">]>;
+/**
+ * HTTP header carrying the personal password to unlock a run's individual-usage
+ * credential(s). It is an AMBIENT credential — like the bearer token, the client attaches
+ * it on the gated calls (start / retry / resolve / approve / request-changes) rather than
+ * baking it into each request body — so it never appears in a wire-contract payload. The
+ * server reads it, unlocks, and mints/re-mints the per-run activation; absent + required ⇒
+ * `428 credential_required`.
+ */
+export declare const PERSONAL_PASSWORD_HEADER = "X-Personal-Password";
+/** Store (or replace) the signed-in user's personal subscription for a vendor. */
+export declare const storePersonalSubscriptionSchema: v.ObjectSchema<{
+    readonly vendor: v.PicklistSchema<["claude", "codex", "glm", "kimi", "deepseek"], undefined>;
+    readonly label: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
+    /** The raw secret (write-only): the `claude setup-token` OAuth token for `claude`. */
+    readonly token: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>]>;
+    /** Personal password that gates the second encryption layer. Never stored. */
+    readonly password: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 8, undefined>, v.MaxLengthAction<string, 256, undefined>, v.RegexAction<string, "Password must use printable ASCII characters (no tabs/newlines).">]>;
+    /**
+     * Epoch ms the subscription itself expires (so we can warn well in advance and
+     * block runs once lapsed). Optional — omit if the plan has no fixed end date.
+     */
+    readonly expiresAt: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type StorePersonalSubscriptionInput = v.InferOutput<typeof storePersonalSubscriptionSchema>;
+/** Read-only status of one personal subscription — metadata only, never the secret. */
+export declare const personalSubscriptionStatusSchema: v.ObjectSchema<{
+    readonly vendor: v.PicklistSchema<["claude", "codex", "glm", "kimi", "deepseek"], undefined>;
+    readonly label: v.StringSchema<undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+    readonly lastUsedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Subscription's own expiry (null = no fixed end date). */
+    readonly expiresAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Whole days until `expiresAt` (negative once lapsed; null when no expiry). */
+    readonly expiresInDays: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Whether the subscription's expiry has already passed. */
+    readonly expired: v.BooleanSchema<undefined>;
+    /** Whether renewal should be surfaced now (expiry within the warning window). */
+    readonly renewSoon: v.BooleanSchema<undefined>;
+}, undefined>;
+export type PersonalSubscriptionStatus = v.InferOutput<typeof personalSubscriptionStatusSchema>;
+export declare const personalSubscriptionListSchema: v.ArraySchema<v.ObjectSchema<{
+    readonly vendor: v.PicklistSchema<["claude", "codex", "glm", "kimi", "deepseek"], undefined>;
+    readonly label: v.StringSchema<undefined>;
+    readonly createdAt: v.NumberSchema<undefined>;
+    readonly updatedAt: v.NumberSchema<undefined>;
+    readonly lastUsedAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Subscription's own expiry (null = no fixed end date). */
+    readonly expiresAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Whole days until `expiresAt` (negative once lapsed; null when no expiry). */
+    readonly expiresInDays: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Whether the subscription's expiry has already passed. */
+    readonly expired: v.BooleanSchema<undefined>;
+    /** Whether renewal should be surfaced now (expiry within the warning window). */
+    readonly renewSoon: v.BooleanSchema<undefined>;
+}, undefined>, undefined>;
+export type PersonalSubscriptionList = v.InferOutput<typeof personalSubscriptionListSchema>;
+//# sourceMappingURL=personal-subscriptions.d.ts.map

package/dist/personal-subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personal-subscriptions.d.ts","sourceRoot":"","sources":["../src/personal-subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAwB5B;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,uOAKlC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAE7D,kFAAkF;AAClF,eAAO,MAAM,+BAA+B;;;IAG1C,sFAAsF;;IAEtF,8EAA8E;;IAE9E;;;OAGG;;aAEH,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,+BAA+B,CAAC,CAAA;AAElG,uFAAuF;AACvF,eAAO,MAAM,gCAAgC;;;;;;IAM3C,4DAA4D;;IAE5D,gFAAgF;;IAEhF,4DAA4D;;IAE5D,iFAAiF;;aAEjF,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,gCAAgC,CAAC,CAAA;AAE/F,eAAO,MAAM,8BAA8B;;;;;;IAXzC,4DAA4D;;IAE5D,gFAAgF;;IAEhF,4DAA4D;;IAE5D,iFAAiF;;yBAKI,CAAA;AACvF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,8BAA8B,CAAC,CAAA"}