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

package/src/api-schemas/registry.ts

@@ -31,7 +31,7 @@ import {
     ToolUseSchema,
     VideoResultSchema,
 } from '@llumiverse/common/schemas';
-import { z } from 'zod';
+import type { z } from 'zod';
 import type {
     CreateEventSubscriptionPayload,
     EventDeliveryTarget,
@@ -90,6 +90,9 @@ import {
     TimeResolutionSchema,
 } from './analytics.js';
 import {
+    AccountApiKeyArraySchema,
+    AccountApiKeySchema,
+    AccountApiKeyWithValueSchema,
     ApiKeyArraySchema,
     ApiKeyListQuerySchema,
     ApiKeyReadQuerySchema,
@@ -97,9 +100,11 @@ import {
     ApiKeySchema,
     ApiKeyWithValueSchema,
     AuthTokenResponseSchema,
+    CreateAccountApiKeyPayloadSchema,
     CreateApiKeyPayloadSchema,
     DeleteOperationResultSchema,
     ProjectRefArraySchema,
+    UpdateAccountApiKeyPayloadSchema,
     UpdateApiKeyPayloadSchema,
 } from './apikey.js';
 import {
@@ -343,6 +348,7 @@ import {
     SemanticColumnTypeSchema,
     UpdateSchemaPayloadSchema,
 } from './data-store.js';
+import { CreateDelegationGrantPayloadSchema, DelegationGrantArraySchema, DelegationGrantSchema } from './delegation.js';
 import {
     DocAnalyzeRunStatusResponseSchema,
     DocAnalyzerProgressSchema,
@@ -374,6 +380,7 @@ import {
     EmbeddingsStatusResponseSchema,
     ProjectConfigurationEmbeddingEnablePayloadSchema,
 } from './embeddings.js';
+import { emitJsonSchema } from './emit-json-schema.js';
 import {
     EnableEnvironmentModelPayloadSchema,
     ExecutionEnvironmentArraySchema,
@@ -839,6 +846,12 @@ const IAM_AND_ACCOUNT_SCHEMAS = {
     ApiKey: ApiKeySchema,
     ApiKeyArray: ApiKeyArraySchema,
     ApiKeyWithValue: ApiKeyWithValueSchema,
+    AccountApiKey: AccountApiKeySchema,
+    AccountApiKeyWithValue: AccountApiKeyWithValueSchema,
+    AccountApiKeyArray: AccountApiKeyArraySchema,
+    CreateAccountApiKeyPayload: CreateAccountApiKeyPayloadSchema,
+    UpdateAccountApiKeyPayload: UpdateAccountApiKeyPayloadSchema,
+
     ApiKeyReadResponse: ApiKeyReadResponseSchema,
     ApiKeyReadQuery: ApiKeyReadQuerySchema,
     CreateApiKeyPayload: CreateApiKeyPayloadSchema,
@@ -875,8 +888,8 @@ const PROJECT_AND_APP_SCHEMAS = {
     ProjectConfigurationEmbedding: ProjectConfigurationEmbeddingSchema,
     BrowserUseProjectConfiguration: BrowserUseProjectConfigurationSchema,
     ProjectIntakeSniffConfiguration: ProjectIntakeSniffConfigurationSchema,
-    // Leaves of the Project closure. `ModelOptions` hoists its
-    // twenty-five driver option sets and four enums; `JSONSchema` hoists `JSONSchemaProperties`.
+    // Leaves of the Project closure. `ModelOptions` hoists its driver option sets and shared enums;
+    // `JSONSchema` hoists `JSONSchemaProperties`.
     JSONSchema: JSONSchemaSchema,
     ModelOptions: ModelOptionsSchema,
     HttpTimeoutOptions: HttpTimeoutOptionsSchema,
@@ -1786,6 +1799,25 @@ const AGENT_RUN_SCHEMAS = {
     SearchAgentRunsQuery: AgentRunSchemas.SearchAgentRunsQuerySchema,
     StreamAgentRunQuery: AgentRunSchemas.StreamAgentRunQuerySchema,
     UpdateAgentRunStatusPayload: AgentRunSchemas.UpdateAgentRunStatusPayloadSchema,
+    AgentRunFeedbackRating: AgentRunSchemas.AgentRunFeedbackRatingSchema,
+    AgentRunFeedbackReasonCode: AgentRunSchemas.AgentRunFeedbackReasonCodeSchema,
+    AgentRunFeedbackPayload: AgentRunSchemas.AgentRunFeedbackPayloadSchema,
+    AgentRunFeedbackStatus: AgentRunSchemas.AgentRunFeedbackStatusSchema,
+    AgentRunFeedbackCounts: AgentRunSchemas.AgentRunFeedbackCountsSchema,
+    AgentRunFeedbackResponse: AgentRunSchemas.AgentRunFeedbackResponseSchema,
+    AgentRunFeedbackEntry: AgentRunSchemas.AgentRunFeedbackEntrySchema,
+    AgentRunEvaluationRollup: AgentRunSchemas.AgentRunEvaluationRollupSchema,
+    AgentRunJudgeResult: AgentRunSchemas.AgentRunJudgeResultSchema,
+    AgentRunContradictionReason: AgentRunSchemas.AgentRunContradictionReasonSchema,
+    AgentRunEvaluation: AgentRunSchemas.AgentRunEvaluationSchema,
+    TurnTerminalType: AgentRunSchemas.TurnTerminalTypeSchema,
+    EvaluationSeverity: AgentRunSchemas.EvaluationSeveritySchema,
+    TurnEvaluationFlag: AgentRunSchemas.TurnEvaluationFlagSchema,
+    ToolErrorClass: AgentRunSchemas.ToolErrorClassSchema,
+    JudgeGateReason: AgentRunSchemas.JudgeGateReasonSchema,
+    JudgeOutcome: AgentRunSchemas.JudgeOutcomeSchema,
+    JudgeVerdict: AgentRunSchemas.JudgeVerdictSchema,
+    ListAgentRunsEvaluationSeverity: AgentRunSchemas.ListAgentRunsEvaluationSeveritySchema,
     AgentEvent: AgentRunSchemas.AgentEventSchema,
     IngestAgentEventsPayload: AgentRunSchemas.IngestAgentEventsPayloadSchema,
     IngestAgentEventsResponse: AgentRunSchemas.IngestAgentEventsResponseSchema,
@@ -2246,7 +2278,13 @@ const CONTENT_QUERY_SCHEMAS = {
     ContentQueryResult: ContentQuerySchemas.ContentQueryResultSchema,
 } as const satisfies Record<string, z.ZodType>;
 
+const DELEGATION_SCHEMAS = {
+    CreateDelegationGrantPayload: CreateDelegationGrantPayloadSchema,
+    DelegationGrant: DelegationGrantSchema,
+    DelegationGrantArray: DelegationGrantArraySchema,
+};
 const API_SCHEMA_GROUPS = [
+    DELEGATION_SCHEMAS,
     IAM_AND_ACCOUNT_SCHEMAS,
     PROJECT_AND_APP_SCHEMAS,
     OAUTH_SCHEMAS,
@@ -2309,7 +2347,8 @@ const API_SCHEMA_GROUPS = [
  * have inferred to. `mergeComponentGroups` rejects a name declared by two groups, so no key is ever
  * intersected with a second schema.
  */
-type ApiSchemaMap = typeof IAM_AND_ACCOUNT_SCHEMAS &
+type ApiSchemaMap = typeof DELEGATION_SCHEMAS &
+    typeof IAM_AND_ACCOUNT_SCHEMAS &
     typeof PROJECT_AND_APP_SCHEMAS &
     typeof OAUTH_SCHEMAS &
     typeof ENVIRONMENT_SCHEMAS &
@@ -2380,6 +2419,13 @@ const API_SCHEMAS: Readonly<Record<ApiComponentName, z.ZodType>> = mergeComponen
  * objects, so a body carrying an undeclared property is rejected rather than quietly accepted.
  */
 const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
+    'AccountApiKey',
+    'AccountApiKeyWithValue',
+    'CreateAccountApiKeyPayload',
+    'UpdateAccountApiKeyPayload',
+
+    'CreateDelegationGrantPayload',
+    'DelegationGrant',
     // Process Test Lab request, fixture, and result contracts.
     'ProcessTestVirtualActor',
     'ProcessTestFixtureResult',
@@ -2580,6 +2626,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'BedrockMantleClaudeOptions',
     'OpenAiThinkingOptions',
     'OpenAiTextOptions',
+    'OpenRouterTextOptions',
     'OpenAiDalleOptions',
     'OpenAiGptImageOptions',
     'XAIGrokImageOptions',
@@ -2778,6 +2825,13 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'UpdateAgentArtifactContentResponse',
     'UpdateAgentArtifactContentPayload',
     'TerminateAgentRunResponse',
+    'AgentRunFeedbackPayload',
+    'AgentRunFeedbackResponse',
+    'AgentRunFeedbackCounts',
+    'AgentRunFeedbackEntry',
+    'AgentRunEvaluationRollup',
+    'AgentRunJudgeResult',
+    'AgentRunEvaluation',
     'StartContentObjectExportResponse',
     'ExportContentObjectsIncludeOptions',
     'ExportContentObjectsFilter',
@@ -3385,12 +3439,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
  * not be used to express contract rules — they would be invisible to both the spec and AJV.
  */
 function emitRawSchemas(): Record<string, unknown> {
-    return Object.fromEntries(
-        Object.entries(API_SCHEMAS).map(([name, schema]) => [
-            name,
-            z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' }),
-        ]),
-    );
+    return Object.fromEntries(Object.entries(API_SCHEMAS).map(([name, schema]) => [name, emitJsonSchema(schema)]));
 }
 
 /**

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

@@ -1,5 +1,3 @@
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import { Ajv } from 'ajv';
 import { describe, expect, it } from 'vitest';
 import { ContentTypeIntakePolicySchema as GeneratedIntakePolicySchema } from '../store/intake-policy-schema.generated.js';
@@ -14,9 +12,9 @@ function assertType<T extends true>(_ok: T): void {}
 
 /**
  * The intake policy is now stated once, in Zod, and reaches its consumers three ways: as the
- * published OpenAPI component, as the checked-in JSON artifact that zeno-server / the workflow tool /
- * the web editor compiles, and as the TypeScript type. This file is the gate that keeps all three
- * the same statement.
+ * canonical component, as the checked-in JSON artifact consumers compile, and as the TypeScript
+ * type. This file keeps those package-owned contracts aligned. Downstream consumers test their
+ * published API documents and generated-client fixtures separately.
  *
  * It also pins the behaviour changes the conversion makes, because the schema it replaced was
  * hand-written and disagreed with the contract in both directions. Each is asserted rather than
@@ -30,101 +28,13 @@ function errors(): string {
     return ajv.errorsText(validate.errors, { separator: '\n' });
 }
 
-/**
- * Reads a file from the studio repository this package is a submodule of.
- *
- * `undefined` when it is not there, which is the normal state in this repository's own CI: it clones
- * composableai alone, so nothing above the submodule root exists. Two of the gates below compare
- * against the published document and the generated-client fixture, both of which live up there — so
- * they are skipped when they cannot be read rather than failing the whole file at import time, which
- * is what used to happen and what left this suite red on every commit.
- *
- * They still run where they are the actual gate: a checkout of the parent repository, which is what
- * the migration's own verification and the studio CI use.
- */
-function readFromStudioRepo(relativePath: string): unknown {
-    try {
-        return JSON.parse(readFileSync(fileURLToPath(new URL(relativePath, import.meta.url)), 'utf8'));
-    } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
-        throw error;
-    }
-}
-
-const publishedDocument = readFromStudioRepo('../../../../../packages/api-specs/vertesia-openapi.json') as
-    | { components: { schemas: Record<string, Record<string, unknown>> } }
-    | undefined;
-const published = publishedDocument?.components.schemas ?? {};
-
-/**
- * The published component minus the OpenAPI-only discriminator hint the bundler drops.
- *
- * Written out here rather than imported from the registry on purpose: reusing the production
- * function to check the production function would make the comparison below pass by construction.
- * The rule is small enough to state twice, and stating it twice is what makes it a gate.
- */
-function withoutDiscriminatorHints(value: unknown): unknown {
-    if (Array.isArray(value)) return value.map(withoutDiscriminatorHints);
-    if (!value || typeof value !== 'object') return value;
-    const node = value as Record<string, unknown>;
-    const restated = node.discriminator !== undefined && node.properties === undefined;
-    return Object.fromEntries(
-        Object.entries(node)
-            .filter(([key]) => key !== 'discriminator' && !(restated && (key === 'type' || key === 'required')))
-            .map(([key, item]) => [key, withoutDiscriminatorHints(item)]),
-    );
-}
-
-function $defsOf(schema: unknown): unknown {
-    return (schema as { $defs: unknown }).$defs;
-}
-
-describe.skipIf(!publishedDocument)('gate — generated artifact = canonical component = published component', () => {
+describe('generated artifact and canonical component', () => {
     it('is the exact bundle the registry emits, so the artifact is compiled output', () => {
         // Deep equality, not a spot check: the file is generated by `pnpm run gen:schemas` from this
         // same function, so any difference means someone hand-edited it or forgot to regenerate.
         expect(GeneratedIntakePolicySchema).toEqual(bundleCanonicalComponent('ContentTypeIntakePolicy'));
     });
 
-    it('describes the same shape as the component the OpenAPI document publishes', () => {
-        // The artifact re-roots `#/components/schemas/X` to `#/$defs/X` so AJV and Monaco can compile
-        // it standalone. Undoing that is what makes the two directly comparable.
-        const { $defs, ...body } = GeneratedIntakePolicySchema as { $defs: Record<string, unknown> };
-        const rerooted = JSON.parse(JSON.stringify(body).replaceAll('#/$defs/', '#/components/schemas/'));
-        expect(rerooted).toEqual(withoutDiscriminatorHints(published.ContentTypeIntakePolicy));
-
-        // ...and every definition it carries is the published component of that name, so the bundle
-        // cannot describe a private variant of a shared type.
-        for (const [name, definition] of Object.entries($defs)) {
-            const asComponent = JSON.parse(JSON.stringify(definition).replaceAll('#/$defs/', '#/components/schemas/'));
-            expect(asComponent, `$defs.${name} disagrees with the published component`).toEqual(
-                withoutDiscriminatorHints(published[name]),
-            );
-        }
-    });
-
-    it('drops the discriminator hint the published component keeps, and only that', () => {
-        // The one place the artifact and the component are allowed to differ, pinned from both sides
-        // so neither can move alone. `synthesizeDiscriminator` restates `type` and `required` on the
-        // union node for the generated Java/Go clients; the node has no `properties`, and Gemini
-        // rejects the whole tool schema over it ("requires unspecified property '_option_id'") when
-        // the artifact reaches Vertex inside `create_or_update_type`'s input schema.
-        expect(published.ModelOptions).toMatchObject({
-            discriminator: { propertyName: '_option_id' },
-            type: 'object',
-            required: ['_option_id'],
-        });
-
-        const bundled = ($defsOf(GeneratedIntakePolicySchema) as Record<string, Record<string, unknown>>).ModelOptions;
-        expect(bundled.discriminator).toBeUndefined();
-        expect(bundled.required).toBeUndefined();
-        expect(bundled.type).toBeUndefined();
-        // The branches are what carried the contract all along, so nothing was validated away.
-        expect((bundled.oneOf as unknown[]).length).toBe(
-            ((published.ModelOptions as { oneOf: unknown[] }).oneOf ?? []).length,
-        );
-    });
-
     it('registers the component the alias claims, under the id the alias name requires', () => {
         expect(Object.keys(ApiSchemaComponents)).toContain('ContentTypeIntakePolicy');
         assertType<Equals<ContentTypeIntakePolicy, (typeof ContentTypeIntakePolicySchema)['_zod']['output']>>(true);
@@ -230,38 +140,6 @@ describe('gate — the artifact accepts exactly what the Zod schema accepts', ()
     });
 });
 
-describe.skipIf(!publishedDocument)('the fixture the generated Java and Go clients deserialize', () => {
-    // `openapi/fixtures/content-type-intake-policy.json` is read by
-    // `openapi/java/src/test/.../ContentTypeIntakePolicyDeserializationTest.java` and by
-    // `openapi/go/tests/intake_policy_deserialization_test.go`. Asserting it HERE is what stops it
-    // going stale: a schema change that the fixture no longer satisfies fails in this package,
-    // beside the schema, rather than in a client harness that only CI runs.
-    const fixture = readFromStudioRepo('../../../../../openapi/fixtures/content-type-intake-policy.json') ?? {};
-
-    it('is a policy the canonical schema and the generated artifact both accept', () => {
-        expect(ContentTypeIntakePolicySchema.safeParse(fixture).success).toBe(true);
-        expect(validate(fixture), errors()).toBe(true);
-    });
-
-    it('exercises the shapes the number -> integer correction changed', () => {
-        // The fields whose generated Java type moved from Double to Integer and whose Go type moved
-        // from float32 to int32. A fixture that omitted them would let the clients compile and
-        // deserialize while proving nothing about the change this batch makes.
-        const policy = fixture as ContentTypeIntakePolicy;
-        expect(policy.extraction?.max_pages).toBe(6);
-        expect(policy.extraction?.page_ranges).toEqual([
-            [1, 2],
-            [-1, -1],
-        ]);
-        expect(policy.text_conversion?.render_dpi).toBe(150);
-        expect(policy.extraction?.vision?.max_image_tokens).toBe(9000);
-        expect(policy.extraction?.grounding?.window_pages).toBe(4);
-        // ...and the discriminated union, which is what a Go oneOf decoder gets wrong when the
-        // discriminator is missing from the document.
-        expect(policy.extraction?.config?.model_options?._option_id).toBe('vertexai-claude');
-    });
-});
-
 describe('the TypeScript type says what the schema says', () => {
     it('widens page ranges to number[][], which is what the component has always described', () => {
         // `[number, number][]` is what the interface used to claim. The published component is

package/src/api-schemas/sts.ts

@@ -59,6 +59,9 @@ export const EnvironmentTokenRequestSchema = z
 export const AgentTokenRequestSchema = z
     .strictObject({
         type: z.literal('agent'),
+        delegation_grant_id: z.string().optional(),
+        delegation_policy_hash: z.string().optional(),
+        continuation_token: z.string().optional(),
         ...baseTokenRequestShape,
         account_id: z.string(),
         project_id: z.string(),

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

@@ -223,11 +223,13 @@ export const PendingActivitySchema = z
         maximumAttempts: z.number(),
         lastFailure: z.string().optional(),
         lastStartedTime: nullableStringSchema,
+        lastHeartbeatTime: nullableStringSchema.optional(),
     })
     .meta({ id: 'PendingActivity' });
 
 export const AgentTaskSchema = z
     .strictObject({
+        history_id: z.string().meta({ description: 'Stable observability row identity across refreshes.' }).optional(),
         taskType: z
             .enum(['tool_call', 'llm_call', 'input', 'timer', 'subagent', 'processing', 'signal'])
             .meta({ description: 'Type discriminator for future task types' }),
@@ -575,6 +577,20 @@ export const WorkflowHistorySchema = z
         }),
         z.strictObject({
             type: z.literal('agent'),
+            mode: z
+                .enum(['snapshot', 'delta'])
+                .meta({
+                    description:
+                        'Snapshot replaces all history; delta replaces returned rows by history_id and retains other rows.',
+                })
+                .optional(),
+            next_from: z
+                .string()
+                .meta({
+                    description:
+                        'Pass as from on the next refresh with the same options. Absence disables incremental refresh.',
+                })
+                .optional(),
             agentTasks: z.array(AgentTaskSchema),
         }),
     ])

package/src/api-schemas/zeno-response-contracts.test.ts

@@ -341,4 +341,40 @@ describe('Zeno read-side response contracts', () => {
             ]).valid,
         ).toBe(true);
     });
+
+    it('publishes agent-node launch and execution policy', () => {
+        expect(
+            validateApiRequest('CreateProcessDefinitionPayload', {
+                name: 'App development process',
+                definition: {
+                    format_version: 1,
+                    process: 'app_development',
+                    initial: 'implement',
+                    context: { schema: {}, initial: {} },
+                    nodes: {
+                        implement: {
+                            type: 'agent',
+                            interaction: 'sys:AppDeveloper',
+                            inherit_context: false,
+                            initial_skills: ['app_quick_fix'],
+                            excluded_tools: ['learn_app_development'],
+                            agent_policy: {
+                                phases: [
+                                    {
+                                        id: 'saved',
+                                        tools: ['app_workspace_save'],
+                                        tool_input_contains: [{ field: 'mode', contains: 'commit' }],
+                                        recovery_prompt: 'Save before finishing.',
+                                    },
+                                ],
+                                phase_resets: [{ tools: ['app_workspace_edit'], to_phase: 'saved' }],
+                                defer_result_schema_until_complete: true,
+                                completion_prompt: 'Return the structured result now.',
+                            },
+                        },
+                    },
+                },
+            }).valid,
+        ).toBe(true);
+    });
 });

package/src/apikey.ts

@@ -80,6 +80,9 @@ export type ApiKeyListQuery = z.infer<typeof ApiKeyListQuerySchema>;
 export type ApiKeyReadQuery = z.infer<typeof ApiKeyReadQuerySchema>;
 
 export interface AuthTokenPayload {
+    credential_scope?: 'project' | 'account';
+    credential_profile?: 'account_admin_v1';
+    delegation?: import('./delegation.js').DelegationTokenClaim;
     sub: string;
     name: string;
     email?: string;
@@ -193,3 +196,13 @@ export enum PrincipalType {
     Agent = 'agent',
     Schedule = 'schedule',
 }
+
+export type AccountApiKey = z.infer<typeof import('./api-schemas/apikey.js').AccountApiKeySchema>;
+export type AccountApiKeyWithValue = z.infer<typeof import('./api-schemas/apikey.js').AccountApiKeyWithValueSchema>;
+export type AccountApiKeyArray = z.infer<typeof import('./api-schemas/apikey.js').AccountApiKeyArraySchema>;
+export type CreateAccountApiKeyPayload = z.infer<
+    typeof import('./api-schemas/apikey.js').CreateAccountApiKeyPayloadSchema
+>;
+export type UpdateAccountApiKeyPayload = z.infer<
+    typeof import('./api-schemas/apikey.js').UpdateAccountApiKeyPayloadSchema
+>;

package/src/delegation.ts

@@ -0,0 +1,18 @@
+import type { z } from 'zod';
+import type {
+    CreateDelegationGrantPayloadSchema,
+    DelegationGrantArraySchema,
+    DelegationGrantSchema,
+} from './api-schemas/delegation.js';
+
+export type CreateDelegationGrantPayload = z.infer<typeof CreateDelegationGrantPayloadSchema>;
+export type DelegationGrant = z.infer<typeof DelegationGrantSchema>;
+export type DelegationGrantArray = z.infer<typeof DelegationGrantArraySchema>;
+
+export interface DelegationTokenClaim {
+    grant_id: string;
+    subject: string;
+    schedule_id: string;
+    output_collection_id: string;
+    policy_hash: string;
+}

package/src/index.ts

@@ -22,6 +22,12 @@ export * from './common.js';
 export * from './content-query.js';
 export * from './cost-analytics.js';
 export * from './data-platform.js';
+export type {
+    CreateDelegationGrantPayload,
+    DelegationGrant,
+    DelegationGrantArray,
+    DelegationTokenClaim,
+} from './delegation.js';
 export * from './email.js';
 export * from './embeddings.js';
 export * from './environment.js';

package/src/oauth-scopes.ts

@@ -1,4 +1,4 @@
-import { Permission } from './access-control-values.js';
+import { ACCOUNT_SCOPED_PERMISSIONS, Permission } from './access-control-values.js';
 
 export const OAUTH_SCOPE_OPENID = 'openid';
 export const OAUTH_SCOPE_PROFILE = 'profile';
@@ -12,6 +12,8 @@ export const OAUTH_STANDARD_SCOPES = [OAUTH_SCOPE_OPENID, OAUTH_SCOPE_PROFILE, O
  * hand out secret material, or are internal to the platform's own consoles.
  */
 const NON_OAUTH_PERMISSION_SCOPES = new Set<Permission>([
+    ...ACCOUNT_SCOPED_PERMISSIONS,
+    Permission.schedule_delegate,
     Permission.api_key_create,
     Permission.api_key_update,
     Permission.api_key_delete,

package/src/project-values.ts

@@ -24,6 +24,7 @@ export enum ResourceVisibility {
 export enum SystemRoles {
     owner = 'owner', // all permissions
     admin = 'admin', // all permissions
+    app_admin = 'app_admin', // all permissions but studio:access — admin driving a custom admin UI
     manager = 'manager', // all permissions but manage_account, manage_billing
     developer = 'developer', // all permissions but manage_account, manage_billing, manage_roles, delete
     application = 'application', // executor + request_pk

package/src/roles.test.ts

@@ -7,6 +7,7 @@ describe('shared role vocabulary', () => {
         expect(Object.values(SystemRoles).sort()).toEqual(
             [
                 'admin',
+                'app_admin',
                 'app_member',
                 'application',
                 'auditor',

package/src/store/agent-run-values.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime values the agent-run API schemas build on.
+ *
+ * Split out of `agent-run.ts` for the reason `account-values.ts` was split out of `user.ts`: the
+ * schema module in `api-schemas/` needs these at runtime, while `agent-run.ts` must stay a
+ * type-only module so importing it never pulls Zod into a consumer's bundle. Both sides import
+ * from here, and `agent-run.ts` re-exports it so the constants are nameable from the package root.
+ */
+
+/**
+ * Bound on `AgentRunFeedbackPayload.comment`, in characters.
+ *
+ * Published so a client can stop the user at the limit instead of letting the server reject the
+ * whole rating over the tail of a comment.
+ */
+export const AGENT_RUN_FEEDBACK_COMMENT_MAX_LENGTH = 2000;
+
+/**
+ * Bound on `AgentRunFeedbackPayload.feedback_id`, in characters. A UUID fits comfortably.
+ */
+export const AGENT_RUN_FEEDBACK_ID_MAX_LENGTH = 64;
+
+/**
+ * How many feedback entries a run retains. Counters are computed over the retained entries;
+ * replaced entries are evicted first, then the oldest.
+ */
+export const AGENT_RUN_FEEDBACK_MAX_ENTRIES = 50;

package/src/store/agent-run.ts

@@ -21,7 +21,18 @@ import type {
     AgentRunArtifactQuerySchema,
     AgentRunArtifactsQuerySchema,
     AgentRunArtifactUploadHeadersSchema,
+    AgentRunContradictionReasonSchema,
     AgentRunDetailsQuerySchema,
+    AgentRunEvaluationRollupSchema,
+    AgentRunEvaluationSchema,
+    AgentRunFeedbackCountsSchema,
+    AgentRunFeedbackEntrySchema,
+    AgentRunFeedbackPayloadSchema,
+    AgentRunFeedbackRatingSchema,
+    AgentRunFeedbackReasonCodeSchema,
+    AgentRunFeedbackResponseSchema,
+    AgentRunFeedbackStatusSchema,
+    AgentRunJudgeResultSchema,
     AgentRunSchema,
     AgentRunUpdatesQuerySchema,
     AgentRunUpdatesResponseSchema,
@@ -31,6 +42,7 @@ import type {
     CreateRunPayloadSchema,
     IngestAgentEventsPayloadSchema,
     IngestAgentEventsResponseSchema,
+    ListAgentRunsEvaluationSeveritySchema,
     ListAgentRunsQuerySchema,
     PostAgentRunUpdatePayloadSchema,
     PostAgentRunUpdateResponseSchema,
@@ -64,6 +76,8 @@ import type {
     WorkflowRunEvent,
 } from './workflow.js';
 
+export * from './agent-run-values.js';
+
 export type AgentRunStatus = z.infer<typeof AgentRunStatusSchema>;
 
 export type AgentRunArchiveState = z.infer<typeof AgentRunArchiveStateSchema>;
@@ -263,6 +277,8 @@ export interface RecordProcessRunPayload<TData = Record<string, unknown>, TSourc
         RecordRunWorkflowPayload {
     run_kind: 'process';
     run_type?: ProcessRunType;
+    schedule_id?: string;
+    type?: AgentRunType;
 }
 
 export type RecordRunPayload<TData = Record<string, unknown>, TSource = RunSource> =
@@ -277,6 +293,18 @@ export type BindRunWorkflowPayload = z.infer<typeof BindRunWorkflowPayloadSchema
 
 export type TerminateAgentRunResponse = z.infer<typeof TerminateAgentRunResponseSchema>;
 
+export type AgentRunFeedbackRating = z.infer<typeof AgentRunFeedbackRatingSchema>;
+export type AgentRunFeedbackReasonCode = z.infer<typeof AgentRunFeedbackReasonCodeSchema>;
+export type AgentRunFeedbackPayload = z.infer<typeof AgentRunFeedbackPayloadSchema>;
+export type AgentRunFeedbackStatus = z.infer<typeof AgentRunFeedbackStatusSchema>;
+export type AgentRunFeedbackCounts = z.infer<typeof AgentRunFeedbackCountsSchema>;
+export type AgentRunFeedbackResponse = z.infer<typeof AgentRunFeedbackResponseSchema>;
+export type AgentRunFeedbackEntry = z.infer<typeof AgentRunFeedbackEntrySchema>;
+export type AgentRunEvaluationRollup = z.infer<typeof AgentRunEvaluationRollupSchema>;
+export type AgentRunJudgeResult = z.infer<typeof AgentRunJudgeResultSchema>;
+export type AgentRunContradictionReason = z.infer<typeof AgentRunContradictionReasonSchema>;
+export type AgentRunEvaluation = z.infer<typeof AgentRunEvaluationSchema>;
+
 /**
  * Payload for updating an AgentRun's lifecycle and derived metadata.
  */
@@ -308,6 +336,11 @@ export interface UpdateAgentRunStatusPayload {
     last_archive_error?: string;
     sequence?: number;
     process_state?: ProcessState;
+    /**
+     * Fold of the run's turn evaluations, written by the conversation workflow. The server applies
+     * it atomically and ignores a rollup whose `seq` is not newer than the one it holds.
+     */
+    evaluation_rollup?: AgentRunEvaluationRollup;
 }
 
 // The wire contract is deliberately open because signal payloads are selected by `signalName`.
@@ -388,6 +421,9 @@ export type AgentRunDetailsStreamEvent =
     | { type: 'control'; data: AgentRunDetailsControlStreamEvent }
     | { type: 'error'; data: AgentRunDetailsErrorStreamEvent };
 
+/** Evaluation severity filter values; `unrated` selects runs without an evaluation. */
+export type ListAgentRunsEvaluationSeverity = z.infer<typeof ListAgentRunsEvaluationSeveritySchema>;
+
 /**
  * Filters for listing agent runs.
  */

package/src/store/conversation-state.ts

@@ -66,7 +66,7 @@ export interface ConversationState {
     /** Run-scoped, exact-target grants created by "allow this action for this run". */
     tool_approval_grants?: Record<string, ToolApprovalGrant>;
 
-    /** Buffered tool results held while approval denial pauses until the next user message. */
+    /** Buffered tool results held across an interactive pause until the next user message. */
     pending_tool_approval_results?: PendingToolApprovalResults;
 
     /** Compact, redacted latest user intent for reviewer-style system interactions. */