@vertesia/common 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260725.083715Z

package/src/interaction.ts

@@ -717,6 +717,21 @@ export {
 } from './email.js';
 // ================= end user communication channels ====================
 
+/**
+ * A tool invocation executed before the first model turn of a conversation.
+ * Results are injected into the initial context so the agent starts with them in hand.
+ */
+export interface InitialToolCall {
+    /** Stable identifier used to make initialization replay-safe. */
+    id: string;
+    /** Read-only builtin activity tool name. Skills are configured separately through initial_skills. */
+    tool: string;
+    /** Tool input parameters. */
+    input?: Record<string, unknown>;
+    /** Whether a failed initialization call aborts the conversation start. */
+    on_error?: 'fail' | 'continue';
+}
+
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
     type: 'conversation';
 
@@ -735,6 +750,28 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     tool_names?: string[];
 
+    /**
+     * Builtin system skills to activate at conversation start. Their related tools are
+     * exposed from the first turn and their instructions are injected into the initial
+     * context, replacing the learn_<skill> round-trip.
+     */
+    initial_skills?: string[];
+
+    /**
+     * Tool calls executed before the first model turn. Results are injected into the
+     * initial context. These run sequentially with the caller's authority before the
+     * first model turn. Only a bounded set of read/hydration tools is accepted.
+     */
+    initial_tool_calls?: InitialToolCall[];
+
+    /**
+     * 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.
+     */
+    excluded_tools?: string[];
+
     /**
      * The maximum number of iterations in case of a conversation. If <=0 the default of 20 will be used.
      */
@@ -973,6 +1010,52 @@ interface ResumeConversationPayload {
     asyncCompletion?: AsyncCompletionOptions;
 }
 
+/**
+ * The kinds of Vertesia resource an agent tool can report having created, updated, or deleted.
+ * Restricted to resources that have a real detail route to navigate to — do not emit a reference
+ * for a mutation with no meaningful navigation target. Add new kinds only once their route exists.
+ */
+export type AgentResourceType =
+    | 'document'
+    | 'collection'
+    | 'content_type'
+    | 'interaction'
+    | 'prompt'
+    | 'agent'
+    | 'workflow'
+    | 'process'
+    | 'process_run'
+    | 'interaction_run'
+    | 'view';
+
+export type AgentResourceAction = 'created' | 'updated' | 'deleted';
+
+/**
+ * A navigable reference to a resource an agent tool mutated. Tools return these as tool-result
+ * metadata (see {@link ToolResultMeta.resources}); the conversation runtime promotes them onto the
+ * tool's completed lifecycle message so the UI can render deterministic deep links and an
+ * end-of-turn "resources changed" summary — independent of any link the model writes in prose.
+ */
+export interface AgentResourceReference {
+    type: AgentResourceType;
+    /** The resource id used to build its detail route. */
+    id: string;
+    /** Human-readable label captured at mutation time (e.g. the document name). */
+    label: string;
+    action: AgentResourceAction;
+    /** Set when the mutation produced a new revision, enabling a "view changes" affordance. */
+    revision_id?: string;
+}
+
+/**
+ * Metadata a tool executor may attach to its result. Kept as an open record for forward
+ * compatibility while typing the fields the runtime interprets.
+ */
+export interface ToolResultMeta extends Record<string, unknown> {
+    /** Resources this tool created/updated/deleted, surfaced as deep links in the UI. */
+    resources?: AgentResourceReference[];
+}
+
 export interface ToolResultContent {
     content: string;
     /**
@@ -992,7 +1075,54 @@ export interface ToolResultContent {
     /**
      * Can contain metadata returned by the tool executor.
      */
-    meta?: Record<string, unknown>;
+    meta?: ToolResultMeta;
+}
+
+const AGENT_RESOURCE_TYPES: readonly AgentResourceType[] = [
+    'document',
+    'collection',
+    'content_type',
+    'interaction',
+    'prompt',
+    'agent',
+    'workflow',
+    'process',
+    'process_run',
+    'interaction_run',
+    'view',
+];
+
+const AGENT_RESOURCE_ACTIONS: readonly AgentResourceAction[] = ['created', 'updated', 'deleted'];
+
+/**
+ * Validate and normalize an untrusted value into a clean list of resource references. References
+ * cross the wire and may originate from external/MCP tools, so malformed entries are dropped
+ * rather than throwing, and an empty/absent label falls back to the id.
+ */
+export function normalizeAgentResources(value: unknown): AgentResourceReference[] {
+    if (!Array.isArray(value)) return [];
+    const result: AgentResourceReference[] = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== 'object') continue;
+        const ref = entry as Record<string, unknown>;
+        const { type, id, label, action, revision_id } = ref;
+        if (typeof type !== 'string' || !AGENT_RESOURCE_TYPES.includes(type as AgentResourceType)) continue;
+        if (typeof id !== 'string' || id.length === 0) continue;
+        if (typeof action !== 'string' || !AGENT_RESOURCE_ACTIONS.includes(action as AgentResourceAction)) continue;
+        result.push({
+            type: type as AgentResourceType,
+            id,
+            label: typeof label === 'string' && label.length > 0 ? label : id,
+            action: action as AgentResourceAction,
+            ...(typeof revision_id === 'string' && revision_id.length > 0 ? { revision_id } : {}),
+        });
+    }
+    return result;
+}
+
+/** Extract the normalized resource references a tool declared in its result metadata. */
+export function getResourcesFromToolResult(result: Pick<ToolResultContent, 'meta'>): AgentResourceReference[] {
+    return normalizeAgentResources(result.meta?.resources);
 }
 
 export interface ToolResult extends ToolResultContent {
@@ -1196,6 +1326,10 @@ export interface InteractionExecutionConfiguration {
     run_data?: RunDataStorageLevel;
     configMode?: ConfigModes;
     model_options?: ModelOptions;
+    /** Stable provider-side routing key for automatic prompt caching. */
+    prompt_cache_key?: string;
+    /** Put the result schema after the cached prefix; Vertesia still validates the returned JSON against it. */
+    prompt_cache_schema_suffix?: boolean;
     /** Per-run HTTP timeouts for upstream LLM-provider calls. */
     http_timeout?: HttpTimeoutOptions;
 }

package/src/platform-event.ts

@@ -3,6 +3,7 @@ import type { ConversationVisibility, InteractionExecutionConfiguration } from '
 import type { SystemRoles } from './project.js';
 import type {
     AgentRunStatus,
+    GroundedVerificationBreakdown,
     JsonLogicRule,
     ProcessDefinitionBody,
     ProcessRunType,
@@ -81,12 +82,44 @@ export interface PlatformEvent extends EventRef {
  */
 export type WorkflowLifecycleAction = 'workflow_completed' | 'workflow_failed';
 
+export interface DocumentProcessingModelUsage {
+    role: 'extraction' | 'review';
+    run_id: string;
+    model?: string;
+    environment_id?: string;
+    provider?: string;
+}
+
+/** Compact, content-free operational summary emitted after grounded IDP completes. */
+export interface DocumentProcessedEventData {
+    schema_version: 1;
+    pipeline: 'grounded_extraction';
+    object_id: string;
+    page_count: number;
+    ocr_page_count: number;
+    vision_page_count: number;
+    property_count: number;
+    citation_count: number;
+    verification: GroundedVerificationBreakdown;
+    result_path: string;
+    confidence?: number;
+    coverage_min?: number;
+    hardness?: number;
+    escalated?: boolean;
+    reviewed?: boolean;
+    review_issue_count?: number;
+    verdict?: 'good_to_go' | 'needs_review';
+    verdict_reason?: string;
+    models_used?: DocumentProcessingModelUsage[];
+    review_agent_run_id?: string;
+}
+
 /**
  * Resource flavor of a workflow lifecycle event, derived from the Temporal workflow type:
  * ExecuteConversationWorkflow -> agent_run, ExecuteProcessWorkflow -> process_run,
- * anything else -> workflow_run.
+ * document-scoped workflows may use content_object, and anything else -> workflow_run.
  */
-export type WorkflowLifecycleResourceType = 'workflow_run' | 'agent_run' | 'process_run';
+export type WorkflowLifecycleResourceType = 'workflow_run' | 'agent_run' | 'process_run' | 'content_object';
 
 /**
  * Body of POST /internal/events/publish (zeno-server, workload-identity gated). Sent by Temporal
@@ -98,6 +131,8 @@ export interface PublishWorkflowLifecycleEventRequest {
     project_id: string;
     action: WorkflowLifecycleAction;
     resource_type: WorkflowLifecycleResourceType;
+    /** Domain resource the workflow acted on. Defaults to workflow_id for workflow-scoped events. */
+    resource_id?: string;
     workflow_id: string;
     workflow_run_id: string;
     workflow_type: string;
@@ -110,6 +145,8 @@ export interface PublishWorkflowLifecycleEventRequest {
     error?: string;
     /** EventRef of the event that started the workflow (payload.vars.event_ref), if any. */
     caused_by?: EventRef;
+    /** Optional IDP outcome published as a separate, subscribable content event. */
+    document_processed?: DocumentProcessedEventData;
 }
 
 /**

package/src/project.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { validateProjectSearchPropertyMappings } from './project.js';
+
+describe('validateProjectSearchPropertyMappings', () => {
+    it('accepts supported leaf mappings on relative property paths', () => {
+        expect(
+            validateProjectSearchPropertyMappings({
+                order_total: { type: 'double', ignore_malformed: true },
+                release_date: {
+                    type: 'date',
+                    format: 'strict_date_optional_time||yyyy-MM-dd',
+                    ignore_malformed: true,
+                },
+                'customer.account_number': { type: 'keyword', ignore_above: 128 },
+            }),
+        ).toEqual([]);
+    });
+
+    it('rejects unsupported mapping options and types', () => {
+        const issues = validateProjectSearchPropertyMappings({
+            order_total: { type: 'scaled_float', scaling_factor: 100 },
+            release_date: { type: 'keyword', format: 'yyyy-MM-dd' },
+            customer: { type: 'keyword', ignore_malformed: true },
+        });
+
+        expect(issues).toEqual(
+            expect.arrayContaining([
+                expect.stringContaining('unsupported option(s): scaling_factor'),
+                expect.stringContaining('type must be one of'),
+                expect.stringContaining('format is supported only for date mappings'),
+                expect.stringContaining('ignore_malformed is supported only for long, double, and date mappings'),
+            ]),
+        );
+    });
+
+    it('allows parent and child leaf mappings for subobjects:false indexes', () => {
+        expect(
+            validateProjectSearchPropertyMappings({
+                customer: { type: 'keyword' },
+                'customer.name': { type: 'keyword' },
+            }),
+        ).toEqual([]);
+    });
+});

package/src/project.ts

@@ -1,7 +1,9 @@
 import type { JSONSchemaType } from 'ajv';
 import type { SupportedIntegrations } from './integrations.js';
+import type { ContentTypeIntakePolicy, IntakeVisionDetail, IntakeVisionProfileSettings } from './store/store.js';
 import type { WorkflowRunStatus } from './store/workflow.js';
 import type { AccountRef } from './user.js';
+import { ELASTICSEARCH_FIELD_PATH_PATTERN } from './view-validation-helpers.js';
 
 export interface ICreateProjectPayload {
     name: string;
@@ -125,6 +127,7 @@ export const SYSTEM_INTERACTION_CATEGORIES: Record<string, SystemInteractionCate
     Mediator: SystemInteractionCategory.non_applicable,
     AnalyzeConversation: SystemInteractionCategory.analysis,
     GetAgentConversationTopic: SystemInteractionCategory.analysis,
+    ContentSearchAgent: SystemInteractionCategory.analysis,
     StudioAssistant: SystemInteractionCategory.agent,
 };
 
@@ -269,7 +272,70 @@ export const BrowserUseProjectConfigurationSchema: JSONSchemaType<BrowserUseProj
 export type ProjectSearchTier = 'standard' | 'performance';
 export type ElasticsearchBackend = 'serverless' | 'hosted';
 
+/**
+ * Fast pre-conversion type identification (the "sniff") for untyped documents.
+ * The sniff classifies a document from cheap local evidence (first/last page text,
+ * a low-res first-page image, office docProps) BEFORE any conversion, so a
+ * high-confidence match can apply the type's intake policy — including skipping
+ * conversion — without paying for it first.
+ */
+export interface ProjectIntakeSniffConfiguration {
+    /**
+     * Enable the pre-conversion sniff for untyped documents. Defaults to true.
+     * Can be overridden per run with the `sniffEnabled` workflow var.
+     */
+    enabled?: boolean;
+
+    /**
+     * Confidence at or above which the sniffed type is committed and its full policy applied
+     * (including conversion-skip). 0..1, defaults to 0.85.
+     */
+    high_confidence?: number;
+
+    /**
+     * Confidence at or above which the sniffed type is treated as provisional: the document
+     * still converts and the post-conversion selector confirms on neutral evidence.
+     * 0..1, defaults to 0.6. Below this the sniff result is advisory provenance only.
+     */
+    medium_confidence?: number;
+
+    /**
+     * Minimum page count for the sniff LLM call. Below this, conversion is cheap and full
+     * converted text is better selection evidence, so intake uses the standard
+     * convert-then-select path. Documents with unknown page counts are sniffed.
+     * Defaults to 5; 0 means always sniff.
+     */
+    min_pages?: number;
+}
+
 export interface ProjectIntakeConfiguration {
+    /**
+     * Master switch for the standard intake pipeline. When false, StandardIntake exits as a
+     * no-op WITHOUT touching object status (objects stay in `created`, identifiable as
+     * unprocessed). Defaults to true.
+     */
+    enabled?: boolean;
+
+    /**
+     * Fast pre-conversion type identification for untyped documents. Absent means enabled
+     * with platform default thresholds.
+     */
+    sniff?: ProjectIntakeSniffConfiguration;
+
+    /**
+     * Project-level intake policy defaults. Same shape as the per-content-type policy; a
+     * type's `intake` block wins field-by-field over these defaults, which in turn win over
+     * the legacy flat fields below. `identification` is type-specific and ignored here.
+     */
+    default_policy?: ContentTypeIntakePolicy;
+
+    /**
+     * Project overrides for the platform vision detail profiles used by intake visual
+     * extraction (`low`/`standard`/`high`). Partial: omitted profiles or fields inherit the
+     * platform defaults. Types reference detail NAMES only; the profile settings live here.
+     */
+    vision_profiles?: Partial<Record<IntakeVisionDetail, Partial<IntakeVisionProfileSettings>>>;
+
     /**
      * Generate table-of-content sections during standard document intake.
      * Defaults to false.
@@ -331,28 +397,7 @@ export interface ProjectConfiguration {
      * Indexing configuration for this project.
      * Controls whether indexing and querying are enabled at the project level.
      */
-    indexing?: {
-        /**
-         * Enable indexing for content objects in this project.
-         * When enabled, content changes trigger indexing workflows.
-         * Defaults to true - indexing is always on when ES infrastructure is available.
-         */
-        enabled?: boolean;
-
-        /**
-         * Search tier for this project.
-         * standard uses the regional hosted Elasticsearch deployment.
-         * performance uses the regional serverless Elasticsearch project.
-         * Defaults to standard when omitted.
-         */
-        search_tier?: ProjectSearchTier;
-
-        /**
-         * Elasticsearch backend override for this project.
-         * Prefer search_tier for project configuration unless an explicit backend override is needed.
-         */
-        backend?: ElasticsearchBackend;
-    };
+    indexing?: ProjectIndexingConfiguration;
 
     /**
      * Standard content intake behavior.
@@ -382,6 +427,142 @@ export interface ProjectConfiguration {
     pdf_template_object_id?: string;
 }
 
+/**
+ * Elasticsearch field types that may be explicitly assigned to content-object
+ * properties. Paths are relative to the object's `properties` field.
+ */
+export type ProjectSearchPropertyType = 'keyword' | 'text' | 'boolean' | 'long' | 'double' | 'date';
+
+/**
+ * Explicit search mapping for one content-object property.
+ *
+ * Changing a mapping requires a full reindex. Existing Elasticsearch fields
+ * cannot change type in place.
+ */
+export interface ProjectSearchPropertyMapping {
+    type: ProjectSearchPropertyType;
+
+    /** Elasticsearch date format. Valid only when type is `date`. */
+    format?: string;
+
+    /** Maximum indexed string length. Valid only when type is `keyword`. */
+    ignore_above?: number;
+
+    /**
+     * Skip malformed values instead of rejecting the whole document. Valid only
+     * for long, double, and date mappings.
+     */
+    ignore_malformed?: boolean;
+}
+
+export const PROJECT_SEARCH_PROPERTY_TYPES: readonly ProjectSearchPropertyType[] = [
+    'keyword',
+    'text',
+    'boolean',
+    'long',
+    'double',
+    'date',
+];
+
+const MAX_PROJECT_SEARCH_PROPERTY_MAPPINGS = 200;
+const MAX_KEYWORD_IGNORE_ABOVE = 8191;
+
+/**
+ * Validate property mappings at API and index-creation boundaries.
+ *
+ * Returns user-facing issue strings instead of throwing so callers can map the
+ * result to the error type appropriate for their boundary.
+ */
+export function validateProjectSearchPropertyMappings(value: unknown): string[] {
+    if (value === undefined) return [];
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return ['indexing.property_mappings must be an object keyed by property path'];
+    }
+
+    const entries = Object.entries(value as Record<string, unknown>);
+    const issues: string[] = [];
+    if (entries.length > MAX_PROJECT_SEARCH_PROPERTY_MAPPINGS) {
+        issues.push(`indexing.property_mappings must contain at most ${MAX_PROJECT_SEARCH_PROPERTY_MAPPINGS} fields`);
+    }
+
+    const supportedTypes = new Set<string>(PROJECT_SEARCH_PROPERTY_TYPES);
+    for (const [path, rawMapping] of entries) {
+        const field = `indexing.property_mappings.${path}`;
+        if (!ELASTICSEARCH_FIELD_PATH_PATTERN.test(path)) {
+            issues.push(`${field} must be a dot-separated path containing only letters, numbers, and underscores`);
+        }
+        if (!rawMapping || typeof rawMapping !== 'object' || Array.isArray(rawMapping)) {
+            issues.push(`${field} must be an object`);
+            continue;
+        }
+        const mapping = rawMapping as Record<string, unknown>;
+        const extraKeys = Object.keys(mapping).filter(
+            (key) => !['type', 'format', 'ignore_above', 'ignore_malformed'].includes(key),
+        );
+        if (extraKeys.length > 0) {
+            issues.push(`${field} contains unsupported option(s): ${extraKeys.join(', ')}`);
+        }
+        if (typeof mapping.type !== 'string' || !supportedTypes.has(mapping.type)) {
+            issues.push(`${field}.type must be one of: ${PROJECT_SEARCH_PROPERTY_TYPES.join(', ')}`);
+        }
+        if (mapping.format !== undefined && (mapping.type !== 'date' || typeof mapping.format !== 'string')) {
+            issues.push(`${field}.format is supported only for date mappings`);
+        }
+        if (
+            mapping.ignore_above !== undefined &&
+            (mapping.type !== 'keyword' ||
+                !Number.isInteger(mapping.ignore_above) ||
+                (mapping.ignore_above as number) < 1 ||
+                (mapping.ignore_above as number) > MAX_KEYWORD_IGNORE_ABOVE)
+        ) {
+            issues.push(
+                `${field}.ignore_above is supported only for keyword mappings and must be an integer from 1 to ${MAX_KEYWORD_IGNORE_ABOVE}`,
+            );
+        }
+        if (
+            mapping.ignore_malformed !== undefined &&
+            (!['long', 'double', 'date'].includes(String(mapping.type)) ||
+                typeof mapping.ignore_malformed !== 'boolean')
+        ) {
+            issues.push(`${field}.ignore_malformed is supported only for long, double, and date mappings`);
+        }
+    }
+    return issues;
+}
+
+export interface ProjectIndexingConfiguration {
+    /**
+     * Enable indexing for content objects in this project.
+     * When enabled, content changes trigger indexing workflows.
+     * Defaults to true - indexing is always on when ES infrastructure is available.
+     */
+    enabled?: boolean;
+
+    /**
+     * Search tier for this project.
+     * standard uses the regional hosted Elasticsearch deployment.
+     * performance uses the regional serverless Elasticsearch project.
+     * Defaults to standard when omitted.
+     */
+    search_tier?: ProjectSearchTier;
+
+    /**
+     * Elasticsearch backend override for this project.
+     * Prefer search_tier for project configuration unless an explicit backend override is needed.
+     */
+    backend?: ElasticsearchBackend;
+
+    /**
+     * Explicit mappings for selected content-object property paths.
+     *
+     * Keys are dot-separated paths relative to `properties`, for example
+     * `order_total` or `customer.account_number`. Unlisted fields are mapped
+     * dynamically from their JSON values. Changing this value requires a full
+     * reindex.
+     */
+    property_mappings?: Record<string, ProjectSearchPropertyMapping>;
+}
+
 // export interface ProjectConfigurationEmbeddings {
 //     environment: string;
 //     max_tokens: number;
@@ -937,6 +1118,8 @@ export interface IndexConfiguration {
     };
     /** ISO 639-1 language code for text analysis */
     language?: string;
+    /** Explicit mappings for selected content-object property paths. */
+    property_mappings?: Record<string, ProjectSearchPropertyMapping>;
     field_mappings?: Record<string, unknown>;
     project_embeddings_config?: {
         text?: EmbeddingTypeConfig;

package/src/query.ts

@@ -88,6 +88,12 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     model?: string;
     status?: ExecutionRunStatus;
     tags?: string[];
+    /**
+     * Tags to exclude. Runs carrying any of these tags are filtered out of the results,
+     * counts, and facet buckets. Combined with `tags` (which requires all of the listed
+     * tags) as an additional `$nin` constraint on the same field.
+     */
+    exclude_tags?: string[];
     query?: string;
     default_query_path?: string;
     parent?: string[];

package/src/refs.ts

@@ -21,6 +21,7 @@ export interface ResourceRef {
     id: string;
     name: string;
     type: string;
+    email?: string;
     description?: string;
     version?: number;
     status?: string;