@vertesia/common 1.6.0-dev.20260918.115658Z → 1.6.0-dev.20261004.085740Z

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,6 +2,8 @@ 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.
@@ -140,7 +142,14 @@ 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>;
+export type AccountBillingFromSchema = Wire.AccountBillingFromSchema;
+export type AccountFromSchema = Wire.AccountFromSchema;
+export type UpdateAccountPayloadFromSchema = Wire.UpdateAccountPayloadFromSchema;
+export type StripeBillingStatusResponseFromSchema = Wire.StripeBillingStatusResponseFromSchema;
+
+/** Account-wide defaults for request API version negotiation. */
+export const AccountApiVersionPolicySchema = z
+    .strictObject({
+        default_api_version: z.enum(ApiVersions).optional(),
+    })
+    .meta({ id: 'AccountApiVersionPolicy' });

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
@@ -40,6 +41,13 @@ export const UpdateAppInstallationToolAllowlistPayloadSchema = z
     })
     .meta({ id: 'UpdateAppInstallationToolAllowlistPayload' });
 
+export const UpdateAppInstallationOAuthApprovalPayloadSchema = z
+    .strictObject({ approved_scopes: z.array(z.string().min(1)).max(200) })
+    .meta({
+        id: 'UpdateAppInstallationOAuthApprovalPayload',
+        description: 'Approve OAuth scopes for this project installation. An empty list revokes project approval.',
+    });
+
 export const ValidateUrlResponseSchema = z
     .strictObject({
         valid: z.boolean(),
@@ -405,6 +413,10 @@ export const StartAppScaffoldRequestSchema = z
         title: z.string().optional(),
         description: z.string().optional(),
         modules: z.array(AppScaffoldModuleSchema).optional(),
+        oauth_scopes: z
+            .array(z.string())
+            .optional()
+            .meta({ description: 'App permissions declared in generated source. Defaults to sign-in only.' }),
         appgen_package_spec: z
             .string()
             .regex(APPGEN_PACKAGE_SPEC_PATTERN)
@@ -431,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/app-runtime.ts

@@ -256,11 +256,18 @@ export const InCodeProcessDefinitionSchema: z.ZodType<InCodeProcessDefinition> =
     })
     .meta({ id: 'InCodeProcessDefinition' });
 
+const appOAuthApprovalSchema = z.strictObject({
+    scopes: z.array(z.string()),
+    approved_by: z.string(),
+    approved_at: z.string(),
+});
+
 export const AppInstallationSchema = z
     .strictObject({
         id: z.string(),
         project: z.string(),
         manifest: z.string(),
+        oauth_approval: appOAuthApprovalSchema.optional(),
         settings: z.looseObject({}).optional(),
         tool_allowlist: z
             .array(z.string())
@@ -331,6 +338,7 @@ export const AppDashboardDefinitionSchema = z
 
 export const AppManifestDataSchema = z
     .strictObject({
+        oauth_scopes: z.array(z.string()).optional(),
         name: z.string().meta({
             description: 'The name of the app, used as the id in the system. Must be in kebab case (e.g. my-app).',
         }),
@@ -511,6 +519,7 @@ export const CompositeAppMessageOverridesSchema = z
 
 export const AppManifestSchema = z
     .strictObject({
+        oauth_scopes: z.array(z.string()).optional(),
         edit_revision: EditRevisionSchema,
         name: z.string().meta({
             description: 'The name of the app, used as the id in the system. Must be in kebab case (e.g. my-app).',
@@ -630,6 +639,7 @@ export const AppInstallationWithManifestSchema = z
     .strictObject({
         id: z.string(),
         project: z.string(),
+        oauth_approval: appOAuthApprovalSchema.optional(),
         settings: z.looseObject({}).optional(),
         tool_allowlist: z
             .array(z.string())
@@ -675,6 +685,7 @@ export const AppInstallationListEntrySchema = z
     .strictObject({
         id: z.string(),
         project: z.string(),
+        oauth_approval: appOAuthApprovalSchema.optional(),
         settings: z.looseObject({}).optional(),
         tool_allowlist: z
             .array(z.string())
@@ -911,6 +922,10 @@ export const AppEventSubscriptionDefinitionSchema = z
 
 export const AppPackageSchema = z
     .strictObject({
+        oauth_scopes: z
+            .array(z.string())
+            .meta({ description: 'OAuth scopes requested by the app. Users must consent to project permissions.' })
+            .optional(),
         ui: AppUIConfigSchema.meta({ description: 'The UI configuration of the app' }).optional(),
         tools: z
             .array(AgentToolDefinitionSchema)

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

@@ -39,6 +39,8 @@ 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(),
         'details.pipeline': z.string().nullable().optional(),
         'details.verdict': z.string().nullable().optional(),
         'details.workflow_type': z.string().nullable().optional(),
@@ -48,7 +50,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'])
     .meta({ id: 'AuditAggregationDistinctField' });
 
 export const AuditAggregationOperationSchema = z
@@ -164,6 +166,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(),
     })

package/src/api-schemas/content.ts

@@ -338,6 +338,13 @@ const collectionPayloadFields = {
         .optional(),
     sensitivity: z.number().meta({ description: 'BLP sensitivity level for member documents' }).optional(),
     compartments: z.array(z.string()).meta({ description: 'Compartments for member documents' }).optional(),
+    shared_root: z
+        .boolean()
+        .meta({
+            description:
+                'Explicitly share this collection as a root of the project shared space (listable/readable by non-members via matching shared-content ABAC rules). This is the explicit API share flag — the sync never sets it.',
+        })
+        .optional(),
 };
 
 export const CreateCollectionPayloadSchema = z
@@ -492,6 +499,20 @@ export const CollectionSchema = z
             .array(z.string())
             .meta({ description: 'Compartments — propagated to member documents (union across collections)' })
             .optional(),
+        shared: z
+            .boolean()
+            .meta({
+                description:
+                    'Effective shared state: true iff the collection is a member of an effectively-shared parent collection (inherited; sync-managed). Combine with shared_root for full readability.',
+            })
+            .optional(),
+        shared_root: z
+            .boolean()
+            .meta({
+                description:
+                    'True iff the collection was explicitly shared via the API (a root of the project shared space). Never set by the sync.',
+            })
+            .optional(),
         shared_properties: z
             .array(z.string())
             .meta({
@@ -499,6 +520,10 @@ export const CollectionSchema = z
                     "List of property names from the collection's properties that should be shared with (injected into) member objects. These properties will be propagated to all members of this collection and merged as arrays.",
             })
             .optional(),
+        user_permissions: ContentObjectUserPermissionsSchema.meta({
+            description:
+                "Computed per-request permissions for the current user on this collection. Not stored — computed on the fly from the collection's security field (same semantics as a content object's user_permissions).",
+        }).optional(),
     })
     .meta({ id: 'Collection' });
 
@@ -548,6 +573,13 @@ export const CreateContentObjectPayloadSchema = z
                 description: 'Compartments — set directly or inherited from collections (union across collections).',
             })
             .optional(),
+        shared_root: z
+            .boolean()
+            .meta({
+                description:
+                    'Explicitly share this document as a root of the project shared space (readable by non-members via matching shared-content ABAC rules). This is the explicit API share flag — the sync never sets it.',
+            })
+            .optional(),
         inherited_properties: z
             .array(InheritedPropertyMetadataSchema)
             .meta({
@@ -648,6 +680,13 @@ export const UpdateContentObjectPayloadSchema = z
                 description: 'Compartments — set directly or inherited from collections (union across collections).',
             })
             .optional(),
+        shared_root: z
+            .boolean()
+            .meta({
+                description:
+                    'Explicitly share this document as a root of the project shared space (readable by non-members via matching shared-content ABAC rules). This is the explicit API share flag — the sync never sets it.',
+            })
+            .optional(),
         inherited_properties: z
             .array(InheritedPropertyMetadataSchema)
             .meta({
@@ -842,6 +881,20 @@ export const ContentObjectApiResponseSchema = z
                 description: 'Compartments — set directly or inherited from collections (union across collections).',
             })
             .optional(),
+        shared: z
+            .boolean()
+            .meta({
+                description:
+                    'Effective shared state: true iff the document is a member of an effectively-shared collection (inherited; sync-managed). Combine with shared_root for full readability.',
+            })
+            .optional(),
+        shared_root: z
+            .boolean()
+            .meta({
+                description:
+                    'True iff the document was explicitly shared via the API (a root of the project shared space). Never set by the sync.',
+            })
+            .optional(),
         inherited_properties: z.array(InheritedPropertyMetadataSchema).optional(),
     })
     .meta({ id: 'ContentObjectApiResponse' });
@@ -913,6 +966,8 @@ export const ContentObjectItemApiResponseSchema = z
         security: StringArrayMapSchema.optional(),
         sensitivity: z.number().nullable().optional(),
         compartments: z.array(z.string()).optional(),
+        shared: z.boolean().optional(),
+        shared_root: z.boolean().optional(),
         inherited_properties: z.array(InheritedPropertyMetadataSchema).optional(),
     })
     .meta({ id: 'ContentObjectItemApiResponse' });