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

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

@@ -1,6 +1,6 @@
 import Ajv from 'ajv';
 import { describe, expect, it } from 'vitest';
-import { ContentTypeEditingPolicySchema } from './store.js';
+import { ContentTypeEditingPolicySchema } from './editing-policy-schema.generated.js';
 
 const validate = new Ajv.default({ allErrors: true, strict: false }).compile(ContentTypeEditingPolicySchema);
 

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,20 +191,14 @@ 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[];
@@ -256,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 {
@@ -302,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

package/src/store/dsl-workflow.ts

@@ -1,34 +1,32 @@
-import type { StringValue } from 'ms';
+import type { z } from 'zod';
+import type {
+    ActivityFetchSpecSchema,
+    DSLActivityOptionsSchema,
+    DSLActivitySpecSchema,
+    DSLActivityStepSchema,
+    DSLRetryPolicySchema,
+    DurationValueSchema,
+} from '../api-schemas/process.js';
+import type {
+    WorkflowDefinitionRefSchema,
+    WorkflowInputFileSchema,
+    WorkflowInputSchema,
+} from '../api-schemas/workflow-runs.js';
 import type { ToolExecutionMetadata } from '../tool-execution.js';
 import type { BaseObject } from './common.js';
 import type { WorkflowExecutionPayload } from './index.js';
 import type { ParentClosePolicyType } from './temporalio.js';
 
-export type DurationValue = StringValue | number;
+export type DurationValue = z.infer<typeof DurationValueSchema>;
 
 /**
  * Discriminator for workflow input type - either object IDs or GCS file URIs
  */
 export type WorkflowInputType = 'objectIds' | 'files';
 
-/**
- * File reference with URL and mimetype
- */
-export interface WorkflowInputFile {
-    url: string;
-    mimetype: string;
-}
+export type WorkflowInputFile = z.infer<typeof WorkflowInputFileSchema>;
 
-/**
- * Discriminated union for workflow inputs.
- * Workflows can accept either a list of object IDs (existing behavior) OR a list of file references (new).
- */
-/**
- * @discriminator inputType
- */
-export type WorkflowInput =
-    | { inputType: 'objectIds'; objectIds: string[] }
-    | { inputType: 'files'; files: WorkflowInputFile[] };
+export type WorkflowInput = z.infer<typeof WorkflowInputSchema>;
 
 /**
  * The payload sent when starting a workflow from the temporal client to the workflow instance.
@@ -41,32 +39,12 @@ export interface DSLWorkflowExecutionPayload extends WorkflowExecutionPayload<Re
     workflow: DSLWorkflowSpec;
 }
 
-/**
- * The payload for a DSL activity options.
- *
- * @see ActivityOptions in @temporalio/common
- */
-export interface DSLActivityOptions {
-    startToCloseTimeout?: DurationValue;
-    heartbeatTimeout?: DurationValue;
-    scheduleToStartTimeout?: DurationValue;
-    scheduleToCloseTimeout?: DurationValue;
-    retry?: DSLRetryPolicy;
-}
+export type DSLActivityOptions = z.infer<typeof DSLActivityOptionsSchema>;
 
-/**
- * The payload for a DSL retry policy.
- *
- * @see RetryPolicy in @temporalio/common
- */
-export interface DSLRetryPolicy {
-    backoffCoefficient?: number;
-    initialInterval?: DurationValue;
-    maximumAttempts?: number;
-    maximumInterval?: DurationValue;
-    nonRetryableErrorTypes?: string[];
-}
+export type DSLRetryPolicy = z.infer<typeof DSLRetryPolicySchema>;
 
+// Temporal accepts Date values internally, while the HTTP schema documents their JSON string form.
+// Keep the execution type truthful at the Temporal boundary instead of pretending HTTP validation revives dates.
 export type WorkflowSearchAttributeValue = string[] | number[] | boolean[] | Date[];
 export type WorkflowSearchAttributes = Record<string, WorkflowSearchAttributeValue>;
 
@@ -82,38 +60,10 @@ export interface DSLActivityExecutionPayload<ParamsT extends object> extends Wor
     activityGroupId?: string;
 }
 
+// The published schema intentionally leaves array items open. This narrower authoring type is an
+// internal DSL convenience, not a claim made by the HTTP validator.
 export type ImportSpec = (string | Record<string, string>)[];
-export interface ActivityFetchSpec {
-    /**
-     * The data provider name
-     */
-    type: 'document' | 'document_type' | 'interaction_run';
-    /**
-     * An optional URI to the data source.
-     */
-    source?: string;
-    /**
-     * The query to be executed by the data provider
-     */
-    query: Record<string, unknown>;
-    /**
-     * a string of space separated field names.
-     * Prefix a field name with "-" to exclude it from the result.
-     */
-    select?: string;
-
-    /**
-     * The number of results to return. If the result is limited to 1 the result will be a single object
-     */
-    limit?: number;
-
-    /**
-     * How to handle not found objects.
-     * 1. ignore - Ignore and return an empty array for multi objects query (or undefined for single object query) or empty array for multiple objects throw an error.
-     * 2. throw - Throw an error if the object or no objects are found.
-     */
-    on_not_found?: 'ignore' | 'throw';
-}
+export type ActivityFetchSpec = z.infer<typeof ActivityFetchSpecSchema>;
 
 export interface DSLWorkflowStepBase {
     /**
@@ -123,86 +73,27 @@ export interface DSLWorkflowStepBase {
     type: 'activity' | 'workflow';
 }
 
-export interface DSLActivitySpec<PARAMS extends object = Record<string, unknown>> {
-    /**
-     * The name of the activity function
-     */
-    name: string;
-    /**
-     * Title of the activity to be displayed in the UI workflow builder
-     */
-    title?: string;
-    /**
-     * The description of the activity to e displayed in the UI workflow builder
-     */
-    description?: string;
-    /**
-     * Activities parameters. These parameters can be either literals
-     * (hardcoded strings, numbers, booleans, objects, arrays etc.), either
-     * references to the workflow variables.
-     * The workflow variables are built from the workflow params (e.g. the workflow configuration)
-     * and from the result of the previous activities.
-     */
-    params?: PARAMS;
-    /**
-     * The name of the workflow variable that will store the result of the activity
-     * If not specified the result will not be stored
-     * The parameters describe how the actual parameters will be obtained from the workflow execution vars.
-     * since it may contain references to workflow execution vars.
-     */
-    output?: string;
-
-    /**
-     * A JSON expression which evaluate to true or false similar to mongo matches.
-     * We support for now basic expression like: $true, $false, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $regexp
-     * {$eq: {name: value}},
-     * Ex: {$eq: {wfVarName: value}}
-     */
-    condition?: Record<string, unknown>;
+type DSLActivitySpecWire = z.infer<typeof DSLActivitySpecSchema>;
 
-    /**
-     * The import spec is used to import data from workflow variables.
-     * The import spec is a list of variable names to import from the workflow context.
-     * You can also use objects to rename the imported variables, or to reference an expression.
-     * Example:
-     * ["runId", {"typeId": "docType.id"}]
-     */
+/** The published activity shape with a caller-specializable parameter bag. */
+export type DSLActivitySpec<PARAMS extends object = Record<string, unknown>> = Omit<
+    DSLActivitySpecWire,
+    'params' | 'import'
+> & {
+    params?: PARAMS;
     import?: ImportSpec;
+};
 
-    /**
-     * The fetch phase is used to fetch data from external sources.
-     */
-    fetch?: Record<string, ActivityFetchSpec>;
-
-    /**
-     * Projection to apply to the result. Not all activities support this.
-     */
-    projection?: never | Record<string, unknown>;
-
-    // ---------- Optional features not implemented in a first step ------------
-    /**
-     * If true the activity will be executed in parallel with the other activities.
-     * (i.e. the workflow will not wait for the activity to finish before starting the next one)
-     */
-    parallel?: boolean;
-
-    /**
-     * Await for a parallel activity execution to return.
-     */
-    await?: string; //the activity name to await
+type DSLActivityStepWire = z.infer<typeof DSLActivityStepSchema>;
 
-    /**
-     * Activity options for configuring the activity execution, which overrides the activity options
-     * defined at workflow level.
-     */
-    options?: DSLActivityOptions;
-}
-
-export interface DSLActivityStep<PARAMS extends object = Record<string, unknown>>
-    extends DSLActivitySpec<PARAMS>,
-        DSLWorkflowStepBase {
-    type: 'activity';
-}
+/** The published activity-step shape with a caller-specializable parameter bag. */
+export type DSLActivityStep<PARAMS extends object = Record<string, unknown>> = Omit<
+    DSLActivityStepWire,
+    'params' | 'import'
+> & {
+    params?: PARAMS;
+    import?: ImportSpec;
+};
 
 export interface DSLChildWorkflowStep extends DSLWorkflowStepBase {
     type: 'workflow';
@@ -310,6 +201,26 @@ export interface DSLWorkflowSpecWithActivities extends DSLWorkflowSpecBase {
  */
 export type DSLWorkflowSpec = DSLWorkflowSpecWithSteps | DSLWorkflowSpecWithActivities;
 
+/**
+ * Legacy upsert fields the workflow-definition write endpoints still accept alongside a spec.
+ *
+ * A body carrying `id` updates that definition instead of creating one, with `updated_at` checked
+ * against the stored value for optimistic concurrency. All server-assigned on the read side, hence
+ * optional here and absent from {@link DSLWorkflowSpec}.
+ */
+export interface LegacyWorkflowDefinitionUpsertFields {
+    id?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+
+export type WorkflowDefinitionPayloadWithSteps = DSLWorkflowSpecWithSteps & LegacyWorkflowDefinitionUpsertFields;
+export type WorkflowDefinitionPayloadWithActivities = DSLWorkflowSpecWithActivities &
+    LegacyWorkflowDefinitionUpsertFields;
+
+/** The request body of `POST /workflows/definitions` and `PUT /workflows/definitions/:id`. */
+export type WorkflowDefinitionPayload = WorkflowDefinitionPayloadWithSteps | WorkflowDefinitionPayloadWithActivities;
+
 export function withDSLWorkflowSpecDiscriminator(spec: DSLWorkflowSpecBase): DSLWorkflowSpec {
     if ('steps' in spec && spec.steps) {
         return { ...spec, spec_format: 'steps' } as DSLWorkflowSpecWithSteps;
@@ -328,14 +239,7 @@ export interface DSLWorkflowDefinitionResponse extends DSLWorkflowDefinition {
     spec_format: 'steps' | 'activities';
 }
 
-export interface WorkflowDefinitionRef {
-    id: string;
-    name: string;
-    description?: string;
-    tags?: string[];
-    created_at: Date;
-    updated_at: Date;
-}
+export type WorkflowDefinitionRef = z.infer<typeof WorkflowDefinitionRefSchema>;
 
 export const WorkflowDefinitionRefPopulate = 'id name description tags created_at updated_at';