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

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

@@ -32,6 +32,9 @@ describe('the provider vocabulary', () => {
         expect(validateApiRequest('ExecutionEnvironmentCreatePayload', { name: 'e', provider: 'openai' }).valid).toBe(
             true,
         );
+        expect(
+            validateApiRequest('ExecutionEnvironmentCreatePayload', { name: 'router', provider: 'openrouter' }).valid,
+        ).toBe(true);
         expect(validateApiRequest('ExecutionEnvironmentCreatePayload', { name: 'e', provider: 'gpt' }).valid).toBe(
             false,
         );

package/src/api-schemas/index.ts

@@ -31,6 +31,7 @@ export * from './integrations.js';
 export * from './oauth-server.js';
 export * from './parameters.js';
 export * from './process.js';
+export * from './process-agent-policy.js';
 export * from './quota.js';
 export * from './registry.js';
 export * from './secrets.js';

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

@@ -93,6 +93,29 @@ describe('AsyncConversationExecutionPayload contract', () => {
         });
     });
 
+    it('accepts Process-authored agent execution policy', () => {
+        const payload: AsyncConversationExecutionPayload = {
+            type: 'conversation',
+            interaction: 'sys:AppDeveloper',
+            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' }],
+                action_phase_count: 1,
+                action_phase_max_tokens: 4_096,
+                completion_prompt: 'Return the structured result now.',
+            },
+        };
+
+        expect(AsyncConversationExecutionPayloadSchema.parse(payload)).toMatchObject(payload);
+    });
+
     it('rejects a non-string app-version target', () => {
         expect(() =>
             AsyncConversationExecutionPayloadSchema.parse({

package/src/api-schemas/interaction.ts

@@ -25,6 +25,7 @@ import { LlmCallType } from '../workflow-analytics.js';
 import { ProjectRefSchema } from './apikey.js';
 import { ExecutionEnvironmentRefSchema } from './environment.js';
 import { AccountRefSchema } from './invites.js';
+import { ProcessAgentExecutionPolicySchema } from './process-agent-policy.js';
 import { AgentCheckpointConfigurationSchema } from './project-configuration.js';
 import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema, RunDataStorageLevelSchema } from './store.js';
@@ -1392,7 +1393,14 @@ export const GeneratedInteractionDefinitionArraySchema = z
 export const PendingToolApprovalResultsSchema = z
     .strictObject({
         results: z.array(ToolResultSchema),
-        reason: z.enum(['denied', 'denied_with_feedback', 'timeout', 'reviewer_denied']),
+        reason: z.enum([
+            'denied',
+            'denied_with_feedback',
+            'timeout',
+            'reviewer_denied',
+            'user_interrupted_after_tool_execution',
+            'user_stopped_after_tool_execution',
+        ]),
         message: z.string(),
         created_at: z.string(),
     })
@@ -1670,7 +1678,7 @@ export const ConversationStateSchema = z
             description: 'Run-scoped, exact-target grants created by "allow this action for this run".',
         }).optional(),
         pending_tool_approval_results: PendingToolApprovalResultsSchema.meta({
-            description: 'Buffered tool results held while approval denial pauses until the next user message.',
+            description: 'Buffered tool results held across an interactive pause until the next user message.',
         }).optional(),
         latest_user_message: z
             .string()
@@ -2207,6 +2215,10 @@ export const AsyncConversationExecutionPayloadSchema = z
                     'Hard denylist of tool names for this conversation. Excluded tools are never exposed to the model and are refused at execution time, even when a skill or tool refresh would otherwise unlock them. Takes precedence over tool_names, initial_skills, and skill-based tool activation.',
             })
             .optional(),
+        agent_policy: ProcessAgentExecutionPolicySchema.meta({
+            description:
+                'Process-authored successful-tool phases enforced by this child conversation. Ordinary conversation callers should leave this unset.',
+        }).optional(),
         max_iterations: z
             .number()
             .meta({
@@ -2479,8 +2491,8 @@ export const ExecutionResponseSchema = z
     .strictObject({
         result: z.array(CompletionResultSchema),
         token_usage: ExecutionTokenUsageSchema.optional(),
-        prompt_cache_diagnostic: PromptCacheDiagnosticSchema.optional(),
         service_tier: z.string().meta({ description: 'Processing tier actually used by the provider' }).optional(),
+        prompt_cache_diagnostic: PromptCacheDiagnosticSchema.optional(),
         tool_use: z.array(ToolUseSchema).optional(),
         finish_reason: z.string().optional(),
         error: z

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

@@ -42,6 +42,7 @@ const UNION_MEMBERS = [
     'BedrockMantleClaudeOptions',
     'OpenAiThinkingOptions',
     'OpenAiTextOptions',
+    'OpenRouterTextOptions',
     'OpenAiDalleOptions',
     'OpenAiGptImageOptions',
     'XAIGrokImageOptions',
@@ -95,21 +96,14 @@ describe('the ModelOptions closure is published whole and enforced closed', () =
             JSON.stringify(validate.errors),
         ).toBe(true);
         expect(validate({ _option_id: 'not-a-driver' })).toBe(false);
-    });
-
-    it('allows provider-specific objects only inside OpenAI-compatible extra_body', () => {
-        const validate = compile('ModelOptions');
         expect(
             validate({
                 _option_id: 'openai-text',
-                extra_body: {
-                    provider: { sort: 'throughput', allow_fallbacks: false },
-                    baseten: { performance: 'max' },
-                },
+                extra_body: { provider: { sort: 'throughput' }, baseten: { performance: 'max' } },
             }),
             JSON.stringify(validate.errors),
         ).toBe(true);
-        expect(validate({ _option_id: 'openai-text', extra_body: ['invalid'] })).toBe(false);
+        expect(validate({ _option_id: 'openai-text', extra_body: ['not-an-object'] })).toBe(false);
     });
 
     it('accepts Gemini Omni task and resolution options through the run request contract', () => {

package/src/api-schemas/oauth-server.ts

@@ -115,6 +115,10 @@ export const OAuthAuthorizationRequestSchema = z
             .string()
             .optional()
             .meta({ description: 'Owning account enforced when restrict_to_owner_account is true.' }),
+        consent_required: z.boolean().optional().meta({
+            description:
+                'False when the authorization server has determined this client may be approved without showing a consent screen. Absent or true means consent must be collected from the user. Granted scopes are clamped to the user permissions by the server in either case, so this controls only whether the user is prompted.',
+        }),
         status: OAuthAuthorizationRequestStatusSchema,
         created_at: z.string(),
         expires_at: z.string(),

package/src/api-schemas/process-agent-policy.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+
+export const ProcessAgentToolInputContainsSchema = z
+    .strictObject({
+        field: z.string().min(1).meta({ description: 'Top-level tool-input field to inspect.' }),
+        contains: z.string().min(1).meta({ description: 'Case-sensitive substring required in the string field.' }),
+        not_contains: z
+            .array(z.string().min(1))
+            .min(1)
+            .meta({ description: 'Case-sensitive substrings forbidden in the same string field.' })
+            .optional(),
+        min_length: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({ description: 'Minimum string length required for the same field.' })
+            .optional(),
+    })
+    .meta({ id: 'ProcessAgentToolInputContains' });
+
+export const ProcessAgentToolPhaseSchema = z
+    .strictObject({
+        id: z.string().min(1),
+        tools: z
+            .array(z.string().min(1))
+            .min(1)
+            .meta({ description: 'Any successful tool in this list advances the phase.' }),
+        continuation_tools: z
+            .array(z.string().min(1))
+            .min(1)
+            .meta({
+                description:
+                    'Additional tools authorized while the phase is active. Successful calls do not advance the phase.',
+            })
+            .optional(),
+        recovery_tools: z
+            .array(z.string().min(1))
+            .min(1)
+            .meta({
+                description:
+                    'Additional tools authorized only after a matching phase tool fails. Successful calls do not advance the phase.',
+            })
+            .optional(),
+        tool_input_contains: z
+            .array(ProcessAgentToolInputContainsSchema)
+            .min(1)
+            .meta({
+                description:
+                    'All declared top-level string-field presence, absence, and minimum-length checks must match before a tool call is authorized or advances the phase.',
+            })
+            .optional(),
+        min_successes: z
+            .number()
+            .int()
+            .positive()
+            .meta({ description: 'Successful matching calls required to advance. Defaults to one.' })
+            .optional(),
+        max_tokens: z
+            .number()
+            .int()
+            .positive()
+            .meta({ description: 'Optional output-token ceiling for model turns while this action phase is active.' })
+            .optional(),
+        recovery_prompt: z.string().min(1).meta({
+            description: 'Process-authored instruction used when the agent tries to finish during this phase.',
+        }),
+    })
+    .meta({ id: 'ProcessAgentToolPhase' });
+
+export const ProcessAgentPhaseResetSchema = z
+    .strictObject({
+        tools: z
+            .array(z.string().min(1))
+            .min(1)
+            .meta({ description: 'Successful tools that invalidate later phase progress.' }),
+        tool_input_contains: z
+            .array(ProcessAgentToolInputContainsSchema)
+            .min(1)
+            .meta({ description: 'Optional input checks applied to the invalidating tool call.' })
+            .optional(),
+        to_phase: z.string().min(1).meta({ description: 'Phase id that must be completed next after invalidation.' }),
+    })
+    .meta({ id: 'ProcessAgentPhaseReset' });
+
+export const ProcessAgentExecutionPolicySchema = z
+    .strictObject({
+        phases: z
+            .array(ProcessAgentToolPhaseSchema)
+            .min(1)
+            .meta({ description: 'Ordered successful-tool phases the agent node must complete.' }),
+        phase_resets: z
+            .array(ProcessAgentPhaseResetSchema)
+            .min(1)
+            .meta({
+                description:
+                    'Successful tool calls that invalidate prior progress and reset execution to a declared phase.',
+            })
+            .optional(),
+        defer_result_schema_until_complete: z
+            .boolean()
+            .meta({ description: 'Hide the node result schema from model calls until every declared phase completes.' })
+            .optional(),
+        restrict_to_phase_tools: z
+            .boolean()
+            .meta({
+                description:
+                    'Expose one stable union of declared phase tools to the model, and reject tool calls that do not satisfy the current phase. This preserves prompt-cache stability while enforcing ordered execution.',
+            })
+            .optional(),
+        action_phase_count: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({
+                description:
+                    'Number of leading phases whose model turns require a tool call. Defaults to zero and cannot exceed phases.length.',
+            })
+            .optional(),
+        action_phase_max_tokens: z
+            .number()
+            .int()
+            .positive()
+            .meta({ description: 'Maximum output tokens while an action phase is active.' })
+            .optional(),
+        max_recovery_attempts_per_phase: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({ description: 'Bounded recovery turns allowed per incomplete phase. Defaults to one.' })
+            .optional(),
+        max_failed_tool_iterations: z
+            .number()
+            .int()
+            .positive()
+            .meta({
+                description:
+                    'Run-wide budget of repeated model iterations containing failed tool results before the agent node stops. The first failing iteration establishes model-visible recovery evidence and is not charged; phase transitions do not reset the budget. Defaults to eight.',
+            })
+            .optional(),
+        max_failed_tool_iterations_per_phase: z
+            .number()
+            .int()
+            .positive()
+            .meta({
+                description:
+                    'Optional per-phase budget of corrective model iterations that still contain failed tool results. The first failure in each phase establishes recovery evidence and is not charged.',
+            })
+            .optional(),
+        max_repeated_tool_failure_iterations: z
+            .number()
+            .int()
+            .positive()
+            .meta({
+                description:
+                    'Optional number of repeated normalized failure fingerprints allowed in one phase before the agent node stops. A value of one stops after the first corrective iteration repeats an already observed cause.',
+            })
+            .optional(),
+        completion_prompt: z
+            .string()
+            .min(1)
+            .meta({
+                description:
+                    'Process-authored instruction appended to the final successful tool result. That turn restores the result schema and requires the agent to return its result without another tool call.',
+            })
+            .optional(),
+    })
+    .meta({ id: 'ProcessAgentExecutionPolicy' });

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

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+import { ProcessRunConfigSchema, RecordProcessRunPayloadSchema } from './process.js';
+import { ProcessAgentExecutionPolicySchema } from './process-agent-policy.js';
+
+describe('ProcessRunConfigSchema', () => {
+    it('accepts validated LLM execution configuration and retains a strict Process boundary', () => {
+        expect(
+            ProcessRunConfigSchema.parse({
+                environment: 'openrouter-environment',
+                model: 'openai/gpt-5.6-sol',
+                model_options: { _option_id: 'openrouter-text', service_tier: 'flex' },
+            }),
+        ).toEqual({
+            environment: 'openrouter-environment',
+            model: 'openai/gpt-5.6-sol',
+            model_options: { _option_id: 'openrouter-text', service_tier: 'flex' },
+        });
+        expect(() =>
+            ProcessRunConfigSchema.parse({ environment: 'openrouter-environment', unexpected: true }),
+        ).toThrow();
+    });
+});
+
+describe('RecordProcessRunPayloadSchema', () => {
+    it('accepts schedule metadata for workflow-owned process runs', () => {
+        expect(
+            RecordProcessRunPayloadSchema.parse({
+                workflow_id: 'ProcessRun:scheduled',
+                first_workflow_run_id: 'temporal-run',
+                run_kind: 'process',
+                process_id: '68c01a23456789abcdef0123',
+                schedule_id: 'schedule-1',
+                type: 'schedule',
+            }),
+        ).toMatchObject({ schedule_id: 'schedule-1', type: 'schedule' });
+    });
+});
+
+describe('ProcessAgentExecutionPolicySchema', () => {
+    it('accepts cache-stable phase tool enforcement and retains a strict boundary', () => {
+        expect(
+            ProcessAgentExecutionPolicySchema.parse({
+                phases: [
+                    {
+                        id: 'inspect',
+                        tools: ['app_workspace_typecheck'],
+                        continuation_tools: ['app_workspace_read'],
+                        recovery_tools: ['app_workspace_read', 'app_workspace_edit'],
+                        tool_input_contains: [
+                            {
+                                field: 'command',
+                                contains: 'pnpm run test:unit',
+                                not_contains: ['|'],
+                                min_length: 18,
+                            },
+                        ],
+                        max_tokens: 12_288,
+                        recovery_prompt: 'Inspect source.',
+                    },
+                ],
+                restrict_to_phase_tools: true,
+                max_failed_tool_iterations: 3,
+                max_failed_tool_iterations_per_phase: 2,
+                max_repeated_tool_failure_iterations: 1,
+            }),
+        ).toMatchObject({
+            phases: [
+                {
+                    tools: ['app_workspace_typecheck'],
+                    continuation_tools: ['app_workspace_read'],
+                    recovery_tools: ['app_workspace_read', 'app_workspace_edit'],
+                    tool_input_contains: [
+                        {
+                            field: 'command',
+                            contains: 'pnpm run test:unit',
+                            not_contains: ['|'],
+                            min_length: 18,
+                        },
+                    ],
+                    max_tokens: 12_288,
+                },
+            ],
+            restrict_to_phase_tools: true,
+            max_failed_tool_iterations: 3,
+            max_failed_tool_iterations_per_phase: 2,
+            max_repeated_tool_failure_iterations: 1,
+        });
+        expect(() =>
+            ProcessAgentExecutionPolicySchema.parse({
+                phases: [{ id: 'inspect', tools: ['app_workspace_read'], recovery_prompt: 'Inspect source.' }],
+                restrict_to_phase_tools: true,
+                unexpected: true,
+            }),
+        ).toThrow();
+        expect(() =>
+            ProcessAgentExecutionPolicySchema.parse({
+                phases: [
+                    {
+                        id: 'inspect',
+                        tools: ['app_workspace_read'],
+                        tool_input_contains: [{ field: 'path', contains: 'src/', not_contains: [], min_length: -1 }],
+                        recovery_prompt: 'Inspect source.',
+                    },
+                ],
+            }),
+        ).toThrow();
+        expect(() =>
+            ProcessAgentExecutionPolicySchema.parse({
+                phases: [{ id: 'inspect', tools: ['app_workspace_read'], recovery_prompt: 'Inspect source.' }],
+                max_failed_tool_iterations_per_phase: 0,
+                max_repeated_tool_failure_iterations: 0,
+            }),
+        ).toThrow();
+    });
+});

package/src/api-schemas/process.ts

@@ -1,11 +1,13 @@
 // Runtime schemas for the process API domain.
 
-import { JSONObjectSchema, JSONSchemaSchema } from '@llumiverse/common/schemas';
+import { JSONObjectSchema, JSONSchemaSchema, ModelOptionsSchema } from '@llumiverse/common/schemas';
 import type { StringValue } from 'ms';
 import { z } from 'zod';
 import { PermissionSchema } from './access-control.js';
+import { AgentRunTypeSchema } from './app-lifecycle.js';
 import { StringValueMapSchema } from './files.js';
 import { ConversationVisibilitySchema, RunSourceSchema } from './interaction.js';
+import { ProcessAgentExecutionPolicySchema } from './process-agent-policy.js';
 import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
 import { TaskFieldSchema } from './task.js';
 
@@ -176,7 +178,14 @@ export const ProcessDefinitionRevisionInfoSchema = z
 
 export const ProcessRunConfigSchema = z
     .strictObject({
+        environment: z
+            .string()
+            .meta({ description: 'Execution environment id used by Process LLM nodes and the supervisor.' })
+            .optional(),
         model: z.string().optional(),
+        model_options: ModelOptionsSchema.meta({
+            description: 'Validated model options applied to Process LLM nodes and the supervisor.',
+        }).optional(),
         user_message: z
             .string()
             .meta({
@@ -827,6 +836,13 @@ export const NodeDefinitionSchema: z.ZodType = z
         }).optional(),
         prompt: z.string().optional(),
         input: z.looseObject({}).optional(),
+        inherit_context: z
+            .boolean()
+            .meta({
+                description:
+                    'Whether interaction and custom-agent nodes receive the complete process context in addition to resolved input. Defaults to true; set false for input-only specialist prompts.',
+            })
+            .optional(),
         config: z.looseObject({}).optional(),
         title: z.string().optional(),
         description: z.string().optional(),
@@ -842,6 +858,18 @@ export const NodeDefinitionSchema: z.ZodType = z
         max_retries: z.number().optional(),
         transitions: z.array(TransitionDefinitionSchema).optional(),
         tools: z.array(z.string()).optional(),
+        initial_skills: z
+            .array(z.string())
+            .meta({ description: "Builtin system skills activated before the agent node's first model turn." })
+            .optional(),
+        excluded_tools: z
+            .array(z.string())
+            .meta({ description: "Execution-time tool denylist for the agent node's child conversation." })
+            .optional(),
+        agent_policy: ProcessAgentExecutionPolicySchema.meta({
+            description:
+                'Declarative successful-tool phases and completion behavior for this agent node. The Process owns this policy; the child conversation enforces it generically.',
+        }).optional(),
         model: z
             .string()
             .meta({
@@ -958,6 +986,8 @@ export const RecordProcessRunPayloadSchema = z
         first_workflow_run_id: z.string().optional(),
         run_kind: z.literal('process'),
         run_type: ProcessRunTypeSchema.optional(),
+        schedule_id: z.string().optional(),
+        type: AgentRunTypeSchema.optional(),
         process_id: z.string().optional(),
         process_version: z.number().optional(),
         process_definition: ProcessDefinitionBodySchema.optional(),

package/src/api-schemas/project-configuration.ts

@@ -67,11 +67,12 @@ export const ProjectSearchTierSchema = z.enum(['standard', 'performance']).meta(
 export const ElasticsearchBackendSchema = z.enum(['serverless', 'hosted']).meta({ id: 'ElasticsearchBackend' });
 
 export const ProjectSearchPropertyTypeSchema = z
-    .enum(['keyword', 'text', 'boolean', 'long', 'double', 'date', 'geo_point'])
+    .enum(['keyword', 'text', 'boolean', 'long', 'double', 'date', 'geo_point', 'nested'])
     .meta({
         id: 'ProjectSearchPropertyType',
         description:
-            'Elasticsearch field types that may be explicitly assigned to content-object properties. Paths are ' +
+            'Elasticsearch field types that may be explicitly assigned to content-object properties. ' +
+            'Declare nested object-array paths with type `nested` and their children as separate dotted paths. Paths are ' +
             "relative to the object's `properties` field.",
     });
 

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

@@ -253,6 +253,21 @@ describe('gate 2 — the closure is closed, bottom-up', () => {
         });
     });
 
+    it('accepts explicit nested paths through the project configuration contract', () => {
+        expect(ApiSchemaComponents.ProjectSearchPropertyType.enum).toContain('nested');
+        expect(
+            validateApiRequest('UpdateProjectConfigurationPayload', {
+                indexing: {
+                    property_mappings: {
+                        line_items: { type: 'nested' },
+                        'line_items.sku': { type: 'keyword' },
+                        'line_items.quantity': { type: 'long' },
+                    },
+                },
+            }).valid,
+        ).toBe(true);
+    });
+
     it('publishes geo_point as an explicit project property mapping type', () => {
         expect(ApiSchemaComponents.ProjectSearchPropertyType.enum).toContain('geo_point');
     });