@vertesia/common 1.5.0-dev.20260804.124748Z → 1.5.0-dev.20260807.073259Z

package/src/apps.test.ts

@@ -1,4 +1,9 @@
 import { describe, expect, it } from 'vitest';
+import {
+    AppEventHookPayloadSchema,
+    AppEventSubscriptionDefinitionSchema,
+    AppPackageHooksSchema,
+} from './api-schemas/app-runtime.js';
 import { APP_ARTIFACT_TYPES, APP_CAPABILITIES, APP_PACKAGE_SCOPES, effectiveAppAccessControl } from './apps.js';
 
 describe('app capability contracts', () => {
@@ -6,6 +11,83 @@ describe('app capability contracts', () => {
         expect(APP_CAPABILITIES).toContain('views');
         expect(APP_PACKAGE_SCOPES).toContain('views');
         expect(APP_ARTIFACT_TYPES).toContain('view');
+        expect(APP_ARTIFACT_TYPES).toContain('hook');
+        expect(APP_ARTIFACT_TYPES).toContain('subscription');
+    });
+
+    it('exposes app hooks as a package query scope', () => {
+        expect(APP_PACKAGE_SCOPES).toContain('hooks');
+        expect(APP_PACKAGE_SCOPES).toContain('subscriptions');
+    });
+
+    it('accepts app-owned subscriptions without a deployment-specific target', () => {
+        expect(
+            AppEventSubscriptionDefinitionSchema.parse({
+                id: 'content-updated',
+                name: 'Content updated',
+                hook: 'content-updated',
+                filter: { action: ['update'], resource_type: ['content_object'] },
+                run_as_role: 'automation',
+            }),
+        ).toEqual({
+            id: 'content-updated',
+            name: 'Content updated',
+            hook: 'content-updated',
+            filter: { action: ['update'], resource_type: ['content_object'] },
+            run_as_role: 'automation',
+        });
+    });
+
+    it('validates the canonical app event-hook envelope', () => {
+        const payload = {
+            event: {
+                event_id: 'event-1',
+                root_event_id: 'event-1',
+                hop_count: 0,
+                event_category: 'content',
+                action: 'update',
+                resource_type: 'content_object',
+                resource_id: 'object-1',
+                account_id: 'account-1',
+                project_id: 'project-1',
+                tenant_id: 'account-1_project-1',
+                timestamp: '2026-08-05T10:00:00.000Z',
+                source: 'zeno-server',
+                details: { changed: ['title'] },
+            },
+            delivery: {
+                id: 'delivery-1',
+                subscription_id: 'subscription-1',
+                attempt: 1,
+            },
+        };
+
+        expect(AppEventHookPayloadSchema.parse(payload)).toEqual(payload);
+        expect(() => AppEventHookPayloadSchema.parse({ event: payload.event })).toThrow();
+    });
+
+    it('accepts lifecycle and event hook package metadata', () => {
+        expect(
+            AppPackageHooksSchema.parse({
+                install: '/api/hooks/install',
+                events: [
+                    {
+                        name: 'content-updated',
+                        path: '/api/hooks/content-updated',
+                        description: 'Processes updated content.',
+                    },
+                ],
+            }),
+        ).toEqual({
+            install: '/api/hooks/install',
+            events: [
+                {
+                    name: 'content-updated',
+                    path: '/api/hooks/content-updated',
+                    description: 'Processes updated content.',
+                },
+            ],
+        });
     });
 });
 

package/src/apps.ts

@@ -2,9 +2,11 @@ import type { z } from 'zod';
 import type {
     AgentToolApprovalClassSchema,
     AgentToolDefinitionSchema,
+    AppApiKeyCollectionParamsSchema,
     AppBuildProgressSchema,
     AppBuildProgressStatusSchema,
     AppBuildTriggerSchema,
+    AppDeleteSummarySchema,
     AppDevelopmentTaskDetailsSchema,
     AppDevelopmentTaskListSchema,
     AppDevelopmentTaskSchema,
@@ -40,6 +42,7 @@ import type {
     AppVersionTargetSchema,
     AppVersionUrlsSchema,
     DeleteAppVersionResponseSchema,
+    McpApiKeyCredentialSchema,
     OAuthClientCredentialsSchema,
     StartAppBuildRequestSchema,
     StartAppBuildResponseSchema,
@@ -51,11 +54,16 @@ import type {
     ValidateUrlResponseSchema,
 } from './api-schemas/app-lifecycle.js';
 import type {
+    AppEventHookDeliverySchema,
+    AppEventHookPayloadSchema,
+    AppEventSubscriptionDefinitionSchema,
     AppInstallationListEntrySchema,
     AppInstallationSchema,
     AppInstallationWithManifestSchema,
     AppManifestDataSchema,
     AppManifestSchema,
+    AppPackageEventHookSchema,
+    AppPackageHooksSchema,
     AppPackageSchema,
     AppWidgetInfoSchema,
     CompositeAppCardOverridesSchema,
@@ -86,9 +94,11 @@ import type {
     AppManifestSourceSchema,
     AppSourceConfigSchema,
     AppUIConfigSchema,
+    MCPApiKeyConfigSchema,
     MCPOAuthConfigSchema,
     MCPToolAnnotationsSchema,
     MCPToolCollectionObjectSchema,
+    McpApiKeyStatusSchema,
     McpOAuthConnectResponseSchema,
     McpOAuthDisconnectResponseSchema,
     McpOAuthTokenRequestSchema,
@@ -96,6 +106,7 @@ import type {
     OAuthAuthorizeResponseSchema,
     OAuthAuthStatusSchema,
     OAuthMetadataResponseSchema,
+    SetMcpApiKeyRequestSchema,
     ToolCollectionAuthTypeSchema,
     ToolCollectionObjectSchema,
     VertesiaSDKToolCollectionObjectSchema,
@@ -162,6 +173,9 @@ export type ToolCollectionType = 'mcp' | 'vertesia_sdk';
 
 export type MCPOAuthConfig = z.infer<typeof MCPOAuthConfigSchema>;
 
+/** Install-time provisioning blueprint for an `auth: 'api_key'` MCP collection. Never holds the key. */
+export type MCPApiKeyConfig = z.infer<typeof MCPApiKeyConfigSchema>;
+
 export type MCPToolCollectionObject = z.infer<typeof MCPToolCollectionObjectSchema>;
 
 export type VertesiaSDKToolCollectionObject = z.infer<typeof VertesiaSDKToolCollectionObjectSchema>;
@@ -296,6 +310,8 @@ export const APP_ARTIFACT_TYPES = [
     'dashboard',
     'activity',
     'tool',
+    'hook',
+    'subscription',
 ] as const;
 
 export type AppArtifactType = (typeof APP_ARTIFACT_TYPES)[number];
@@ -304,7 +320,7 @@ export type AppArtifactType = (typeof APP_ARTIFACT_TYPES)[number];
  * A single platform artifact the App Solution Architect requires the build to create.
  * `id` is the app-owned in-code id the implementation must register and reference
  * (e.g. `app:<name>:main:extract-item` for interactions/agents, `app:<name>:<type>` for
- * types, `app:<name>:<process>` for processes).
+ * types, `app:<name>:<process>` for processes, and `app:<name>:<local-id>` for hooks/subscriptions).
  */
 /**
  * Build progress for one artifact, maintained by the developer agent as a living checklist:
@@ -337,10 +353,10 @@ export interface AppPlannedArtifact {
 
 /**
  * Structured result the App Solution Architect emits alongside its prose artifacts — the
- * machine-readable contract for the build. The implementation MUST create and successfully
- * exercise every required artifact before building a deployable version. Persisted into the app repo as
- * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the version-build
- * capability gate can verify against it deterministically. If the builder finds the plan
+ * machine-readable contract for the build. The implementation MUST register every required artifact
+ * before building a candidate, then successfully exercise it after that candidate is installed and
+ * version-pinned. Persisted into the app repo as {@link APP_CAPABILITY_MANIFEST_PATH} so it survives
+ * across runs and the package-registration gate can verify it deterministically. If the builder finds the plan
  * wrong or insufficient, the orchestrator relaunches the architect to revise the manifest;
  * the gate always checks against the latest committed copy.
  */
@@ -600,10 +616,17 @@ export const APP_PACKAGE_SCOPES = [
     'settings',
     'widgets',
     'activities',
+    'hooks',
+    'subscriptions',
     'all',
 ] as const;
 
 export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
+export type AppPackageEventHook = z.infer<typeof AppPackageEventHookSchema>;
+export type AppPackageHooks = z.infer<typeof AppPackageHooksSchema>;
+export type AppEventHookDelivery = z.infer<typeof AppEventHookDeliverySchema>;
+export type AppEventHookPayload = z.infer<typeof AppEventHookPayloadSchema>;
+export type AppEventSubscriptionDefinition = z.infer<typeof AppEventSubscriptionDefinitionSchema>;
 export type AppPackage = z.infer<typeof AppPackageSchema>;
 
 /**
@@ -663,6 +686,12 @@ export interface OrphanedAppInstallation extends Omit<AppInstallation, 'manifest
 export type OAuthClientCredentials = z.infer<typeof OAuthClientCredentialsSchema>;
 
 export type AppOAuthCollectionParams = z.infer<typeof AppOAuthCollectionParamsSchema>;
+
+/** One installer-supplied MCP API key. */
+export type McpApiKeyCredential = z.infer<typeof McpApiKeyCredentialSchema>;
+
+/** Installer-supplied MCP API keys, keyed by collection id. */
+export type AppApiKeyCollectionParams = z.infer<typeof AppApiKeyCollectionParamsSchema>;
 export type AppOAuthProviderParams = z.infer<typeof AppOAuthProviderParamsSchema>;
 
 export type AppInstallationPayload = z.infer<typeof AppInstallationPayloadSchema>;
@@ -697,6 +726,15 @@ export interface McpOAuthCollectionRef {
     collection_id: string;
 }
 
+/**
+ * Payload for storing the static bearer token of an `auth: 'api_key'` MCP collection.
+ * The key is write-only — it is never echoed back by any endpoint.
+ */
+export type SetMcpApiKeyRequest = z.infer<typeof SetMcpApiKeyRequestSchema>;
+
+/** Whether an `auth: 'api_key'` MCP collection has a key stored, plus a display-only hint. */
+export type McpApiKeyStatus = z.infer<typeof McpApiKeyStatusSchema>;
+
 export type McpOAuthTokenRequest = z.infer<typeof McpOAuthTokenRequestSchema>;
 
 export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponseSchema>;
@@ -873,15 +911,11 @@ export type ValidateUrlResponse = z.infer<typeof ValidateUrlResponseSchema>;
  * Result of DELETE /api/v1/apps/:id. With `?confirm=true` the cascade runs and
  * `deleted: true` is set; without it the endpoint returns a dry-run summary so
  * the UI can show what would be removed.
+ *
+ * Inferred from the published component rather than hand-written: the endpoint
+ * had been declaring `CountResult`, so response validation reported a missing
+ * `count` and every field here as unexpected — and in local development, where
+ * the check fails closed, that surfaced as a 500 raised AFTER the app was
+ * already deleted. Deriving the type is what keeps the two from drifting again.
  */
-export interface AppDeleteSummary {
-    confirmed: boolean;
-    app_id: string;
-    app_name: string;
-    versions: number;
-    installations: number;
-    storage_prefix: string;
-    git_repo_url?: string;
-    deleted: boolean;
-    warnings: string[];
-}
+export type AppDeleteSummary = z.infer<typeof AppDeleteSummarySchema>;

package/src/index.ts

@@ -75,6 +75,7 @@ export type {
     ZenoBulkContentObjectExportSplitShardRequest,
     ZenoBulkContentObjectExportSplitShardResponse,
 } from './store/store.js';
+export * from './sts-errors.js';
 export * from './sts-token-types.js';
 export * from './tenant.js';
 export * from './tool-execution.js';

package/src/platform-event-validation.test.ts

@@ -63,6 +63,32 @@ describe('event subscription input validation', () => {
         expect(result.errors.join(' ')).toContain('timeout_ms');
     });
 
+    it('accepts a fully resolved app hook target', () => {
+        const result = getCreateEventSubscriptionValidationResult(
+            validCreate({
+                target: {
+                    type: 'app',
+                    app_id: 'content-app',
+                    installation_id: 'installation-1',
+                    hook: 'content-updated',
+                    url: 'https://gateway.example/apps/content-app/api/hooks/content-updated',
+                },
+            }),
+        );
+        expect(result.valid).toBe(true);
+    });
+
+    it('requires app hook identity and URL fields', () => {
+        const result = getCreateEventSubscriptionValidationResult(
+            validCreate({ target: { type: 'app', app_id: '', installation_id: '', hook: '', url: '' } }),
+        );
+        expect(result.valid).toBe(false);
+        expect(result.errors.join(' ')).toContain('app_id');
+        expect(result.errors.join(' ')).toContain('installation_id');
+        expect(result.errors.join(' ')).toContain('hook');
+        expect(result.errors.join(' ')).toContain('url');
+    });
+
     it('requires endpoint for workflow targets', () => {
         const result = getCreateEventSubscriptionValidationResult(
             validCreate({ target: { type: 'workflow' } as never }),

package/src/platform-event-validation.ts

@@ -163,8 +163,8 @@ function validateTarget(target: unknown, errors: string[]): void {
         return;
     }
     const type = target.type;
-    if (type !== 'workflow' && type !== 'webhook' && type !== 'agent' && type !== 'process') {
-        errors.push('target.type must be one of workflow, webhook, agent, process');
+    if (type !== 'workflow' && type !== 'webhook' && type !== 'app' && type !== 'agent' && type !== 'process') {
+        errors.push('target.type must be one of workflow, webhook, app, agent, process');
         return;
     }
     const t = target as EventDeliveryTargetInput;
@@ -204,6 +204,19 @@ function validateTarget(target: unknown, errors: string[]): void {
             }
             break;
         }
+        case 'app': {
+            for (const field of ['app_id', 'installation_id', 'hook', 'url'] as const) {
+                if (typeof t[field] !== 'string' || t[field].length === 0) {
+                    errors.push(`app target requires a non-empty "${field}"`);
+                }
+            }
+            if (t.timeout_ms !== undefined) {
+                if (!Number.isInteger(t.timeout_ms) || t.timeout_ms <= 0 || t.timeout_ms > MAX_WEBHOOK_TIMEOUT_MS) {
+                    errors.push(`app target.timeout_ms must be an integer between 1 and ${MAX_WEBHOOK_TIMEOUT_MS}`);
+                }
+            }
+            break;
+        }
         case 'process':
             if ((typeof t.process_ref !== 'string' || t.process_ref.length === 0) && !isRecord(t.process_definition)) {
                 errors.push('process target requires "process_ref" or an inline "process_definition"');

package/src/platform-event.ts

@@ -5,6 +5,10 @@ import type {
     AgentDeliveryMatchModeSchema,
     AgentEventDeliveryTargetSchema,
     AgentSemanticEvaluatorSchema,
+    AppEventDeliveryTargetInputSchema,
+    AppEventDeliveryTargetSchema,
+    CancelEventDeliveryIntentsPayloadSchema,
+    CancelEventDeliveryIntentsResponseSchema,
     CreateEventIngestChannelPayloadSchema,
     EventDeliveryIntentStatusSchema,
     EventDeliveryIntentSummarySchema,
@@ -217,6 +221,8 @@ export type WorkflowEventDeliveryTarget = z.infer<typeof WorkflowEventDeliveryTa
 
 export type WebhookEventDeliveryTarget = z.infer<typeof WebhookEventDeliveryTargetSchema>;
 
+export type AppEventDeliveryTarget = z.infer<typeof AppEventDeliveryTargetSchema>;
+
 export const DEFAULT_EVENT_AGENT_INTERACTION_REF = 'sys:GeneralAgent';
 
 export type AgentDeliveryMatchMode = z.infer<typeof AgentDeliveryMatchModeSchema>;
@@ -242,6 +248,7 @@ export interface ProcessEventDeliveryTarget {
 export type EventDeliveryTarget =
     | WorkflowEventDeliveryTarget
     | WebhookEventDeliveryTarget
+    | AppEventDeliveryTarget
     | AgentEventDeliveryTarget
     | ProcessEventDeliveryTarget;
 
@@ -254,9 +261,12 @@ export type WorkflowEventDeliveryTargetInput = z.infer<typeof WorkflowEventDeliv
 
 export type WebhookEventDeliveryTargetInput = z.infer<typeof WebhookEventDeliveryTargetInputSchema>;
 
+export type AppEventDeliveryTargetInput = z.infer<typeof AppEventDeliveryTargetInputSchema>;
+
 export type EventDeliveryTargetInput =
     | WorkflowEventDeliveryTargetInput
     | WebhookEventDeliveryTargetInput
+    | AppEventDeliveryTargetInput
     | AgentEventDeliveryTarget
     | ProcessEventDeliveryTarget;
 
@@ -284,6 +294,9 @@ export interface EventSubscription {
     protected: boolean;
     enabled: boolean;
     priority?: EventPriority;
+    app_installation_id?: string;
+    app_id?: string;
+    app_subscription_id?: string;
     created_by?: string;
     updated_by?: string;
     created_at?: string;
@@ -387,6 +400,32 @@ export interface ListEventSubscriptionsQuery {
     scope?: ('account' | 'project')[];
     sort_by?: EventSubscriptionSortField;
     sort_order?: 'asc' | 'desc';
+    app_installation_id?: string;
+}
+
+/** Trusted Studio -> Zeno request used to provision subscriptions declared by an installed app. */
+export interface ProvisionAppEventSubscriptionsRequest {
+    account_id: string;
+    project_id: string;
+    subscriptions: Array<
+        CreateEventSubscriptionPayload & {
+            target: AppEventDeliveryTargetInput;
+            app_installation_id: string;
+            app_id: string;
+            app_subscription_id: string;
+        }
+    >;
+}
+
+/** Trusted Studio -> Zeno request used to remove every subscription owned by an app installation. */
+export interface RemoveAppEventSubscriptionsRequest {
+    account_id: string;
+    project_id: string;
+    app_installation_id: string;
+}
+
+export interface AppEventSubscriptionsMutationResponse {
+    subscription_ids: string[];
 }
 
 export type EventIngestChannelSortField = 'name' | 'source' | 'enabled' | 'updated_at';
@@ -410,6 +449,10 @@ export type EventDeliveryQueueSubscriptionSummary = z.infer<typeof EventDelivery
 
 export type EventDeliveryQueueSummaryResponse = z.infer<typeof EventDeliveryQueueSummaryResponseSchema>;
 
+export type CancelEventDeliveryIntentsPayload = z.infer<typeof CancelEventDeliveryIntentsPayloadSchema>;
+
+export type CancelEventDeliveryIntentsResponse = z.infer<typeof CancelEventDeliveryIntentsResponseSchema>;
+
 export interface PublishPlatformEventPayload {
     event: PlatformEvent;
     priority?: EventPriority;

package/src/store/intake-policy-schema.generated.ts

@@ -273,6 +273,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -345,6 +348,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -371,6 +377,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -433,6 +442,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -515,6 +527,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                     type: 'string',
                     enum: ['low', 'high', 'auto'],
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -541,6 +556,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -567,6 +585,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -1169,6 +1190,12 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                 max_tokens: {
                     type: 'number',
                 },
+                effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
+                reasoning_effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
                 temperature: {
                     type: 'number',
                 },
@@ -1191,6 +1218,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                     type: 'string',
                     enum: ['low', 'high', 'auto'],
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -1221,6 +1251,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                     type: 'string',
                     enum: ['low', 'high', 'auto'],
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,
@@ -1264,6 +1297,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                include_thoughts: {
+                    type: 'boolean',
+                },
             },
             required: ['_option_id'],
             additionalProperties: false,

package/src/store/workflow.ts

@@ -737,6 +737,15 @@ export enum FileProcessingStatus {
 
 export type ConversationFile = z.infer<typeof ConversationFileSchema>;
 
+/**
+ * A file is deliverable when it is ready and has not yet been delivered to the agent as part
+ * of a user message. Deliverable files get attached to the next message; consumed ones stay
+ * reachable to tools via artifact_path/md_path but are not re-attached.
+ */
+export function isDeliverableFile(file: ConversationFile): boolean {
+    return file.status === FileProcessingStatus.READY && !file.consumed_at;
+}
+
 /**
  * Details for file processing SYSTEM messages.
  * Used when type is AgentMessageType.SYSTEM with system_type: 'file_processing'.

package/src/sts-errors.ts

@@ -0,0 +1,13 @@
+export const REQUESTED_SCOPE_UNAVAILABLE_ERROR_CODE = 'requested_scope_unavailable';
+export const NO_ACCESSIBLE_ACCOUNT_ERROR_CODE = 'no_accessible_account';
+export const RESTRICTED_ENVIRONMENT_ERROR_CODE = 'restricted_environment';
+export const TOKEN_ISSUANCE_FORBIDDEN_ERROR_CODE = 'token_issuance_forbidden';
+
+export const ISSUE_TOKEN_FORBIDDEN_ERROR_CODES = [
+    REQUESTED_SCOPE_UNAVAILABLE_ERROR_CODE,
+    NO_ACCESSIBLE_ACCOUNT_ERROR_CODE,
+    RESTRICTED_ENVIRONMENT_ERROR_CODE,
+    TOKEN_ISSUANCE_FORBIDDEN_ERROR_CODE,
+] as const;
+
+export type IssueTokenForbiddenErrorCode = (typeof ISSUE_TOKEN_FORBIDDEN_ERROR_CODES)[number];

package/src/sts-token-types.ts

@@ -7,6 +7,7 @@ import type {
     AgentTokenRequestSchema,
     ApiKeyTokenRequestSchema,
     EnvironmentTokenRequestSchema,
+    IssueTokenForbiddenResponseSchema,
     IssueTokenRequestSchema,
     IssueTokenResponseSchema,
     ProjectTokenRequestSchema,
@@ -91,6 +92,7 @@ export interface TokenResponse {
 }
 
 export type IssueTokenResponse = z.infer<typeof IssueTokenResponseSchema>;
+export type IssueTokenForbiddenResponse = z.infer<typeof IssueTokenForbiddenResponseSchema>;
 
 export interface ValidateTokenResponse {
     valid: boolean;

package/src/user.ts

@@ -59,7 +59,7 @@ export const EARLY_ACCESS_ANNOTATION = 'early-access';
  * restricted (`preview`/`preprod`) environment because they lack the {@link EARLY_ACCESS_ANNOTATION}
  * annotation. The UI keys its dedicated rejection screen off this code.
  */
-export const RESTRICTED_ENVIRONMENT_ERROR_CODE = 'restricted_environment';
+export { RESTRICTED_ENVIRONMENT_ERROR_CODE } from './sts-errors.js';
 
 /**
  * The account as it crosses the wire.

package/src/versions.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { ApiVersions, CURRENT_API_VERSION, CURRENT_API_VERSION_HEADER_VALUE } from './versions.js';
+
+describe('API versions', () => {
+    it('keeps the current API version aligned with the latest milestone', () => {
+        const milestones = Object.values(ApiVersions).filter(
+            (version): version is number => typeof version === 'number',
+        );
+
+        expect(CURRENT_API_VERSION).toBe(Math.max(...milestones));
+        expect(CURRENT_API_VERSION_HEADER_VALUE).toBe(String(CURRENT_API_VERSION));
+    });
+});

package/src/versions.ts

@@ -27,3 +27,15 @@ export enum ApiVersions {
      */
     REQUEST_CONTRACT_ENFORCEMENT_V1 = 20260803,
 }
+
+/**
+ * The API version used by current clients and published as the current OpenAPI shape.
+ *
+ * Keep this explicit rather than deriving it at runtime: promoting a milestone to the client
+ * default is a deliberate compatibility decision. The versions test ensures this alias is
+ * reconsidered whenever a newer milestone is added.
+ */
+export const CURRENT_API_VERSION = ApiVersions.REQUEST_CONTRACT_ENFORCEMENT_V1;
+
+/** The current API version formatted for the {@link VERSION_HEADER} wire value. */
+export const CURRENT_API_VERSION_HEADER_VALUE = String(CURRENT_API_VERSION);

package/src/workflow-analytics.ts

@@ -114,11 +114,18 @@ export interface AgentRunCompletedEvent extends BaseAgentEvent {
     totalToolCalls: number;
     /** Total LLM calls made */
     totalLlmCalls: number;
-    /** Cumulative token usage */
-    totalTokens?: {
+    /**
+     * Cumulative token usage breakdown for the run.
+     *
+     * No `totalTokens` (and no `total` here): an input+output sum mixes
+     * differently-priced quantities and nothing consumes it — token analytics
+     * aggregate the per-call LlmCallEvent fields. This also keeps
+     * `$.totalTokens` scalar-only in the telemetry `event_data` column
+     * (LlmCallEvent is the only current producer of that path).
+     */
+    tokenUsage?: {
         input: number;
         output: number;
-        total: number;
     };
     /** If conversation was ended via end_conversation tool */
     endConversation?: {