@vertesia/common 1.6.0-dev.20260923.085325Z → 1.6.0-dev.20261008.064737Z

package/src/api-schemas/access-control.ts

@@ -8,6 +8,7 @@ import {
     Permission,
     RoleDomains,
 } from '../access-control-values.js';
+import type * as Wire from '../wire-types.generated.js';
 
 /**
  * Runtime API schemas for IAM roles and access-control entries.
@@ -34,8 +35,9 @@ export const RoleDomainSchema = z.enum(RoleDomains).meta({
     description:
         'Logical grouping of roles by the service area that owns them. One domain may declare roles ' +
         'applicable to multiple scopes (e.g. the `content` domain owns roles applicable to both `document` ' +
-        'and `collection` scopes). The `system` domain owns the built-in foundational roles (currently ' +
-        'exposed as `SystemRoles`) — registered first so domain partitions cannot shadow them.',
+        'and `collection` scopes, while `agent_runs` owns the `agent_run` scope). The `system` domain ' +
+        'owns the built-in foundational roles (currently exposed as `SystemRoles`) — registered first so ' +
+        'domain partitions cannot shadow them.',
 });
 
 /**
@@ -72,7 +74,7 @@ export const AceConditionsSchema = z
         scope: AbacScopeSchema.meta({
             description:
                 "Kind of object the `resource_props` matches. Used to disambiguate which partition's roles " +
-                'apply (e.g. content roles vs task roles) and to form the JWT `content_security` key prefix ' +
+                'apply (e.g. content roles vs agent-run roles) and to form the JWT `content_security` key prefix ' +
                 "(`{scope}:{verb}`). Absent → `'document'` (default; emits bare `read`/`write`/`delete` keys " +
                 'for backward compatibility).',
         }).optional(),
@@ -104,9 +106,9 @@ export const AccessControlEntrySchema = z
         role: z.string().meta({
             description:
                 'Role name. Typed as `string` because role names now span multiple partitions: `SystemRoles` ' +
-                "enum values for system-domain roles, and bare strings for ABAC-domain roles (e.g. `'content:reader'`, " +
-                "`'content:writer'`, `'content:manager'`). Mongoose schema validates the value against the " +
-                'registered role catalog via `getAllRoleNames()`.',
+                'enum values for system-domain roles, and bare strings for ABAC-domain roles (e.g. ' +
+                "`'content:reader'`, `'content:writer'`, `'content:manager'`, `'agent_runs:reader'`). Mongoose " +
+                'schema validates the value against the registered role catalog via `getAllRoleNames()`.',
         }),
         resource_type: AccessControlResourceTypeSchema,
         resource: z.string(),
@@ -196,13 +198,13 @@ export const SystemRoleDefinitionArraySchema = z
  * The public access-control types, inferred rather than written. `../access-control.ts` and
  * `../roles/types.ts` re-export these under their public names.
  */
-export type PropertyConditionsFromSchema = z.infer<typeof PropertyConditionsSchema>;
-export type AceConditionsFromSchema = z.infer<typeof AceConditionsSchema>;
-export type AccessControlEntryFromSchema = z.infer<typeof AccessControlEntrySchema>;
-export type AccessControlEntryArrayFromSchema = z.infer<typeof AccessControlEntryArraySchema>;
-export type ACECreatePayloadFromSchema = z.infer<typeof ACECreatePayloadSchema>;
-export type ACEUpdatePayloadFromSchema = z.infer<typeof ACEUpdatePayloadSchema>;
-export type RoleDefinitionFromSchema = z.infer<typeof RoleDefinitionSchema>;
-export type RoleDefinitionArrayFromSchema = z.infer<typeof RoleDefinitionArraySchema>;
-export type SystemRoleDefinitionFromSchema = z.infer<typeof SystemRoleDefinitionSchema>;
-export type SystemRoleDefinitionArrayFromSchema = z.infer<typeof SystemRoleDefinitionArraySchema>;
+export type PropertyConditionsFromSchema = Wire.PropertyConditionsFromSchema;
+export type AceConditionsFromSchema = Wire.AceConditionsFromSchema;
+export type AccessControlEntryFromSchema = Wire.AccessControlEntryFromSchema;
+export type AccessControlEntryArrayFromSchema = Wire.AccessControlEntryArrayFromSchema;
+export type ACECreatePayloadFromSchema = Wire.ACECreatePayloadFromSchema;
+export type ACEUpdatePayloadFromSchema = Wire.ACEUpdatePayloadFromSchema;
+export type RoleDefinitionFromSchema = Wire.RoleDefinitionFromSchema;
+export type RoleDefinitionArrayFromSchema = Wire.RoleDefinitionArrayFromSchema;
+export type SystemRoleDefinitionFromSchema = Wire.SystemRoleDefinitionFromSchema;
+export type SystemRoleDefinitionArrayFromSchema = Wire.SystemRoleDefinitionArrayFromSchema;

package/src/api-schemas/account.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 // From the values module, never from `user.ts`: `user.ts` derives its public types from the schemas
 // below, so importing it here would invert the dependency and make the source of truth circular.
 import { ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH, AccountType, BillingMethod, QuotaTier } from '../account-values.js';
-import { ApiVersions } from '../versions.js';
+import type * as Wire from '../wire-types.generated.js';
 
 /**
  * Runtime API schemas for the Accounts endpoints.
@@ -141,14 +141,7 @@ export const StripeBillingStatusResponseSchema = z
     .discriminatedUnion('status', [StripeBillingEnabledSchema, StripeBillingDisabledSchema])
     .meta({ id: 'StripeBillingStatusResponse' });
 
-export type AccountBillingFromSchema = z.infer<typeof AccountBillingSchema>;
-export type AccountFromSchema = z.infer<typeof AccountSchema>;
-export type UpdateAccountPayloadFromSchema = z.infer<typeof UpdateAccountPayloadSchema>;
-export type StripeBillingStatusResponseFromSchema = z.infer<typeof StripeBillingStatusResponseSchema>;
-
-/** Account-wide defaults for request API version negotiation. */
-export const AccountApiVersionPolicySchema = z
-    .strictObject({
-        default_api_version: z.enum(ApiVersions).optional(),
-    })
-    .meta({ id: 'AccountApiVersionPolicy' });
+export type AccountBillingFromSchema = Wire.AccountBillingFromSchema;
+export type AccountFromSchema = Wire.AccountFromSchema;
+export type UpdateAccountPayloadFromSchema = Wire.UpdateAccountPayloadFromSchema;
+export type StripeBillingStatusResponseFromSchema = Wire.StripeBillingStatusResponseFromSchema;

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+
+export const AgentBudgetConfigurationSchema = z
+    .strictObject({
+        mode: z.enum(['token', 'dollar']).optional().meta({
+            description: 'Run budget mode. An omitted mode preserves weighted-token budgeting.',
+        }),
+        limit_usd: z
+            .number()
+            .positive()
+            .max(Number.MAX_SAFE_INTEGER / 1e9)
+            .optional()
+            .meta({
+                description:
+                    'Soft USD allowance for priced model calls; dollar mode also requires limit_tokens for unpriced calls.',
+            }),
+        reminder_at_remaining_fractions: z.array(z.number().positive().lt(1)).optional(),
+        limit_tokens: z
+            .number()
+            .optional()
+            .meta({
+                description:
+                    'Weighted token budget shared by the run and every subagent workstream it launches. When the ' +
+                    'run and its workstreams together use this many weighted tokens, the agent gets one final ' +
+                    'turn without tools to summarize its work, and the run ends. This is a soft limit, not a ' +
+                    'spending cap: workstreams running concurrently and the final summary turns can go over ' +
+                    'it. Unset or <=0 means no budget.',
+            }),
+        reminder_at_remaining_tokens: z
+            .array(z.number())
+            .optional()
+            .meta({
+                description:
+                    'Remaining-budget thresholds, in weighted tokens, at which the agent is told how much budget ' +
+                    'is left. Each threshold is delivered once per context window (again after a checkpoint). ' +
+                    'Values outside (0, limit_tokens) are ignored. Unset means reminders at 25% and 10% remaining.',
+            }),
+        output_token_weight: z.number().min(0).optional().meta({
+            description: 'Weight applied to output tokens, reasoning included, when charging the budget. Default 5.',
+        }),
+        input_token_weight: z.number().min(0).optional().meta({
+            description: 'Weight applied to input tokens not read from the prompt cache. Default 1.',
+        }),
+        cached_input_token_weight: z
+            .number()
+            .min(0)
+            .optional()
+            .meta({
+                description:
+                    'Weight applied to input tokens read from the prompt cache. Default 0.1, so a long conversation ' +
+                    'that mostly re-reads cached context is charged a tenth of the uncached rate for it.',
+            }),
+    })
+    .meta({
+        id: 'AgentBudgetConfiguration',
+        description:
+            'Weighted token budget for an agent run and its subagent workstreams. A call is charged ' +
+            'output × output_token_weight + uncached input × input_token_weight + cached input × ' +
+            'cached_input_token_weight.',
+    });

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

@@ -16,6 +16,7 @@ import {
     RunTypeSchema,
 } from './app-lifecycle.js';
 import {
+    AgentEvaluateRequestSchema,
     AgentResourceReferenceSchema,
     AgentSearchScopeSchema,
     AgentToolApprovalModeSchema,
@@ -34,7 +35,7 @@ import {
     ProcessStateSchema,
     RecordProcessRunPayloadSchema,
 } from './process.js';
-import { AgentCheckpointConfigurationSchema } from './project-configuration.js';
+import { AgentBudgetConfigurationSchema, AgentCheckpointConfigurationSchema } from './project-configuration.js';
 import { nullableStringSchema } from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema } from './store.js';
 
@@ -91,17 +92,17 @@ const TelemetryProducerSchema = z.strictObject({
     version: z.string(),
 });
 
-export const JudgeGateReasonSchema = z
-    .enum(['signal', 'sample'])
-    .meta({ id: 'JudgeGateReason', description: 'Why the judge looked at a run.' });
+export const EvaluationGateReasonSchema = z
+    .enum(['signal', 'sample', 'opt_in', 'always_on'])
+    .meta({ id: 'EvaluationGateReason', description: 'Why a run was selected for LLM evaluation.' });
 
-export const JudgeOutcomeSchema = z
-    .enum(['judged', 'skipped_unarchived', 'failed'])
-    .meta({ id: 'JudgeOutcome', description: 'What a judge run produced.' });
+export const EvaluationOutcomeSchema = z
+    .enum(['evaluated', 'skipped_unarchived', 'failed'])
+    .meta({ id: 'EvaluationOutcome', description: 'Outcome of an LLM evaluation run.' });
 
-export const JudgeVerdictSchema = z
+export const EvaluationVerdictSchema = z
     .enum(['success', 'partial', 'failure'])
-    .meta({ id: 'JudgeVerdict', description: "The judge's reading of a turn." });
+    .meta({ id: 'EvaluationVerdict', description: 'LLM evaluation verdict for a turn.' });
 
 // ----------------------------------------------------------------------------
 // User feedback
@@ -225,7 +226,7 @@ const AgentRunEvaluationTotalsSchema = z.strictObject({
 
 /**
  * What the workflow reports about a run: the fold of its turn evaluations. Owned by the workflow;
- * it never carries feedback or judge fields, which the server owns.
+ * it never carries feedback or evaluator fields, which the server owns.
  */
 export const AgentRunEvaluationRollupSchema = z
     .strictObject({
@@ -245,36 +246,36 @@ export const AgentRunEvaluationRollupSchema = z
     })
     .meta({ id: 'AgentRunEvaluationRollup', description: 'Fold of the turn evaluations of a run.' });
 
-export const AgentRunJudgeResultSchema = z
+export const AgentRunLlmEvaluationResultSchema = z
     .strictObject({
         rev: z.number().int(),
-        gate: JudgeGateReasonSchema,
+        gate: EvaluationGateReasonSchema,
         sample_rate: z.number(),
         selected_probability: z.number(),
-        outcome: JudgeOutcomeSchema,
-        verdict: JudgeVerdictSchema.optional(),
+        outcome: EvaluationOutcomeSchema,
+        verdict: EvaluationVerdictSchema.optional(),
         score: z.number().optional(),
         model: z.string().optional(),
         prompt_version: z.string(),
-        turns_judged: z.array(z.number().int()).optional(),
-        judged_at: z.string().meta({ format: 'date-time' }),
+        turns_evaluated: z.array(z.number().int()).optional(),
+        evaluated_at: z.string().meta({ format: 'date-time' }),
     })
-    .meta({ id: 'AgentRunJudgeResult', description: 'Latest judge result for a run.' });
+    .meta({ id: 'AgentRunLlmEvaluationResult', description: 'Latest LLM evaluation result for a run.' });
 
 export const AgentRunContradictionReasonSchema = z
-    .enum(['feedback_down_on_clean_run', 'judge_failure_on_clean_run'])
+    .enum(['feedback_down_on_clean_run', 'evaluation_failure_on_clean_run'])
     .meta({ id: 'AgentRunContradictionReason' });
 
 /**
  * The server-owned evaluation summary of a run: the workflow rollup, the feedback counts and the
- * judge result, plus the derived severity, flags and contradiction the run list filters on.
+ * evaluator result, plus the derived severity, flags and contradiction the run list filters on.
  */
 export const AgentRunEvaluationSchema = z
     .strictObject({
         rev: z.number().int().meta({ description: 'Bumped on every change to any part of the summary.' }),
         rollup: AgentRunEvaluationRollupSchema.optional(),
         feedback_counts: AgentRunFeedbackCountsSchema.optional(),
-        judge: AgentRunJudgeResultSchema.optional(),
+        llm_evaluation: AgentRunLlmEvaluationResultSchema.optional(),
         severity: EvaluationSeveritySchema,
         flags: z.array(TurnEvaluationFlagSchema),
         contradicted: z.boolean(),
@@ -350,6 +351,7 @@ const LlmCallEventSchema = z.strictObject({
     callType: z.enum(LlmCallType),
     attemptNumber: z.number().optional(),
     errorType: z.string().optional(),
+    executionRunId: z.string().optional(),
     // `NestedInteractionEvent` — an interaction executed from inside a tool — is an `LlmCallEvent`
     // with three more fields and the same `eventType`, so it cannot be a branch of its own and has to
     // widen this one. They are optional because a plain LLM call carries none of them; the three
@@ -452,17 +454,17 @@ const FeedbackEventSchema = z.strictObject({
     replaced: z.boolean(),
 });
 
-const TurnJudgementEventSchema = z.strictObject({
+const TurnLlmEvaluationEventSchema = z.strictObject({
     ...agentEventBase,
-    eventType: z.literal(AgentEventType.TurnJudgement),
+    eventType: z.literal(AgentEventType.TurnLlmEvaluation),
     evaluationRev: z.number().int(),
     workstreamId: z.string(),
     turnSeq: z.number().int().min(0),
-    gate: JudgeGateReasonSchema,
+    gate: EvaluationGateReasonSchema,
     sampleRate: z.number(),
     selectedProbability: z.number(),
-    outcome: JudgeOutcomeSchema,
-    verdict: JudgeVerdictSchema.optional(),
+    outcome: EvaluationOutcomeSchema,
+    verdict: EvaluationVerdictSchema.optional(),
     score: z.number().optional(),
     reasons: z.array(z.string()).optional(),
     promptVersion: z.string(),
@@ -490,7 +492,7 @@ export const AgentEventSchema: z.ZodType<AgentEvent> = z
         ToolCallEventSchema,
         TurnEvaluationEventSchema,
         FeedbackEventSchema,
-        TurnJudgementEventSchema,
+        TurnLlmEvaluationEventSchema,
         StallBreakerEventSchema,
     ])
     .meta({ id: 'AgentEvent' });
@@ -614,6 +616,25 @@ export const AgentArtifactUrlResponseSchema = z
     })
     .meta({ id: 'AgentArtifactUrlResponse', description: 'Signed artifact URL response for agent artifacts.' });
 
+export const AllocateAgentRunBudgetPayloadSchema = z
+    .union([
+        z.strictObject({
+            additional_tokens: z
+                .number()
+                .int()
+                .positive()
+                .meta({ description: 'Weighted tokens to add to the run allowance.' }),
+        }),
+        z.strictObject({
+            additional_usd: z
+                .number()
+                .positive()
+                .max(Number.MAX_SAFE_INTEGER / 1e9)
+                .meta({ description: 'USD to add to the dollar allowance.' }),
+        }),
+    ])
+    .meta({ id: 'AllocateAgentRunBudgetPayload', description: 'Add exactly one allowance: weighted tokens or USD.' });
+
 export const SignalAgentResponseSchema = z
     .strictObject({
         status: z.string(),
@@ -781,6 +802,7 @@ export const AutonomousRunResponseSchema = z
             .array(z.string())
             .meta({ description: 'Lessons learned from the conversation (extracted at completion)' })
             .optional(),
+        evaluate: AgentEvaluateRequestSchema,
         evaluation: AgentRunEvaluationSchema.meta({ description: 'Evaluation summary of the run.' }).optional(),
         feedback: z
             .array(AgentRunFeedbackEntrySchema)
@@ -934,6 +956,7 @@ export const AgentRunSchema = z
             .array(z.string())
             .meta({ description: 'Lessons learned from the conversation (extracted at completion)' })
             .optional(),
+        evaluate: AgentEvaluateRequestSchema,
         evaluation: AgentRunEvaluationSchema.meta({ description: 'Evaluation summary of the run.' }).optional(),
         feedback: z
             .array(AgentRunFeedbackEntrySchema)
@@ -966,6 +989,7 @@ export const CreateAgentRunPayloadSchema = z
     .strictObject({
         interaction: z.string().meta({ description: 'Interaction ID or code (e.g. "sys:generic_question").' }),
         ...ConversationEnrichmentFields,
+        evaluate: AgentEvaluateRequestSchema,
         data: z.looseObject({}).meta({ description: 'Input parameters, typed per interaction' }).optional(),
         config: InteractionExecutionConfigurationSchema.meta({
             description: 'Execution configuration (environment, model, model_options, etc.)',
@@ -1040,7 +1064,18 @@ export const CreateAgentRunPayloadSchema = z
             description:
                 "Structured checkpoint override for this run. Field-wise it takes precedence over the interaction's `agent_runner_options.checkpoint` and the project's `configuration.agent.checkpoint`; the legacy `checkpoint_tokens` above still wins over everything when set.",
         }).optional(),
+        budget: AgentBudgetConfigurationSchema.meta({
+            description:
+                "Token budget for this run and its subagent workstreams. Field-wise it takes precedence over the interaction's `agent_runner_options.budget` and the project's `configuration.agent.budget`.",
+        }).optional(),
         max_iterations: z.number().meta({ description: 'Maximum conversation iterations (default: 20)' }).optional(),
+        final_verification: z
+            .boolean()
+            .meta({
+                description:
+                    'When true, a non-interactive free-form run takes one extra turn after its answer to check that the task is complete. Off by default. Not kept on restart or fork.',
+            })
+            .optional(),
         notify_endpoints: z.array(z.string()).meta({ description: 'Webhook URLs to notify on completion' }).optional(),
         debug_mode: z.boolean().meta({ description: 'Enable debug mode for verbose logging' }).optional(),
         started_by: z
@@ -1418,7 +1453,7 @@ export const ListAgentRunsQuerySchema = z
         }).optional(),
         contradicted: z
             .boolean()
-            .meta({ description: 'Only runs whose feedback or judge contradicts the detectors' })
+            .meta({ description: 'Only runs whose feedback or LLM evaluation contradicts the detectors' })
             .optional(),
     })
     .meta({ id: 'ListAgentRunsQuery' });
@@ -1473,6 +1508,7 @@ export const RecordAgentRunPayloadSchema = z
         run_kind: z.literal('agent').optional(),
         interaction: z.string(),
         ...ConversationEnrichmentFields,
+        evaluate: AgentEvaluateRequestSchema,
         parent_run_id: z.string().optional(),
         workstream_id: z.string().optional(),
         schedule_id: z.string().optional(),

package/src/api-schemas/apikey.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 // types from the schemas below, so importing them here would invert the dependency.
 import { ApiKeyTypes } from '../apikey-values.js';
 import { SystemRoles } from '../project-values.js';
+import type * as Wire from '../wire-types.generated.js';
 import { ProjectSchema } from './project.js';
 
 /**
@@ -197,16 +198,16 @@ export const DeleteOperationResultSchema = z
     })
     .meta({ id: 'DeleteOperationResult' });
 
-export type ApiKeyListQueryFromSchema = z.infer<typeof ApiKeyListQuerySchema>;
-export type ApiKeyReadQueryFromSchema = z.infer<typeof ApiKeyReadQuerySchema>;
-export type ProjectRefArrayFromSchema = z.infer<typeof ProjectRefArraySchema>;
-export type ApiKeyFromSchema = z.infer<typeof ApiKeySchema>;
-export type ApiKeyArrayFromSchema = z.infer<typeof ApiKeyArraySchema>;
-export type ApiKeyWithValueFromSchema = z.infer<typeof ApiKeyWithValueSchema>;
-export type ApiKeyReadResponseFromSchema = z.infer<typeof ApiKeyReadResponseSchema>;
-export type CreateApiKeyPayloadFromSchema = z.infer<typeof CreateApiKeyPayloadSchema>;
-export type UpdateApiKeyPayloadFromSchema = z.infer<typeof UpdateApiKeyPayloadSchema>;
-export type AuthTokenResponseFromSchema = z.infer<typeof AuthTokenResponseSchema>;
+export type ApiKeyListQueryFromSchema = Wire.ApiKeyListQueryFromSchema;
+export type ApiKeyReadQueryFromSchema = Wire.ApiKeyReadQueryFromSchema;
+export type ProjectRefArrayFromSchema = Wire.ProjectRefArrayFromSchema;
+export type ApiKeyFromSchema = Wire.ApiKeyFromSchema;
+export type ApiKeyArrayFromSchema = Wire.ApiKeyArrayFromSchema;
+export type ApiKeyWithValueFromSchema = Wire.ApiKeyWithValueFromSchema;
+export type ApiKeyReadResponseFromSchema = Wire.ApiKeyReadResponseFromSchema;
+export type CreateApiKeyPayloadFromSchema = Wire.CreateApiKeyPayloadFromSchema;
+export type UpdateApiKeyPayloadFromSchema = Wire.UpdateApiKeyPayloadFromSchema;
+export type AuthTokenResponseFromSchema = Wire.AuthTokenResponseFromSchema;
 
 /** Project-independent organization credentials, managed only by interactive administrators. */
 export const AccountApiKeySchema = ApiKeySchema.pick({

package/src/api-schemas/app-lifecycle.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { APPGEN_PACKAGE_SPEC_PATTERN } from '../appgen.js';
 import { AppAccessControlSchema, AppAvailableInSchema, MCPToolAnnotationsSchema } from './apps.js';
 import { EventCategorySchema } from './audit-trail.js';
+import { AgentBudgetConfigurationSchema } from './project-configuration.js';
 
 // The app lifecycle contracts: versions, builds, scaffolds, git repositories, development tasks,
 // installations and inspection. `./apps.js` holds the manifest itself and the tool-collection
@@ -442,6 +443,10 @@ export const StartAppDevelopmentTaskRequestSchema = z
             .boolean()
             .meta({ description: 'Create one immutable app version after validation. Defaults to false.' })
             .optional(),
+        budget: AgentBudgetConfigurationSchema.meta({
+            description:
+                "Token budget for the whole task, shared by the App Builder run and every step of its development process. Field-wise it overrides the project's `configuration.agent.budget`; `limit_tokens` <= 0 runs the task without a budget.",
+        }).optional(),
     })
     .meta({ id: 'StartAppDevelopmentTaskRequest' });
 

package/src/api-schemas/audit-trail.ts

@@ -39,6 +39,12 @@ export const AuditAggregationDimensionMapSchema = z
         event_category: z.string().nullable().optional(),
         provider: z.string().nullable().optional(),
         project_id: z.string().nullable().optional(),
+        principal_id: z.string().nullable().optional(),
+        actor_id: z.string().nullable().optional(),
+        user_id: z.string().nullable().optional().meta({
+            description:
+                'Originating user identity, including delegated and scheduled activity with a recorded user owner. Non-user principals without a user origin are excluded.',
+        }),
         'details.pipeline': z.string().nullable().optional(),
         'details.verdict': z.string().nullable().optional(),
         'details.workflow_type': z.string().nullable().optional(),
@@ -48,7 +54,7 @@ export const AuditAggregationDimensionMapSchema = z
     .meta({ id: 'AuditAggregationDimensionMap' });
 
 export const AuditAggregationDistinctFieldSchema = z
-    .enum(['resource_id', 'request_id'])
+    .enum(['resource_id', 'request_id', 'principal_id', 'actor_id', 'user_id'])
     .meta({ id: 'AuditAggregationDistinctField' });
 
 export const AuditAggregationOperationSchema = z
@@ -164,6 +170,10 @@ export const AuditAggregationFilterSchema = z
         resourceTypes: z.array(z.string()).optional(),
         eventCategories: z.array(EventCategorySchema).optional(),
         providers: z.array(z.string()).optional(),
+        principalTypes: z
+            .array(z.string())
+            .meta({ description: 'Restrict events to top-level actor categories such as user or apikey.' })
+            .optional(),
         success: z.boolean().optional(),
         details: z.array(AuditAggregationDetailFilterSchema).optional(),
     })
@@ -241,3 +251,167 @@ export const AuditTrailQuerySchema = z
         offset: z.number().meta({ description: 'Pagination: offset' }).optional(),
     })
     .meta({ id: 'AuditTrailQuery' });
+
+export const AuditAdoptionFilterSchema = z
+    .strictObject({
+        actions: z.array(AuditActionSchema).max(32).optional(),
+        resourceTypes: z.array(z.string().max(128)).max(16).optional(),
+        eventCategories: z.array(EventCategorySchema).max(6).optional(),
+    })
+    .meta({ id: 'AuditAdoptionFilter' });
+
+export const AuditAdoptionQuerySchema = z
+    .strictObject({
+        projectId: z.string().optional(),
+        from: z
+            .string()
+            .meta({ format: 'date-time', description: 'Inclusive start; defaults to 30 days before to.' })
+            .optional(),
+        to: z
+            .string()
+            .meta({ format: 'date-time', description: 'Exclusive end; defaults to now. Maximum duration: 366 days.' })
+            .optional(),
+        filter: AuditAdoptionFilterSchema.optional(),
+    })
+    .meta({
+        id: 'AuditAdoptionQuery',
+        description:
+            'Productive direct authenticated user activity, including user OAuth/MCP calls. Scope is enforced by the server.',
+    });
+
+export const AuditAdoptionPeriodSchema = z
+    .strictObject({
+        from: z.string().meta({ format: 'date-time' }),
+        to: z.string().meta({ format: 'date-time' }),
+    })
+    .meta({ id: 'AuditAdoptionPeriod' });
+
+export const AuditAdoptionBucketSchema = z
+    .strictObject({
+        from: z.string().meta({ format: 'date-time' }),
+        to: z.string().meta({ format: 'date-time' }),
+        partial: z.boolean(),
+        active_users: z.number().int().nonnegative(),
+    })
+    .meta({ id: 'AuditAdoptionBucket' });
+
+export const AuditAdoptionActiveDaysSchema = z
+    .strictObject({
+        days: z.number().int().min(1).max(367),
+        users: z.number().int().nonnegative(),
+    })
+    .meta({ id: 'AuditAdoptionActiveDays' });
+
+export const AuditAdoptionProjectSchema = z
+    .strictObject({
+        project_id: z.string(),
+        project_name: z.string().nullable(),
+        active_users: z.number().int().nonnegative(),
+        active_user_days: z.number().int().nonnegative(),
+    })
+    .meta({ id: 'AuditAdoptionProject' });
+
+export const AuditAdoptionHistorySchema = z
+    .strictObject({
+        earliest_observed_at: z.string().meta({ format: 'date-time' }).nullable(),
+        coverage_from: z
+            .string()
+            .meta({
+                format: 'date-time',
+                description:
+                    'Authoritative complete-history boundary, if known. Earliest observation is not a coverage boundary.',
+            })
+            .nullable(),
+        completeness: z.enum(['unknown', 'insufficient', 'verified']),
+        retention_unavailable_reason: z.enum(['no_previous_users', 'insufficient_history']).nullable(),
+    })
+    .meta({ id: 'AuditAdoptionHistory' });
+
+export const AuditAdoptionResponseSchema = z
+    .strictObject({
+        period: AuditAdoptionPeriodSchema,
+        previous_period: AuditAdoptionPeriodSchema,
+        resolution: z.enum(['day', 'week']),
+        active_users: z.number().int().nonnegative(),
+        previous_active_users: z.number().int().nonnegative(),
+        retained_users: z.number().int().nonnegative(),
+        observed_retention: z.number().min(0).max(1).nullable(),
+        returning_user_share: z.number().min(0).max(1).nullable(),
+        repeat_user_share: z.number().min(0).max(1).nullable(),
+        median_active_days: z.number().nonnegative().nullable(),
+        active_projects: z.number().int().nonnegative().nullable(),
+        timeline: z.array(AuditAdoptionBucketSchema),
+        active_day_distribution: z.array(AuditAdoptionActiveDaysSchema),
+        top_projects: z.array(AuditAdoptionProjectSchema).max(10),
+        history: AuditAdoptionHistorySchema,
+    })
+    .meta({
+        id: 'AuditAdoptionResponse',
+        description:
+            'Distinct user adoption sets over two equal-duration half-open periods. Ratios use available audit history, not guaranteed historical coverage. No user identities are returned.',
+    });
+
+export const AuditUsageQuerySchema = AuditAdoptionQuerySchema.omit({ filter: true })
+    .extend({
+        resolution: z.enum(['day', 'week', 'month']).optional().meta({
+            description: 'UTC calendar buckets. Weeks start Monday. Omitted: daily up to 200 dates, otherwise weekly.',
+        }),
+    })
+    .meta({
+        id: 'AuditUsageQuery',
+        description: 'Usage trends for an authorized account or project over a half-open interval of at most 366 days.',
+    });
+
+export const AuditUsageCountsSchema = z
+    .strictObject({
+        active_users: z.number().int().nonnegative(),
+        agent_runs: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({ description: 'All audited run creations and marked restarts, including automated runs.' }),
+        user_agent_runs: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({ description: 'Run operations initiated directly by authenticated users, including OAuth/MCP.' }),
+        automated_agent_runs: z.number().int().nonnegative().meta({
+            description: 'Other run operations, including schedules, delegated agents, services and API keys.',
+        }),
+        agent_users: z.number().int().nonnegative().meta({
+            description:
+                'Distinct identifiable user initiators or owners of run operations, including scheduled and delegated runs.',
+        }),
+        direct_calls: z.number().int().nonnegative(),
+        direct_call_users: z.number().int().nonnegative(),
+        content_objects: z.number().int().nonnegative(),
+        user_content_objects: z.number().int().nonnegative(),
+        other_content_objects: z.number().int().nonnegative(),
+    })
+    .meta({
+        id: 'AuditUsageCounts',
+        description:
+            'Direct productive users, run initiators/owners, all run operations and standalone inference audit events.',
+    });
+
+export const AuditUsageBucketSchema = z
+    .strictObject({
+        from: z.string().meta({ format: 'date-time' }),
+        to: z.string().meta({ format: 'date-time' }),
+        partial: z.boolean(),
+        counts: AuditUsageCountsSchema,
+    })
+    .meta({ id: 'AuditUsageBucket' });
+
+export const AuditUsageResponseSchema = z
+    .strictObject({
+        period: AuditAdoptionPeriodSchema,
+        resolution: z.enum(['day', 'week', 'month']),
+        totals: AuditUsageCountsSchema,
+        timeline: z.array(AuditUsageBucketSchema),
+    })
+    .meta({
+        id: 'AuditUsageResponse',
+        description:
+            'UTC usage trends. Period-wide distinct users are not sums of bucket populations. No user identities are returned.',
+    });