@vertesia/common 1.6.0-dev.20260912.110338Z → 1.6.0-dev.20260918.061604Z

package/src/api-contract/components.generated.json

@@ -289,7 +289,15 @@
         "const": "stripe"
       },
       "portal_url": {
-        "type": "string"
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Interactive billing portal URL; null for account API keys."
       }
     },
     "required": [
@@ -1303,6 +1311,16 @@
   "Permission": {
     "type": "string",
     "enum": [
+      "account:user:read",
+      "account:user:manage",
+      "account:group:read",
+      "account:group:manage",
+      "account:membership:read",
+      "account:membership:manage",
+      "account:api_key:read",
+      "account:api_key:manage",
+      "account:billing:status_read",
+      "account:billing:portal_create",
       "schedule:delegate",
       "interaction:read",
       "interaction:write",
@@ -1374,6 +1392,10 @@
       "enabled": {
         "type": "boolean"
       },
+      "scim_provisioning": {
+        "type": "boolean",
+        "description": "Organization-wide SCIM provisioning credential. Only account administrators may create or manage these keys. May be enabled by account administrators on existing keys; disable or delete to revoke access."
+      },
       "created_by": {
         "type": "string"
       },
@@ -1433,6 +1455,7 @@
     "enum": [
       "owner",
       "admin",
+      "app_admin",
       "manager",
       "developer",
       "application",
@@ -1485,6 +1508,10 @@
       "enabled": {
         "type": "boolean"
       },
+      "scim_provisioning": {
+        "type": "boolean",
+        "description": "Organization-wide SCIM provisioning credential. Only account administrators may create or manage these keys. May be enabled by account administrators on existing keys; disable or delete to revoke access."
+      },
       "created_by": {
         "type": "string"
       },
@@ -1539,6 +1566,174 @@
     ],
     "additionalProperties": false
   },
+  "AccountApiKey": {
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "account": {
+        "type": "string"
+      },
+      "enabled": {
+        "type": "boolean"
+      },
+      "maskedValue": {
+        "type": "string"
+      },
+      "created_by": {
+        "type": "string"
+      },
+      "updated_by": {
+        "type": "string"
+      },
+      "created_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "updated_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "expires_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "scope": {
+        "type": "string",
+        "const": "account"
+      },
+      "profile": {
+        "type": "string",
+        "const": "account_admin_v1"
+      },
+      "last_used_at": {
+        "type": "string",
+        "format": "date-time"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "account",
+      "enabled",
+      "created_by",
+      "updated_by",
+      "created_at",
+      "updated_at",
+      "scope",
+      "profile"
+    ],
+    "additionalProperties": false
+  },
+  "AccountApiKeyWithValue": {
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "account": {
+        "type": "string"
+      },
+      "enabled": {
+        "type": "boolean"
+      },
+      "maskedValue": {
+        "type": "string"
+      },
+      "created_by": {
+        "type": "string"
+      },
+      "updated_by": {
+        "type": "string"
+      },
+      "created_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "updated_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "expires_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "scope": {
+        "type": "string",
+        "const": "account"
+      },
+      "profile": {
+        "type": "string",
+        "const": "account_admin_v1"
+      },
+      "last_used_at": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "value": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "account",
+      "enabled",
+      "created_by",
+      "updated_by",
+      "created_at",
+      "updated_at",
+      "scope",
+      "profile",
+      "value"
+    ],
+    "additionalProperties": false
+  },
+  "AccountApiKeyArray": {
+    "type": "array",
+    "items": {
+      "$ref": "#/components/schemas/AccountApiKey"
+    }
+  },
+  "CreateAccountApiKeyPayload": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      },
+      "expires_at": {
+        "type": "string",
+        "format": "date-time"
+      }
+    },
+    "required": [
+      "name"
+    ],
+    "additionalProperties": false
+  },
+  "UpdateAccountApiKeyPayload": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S"
+      },
+      "enabled": {
+        "type": "boolean"
+      }
+    },
+    "additionalProperties": false
+  },
   "ApiKeyReadResponse": {
     "type": "object",
     "properties": {
@@ -1569,6 +1764,10 @@
       "enabled": {
         "type": "boolean"
       },
+      "scim_provisioning": {
+        "type": "boolean",
+        "description": "Organization-wide SCIM provisioning credential. Only account administrators may create or manage these keys. May be enabled by account administrators on existing keys; disable or delete to revoke access."
+      },
       "created_by": {
         "type": "string"
       },
@@ -1647,6 +1846,10 @@
         "type": "string",
         "format": "date-time"
       },
+      "scim_provisioning": {
+        "type": "boolean",
+        "description": "Organization-wide SCIM provisioning credential. Only account administrators may create or manage these keys. May be enabled by account administrators on existing keys; disable or delete to revoke access."
+      },
       "properties": {
         "type": "object",
         "additionalProperties": true,
@@ -1682,6 +1885,10 @@
       "enabled": {
         "type": "boolean"
       },
+      "scim_provisioning": {
+        "type": "boolean",
+        "description": "Organization-wide SCIM provisioning credential. Only account administrators may create or manage these keys. May be enabled by account administrators on existing keys; disable or delete to revoke access."
+      },
       "properties": {
         "type": "object",
         "additionalProperties": true,
@@ -2339,9 +2546,10 @@
       "long",
       "double",
       "date",
-      "geo_point"
+      "geo_point",
+      "nested"
     ],
-    "description": "Elasticsearch field types that may be explicitly assigned to content-object properties. Paths are relative to the object's `properties` field."
+    "description": "Elasticsearch field types that may be explicitly assigned to content-object properties. Declare nested object-array paths with type `nested` and their children as separate dotted paths. Paths are relative to the object's `properties` field."
   },
   "ProjectConfigurationEmbedding": {
     "type": "object",
@@ -32884,6 +33092,11 @@
             "type": "integer",
             "minimum": -9007199254740991,
             "maximum": 9007199254740991
+          },
+          "stall_trips": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -32945,7 +33158,8 @@
       "high_gather",
       "overhead",
       "followup_after_answer",
-      "approval_denied"
+      "approval_denied",
+      "circuit_breaker"
     ],
     "description": "Reason behind an evaluation severity."
   },
@@ -32986,7 +33200,7 @@
       "down"
     ],
     "additionalProperties": false,
-    "description": "Ratings over the retained feedback entries."
+    "description": "Ratings over the retained feedback entries, one vote per rater: a user who rated the run and one of its answers counts once, by their latest rating."
   },
   "AgentRunFeedbackRating": {
     "type": "string",
@@ -35490,6 +35704,16 @@
             "minimum": -9007199254740991,
             "maximum": 9007199254740991
           },
+          "stallCorrectives": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "stallTrips": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
           "followupAfterAnswer": {
             "type": "boolean"
           },
@@ -35856,6 +36080,138 @@
           "promptVersion"
         ],
         "additionalProperties": false
+      },
+      {
+        "type": "object",
+        "properties": {
+          "timestamp": {
+            "type": "string"
+          },
+          "runId": {
+            "type": "string"
+          },
+          "agentRunId": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "environmentId": {
+            "type": "string"
+          },
+          "environmentType": {
+            "type": "string"
+          },
+          "interactionId": {
+            "type": "string"
+          },
+          "parentRunId": {
+            "type": "string"
+          },
+          "ancestorRunIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "eventId": {
+            "type": "string"
+          },
+          "deployment": {
+            "type": "object",
+            "properties": {
+              "env": {
+                "type": "string"
+              },
+              "group": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              },
+              "region": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "env",
+              "group",
+              "version"
+            ],
+            "additionalProperties": false
+          },
+          "producer": {
+            "type": "object",
+            "properties": {
+              "version": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "version"
+            ],
+            "additionalProperties": false
+          },
+          "eventType": {
+            "type": "string",
+            "const": "stall_breaker"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "corrective",
+              "trip"
+            ]
+          },
+          "toolNames": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "repeatCount": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "stallMeasure": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "allErrored": {
+            "type": "boolean"
+          },
+          "iteration": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "interactive": {
+            "type": "boolean"
+          },
+          "workstreamId": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "timestamp",
+          "runId",
+          "model",
+          "environmentId",
+          "environmentType",
+          "interactionId",
+          "eventType",
+          "action",
+          "toolNames",
+          "repeatCount",
+          "stallMeasure",
+          "allErrored",
+          "iteration",
+          "interactive",
+          "workstreamId"
+        ],
+        "additionalProperties": false
       }
     ]
   },

package/src/api-schemas/account-apikey.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { ApiSchemaComponents } from '../api-contract/index.js';
+import {
+    AccountApiKeySchema,
+    AccountApiKeyWithValueSchema,
+    ApiKeySchema,
+    CreateAccountApiKeyPayloadSchema,
+    UpdateAccountApiKeyPayloadSchema,
+} from './apikey.js';
+import { validateApiRequest } from './registry.js';
+
+describe('separate account-key wire contract', () => {
+    const metadata = {
+        id: 'key',
+        name: 'IdP',
+        account: 'account',
+        scope: 'account',
+        profile: 'account_admin_v1',
+        enabled: true,
+        maskedValue: 'sk-…',
+        created_at: '2026-09-15T00:00:00Z',
+        updated_at: '2026-09-15T00:00:00Z',
+        created_by: 'user:admin',
+        updated_by: 'user:admin',
+    };
+    it('requires account scope/profile without weakening the project-key contract', () => {
+        expect(AccountApiKeySchema.safeParse(metadata).success).toBe(true);
+        expect(AccountApiKeySchema.safeParse({ ...metadata, profile: 'other' }).success).toBe(false);
+        expect(ApiKeySchema.safeParse(metadata).success).toBe(false);
+        expect(AccountApiKeyWithValueSchema.safeParse(metadata).success).toBe(false);
+        expect(AccountApiKeyWithValueSchema.safeParse({ ...metadata, value: 'test-secret' }).success).toBe(true);
+    });
+    it('publishes strict management payloads and metadata without a value or project property', () => {
+        const components = ApiSchemaComponents as Record<
+            string,
+            { additionalProperties?: boolean; properties?: Record<string, unknown>; required?: string[] }
+        >;
+        for (const name of ['AccountApiKey', 'CreateAccountApiKeyPayload', 'UpdateAccountApiKeyPayload']) {
+            expect(components[name].additionalProperties).toBe(false);
+            expect(components[name].properties).not.toHaveProperty('value');
+            expect(components[name].properties).not.toHaveProperty('project');
+        }
+        expect(components.ApiKey.required).toContain('project');
+    });
+});
+
+// AJV enforces emitted JSON Schema; Zod trimming alone cannot reject whitespace at the API boundary.
+describe.each([
+    ['CreateAccountApiKeyPayload', CreateAccountApiKeyPayloadSchema],
+    ['UpdateAccountApiKeyPayload', UpdateAccountApiKeyPayloadSchema],
+] as const)('%s name validation', (component, schema) => {
+    it.each(['', '   ', '\t\n ', '\u00a0'])('rejects blank name %j in Zod and AJV', (name) => {
+        expect(schema.safeParse({ name }).success).toBe(false);
+        expect(validateApiRequest(component, { name }).valid).toBe(false);
+    });
+    it.each(['IdP provisioning', '  IdP provisioning  '])('accepts nonblank name %j in both validators', (name) => {
+        expect(schema.safeParse({ name }).success).toBe(true);
+        expect(validateApiRequest(component, { name }).valid).toBe(true);
+    });
+});

package/src/api-schemas/account.contract.test.ts

@@ -74,7 +74,7 @@ describe('gate 1 — the schema is the single source of truth for the public typ
             portal_url: 'https://billing.stripe.com/p/session_1',
         };
         if (enabled.status === 'enabled') {
-            assertType<Equals<typeof enabled.portal_url, string>>(true);
+            assertType<Equals<typeof enabled.portal_url, string | null>>(true);
             expect(enabled.portal_url).toBe('https://billing.stripe.com/p/session_1');
         }
 
@@ -146,6 +146,7 @@ describe('gate 3 — AJV validates the same canonical objects that are published
     it('enforces the discriminated union per branch', () => {
         const validate = compile('StripeBillingStatusResponse');
         expect(validate({ status: 'enabled', billing_method: 'stripe', portal_url: 'https://x' })).toBe(true);
+        expect(validate({ status: 'enabled', billing_method: 'stripe', portal_url: null })).toBe(true);
         expect(validate({ status: 'disabled', billing_method: null, reason: 'No billing method' })).toBe(true);
         // The flattened interface allowed this; a real discriminated union does not.
         expect(validate({ status: 'enabled', billing_method: 'stripe', reason: 'nope' })).toBe(false);

package/src/api-schemas/account.ts

@@ -111,14 +111,7 @@ export const UpdateAccountPayloadSchema = z
     })
     .meta({ id: 'UpdateAccountPayload' });
 
-/**
- * Stripe billing status, modelled as a real discriminated union.
- *
- * The hand-written `StripeBillingStatusResponse` in `meters.ts` flattens this into one object
- * with `portal_url?` and `reason?` both optional, so a generated Java/Go client gets two
- * unrelated optionals and no way to know which is populated. The server only ever sets
- * `portal_url` when enabled and `reason` when disabled.
- */
+/** Stripe billing status. Account API keys receive status without a billing portal session. */
 export const StripeBillingEnabledSchema = z
     .object({
         status: z.literal('enabled'),
@@ -128,7 +121,10 @@ export const StripeBillingEnabledSchema = z
          * would describe states the server cannot produce.
          */
         billing_method: z.literal(BillingMethod.stripe),
-        portal_url: z.string(),
+        portal_url: z
+            .string()
+            .nullable()
+            .meta({ description: 'Interactive billing portal URL; null for account API keys.' }),
     })
     .meta({ id: 'StripeBillingEnabled' });
 

package/src/api-schemas/agent-runs.contract.test.ts

@@ -59,6 +59,8 @@ const turnEvaluation: TurnEvaluationEvent = {
     approvalsRequested: 1,
     approvalsDenied: 0,
     stopRequests: 0,
+    stallCorrectives: 0,
+    stallTrips: 0,
     followupAfterAnswer: false,
     severity: 'none',
     flags: [],
@@ -98,6 +100,11 @@ describe('agent run evaluation API contracts', () => {
         expect(validateApiRequest('IngestAgentEventsPayload', { events: [turnEvaluation] }).valid).toBe(true);
     });
 
+    it('accepts a turn_evaluation event from a producer that predates the stall counters', () => {
+        const { stallCorrectives: _c, stallTrips: _t, ...legacy } = turnEvaluation;
+        expect(validateApiRequest('IngestAgentEventsPayload', { events: [legacy] }).valid).toBe(true);
+    });
+
     it('rejects a turn_evaluation event with an undeclared field', () => {
         const events = [{ ...turnEvaluation, verdict: 'success' }];
         expect(validateApiRequest('IngestAgentEventsPayload', { events }).valid).toBe(false);
@@ -138,6 +145,18 @@ describe('agent run evaluation API contracts', () => {
                 score: 0.2,
                 promptVersion: 'v1',
             },
+            {
+                ...base,
+                eventType: 'stall_breaker',
+                action: 'trip',
+                toolNames: ['fetch_document'],
+                repeatCount: 4,
+                stallMeasure: 4,
+                allErrored: false,
+                iteration: 7,
+                interactive: true,
+                workstreamId: 'main',
+            },
         ];
         expect(validateApiRequest('IngestAgentEventsPayload', { events }).valid).toBe(true);
     });
@@ -175,10 +194,28 @@ describe('agent run evaluation API contracts', () => {
                 approvals_requested: 0,
                 approvals_denied: 0,
                 stop_requests: 0,
+                stall_trips: 0,
             },
             updated_at: turnEvaluation.timestamp,
         };
         expect(validateApiRequest('UpdateAgentRunStatusPayload', { evaluation_rollup: rollup }).valid).toBe(true);
+        // Rollups stored or sent before the stall counter existed keep validating.
+        const { stall_trips: _s, ...legacyTotals } = rollup.totals;
+        expect(
+            validateApiRequest('UpdateAgentRunStatusPayload', {
+                evaluation_rollup: { ...rollup, totals: legacyTotals },
+            }).valid,
+        ).toBe(true);
+        expect(
+            validateApiResponse('AgentRunEvaluation', {
+                rev: 1,
+                rollup: { ...rollup, totals: legacyTotals },
+                severity: 'medium',
+                flags: ['unrecovered_tool'],
+                contradicted: false,
+                updated_at: turnEvaluation.timestamp,
+            }).valid,
+        ).toBe(true);
         expect(
             validateApiRequest('UpdateAgentRunStatusPayload', {
                 evaluation_rollup: { ...rollup, feedback_counts: { up: 1, down: 0 } },