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

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/adapter-edge-cases.test.ts

@@ -2,6 +2,25 @@ import { describe, expect, it } from 'vitest';
 import { type JsonObject, SchemaAdapterError, toOpenApiComponents } from './adapter.js';
 
 describe('reference integrity', () => {
+    it('uses the definition when a named root references its own $defs entry', () => {
+        const definition = {
+            type: 'object',
+            properties: { child: { $ref: '#/$defs/Account' } },
+        };
+        expect(toOpenApiComponents({ Account: { $ref: '#/$defs/Account', $defs: { Account: definition } } })).toEqual({
+            Account: { type: 'object', properties: { child: { $ref: '#/components/schemas/Account' } } },
+        });
+    });
+
+    it('still rejects conflicting definitions behind a named root reference', () => {
+        expect(() =>
+            toOpenApiComponents({
+                Holder: { type: 'object', $defs: { Account: { type: 'string' } } },
+                Account: { $ref: '#/$defs/Account', $defs: { Account: { type: 'number' } } },
+            }),
+        ).toThrow(SchemaAdapterError);
+    });
+
     it('rejects a reference to a component that does not exist', () => {
         // A dangling pointer produces a spec that validates structurally but breaks every
         // generated client at deserialization time.

package/src/api-schemas/adapter.ts

@@ -316,7 +316,14 @@ export function toOpenApiComponents(
             throw new SchemaAdapterError(`Component '${name}' is not an object schema.`);
         }
         ctx.rootName = name;
-        register(name, walk(structuredClone(schema), ctx, true) as JsonObject, ctx);
+        const adapted = walk(structuredClone(schema), ctx, true) as JsonObject;
+        // Zod 4.5 emits named roots as a bare reference to their own $defs entry.
+        // walk already registered that definition; registering the wrapper would replace it
+        // with a self-reference and incorrectly report a conflicting component shape.
+        if (adapted[REF] === `${COMPONENT_PREFIX}${name}` && Object.keys(adapted).length === 1 && ctx.seen.has(name)) {
+            continue;
+        }
+        register(name, adapted, ctx);
     }
 
     const strict = options.strictComponents;

package/src/api-schemas/agent-communication.ts

@@ -139,6 +139,12 @@ export const RegisterPendingAskRequestSchema = z
         timeoutHours: z.number().optional(),
         userChannels: z.array(UserChannelSchema),
         taskFields: z.array(TaskFieldSchema).optional(),
+        /**
+         * Id of the REQUEST_INPUT message carrying this ask (the `ask_user` tool-use id), so a
+         * notified client can open the exact prompt. Optional: workers built before this field
+         * still validate against the component.
+         */
+        requestId: z.string().optional(),
     })
     .meta({ id: 'RegisterPendingAskRequest' });
 

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { validateApiRequest, validateApiResponse } from './registry.js';
+
+describe('agent history delta wire contract', () => {
+    it('accepts optional cursors and bounds their size', () => {
+        expect(validateApiRequest('AgentRunDetailsQuery', { include_history: true, from: 'opaque' }).valid).toBe(true);
+        expect(validateApiRequest('AgentRunDetailsQuery', { from: {} }).valid).toBe(false);
+        expect(validateApiRequest('AgentRunDetailsQuery', { from: 'x'.repeat(12001) }).valid).toBe(false);
+    });
+    it('validates legacy, snapshot, and delta responses through the registered contract', () => {
+        for (const mode of [undefined, 'snapshot', 'delta']) {
+            expect(
+                validateApiResponse('WorkflowRunWithDetails', {
+                    started_at: null,
+                    closed_at: null,
+                    history: {
+                        type: 'agent',
+                        ...(mode ? { mode, next_from: 'opaque' } : {}),
+                        agentTasks: [
+                            {
+                                history_id: 'run:activity:7',
+                                taskType: 'tool_call',
+                                toolName: 'test',
+                                status: 'running',
+                                scheduled_at: null,
+                                started_at: null,
+                                completed_at: null,
+                            },
+                        ],
+                    },
+                }).valid,
+            ).toBe(true);
+        }
+        expect(
+            validateApiResponse('WorkflowRunWithDetails', {
+                started_at: null,
+                closed_at: null,
+                history: { type: 'agent', mode: 'append', agentTasks: [] },
+            }).valid,
+        ).toBe(false);
+    });
+});

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

@@ -0,0 +1,240 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+    AgentRunEvaluation,
+    AgentRunEvaluationRollup,
+    AgentRunFeedbackEntry,
+    AgentRunFeedbackPayload,
+    AgentRunFeedbackResponse,
+} from '../store/agent-run.js';
+import { AgentEventType, type TurnEvaluationEvent } from '../workflow-analytics.js';
+import type {
+    AgentRunEvaluationRollupSchema,
+    AgentRunEvaluationSchema,
+    AgentRunFeedbackEntrySchema,
+    AgentRunFeedbackPayloadSchema,
+    AgentRunFeedbackResponseSchema,
+} from './agent-runs.js';
+import { validateApiRequest, validateApiResponse } from './registry.js';
+
+const turnEvaluation: TurnEvaluationEvent = {
+    eventType: AgentEventType.TurnEvaluation,
+    eventId: 'run-1:main:1:answer',
+    timestamp: '2026-09-11T10:00:00.000Z',
+    runId: 'wf-run-1',
+    agentRunId: 'run-1',
+    model: 'claude',
+    environmentId: 'env-1',
+    environmentType: 'vertexai',
+    interactionId: 'sys:StudioAssistant',
+    schemaVersion: 1,
+    detectorVersion: 1,
+    workstreamId: 'main',
+    turnSeq: 1,
+    terminalType: 'answer',
+    startedAt: '2026-09-11T09:59:00.000Z',
+    endedAt: '2026-09-11T10:00:00.000Z',
+    durationMs: 60_000,
+    activeMs: 50_000,
+    askUserWaitMs: 0,
+    approvalWaitMs: 10_000,
+    toolCalls: 3,
+    errorToolResults: 1,
+    maxFailStreak: 1,
+    identicalRetryCount: 0,
+    unrecoveredTools: [],
+    errorClasses: { schema: 1, platform: 0, config: 0, environment: 0, other: 0 },
+    gatherCalls: 2,
+    gatherRatio: 2 / 3,
+    mutationAttempted: true,
+    mutationSucceeded: true,
+    rereadCount: 0,
+    overheadCalls: 0,
+    skillsLoaded: 0,
+    interruptedToolCalls: 0,
+    llmCalls: 4,
+    promptTokens: 1000,
+    completionTokens: 200,
+    cachedTokens: 800,
+    retryCompletionTokens: 50,
+    approvalsRequested: 1,
+    approvalsDenied: 0,
+    stopRequests: 0,
+    stallCorrectives: 0,
+    stallTrips: 0,
+    followupAfterAnswer: false,
+    severity: 'none',
+    flags: [],
+    tools: [
+        {
+            seq: 1,
+            toolUseId: 'tu-1',
+            name: 'create_view',
+            approvalClass: 'side_effecting',
+            ok: false,
+            errorClass: 'schema',
+            sig: 'abcd1234',
+            durationMs: 20,
+        },
+    ],
+    toolsTruncated: 0,
+};
+
+describe('agent run evaluation API contracts', () => {
+    it('derives the public types from the runtime schemas', () => {
+        expectTypeOf<AgentRunFeedbackPayload>().toEqualTypeOf<
+            import('zod').z.infer<typeof AgentRunFeedbackPayloadSchema>
+        >();
+        expectTypeOf<AgentRunFeedbackResponse>().toEqualTypeOf<
+            import('zod').z.infer<typeof AgentRunFeedbackResponseSchema>
+        >();
+        expectTypeOf<AgentRunFeedbackEntry>().toEqualTypeOf<
+            import('zod').z.infer<typeof AgentRunFeedbackEntrySchema>
+        >();
+        expectTypeOf<AgentRunEvaluationRollup>().toEqualTypeOf<
+            import('zod').z.infer<typeof AgentRunEvaluationRollupSchema>
+        >();
+        expectTypeOf<AgentRunEvaluation>().toEqualTypeOf<import('zod').z.infer<typeof AgentRunEvaluationSchema>>();
+    });
+
+    it('accepts a turn_evaluation event through the ingest payload', () => {
+        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);
+    });
+
+    it('accepts a feedback event and a judgement event', () => {
+        const base = {
+            timestamp: turnEvaluation.timestamp,
+            runId: 'wf-run-1',
+            agentRunId: 'run-1',
+            model: '',
+            environmentId: '',
+            environmentType: '',
+            interactionId: 'sys:StudioAssistant',
+            deployment: { env: 'staging', group: 'staging', version: 'abc' },
+        };
+        const events = [
+            {
+                ...base,
+                eventType: 'feedback',
+                feedbackId: 'f1',
+                rating: 'down',
+                hasComment: false,
+                messageScoped: false,
+                replaced: false,
+            },
+            {
+                ...base,
+                eventType: 'turn_judgement',
+                evaluationRev: 2,
+                workstreamId: 'main',
+                turnSeq: 1,
+                gate: 'signal',
+                sampleRate: 0,
+                selectedProbability: 1,
+                outcome: 'judged',
+                verdict: 'failure',
+                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);
+    });
+
+    it('requires feedback_id and rejects the retired episode_seq field', () => {
+        expect(validateApiRequest('AgentRunFeedbackPayload', { rating: 'up' }).valid).toBe(false);
+        expect(validateApiRequest('AgentRunFeedbackPayload', { feedback_id: 'f1', rating: 'up' }).valid).toBe(true);
+        expect(
+            validateApiRequest('AgentRunFeedbackPayload', { feedback_id: 'f1', rating: 'up', episode_seq: 1 }).valid,
+        ).toBe(false);
+    });
+
+    it('keeps the workflow rollup free of server-owned fields', () => {
+        const rollup: AgentRunEvaluationRollup = {
+            seq: 3,
+            detector_version: 1,
+            turns: 2,
+            severity: 'medium',
+            flags: ['unrecovered_tool'],
+            worst_turn_seq: 2,
+            last_terminal_type: 'answer',
+            totals: {
+                tool_calls: 5,
+                error_tool_results: 2,
+                unrecovered_tools: ['create_view'],
+                llm_calls: 6,
+                prompt_tokens: 100,
+                completion_tokens: 20,
+                cached_tokens: 0,
+                retry_completion_tokens: 5,
+                active_ms: 1000,
+                ask_user_wait_ms: 0,
+                approval_wait_ms: 0,
+                followups: 0,
+                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 } },
+            }).valid,
+        ).toBe(false);
+    });
+
+    it('validates the published evaluation summary', () => {
+        const evaluation: AgentRunEvaluation = {
+            rev: 2,
+            feedback_counts: { up: 0, down: 1, last_rating: 'down', last_reason_code: 'wrong_result' },
+            severity: 'none',
+            flags: [],
+            contradicted: true,
+            contradiction_reasons: ['feedback_down_on_clean_run'],
+            deployment_env: 'staging',
+            updated_at: turnEvaluation.timestamp,
+        };
+        expect(validateApiResponse('AgentRunEvaluation', evaluation).valid).toBe(true);
+        expect(validateApiRequest('ListAgentRunsQuery', { evaluation_severity: ['unrated', 'high'] }).valid).toBe(true);
+    });
+});