@cat-factory/kernel 0.243.0 → 0.244.0

package/dist/domain/agent-capabilities.d.ts

@@ -129,6 +129,85 @@ export interface McpSecretRef {
      */
     usage?: string;
 }
+/**
+ * How a REMOTE (`http`) tool server's access token is obtained, when the server authenticates with
+ * OAuth 2.1 rather than a static credential.
+ *
+ * This is the declaration half only: the deployment states which OAuth client it is and what it
+ * wants, and everything mutable (the tokens, their expiry, the refresh) lives per WORKSPACE in the
+ * sealed grant store. That split is deliberate and mirrors {@link McpSecretRef}: a static
+ * credential's declaration is a key NAME and its value is per-tenant, and an OAuth credential's
+ * declaration is a client and its GRANT is per-tenant. A deployment therefore registers a vendor's
+ * remote server once, and each board authorises its own account against it.
+ *
+ * The two grants cover the two shapes a remote server comes in, and they differ in whether a HUMAN
+ * is involved at all, which is why they are one field rather than two definitions:
+ *
+ * - `authorization_code` — the vendor case (Linear, Atlassian, Figma). Someone with
+ *   `secrets.manage` presses Connect, authorises in the vendor's own UI, and the workspace holds
+ *   the resulting refresh token. PKCE is always used, so a PUBLIC client (no
+ *   {@link McpOAuthConfig.clientSecretKey}) is a supported and common shape.
+ * - `client_credentials` — a machine grant against an internal or partner server. No browser, no
+ *   grant UI, nothing per-tenant except the client secret: the token is minted on demand and
+ *   cached in the same store. This is what makes an OAuth-protected INTERNAL server reachable on a
+ *   deployment that has no one to press a button (a cron-driven install, a CI environment).
+ */
+export interface McpOAuthConfig {
+    grant: 'authorization_code' | 'client_credentials';
+    /**
+     * The OAuth client id this deployment registered with the server's authorization server.
+     *
+     * Static on purpose: dynamic client registration (RFC 7591) is not performed, because a
+     * client registered at runtime is deployment state with no home in a composition-root
+     * registration and no operator-visible identity at the vendor. Register the client once in the
+     * vendor's console and name it here.
+     */
+    clientId: string;
+    /**
+     * The LOOKUP key for the client SECRET, resolved through the very same `ToolSecretResolver`
+     * chain a {@link McpSecretRef} uses — so a workspace can bring its own OAuth client through the
+     * capability-credential checklist, and a single-tenant deployment can set an environment
+     * variable, with no second credential mechanism to learn.
+     *
+     * Omitted ⇒ a PUBLIC client: the token requests carry the client id and PKCE and no secret,
+     * which is what most remote MCP servers expect. Held to the same reserved-key floor as every
+     * other capability credential (`isReservedPlatformEnvKey`), for the same reason: a definition
+     * names both the key it wants and the endpoint that key is sent to.
+     */
+    clientSecretKey?: string;
+    /**
+     * The authorization endpoint. Omitted ⇒ DISCOVERED from the server url (RFC 9728 protected
+     * resource metadata, then RFC 8414 authorization-server metadata), which is what the MCP
+     * authorization spec prescribes and what makes a vendor server connectable without an operator
+     * hunting endpoint URLs out of a changelog.
+     *
+     * Declared, it WINS over discovery: a deployment that pins its endpoints is stating that it does
+     * not want a third party's metadata document deciding where its tokens are sent.
+     */
+    authorizationUrl?: string;
+    /** The token endpoint. Omitted ⇒ discovered, as {@link McpOAuthConfig.authorizationUrl}. */
+    tokenUrl?: string;
+    /** Scopes requested at authorization. Omitted ⇒ whatever the server grants by default. */
+    scopes?: string[];
+    /**
+     * The RFC 8707 `resource` indicator sent with the authorization and token requests, which the
+     * MCP authorization spec requires so a token minted for one MCP server cannot be replayed
+     * against another behind the same authorization server. Omitted ⇒ the server's own url, which is
+     * the right answer whenever the server is its own resource.
+     */
+    resource?: string;
+    /**
+     * The request header the access token rides, and its template. Default `Authorization` /
+     * `Bearer {value}`, which is what every OAuth-protected MCP server expects; the override exists
+     * for a gateway that reads the token somewhere else, exactly as {@link McpSecretRef.header} does.
+     */
+    header?: string;
+    headerTemplate?: string;
+}
+/** The header an OAuth access token rides when the declaration does not say otherwise. */
+export declare const MCP_OAUTH_DEFAULT_HEADER = "Authorization";
+/** The template that header's value uses when the declaration does not say otherwise. */
+export declare const MCP_OAUTH_DEFAULT_HEADER_TEMPLATE = "Bearer {value}";
 /**
  * A tool server (MCP) an agent kind can be given. Registered on the `AgentKindRegistry` by id and
  * referenced from any number of kinds, or declared inline on a single kind.
@@ -178,6 +257,17 @@ export interface McpServerDefinition {
     harnesses?: HarnessKind[];
     /** Credentials the server needs, by name. Resolved at dispatch; never rendered into a prompt. */
     secretKeys?: McpSecretRef[];
+    /**
+     * OAuth, for a remote server that authenticates with a granted token rather than a static one.
+     * `http` transport only — a `stdio` server is a child process with no request to authorise, and
+     * boot validation refuses the combination rather than letting it read as configured.
+     *
+     * Composes with {@link McpServerDefinition.secretKeys} rather than replacing them: a server may
+     * want a granted token AND a static tenant header, and each rides the channel its own
+     * declaration named. The access token's header is the one place they can collide, which boot
+     * validation names.
+     */
+    oauth?: McpOAuthConfig;
 }
 /**
  * The prompt-facing projection of a tool server that was actually wired for this dispatch. Carried
@@ -213,8 +303,17 @@ export interface UnavailableToolServer {
      *   `harnesses` list, not a different harness.
      * - `over_budget` says the server was declared, servable and credentialed, and lost to a cap.
      *   Nothing about the server is wrong; the KIND declares more than a job body carries.
+     * - `oauth_not_connected` is kept apart from `missing_secret` because the fix is not a value to
+     *   type: nobody has AUTHORISED this workspace against the server yet, and the remedy is a
+     *   person pressing Connect and signing in at the vendor. An operator who read "credential not
+     *   configured" would go looking for a variable that does not exist.
+     * - `oauth_token_failed` says a grant (or a client-credentials client) IS on file and the
+     *   platform could not turn it into an access token: a revoked or expired refresh token, an
+     *   authorization server that would not answer, a rotated client secret. Apart from
+     *   `oauth_not_connected` because "never connected" and "the connection stopped working" send an
+     *   operator to different places, and only the second is ever transient.
      */
-    reason: 'harness_unsupported' | 'transport_unsupported' | 'missing_secret' | 'reserved_secret' | 'over_budget';
+    reason: 'harness_unsupported' | 'transport_unsupported' | 'missing_secret' | 'reserved_secret' | 'oauth_not_connected' | 'oauth_token_failed' | 'over_budget';
 }
 /**
  * Which MCP transports each harness's CLI can actually reach. An exhaustive `Record` over

package/dist/domain/agent-capabilities.d.ts.map

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

package/dist/domain/agent-capabilities.js

@@ -1,3 +1,7 @@
+/** The header an OAuth access token rides when the declaration does not say otherwise. */
+export const MCP_OAUTH_DEFAULT_HEADER = 'Authorization';
+/** The template that header's value uses when the declaration does not say otherwise. */
+export const MCP_OAUTH_DEFAULT_HEADER_TEMPLATE = 'Bearer {value}';
 /**
  * Which MCP transports each harness's CLI can actually reach. An exhaustive `Record` over
  * `HarnessKind`, so a new harness cannot be added without stating its answer: an omitted entry

package/dist/domain/agent-capabilities.js.map

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

package/dist/domain/audit-log.d.ts

@@ -0,0 +1,95 @@
+import type { AuditEventDetails } from '@cat-factory/contracts';
+import type { AuditActor, AuditEventRecord, AuditEventView } from '../ports/audit.js';
+/** Default page size when a caller names none. */
+export declare const AUDIT_PAGE_LIMIT_DEFAULT = 50;
+/** Hard ceiling, so a caller-supplied `limit` can't ask for the whole table. */
+export declare const AUDIT_PAGE_LIMIT_MAX = 200;
+/** The (at, id) pair a cursor points just past. */
+export interface AuditCursor {
+    at: number;
+    id: string;
+}
+/** Clamp a caller's requested page size into the allowed range. */
+export declare function auditPageLimit(limit?: number): number;
+/**
+ * Encode the last row of a page as the next page's cursor. `at` and `id` TOGETHER, because `at`
+ * alone is not unique: two events recorded in the same millisecond would straddle the boundary
+ * and be served twice or skipped.
+ */
+export declare function encodeAuditCursor(row: AuditCursor): string;
+/**
+ * Decode a cursor, or null when there is none / it is unreadable.
+ *
+ * A malformed cursor reads as "start from the newest" rather than throwing: cursors are opaque
+ * and round-trip through a URL, so a truncated one is a client bug that should cost a page
+ * position, not a 500. It cannot widen a read either way, because the account scope is a
+ * separate argument that no cursor carries.
+ */
+export declare function decodeAuditCursor(cursor?: string | null): AuditCursor | null;
+/**
+ * The persisted actor columns as a discriminated {@link AuditActor}.
+ *
+ * Anything that is not a complete `user` or `apiKey` principal reads as `system`: that is the
+ * honest rendering of "no principal is recorded on this row", and it never invents a user id,
+ * which is the single outcome that would misattribute an action to a person.
+ */
+export declare function rowToAuditActor(row: {
+    actor_kind: string;
+    actor_user_id: string | null;
+    actor_api_key_id: string | null;
+}): AuditActor;
+/** The two nullable actor columns for a principal, for an INSERT. */
+export declare function auditActorColumns(actor: AuditActor): {
+    actor_kind: AuditActor['kind'];
+    actor_user_id: string | null;
+    actor_api_key_id: string | null;
+};
+/** An event's `details` as the single TEXT column both stores keep it in. */
+export declare function encodeAuditDetails(details: AuditEventDetails): string;
+/**
+ * The `details` column as fields again, or an EMPTY set when the blob is unreadable.
+ *
+ * Empty rather than a throw, deliberately, and it is the one place in this module where the
+ * lenient branch is the strict choice: who acted, on what, and when are the irreplaceable parts
+ * of an audit row, and losing the whole row (or the whole PAGE) because one event's values no
+ * longer parse is the single failure a viewer must not have. The values are what the viewer
+ * interpolates, so their absence shows up as a row that states less, never as a row that is not
+ * there. A non-object blob (`"null"`, `"3"`, `"[]"`) counts as unreadable for the same reason it
+ * would break interpolation.
+ */
+export declare function decodeAuditDetails(raw: string | null): AuditEventDetails;
+/** The snake_case columns both stores keep an audit event in, as WRITTEN. */
+export interface AuditEventColumns {
+    id: string;
+    account_id: string;
+    workspace_id: string | null;
+    actor_kind: string;
+    actor_user_id: string | null;
+    actor_api_key_id: string | null;
+    action: string;
+    target_type: string;
+    target_id: string;
+    details: string;
+    at: number;
+}
+/**
+ * The same row as READ BACK. Identical but for `details`, which the reader tolerates as NULL
+ * even though both schemas declare it NOT NULL: a driver, a hand-run statement or a future
+ * lineage can still hand one over, and the row is worth more than its values (see
+ * {@link decodeAuditDetails}). The WRITE type admits no null, so nothing here can produce one.
+ */
+export interface AuditEventRow extends Omit<AuditEventColumns, 'details'> {
+    details: string | null;
+}
+/** Every column of an audit event, for an INSERT. */
+export declare function auditEventColumns(event: AuditEventRecord): AuditEventColumns;
+/**
+ * A persisted row as the event a viewer renders.
+ *
+ * Shaped structurally (a plain snake_case object) rather than against either driver's row type,
+ * so both facades map through this one function. `action` and `target_type` go through the
+ * contracts readers, so a member retired since the row was written arrives NAMED as retired
+ * rather than dropped or guessed at.
+ */
+export declare function rowToAuditEventView(row: AuditEventRow): AuditEventView;
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/domain/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../src/domain/audit-log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE/D,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAiBrF,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,MAAM,CAAA;AAEvC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;CACX;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAO5E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC,GAAG,UAAU,CAQb;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG;IACpD,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAA;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC,CAMA;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,iBAAiB,CAWxE;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC;IACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAY5E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CAYtE"}

package/dist/domain/audit-log.js

@@ -0,0 +1,142 @@
+import { readAuditAction, readAuditTargetType } from '@cat-factory/contracts';
+// ---------------------------------------------------------------------------
+// The audit log's pure rules: how a page is bounded, how a cursor names the row it continues
+// from, and how a persisted row reads back as an event.
+//
+// In kernel rather than in either facade because BOTH implement `AuditEventRepository` and must
+// agree byte-for-byte about all of it. A cursor is opaque to its caller, which is exactly why a
+// per-facade copy of its encoding is dangerous: nothing about a mismatched cursor looks wrong at
+// the boundary, it just silently starts a page somewhere else. The row mapping is here for a
+// related reason: it holds three decisions a reader could get subtly wrong on its own (which
+// actor column belongs to which kind, what a retired vocabulary member renders as, what an
+// unreadable `details` blob does), and a facade that re-derived any of them would diverge in a
+// way only that runtime's users would ever see. The conformance suite drives both repositories
+// through the same assertions, so a divergence would have to be a divergence in code they share.
+// ---------------------------------------------------------------------------
+/** Default page size when a caller names none. */
+export const AUDIT_PAGE_LIMIT_DEFAULT = 50;
+/** Hard ceiling, so a caller-supplied `limit` can't ask for the whole table. */
+export const AUDIT_PAGE_LIMIT_MAX = 200;
+/** Clamp a caller's requested page size into the allowed range. */
+export function auditPageLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit) || limit < 1)
+        return AUDIT_PAGE_LIMIT_DEFAULT;
+    return Math.min(Math.floor(limit), AUDIT_PAGE_LIMIT_MAX);
+}
+/**
+ * Encode the last row of a page as the next page's cursor. `at` and `id` TOGETHER, because `at`
+ * alone is not unique: two events recorded in the same millisecond would straddle the boundary
+ * and be served twice or skipped.
+ */
+export function encodeAuditCursor(row) {
+    return `${row.at}:${row.id}`;
+}
+/**
+ * Decode a cursor, or null when there is none / it is unreadable.
+ *
+ * A malformed cursor reads as "start from the newest" rather than throwing: cursors are opaque
+ * and round-trip through a URL, so a truncated one is a client bug that should cost a page
+ * position, not a 500. It cannot widen a read either way, because the account scope is a
+ * separate argument that no cursor carries.
+ */
+export function decodeAuditCursor(cursor) {
+    if (!cursor)
+        return null;
+    const split = cursor.indexOf(':');
+    if (split <= 0 || split === cursor.length - 1)
+        return null;
+    const at = Number(cursor.slice(0, split));
+    if (!Number.isSafeInteger(at))
+        return null;
+    return { at, id: cursor.slice(split + 1) };
+}
+/**
+ * The persisted actor columns as a discriminated {@link AuditActor}.
+ *
+ * Anything that is not a complete `user` or `apiKey` principal reads as `system`: that is the
+ * honest rendering of "no principal is recorded on this row", and it never invents a user id,
+ * which is the single outcome that would misattribute an action to a person.
+ */
+export function rowToAuditActor(row) {
+    if (row.actor_kind === 'user' && row.actor_user_id) {
+        return { kind: 'user', userId: row.actor_user_id };
+    }
+    if (row.actor_kind === 'apiKey' && row.actor_api_key_id) {
+        return { kind: 'apiKey', apiKeyId: row.actor_api_key_id };
+    }
+    return { kind: 'system' };
+}
+/** The two nullable actor columns for a principal, for an INSERT. */
+export function auditActorColumns(actor) {
+    return {
+        actor_kind: actor.kind,
+        actor_user_id: actor.kind === 'user' ? actor.userId : null,
+        actor_api_key_id: actor.kind === 'apiKey' ? actor.apiKeyId : null,
+    };
+}
+/** An event's `details` as the single TEXT column both stores keep it in. */
+export function encodeAuditDetails(details) {
+    return JSON.stringify(details);
+}
+/**
+ * The `details` column as fields again, or an EMPTY set when the blob is unreadable.
+ *
+ * Empty rather than a throw, deliberately, and it is the one place in this module where the
+ * lenient branch is the strict choice: who acted, on what, and when are the irreplaceable parts
+ * of an audit row, and losing the whole row (or the whole PAGE) because one event's values no
+ * longer parse is the single failure a viewer must not have. The values are what the viewer
+ * interpolates, so their absence shows up as a row that states less, never as a row that is not
+ * there. A non-object blob (`"null"`, `"3"`, `"[]"`) counts as unreadable for the same reason it
+ * would break interpolation.
+ */
+export function decodeAuditDetails(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        // An unparseable value blob must not cost the row it belongs to, and the empty result is
+        // itself the report: the viewer renders the action with no values.
+        return {};
+    }
+}
+/** Every column of an audit event, for an INSERT. */
+export function auditEventColumns(event) {
+    return {
+        id: event.id,
+        account_id: event.accountId,
+        workspace_id: event.workspaceId ?? null,
+        ...auditActorColumns(event.actor),
+        action: event.action,
+        target_type: event.targetType,
+        target_id: event.targetId,
+        details: encodeAuditDetails(event.details),
+        at: event.at,
+    };
+}
+/**
+ * A persisted row as the event a viewer renders.
+ *
+ * Shaped structurally (a plain snake_case object) rather than against either driver's row type,
+ * so both facades map through this one function. `action` and `target_type` go through the
+ * contracts readers, so a member retired since the row was written arrives NAMED as retired
+ * rather than dropped or guessed at.
+ */
+export function rowToAuditEventView(row) {
+    return {
+        id: row.id,
+        accountId: row.account_id,
+        workspaceId: row.workspace_id,
+        actor: rowToAuditActor(row),
+        action: readAuditAction(row.action),
+        targetType: readAuditTargetType(row.target_type),
+        targetId: row.target_id,
+        details: decodeAuditDetails(row.details),
+        at: row.at,
+    };
+}
+//# sourceMappingURL=audit-log.js.map

package/dist/domain/audit-log.js.map

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

package/dist/domain/tool-call-rollup.d.ts

@@ -0,0 +1,53 @@
+import type { AgentToolCallSummary } from '../ports/agent-tool-calls.js';
+/** What every level of the tool-call rollup counts. */
+export interface ToolCallRollupTotals {
+    calls: number;
+    /** Calls that came back `ok: false` — the tool itself failed, inside the container. */
+    failures: number;
+}
+/** One tool's calls, folded across the agent kinds that made them. */
+export interface ToolCallToolRollup extends ToolCallRollupTotals {
+    tool: string;
+}
+/** One agent kind's calls, folded across the tools it used. */
+export interface ToolCallKindRollup extends ToolCallRollupTotals {
+    agentKind: string;
+}
+/** Fold every cell into the run's totals. */
+export declare function foldToolCallTotals(cells: readonly AgentToolCallSummary[]): ToolCallRollupTotals;
+/**
+ * Fold the cells into one rollup per TOOL, most-failed first.
+ *
+ * Ordered by failures rather than by call count or store order, because the question this
+ * breakdown exists to answer is which tool to look at, and a run's busiest tool is almost
+ * never its broken one.
+ */
+export declare function foldToolCallsByTool(cells: readonly AgentToolCallSummary[]): ToolCallToolRollup[];
+/** Fold the cells into one rollup per AGENT KIND, most-failed first (same ordering rule). */
+export declare function foldToolCallsByAgentKind(cells: readonly AgentToolCallSummary[]): ToolCallKindRollup[];
+/**
+ * The worst `(agentKind, tool)` cell that is itself a retry loop, or null when no cell is one.
+ *
+ * The finest grain the store keeps, which is the point: a run's failures are diagnostic when they
+ * CONCENTRATE (one agent kind retrying one tool that cannot work) and unremarkable when they
+ * scatter, and only a cell can tell those apart. Both breakdowns above have folded that
+ * concentration away by the time a reader sees them.
+ *
+ * FILTER FIRST, then rank. The reverse, ranking every failing cell and testing only the
+ * winner, reads as the same thing and is not: the ranking leads on failure COUNT, so a coder's
+ * 6 failures across 100 healthy `bash` calls outranks a fixer wedged 5-for-5 on one tool, and
+ * the run that is textbook stuck reports no loop at all. The qualifying cells are what the rule
+ * is about; the ranking only decides which of them to name.
+ */
+export declare function worstToolRetryLoop(cells: readonly AgentToolCallSummary[]): AgentToolCallSummary | null;
+/**
+ * The share of a rollup's calls that failed, or NULL where it made none.
+ *
+ * Null rather than 0: a run that called no tools has no failure rate, and reporting one as a
+ * clean 0% would put it beside a run whose every call worked — the same number for "nothing
+ * happened" and "everything worked", which are different findings. A cell always has calls (it
+ * exists because rows were counted into it), so only the folded totals of an empty run reach
+ * the null.
+ */
+export declare function toolCallFailureRate(totals: ToolCallRollupTotals): number | null;
+//# sourceMappingURL=tool-call-rollup.d.ts.map

package/dist/domain/tool-call-rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-rollup.d.ts","sourceRoot":"","sources":["../../src/domain/tool-call-rollup.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AAExE,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,uFAAuF;IACvF,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,IAAI,EAAE,MAAM,CAAA;CACb;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,SAAS,EAAE,MAAM,CAAA;CAClB;AAQD,6CAA6C;AAC7C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GAAG,oBAAoB,CAE/F;AAeD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GAAG,kBAAkB,EAAE,CAOhG;AAED,6FAA6F;AAC7F,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,kBAAkB,EAAE,CAStB;AA2CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,oBAAoB,GAAG,IAAI,CAE7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAE/E"}

package/dist/domain/tool-call-rollup.js

@@ -0,0 +1,117 @@
+// Pure folds over the TOOL-CALL rollup the telemetry stores compute.
+//
+// The sibling of `llm-rollup.ts`, and it follows the same rule for the same reason: the store
+// aggregates ONE grain — `(agentKind, tool)` — and every coarser view (per tool, per agent
+// kind, the run totals) is a fold over that same result set. A second aggregate over the same
+// rows is a second chance to disagree with the breakdown printed beside it.
+//
+// These fold a handful of cells (the tools one run touched), NOT the rows they were computed
+// from: the aggregation itself stays in SQL.
+const EMPTY = { calls: 0, failures: 0 };
+function merge(a, b) {
+    return { calls: a.calls + b.calls, failures: a.failures + b.failures };
+}
+/** Fold every cell into the run's totals. */
+export function foldToolCallTotals(cells) {
+    return cells.reduce((acc, cell) => merge(acc, cell), EMPTY);
+}
+/**
+ * Order two folded rows most-broken first: failure COUNT, then the failure SHARE, then the
+ * name so the order is total (an order that varies between two reads of the same unchanged
+ * run reads to a caller as a change in the run).
+ *
+ * The share is compared by cross-multiplication rather than by dividing: both `calls` are
+ * positive on a folded row, so the two orderings agree, and this one cannot produce a NaN
+ * from a row an empty fold happened to reach.
+ */
+function mostBrokenFirst(a, b) {
+    return b.failures - a.failures || b.failures * a.calls - a.failures * b.calls;
+}
+/**
+ * Fold the cells into one rollup per TOOL, most-failed first.
+ *
+ * Ordered by failures rather than by call count or store order, because the question this
+ * breakdown exists to answer is which tool to look at, and a run's busiest tool is almost
+ * never its broken one.
+ */
+export function foldToolCallsByTool(cells) {
+    const byTool = new Map();
+    for (const cell of cells) {
+        const prev = byTool.get(cell.tool);
+        byTool.set(cell.tool, { tool: cell.tool, ...merge(prev ?? EMPTY, cell) });
+    }
+    return [...byTool.values()].sort((a, b) => mostBrokenFirst(a, b) || a.tool.localeCompare(b.tool));
+}
+/** Fold the cells into one rollup per AGENT KIND, most-failed first (same ordering rule). */
+export function foldToolCallsByAgentKind(cells) {
+    const byKind = new Map();
+    for (const cell of cells) {
+        const prev = byKind.get(cell.agentKind);
+        byKind.set(cell.agentKind, { agentKind: cell.agentKind, ...merge(prev ?? EMPTY, cell) });
+    }
+    return [...byKind.values()].sort((a, b) => mostBrokenFirst(a, b) || a.agentKind.localeCompare(b.agentKind));
+}
+/**
+ * The single `(agentKind, tool)` cell most worth looking at among those given, or null when the
+ * set is empty or nothing in it failed.
+ *
+ * Ordered by the same rule as the breakdowns, so the row a reader is pointed at is the one that
+ * sorts first in them. Module-local: it RANKS a set someone else chose, which on its own answers
+ * no question a caller has. {@link worstToolRetryLoop} is the exported selector, and pairing the
+ * two here rather than at the call site is the whole point: ranking first and testing the winner
+ * afterwards silently drops every qualifying cell behind a busier one (see its note).
+ */
+function worstToolCallCell(cells) {
+    const failing = cells.filter((cell) => cell.failures > 0);
+    if (failing.length === 0)
+        return null;
+    return failing.sort((a, b) => mostBrokenFirst(a, b) ||
+        a.agentKind.localeCompare(b.agentKind) ||
+        a.tool.localeCompare(b.tool))[0];
+}
+/**
+ * Failures on ONE `(agentKind, tool)` cell at or above this share of that cell's calls, once it
+ * has failed at least {@link RETRY_LOOP_MIN_FAILURES} times, read as an agent retrying something
+ * that cannot work rather than meeting the occasional failing command.
+ *
+ * Two conditions rather than one because each alone fires on a healthy run: a share alone flags
+ * the single `bash` call that legitimately returned non-zero, and a count alone flags a thorough
+ * agent that ran hundreds of tests. Both together are the shape a stuck loop makes.
+ */
+const RETRY_LOOP_FAILURE_RATE = 0.5;
+const RETRY_LOOP_MIN_FAILURES = 5;
+/** Whether one cell, on its own, has the shape of an agent stuck retrying a broken tool. */
+function isToolRetryLoop(cell) {
+    return (cell.failures >= RETRY_LOOP_MIN_FAILURES &&
+        cell.failures / cell.calls >= RETRY_LOOP_FAILURE_RATE);
+}
+/**
+ * The worst `(agentKind, tool)` cell that is itself a retry loop, or null when no cell is one.
+ *
+ * The finest grain the store keeps, which is the point: a run's failures are diagnostic when they
+ * CONCENTRATE (one agent kind retrying one tool that cannot work) and unremarkable when they
+ * scatter, and only a cell can tell those apart. Both breakdowns above have folded that
+ * concentration away by the time a reader sees them.
+ *
+ * FILTER FIRST, then rank. The reverse, ranking every failing cell and testing only the
+ * winner, reads as the same thing and is not: the ranking leads on failure COUNT, so a coder's
+ * 6 failures across 100 healthy `bash` calls outranks a fixer wedged 5-for-5 on one tool, and
+ * the run that is textbook stuck reports no loop at all. The qualifying cells are what the rule
+ * is about; the ranking only decides which of them to name.
+ */
+export function worstToolRetryLoop(cells) {
+    return worstToolCallCell(cells.filter(isToolRetryLoop));
+}
+/**
+ * The share of a rollup's calls that failed, or NULL where it made none.
+ *
+ * Null rather than 0: a run that called no tools has no failure rate, and reporting one as a
+ * clean 0% would put it beside a run whose every call worked — the same number for "nothing
+ * happened" and "everything worked", which are different findings. A cell always has calls (it
+ * exists because rows were counted into it), so only the folded totals of an empty run reach
+ * the null.
+ */
+export function toolCallFailureRate(totals) {
+    return totals.calls > 0 ? totals.failures / totals.calls : null;
+}
+//# sourceMappingURL=tool-call-rollup.js.map

package/dist/domain/tool-call-rollup.js.map

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

package/dist/domain/workspace-cascade.d.ts

@@ -18,7 +18,7 @@
  * - Runtime-specific tables that only exist on one facade (e.g. the Cloudflare-only
  *   `live_containers` Durable-Object tracking table) are appended by that facade.
  */
-export declare const WORKSPACE_SCOPED_TABLES: readonly ['agent_prompt_revisions', 'agent_runs', 'blocks', 'brainstorm_sessions', 'capability_credentials', 'clarity_reviews', 'consensus_groups', 'consensus_sessions', 'custom_manifest_types', 'doc_interview_sessions', 'document_connections', 'documents', 'environment_connections', 'environment_test_runs', 'environment_user_handlers', 'environments', 'gate_outcomes', 'github_branches', 'github_check_runs', 'github_commits', 'github_installations', 'github_issues', 'github_pull_requests', 'github_repos', 'incident_enrichment_connections', 'initiatives', 'kaizen_gradings', 'kaizen_verified_combos', 'merge_threshold_presets', 'merge_track_records', 'model_presets', 'notification_webhooks', 'notifications', 'observability_connections', 'package_registry_connections', 'pipeline_schedule_runs', 'pipeline_schedules', 'pipelines', 'platform_run_days', 'provider_model_catalog', 'provider_subscription_tokens', 'public_api_keys', 'reference_architectures', 'release_health_configs', 'requirement_reviews', 'review_question_posts', 'runner_pool_connections', 'shared_stacks', 'slack_settings', 'task_connections', 'task_source_settings', 'tasks', 'test_secrets', 'tracker_comment_ingests', 'token_usage', 'tracker_settings', 'validation_configs', 'workspace_agent_settings', 'workspace_fragment_defaults', 'workspace_members', 'workspace_settings'];
+export declare const WORKSPACE_SCOPED_TABLES: readonly ['agent_prompt_revisions', 'agent_runs', 'blocks', 'brainstorm_sessions', 'capability_credentials', 'clarity_reviews', 'consensus_groups', 'consensus_sessions', 'custom_manifest_types', 'doc_interview_sessions', 'document_connections', 'documents', 'environment_connections', 'environment_test_runs', 'environment_user_handlers', 'environments', 'gate_outcomes', 'github_branches', 'github_check_runs', 'github_commits', 'github_installations', 'github_issues', 'github_pull_requests', 'github_repos', 'incident_enrichment_connections', 'initiatives', 'kaizen_gradings', 'kaizen_verified_combos', 'mcp_oauth_grants', 'merge_threshold_presets', 'merge_track_records', 'model_presets', 'notification_webhooks', 'notifications', 'observability_connections', 'package_registry_connections', 'pipeline_schedule_runs', 'pipeline_schedules', 'pipelines', 'platform_run_days', 'provider_model_catalog', 'provider_subscription_tokens', 'public_api_keys', 'reference_architectures', 'release_health_configs', 'requirement_reviews', 'review_question_posts', 'runner_pool_connections', 'shared_stacks', 'slack_settings', 'task_connections', 'task_source_settings', 'tasks', 'test_secrets', 'tracker_comment_ingests', 'token_usage', 'tracker_settings', 'validation_configs', 'workspace_agent_settings', 'workspace_fragment_defaults', 'workspace_members', 'workspace_settings'];
 export type WorkspaceScopedTable = (typeof WORKSPACE_SCOPED_TABLES)[number];
 /**
  * Tables that carry a `workspace_id` column but are NOT in {@link WORKSPACE_SCOPED_TABLES}

package/dist/domain/workspace-cascade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-cascade.d.ts","sourceRoot":"","sources":["../../src/domain/workspace-cascade.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,YAClC,wBAAwB,EACxB,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,WAAW,EACX,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,iCAAiC,EACjC,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,2BAA2B,EAC3B,8BAA8B,EAC9B,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,wBAAwB,EACxB,8BAA8B,EAC9B,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACP,cAAc,EACd,yBAAyB,EACzB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,mBAAmB,EACnB,oBAAoB,CACZ,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,YAAI,oBAAoB,EAAE,kBAAkB,CAAU,CAAA"}
+{"version":3,"file":"workspace-cascade.d.ts","sourceRoot":"","sources":["../../src/domain/workspace-cascade.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,YAClC,wBAAwB,EACxB,YAAY,EACZ,QAAQ,EACR,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,EACtB,WAAW,EACX,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,iCAAiC,EACjC,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,2BAA2B,EAC3B,8BAA8B,EAC9B,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,wBAAwB,EACxB,8BAA8B,EAC9B,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACP,cAAc,EACd,yBAAyB,EACzB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,mBAAmB,EACnB,oBAAoB,CACZ,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,YAAI,oBAAoB,EAAE,kBAAkB,CAAU,CAAA"}