@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260804.124748Z

package/src/store/collections.ts

@@ -1,3 +1,15 @@
+import type { z } from 'zod';
+import type {
+    CollectionChildrenUpdatePayloadSchema,
+    CollectionChildrenUpdateResultSchema,
+    CollectionMembersQuerySchema,
+    CollectionMembersUpdatePayloadSchema,
+    CollectionMembersUpdateResultSchema,
+    CollectionPropagationResponseSchema,
+    CollectionSchema,
+    CollectionSecuritySettingsResponseSchema,
+    CreateCollectionPayloadSchema,
+} from '../api-schemas/content.js';
 import type { BaseObject } from './common.js';
 import type { ColumnLayout, ContentObjectTypeRef } from './store.js';
 
@@ -6,25 +18,7 @@ export enum CollectionStatus {
     archived = 'archived',
 }
 
-export interface CreateCollectionPayload {
-    name: string;
-    dynamic: boolean;
-    description?: string;
-    skip_head_sync?: boolean;
-    tags?: string[];
-    type?: string | null;
-    query?: Record<string, unknown>;
-    properties?: Record<string, unknown>;
-    parent?: string | null;
-    table_layout?: ColumnLayout[] | null;
-    allowed_types?: string[];
-    updated_by?: string;
-    shared_properties?: string[];
-    /** BLP sensitivity level for member documents */
-    sensitivity?: number;
-    /** Compartments for member documents */
-    compartments?: string[];
-}
+export type CreateCollectionPayload = z.infer<typeof CreateCollectionPayloadSchema>;
 
 export interface CollectionItem extends BaseObject {
     /**
@@ -58,20 +52,7 @@ export interface CollectionItem extends BaseObject {
     allowed_types?: string[];
 }
 
-export interface Collection extends CollectionItem {
-    properties?: Record<string, unknown>;
-    query?: Record<string, unknown>;
-    security?: Record<string, string[]>; // ACL for collection access
-    /** BLP sensitivity level — propagated to member documents (max across collections) */
-    sensitivity?: number;
-    /** Compartments — propagated to member documents (union across collections) */
-    compartments?: string[];
-    /**
-     * List of property names from the collection's properties that should be shared with (injected into) member objects.
-     * These properties will be propagated to all members of this collection and merged as arrays.
-     */
-    shared_properties?: string[];
-}
+export type Collection = z.infer<typeof CollectionSchema>;
 
 export interface StaticCollection extends Collection {
     dynamic: false;
@@ -94,39 +75,16 @@ export interface CollectionSearchPayload {
     types?: string[];
 }
 
-export interface CollectionMembersUpdateResult {
-    id: string;
-}
+export type CollectionMembersUpdateResult = z.infer<typeof CollectionMembersUpdateResultSchema>;
 
-export interface CollectionSecuritySettingsResponse {
-    id: string;
-    security: Record<string, string[]>;
-}
+export type CollectionSecuritySettingsResponse = z.infer<typeof CollectionSecuritySettingsResponseSchema>;
 
-export interface CollectionPropagationResponse {
-    id: string;
-    message: string;
-    security?: Record<string, string[]>;
-    shared_properties?: string[];
-}
+export type CollectionPropagationResponse = z.infer<typeof CollectionPropagationResponseSchema>;
 
-export interface CollectionChildrenUpdateResult {
-    count: number;
-}
+export type CollectionChildrenUpdateResult = z.infer<typeof CollectionChildrenUpdateResultSchema>;
 
-export interface CollectionMembersUpdatePayload {
-    action: 'add' | 'delete';
-    members: string[];
-}
+export type CollectionMembersUpdatePayload = z.infer<typeof CollectionMembersUpdatePayloadSchema>;
 
-export interface CollectionChildrenUpdatePayload {
-    action: 'add' | 'delete';
-    children: string[];
-}
+export type CollectionChildrenUpdatePayload = z.infer<typeof CollectionChildrenUpdatePayloadSchema>;
 
-export interface CollectionMembersQuery {
-    status?: string;
-    type?: string;
-    limit?: number;
-    offset?: number;
-}
+export type CollectionMembersQuery = z.infer<typeof CollectionMembersQuerySchema>;

package/src/store/content-type-editing.test.ts

@@ -0,0 +1,17 @@
+import Ajv from 'ajv';
+import { describe, expect, it } from 'vitest';
+import { ContentTypeEditingPolicySchema } from './editing-policy-schema.generated.js';
+
+const validate = new Ajv.default({ allErrors: true, strict: false }).compile(ContentTypeEditingPolicySchema);
+
+describe('ContentTypeEditingPolicySchema', () => {
+    it('accepts an omitted or configured interaction', () => {
+        expect(validate({})).toBe(true);
+        expect(validate({ interaction: 'sys:GeneralAgent' })).toBe(true);
+    });
+
+    it('rejects unknown fields and non-string interactions', () => {
+        expect(validate({ interaction: 42 })).toBe(false);
+        expect(validate({ interaction: 'sys:GeneralAgent', tools: [] })).toBe(false);
+    });
+});

package/src/store/conversation-state.ts

@@ -1,4 +1,13 @@
 import type { CompletionResult, ExecutionTokenUsage, StatelessExecutionOptions, ToolUse } from '@llumiverse/common';
+import type { z } from 'zod';
+import type {
+    ExternalizedToolInputRefSchema,
+    ExternalizedToolInputRefsSchema,
+    PendingMcpConnectionSchema,
+    TextArtifactReferenceSchema,
+    ToolReferenceSchema,
+    UsedSkillSchema,
+} from '../api-schemas/interaction.js';
 import type { ConversationStripOptions, ResolvedInteractionExecutionInfo, UserChannel } from '../interaction.js';
 import type { ExecutionRunDocRef } from '../runs.js';
 import type { AgentToolApprovalMode, PendingToolApprovalResults, ToolApprovalGrant } from './agent-approval.js';
@@ -8,43 +17,31 @@ import type { Plan, WorkflowAncestor } from './workflow.js';
  * Lightweight tool reference for activity payloads.
  * References tools stored in GCP instead of embedding full tool definitions.
  */
-export interface ToolReference {
-    storage_key: string;
-    tool_count: number;
-    stored_at: string;
-}
+export type ToolReference = z.infer<typeof ToolReferenceSchema>;
 
 /** Reference to text content externalized to agent artifact storage. */
-export interface TextArtifactReference {
-    storage_id: string;
-    artifact_path: string;
-    display_ref: string;
-    sha256: string;
-    size_bytes: number;
-    content_type: string;
-}
+export type TextArtifactReference = z.infer<typeof TextArtifactReferenceSchema>;
 
 /**
  * Sidecar metadata for generated tool input fields that were stored outside
  * model-visible tool_input. Keyed by tool_use.id on ConversationState.
  */
-export interface ExternalizedToolInputRef {
-    tool_name: string;
-    input_path: ['content'];
-    ref: TextArtifactReference;
-}
+export type ExternalizedToolInputRef = z.infer<typeof ExternalizedToolInputRefSchema>;
 
-export interface ExternalizedToolInputRefs {
-    [toolUseId: string]: ExternalizedToolInputRef[];
-}
+export type ExternalizedToolInputRefs = z.infer<typeof ExternalizedToolInputRefsSchema>;
 
 export function toolInputRefsArtifactPath(storageId: string): string {
     return `agents/${storageId}/tool-input-refs.json`;
 }
 
 /**
- * Conversation state passed between workflow activities.
- * Contains all context needed to continue a multi-turn agent conversation.
+ * Conversation state passed between workflow activities: the activity-safe,
+ * per-turn dynamic subset of a multi-turn agent conversation. Rides every
+ * conversation activity payload, so it deliberately excludes anything large or
+ * fetchable — the conversation history and tool definitions live in artifact
+ * storage (referenced via `tool_reference` / the conversation storage id), and
+ * catalog/activation data lives in the workflow-memory
+ * {@link ConversationCatalogState} (persisted as catalog.json).
  */
 export interface ConversationState {
     /**
@@ -131,21 +128,27 @@ export interface ConversationState {
     /** Active tools that should not be evicted by bounded active-tool pruning. */
     pinned_tool_names?: string[];
 
-    /**
-     * Activation and usage metadata for tools seen during the conversation.
-     * Used to keep the active tool set bounded without losing recovery context.
-     */
-    tool_activation_metadata?: Record<string, ToolActivationMetadata>;
-
     /** Skills that have been used in this conversation (for auto-syncing scripts and package installation) */
     used_skills?: UsedSkill[];
 
-    /** All available skills from registered tool collections (for upfront hydration in sandbox) */
-    available_skills?: AvailableSkill[];
-
     /** Whether to stream LLM responses to Redis (cached from project config) */
     streaming_enabled?: boolean;
 
+    /**
+     * Project-configured checkpoint threshold as a fraction of the model's
+     * context window (cached from project.configuration.agent_checkpoint_threshold
+     * at conversation start).
+     */
+    checkpoint_threshold?: number;
+
+    /**
+     * Project-configured checkpoint hard cap in tokens (cached from
+     * project.configuration.agent_checkpoint_tokens at conversation start).
+     * The workflow resolves the effective threshold from these, the per-run
+     * checkpoint_tokens override, and the model-based default.
+     */
+    checkpoint_tokens?: number;
+
     /**
      * Active communication channels with their current state.
      * Channels can be updated as conversation progresses (e.g., email threading info).
@@ -188,24 +191,21 @@ export interface ConversationState {
      */
     latest_streaming_id?: string;
 
-    /**
-     * Mapping of skill names to their related tools.
-     * When a skill is called, its related tools are added to unlocked_tools.
-     */
-    skill_tool_map?: Record<string, string[]>;
-
     /**
      * Names of skills whose full instructions are already present in the live conversation
      * history (i.e. were delivered by a prior `learn_<skill>` call). Used to make skill
      * re-activation idempotent: a repeat call returns a short "already active" acknowledgement
      * instead of re-dumping the instructions.
      *
-     * Unlike `unlocked_tools`/`skill_tool_map` (which must survive a checkpoint so tools stay
-     * unlocked), this list is reset when a checkpoint compacts the conversation, because the
+     * Unlike `unlocked_tools` (which must survive a checkpoint so tools stay unlocked),
+     * this list is reset when a checkpoint compacts the conversation, because the
      * summary no longer carries the skill instructions and the next call must re-deliver them.
      */
     skill_instructions_delivered?: string[];
 
+    /** Stable ids of initialization tool calls completed before the first model turn. */
+    initialization_call_ids?: string[];
+
     /**
      * Denylist of MCP tool-collection ids deactivated for this conversation.
      * `undefined`/empty means all installed/connected MCP collections are active.
@@ -253,23 +253,48 @@ export interface ConversationState {
     app_version?: string;
 }
 
+/**
+ * Tool/skill catalog state for a conversation, split out of {@link ConversationState}
+ * so it never rides Temporal activity payloads:
+ * - `skill_tool_map` and `available_skills` are composed by tool generation and
+ *   persisted next to the tool universe (catalog.json); the workflow holds them in
+ *   memory and the few consuming activities fetch them from artifact storage.
+ * - `tool_activation_metadata` is workflow-side eviction/pin bookkeeping; it survives
+ *   continueAsNew via the continuation payload, never via activity inputs.
+ */
+export interface ConversationCatalogState {
+    /**
+     * Mapping of skill names to their related tools.
+     * When a skill is called, its related tools are added to unlocked_tools.
+     */
+    skill_tool_map?: Record<string, string[]>;
+
+    /** All available skills from registered tool collections (for upfront hydration in sandbox) */
+    available_skills?: AvailableSkill[];
+
+    /**
+     * Activation and usage metadata for tools seen during the conversation.
+     * Used to keep the active tool set bounded without losing recovery context.
+     */
+    tool_activation_metadata?: Record<string, ToolActivationMetadata>;
+}
+
+/**
+ * The subset of {@link ConversationCatalogState} persisted to artifact storage
+ * (catalog.json, next to conversation.json and tools.json). Activation metadata is
+ * runtime bookkeeping and is deliberately not part of the stored catalog.
+ */
+export type StoredConversationCatalog = Pick<ConversationCatalogState, 'skill_tool_map' | 'available_skills'>;
+
+/** Artifact key of the stored conversation catalog, relative to the agent storage root. */
+export const CONVERSATION_CATALOG_ARTIFACT_KEY = 'catalog.json';
+
 /**
  * An MCP server the user can connect to but hasn't yet (active + accessible, no OAuth token).
  * Built at tool-discovery time and stored on the conversation state so the agent can
  * discover it (by description) and ask the user to connect.
  */
-export interface PendingMcpConnection {
-    /** The app installation id owning the collection (used for OAuth operations). */
-    app_install_id: string;
-    /** The MCP tool-collection id. */
-    collection_id: string;
-    /** Human-readable label for the server/collection. */
-    name: string;
-    /** Manifest description of what the server provides (used for discovery). */
-    description?: string;
-    /** Tool-name prefix for this collection. */
-    namespace?: string;
-}
+export type PendingMcpConnection = z.infer<typeof PendingMcpConnectionSchema>;
 
 /** Skill metadata collected at workflow start for upfront sandbox hydration */
 export interface AvailableSkill {
@@ -299,18 +324,7 @@ export function getConversationStorageId(
 }
 
 /** Skill metadata tracked when a skill is used */
-export interface UsedSkill {
-    /** Skill name (e.g., "analyze_data") */
-    name: string;
-    /** Source URL of the skill collection (e.g., "https://tools.vertesia.io/api/skills/data-analysis") */
-    src: string;
-    /** Programming language (e.g., "python") */
-    language?: string;
-    /** Required packages (e.g., ["pandas", "numpy"]) */
-    packages?: string[];
-    /** System-level packages to install via sudo apt-get (e.g., ["poppler-utils"]) */
-    system_packages?: string[];
-}
+export type UsedSkill = z.infer<typeof UsedSkillSchema>;
 
 export interface ToolActivationMetadata {
     /** Turn when the tool became active in this conversation. */

package/src/store/doc-analyzer.ts

@@ -1,51 +1,35 @@
-import type { WorkflowExecutionPayload, WorkflowRunStatus } from './workflow.js';
-
-export interface DocumentPrepOptions {
-    features?: string[];
-    debug?: boolean;
-    output_format?: DocProcessorOutputFormat;
-    [key: string]: unknown;
-}
+import type { z } from 'zod';
+import type {
+    DocAnalyzeRunStatusResponseSchema,
+    DocAnalyzerProgressSchema,
+    DocAnalyzerProgressStatusSchema,
+    DocProcessorOutputFormatSchema,
+    DocumentPrepOptionsSchema,
+    DocumentProcessingPhaseSchema,
+} from '../api-schemas/document-processing.js';
+import type { WorkflowExecutionPayload } from './workflow.js';
+
+export type DocumentPrepOptions = z.infer<typeof DocumentPrepOptionsSchema>;
 
 export interface DocumentPrepWorkflowPayload extends Omit<WorkflowExecutionPayload, 'vars'> {
     vars: DocumentPrepOptions;
 }
 
-export type DocumentProcessingPhase = 'markdown' | 'grounded_extraction';
+export type DocumentProcessingPhase = z.infer<typeof DocumentProcessingPhaseSchema>;
 
 /**
  * Output format for document processing workflows
  */
-export type DocProcessorOutputFormat = 'markdown';
+export type DocProcessorOutputFormat = z.infer<typeof DocProcessorOutputFormatSchema>;
 
 /**
  * Represents a document analysis run status
  */
-export interface DocAnalyzeRunStatusResponse extends WorkflowRunStatus {
-    phase?: DocumentProcessingPhase;
-    progress?: DocAnalyzerProgress;
-    /** The output format being used for processing. */
-    output_format?: DocProcessorOutputFormat;
-}
+export type DocAnalyzeRunStatusResponse = z.infer<typeof DocAnalyzeRunStatusResponseSchema>;
 
-export interface DocAnalyzerProgress {
-    phase?: DocumentProcessingPhase;
-    pages: DocAnalyzerProgressStatus;
-    images: DocAnalyzerProgressStatus;
-    tables: DocAnalyzerProgressStatus;
-    visuals: DocAnalyzerProgressStatus;
-    started_at?: number;
-    percent: number;
-    /** The output format being used for processing. */
-    output_format?: DocProcessorOutputFormat;
-}
+export type DocAnalyzerProgress = z.infer<typeof DocAnalyzerProgressSchema>;
 
-interface DocAnalyzerProgressStatus {
-    total: number;
-    processed: number;
-    success: number;
-    failed: number;
-}
+export type DocAnalyzerProgressStatus = z.infer<typeof DocAnalyzerProgressStatusSchema>;
 
 /**
  * Adapt Tables Parameters, part of the request