@vertesia/common 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

package/src/api-schemas/schema-primitives.ts

@@ -10,3 +10,16 @@ export const nullableNumberSchema = z
     .number()
     .nullable()
     .meta({ anyOf: undefined, type: ['number', 'null'] });
+
+/** Monotonic token for optimistic concurrency on mutable, user-authored resources. */
+export const EditRevisionSchema = z
+    .number()
+    .int()
+    .min(1)
+    .meta({ description: 'Monotonic edit revision used to detect concurrent updates.' });
+
+/** Revision a caller last observed and expects to replace. */
+export const ExpectedEditRevisionSchema = EditRevisionSchema.optional().meta({
+    description:
+        'Edit revision returned by the last read. Stale revisions are rejected with HTTP 409. Omit for legacy last-write-wins behavior.',
+});

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

@@ -374,6 +374,11 @@ describe('runtime tightenings — recorded as operation 25 of the 1.5 runbook',
         // carrying an undeclared key there is now rejected at write time.
         expect(ApiSchemaComponents.InteractionExecutionConfiguration.additionalProperties).toBe(false);
         expect(validate({ extraction: { config: { model: 'claude-sonnet-4-5' } } }), errors()).toBe(true);
+        expect(
+            validate({ extraction: { config: { prompt_cache_mode: 'required', prompt_cache_ttl_seconds: 3600 } } }),
+            errors(),
+        ).toBe(true);
+        expect(validate({ extraction: { config: { prompt_cache_ttl_seconds: 59 } } })).toBe(false);
         expect(validate({ extraction: { config: { temperature: 0.5 } } })).toBe(false);
         expect(validate({ extraction: { config: { http_timeout: { socketTimeout: 1000 } } } })).toBe(false);
     });
@@ -430,7 +435,7 @@ describe('the five content-type shapes are composed, not repeated', () => {
         // Order is contract: it decides the order of the generated clients' constructor arguments and
         // model fields. The five orders differ because they were derived from five different types.
         expect(properties('ContentObjectTypeItem')).toEqual(properties('ContentObjectType'));
-        expect(properties('ContentObjectTypeCatalogEntry').slice(0, 11)).toEqual(properties('InCodeTypeDefinition'));
+        expect(properties('ContentObjectTypeCatalogEntry').slice(0, 12)).toEqual(properties('InCodeTypeDefinition'));
         expect(properties('CreateContentObjectTypePayload')).toEqual([
             'status',
             'is_chunkable',
@@ -468,4 +473,28 @@ describe('the five content-type shapes are composed, not repeated', () => {
             }).valid,
         ).toBe(true);
     });
+
+    it('publishes `title` on the app-contribution shapes and withholds it from the stored ones', () => {
+        // An app package contributes a display title alongside the app-local `name`, exactly as
+        // `InCodeViewDefinition` and `InCodeProcessDefinition` do. Only the two shapes that carry a
+        // contribution get it; a type someone stored through the API has no `title` to publish.
+        for (const shape of ['InCodeTypeDefinition', 'ContentObjectTypeCatalogEntry']) {
+            expect(property(shape, 'title'), `${shape} should publish title`).toBeDefined();
+        }
+        for (const shape of ['ContentObjectTypeItem', 'ContentObjectType', 'CreateContentObjectTypePayload']) {
+            expect(property(shape, 'title'), `${shape} should not publish title`).toBeUndefined();
+        }
+    });
+
+    it('accepts an app-contributed type that carries a title', () => {
+        // The regression: deployed app packages send `title`, the shape was strict and did not
+        // declare it, so every `GET /projects/:projectId/app-types` failed its own response contract.
+        expect(
+            validateApiResponse('InCodeTypeDefinition', {
+                id: 'invoice',
+                name: 'invoice',
+                title: 'Invoice',
+            }).valid,
+        ).toBe(true);
+    });
 });

package/src/api-schemas/store.ts

@@ -1,7 +1,8 @@
-import { HttpTimeoutOptionsSchema, ModelOptionsSchema } from '@llumiverse/common/schemas';
+import { HttpTimeoutOptionsSchema, ModelOptionsSchema, PromptCacheModeSchema } from '@llumiverse/common/schemas';
 import { z } from 'zod';
 // From the values module, for the reason `./apikey.js` gives.
 import { ConfigModes, RunDataStorageLevel } from '../interaction-values.js';
+import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
 
 /**
  * Runtime API schemas for the content-intake policy tree.
@@ -87,6 +88,21 @@ export const InteractionExecutionConfigurationSchema = z
             .string()
             .optional()
             .meta({ description: 'Stable provider-side routing key for automatic prompt caching.' }),
+        prompt_cache_mode: PromptCacheModeSchema.optional().meta({
+            description:
+                'Controls provider-side explicit caching: auto falls back safely, off disables it, and required ' +
+                'surfaces cache preparation failures for diagnostics.',
+        }),
+        prompt_cache_ttl_seconds: z
+            .number()
+            .int()
+            .min(60)
+            .optional()
+            .meta({
+                description:
+                    'Caller-selected explicit cache lifetime in seconds. Defaults remain provider-specific; ' +
+                    'Vertex Gemini requires at least 60 seconds.',
+            }),
         prompt_cache_schema_suffix: z
             .boolean()
             .optional()
@@ -396,7 +412,10 @@ export const ColumnLayoutSchema = z
                     'The type of the field specifies how the rendering will be done. If not specified the string type will be used. The type may contain additional parameters prepended using a web-like query string syntax: date?LLL',
             })
             .optional(),
-        fallback: z.string().optional(),
+        fallback: z
+            .string()
+            .meta({ description: 'Path of an alternate field to display when the primary field is absent' })
+            .optional(),
         default: z
             .unknown()
             .meta({ description: 'A default value to be used if the field is not present in the object' })
@@ -442,17 +461,22 @@ const contentTypeFields = {
         .looseObject({})
         .meta({
             description:
-                'this is only included in ContentObjectTypeItem if explicitly requested It is always included in ContentObjectType',
+                'JSON Schema for the structured properties extracted into documents of this type. ' +
+                'Only included in ContentObjectTypeItem if explicitly requested; always included in ContentObjectType.',
         })
         .optional(),
     table_layout: z
         .array(ColumnLayoutSchema)
         .meta({
             description:
-                'This is only included in ContentObjectTypeItem if explicitly requested It is always included in ContentObjectType',
+                'Column layout used when listing documents of this type. ' +
+                'Only included in ContentObjectTypeItem if explicitly requested; always included in ContentObjectType.',
         })
         .optional(),
-    is_chunkable: z.boolean().optional(),
+    is_chunkable: z
+        .boolean()
+        .meta({ description: 'Whether documents of this type can be split into chunks' })
+        .optional(),
     strict_mode: z
         .boolean()
         .meta({
@@ -463,6 +487,23 @@ const contentTypeFields = {
     status: ContentObjectTypeStatusSchema.optional(),
     intake: ContentTypeIntakePolicySchema.optional(),
     editing: ContentTypeEditingPolicySchema.optional(),
+    /**
+     * Display title, as every OTHER app-contribution shape already publishes it:
+     * `InCodeViewDefinition`, `InCodeProcessDefinition` and `AppDashboardDefinition` all pair the
+     * app-local `name` used for lookup with an optional human-readable `title`. A contributed type
+     * was the one shape missing it, so deployed app packages sent `title` into a `strictObject` that
+     * forbade it and `GET /projects/:projectId/app-types` and `GET /types/catalog` failed their own
+     * response contract on every call.
+     *
+     * Appended last on purpose: property order decides the generated clients' constructor argument
+     * order, so a new field goes on the end rather than next to `name` where it reads better.
+     *
+     * Note this key reaches only the two shapes that spread the whole dictionary —
+     * `InCodeTypeDefinition` and `ContentObjectTypeCatalogEntry`, the two that carry app
+     * contributions. The stored shapes and the create payload list their keys explicitly, so a
+     * stored type still has no `title`.
+     */
+    title: z.string().meta({ description: 'Display title. Defaults to `name` or `id`.' }).optional(),
 };
 
 /**
@@ -492,6 +533,9 @@ export const ContentObjectTypeCatalogEntrySchema = z
     .strictObject({
         ...contentTypeFields,
         ...catalogAuditFields,
+        edit_revision: EditRevisionSchema.optional().meta({
+            description: 'Stored-resource revision. Omitted for app-contributed in-code types.',
+        }),
     })
     .meta({ id: 'ContentObjectTypeCatalogEntry' });
 
@@ -509,6 +553,7 @@ export const ContentObjectTypeCatalogEntryArraySchema = z
  */
 const storedContentTypeShape = {
     id: contentTypeFields.id,
+    edit_revision: EditRevisionSchema,
     name: contentTypeFields.name,
     description: contentTypeFields.description,
     tags: contentTypeFields.tags,
@@ -564,12 +609,14 @@ export const CreateContentObjectTypePayloadSchema = z
  * the fields it changes, which is what `.partial()` says and what the handler has always done. The
  * property order is the create payload's, so the generated clients' argument order does not move.
  */
-export const UpdateContentObjectTypePayloadSchema = CreateContentObjectTypePayloadSchema.partial().meta({
-    id: 'UpdateContentObjectTypePayload',
-    description:
-        'Fields to change on a content object type. Every field is optional — only the ones present ' +
-        'are written, and the rest are left as they are.',
-});
+export const UpdateContentObjectTypePayloadSchema = CreateContentObjectTypePayloadSchema.partial()
+    .extend({ expected_edit_revision: ExpectedEditRevisionSchema })
+    .meta({
+        id: 'UpdateContentObjectTypePayload',
+        description:
+            'Fields to change on a content object type. Only fields present are written; ' +
+            'expected_edit_revision prevents overwriting a concurrent edit.',
+    });
 
 export const ContentObjectTypeSchema = z.strictObject(storedContentTypeShape).meta({ id: 'ContentObjectType' });
 

package/src/api-schemas/tools.ts

@@ -1,4 +1,6 @@
+import { JSONSchemaSchema } from '@llumiverse/common/schemas';
 import { z } from 'zod';
+import { AgentToolApprovalClassSchema } from './app-lifecycle.js';
 import { MCPToolAnnotationsSchema } from './apps.js';
 
 // The unified project-scoped tool registry as `GET /tools` and `POST /tools/validate` publish it.
@@ -13,6 +15,30 @@ export const ToolSourceSchema = z.enum(['builtin', 'app', 'interaction']).meta({
         'Origin of a tool in the unified project-scoped tool registry.\n\n- `builtin`: anything statically registered on the worker — workflow builtins, studio agent tools, and sys skills\n- `app`: tools contributed by an installed app for the project\n- `interaction`: a project interaction exposed via `tag=tool` / `is_tool=true` / `is_skill=true`\n\nSkill semantics (the tool unlocks others when invoked) are NOT part of the source. They are identified universally by the `learn_` prefix in the tool name. This matches how the runtime registry stores them and avoids splitting one logical origin into two sources.',
 });
 
+export const ToolRuntimeContextSchema = z.enum(['conversation', 'process']).meta({
+    id: 'ToolRuntimeContext',
+    description: 'The runtime context in which a caller intends to use a tool.',
+});
+
+export const ProcessToolCompatibilityReasonSchema = z
+    .enum([
+        'skill_not_supported',
+        'interaction_not_supported',
+        'agent_not_supported',
+        'confirmation_not_supported',
+        'control_tool_not_supported',
+        'approval_metadata_unavailable',
+        'ambiguous_name',
+    ])
+    .meta({ id: 'ProcessToolCompatibilityReason' });
+
+export const ProcessToolCompatibilitySchema = z
+    .strictObject({
+        compatible: z.boolean(),
+        reason: ProcessToolCompatibilityReasonSchema.optional(),
+    })
+    .meta({ id: 'ProcessToolCompatibility' });
+
 export const ValidateToolNamesPayloadSchema = z
     .strictObject({
         names: z.array(z.string()).meta({
@@ -76,6 +102,8 @@ export const AggregatedToolSchema = z
             })
             .optional(),
         annotations: MCPToolAnnotationsSchema.optional(),
+        approval_class: AgentToolApprovalClassSchema.optional(),
+        process_compatibility: ProcessToolCompatibilitySchema.optional(),
         unlocked_tools: z
             .array(z.string())
             .meta({ description: 'For skills (`learn_*`): tool names this skill unlocks when invoked.' })
@@ -126,6 +154,39 @@ export const ValidateToolNamesResponseSchema = z
 
 export const AggregatedToolArraySchema = z.array(AggregatedToolSchema).meta({ id: 'AggregatedToolArray' });
 
+export const InspectProjectToolQuerySchema = z
+    .strictObject({ context: ToolRuntimeContextSchema.optional() })
+    .meta({ id: 'InspectProjectToolQuery' });
+
+export const ToolInspectionSchema = z
+    .strictObject({
+        name: z.string(),
+        source: ToolSourceSchema,
+        description: z.string().optional(),
+        title: z.string().optional(),
+        input_schema: JSONSchemaSchema.optional().meta({
+            description: 'Exact input schema when the provider supplied one. Omitted rather than fabricated.',
+        }),
+        output_schema: JSONSchemaSchema.optional().meta({
+            description:
+                'MCP outputSchema advertised by the provider. It does not describe the process node result transport.',
+        }),
+        output_contract_status: z
+            .enum(['provider_supplied', 'unknown'])
+            .meta({
+                description:
+                    'For app tools, whether the provider advertised output schema metadata. Omitted for builtin and interaction tools.',
+            })
+            .optional(),
+        approval_class: AgentToolApprovalClassSchema.optional(),
+        annotations: MCPToolAnnotationsSchema.optional(),
+        app_install_id: z.string().optional(),
+        app_name: z.string().optional(),
+        ready: z.boolean().meta({ description: 'True only when an exact input schema was resolved.' }),
+        process_compatibility: ProcessToolCompatibilitySchema.optional(),
+    })
+    .meta({ id: 'ToolInspection' });
+
 // Query contracts are registry components even though the scanner expands them into parameters.
 export const ListProjectToolsQuerySchema = z
     .strictObject({
@@ -136,5 +197,6 @@ export const ListProjectToolsQuerySchema = z
                 description: 'Drop these sources from the result (and skip their fetch). Applied after `sources`.',
             })
             .optional(),
+        context: ToolRuntimeContextSchema.optional(),
     })
     .meta({ id: 'ListProjectToolsQuery' });

package/src/api-schemas/view-execution.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 import type { ViewNavigationNode } from '../views.js';
 import { ContentObjectItemApiResponseSchema } from './content.js';
 import { StringArrayMapSchema } from './dashboard.js';
+import { StringValueMapSchema } from './files.js';
 import * as ViewSchemas from './views.js';
 
 const ViewSearchFieldDefinitionSchema = ViewSchemas.ViewSearchFieldDefinitionSchema;
@@ -49,6 +50,9 @@ export const ExecuteViewRequestSchema = z
         query: z.string().optional(),
         key_terms: StringArrayMapSchema.optional(),
         navigation: StringArrayMapSchema.optional(),
+        navigation_queries: StringValueMapSchema.meta({
+            description: 'Server-side text filters for large navigation sources, keyed by navigation id.',
+        }).optional(),
         display: z.string().optional(),
         sort: z.string().optional(),
         offset: z.number().optional(),
@@ -65,9 +69,13 @@ export const ViewNavigationResultSchema = z
         id: z.string(),
         selected: z.array(z.string()),
         nodes: z.array(ViewNavigationNodeSchema),
+        query: z
+            .string()
+            .meta({ description: 'Applied server-side node filter, when the navigation source supports it.' })
+            .optional(),
         breadcrumbs: z
             .array(ViewNavigationNodeSchema)
-            .meta({ description: 'Selected hierarchy path from its root through the current value.' })
+            .meta({ description: 'Selected drill-down path from its root through the current value.' })
             .optional(),
         truncated: z.boolean().optional(),
     })
@@ -87,6 +95,20 @@ export const ViewExecutionQueryPlanSchema = z
             'Safe query-planning diagnostics. The query contains only the model-authored subtree; server-owned scope and content-security filters are never exposed.',
     });
 
+export const ViewRerankFailureCodeSchema = z
+    .enum(['interaction_failed', 'invalid_output', 'timeout', 'unknown'])
+    .meta({ id: 'ViewRerankFailureCode' });
+
+export const ViewExecutionRerankResultSchema = z
+    .strictObject({
+        status: z.enum(['applied', 'fallback', 'skipped']),
+        candidate_count: z.number(),
+        skip_reason: z.enum(['not_enough_candidates', 'query_fallback', 'explicit_sort', 'configured_sort']).optional(),
+        error_code: ViewRerankFailureCodeSchema.optional(),
+        error_message: z.string().optional(),
+    })
+    .meta({ id: 'ViewExecutionRerankResult' });
+
 export const ViewExecutionSearchConfigurationSchema = z
     .strictObject({
         renderer: z.string().optional(),
@@ -116,8 +138,9 @@ export const ViewExecutionSearchResultSchema = z
         interpretation: z.string().optional(),
         key_terms: StringArrayMapSchema.optional(),
         plan: ViewExecutionQueryPlanSchema.optional(),
+        rerank: ViewExecutionRerankResultSchema.optional(),
         requested_mode: z.enum(['browse', 'deterministic', 'agentic']),
-        applied_mode: z.enum(['browse', 'deterministic', 'query']),
+        applied_mode: z.enum(['browse', 'deterministic', 'query', 'query_and_view']),
         fallback_reason: z.string().optional(),
         warnings: z.array(ViewExecutionWarningSchema),
     })
@@ -185,6 +208,9 @@ export const PreviewViewExperienceRequestSchema = z
         query: z.string().optional(),
         key_terms: StringArrayMapSchema.optional(),
         navigation: StringArrayMapSchema.optional(),
+        navigation_queries: StringValueMapSchema.meta({
+            description: 'Server-side text filters for large navigation sources, keyed by navigation id.',
+        }).optional(),
         display: z.string().optional(),
         sort: z.string().optional(),
         offset: z.number().optional(),

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

@@ -0,0 +1,119 @@
+import { assertType, describe, expect, it } from 'vitest';
+import type { z } from 'zod';
+import { type ViewExperienceConfiguration, viewExperienceRoute } from '../views.js';
+import { ApiSchemaComponents, validateApiRequest, validateApiResponse } from './registry.js';
+import type { ViewExperienceConfigurationSchema } from './view-execution.js';
+
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+/**
+ * Lives here rather than next to the JSON Schema artifact that consumes it. Both subjects are
+ * declarations of THIS package — the public TypeScript type and the Zod schema it must mirror — and
+ * asserting it from the consuming package would have made that package depend on Zod, which it must
+ * not: it is loaded in the browser.
+ */
+describe('ViewExperienceConfiguration', () => {
+    it('keeps the temporary named TypeScript bridge identical to the runtime schema', () => {
+        assertType<Equals<ViewExperienceConfiguration, z.infer<typeof ViewExperienceConfigurationSchema>>>(true);
+    });
+
+    it('publishes selection, app actions, upload drops, generated presentation mode, and reranking', () => {
+        expect(Object.keys(ApiSchemaComponents)).toEqual(
+            expect.arrayContaining([
+                'AgenticViewRerankConfiguration',
+                'ViewActionConfiguration',
+                'ViewActionsConfiguration',
+                'ViewDropConfiguration',
+                'ViewExecutionRerankResult',
+                'ViewSelectionConfiguration',
+            ]),
+        );
+
+        expect(
+            validateApiRequest('PreviewViewExperienceRequest', {
+                configuration: {
+                    name: 'Orders',
+                    search: {
+                        mode: 'agentic',
+                        agentic: {
+                            mode: 'query_and_view',
+                            rerank: { max_candidates: 24, include_why_match: true, timeout_ms: 30_000 },
+                        },
+                    },
+                    results: {
+                        default_display: 'table',
+                        displays: [{ id: 'table', label: 'Orders', type: 'table', columns: [] }],
+                        selection: { mode: 'multiple', select_all: 'page' },
+                        actions: {
+                            include_defaults: true,
+                            items: [{ id: 'approve', label: 'Approve', handler: 'approve-orders' }],
+                        },
+                        drop: { handler: 'upload', accept: ['files'], params: { type_id: 'sales-order' } },
+                    },
+                },
+            }).valid,
+        ).toBe(true);
+    });
+
+    it('keeps executable custom drop handlers out of the persisted wire contract', () => {
+        expect(
+            validateApiRequest('PreviewViewExperienceRequest', {
+                configuration: {
+                    name: 'Orders',
+                    results: {
+                        default_display: 'table',
+                        displays: [{ id: 'table', label: 'Orders', type: 'table', columns: [] }],
+                        drop: { handler: 'custom-drop' },
+                    },
+                },
+            }).valid,
+        ).toBe(false);
+    });
+
+    it('accepts View model options that name no driver, while the shared config still requires one', () => {
+        // The regression: a View's `model_options` are authored in the editor and saved before any
+        // driver is resolved, so they carry no `_option_id`. Validating them against the
+        // `ModelOptions` driver union — every branch of which requires that discriminator — meant a
+        // stored View could not satisfy its own response schema, and `GET /views` logged a contract
+        // violation on every call.
+        const authored = { model_options: { temperature: 0.2, max_tokens: 1024 } };
+        expect(validateApiResponse('ViewAgenticExecutionConfiguration', authored).valid).toBe(true);
+
+        // The split is the point: agent runs, events and workflow runs record options a driver
+        // already resolved, so the shared component keeps the union. Asserted on the published
+        // schema because `InteractionExecutionConfiguration` is not itself a response slot — if it
+        // ever stops pointing at `ModelOptions`, the relaxation leaked out of Views.
+        const modelOptions = (name: string) =>
+            (ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties.model_options;
+        expect(modelOptions('InteractionExecutionConfiguration')).toEqual({
+            $ref: '#/components/schemas/ModelOptions',
+        });
+        expect(modelOptions('ViewAgenticExecutionConfiguration')).toMatchObject({
+            type: 'object',
+            additionalProperties: true,
+        });
+    });
+
+    it('keeps the View config otherwise identical to the shared execution configuration', () => {
+        // Only `model_options` may differ. Anything else diverging means the two drifted apart
+        // rather than the union being deliberately relaxed for authored options.
+        const properties = (name: string) =>
+            (ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties;
+        const view = properties('ViewAgenticExecutionConfiguration');
+        const shared = properties('InteractionExecutionConfiguration');
+
+        expect(Object.keys(view)).toEqual(Object.keys(shared));
+        for (const key of Object.keys(shared)) {
+            if (key === 'model_options') continue;
+            expect(JSON.stringify(view[key]), `${key} drifted from the shared configuration`).toBe(
+                JSON.stringify(shared[key]),
+            );
+        }
+    });
+
+    it('builds generic routes for system and app-contributed Views without exposing path material', () => {
+        expect(viewExperienceRoute('app:content:document-library')).toBe('/view/app%3Acontent%3Adocument-library');
+        expect(viewExperienceRoute('sys:AgenticDocumentExplorer')).toBe('/view/sys%3AAgenticDocumentExplorer');
+        expect(viewExperienceRoute('unsafe/id')).toBe('/view/unsafe%2Fid');
+    });
+});

package/src/api-schemas/views.ts

@@ -1,5 +1,14 @@
+import { JSONObjectSchema } from '@llumiverse/common/schemas';
 import { z } from 'zod';
-import { VIEW_EXPERIENCE_SCHEMA_VERSION, VIEW_RESULT_FIELD_FORMATS, VIEW_SEARCH_FIELD_TYPES } from '../views.js';
+import {
+    VIEW_ACTION_PLACEMENTS,
+    VIEW_ACTION_SELECTION_REQUIREMENTS,
+    VIEW_AGENTIC_SEARCH_MODES,
+    VIEW_EXPERIENCE_SCHEMA_VERSION,
+    VIEW_RESULT_FIELD_FORMATS,
+    VIEW_SEARCH_FIELD_TYPES,
+    VIEW_SELECTION_MODES,
+} from '../views.js';
 import { InteractionExecutionConfigurationSchema } from './store.js';
 
 // The view experiences a project publishes: the search, navigation, results and display
@@ -54,17 +63,68 @@ export const ViewTableColumnSchema = z
     })
     .meta({ id: 'ViewTableColumn' });
 
+export const ViewAgenticSearchModeSchema = z.enum(VIEW_AGENTIC_SEARCH_MODES).meta({ id: 'ViewAgenticSearchMode' });
+
+export const AgenticViewRerankConfigurationSchema = z
+    .strictObject({
+        interaction: z
+            .string()
+            .meta({
+                description: 'Interaction used only for candidate reranking. Defaults to sys:ContentSearchReranker.',
+            })
+            .optional(),
+        max_candidates: z
+            .number()
+            .meta({ description: 'Maximum candidates from the current result page sent to the model.' })
+            .optional(),
+        include_why_match: z
+            .boolean()
+            .meta({ description: 'Ask the model for a short per-result explanation. Defaults to true.' })
+            .optional(),
+        timeout_ms: z.number().meta({ description: 'Reranking-stage timeout.' }).optional(),
+    })
+    .meta({ id: 'AgenticViewRerankConfiguration' });
+
+/**
+ * The model configuration a View stores for its agentic search.
+ *
+ * Identical to `InteractionExecutionConfiguration` apart from `model_options`, which is an open
+ * object here rather than the `ModelOptions` driver union. A View's options are authored in the view
+ * editor and saved before any driver is chosen, so they carry no `_option_id`; every branch of the
+ * union requires one, so a stored View could not satisfy it and `GET /views` failed its own response
+ * contract on every call.
+ *
+ * Only the View usage changes. The shared component keeps the strict union because agent runs,
+ * events and workflow runs record options a driver already resolved, and those are in production.
+ */
+export const ViewAgenticExecutionConfigurationSchema = InteractionExecutionConfigurationSchema.extend({
+    model_options: z
+        .looseObject({})
+        .meta({
+            description:
+                'Model options as authored for this View. Open rather than the driver-discriminated ' +
+                '`ModelOptions` union, because a View is saved before a driver is resolved.',
+        })
+        .optional(),
+}).meta({ id: 'ViewAgenticExecutionConfiguration' });
+
 export const AgenticViewSearchConfigurationSchema = z
     .strictObject({
         interaction: z.string().optional(),
-        config: InteractionExecutionConfigurationSchema.optional(),
+        config: ViewAgenticExecutionConfigurationSchema.optional(),
         instructions: z
             .string()
             .meta({ description: 'View-specific guidance for Elasticsearch query planning.' })
             .optional(),
-        mode: z.literal('query').optional(),
+        mode: ViewAgenticSearchModeSchema.meta({
+            description: 'Generate only Elasticsearch DSL, or generate DSL plus a safe ephemeral result presentation.',
+        }).optional(),
         timeout_ms: z.number().optional(),
         minimum_confidence: z.number().optional(),
+        rerank: AgenticViewRerankConfigurationSchema.meta({
+            description:
+                'Optional second stage that reorders an authorized candidate page using the same model configuration.',
+        }).optional(),
     })
     .meta({ id: 'AgenticViewSearchConfiguration' });
 
@@ -357,6 +417,82 @@ export const ViewDisplayConfigurationSchema = z
     ])
     .meta({ id: 'ViewDisplayConfiguration', type: 'object' });
 
+export const ViewSelectionModeSchema = z.enum(VIEW_SELECTION_MODES).meta({ id: 'ViewSelectionMode' });
+
+export const ViewSelectionConfigurationSchema = z
+    .strictObject({
+        mode: ViewSelectionModeSchema,
+        select_all: z
+            .literal('page')
+            .meta({ description: 'Select-all applies to the currently rendered page.' })
+            .optional(),
+    })
+    .meta({
+        id: 'ViewSelectionConfiguration',
+        description: 'Client-side selection behavior for normalized View hits.',
+    });
+
+export const ViewActionPlacementSchema = z.enum(VIEW_ACTION_PLACEMENTS).meta({ id: 'ViewActionPlacement' });
+
+export const ViewActionSelectionRequirementSchema = z
+    .enum(VIEW_ACTION_SELECTION_REQUIREMENTS)
+    .meta({ id: 'ViewActionSelectionRequirement' });
+
+export const ViewActionConfigurationSchema = z
+    .strictObject({
+        id: z.string(),
+        label: z.string(),
+        handler: z.string(),
+        placement: ViewActionPlacementSchema.optional(),
+        requires_selection: ViewActionSelectionRequirementSchema.optional(),
+        destructive: z.boolean().optional(),
+        confirm: z.boolean().optional(),
+        params: JSONObjectSchema.optional(),
+    })
+    .meta({
+        id: 'ViewActionConfiguration',
+        description:
+            'Declarative action exposed by a View. The handler name is resolved by the embedding application; persisted configuration never contains executable code.',
+    });
+
+export const ViewActionsConfigurationSchema = z
+    .strictObject({
+        include_defaults: z
+            .boolean()
+            .meta({
+                description:
+                    'Include the standard content export and delete actions. Defaults to true when selection is enabled.',
+            })
+            .optional(),
+        exclude_defaults: z
+            .array(z.enum(['export', 'delete']))
+            .meta({ description: 'Hide individual standard actions while keeping the remaining defaults.' })
+            .optional(),
+        items: z.array(ViewActionConfigurationSchema).optional(),
+    })
+    .meta({ id: 'ViewActionsConfiguration' });
+
+export const ViewUploadDropParametersSchema = z
+    .strictObject({
+        type_id: z.string().optional(),
+        collection_id: z.string().optional(),
+        location: z.string().optional(),
+        properties: JSONObjectSchema.optional(),
+        allow_folders: z.boolean().optional(),
+    })
+    .meta({ id: 'ViewUploadDropParameters' });
+
+export const ViewDropConfigurationSchema = z
+    .strictObject({
+        handler: z.literal('upload'),
+        accept: z.array(z.literal('files')).optional(),
+        params: ViewUploadDropParametersSchema.optional(),
+    })
+    .meta({
+        id: 'ViewDropConfiguration',
+        description: 'A declarative result-area drop target. Stored JSON supports the built-in upload action only.',
+    });
+
 export const ViewResultsConfigurationSchema = z
     .strictObject({
         default_display: z.string(),
@@ -364,6 +500,9 @@ export const ViewResultsConfigurationSchema = z
         displays: z.array(ViewDisplayConfigurationSchema),
         default_sort: z.string().optional(),
         sort_options: z.array(ViewSortOptionSchema).optional(),
+        selection: ViewSelectionConfigurationSchema.optional(),
+        actions: ViewActionsConfigurationSchema.optional(),
+        drop: ViewDropConfigurationSchema.optional(),
     })
     .meta({ id: 'ViewResultsConfiguration' });