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

package/src/store/workflow.ts

@@ -1,12 +1,15 @@
 import type { ExecutionTokenUsage, HttpTimeoutOptions, ModelOptions } from '@llumiverse/common';
 import type {
+    AgentResourceReference,
     ConversationVisibility,
     InteractionExecutionConfiguration,
     InteractionRef,
     UserChannel,
 } from '../interaction.js';
+import { normalizeAgentResources } from '../interaction.js';
 import type { JSONObject, JSONValue } from '../json.js';
 import type { JSONSchema } from '../json-schema.js';
+import type { SupportedEmbeddingTypes } from '../project.js';
 import type { AgentToolApprovalMode } from './agent-approval.js';
 import type { WorkflowInput } from './dsl-workflow.js';
 
@@ -769,6 +772,8 @@ export interface AgentMessageDetails extends Record<string, unknown> {
     outputFiles?: string[];
     files?: ConversationFile[] | string[];
     plan?: PlanTask[];
+    /** Deep-linkable references to resources a tool created/updated/deleted (see AgentResourceReference). */
+    resources?: AgentResourceReference[];
     streaming_id?: string;
     streaming_id_scope?: 'workflow_run' | 'workstream';
     chunk_index?: number;
@@ -845,6 +850,11 @@ export function isToolCallMessage(msg: AgentMessage): msg is AgentMessage & { de
     );
 }
 
+/** Extract the normalized resource references carried on a message's details, if any. */
+export function getResourcesFromMessage(msg: AgentMessage): AgentResourceReference[] {
+    return normalizeAgentResources((msg.details as AgentMessageDetails | undefined)?.resources);
+}
+
 export function isDocumentEventMessage(msg: AgentMessage): msg is AgentMessage & { details: DocumentEventDetails } {
     const details = msg.details as Record<string, unknown> | undefined;
     return (
@@ -1391,6 +1401,8 @@ export interface AgentIntakeWorkflowResult {
     collectionIds?: string[];
     /** Whether embeddings were generated */
     hasEmbeddings: boolean;
+    /** Embedding kinds that were actually generated. Skipped or failed activity results are omitted. */
+    generatedEmbeddings?: SupportedEmbeddingTypes[];
 }
 
 // ---------------------------------------------------------------------------

package/src/user.ts

@@ -116,10 +116,54 @@ export function quotaTierForAccountType(accountType: AccountType | undefined | n
     }
 }
 
+export const ACCOUNT_NAMESPACE_MAX_LENGTH = 63;
+export const ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH = 1000;
+export const RESERVED_ACCOUNT_NAMESPACES = [
+    'admin',
+    'api',
+    'apps',
+    'auth',
+    'cdn',
+    'docs',
+    'internal-auth',
+    'mcp',
+    'status',
+    'sts',
+    'www',
+] as const;
+
+const ACCOUNT_NAMESPACE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export function normalizeAccountNamespace(namespace: string): string {
+    return namespace.trim().toLowerCase();
+}
+
+export function getAccountNamespaceValidationError(namespace: string): string | undefined {
+    if (!namespace) {
+        return 'Account namespace is required';
+    }
+    if (namespace.length > ACCOUNT_NAMESPACE_MAX_LENGTH || !ACCOUNT_NAMESPACE_PATTERN.test(namespace)) {
+        return 'Account namespace must be a lowercase DNS label containing only letters, numbers, and hyphens';
+    }
+    if ((RESERVED_ACCOUNT_NAMESPACES as readonly string[]).includes(namespace)) {
+        return `Account namespace '${namespace}' is reserved`;
+    }
+    return undefined;
+}
+
 export interface Account {
     id: string;
     name: string;
 
+    /** Public DNS-label-compatible identifier used by organization app domains. */
+    namespace?: string;
+
+    /**
+     * Plain-text instructions shown when a signed-in user has no application access.
+     * @maxLength 1000
+     */
+    app_access_message?: string;
+
     email_domains: string[];
 
     onboarding: {
@@ -144,6 +188,8 @@ export interface Account {
 
 export interface UpdateAccountPayload {
     name?: string;
+    /** @maxLength 1000 */
+    app_access_message?: string;
     email_domains?: string[];
     billing?: AccountBilling;
     quota_tier?: QuotaTier;

package/src/view-configuration-validation.ts

@@ -0,0 +1,74 @@
+import Ajv, { type ErrorObject } from 'ajv';
+import type { ViewExperienceConfiguration } from './views.js';
+import {
+    PersistedViewExperienceConfigurationJsonSchema,
+    ViewExperienceConfigurationJsonSchema,
+} from './views-schema.js';
+import { type ViewValidationIssue, validateViewExperienceSemantics } from './views-validation.js';
+
+export type ViewConfigurationValidationMode = 'draft' | 'persisted';
+
+const ajv = new Ajv.default({ allErrors: true, strict: false });
+const validateDraftStructure = ajv.compile(ViewExperienceConfigurationJsonSchema);
+const validatePersistedStructure = ajv.compile(PersistedViewExperienceConfigurationJsonSchema);
+
+function jsonPointerPath(instancePath: string): string {
+    if (instancePath === '') return 'configuration';
+    return instancePath
+        .slice(1)
+        .split('/')
+        .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'))
+        .reduce((path, segment) => {
+            if (/^\d+$/.test(segment)) return `${path}[${segment}]`;
+            return path.length === 0 ? segment : `${path}.${segment}`;
+        }, '');
+}
+
+function errorPath(error: ErrorObject): string {
+    const base = jsonPointerPath(error.instancePath);
+    if (error.keyword === 'required' && 'missingProperty' in error.params) {
+        const missingProperty = String(error.params.missingProperty);
+        return base === 'configuration' ? missingProperty : `${base}.${missingProperty}`;
+    }
+    if (error.keyword === 'additionalProperties' && 'additionalProperty' in error.params) {
+        const additionalProperty = String(error.params.additionalProperty);
+        return base === 'configuration' ? additionalProperty : `${base}.${additionalProperty}`;
+    }
+    return base;
+}
+
+function structuralIssues(value: unknown, mode: ViewConfigurationValidationMode): ViewValidationIssue[] {
+    const validateStructure = mode === 'persisted' ? validatePersistedStructure : validateDraftStructure;
+    if (validateStructure(value)) return [];
+    const issues = (validateStructure.errors ?? []).map((error: ErrorObject) => ({
+        path: errorPath(error),
+        message: error.message ?? 'is invalid',
+    }));
+    return [...new Map(issues.map((issue) => [`${issue.path}\u0000${issue.message}`, issue])).values()];
+}
+
+/**
+ * Validate both the canonical JSON structure and semantic cross-reference rules.
+ *
+ * Persisted mode adds the documentation requirement structurally. Blank
+ * descriptions pass the shape check and are rejected by semantic validation,
+ * while structure-first short-circuiting prevents duplicate errors.
+ */
+export function validateViewConfiguration(
+    value: unknown,
+    mode: ViewConfigurationValidationMode = 'draft',
+): ViewValidationIssue[] {
+    const issues = structuralIssues(value, mode);
+    if (issues.length > 0) return issues;
+    return validateViewExperienceSemantics(value as ViewExperienceConfiguration, mode);
+}
+
+/** @deprecated Use validateViewConfiguration(value, 'draft'). */
+export function validateViewExperienceConfiguration(value: unknown): ViewValidationIssue[] {
+    return validateViewConfiguration(value, 'draft');
+}
+
+/** @deprecated Use validateViewConfiguration(value, 'persisted'). */
+export function validatePersistedViewExperienceConfiguration(value: unknown): ViewValidationIssue[] {
+    return validateViewConfiguration(value, 'persisted');
+}

package/src/view-query-validation.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { validateSupportedViewQuery } from './view-query-validation.js';
+
+function deeplyNestedFilter(depth: number): unknown {
+    let query: unknown = { term: { status: 'active' } };
+    for (let index = 0; index < depth; index++) {
+        query = { bool: { filter: query } };
+    }
+    return query;
+}
+
+describe('View query validation', () => {
+    it('rejects deeply nested queries without overflowing the call stack', () => {
+        expect(() => validateSupportedViewQuery(deeplyNestedFilter(6_000))).not.toThrow();
+        expect(validateSupportedViewQuery(deeplyNestedFilter(6_000))).toContainEqual(
+            expect.objectContaining({
+                message: 'exceeds the maximum of 100 query clauses',
+            }),
+        );
+    });
+});

package/src/view-query-validation.ts

@@ -0,0 +1,319 @@
+import {
+    ELASTICSEARCH_FIELD_PATH_PATTERN as FIELD_PATTERN,
+    isViewValidationRecord as isRecord,
+    SERVER_CONTROLLED_VIEW_FIELD_ROOTS,
+} from './view-validation-helpers.js';
+import type { ViewElasticsearchQuery } from './views.js';
+
+export interface ViewQueryValidationIssue {
+    path: string;
+    message: string;
+}
+
+export interface ViewQueryValidationOptions {
+    allowedFields?: ReadonlySet<string>;
+    allowedOperators?: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+const ALLOWED_QUERY_TYPES = new Set([
+    'bool',
+    'match',
+    'multi_match',
+    'simple_query_string',
+    'term',
+    'terms',
+    'range',
+    'exists',
+    'ids',
+    'prefix',
+    'match_all',
+]);
+const MAX_QUERY_CLAUSES = 100;
+const FORBIDDEN_FIELD_ROOTS = new Set<string>(SERVER_CONTROLLED_VIEW_FIELD_ROOTS);
+
+function addFieldIssue(
+    issues: ViewQueryValidationIssue[],
+    field: unknown,
+    path: string,
+    options: ViewQueryValidationOptions,
+): void {
+    if (typeof field !== 'string' || !FIELD_PATTERN.test(field)) {
+        issues.push({ path, message: 'must be a dot-separated field name' });
+        return;
+    }
+    if (FORBIDDEN_FIELD_ROOTS.has(field.split('.')[0])) {
+        issues.push({ path, message: `field '${field}' is server-controlled` });
+        return;
+    }
+    if (options.allowedFields && !options.allowedFields.has(field)) {
+        issues.push({ path, message: `field '${field}' is not available to this View` });
+    }
+}
+
+function addOperatorIssue(
+    issues: ViewQueryValidationIssue[],
+    field: string,
+    operator: string,
+    path: string,
+    options: ViewQueryValidationOptions,
+): void {
+    const allowed = options.allowedOperators?.get(field);
+    if (allowed && !allowed.has(operator)) {
+        issues.push({
+            path,
+            message: `operator '${operator}' is not available for field '${field}'`,
+        });
+    }
+}
+
+function validateSingleFieldClause(
+    issues: ViewQueryValidationIssue[],
+    value: unknown,
+    path: string,
+    validateValue: (fieldValue: unknown, valuePath: string, field: string) => void,
+    options: ViewQueryValidationOptions,
+): void {
+    if (!isRecord(value)) {
+        issues.push({ path, message: 'must be an object keyed by field name' });
+        return;
+    }
+    const entries = Object.entries(value);
+    if (entries.length !== 1) {
+        issues.push({ path, message: 'must reference exactly one field' });
+        return;
+    }
+    const [field, fieldValue] = entries[0];
+    addFieldIssue(issues, field, `${path}.${field}`, options);
+    validateValue(fieldValue, `${path}.${field}`, field);
+}
+
+function validateQueryNode(
+    issues: ViewQueryValidationIssue[],
+    value: unknown,
+    path: string,
+    state: { clauses: number },
+    options: ViewQueryValidationOptions,
+): void {
+    state.clauses++;
+    if (state.clauses > MAX_QUERY_CLAUSES) {
+        issues.push({ path, message: `exceeds the maximum of ${MAX_QUERY_CLAUSES} query clauses` });
+        return;
+    }
+    if (!isRecord(value)) {
+        issues.push({ path, message: 'must be an Elasticsearch query object' });
+        return;
+    }
+    const entries = Object.entries(value);
+    if (entries.length !== 1) {
+        issues.push({ path, message: 'must contain exactly one query clause' });
+        return;
+    }
+    const [type, body] = entries[0];
+    if (!ALLOWED_QUERY_TYPES.has(type)) {
+        issues.push({ path: `${path}.${type}`, message: `query type '${type}' is not supported` });
+        return;
+    }
+
+    if (type === 'match_all') {
+        if (!isRecord(body)) {
+            issues.push({ path: `${path}.match_all`, message: 'must be an object' });
+        }
+        return;
+    }
+    if (type === 'bool') {
+        if (!isRecord(body)) {
+            issues.push({ path: `${path}.bool`, message: 'must be an object' });
+            return;
+        }
+        const allowed = new Set(['must', 'filter', 'should', 'must_not', 'minimum_should_match']);
+        for (const key of Object.keys(body)) {
+            if (!allowed.has(key)) {
+                issues.push({ path: `${path}.bool.${key}`, message: 'is not supported' });
+            }
+        }
+        for (const key of ['must', 'filter', 'should', 'must_not'] as const) {
+            const child = body[key];
+            if (child === undefined) continue;
+            const children = Array.isArray(child) ? child : [child];
+            if (children.length > 50) {
+                issues.push({ path: `${path}.bool.${key}`, message: 'must contain at most 50 clauses' });
+            }
+            children.forEach((item, index) => {
+                validateQueryNode(issues, item, `${path}.bool.${key}[${index}]`, state, options);
+            });
+        }
+        const minimumShouldMatch = body.minimum_should_match;
+        if (
+            minimumShouldMatch !== undefined &&
+            typeof minimumShouldMatch !== 'number' &&
+            typeof minimumShouldMatch !== 'string'
+        ) {
+            issues.push({ path: `${path}.bool.minimum_should_match`, message: 'must be a number or string' });
+        }
+        return;
+    }
+    if (type === 'exists') {
+        if (!isRecord(body)) {
+            issues.push({ path: `${path}.exists`, message: 'must be an object' });
+        } else {
+            addFieldIssue(issues, body.field, `${path}.exists.field`, options);
+            if (typeof body.field === 'string') {
+                addOperatorIssue(issues, body.field, 'exists', `${path}.exists.field`, options);
+            }
+        }
+        return;
+    }
+    if (type === 'ids') {
+        if (!isRecord(body) || !Array.isArray(body.values) || body.values.length > 1_000) {
+            issues.push({ path: `${path}.ids.values`, message: 'must be an array containing at most 1000 IDs' });
+        } else if (body.values.some((id) => typeof id !== 'string')) {
+            issues.push({ path: `${path}.ids.values`, message: 'must contain only strings' });
+        }
+        return;
+    }
+    if (type === 'multi_match' || type === 'simple_query_string') {
+        if (!isRecord(body) || typeof body.query !== 'string') {
+            issues.push({ path: `${path}.${type}.query`, message: 'must be a string' });
+            return;
+        }
+        if (!Array.isArray(body.fields) || body.fields.length === 0 || body.fields.length > 20) {
+            issues.push({ path: `${path}.${type}.fields`, message: 'must contain between 1 and 20 fields' });
+        } else {
+            body.fields.forEach((rawField, index) => {
+                const field = typeof rawField === 'string' ? rawField.split('^')[0] : rawField;
+                addFieldIssue(issues, field, `${path}.${type}.fields[${index}]`, options);
+                if (typeof field === 'string') {
+                    addOperatorIssue(issues, field, type, `${path}.${type}.fields[${index}]`, options);
+                }
+            });
+        }
+        return;
+    }
+
+    if (isRecord(body)) {
+        const fieldEntries = Object.entries(body);
+        if (fieldEntries.length === 1) {
+            addOperatorIssue(issues, fieldEntries[0][0], type, `${path}.${type}.${fieldEntries[0][0]}`, options);
+        }
+    }
+    validateSingleFieldClause(
+        issues,
+        body,
+        `${path}.${type}`,
+        (fieldValue, valuePath, field) => {
+            if (type === 'terms') {
+                if (!Array.isArray(fieldValue) || fieldValue.length > 1_000) {
+                    issues.push({ path: valuePath, message: 'must be an array containing at most 1000 values' });
+                }
+                return;
+            }
+            if (type === 'range') {
+                if (!isRecord(fieldValue)) {
+                    issues.push({ path: valuePath, message: 'must be a range object' });
+                    return;
+                }
+                const allowed = new Set(['gt', 'gte', 'lt', 'lte']);
+                if (Object.keys(fieldValue).length === 0 || Object.keys(fieldValue).some((key) => !allowed.has(key))) {
+                    issues.push({ path: valuePath, message: 'supports only gt, gte, lt, and lte' });
+                }
+                return;
+            }
+            if (type === 'prefix') {
+                if (field !== 'location') {
+                    issues.push({ path: valuePath, message: 'prefix queries are supported only for location' });
+                }
+                const prefix = isRecord(fieldValue) ? fieldValue.value : fieldValue;
+                if (typeof prefix !== 'string' || !prefix.startsWith('/') || !prefix.endsWith('/')) {
+                    issues.push({ path: valuePath, message: 'must be a boundary-aware absolute location prefix' });
+                }
+                return;
+            }
+            if (type === 'match') {
+                const query = isRecord(fieldValue) ? fieldValue.query : fieldValue;
+                if (typeof query !== 'string') {
+                    issues.push({ path: valuePath, message: 'must contain a string query' });
+                }
+                return;
+            }
+            if (type === 'term' && isRecord(fieldValue)) {
+                const allowed = new Set(['value', 'boost', 'case_insensitive']);
+                if (!('value' in fieldValue) || Object.keys(fieldValue).some((key) => !allowed.has(key))) {
+                    issues.push({
+                        path: valuePath,
+                        message: 'supports only value, boost, and case_insensitive options',
+                    });
+                    return;
+                }
+                if (isRecord(fieldValue.value) || Array.isArray(fieldValue.value)) {
+                    issues.push({ path: `${valuePath}.value`, message: 'must be a scalar value' });
+                }
+                if (fieldValue.boost !== undefined && typeof fieldValue.boost !== 'number') {
+                    issues.push({ path: `${valuePath}.boost`, message: 'must be a number' });
+                }
+                if (fieldValue.case_insensitive !== undefined && typeof fieldValue.case_insensitive !== 'boolean') {
+                    issues.push({ path: `${valuePath}.case_insensitive`, message: 'must be a boolean' });
+                }
+                return;
+            }
+            if (isRecord(fieldValue) || Array.isArray(fieldValue)) {
+                issues.push({ path: valuePath, message: 'must be a scalar value' });
+            }
+        },
+        options,
+    );
+}
+
+function normalizeViewQueryNode(value: unknown, state: { clauses: number }): unknown {
+    state.clauses++;
+    if (state.clauses > MAX_QUERY_CLAUSES) return value;
+    if (!isRecord(value)) return value;
+    const entries = Object.entries(value);
+    if (entries.length !== 1) return value;
+    const [type, body] = entries[0];
+    if (type === 'bool' && isRecord(body)) {
+        const normalizedBody: Record<string, unknown> = { ...body };
+        for (const key of ['must', 'filter', 'should', 'must_not'] as const) {
+            const child = body[key];
+            if (Array.isArray(child)) {
+                normalizedBody[key] = child.map((item) => normalizeViewQueryNode(item, state));
+            } else if (child !== undefined) {
+                normalizedBody[key] = normalizeViewQueryNode(child, state);
+            }
+        }
+        return { bool: normalizedBody };
+    }
+    if (type !== 'term' || !isRecord(body)) return value;
+    const fieldEntries = Object.entries(body);
+    if (fieldEntries.length !== 1) return value;
+    const [field, fieldValue] = fieldEntries[0];
+    if (!isRecord(fieldValue) || Object.keys(fieldValue).length !== 1 || !('value' in fieldValue)) return value;
+    return { term: { [field]: fieldValue.value } };
+}
+
+export function normalizeViewQuery(value: unknown): unknown {
+    return normalizeViewQueryNode(value, { clauses: 0 });
+}
+
+export function validateSupportedViewQuery(
+    value: unknown,
+    path = 'query',
+    options: ViewQueryValidationOptions = {},
+): ViewQueryValidationIssue[] {
+    const issues: ViewQueryValidationIssue[] = [];
+    validateQueryNode(issues, normalizeViewQuery(value), path, { clauses: 0 }, options);
+    return issues;
+}
+
+export function asSupportedViewQuery(
+    value: unknown,
+    path = 'query',
+    options: ViewQueryValidationOptions = {},
+): ViewElasticsearchQuery {
+    const normalized = normalizeViewQuery(value);
+    const issues: ViewQueryValidationIssue[] = [];
+    validateQueryNode(issues, normalized, path, { clauses: 0 }, options);
+    if (issues.length > 0) {
+        throw new Error(issues.map((issue) => `${issue.path} ${issue.message}`).join('; '));
+    }
+    return normalized as ViewElasticsearchQuery;
+}

package/src/view-validation-helpers.ts

@@ -0,0 +1,28 @@
+export const VIEW_CONFIGURATION_ID_PATTERN_SOURCE = '^[a-z][a-z0-9_-]*$';
+export const ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE = '^[A-Za-z0-9_]+(?:\\.[A-Za-z0-9_]+)*$';
+
+export const VIEW_CONFIGURATION_ID_PATTERN = new RegExp(VIEW_CONFIGURATION_ID_PATTERN_SOURCE);
+export const ELASTICSEARCH_FIELD_PATH_PATTERN = new RegExp(ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE);
+
+/**
+ * Elasticsearch roots owned by the server and unavailable to View-authored
+ * queries or dynamic collection filters.
+ */
+export const SERVER_CONTROLLED_VIEW_FIELD_ROOTS = [
+    'security',
+    'revision',
+    'is_deleted',
+    'embeddings_text',
+    'embeddings_image',
+    'embeddings_properties',
+    '_indexing_metadata',
+] as const;
+
+/** @deprecated Use ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE. */
+export const VIEW_FIELD_PATTERN_SOURCE = ELASTICSEARCH_FIELD_PATH_PATTERN_SOURCE;
+/** @deprecated Use ELASTICSEARCH_FIELD_PATH_PATTERN. */
+export const VIEW_FIELD_PATTERN = ELASTICSEARCH_FIELD_PATH_PATTERN;
+
+export function isViewValidationRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}