@vertesia/common 1.5.0-dev.20260910.051115Z → 1.6.0-dev.20260912.110338Z

package/src/apikey.ts

@@ -80,6 +80,7 @@ export type ApiKeyListQuery = z.infer<typeof ApiKeyListQuerySchema>;
 export type ApiKeyReadQuery = z.infer<typeof ApiKeyReadQuerySchema>;
 
 export interface AuthTokenPayload {
+    delegation?: import('./delegation.js').DelegationTokenClaim;
     sub: string;
     name: string;
     email?: string;

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

@@ -12,6 +12,7 @@ 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>([
+    Permission.schedule_delegate,
     Permission.api_key_create,
     Permission.api_key_update,
     Permission.api_key_delete,

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. */

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

@@ -1224,6 +1224,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                 {
                     $ref: '#/$defs/OpenAiTextOptions',
                 },
+                {
+                    $ref: '#/$defs/OpenRouterTextOptions',
+                },
                 {
                     $ref: '#/$defs/OpenAiDalleOptions',
                 },
@@ -1370,6 +1373,10 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                 max_tokens: {
                     type: 'number',
                 },
+                tool_choice: {
+                    type: 'string',
+                    enum: ['auto', 'none', 'any', 'required'],
+                },
                 effort: {
                     $ref: '#/$defs/ReasoningEffort',
                 },
@@ -1426,6 +1433,10 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                 max_tokens: {
                     type: 'number',
                 },
+                tool_choice: {
+                    type: 'string',
+                    enum: ['auto', 'none', 'any', 'required'],
+                },
                 stop_sequence: {
                     type: 'array',
                     items: {
@@ -1460,6 +1471,116 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
             required: ['_option_id'],
             additionalProperties: false,
         },
+        OpenRouterTextOptions: {
+            type: 'object',
+            properties: {
+                max_tokens: {
+                    type: 'number',
+                },
+                tool_choice: {
+                    type: 'string',
+                    enum: ['auto', 'none', 'any', 'required'],
+                },
+                effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
+                reasoning_effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
+                temperature: {
+                    type: 'number',
+                },
+                top_p: {
+                    type: 'number',
+                },
+                presence_penalty: {
+                    type: 'number',
+                },
+                frequency_penalty: {
+                    type: 'number',
+                },
+                stop_sequence: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                    },
+                },
+                image_detail: {
+                    type: 'string',
+                    enum: ['low', 'high', 'auto'],
+                },
+                include_thoughts: {
+                    type: 'boolean',
+                },
+                service_tier: {
+                    type: 'string',
+                    minLength: 1,
+                    description:
+                        'Provider-defined processing tier. Unknown non-empty values are preserved for forward compatibility.',
+                },
+                _option_id: {
+                    type: 'string',
+                    const: 'openrouter-text',
+                },
+                provider_sort: {
+                    type: 'string',
+                    enum: ['price', 'throughput', 'latency', 'exacto'],
+                },
+                provider_order: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                    },
+                },
+                provider_only: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                    },
+                },
+                provider_ignore: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                    },
+                },
+                provider_allow_fallbacks: {
+                    type: 'boolean',
+                },
+                provider_require_parameters: {
+                    type: 'boolean',
+                },
+                provider_data_collection: {
+                    type: 'string',
+                    enum: ['allow', 'deny'],
+                },
+                provider_zdr: {
+                    type: 'boolean',
+                },
+                provider_quantizations: {
+                    type: 'array',
+                    items: {
+                        type: 'string',
+                        enum: [
+                            'int4',
+                            'int8',
+                            'fp4',
+                            'mxfp4',
+                            'nvfp4',
+                            'fp6',
+                            'fp8',
+                            'mxfp8',
+                            'fp16',
+                            'bf16',
+                            'fp32',
+                            'unknown',
+                        ],
+                    },
+                },
+            },
+            required: ['_option_id'],
+            additionalProperties: false,
+        },
         PromptCacheMode: {
             type: 'string',
             enum: ['auto', 'off', 'required'],
@@ -1482,6 +1603,10 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                 max_tokens: {
                     type: 'number',
                 },
+                tool_choice: {
+                    type: 'string',
+                    enum: ['auto', 'none', 'any', 'required'],
+                },
                 temperature: {
                     type: 'number',
                 },

package/src/store/process.ts

@@ -63,6 +63,12 @@ import type {
     UpdateProcessTestScenarioPayloadSchema,
     UpdateProcessTestSuitePayloadSchema,
 } from '../api-schemas/process.js';
+import type {
+    ProcessAgentExecutionPolicySchema,
+    ProcessAgentPhaseResetSchema,
+    ProcessAgentToolInputContainsSchema,
+    ProcessAgentToolPhaseSchema,
+} from '../api-schemas/process-agent-policy.js';
 import type { JSONSchema } from '../json-schema.js';
 
 export type JsonLogicRule = z.infer<typeof JsonLogicRuleSchema>;
@@ -81,6 +87,10 @@ export type ProcessNodeRunType = z.infer<typeof ProcessNodeRunTypeSchema>;
 export type ParallelCollectMode = z.infer<typeof ParallelCollectModeSchema>;
 export type BranchJoinPolicy = z.infer<typeof BranchJoinPolicySchema>;
 export type ProcessDefinitionMetadata = z.infer<typeof ProcessDefinitionMetadataSchema>;
+export type ProcessAgentToolPhase = z.infer<typeof ProcessAgentToolPhaseSchema>;
+export type ProcessAgentToolInputContains = z.infer<typeof ProcessAgentToolInputContainsSchema>;
+export type ProcessAgentPhaseReset = z.infer<typeof ProcessAgentPhaseResetSchema>;
+export type ProcessAgentExecutionPolicy = z.infer<typeof ProcessAgentExecutionPolicySchema>;
 export type ProcessScriptLanguage = z.infer<typeof ProcessScriptLanguageSchema>;
 
 export type ProcessScriptInlineSource = z.infer<typeof ProcessScriptInlineSourceSchema>;
@@ -131,6 +141,12 @@ export interface NodeDefinition {
     result_schema?: JSONSchema;
     prompt?: string;
     input?: Record<string, unknown>;
+    /**
+     * Whether interaction and custom-agent nodes receive the complete process
+     * context in addition to resolved `input`. Defaults to true for backward
+     * compatibility. Set false to keep specialist prompts input-only.
+     */
+    inherit_context?: boolean;
     config?: Record<string, unknown>;
     title?: string;
     description?: string;
@@ -147,6 +163,12 @@ export interface NodeDefinition {
     max_retries?: number;
     transitions?: TransitionDefinition[];
     tools?: string[];
+    /** Builtin system skills activated before the agent node's first model turn. */
+    initial_skills?: string[];
+    /** Execution-time tool denylist for the agent node's child conversation. */
+    excluded_tools?: string[];
+    /** Process-owned successful-tool phases and completion behavior for this agent node. */
+    agent_policy?: ProcessAgentExecutionPolicy;
     /**
      * Model id override for this node. If unset, falls back to the process
      * run's `config.model`, then to the project's default. Useful when a

package/src/store/schedule.test.ts

@@ -0,0 +1,59 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { AgentSchedule, CreateSchedulePayload, ScheduleListItem, UpdateSchedulePayload } from './schedule.js';
+
+describe('CreateSchedulePayload', () => {
+    it('accepts agent schedules without an explicit target', () => {
+        expectTypeOf({
+            run_as: { mode: 'creator' as const },
+            name: 'Weekly report',
+            interaction: 'WeeklyReportAgent',
+            cron_expression: '0 9 * * MON',
+        }).toMatchTypeOf<CreateSchedulePayload>();
+    });
+
+    it('accepts process schedules with context', () => {
+        expectTypeOf({
+            run_as: { mode: 'creator' as const },
+            name: 'Nightly refresh',
+            target: 'process' as const,
+            process: '68c01a23456789abcdef0123',
+            cron_expression: '0 2 * * *',
+            context: { collection: 'reports' },
+        }).toMatchTypeOf<CreateSchedulePayload>();
+    });
+
+    it('rejects a process schedule without a process definition', () => {
+        expectTypeOf({
+            run_as: { mode: 'creator' as const },
+            name: 'Nightly refresh',
+            target: 'process' as const,
+            cron_expression: '0 2 * * *',
+        }).not.toMatchTypeOf<CreateSchedulePayload>();
+    });
+});
+
+describe('schedule read models', () => {
+    it('report the configuration a process schedule fires with', () => {
+        // The gap this closes: execution worked, but nothing read back said what a process schedule
+        // ran with, so it could not be inspected or recreated from the API.
+        expectTypeOf<AgentSchedule['context']>().toEqualTypeOf<Record<string, unknown> | undefined>();
+        expectTypeOf<AgentSchedule['run_type']>().toEqualTypeOf<'programmatic' | 'supervised' | undefined>();
+    });
+
+    it('summarize run_type in a listing but not context', () => {
+        // `run_type` is a scalar, like `target`. `context` is caller-sized payload, so it stays out
+        // of the summary for the same reason `vars` does.
+        expectTypeOf<ScheduleListItem['run_type']>().toEqualTypeOf<'programmatic' | 'supervised' | undefined>();
+        expectTypeOf<ScheduleListItem>().not.toHaveProperty('context');
+        expectTypeOf<ScheduleListItem>().not.toHaveProperty('vars');
+    });
+
+    it('do not accept execution inputs on update', () => {
+        // These are fixed in the scheduler at creation and update does not re-publish the job
+        // specification, so accepting them would record a change that never takes effect.
+        expectTypeOf<UpdateSchedulePayload>().not.toHaveProperty('context');
+        expectTypeOf<UpdateSchedulePayload>().not.toHaveProperty('run_type');
+        expectTypeOf<UpdateSchedulePayload>().not.toHaveProperty('process');
+        expectTypeOf<UpdateSchedulePayload>().not.toHaveProperty('interaction');
+    });
+});

package/src/store/schedule.ts

@@ -1,14 +1,24 @@
 /**
- * Agent Schedule Types
+ * Schedule Types
  *
- * Defines types for scheduling agents to run on a recurring basis using cron expressions.
+ * Defines types for scheduling agents or processes to run on a recurring basis using cron expressions.
  * Schedules are stored in MongoDB with execution handled by Temporal.
  */
 
+import type { ProcessRunType } from './agent-run.js';
+
 /**
  * Represents a scheduled agent execution configuration.
  */
+export type ScheduleRunAs = { mode: 'creator' } | { mode: 'user'; user_id: string };
+
 export interface AgentSchedule {
+    owner?: string;
+    run_as?: ScheduleRunAs;
+    visibility?: 'project' | 'private';
+    delegation_grant_id?: string;
+    delegation_expires_at?: string | null;
+    output_collection_id?: string;
     /** Unique identifier for the schedule */
     id: string;
 
@@ -24,12 +34,30 @@ export interface AgentSchedule {
     /** Account ID this schedule belongs to */
     account: string;
 
+    /** The kind of workflow started by the schedule. Older agent schedules may omit this field. */
+    target?: 'agent' | 'process';
+
     /** Interaction ID or endpoint name to execute (e.g., "MyAgent" or ObjectId) */
-    interaction: string;
+    interaction?: string;
 
     /** Cached interaction name for display purposes */
     interaction_name?: string;
 
+    /** Process definition ID to execute */
+    process?: string;
+
+    /**
+     * Initial process context the schedule fires with, as supplied at creation. Process schedules
+     * only; the agent equivalent is `vars`.
+     */
+    context?: Record<string, unknown>;
+
+    /**
+     * Process execution mode the schedule fires with. Process schedules only. Absent on schedules
+     * created before this field was reported, which run as "programmatic".
+     */
+    run_type?: ProcessRunType;
+
     /**
      * Cron expression defining when to run.
      * Standard 5-field format: minute hour day-of-month month day-of-week
@@ -74,19 +102,16 @@ export interface AgentSchedule {
     next_run_at?: Date;
 }
 
-/**
- * Payload for creating a new schedule.
- */
-export interface CreateSchedulePayload {
+interface CreateSchedulePayloadBase {
+    run_as: ScheduleRunAs;
+    delegation_expires_at?: string | null;
+    request_id?: string;
     /** Human-readable name for the schedule */
     name: string;
 
     /** Optional description of what the schedule does */
     description?: string;
 
-    /** Interaction ID or endpoint name to execute */
-    interaction: string;
-
     /**
      * Cron expression defining when to run.
      * Standard 5-field format: minute hour day-of-month month day-of-week
@@ -96,23 +121,54 @@ export interface CreateSchedulePayload {
     /** Timezone for the cron expression (defaults to "UTC") */
     timezone?: string;
 
-    /** Variables to pass to the agent workflow */
-    vars?: Record<string, unknown>;
-
     /** Optional task queue override */
     task_queue?: string;
 
     /** Whether the schedule should be enabled immediately (defaults to true) */
     enabled?: boolean;
+}
+
+/** Payload for creating an agent schedule. */
+export interface CreateAgentSchedulePayload extends CreateSchedulePayloadBase {
+    /** Agent schedules are the default for backwards compatibility. */
+    target?: 'agent';
+
+    /** Interaction ID or endpoint name to execute */
+    interaction: string;
+
+    /** Variables to pass to the agent workflow */
+    vars?: Record<string, unknown>;
 
     /** Visibility of the conversation (defaults to "project") */
     visibility?: 'project' | 'private';
 }
 
+/** Payload for creating a process schedule. */
+export interface CreateProcessSchedulePayload extends CreateSchedulePayloadBase {
+    target: 'process';
+
+    /** Process definition ID to execute */
+    process: string;
+
+    /** Initial process context merged with the definition's initial context */
+    context?: Record<string, unknown>;
+
+    /** Process execution mode (defaults to "programmatic") */
+    run_type?: ProcessRunType;
+}
+
+/** Payload for creating a new schedule. */
+export type CreateSchedulePayload = CreateAgentSchedulePayload | CreateProcessSchedulePayload;
+
 /**
  * Payload for updating an existing schedule.
+ *
+ * Agent vars and delegation changes re-publish the execution specification. Process context,
+ * run_type, and task queues remain fixed at creation.
  */
 export interface UpdateSchedulePayload {
+    run_as?: ScheduleRunAs;
+    delegation_expires_at?: string | null;
     /** Updated name */
     name?: string;
 
@@ -138,20 +194,28 @@ export interface UpdateSchedulePayload {
 /**
  * Summary information for listing schedules.
  */
-export interface ScheduleListItem {
-    id: string;
-    name: string;
-    description?: string;
-    interaction: string;
-    interaction_name?: string;
-    cron_expression: string;
-    timezone?: string;
-    enabled: boolean;
-    last_run_at?: Date;
-    next_run_at?: Date;
-    created_by: string;
-    updated_at: Date;
-}
+export type ScheduleListItem = Pick<
+    AgentSchedule,
+    | 'owner'
+    | 'run_as'
+    | 'delegation_grant_id'
+    | 'delegation_expires_at'
+    | 'id'
+    | 'name'
+    | 'description'
+    | 'target'
+    | 'process'
+    | 'run_type'
+    | 'interaction'
+    | 'interaction_name'
+    | 'cron_expression'
+    | 'timezone'
+    | 'enabled'
+    | 'last_run_at'
+    | 'next_run_at'
+    | 'created_by'
+    | 'updated_at'
+>;
 
 /**
  * Extended schedule information including Temporal execution details.

package/src/store/workflow.ts

@@ -62,6 +62,8 @@ export interface Queue {
 export type WorkflowAncestor = z.infer<typeof WorkflowAncestorSchema>;
 
 export interface WorkflowExecutionBaseParams<T = Record<string, unknown>> {
+    /** Effective principal for private scheduled runs; server supplied. */
+    subject?: string;
     /**
      * The ref of the user who initiated the workflow.
      */