@vertesia/appgen-docs 1.5.0-dev.20260725.083715Z

package/lib/docs/vertesia-common.d.ts

@@ -0,0 +1,4404 @@
+// Generated by @vertesia/appgen-docs.
+// Do not edit by hand. This concatenates selected @vertesia/common declaration files
+// for generated app agents.
+//
+// Use this file before defining app package capabilities or data-backed screens:
+// - AppPackage, app capabilities, app UI/runtime metadata
+// - In-code types, processes, dashboards, and tool execution contracts
+// - ContentObject, ContentObjectItem, ObjectSearchResponse, collections, and store process types
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: index.d.ts
+// -----------------------------------------------------------------------------
+export * from './access-control.js';
+export * from './agent-request-template.js';
+export * from './analytics.js';
+/**
+ * Schema-derived API types. MUST stay `export type` — tsc erases it, so `lib/index.js` never
+ * references `./api-schemas/*` and zod stays out of the browser bundle. A runtime `export *` here
+ * would ship zod to every UI user; see `./api-schemas/index.ts` for why.
+ */
+export type { UserGroupArrayFromSchema } from './api-schemas/group.js';
+export type { PrincipalContextFromSchema, UserArrayFromSchema, UserRefArrayFromSchema, } from './api-schemas/user.js';
+export * from './apikey.js';
+export * from './apps.js';
+export * from './ask-user.js';
+export * from './audit-trail.js';
+export * from './browser-credentials.js';
+export * from './channels.js';
+export * from './common.js';
+export * from './cost-analytics.js';
+export * from './data-platform.js';
+export * from './embeddings.js';
+export * from './environment.js';
+export * from './facets.js';
+export * from './group.js';
+export * from './host-utils.js';
+export * from './integrations.js';
+export * from './interaction.js';
+export * from './json.js';
+export * from './json-schema.js';
+export * from './meters.js';
+export * from './model_utility.js';
+export * from './oauth.js';
+export * from './oauth-scopes.js';
+export * from './oauth-server.js';
+export * from './Progress.js';
+export * from './payload.js';
+export * from './pending-asks.js';
+export * from './platform-event.js';
+export * from './platform-event-validation.js';
+export * from './principal-context.js';
+export * from './project.js';
+export * from './prompt.js';
+export * from './query.js';
+export * from './rate-limiter.js';
+export * from './refs.js';
+export * from './roles/types.js';
+export * from './runs.js';
+export * from './schema-for-extraction.js';
+export * from './secrets.js';
+export * from './skill.js';
+export * from './store/index.js';
+export type { ContentObjectExportArtifact, ContentObjectExportArtifactFile, ContentObjectExportProgress, ContentObjectExportResult, ContentObjectExportStatusResponse, DeleteContentObjectExportResponse, ExportContentObjectsFilter, ExportContentObjectsIncludeOptions, ExportedContentObjectRecord, ListContentObjectExportsResponse, StartContentObjectExportRequest, StartContentObjectExportResponse, ZenoBulkContentObjectExportComposeRequest, ZenoBulkContentObjectExportPlanRequest, ZenoBulkContentObjectExportPlanResponse, ZenoBulkContentObjectExportRequest, ZenoBulkContentObjectExportShardRange, ZenoBulkContentObjectExportShardRequest, ZenoBulkContentObjectExportShardResult, ZenoBulkContentObjectExportSplitShardRequest, ZenoBulkContentObjectExportSplitShardResponse, } from './store/store.js';
+export * from './sts-token-types.js';
+export * from './tenant.js';
+export * from './tool-execution.js';
+export * from './tools.js';
+export * from './training.js';
+export * from './transient-tokens.js';
+export * from './user.js';
+export * from './utils/auth.js';
+export * from './utils/schemas.js';
+export type * from './utils/type-helpers.js';
+export * from './versions.js';
+export * from './view-configuration-validation.js';
+export * from './view-query-validation.js';
+export * from './view-validation-helpers.js';
+export * from './views.js';
+export * from './views-schema.js';
+export { type AppViewExperienceId, parseAppViewExperienceId, type ViewValidationIssue, validateViewExperienceId, } from './views-validation.js';
+export * from './workflow-analytics.js';
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: apps.d.ts
+// -----------------------------------------------------------------------------
+import type { z } from 'zod';
+import type { AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, DeleteAppVersionResponseSchema, OAuthClientCredentialsSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema } from './api-schemas/app-lifecycle.js';
+import type { AppInstallationListEntrySchema, AppInstallationSchema, AppInstallationWithManifestSchema, AppManifestDataSchema, AppManifestSchema, AppPackageSchema, AppWidgetInfoSchema, CompositeAppCardOverridesSchema, CompositeAppConfigPayloadSchema, CompositeAppConfigSchema, CompositeAppEntrySchema, CompositeAppHeaderItemKindSchema, CompositeAppHeaderItemSchema, CompositeAppHeaderItemTargetSchema, CompositeAppHeaderOverridesSchema, CompositeAppHomePluginSchema, CompositeAppLogoOverridesSchema, CompositeAppMenuSectionSchema, CompositeAppMessageOverridesSchema, CompositeAppMessageStyleSchema, CompositeAppNavItemPermissionsSchema, CompositeAppSidebarOverridesSchema, CompositeAppSwitchersOverridesSchema, CompositeAppThemeOverridesSchema, CompositeAppUserMenuOverridesSchema, PromoteAppVersionResponseSchema } from './api-schemas/app-runtime.js';
+import type { AppAccessControlSchema, AppAvailableInSchema, AppCapabilitiesSchema, AppGitSourceConfigSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPOAuthConfigSchema, MCPToolAnnotationsSchema, MCPToolCollectionObjectSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, ToolCollectionAuthTypeSchema, ToolCollectionObjectSchema, VertesiaSDKToolCollectionObjectSchema } from './api-schemas/apps.js';
+import type { RemoteActivityDefinitionSchema } from './api-schemas/integrations.js';
+import type { ProjectToolInfoSchema, RenderingTemplateDefinitionRefSchema, RenderingTemplateDefinitionSchema } from './api-schemas/project.js';
+/** Allowed values for AppUINavItem.preferredSection */
+export declare const PREFERRED_SECTIONS: readonly ["default", "footer", "settings"];
+/**
+ * Additional navigation item for an app's UI configuration.
+ * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
+ * Icon values are Lucide icon component names or SVG content strings.
+ */
+export interface AppUINavItem {
+    /** Display label */
+    label: string;
+    /** Lucide icon name or SVG content string */
+    icon: string;
+    /** Route path relative to app base */
+    route: string;
+    /** Optional description shown on dashboard cards and other summary views */
+    description?: string;
+    /** Nested sub-items displayed within this item's collapsible section */
+    children?: AppUINavItem[];
+    /** When true, this item appears as an independent entry in the sidebar (outside its parent app group) */
+    topLevel?: boolean;
+    /**
+     * Which sidebar section this item should be placed in when first added.
+     * - "default" or unset: normal behavior (child of its app group)
+     * - "footer": placed in the footer section
+     * - "settings": placed in the settings section
+     */
+    preferredSection?: (typeof PREFERRED_SECTIONS)[number];
+}
+export type AppUIConfig = z.infer<typeof AppUIConfigSchema>;
+export type AppInstallationProjectsQuery = z.infer<typeof AppInstallationProjectsQuerySchema>;
+export type AppInstallationsQuery = z.infer<typeof AppInstallationsQuerySchema>;
+export type ToolCollectionAuthType = z.infer<typeof ToolCollectionAuthTypeSchema>;
+/**
+ * Tool collection type
+ */
+export type ToolCollectionType = 'mcp' | 'vertesia_sdk';
+export type MCPOAuthConfig = z.infer<typeof MCPOAuthConfigSchema>;
+export type MCPToolCollectionObject = z.infer<typeof MCPToolCollectionObjectSchema>;
+export type VertesiaSDKToolCollectionObject = z.infer<typeof VertesiaSDKToolCollectionObjectSchema>;
+export type ToolCollectionObject = z.infer<typeof ToolCollectionObjectSchema>;
+/**
+ * Backward-compatible TypeScript alias. Public API payloads should reference
+ * ToolCollectionObject directly so generated clients do not create a wrapper
+ * model around the discriminated union.
+ */
+export type ToolCollection = ToolCollectionObject;
+export declare const MCP_COLLECTION_ID_PATTERN: RegExp;
+export declare const MCP_COLLECTION_NAMESPACE_PATTERN: RegExp;
+export declare function isValidMCPCollectionId(id: string): boolean;
+export declare function isValidMCPCollectionNamespace(namespace: string): boolean;
+export declare function deriveMCPCollectionId(input: string): string;
+export declare function getDefaultOAuthAppNameForCollectionId(collectionId: string): string;
+/**
+ * Normalizes a tool collection to the object format.
+ * Applies optional `{{var}}` substitution to the URL so manifests can reference
+ * deployment-time variables like `{{studio_ui}}`.
+ *
+ * @param collection - ToolCollectionObject
+ * @param vars - Optional endpoint variables to substitute in URLs
+ * @returns Normalized ToolCollectionObject
+ */
+export declare function normalizeToolCollection(collection: ToolCollectionObject, vars?: Endpoints): ToolCollectionObject;
+/**
+ * Metadata hints from MCP tool annotations (per MCP spec).
+ */
+export type MCPToolAnnotations = z.infer<typeof MCPToolAnnotationsSchema>;
+/**
+ * Approval behavior class for a tool exposed to agents.
+ *
+ * - `read_only`: reads or inspects state without changing Vertesia, external systems, or user-visible artifacts.
+ * - `side_effecting`: can create, update, delete, send, execute, schedule, or otherwise change state.
+ * - `control`: affects agent control flow or tool availability, not user data or external systems.
+ * - `requires_confirmation`: high-impact action that must ask the user even in interactive full-control mode.
+ */
+export type AgentToolApprovalClass = z.infer<typeof AgentToolApprovalClassSchema>;
+/**
+ * Tool definition with optional activation control for agent exposure.
+ */
+export type AgentToolDefinition = z.infer<typeof AgentToolDefinitionSchema>;
+/**
+ * Definition of a remote activity exposed by a tool server for use in DSL workflows.
+ * Remote activities are identified in workflow steps using colon-separated names:
+ * `app:<app_name>:<collection>:<activity_name>` (e.g. `app:my-nlp-app:examples:word_count`).
+ */
+export type RemoteActivityDefinition = z.infer<typeof RemoteActivityDefinitionSchema>;
+/**
+ * Canonical app capabilities Studio renders/supports. The public type is derived from
+ * this list so runtime validation and TypeScript cannot drift.
+ */
+export declare const APP_CAPABILITIES: readonly ["ui", "tools", "interactions", "types", "processes", "views", "templates", "dashboards"];
+export type AppCapabilities = z.infer<typeof AppCapabilitiesSchema>;
+/**
+ * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
+ * capability refs (`app:<app>:...`) against that exact version instead of the promoted version.
+ * Resolution-time only; never persisted. Set by the generated app template via client.withAppVersion.
+ */
+export declare const APP_VERSION_HEADER = "x-vertesia-app-version";
+/**
+ * The platform-artifact types an app build can be required to create. A finer-grained
+ * counterpart to {@link AppCapabilities}: a single `interactions` capability may comprise
+ * several `interaction` artifacts plus `agent`, `activity`, and `tool` artifacts that
+ * {@link AppCapabilities} folds together. Used by the App Solution Architect manifest and
+ * the publish-time capability gate.
+ */
+export declare const APP_ARTIFACT_TYPES: readonly ["interaction", "agent", "type", "process", "view", "template", "dashboard", "activity", "tool"];
+export type AppArtifactType = (typeof APP_ARTIFACT_TYPES)[number];
+/**
+ * A single platform artifact the App Solution Architect requires the build to create.
+ * `id` is the app-owned in-code id the implementation must register and reference
+ * (e.g. `app:<name>:main:extract-item` for interactions/agents, `app:<name>:<type>` for
+ * types, `app:<name>:<process>` for processes).
+ */
+/**
+ * Build progress for one artifact, maintained by the developer agent as a living checklist:
+ *  - `pending` — defined by the architect, not yet built.
+ *  - `built`   — registered in the package, not yet successfully exercised.
+ *  - `done`    — built AND successfully exercised against real data.
+ * This is the agent's self-reported claim for tracking/handoff; the capability gate verifies
+ * the truth independently via package registration + run/data telemetry and does not trust it.
+ */
+export type AppArtifactStatus = 'pending' | 'built' | 'done';
+export declare const APP_ARTIFACT_STATUSES: readonly AppArtifactStatus[];
+export interface AppPlannedArtifact {
+    /** App-owned in-code id the build must register and reference. */
+    id: string;
+    type: AppArtifactType;
+    /** Short human label. */
+    name?: string;
+    /** Why this artifact exists / what it does — carried into the build checklist. */
+    purpose?: string;
+    /**
+     * When false, the artifact is planned but optional: the capability gate warns rather
+     * than blocks if it is missing or never exercised. Defaults to required (true).
+     */
+    required?: boolean;
+    /** Build progress, updated by the developer agent. Defaults to `pending`. */
+    status?: AppArtifactStatus;
+}
+/**
+ * Structured result the App Solution Architect emits alongside its prose artifacts — the
+ * machine-readable contract for the build. The implementation MUST create and successfully
+ * exercise every required artifact before building a deployable version. Persisted into the app repo as
+ * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the version-build
+ * capability gate can verify against it deterministically. If the builder finds the plan
+ * wrong or insufficient, the orchestrator relaunches the architect to revise the manifest;
+ * the gate always checks against the latest committed copy.
+ */
+export interface AppCapabilityManifest {
+    /** Artifact-storage ref to the prose architecture spec (e.g. the architecture `.md`). */
+    spec_artifact: string;
+    /** Platform artifacts the build must create. */
+    artifacts: AppPlannedArtifact[];
+    /**
+     * Monotonic revision, starting at 1, bumped each time the architect evolves the manifest for
+     * the SAME app on a later iteration (read the committed manifest, preserve untouched artifacts,
+     * add/modify/remove, then bump). Lets downstream agents tell which contract they are building to.
+     */
+    revision?: number;
+    /**
+     * Newest-first change notes, one entry per revision (what was added/modified/removed and why).
+     * How manifest changes are communicated to downstream agents across iterations.
+     */
+    changelog?: string[];
+    /** Optional free-form notes the architect wants the builder to honor. */
+    notes?: string;
+}
+/** Repo-relative path the capability manifest is committed to, read by version-build gates. */
+export declare const APP_CAPABILITY_MANIFEST_PATH = "docs/app-capability-manifest.json";
+export type AppAvailableIn = z.infer<typeof AppAvailableInSchema>;
+export type AppVersionKind = z.infer<typeof AppVersionKindSchema>;
+export type AppVersionState = z.infer<typeof AppVersionStateSchema>;
+export type AppVersionTarget = z.infer<typeof AppVersionTargetSchema>;
+export type AppVersionGitRefType = z.infer<typeof AppVersionGitRefTypeSchema>;
+export type AppBuildTrigger = z.infer<typeof AppBuildTriggerSchema>;
+export type AppVersionStorage = z.infer<typeof AppVersionStorageSchema>;
+export type AppVersionGitSource = z.infer<typeof AppVersionGitSourceSchema>;
+export type AppVersionUrls = z.infer<typeof AppVersionUrlsSchema>;
+export type AppVersionRecord = z.infer<typeof AppVersionRecordSchema>;
+export type DeleteAppVersionResponse = z.infer<typeof DeleteAppVersionResponseSchema>;
+export type UpsertAppVersionRequest = z.infer<typeof UpsertAppVersionRequestSchema>;
+export interface AppVersionListQuery {
+    app_id?: string;
+    kind?: AppVersionKind;
+    include_expired?: boolean;
+    limit?: number;
+}
+export type PromoteAppVersionResponse = z.infer<typeof PromoteAppVersionResponseSchema>;
+export type StartAppBuildRequest = z.infer<typeof StartAppBuildRequestSchema>;
+export type StartAppBuildResponse = z.infer<typeof StartAppBuildResponseSchema>;
+export interface AppBuildWorkflowInput extends StartAppBuildRequest {
+    app_id: string;
+    app_record_id?: string;
+    /** Rebuild this persisted version record at its original commit and target. */
+    rebuild_version_record_id?: string;
+    app_title?: string;
+    app_description?: string;
+    source_git_url?: string;
+}
+export interface AppBuildWorkflowResult {
+    app_id: string;
+    version_id: string;
+    kind: Extract<AppVersionKind, 'version'>;
+    state: AppVersionState;
+    source_commit: string;
+    source_git?: AppVersionGitSource;
+    urls?: AppVersionUrls;
+    file_count?: number;
+}
+export type AppBuildProgressStatus = z.infer<typeof AppBuildProgressStatusSchema>;
+export type AppBuildProgress = z.infer<typeof AppBuildProgressSchema>;
+export type AppScaffoldModule = z.infer<typeof AppScaffoldModuleSchema>;
+export type StartAppScaffoldRequest = z.infer<typeof StartAppScaffoldRequestSchema>;
+export type StartAppScaffoldResponse = z.infer<typeof StartAppScaffoldResponseSchema>;
+export interface AppScaffoldWorkflowInput extends StartAppScaffoldRequest {
+}
+export interface AppScaffoldWorkflowResult {
+    app_id: string;
+    app_record_id?: string;
+    installation_id?: string;
+    git_url?: string;
+    source_git?: AppVersionGitSource;
+    files?: number;
+    initial_version_build?: StartAppBuildResponse;
+}
+export type AppScaffoldProgressStatus = z.infer<typeof AppScaffoldProgressStatusSchema>;
+export type AppScaffoldProgress = z.infer<typeof AppScaffoldProgressSchema>;
+/**
+ * Access control policy for an app installation.
+ * Declares which access surfaces are gated by per-user ACEs.
+ *
+ * - 'all' (default): every surface (UI portal, tool/endpoint use, contributions) requires
+ *   an explicit app_member ACE — the historical behavior.
+ * - 'ui': UI portal visibility requires an ACE, but tool/endpoint use and contributions
+ *   are open to anyone in the project.
+ * - 'none': fully open within the project — no ACE required for any surface.
+ *
+ * Declared on the manifest as the app's default. May be overridden per-installation.
+ */
+export type AppAccessControl = z.infer<typeof AppAccessControlSchema>;
+/**
+ * Resolve the effective access_control policy for an installed app:
+ * installation override wins, then manifest default, then `'all'`.
+ *
+ * Shared by the STS (JWT generation), the studio-server (validation), and the UI (badge display)
+ * so the resolution rule lives in exactly one place. Named `effectiveAppAccessControl` (not just
+ * `effectiveAccessControl`) because exports from `@vertesia/common` are flattened — the broader
+ * name would risk colliding with other access-control families added later.
+ */
+export declare function effectiveAppAccessControl(installation: {
+    access_control?: AppAccessControl;
+} | null | undefined, manifest: {
+    access_control?: AppAccessControl;
+} | null | undefined): AppAccessControl;
+export type AppManifestData = z.infer<typeof AppManifestDataSchema>;
+export type AppGitSourceConfig = z.infer<typeof AppGitSourceConfigSchema>;
+export type AppSourceConfig = z.infer<typeof AppSourceConfigSchema>;
+/**
+ * Deployment-time URL endpoints that can be referenced in app manifest URLs
+ * via `{{key}}` placeholders. The caller (typically studio-server) supplies
+ * these from environment config so that system apps can ship a single manifest
+ * with endpoints like `{{studio}}/api/package` that resolve per deployment.
+ */
+export interface Endpoints {
+    /** The Studio API (studio-server) base URL */
+    studio?: string;
+    /** The Store API (zeno-server) base URL */
+    store?: string;
+    /** The token server base URL */
+    token?: string;
+    /** The browser-facing Studio UI (composable-ui) base URL */
+    ui?: string;
+    /** The Smart HTTP app source git server base URL */
+    git?: string;
+    /** The appgen app-gateway base URL (serves promoted app bundles + their `/api` runtime). */
+    gateway?: string;
+}
+/** One entry in an app git-repo directory listing (see {@link AppRepoTree}). */
+export type AppRepoTreeEntry = z.infer<typeof AppRepoTreeEntrySchema>;
+/** A non-recursive listing of an app git repo directory at a given ref. */
+export type AppRepoTree = z.infer<typeof AppRepoTreeSchema>;
+/** Browser-side limits mirrored by the app Git service document endpoint. */
+export declare const APP_REPO_DOCUMENT_UPLOAD_MAX_FILE_BYTES: number;
+export declare const APP_REPO_DOCUMENT_UPLOAD_MAX_TOTAL_BYTES: number;
+export declare const APP_REPO_DOCUMENT_UPLOAD_MAX_FILES = 20;
+export declare const APP_REPO_DOCUMENT_UPLOAD_PREFIX = "docs/";
+/** Result of committing one or more uploaded documents to an app repository. */
+export type AppRepoDocumentCommit = z.infer<typeof AppRepoDocumentCommitSchema>;
+/** One commit that inserted or changed a file in an app git repository. */
+export type AppRepoCommit = z.infer<typeof AppRepoCommitSchema>;
+/** Commit history in an app git repository, optionally filtered to a file. */
+export type AppRepoCommits = z.infer<typeof AppRepoCommitsSchema>;
+/** A branch or tag in an app git repo, resolved to its latest commit. */
+export type AppRepoRef = z.infer<typeof AppRepoRefSchema>;
+/** The branches and tags of an app git repo (see {@link AppRepoRef}). */
+export type AppRepoRefs = z.infer<typeof AppRepoRefsSchema>;
+/** A mutable app development task represented by an `agent/*` Git branch. */
+export type AppDevelopmentTask = z.infer<typeof AppDevelopmentTaskSchema>;
+/** Git-backed development tasks and the branch used for new tasks by default. */
+export type AppDevelopmentTaskList = z.infer<typeof AppDevelopmentTaskListSchema>;
+/** Development task details, including the latest parent assistant run when one exists. */
+export type AppDevelopmentTaskDetails = z.infer<typeof AppDevelopmentTaskDetailsSchema>;
+/** Request to create a branch from an existing branch, tag, or commit. */
+export interface CreateAppRepoBranchRequest {
+    name: string;
+    source_ref: string;
+}
+/** A newly created app repository branch. */
+export type AppRepoBranch = z.infer<typeof AppRepoBranchSchema>;
+/**
+ * Canonical package scopes, including the catch-all `all`. The public type is derived
+ * from this list so request parsing and TypeScript cannot drift.
+ */
+export declare const APP_PACKAGE_SCOPES: readonly ["ui", "tools", "interactions", "types", "processes", "views", "templates", "dashboards", "settings", "widgets", "activities", "all"];
+export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
+export type AppPackage = z.infer<typeof AppPackageSchema>;
+/**
+ * A single diagnostic produced while inspecting an app's registration state.
+ */
+export type AppInspectionIssue = z.infer<typeof AppInspectionIssueSchema>;
+/**
+ * Per-capability report of what an app's promoted package actually exposes,
+ * compared against what its manifest declares.
+ */
+export type AppInspectionCapabilityReport = z.infer<typeof AppInspectionCapabilityReportSchema>;
+/**
+ * Result of inspecting an app's registration: the resolved manifest state, what
+ * the promoted package actually exposes per capability, and diagnostics. This
+ * is the ground truth used by the `app_inspect_registration` agent tool and the
+ * Build › App inspection UI to verify what is registered vs declared, instead of
+ * inferring it from failed object/import calls.
+ */
+export type AppInspectionResult = z.infer<typeof AppInspectionResultSchema>;
+export type AppWidgetInfo = z.infer<typeof AppWidgetInfoSchema>;
+export type RenderingTemplateDefinition = z.infer<typeof RenderingTemplateDefinitionSchema>;
+export type RenderingTemplateDefinitionRef = z.infer<typeof RenderingTemplateDefinitionRefSchema>;
+export type AppManifest = z.infer<typeof AppManifestSchema>;
+export type AppManifestSource = z.infer<typeof AppManifestSourceSchema>;
+/**
+ * Binding between an MCP collection and an OAuth provider created at install time.
+ * Stored on AppInstallation so the runtime can look up the correct OAuth provider by ID,
+ * independent of manifest oauth_provider references (which may change).
+ */
+export type AppInstallationOAuthBinding = z.infer<typeof AppInstallationOAuthBindingSchema>;
+/**
+ * Binding between a named OAuth provider and the OAuth provider created for it at install time.
+ * Stored on AppInstallation so the runtime can resolve the correct OAuth provider for collections
+ * that reference a shared provider via MCPToolCollectionObject.oauth_provider.
+ */
+export type AppInstallationProviderBinding = z.infer<typeof AppInstallationProviderBindingSchema>;
+export type AppInstallation = z.infer<typeof AppInstallationSchema>;
+export type AppInstallationWithManifest = z.infer<typeof AppInstallationWithManifestSchema>;
+export type AppInstallationListEntry = z.infer<typeof AppInstallationListEntrySchema>;
+export interface OrphanedAppInstallation extends Omit<AppInstallation, 'manifest'> {
+    manifest: null;
+}
+export type OAuthClientCredentials = z.infer<typeof OAuthClientCredentialsSchema>;
+export type AppOAuthCollectionParams = z.infer<typeof AppOAuthCollectionParamsSchema>;
+export type AppOAuthProviderParams = z.infer<typeof AppOAuthProviderParamsSchema>;
+export type AppInstallationPayload = z.infer<typeof AppInstallationPayloadSchema>;
+export type UpdateAppInstallationToolAllowlistPayload = z.infer<typeof UpdateAppInstallationToolAllowlistPayloadSchema>;
+export type AppInstallationKind = z.infer<typeof AppInstallationKindSchema>;
+/**
+ * A description of the tools provided by an app
+ */
+export type AppToolCollection = z.infer<typeof AppToolCollectionSchema>;
+/**
+ * A tool and the app installation that provides it, inferred from `./api-schemas/project.js` — the
+ * module that owns it, because it converted with the Projects batch rather than with Apps.
+ */
+export type ProjectToolInfo = z.infer<typeof ProjectToolInfoSchema>;
+/**
+ * OAuth authentication status for an MCP tool collection
+ */
+export type OAuthAuthStatus = z.infer<typeof OAuthAuthStatusSchema>;
+/**
+ * Response from OAuth authorization endpoint
+ */
+export type OAuthAuthorizeResponse = z.infer<typeof OAuthAuthorizeResponseSchema>;
+export interface McpOAuthCollectionRef {
+    app_install_id: string;
+    collection_id: string;
+}
+export type McpOAuthTokenRequest = z.infer<typeof McpOAuthTokenRequestSchema>;
+export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponseSchema>;
+export type McpOAuthConnectResponse = z.infer<typeof McpOAuthConnectResponseSchema>;
+export type McpOAuthDisconnectResponse = z.infer<typeof McpOAuthDisconnectResponseSchema>;
+/**
+ * Response from OAuth metadata endpoint
+ */
+export type OAuthMetadataResponse = z.infer<typeof OAuthMetadataResponseSchema>;
+/**
+ * Configuration entry for an individual app in the CompositeApp shell.
+ * References an app installation by name.
+ */
+export type CompositeAppEntry = z.infer<typeof CompositeAppEntrySchema>;
+/**
+ * Logo overrides for the CompositeApp shell header.
+ * When provided, these URLs replace the default Vertesia logo.
+ */
+export type CompositeAppLogoOverrides = z.infer<typeof CompositeAppLogoOverridesSchema>;
+/**
+ * Message banner overrides for the shell header.
+ */
+export type CompositeAppMessageStyle = z.infer<typeof CompositeAppMessageStyleSchema>;
+export type CompositeAppMessageOverrides = z.infer<typeof CompositeAppMessageOverridesSchema>;
+/**
+ * Switcher visibility overrides for the CompositeApp header.
+ */
+export type CompositeAppSwitchersOverrides = z.infer<typeof CompositeAppSwitchersOverridesSchema>;
+/**
+ * Header button visibility overrides for the CompositeApp header.
+ *
+ * @deprecated Superseded by `CompositeAppConfig.headerMenu` (free-form header items).
+ * Retained for backward compatibility and to seed the default header menu when no
+ * `headerMenu` has been configured yet.
+ */
+export type CompositeAppHeaderOverrides = z.infer<typeof CompositeAppHeaderOverridesSchema>;
+/**
+ * User menu overrides for the CompositeApp.
+ *
+ * @deprecated Superseded by the `user_menu` item in `CompositeAppConfig.headerMenu`.
+ * Retained for backward compatibility and to seed the default header menu when no
+ * `headerMenu` has been configured yet.
+ */
+export type CompositeAppUserMenuOverrides = z.infer<typeof CompositeAppUserMenuOverridesSchema>;
+/**
+ * Theme overrides for the CompositeApp.
+ */
+export type CompositeAppThemeOverrides = z.infer<typeof CompositeAppThemeOverridesSchema>;
+/**
+ * Sidebar display overrides for the CompositeApp.
+ */
+export type CompositeAppSidebarOverrides = z.infer<typeof CompositeAppSidebarOverridesSchema>;
+/**
+ * Card display overrides for the CompositeApp in the App Portal.
+ * Similar to AppManifest display properties, but specific to the CompositeApp card.
+ * Allows customers to customize the app portal card (not otherwise possible if using a
+ * shared, Vertesia-managed manifest across accounts).
+ */
+export type CompositeAppCardOverrides = z.infer<typeof CompositeAppCardOverridesSchema>;
+/**
+ * Access control settings for a composite app nav item.
+ *
+ * If any of `groupsAllowed`, `usersAllowed`, or `rolesAllowed` are set,
+ * access is granted when the user matches ANY list (OR logic).
+ * All empty/absent means visible to everyone. Admin users bypass all checks.
+ */
+export type CompositeAppNavItemPermissions = z.infer<typeof CompositeAppNavItemPermissionsSchema>;
+/**
+ * A navigable item in the sidebar menu.
+ * An "app" is just a nav-item with `appName` + `route: "/"` that has children.
+ * Nav-items carry their own `appName` for routing, independent of position in the tree.
+ */
+export interface CompositeAppMenuNavItem {
+    /** Stable unique identifier */
+    id: string;
+    /** Display label shown in the sidebar */
+    label: string;
+    /** Lucide icon name or SVG content string */
+    icon?: string;
+    /** Which installed app this item routes to */
+    appName?: string;
+    /** Route path within the app (e.g. "/" or "/dashboard") */
+    route?: string;
+    /** When true, this item is hidden from the sidebar */
+    hidden?: boolean;
+    /**
+     * Optional description for dashboard cards and summary views.
+     * `null` = user explicitly cleared it (show no description, skip fallback).
+     * `undefined` / absent = no override (fall back to manifest description).
+     */
+    description?: string | null;
+    /** When true, this item is excluded from the Composite App dashboard cards */
+    hideFromDashboard?: boolean;
+    /** Optional access control settings for this nav item */
+    permissions?: CompositeAppNavItemPermissions;
+    /** Ordered child nav-items */
+    children?: CompositeAppMenuNavItem[];
+}
+/**
+ * A top-level section heading in the sidebar menu.
+ * Sections are always at root level and contain nav-items.
+ */
+export type CompositeAppMenuSection = z.infer<typeof CompositeAppMenuSectionSchema>;
+export type CompositeAppHomePlugin = z.infer<typeof CompositeAppHomePluginSchema>;
+/**
+ * Discriminator for a header item.
+ * The four built-ins (`app_portal`, `docs`, `help`, `user_menu`) seed the default
+ * header and cannot be deleted (only hidden/customized); `custom` items are fully
+ * user-defined buttons.
+ */
+export type CompositeAppHeaderItemKind = z.infer<typeof CompositeAppHeaderItemKindSchema>;
+/** Where a header link opens. */
+export type CompositeAppHeaderItemTarget = z.infer<typeof CompositeAppHeaderItemTargetSchema>;
+/** Stable identifiers for the built-in header items. */
+export declare const COMPOSITE_APP_HEADER_BUILTIN_IDS: readonly ["app_portal", "docs", "help", "user_menu"];
+/**
+ * A single button in the CompositeApp header bar.
+ *
+ * Unlike sidebar nav-items, header items are free-form and not tied to an installed
+ * app: each is a labelled, icon-bearing button linking to a route or external URL.
+ * The `user_menu` item is special — it renders the account dropdown, so its `icon`,
+ * `href`, and `target` are ignored.
+ */
+export type CompositeAppHeaderItem = z.infer<typeof CompositeAppHeaderItemSchema>;
+/**
+ * CompositeApp shell configuration.
+ * This is the main configuration interface for storing CompositeApp settings.
+ * Used as the MongoDB model for persisting CompositeApp configurations.
+ */
+export type CompositeAppConfig = z.infer<typeof CompositeAppConfigSchema>;
+export type CompositeAppConfigPayload = z.infer<typeof CompositeAppConfigPayloadSchema>;
+export type ValidateUrlRequest = z.infer<typeof ValidateUrlRequestSchema>;
+export type ValidateUrlResponse = z.infer<typeof ValidateUrlResponseSchema>;
+/**
+ * Result of DELETE /api/v1/apps/:id. With `?confirm=true` the cascade runs and
+ * `deleted: true` is set; without it the endpoint returns a dry-run summary so
+ * the UI can show what would be removed.
+ */
+export interface AppDeleteSummary {
+    confirmed: boolean;
+    app_id: string;
+    app_name: string;
+    versions: number;
+    installations: number;
+    storage_prefix: string;
+    git_repo_url?: string;
+    deleted: boolean;
+    warnings: string[];
+}
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: data-platform.d.ts
+// -----------------------------------------------------------------------------
+import type { AppDashboardDefinitionSchema } from './api-schemas/app-runtime.js';
+/**
+ * Data Platform Types
+ *
+ * Types for managing versioned analytical data stores with DuckDB + GCS storage.
+ * Supports AI-manageable schemas and multi-table atomic operations.
+ */
+import type { z } from 'zod';
+import type { CreateDashboardPayloadSchema, CreateDashboardSnapshotPayloadSchema, DashboardArchiveResultSchema, DashboardBulkArchiveResultSchema, DashboardBulkDeleteResultSchema, DashboardDataSourceSchema, DashboardElasticsearchDslSchema, DashboardElasticsearchResultMappingSchema, DashboardItemSchema, DashboardLayoutSchema, DashboardPanelPositionSchema, DashboardPanelSchema, DashboardQuerySchema, DashboardSchema, DashboardSqlDataSourceSchema, DashboardStatusSchema, DashboardStoreElasticsearchDataSourceSchema, DashboardVersionItemSchema, DashboardVersioningPayloadSchema, DashboardVersioningStatusResponseSchema, DashboardVersionSchema, PromoteDashboardVersionPayloadSchema, UpdateDashboardPayloadSchema } from './api-schemas/dashboard.js';
+import type { AlterTableOperationSchema, AlterTablePayloadSchema, BatchQueryPayloadSchema, BatchQueryResultItemSchema, BatchQueryResultSchema, CreateDataStorePayloadSchema, CreateSnapshotPayloadSchema, CreateTablePayloadSchema, CreateTablesPayloadSchema, DataColumnForAISchema, DataColumnSchema, DataColumnTypeSchema, DataForeignKeyForAISchema, DataForeignKeySchema, DataIndexSchema, DataRelationshipForAISchema, DataRelationshipSchema, DataRelationshipTypeSchema, DataSchemaForAISchema, DataSchemaSchema, DataStoreArchiveResultSchema, DataStoreDownloadInfoSchema, DataStoreFullSchemaResponseSchema, DataStoreItemSchema, DataStoreMutateRowsPayloadSchema, DataStoreMutateRowsResultSchema, DataStoreSchema, DataStoreSchemaResponseSchema, DataStoreStatusSchema, DataStoreTableDetailSchema, DataStoreTableDropResultSchema, DataStoreVersionSchema, DataStoreVersionTableStateSchema, DataTableForAISchema, DataTableSchema, DataTableSemanticTypeSchema, DataTableSummarySchema, GetDataStoreTableQuerySchema, ImportDataFormatSchema, ImportDataPayloadSchema, ImportDataSourceSchema, ImportJobSchema, ImportStatusSchema, ImportTableDataSchema, ListDataStoreVersionsQuerySchema, QueryPayloadSchema, QueryResultColumnSchema, QueryResultSchema, QueryValidationErrorSchema, QueryValidationPayloadSchema, QueryValidationResultSchema, SemanticColumnTypeSchema, UpdateSchemaPayloadSchema } from './api-schemas/data-store.js';
+/**
+ * Supported column data types for DuckDB tables.
+ */
+export declare const DataColumnType: {
+    readonly STRING: "STRING";
+    readonly INTEGER: "INTEGER";
+    readonly BIGINT: "BIGINT";
+    readonly FLOAT: "FLOAT";
+    readonly DOUBLE: "DOUBLE";
+    readonly DECIMAL: "DECIMAL";
+    readonly BOOLEAN: "BOOLEAN";
+    readonly DATE: "DATE";
+    readonly TIMESTAMP: "TIMESTAMP";
+    readonly JSON: "JSON";
+};
+export type DataColumnType = z.infer<typeof DataColumnTypeSchema>;
+/**
+ * Semantic types that provide AI agents with context about column meaning.
+ */
+export declare const SemanticColumnType: {
+    readonly EMAIL: "email";
+    readonly PHONE: "phone";
+    readonly URL: "url";
+    readonly CURRENCY: "currency";
+    readonly PERCENTAGE: "percentage";
+    readonly PERSON_NAME: "person_name";
+    readonly ADDRESS: "address";
+    readonly COUNTRY: "country";
+    readonly DATE_ISO: "date_iso";
+    readonly IDENTIFIER: "identifier";
+};
+export type SemanticColumnType = z.infer<typeof SemanticColumnTypeSchema>;
+/**
+ * Mapping from DataColumnType to DuckDB SQL types.
+ */
+export declare const DATA_COLUMN_TYPE_TO_DUCKDB: Record<DataColumnType, string>;
+/**
+ * Column definition for a data table.
+ */
+export type DataColumn = z.infer<typeof DataColumnSchema>;
+/**
+ * Foreign key constraint definition.
+ */
+export type DataForeignKey = z.infer<typeof DataForeignKeySchema>;
+/**
+ * Index definition for a table.
+ */
+export type DataIndex = z.infer<typeof DataIndexSchema>;
+/**
+ * Semantic type categorization for tables.
+ */
+export type DataTableSemanticType = z.infer<typeof DataTableSemanticTypeSchema>;
+/**
+ * Table definition within a data schema.
+ */
+export type DataTable = z.infer<typeof DataTableSchema>;
+/**
+ * Summary view of a data table (for listings).
+ */
+export type DataTableSummary = z.infer<typeof DataTableSummarySchema>;
+/**
+ * Relationship type between tables.
+ */
+export type DataRelationshipType = z.infer<typeof DataRelationshipTypeSchema>;
+/**
+ * Semantic relationship between tables for AI understanding.
+ */
+export type DataRelationship = z.infer<typeof DataRelationshipSchema>;
+/**
+ * Complete schema definition for a data store.
+ */
+export type DataSchema = z.infer<typeof DataSchemaSchema>;
+export type DataStoreFullSchemaResponse = z.infer<typeof DataStoreFullSchemaResponseSchema>;
+/**
+ * Data store lifecycle status.
+ */
+export declare const DataStoreStatus: {
+    readonly CREATING: "creating";
+    readonly ACTIVE: "active";
+    readonly ERROR: "error";
+    readonly ARCHIVED: "archived";
+};
+export type DataStoreStatus = z.infer<typeof DataStoreStatusSchema>;
+/**
+ * Summary view of a data store (for listings).
+ */
+export type DataStoreItem = z.infer<typeof DataStoreItemSchema>;
+/**
+ * Full data store with schema details.
+ */
+export type DataStore = z.infer<typeof DataStoreSchema>;
+/**
+ * Table state within a version.
+ */
+export type DataStoreVersionTableState = z.infer<typeof DataStoreVersionTableStateSchema>;
+/**
+ * A point-in-time version of a data store.
+ */
+export type DataStoreVersion = z.infer<typeof DataStoreVersionSchema>;
+export type ListDataStoreVersionsQuery = z.infer<typeof ListDataStoreVersionsQuerySchema>;
+export type GetDataStoreTableQuery = z.infer<typeof GetDataStoreTableQuerySchema>;
+/**
+ * Import job status.
+ */
+export declare const ImportStatus: {
+    readonly PENDING: "pending";
+    readonly PROCESSING: "processing";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly ROLLED_BACK: "rolled_back";
+};
+export type ImportStatus = z.infer<typeof ImportStatusSchema>;
+/**
+ * Import job tracking.
+ */
+export type ImportJob = z.infer<typeof ImportJobSchema>;
+/**
+ * Payload for creating a new data store.
+ */
+export type CreateDataStorePayload = z.infer<typeof CreateDataStorePayloadSchema>;
+/**
+ * Payload for creating a new table.
+ */
+export type CreateTablePayload = z.infer<typeof CreateTablePayloadSchema>;
+/**
+ * Payload for creating multiple tables atomically.
+ */
+export type CreateTablesPayload = z.infer<typeof CreateTablesPayloadSchema>;
+export type QueryValidationPayload = z.infer<typeof QueryValidationPayloadSchema>;
+export type BatchQueryPayload = z.infer<typeof BatchQueryPayloadSchema>;
+/**
+ * Schema change operation types.
+ */
+/**
+ * @discriminator op
+ */
+export type AlterTableOperation = z.infer<typeof AlterTableOperationSchema>;
+/**
+ * Payload for altering a table schema.
+ */
+export type AlterTablePayload = z.infer<typeof AlterTablePayloadSchema>;
+/**
+ * Payload for AI-driven bulk schema updates.
+ */
+export type UpdateSchemaPayload = z.infer<typeof UpdateSchemaPayloadSchema>;
+/**
+ * Data source for import.
+ * - 'inline': data provided directly in the payload
+ * - 'gcs': data in Google Cloud Storage (gs://bucket/path)
+ * - 'url': data at an HTTPS URL
+ * - 'artifact': data from workflow artifact (resolved to GCS by tool)
+ */
+export type ImportDataSource = z.infer<typeof ImportDataSourceSchema>;
+/**
+ * Data format for external sources.
+ */
+export type ImportDataFormat = z.infer<typeof ImportDataFormatSchema>;
+/**
+ * Table data specification for import.
+ */
+export type ImportTableData = z.infer<typeof ImportTableDataSchema>;
+/**
+ * Payload for importing data into tables.
+ */
+export type ImportDataPayload = z.infer<typeof ImportDataPayloadSchema>;
+/**
+ * Payload for creating a named snapshot.
+ */
+export type CreateSnapshotPayload = z.infer<typeof CreateSnapshotPayloadSchema>;
+/**
+ * Payload for executing a query.
+ */
+export type QueryPayload = z.infer<typeof QueryPayloadSchema>;
+/**
+ * Payload for mutating data rows with a single SQL statement.
+ */
+export type DataStoreMutateRowsPayload = z.infer<typeof DataStoreMutateRowsPayloadSchema>;
+/**
+ * Result from mutating rows in a data store.
+ */
+export type DataStoreMutateRowsResult = z.infer<typeof DataStoreMutateRowsResultSchema>;
+/**
+ * Column metadata in query results.
+ */
+export type QueryResultColumn = z.infer<typeof QueryResultColumnSchema>;
+/**
+ * Query execution result.
+ */
+export type QueryResult = z.infer<typeof QueryResultSchema>;
+export type BatchQueryResultItem = z.infer<typeof BatchQueryResultItemSchema>;
+export type BatchQueryResult = z.infer<typeof BatchQueryResultSchema>;
+export type QueryValidationError = z.infer<typeof QueryValidationErrorSchema>;
+export type QueryValidationResult = z.infer<typeof QueryValidationResultSchema>;
+export type DataStoreDownloadInfo = z.infer<typeof DataStoreDownloadInfoSchema>;
+export type DataStoreArchiveResult = z.infer<typeof DataStoreArchiveResultSchema>;
+/**
+ * @discriminator schema_format
+ */
+export type DataStoreSchemaResponse = z.infer<typeof DataStoreSchemaResponseSchema>;
+export type DataStoreTableDetail = z.infer<typeof DataStoreTableDetailSchema>;
+export type DataStoreTableDropResult = z.infer<typeof DataStoreTableDropResultSchema>;
+export type DashboardArchiveResult = z.infer<typeof DashboardArchiveResultSchema>;
+export type DashboardBulkArchiveResult = z.infer<typeof DashboardBulkArchiveResultSchema>;
+export type DashboardBulkDeleteResult = z.infer<typeof DashboardBulkDeleteResultSchema>;
+export type DashboardVersioningStatusResponse = z.infer<typeof DashboardVersioningStatusResponseSchema>;
+export type DashboardVersioningPayload = z.infer<typeof DashboardVersioningPayloadSchema>;
+/**
+ * Simplified column representation for AI agents.
+ */
+export type DataColumnForAI = z.infer<typeof DataColumnForAISchema>;
+/**
+ * Simplified foreign key representation for AI agents.
+ */
+export type DataForeignKeyForAI = z.infer<typeof DataForeignKeyForAISchema>;
+/**
+ * Simplified table representation for AI agents.
+ */
+export type DataTableForAI = z.infer<typeof DataTableForAISchema>;
+/**
+ * Simplified relationship representation for AI agents.
+ */
+export type DataRelationshipForAI = z.infer<typeof DataRelationshipForAISchema>;
+/**
+ * Simplified schema representation optimized for AI agent consumption.
+ * Provides semantic context for understanding the data model.
+ */
+export type DataSchemaForAI = z.infer<typeof DataSchemaForAISchema>;
+/**
+ * Version retention configuration.
+ */
+export interface DataStoreRetentionConfig {
+    /** Keep versions for this many days */
+    retention_days: number;
+    /** Named snapshots are exempt from retention */
+    snapshots_exempt: boolean;
+}
+/**
+ * Default retention configuration: 30 days, snapshots exempt.
+ */
+export declare const DEFAULT_RETENTION_CONFIG: DataStoreRetentionConfig;
+/**
+ * Dashboard lifecycle status.
+ */
+export declare const DashboardStatus: {
+    /** Dashboard is active and usable */
+    readonly ACTIVE: "active";
+    /** Dashboard has been archived (soft deleted) */
+    readonly ARCHIVED: "archived";
+};
+export type DashboardStatus = z.infer<typeof DashboardStatusSchema>;
+/**
+ * Named SQL query that maps to a Vega data source.
+ * Supports parameterized SQL with {{param_name}} placeholders.
+ *
+ * @deprecated Use single `query` field on Dashboard instead. Multiple queries
+ * prevent cross-panel interactivity. Use JOINs/CTEs in a single query.
+ */
+export type DashboardQuery = z.infer<typeof DashboardQuerySchema>;
+/**
+ * Panel position within the dashboard grid.
+ *
+ * @deprecated Use combined Vega-Lite spec with vconcat/hconcat instead.
+ */
+export type DashboardPanelPosition = z.infer<typeof DashboardPanelPositionSchema>;
+/**
+ * Dashboard panel with Vega/Vega-Lite visualization.
+ *
+ * @deprecated Use combined Vega-Lite spec with vconcat/hconcat instead.
+ * Combined specs enable cross-panel interactivity (selections filtering other panels).
+ */
+export type DashboardPanel = z.infer<typeof DashboardPanelSchema>;
+/**
+ * Dashboard layout configuration.
+ *
+ * @deprecated Layout is now handled within the Vega-Lite spec via vconcat/hconcat.
+ */
+export type DashboardLayout = z.infer<typeof DashboardLayoutSchema>;
+/**
+ * Default layout configuration for dashboards.
+ *
+ * @deprecated Use combined Vega-Lite spec with vconcat/hconcat instead.
+ */
+export declare const DEFAULT_DASHBOARD_LAYOUT: DashboardLayout;
+/**
+ * SQL query parameters with default values.
+ * Supports {{param_name}} placeholders in SQL that get substituted at runtime.
+ */
+export interface DashboardQueryParameters {
+    /** Default values for SQL parameters. Keys are parameter names (without braces). */
+    defaults: Record<string, string>;
+}
+/**
+ * Elasticsearch DSL supported by dashboard data sources.
+ * Queries execute through Vertesia Store, so project/security filtering remains server-side.
+ */
+export type DashboardElasticsearchDsl = z.infer<typeof DashboardElasticsearchDslSchema>;
+/**
+ * How an Elasticsearch DSL result should be converted into Vega rows.
+ */
+export type DashboardElasticsearchResultMapping = z.infer<typeof DashboardElasticsearchResultMappingSchema>;
+/**
+ * Dashboard data source backed by a Data Platform SQL query.
+ */
+export type DashboardSqlDataSource = z.infer<typeof DashboardSqlDataSourceSchema>;
+/**
+ * Dashboard data source backed by Vertesia Store Elasticsearch DSL.
+ */
+export type DashboardStoreElasticsearchDataSource = z.infer<typeof DashboardStoreElasticsearchDataSourceSchema>;
+/**
+ * Data source for a Vega dashboard.
+ */
+export type DashboardDataSource = z.infer<typeof DashboardDataSourceSchema>;
+/**
+ * Dashboard definition contributed by an app package.
+ *
+ * App dashboard IDs are local to the app. The platform exposes them as
+ * `app:<app_name>:<id>` when listing or retrieving dashboards.
+ */
+export type AppDashboardDefinition = z.infer<typeof AppDashboardDefinitionSchema>;
+/**
+ * Summary view of a dashboard (for listings).
+ */
+export type DashboardItem = z.infer<typeof DashboardItemSchema>;
+/**
+ * Full dashboard with SQL query and Vega-Lite specification.
+ *
+ * **New architecture (v2):**
+ * - `dataSource` field with either SQL or Store Elasticsearch DSL
+ * - Single `spec` field with complete Vega-Lite spec (vconcat/hconcat for multiple panels)
+ * - Cross-panel interactivity via Vega selections
+ * - Legacy top-level `query` fields are treated as a SQL data source
+ *
+ * **Legacy architecture (v1, deprecated):**
+ * - Multiple `queries` with named data sources
+ * - Multiple `panels` with separate specs and dataSources references
+ * - `layout` for grid positioning
+ * - No cross-panel interactivity
+ */
+export type Dashboard = z.infer<typeof DashboardSchema>;
+/**
+ * Payload for creating a new dashboard.
+ * Requires a data source and spec (Vega-Lite).
+ */
+export type CreateDashboardPayload = z.infer<typeof CreateDashboardPayloadSchema>;
+/**
+ * Payload for updating a dashboard.
+ */
+export type UpdateDashboardPayload = z.infer<typeof UpdateDashboardPayloadSchema>;
+/**
+ * Payload for previewing a dashboard (render without saving).
+ */
+export interface PreviewDashboardPayload {
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard */
+    query?: string;
+    /** Maximum rows to return from the query (default: 10000) */
+    queryLimit?: number;
+    /** Default values for SQL parameters */
+    queryParameters?: Record<string, string>;
+    /** Complete Vega-Lite specification for the entire dashboard */
+    spec?: Record<string, unknown>;
+    /** @deprecated Use single `query` field instead */
+    queries?: DashboardQuery[];
+    /** @deprecated Use single `spec` field with vconcat/hconcat instead */
+    panels?: DashboardPanel[];
+    /** @deprecated Layout is now handled within the Vega-Lite spec */
+    layout?: Partial<DashboardLayout>;
+}
+/**
+ * Options for rendering a dashboard.
+ */
+export interface RenderDashboardOptions {
+    /** Scale factor for higher resolution (default: 1) */
+    scale?: number;
+    /** Force re-render even if cached (default: false) */
+    force?: boolean;
+    /** Background color (default: white) */
+    backgroundColor?: string;
+}
+/**
+ * Result of rendering a dashboard.
+ */
+export interface RenderDashboardResult {
+    /** URL to the rendered PNG image */
+    url: string;
+    /** When the URL expires (seconds from now) */
+    expires_in: number;
+    /** When the dashboard was rendered */
+    rendered_at: string;
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+}
+/**
+ * A point-in-time version of a dashboard.
+ * Stores full snapshot inline (no external storage needed for small JSON documents).
+ */
+export type DashboardVersion = z.infer<typeof DashboardVersionSchema>;
+/**
+ * Summary view of a dashboard version (for listings).
+ */
+export type DashboardVersionItem = z.infer<typeof DashboardVersionItemSchema>;
+/**
+ * Payload for creating a named snapshot.
+ */
+export type CreateDashboardSnapshotPayload = z.infer<typeof CreateDashboardSnapshotPayloadSchema>;
+/**
+ * Payload for promoting a version to current.
+ */
+export type PromoteDashboardVersionPayload = z.infer<typeof PromoteDashboardVersionPayloadSchema>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: interaction.d.ts
+// -----------------------------------------------------------------------------
+import type { CompletionResult, ExecutionTokenUsage, JSONObject, JSONSchema, Modalities, ModelOptions, StatelessExecutionOptions, ToolUse } from '@llumiverse/common';
+import type { z } from 'zod';
+import type { AgentResourceActionSchema, AgentResourceReferenceSchema, AgentResourceTypeSchema, AgentRunnerOptionsSchema, AsyncCompletionModeSchema, AsyncCompletionOptionsSchema, AsyncConversationExecutionPayloadSchema, AsyncExecutionPayloadSchema, AsyncExecutionResultSchema, AsyncInteractionExecutionPayloadSchema, CachePolicySchema, CatalogInteractionRefSchema, ConversationStripOptionsSchema, ConversationVisibilitySchema, ExecutionRunInteractionSchema, ExecutionRunRefSchema, ExecutionRunWorkflowSchema, GeneratedInteractionDefinitionSchema, GeneratedInteractionPromptSegmentSchema, GeneratedInteractionPromptTemplateSchema, GeneratedTestDataRecordSchema, GenerateInteractionPayloadSchema, GenerateTestDataPayloadSchema, ImprovePromptPayloadConfigSchema, ImprovePromptPayloadSchema, InCodePromptSchema, InitialToolCallSchema, InteractionCreatePayloadSchema, InteractionEndpointQuerySchema, InteractionEndpointSchema, InteractionExecutionErrorSchema, InteractionExecutionPayloadSchema, InteractionForkPayloadSchema, InteractionNameSchema, InteractionPublishPayloadSchema, InteractionRefSchema, InteractionRefWithSchemaSchema, InteractionSchema, InteractionsExportPayloadSchema, InteractionTagsSchema, InteractionUpdatePayloadSchema, InteractionVisibilitySchema, NamedInteractionExecutionPayloadSchema, PromptImprovementResponseSchema, PromptModalitiesSchema, RateLimitRequestPayloadSchema, RateLimitRequestResponseSchema, ResolvedEnvironmentInfoSchema, ResolvedInteractionExecutionInfoSchema, ResolvedRuntimeConfigSchema, ResultStorageOptionsSchema, RunSourceSchema, SchemaRefSchema, SkillContextTriggersSchema, StreamingOptionsSchema, StreamingTelemetryContextSchema, ToolResultMetaSchema, ToolResultSchema, ToolResultsPayloadSchema, UserMessagePayloadSchema } from './api-schemas/interaction.js';
+import type { InteractionExecutionConfigurationSchema } from './api-schemas/store.js';
+import type { MCPToolAnnotations } from './apps.js';
+import type { ExecutionEnvironmentRef } from './environment.js';
+import type { ProjectRef } from './project.js';
+import type { ExecutablePromptSegmentDef, PopulatedPromptSegmentDef } from './prompt.js';
+import type { TextArtifactReference } from './store/conversation-state.js';
+import type { AccountRef } from './user.js';
+/**
+ * `RunDataStorageLevel` and `ConfigModes` live in `./interaction-values.js` so the API schemas can
+ * read them without importing this module back. Re-exported here so every existing import path keeps
+ * working.
+ */
+export * from './interaction-values.js';
+import { ConfigModes, RunDataStorageLevel } from './interaction-values.js';
+export type InteractionExecutionError = z.infer<typeof InteractionExecutionErrorSchema>;
+/**
+ * Configuration for stripping large data from conversation history
+ * to prevent JSON serialization issues and reduce storage bloat.
+ */
+export type ConversationStripOptions = z.infer<typeof ConversationStripOptionsSchema>;
+/**
+ * Reference to an interaction in the catalog.
+ * Used in catalog listing. The id is composed of the namespace and the interaction name.
+ * Stored interactions can use `oid:` prefix.
+ * If no prefix is used it fallback on `oid:`.
+ */
+export type CatalogInteractionRef = z.infer<typeof CatalogInteractionRefSchema>;
+export interface CatalogTagQuery {
+    tag?: string;
+}
+export interface StoredCatalogInteractionsQuery extends CatalogTagQuery {
+    status?: string;
+    published?: boolean;
+}
+export interface ExecuteInteractionByEndpointQuery {
+    tag?: string;
+}
+export interface ExecuteInteractionByEndpointHeaders {
+    'x-interaction-tag'?: string;
+}
+export interface ResolveInteractionQuery {
+    environment?: string;
+    model?: string;
+    hasImage?: boolean;
+    hasVideo?: boolean;
+}
+export type InCodePrompt = z.infer<typeof InCodePromptSchema>;
+export interface InCodeInteraction {
+    /**
+     * The interaction type.
+     */
+    type: 'sys' | 'app' | 'stored' | 'draft';
+    /**
+     * The id of the interaction. Required.
+     * The id is a unique identifier for the interaction.
+     * It is recommended to use a URL safe string and not include spaces.
+     * The id is composed of some namespace or prefix and the interaction name.
+     * Example: sys:generic_question, app:review_contract, tmp:my_temp_interaction
+     */
+    id: string;
+    /**
+     * The interaction code name. Required.
+     * Should be a URL safe string and not include spaces. It is recommended to use kebab-case or camel-case.
+     * The endpoints must satisfy the following regexp: /^[a-zA-Z0-9-_]+$/. No whitespaces or special characters are allowed.
+     */
+    name: string;
+    /**
+     * Only applies for stored interactions. The version of the interaction.
+     * Undefined for non stored interactions
+     */
+    version?: number;
+    /**
+     * Only applies for stored interactions. Whether the interaction is published or not.
+     */
+    published?: boolean;
+    /**
+     * A title for the interaction. If not provided, the endpoint will be used.
+     */
+    title?: string;
+    /**
+     * An optional description of the interaction.
+     */
+    description?: string;
+    /**
+     * The JSON schema to be used for the result if any.
+     */
+    result_schema?: JSONSchema | SchemaRef;
+    /**
+     * The modality of the interaction output.
+     * If not specified Modalities.Text is assumed.
+     */
+    output_modality?: Modalities;
+    /**
+     * How to store the run data for executions of this interaction.
+     * Defaults to STANDARD.
+     */
+    storage?: RunDataStorageLevel;
+    /**
+     * Optional tags for the interaction.
+     */
+    tags?: string[];
+    /**
+     * Agent Runner configuration options.
+     */
+    agent_runner_options?: AgentRunnerOptions;
+    /**
+     * Default options for the model to be used when executing this interaction.
+     * (like temperature etc)
+     */
+    model_options?: ModelOptions;
+    /**
+     * The prompts composing the interaction. Required.
+     */
+    prompts: InCodePrompt[];
+    /**
+     * Optional reference to an external resource if any.
+     * Used internally by the system to synchronize stored interactions with in-code interactions.
+     */
+    externalId?: string;
+    /**
+     * Runtime configuration (system use only)
+     *
+     * This field is populated by the system when converting stored interactions
+     * and contains runtime-specific defaults like target model/environment IDs.
+     *
+     * DO NOT set this field manually when writing interaction definitions.
+     * These values are environment-specific and not portable.
+     *
+     * @internal
+     */
+    runtime?: {
+        /**
+         * Default target environment for the interaction execution
+         */
+        environment?: string;
+        /**
+         * Default (recommended) target model for the interaction execution
+         */
+        model?: string;
+    };
+}
+export interface InteractionSpec extends Omit<InCodeInteraction, 'id' | 'runtime' | 'type' | 'published' | 'version'> {
+}
+/**
+ * The payload to query the interaction endpoints
+ */
+export type InteractionEndpointQuery = z.infer<typeof InteractionEndpointQuerySchema>;
+/**
+ * A description of an interaction endpoint.
+ */
+export type InteractionEndpoint = z.infer<typeof InteractionEndpointSchema>;
+export type InteractionTags = z.infer<typeof InteractionTagsSchema>;
+export type InteractionRef = z.infer<typeof InteractionRefSchema>;
+/** An interaction reduced to the fields a name picker needs. */
+export type InteractionName = z.infer<typeof InteractionNameSchema>;
+export declare const InteractionNamePopulate = "id name";
+export declare const InteractionRefPopulate = "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts";
+export declare const InteractionRefWithSchemaPopulate = "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts result_schema";
+/**
+ * An interaction reference carrying the schemas an export needs to reconstruct it.
+ *
+ * An alias of the published component rather than the `Omit<InteractionRef, 'prompts'>` interface it
+ * replaces. That `Omit` could not be resolved by the schema generator once `InteractionRef` became a
+ * canonical alias — the alias publishes as a bare reference, with no members to omit — and the
+ * interface also overstated each prompt template, which an export populates with `inputSchema` alone.
+ */
+export type InteractionRefWithSchema = z.infer<typeof InteractionRefWithSchemaSchema>;
+export type InteractionsExportPayload = z.infer<typeof InteractionsExportPayloadSchema>;
+export declare enum InteractionStatus {
+    draft = "draft",
+    published = "published",
+    archived = "archived",
+    code = "code",// for in-code interactions that are not stored in the database
+    unknown = "unknown"
+}
+export declare enum ExecutionRunStatus {
+    created = "created",
+    processing = "processing",
+    completed = "completed",
+    failed = "failed"
+}
+export declare enum RunDataStorageDescription {
+    STANDARD = "Run data is stored for both the model inputs and output.",
+    RESTRICTED = "No run data is stored for the model inputs \u2014 only the model output.",
+    DEBUG = "Run data is stored for the model inputs and output, schema, and final prompt."
+}
+export declare const RunDataStorageOptions: Record<RunDataStorageLevel, RunDataStorageDescription>;
+/**
+ * Schema can be stored or specified as a reference to an external schema.
+ * We only support "store:" references for now
+ */
+export type SchemaRef = z.infer<typeof SchemaRefSchema>;
+export type CachePolicy = z.infer<typeof CachePolicySchema>;
+export type InteractionVisibility = z.infer<typeof InteractionVisibilitySchema>;
+export interface InteractionData {
+    readonly id: string;
+    name: string;
+    endpoint: string;
+    description?: string;
+    project: string | ProjectRef;
+    tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
+    result_schema?: JSONSchema | SchemaRef;
+    environment?: string | ExecutionEnvironmentRef;
+    model?: string;
+    model_options?: ModelOptions;
+    restriction?: RunDataStorageLevel;
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
+    output_modality?: Modalities;
+}
+export type Interaction = z.infer<typeof InteractionSchema>;
+export interface PopulatedInteraction extends Omit<Interaction, 'prompts'> {
+    prompts: PopulatedPromptSegmentDef[];
+}
+/**
+ * Used to describe an interaction that can be executed. Contains only the interaction data useful
+ * to execute the interaction plus the prompt templates
+ */
+export interface ExecutableInteraction extends InteractionData {
+    prompts: ExecutablePromptSegmentDef[];
+}
+export type InteractionCreatePayload = z.infer<typeof InteractionCreatePayloadSchema>;
+export type InteractionUpdatePayload = z.infer<typeof InteractionUpdatePayloadSchema>;
+export type InteractionPublishPayload = z.infer<typeof InteractionPublishPayloadSchema>;
+export interface InteractionDeletePayload {
+    /**
+     * When true, also delete every interaction in the same family as the target:
+     * - If the target is the root draft, its forks and published versions are deleted.
+     * - If the target is a published version (or fork), the parent draft and all siblings are deleted.
+     * Forward-only cascade — never deletes outside the target's family.
+     */
+    cascade?: boolean;
+}
+export type InteractionForkPayload = z.infer<typeof InteractionForkPayloadSchema>;
+export type InteractionExecutionPayload = z.infer<typeof InteractionExecutionPayloadSchema>;
+export type NamedInteractionExecutionPayload = z.infer<typeof NamedInteractionExecutionPayloadSchema>;
+export type ToolRef = string | {
+    name: string;
+    description: string;
+};
+export type ConversationVisibility = z.infer<typeof ConversationVisibilitySchema>;
+/**
+ * Defines the scope for agent search operations.
+ */
+export declare enum AgentSearchScope {
+    /**
+     * Search is scoped to a specific collection.
+     */
+    Collection = "collection"
+}
+/**
+ * Context triggers for auto-injection of skills.
+ * When these conditions match, the skill is automatically injected into the agent context.
+ */
+export type SkillContextTriggers = z.infer<typeof SkillContextTriggersSchema>;
+/**
+ * Configuration options for Agent Runner functionality.
+ * These options control how interactions are exposed and executed in the Agent Runner.
+ */
+export type AgentRunnerOptions = z.infer<typeof AgentRunnerOptionsSchema>;
+export type { EmailChannel, EmailRouteData, InteractiveChannel, UserChannel, } from './email.js';
+export { isEmailChannel, isInteractiveChannel, } from './email.js';
+/**
+ * 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 type InitialToolCall = z.infer<typeof InitialToolCallSchema>;
+export type AsyncConversationExecutionPayload = z.infer<typeof AsyncConversationExecutionPayloadSchema>;
+export type AsyncInteractionExecutionPayload = z.infer<typeof AsyncInteractionExecutionPayloadSchema>;
+/**
+ * @discriminator type
+ */
+export type AsyncExecutionPayload = z.infer<typeof AsyncExecutionPayloadSchema>;
+export type AsyncExecutionResult = z.infer<typeof AsyncExecutionResultSchema>;
+/**
+ * Telemetry context for streaming mode.
+ * Contains info not available in current_state needed to send LlmCallEvent.
+ */
+export type StreamingTelemetryContext = z.infer<typeof StreamingTelemetryContextSchema>;
+/**
+ * Options for storing inference results to cloud storage
+ */
+export type ResultStorageOptions = z.infer<typeof ResultStorageOptionsSchema>;
+export type AsyncCompletionMode = z.infer<typeof AsyncCompletionModeSchema>;
+/**
+ * Streaming-specific options (only needed when stream=true)
+ */
+export type StreamingOptions = z.infer<typeof StreamingOptionsSchema>;
+/**
+ * Options for async completion and/or streaming LLM responses
+ */
+export type AsyncCompletionOptions = z.infer<typeof AsyncCompletionOptionsSchema>;
+/**
+ * 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 = z.infer<typeof AgentResourceTypeSchema>;
+export type AgentResourceAction = z.infer<typeof AgentResourceActionSchema>;
+/**
+ * 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 type AgentResourceReference = z.infer<typeof AgentResourceReferenceSchema>;
+/**
+ * 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 type ToolResultMeta = z.infer<typeof ToolResultMetaSchema>;
+export interface ToolResultContent {
+    content: string;
+    /**
+     * Reference to text content stored outside Temporal/API payloads. Servers that
+     * execute the next model turn should resolve this before constructing the
+     * provider prompt.
+     */
+    content_ref?: TextArtifactReference;
+    is_error: boolean;
+    files?: string[];
+    /**
+     * Optional message to display in the UI instead of the content.
+     * Use this when the content is large or technical (e.g., document text)
+     * and you want to show a friendly message to the user.
+     */
+    display_message?: string;
+    /**
+     * Can contain metadata returned by the tool executor.
+     */
+    meta?: ToolResultMeta;
+}
+/**
+ * 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 declare function normalizeAgentResources(value: unknown): AgentResourceReference[];
+/** Extract the normalized resource references a tool declared in its result metadata. */
+export declare function getResourcesFromToolResult(result: Pick<ToolResultContent, 'meta'>): AgentResourceReference[];
+export type ToolResult = z.infer<typeof ToolResultSchema>;
+/**
+ * The payload to sent the tool responses back to the target LLM
+ */
+export type ToolResultsPayload = z.infer<typeof ToolResultsPayloadSchema>;
+export type UserMessagePayload = z.infer<typeof UserMessagePayloadSchema>;
+export type CheckpointConversationPayload = Omit<ToolResultsPayload, 'results' | 'tools'>;
+export declare enum RunSourceTypes {
+    api = "api",
+    cli = "cli",
+    ui = "ui",
+    webhook = "webhook",
+    test = "test-data",
+    system = "system",
+    schedule = "schedule"
+}
+export type RunSource = z.infer<typeof RunSourceSchema>;
+export type ExecutionRunInteraction = z.infer<typeof ExecutionRunInteractionSchema>;
+export interface BaseExecutionRun<P = unknown> {
+    readonly id: string;
+    /**
+     * Only used by runs that were created by a virtual run to point toward the virtual run parent
+     */
+    parent?: string | ExecutionRun;
+    evaluation?: {
+        score?: number;
+        selected?: boolean;
+        scores?: Record<string, number>;
+    };
+    result: CompletionResult[];
+    /**
+     * The parameters used to create the interaction.
+     * If the parameters contains the special property "@memory" it will be used
+     * to locate a memory pack and the other properties will be used as the memory pack mapping.
+     */
+    parameters: P;
+    tags?: string[];
+    interaction?: string | ExecutionRunInteraction;
+    /** Environment reference - populated with full object in API responses */
+    environment: ExecutionEnvironmentRef;
+    modelId?: string;
+    result_schema?: JSONSchema;
+    ttl: number;
+    status: ExecutionRunStatus;
+    finish_reason?: string;
+    prompt?: unknown;
+    token_use?: ExecutionTokenUsage;
+    chunks?: number;
+    execution_time?: number;
+    /** @format date-time */
+    created_at: string;
+    /** @format date-time */
+    updated_at: string;
+    account: AccountRef;
+    project: ProjectRef;
+    config: InteractionExecutionConfiguration;
+    error?: InteractionExecutionError;
+    source: RunSource;
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
+    output_modality?: Modalities;
+    created_by: string;
+    updated_by: string;
+    /**
+     * The Vertesia Workflow related to this Interaction Run.
+     *
+     * This is only set when the interaction is executed as part of a workflow.
+     *
+     * @since 0.60.0
+     */
+    workflow?: ExecutionRunWorkflow;
+}
+export interface ExecutionRun<P = unknown> extends BaseExecutionRun<P> {
+    interaction?: ExecutionRunInteraction;
+}
+export interface PopulatedExecutionRun<P = unknown> extends BaseExecutionRun<P> {
+    interaction?: ExecutionRunInteraction;
+}
+export type ExecutionRunWorkflow = z.infer<typeof ExecutionRunWorkflowSchema>;
+export type PromptModalities = z.infer<typeof PromptModalitiesSchema>;
+export interface InteractionExecutionResult<P = unknown> extends Omit<ExecutionRun<P>, 'account' | 'project' | 'interaction'> {
+    account: string;
+    project: string;
+    interaction?: string;
+    tool_use?: ToolUse[];
+    conversation?: unknown;
+    options?: StatelessExecutionOptions;
+}
+export interface LegacyInteractionExecutionResult<P = unknown> extends Omit<InteractionExecutionResult<P>, 'result' | 'account' | 'project'> {
+    account: string | AccountRef;
+    project: string | ProjectRef;
+    result?: JSONObject | string | null;
+}
+export type ExecutionRunRef = z.infer<typeof ExecutionRunRefSchema>;
+export declare const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
+export declare enum ConfigModesDescription {
+    RUN_AND_INTERACTION_CONFIG = "This run configuration is used. Undefined options are filled with interaction configuration.",
+    RUN_CONFIG_ONLY = "Only this run configuration is used. Undefined options remain undefined.",
+    INTERACTION_CONFIG_ONLY = "Only interaction configuration is used."
+}
+export declare const ConfigModesOptions: Record<ConfigModes, ConfigModesDescription>;
+export type InteractionExecutionConfiguration = z.infer<typeof InteractionExecutionConfigurationSchema>;
+export type GenerateInteractionPayload = z.infer<typeof GenerateInteractionPayloadSchema>;
+export type GenerateTestDataPayload = z.infer<typeof GenerateTestDataPayloadSchema>;
+export type GeneratedTestDataRecord = z.infer<typeof GeneratedTestDataRecordSchema>;
+export type ImprovePromptPayloadConfig = z.infer<typeof ImprovePromptPayloadConfigSchema>;
+export type ImprovePromptPayload = z.infer<typeof ImprovePromptPayloadSchema>;
+export type GeneratedInteractionPromptTemplate = z.infer<typeof GeneratedInteractionPromptTemplateSchema>;
+export type GeneratedInteractionPromptSegment = z.infer<typeof GeneratedInteractionPromptSegmentSchema>;
+export type GeneratedInteractionDefinition = z.infer<typeof GeneratedInteractionDefinitionSchema>;
+export type PromptImprovementResponse = z.infer<typeof PromptImprovementResponseSchema>;
+export type RateLimitRequestPayload = z.infer<typeof RateLimitRequestPayloadSchema>;
+export type RateLimitRequestResponse = z.infer<typeof RateLimitRequestResponseSchema>;
+/**
+ * Source of the resolved model configuration
+ */
+export declare enum ModelSource {
+    /** Model was explicitly provided in the execution config */
+    config = "config",
+    /** Model comes from the interaction definition */
+    interaction = "interaction",
+    /** Model comes from environment's default_model */
+    environmentDefault = "environmentDefault",
+    /** Model comes from project system interaction defaults */
+    projectSystemDefault = "projectSystemDefault",
+    /** Model comes from project base defaults */
+    projectBaseDefault = "projectBaseDefault",
+    /** Model comes from project modality-specific defaults */
+    projectModalityDefault = "projectModalityDefault",
+    /** Model comes from legacy project defaults */
+    projectLegacyDefault = "projectLegacyDefault"
+}
+/**
+ * Resolved environment information
+ */
+export type ResolvedEnvironmentInfo = z.infer<typeof ResolvedEnvironmentInfoSchema>;
+/**
+ * Resolved runtime configuration for an interaction
+ */
+export type ResolvedRuntimeConfig = z.infer<typeof ResolvedRuntimeConfigSchema>;
+/**
+ * Resolved execution info for an interaction.
+ * Contains the interaction ID, basic metadata, and the resolved runtime configuration
+ * (environment, model) that would be used at execution time.
+ */
+export type ResolvedInteractionExecutionInfo = z.infer<typeof ResolvedInteractionExecutionInfoSchema>;
+/**
+ * A builtin tool definition from the tools catalog
+ */
+export interface BuiltinToolDefinition {
+    /**
+     * The unique tool name
+     */
+    name: string;
+    /**
+     * One-line summary shown in the tool selector UI
+     */
+    summary?: string;
+    /**
+     * JSON schema for the tool's parameters
+     */
+    params: JSONSchema;
+    /**
+     * Whether this tool is active by default when no explicit tool list is provided.
+     * Tools with default: false are only activated by skills.
+     */
+    default: boolean;
+    /**
+     * Behavioral hints following the MCP ToolAnnotations spec.
+     * Used for display purposes only — not sent to LLMs.
+     */
+    annotations?: MCPToolAnnotations;
+}
+/**
+ * A system skill entry in the tools catalog.
+ * System skills are built into the platform and unlock hidden tools.
+ */
+export interface SystemSkillCatalogEntry {
+    /** Skill name without the learn_ prefix, e.g. "document_search" */
+    name: string;
+    /** Tool name used in agent selection, i.e. "learn_document_search" */
+    tool_name: string;
+    /** Human-readable display title */
+    title: string;
+    /** Description of what the skill unlocks */
+    description: string;
+    /** Tool names this skill enables (unlocks) when called */
+    tools: string[];
+    /** Whether this skill is part of the default agent toolkit */
+    default?: boolean;
+}
+/**
+ * Response from the builtin tools catalog endpoint
+ */
+export interface BuiltinToolsCatalogResponse {
+    /**
+     * List of available builtin tools
+     */
+    tools: BuiltinToolDefinition[];
+    /**
+     * When the catalog was generated
+     */
+    generated_at: string;
+    /**
+     * Total number of tools in the catalog
+     */
+    total_tools: number;
+    /**
+     * System skills bundled in the platform, available without app installation
+     */
+    skills?: SystemSkillCatalogEntry[];
+}
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: prompt.d.ts
+// -----------------------------------------------------------------------------
+import type { JSONSchema, PromptRole } from '@llumiverse/common';
+import type { z } from 'zod';
+import type { PromptTemplateCreatePayloadSchema, PromptTemplateRefSchema, PromptTemplateSchema, PromptTemplateUpdatePayloadSchema } from './api-schemas/interaction.js';
+import type { PromptTemplateForkPayloadSchema, PromptTemplateInteractionsResponseSchema, PromptTemplateInteractionUsageSchema, PromptTemplateInteractionVersionSchema, RenderPromptPayloadSchema, RenderPromptResponseSchema } from './api-schemas/prompt.js';
+export interface ChatPromptSchema {
+    role: PromptRole.user | PromptRole.assistant;
+    content: string;
+}
+export declare enum PromptStatus {
+    draft = "draft",
+    published = "published",
+    archived = "archived"
+}
+export declare enum PromptSegmentDefType {
+    chat = "chat",
+    template = "template"
+}
+export interface PromptSegmentDef<T = string | PromptTemplate | PromptTemplateRef> {
+    id?: string;
+    type: PromptSegmentDefType;
+    template?: T;
+    configuration?: unknown;
+}
+export interface PromptSegmentRef<T = string | PromptTemplate | PromptTemplateRef> extends PromptSegmentDef<T> {
+    id: string;
+}
+export interface PopulatedPromptSegmentDef extends Omit<PromptSegmentDef, 'template'> {
+    template?: PromptTemplate;
+}
+/**
+ * Used for prompt rendering at interaction execution
+ */
+export interface ExecutablePromptSegmentDef extends Omit<PromptSegmentDef, 'template'> {
+    template?: ExecutablePromptTemplate;
+}
+export type PromptTemplateRef = z.infer<typeof PromptTemplateRefSchema>;
+export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
+    inputSchema?: JSONSchema;
+}
+export declare enum TemplateType {
+    jst = "jst",
+    handlebars = "handlebars",
+    text = "text"
+}
+export interface ExecutablePromptTemplate {
+    role: PromptRole;
+    content: string;
+    content_type: TemplateType;
+    inputSchema?: JSONSchema;
+}
+export type PromptTemplate = z.infer<typeof PromptTemplateSchema>;
+export type PromptTemplateForkPayload = z.infer<typeof PromptTemplateForkPayloadSchema>;
+export type PromptTemplateCreatePayload = z.infer<typeof PromptTemplateCreatePayloadSchema>;
+export type PromptTemplateUpdatePayload = z.infer<typeof PromptTemplateUpdatePayloadSchema>;
+export type PromptTemplateInteractionVersion = z.infer<typeof PromptTemplateInteractionVersionSchema>;
+export type PromptTemplateInteractionUsage = z.infer<typeof PromptTemplateInteractionUsageSchema>;
+export type PromptTemplateInteractionsResponse = z.infer<typeof PromptTemplateInteractionsResponseSchema>;
+export type RenderPromptPayload = z.infer<typeof RenderPromptPayloadSchema>;
+/**
+ * What `POST /prompts/:id/render` answers with: the segment identity plus the rendered body.
+ *
+ * Stated here for the first time — the endpoint declared its response inline, so there has never
+ * been a name for it on either side of the wire.
+ */
+export type RenderPromptResponse = z.infer<typeof RenderPromptResponseSchema>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: project.d.ts
+// -----------------------------------------------------------------------------
+import type { z } from 'zod';
+import type { ProjectRefSchema } from './api-schemas/apikey.js';
+import type { EmbeddingsStatusResponseSchema, ProjectConfigurationEmbeddingEnablePayloadSchema } from './api-schemas/embeddings.js';
+import type { DriftAnalysisProgressSchema, DriftAnalysisResultSchema, DriftAnalysisStatusResponseSchema, IndexingStatusResponseSchema, ReindexAgentRunsPayloadSchema, ReindexAgentRunsResponseSchema, StartProjectReindexPayloadSchema } from './api-schemas/indexing.js';
+import type { CreateProjectPayloadFromSchema, ListProjectsQuerySchema, ProjectIntegrationListEntrySchema, ProjectIntegrationListResponseSchema, ProjectPluginsUpdatePayloadSchema, ProjectSchema, ProjectTagQuerySchema } from './api-schemas/project.js';
+import type { AgentCheckpointConfigurationSchema, AgentProjectConfigurationSchema, BrowserUseProjectConfigurationSchema, BrowserUseRiskPolicySchema, BrowserUseScreenshotCaptureSchema, ElasticsearchBackendSchema, ModalityDefaultsSchema, ModelDefaultSchema, ProjectConfigurationEmbeddingSchema, ProjectConfigurationSchema, ProjectIndexingConfigurationSchema, ProjectIntakeConfigurationSchema, ProjectIntakeSniffConfigurationSchema, ProjectModelDefaultsSchema, ProjectSearchPropertyMappingSchema, ProjectSearchPropertyTypeSchema, ProjectSearchTierSchema, SystemDefaultsSchema } from './api-schemas/project-configuration.js';
+import type { AccountRef } from './user.js';
+/**
+ * `SystemRoles` lives in `./project-values.js` so the API schemas can read it without importing this
+ * module back. Re-exported here so every existing import path keeps working.
+ */
+export * from './project-values.js';
+export type ICreateProjectPayload = CreateProjectPayloadFromSchema;
+export declare function isRoleIncludedIn(role: string, includingRole: string): boolean;
+export interface PopulatedProjectRef {
+    id: string;
+    name: string;
+    account: AccountRef;
+}
+export type ProjectRef = z.infer<typeof ProjectRefSchema>;
+export type ProjectTagQuery = z.infer<typeof ProjectTagQuerySchema>;
+export type ListProjectsQuery = z.infer<typeof ListProjectsQuerySchema>;
+export type ModelDefault = z.infer<typeof ModelDefaultSchema>;
+export type ModalityDefaults = z.infer<typeof ModalityDefaultsSchema>;
+/**
+ * System interaction category enum.
+ * Categories group one or more system interactions for default model assignment.
+ */
+export declare enum SystemInteractionCategory {
+    content_type = "content_type",
+    intake = "intake",
+    analysis = "analysis",
+    agent = "agent",
+    non_applicable = "non_applicable"
+}
+/**
+ * Map system interaction endpoints to categories.
+ */
+export declare const SYSTEM_INTERACTION_CATEGORIES: Record<string, SystemInteractionCategory>;
+/**
+ * Get category for a system interaction endpoint.
+ * Returns undefined if category is non-applicable or endpoint is not recognized.
+ * Note: Caller is responsible for determining if the interaction is a system interaction.
+ * @param endpoint - The interaction endpoint name
+ */
+export declare function getSystemInteractionCategory(endpoint: string): SystemInteractionCategory | undefined;
+/**
+ * One optional default per {@link SystemInteractionCategory}.
+ *
+ * The schema writes the categories out rather than mapping over the enum, so `project.contract.test`
+ * asserts that its keys are exactly the category union — a new category has to be added in both
+ * places, and fails to compile until it is.
+ */
+export type SystemDefaults = z.infer<typeof SystemDefaultsSchema>;
+export type ProjectModelDefaults = z.infer<typeof ProjectModelDefaultsSchema>;
+export type BrowserUseRiskPolicy = z.infer<typeof BrowserUseRiskPolicySchema>;
+export type BrowserUseScreenshotCapture = z.infer<typeof BrowserUseScreenshotCaptureSchema>;
+/**
+ * Project defaults and caps for `browser_use` agent workstreams.
+ *
+ * A hand-written `JSONSchemaType<BrowserUseProjectConfiguration>` used to sit here beside the
+ * interface. Nothing read it, and its descriptions had already drifted from the TSDoc the published
+ * component was derived from — the schema module is now the only statement of the shape.
+ */
+export type BrowserUseProjectConfiguration = z.infer<typeof BrowserUseProjectConfigurationSchema>;
+export type ProjectSearchTier = z.infer<typeof ProjectSearchTierSchema>;
+export type ElasticsearchBackend = z.infer<typeof ElasticsearchBackendSchema>;
+export type ProjectIntakeSniffConfiguration = z.infer<typeof ProjectIntakeSniffConfigurationSchema>;
+export type ProjectIntakeConfiguration = z.infer<typeof ProjectIntakeConfigurationSchema>;
+export type ProjectConfiguration = z.infer<typeof ProjectConfigurationSchema>;
+export type AgentProjectConfiguration = z.infer<typeof AgentProjectConfigurationSchema>;
+export type AgentCheckpointConfiguration = z.infer<typeof AgentCheckpointConfigurationSchema>;
+export type ProjectSearchPropertyType = z.infer<typeof ProjectSearchPropertyTypeSchema>;
+export type ProjectSearchPropertyMapping = z.infer<typeof ProjectSearchPropertyMappingSchema>;
+export declare const PROJECT_SEARCH_PROPERTY_TYPES: readonly ProjectSearchPropertyType[];
+/**
+ * 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 declare function validateProjectSearchPropertyMappings(value: unknown): string[];
+export type ProjectIndexingConfiguration = z.infer<typeof ProjectIndexingConfigurationSchema>;
+export declare enum SupportedEmbeddingTypes {
+    text = "text",
+    image = "image",
+    properties = "properties"
+}
+export declare enum FullTextType {
+    full_text = "full_text"
+}
+export type SearchTypes = SupportedEmbeddingTypes | FullTextType;
+export declare const SearchTypes: {
+    readonly full_text: FullTextType.full_text;
+    readonly text: SupportedEmbeddingTypes.text;
+    readonly image: SupportedEmbeddingTypes.image;
+    readonly properties: SupportedEmbeddingTypes.properties;
+};
+export type ProjectConfigurationEmbedding = z.infer<typeof ProjectConfigurationEmbeddingSchema>;
+export type ProjectConfigurationEmbeddingEnablePayload = z.infer<typeof ProjectConfigurationEmbeddingEnablePayloadSchema>;
+export type Project = z.infer<typeof ProjectSchema>;
+export interface ProjectCreatePayload {
+    name: string;
+    description?: string;
+}
+export interface ProjectUpdatePayload extends Partial<Project> {
+}
+export type ProjectPluginsUpdatePayload = z.infer<typeof ProjectPluginsUpdatePayloadSchema>;
+export declare const ProjectRefPopulate = "id name account";
+export type EmbeddingsStatusResponse = z.infer<typeof EmbeddingsStatusResponseSchema>;
+/**
+ * Response from indexing status endpoint
+ */
+export type IndexingStatusResponse = z.infer<typeof IndexingStatusResponseSchema>;
+export type StartProjectReindexPayload = z.infer<typeof StartProjectReindexPayloadSchema>;
+/**
+ * Auto-tunes shard sizing based on project doc count.
+ *
+ * Returns:
+ * - shard_size: target docs per shard (workflow path uses this; zeno-bulk
+ *   computes shard count from total/shard_size).
+ * - parallel_shard_count: max in-flight shard activities (workflow path only).
+ * - max_shards: hard cap on shard count for the direct path. Direct path
+ *   passes this as `shards` to zeno-bulk so all shards run as cursors in
+ *   ONE process; without this cap, an under-estimated shard_size (e.g.
+ *   from stale estimatedDocumentCount) can spawn 10+ in-flight cursors
+ *   and exceed Cloud Run memory.
+ *
+ * Explicit overrides should bypass this function and use user-provided values.
+ */
+export declare function autoTuneReindexParams(docCount: number): {
+    shard_size: number;
+    parallel_shard_count: number;
+    max_shards: number;
+};
+export type ReindexAgentRunsPayload = z.infer<typeof ReindexAgentRunsPayloadSchema>;
+export type ReindexAgentRunsResponse = z.infer<typeof ReindexAgentRunsResponseSchema>;
+/**
+ * Indexed (`_source`) shape of the content type ref. Unlike the public
+ * ContentObjectTypeRef discriminated union, the index stores BOTH kinds under
+ * `id` — the ObjectId hex for stored types, the namespaced code for in-code
+ * types — so search filters and facets work on a single keyword field
+ * regardless of the kind. `ref_type` is kept to rebuild the public union on
+ * read. `code` only exists on documents written before the field was unified.
+ */
+export interface IndexedContentTypeRef {
+    ref_type: 'stored' | 'incode';
+    id: string;
+    code?: string;
+    name: string;
+}
+/**
+ * Document data structure for Elasticsearch indexing
+ */
+export interface ElasticsearchDocumentData {
+    name?: string;
+    text?: string;
+    properties?: Record<string, unknown>;
+    status?: string;
+    type?: IndexedContentTypeRef;
+    security?: {
+        'content:read'?: string[];
+        'content:write'?: string[];
+        'content:delete'?: string[];
+    };
+    revision?: {
+        head?: boolean;
+        root?: string;
+    };
+    embeddings_text?: number[];
+    embeddings_image?: number[];
+    embeddings_properties?: number[];
+    created_at?: Date | string;
+    updated_at?: Date | string;
+}
+/**
+ * Result from bulk indexing
+ */
+export interface BulkIndexResult {
+    successful: number;
+    failed: number;
+}
+/**
+ * Result from creating a reindex target
+ */
+export interface CreateReindexTargetResult {
+    created: boolean;
+    index_name: string;
+    alias_name: string;
+    version: number;
+    backend?: ElasticsearchBackend;
+    dimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    language?: string;
+}
+/**
+ * Result from fetching a batch
+ */
+export interface FetchBatchResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    next_cursor: string | null;
+    done: boolean;
+}
+/**
+ * Result from discovering the next cursor boundary for batch partitioning
+ */
+export interface NextIndexCursorResult {
+    next_cursors: string[];
+    count: number;
+    done: boolean;
+}
+/**
+ * Result from triggering a reindex
+ */
+export interface TriggerReindexResult {
+    status: string;
+    workflow?: string;
+    workflow_id?: string;
+    run_id?: string;
+    object_count?: number;
+    reason?: string;
+    enabled?: boolean;
+}
+export interface ComputeShardsRequest {
+    tenant_id: string;
+    shard_size?: number;
+    updated_since?: string;
+    backend?: ElasticsearchBackend;
+}
+export interface ComputeShardsResult {
+    shards: Array<{
+        min?: string;
+        max?: string;
+    }>;
+    count: number;
+}
+export interface IndexShardParams {
+    tenant_id: string;
+    target_index: string;
+    shard_min: string;
+    shard_max?: string;
+    backend?: ElasticsearchBackend;
+    embedding_dimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    dry_run?: boolean;
+    concurrency?: number;
+    batch_size?: number;
+    bulk_size_bytes?: number;
+    bulk_concurrency?: number;
+    updated_since?: string;
+}
+export interface IndexShardRequest {
+    force?: boolean;
+    params: IndexShardParams;
+}
+export interface IndexShardResult {
+    status: string;
+    projects_done: number;
+    projects_total: number;
+    scanned: number;
+    written: number;
+    skipped: number;
+    errors: number;
+    /** Per-document ES bulk-item errors (e.g. mapping timeouts). Doc-level data-quality, not pipeline failure. */
+    bulk_errors?: number;
+    /** Sampled details of bulk-item failures (capped at 100 per shard). */
+    bulk_error_sample?: Array<{
+        tenant?: string;
+        doc_id: string;
+        type: string;
+        reason: string;
+    }>;
+    embeddings_written?: number;
+    skipped_embeddings?: number;
+    embeddings_text_written?: number;
+    embeddings_image_written?: number;
+    embeddings_properties_written?: number;
+    embeddings_text_skipped?: number;
+    embeddings_image_skipped?: number;
+    embeddings_properties_skipped?: number;
+    properties_values_trimmed?: number;
+    properties_bytes_dropped?: number;
+    batches_flushed?: number;
+    bulk_chunks_written?: number;
+    avg_docs_per_batch?: number;
+    avg_chunks_per_batch?: number;
+    avg_bytes_per_doc?: number;
+    avg_bytes_per_chunk?: number;
+    read_docs_s: string;
+    write_docs_s: string;
+    read_mb: string;
+    write_mb: string;
+    mongo_read_mb?: string;
+    gcs_read_mb?: string;
+    es_bulk_mb?: string;
+    read_mb_s: string;
+    write_mb_s: string;
+    mongo_read_mb_s?: string;
+    gcs_read_mb_s?: string;
+    es_bulk_mb_s?: string;
+    duration_sec: number;
+    failed_projects?: Array<{
+        tenant: string;
+        error: string;
+    }>;
+}
+export interface SwapAliasRequest {
+    tenant_id: string;
+    target_index: string;
+    backend?: ElasticsearchBackend;
+    /** ES alias name. If not provided, the Go service derives it from the tenant ID. */
+    alias?: string;
+}
+export interface SwapAliasResult {
+    status: string;
+    alias: string;
+    old_index: string;
+    new_index: string;
+}
+export interface ReindexViaBulkRequest {
+    tenant_id: string;
+    project_id?: string;
+    backend?: ElasticsearchBackend;
+    dry_run?: boolean;
+    /** Approximate documents per shard; drives auto-shard count (total / shard_size). Default 250_000. */
+    shard_size?: number;
+    /** Explicit shard count. When set, overrides shard_size-based auto-sharding. Useful to cap in-process concurrency for the direct path. */
+    shards?: number;
+    /** Number of ES bulk-write workers per shard. Default 10. */
+    bulk_concurrency?: number;
+    /** Hard cap per ES bulk request body in bytes. Default 12 MB. */
+    bulk_size_bytes?: number;
+    /** Max documents per batcher flush (size cap still regulates ES bulk requests). Default 200. */
+    bulk_max_docs?: number;
+}
+export interface ReindexViaBulkResult {
+    status: string;
+    error?: string;
+    projects_done: number;
+    projects_total: number;
+    scanned: number;
+    written: number;
+    errors: number;
+    embeddings_written?: number;
+    skipped_embeddings?: number;
+    embeddings_text_written?: number;
+    embeddings_image_written?: number;
+    embeddings_properties_written?: number;
+    embeddings_text_skipped?: number;
+    embeddings_image_skipped?: number;
+    embeddings_properties_skipped?: number;
+    properties_values_trimmed?: number;
+    properties_bytes_dropped?: number;
+    batches_flushed?: number;
+    bulk_chunks_written?: number;
+    avg_docs_per_batch?: number;
+    avg_chunks_per_batch?: number;
+    avg_bytes_per_doc?: number;
+    avg_bytes_per_chunk?: number;
+    read_docs_s: string;
+    write_docs_s: string;
+    read_mb: string;
+    write_mb: string;
+    mongo_read_mb?: string;
+    gcs_read_mb?: string;
+    es_bulk_mb?: string;
+    read_mb_s?: string;
+    write_mb_s?: string;
+    mongo_read_mb_s?: string;
+    gcs_read_mb_s?: string;
+    es_bulk_mb_s?: string;
+    duration_sec: number;
+}
+/**
+ * Elasticsearch index statistics
+ */
+export interface ElasticsearchIndexStats {
+    enabled: boolean;
+    backend?: ElasticsearchBackend;
+    exists?: boolean;
+    document_count?: number;
+    size_in_bytes?: number;
+    index_name?: string;
+    alias_name?: string;
+}
+/**
+ * Embedding configuration for a single type
+ */
+export interface EmbeddingTypeConfig {
+    environment?: string;
+    dimensions?: number;
+    model?: string;
+    provider?: string;
+    enabled?: boolean;
+}
+/**
+ * Detailed index configuration
+ */
+export interface IndexConfiguration {
+    enabled: boolean;
+    exists?: boolean;
+    index_name?: string;
+    alias_name?: string;
+    version?: number;
+    document_count?: number;
+    size_in_bytes?: number;
+    embedding_dimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    /** 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;
+        image?: EmbeddingTypeConfig;
+        properties?: EmbeddingTypeConfig;
+    };
+    created_at?: Date | null;
+}
+/**
+ * Supported languages for full-text search with their display names.
+ * Maps ISO 639-1 codes to human-readable language names.
+ */
+export declare const SUPPORTED_SEARCH_LANGUAGES: Record<string, string>;
+/**
+ * Result from fetching documents by IDs
+ */
+export interface FetchDocumentsByIdsResult {
+    documents: Array<{
+        id: string;
+        document: ElasticsearchDocumentData;
+    }>;
+    not_found: string[];
+}
+/**
+ * Result from bulk delete
+ */
+export interface BulkDeleteResult {
+    successful: number;
+    failed: number;
+}
+/**
+ * Result from ensure index operation
+ */
+export interface EnsureIndexResult {
+    created: boolean;
+    recreated?: boolean;
+    existed?: boolean;
+    enabled?: boolean;
+    status?: string;
+    dimensions?: {
+        text?: number;
+        image?: number;
+        properties?: number;
+    };
+    language?: string;
+}
+export interface AnalyzeDriftBatchResult {
+    processed: number;
+    missing: number;
+    stale: number;
+    next_cursor: string | null;
+    done: boolean;
+    sample_missing_ids: string[];
+    sample_stale_ids: string[];
+}
+export type DriftAnalysisProgress = z.infer<typeof DriftAnalysisProgressSchema>;
+export type DriftAnalysisResult = z.infer<typeof DriftAnalysisResultSchema>;
+export type DriftAnalysisStatusResponse = z.infer<typeof DriftAnalysisStatusResponseSchema>;
+export type ProjectIntegrationListEntry = z.infer<typeof ProjectIntegrationListEntrySchema>;
+export type ProjectIntegrationListResponse = z.infer<typeof ProjectIntegrationListResponseSchema>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: runs.d.ts
+// -----------------------------------------------------------------------------
+import type { z } from 'zod';
+import type { ExecutionRunDocRefSchema, RunClonePayloadSchema, RunCreatePayloadSchema, RunSearchMetaResponseSchema } from './api-schemas/interaction.js';
+/**
+ * The run ref is used to identify a run document in the storage
+ */
+export type ExecutionRunDocRef = z.infer<typeof ExecutionRunDocRefSchema>;
+/**
+ * Interaction execution payload for creating a new run
+ * It uses interaction field (from NamedInteractionExecutionPayload) to pass the interaction ID to run
+ */
+export type RunCreatePayload = z.infer<typeof RunCreatePayloadSchema>;
+/**
+ * Payload for cloning an existing ExecutionRun.
+ * Creates a new run document with the same interaction/config but fresh status.
+ * Used by fork flows to create a new ExecutionRun for the forked workflow.
+ */
+export type RunClonePayload = z.infer<typeof RunClonePayloadSchema>;
+/**
+ * To be used as a value for a numeric or date filters
+ */
+export interface RangeValue {
+    gt?: number | string;
+    gte?: number | string;
+    lt?: number | string;
+    lte?: number | string;
+}
+export type RunSearchMetaResponse = z.infer<typeof RunSearchMetaResponseSchema>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: skill.d.ts
+// -----------------------------------------------------------------------------
+/**
+ * Skill types for interaction-based skills.
+ *
+ * Skills are interactions with `agent_runner_options.is_skill = true`.
+ * They provide contextual instructions to agents without executing code.
+ * When a skill is called, its rendered prompt is returned as instructions.
+ *
+ * Skills can have associated scripts stored at:
+ *   skills/{skill_name}/*.py, *.js, etc.
+ * These are automatically synced to the sandbox when the skill is used.
+ */
+/**
+ * Context provided when searching for relevant skills
+ */
+export interface SkillContext {
+    /**
+     * The task description or user prompt
+     */
+    task_description?: string;
+    /**
+     * Tools currently being used or available
+     */
+    tool_names?: string[];
+    /**
+     * Sample of input data for pattern matching
+     */
+    data_sample?: string;
+    /**
+     * Additional keywords to consider
+     */
+    keywords?: string[];
+}
+/**
+ * Payload for finding relevant skills
+ */
+export interface FindRelevantSkillsPayload {
+    context: SkillContext;
+    limit?: number;
+}
+/**
+ * Result from skill injection into agent context.
+ * Contains the rendered prompt/instructions from a skill interaction.
+ */
+export interface InjectedSkill {
+    /**
+     * The skill/interaction name
+     */
+    name: string;
+    /**
+     * The skill's rendered instructions (from the interaction prompt)
+     */
+    instructions: string;
+    /**
+     * Tools related to this skill
+     */
+    tools?: string[];
+    /**
+     * UI module for rendering results
+     */
+    ui_module?: string;
+    /**
+     * Match score (0-1) indicating relevance
+     */
+    match_score?: number;
+}
+/**
+ * Result from generateTools activity with skills
+ */
+export interface ToolsWithSkills {
+    /**
+     * Array of tool definitions
+     */
+    tools: unknown[];
+    /**
+     * Skills injected based on context
+     */
+    injected_skills: InjectedSkill[];
+}
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: store/store.d.ts
+// -----------------------------------------------------------------------------
+import type { z } from 'zod';
+import type { ContentObjectTypeRefSchema } from '../api-schemas/app-lifecycle.js';
+import type { ComplexSearchPayloadSchema, ContentObjectApiResponseSchema, ContentObjectApiRevisionSchema, ContentObjectApiTypeRefSchema, ContentObjectExportArtifactFileSchema, ContentObjectExportArtifactSchema, ContentObjectExportProgressSchema, ContentObjectExportResultSchema, ContentObjectExportStatusResponseSchema, ContentObjectItemApiResponseSchema, ContentObjectTextResponseSchema, ContentObjectUserPermissionsSchema, ContentSourceSchema, CreateContentObjectHeadersSchema, CreateContentObjectPayloadSchema, CreateContentObjectQuerySchema, DeleteContentObjectExportResponseSchema, DeleteContentObjectResultSchema, EmbeddingSchema, ExportContentObjectsFilterSchema, ExportContentObjectsIncludeOptionsSchema, GenerationRunMetadataSchema, GetObjectRenditionQuerySchema, GetRenditionResponseSchema, InheritedPropertyMetadataSchema, ListContentObjectExportsResponseSchema, ObjectSearchResponseSchema, RevisionInfoSchema, SetObjectEmbeddingsResponseSchema, StartContentObjectExportRequestSchema, StartContentObjectExportResponseSchema, TranscriptSchema, TranscriptSegmentSchema, UpdateContentObjectHeadersSchema, UpdateContentObjectQuerySchema } from '../api-schemas/content.js';
+import type { MarkdownRenditionFormatSchema } from '../api-schemas/document-processing.js';
+import type { CreateWorkflowRulePayloadSchema, WorkflowRuleItemSchema, WorkflowRuleSchema } from '../api-schemas/events.js';
+import type { BucketReadAccessStatusResponseSchema, BulkUploadUrlsPayloadSchema, BulkUploadUrlsResponseSchema, CopyFilePayloadSchema, CopyFileResponseSchema, DeleteFileResultSchema, EnsureBucketReadAccessPayloadSchema, EnsureBucketReadAccessResponseSchema, FileBucketResponseSchema, FileDeleteQuerySchema, FileListQuerySchema, FileListResponseSchema, FileMetadataQuerySchema, FileMetadataResponseSchema, FileMetadataUpdateResultSchema, GetFileUrlPayloadSchema, GetFileUrlResponseSchema, GetUploadUrlPayloadSchema, SetFileMetadataPayloadSchema } from '../api-schemas/files.js';
+import type { ColumnLayoutSchema, ContentObjectTypeCatalogEntrySchema, ContentObjectTypeCatalogQuerySchema, ContentObjectTypeItemSchema, ContentObjectTypeListQuerySchema, ContentObjectTypeSchema, ContentObjectTypeStatusSchema, ContentTypeEditingPolicySchema, ContentTypeExtractionGroundingPolicySchema, ContentTypeExtractionGroundingReviewPolicySchema, ContentTypeIntakePolicySchema, CreateContentObjectTypePayloadSchema, InCodeTypeDefinitionSchema, IntakePageRangesSchema, IntakePageScopeSchema, IntakeVisionDetailSchema, UpdateContentObjectTypePayloadSchema } from '../api-schemas/store.js';
+import type { JSONObject } from '../json.js';
+import type { SupportedEmbeddingTypes } from '../project.js';
+import type { BaseObject } from './common.js';
+export declare enum ContentObjectApiHeaders {
+    COLLECTION_ID = "x-collection-id",
+    PROCESSING_PRIORITY = "x-processing-priority",
+    CREATE_REVISION = "x-create-revision",
+    REVISION_LABEL = "x-revision-label",
+    /**
+     * @deprecated Events are now always emitted. This suppresses the Temporal-backed delivery targets (workflow, agent, and process) — webhook deliveries still fire.
+     */
+    SUPPRESS_WORKFLOWS = "x-suppress-workflows"
+}
+export type CreateContentObjectQuery = z.infer<typeof CreateContentObjectQuerySchema>;
+export type CreateContentObjectHeaders = z.infer<typeof CreateContentObjectHeadersSchema>;
+export type UpdateContentObjectQuery = z.infer<typeof UpdateContentObjectQuerySchema>;
+export type UpdateContentObjectHeaders = z.infer<typeof UpdateContentObjectHeadersSchema>;
+export type GetObjectRenditionQuery = z.infer<typeof GetObjectRenditionQuerySchema>;
+/**
+ * Headers for Data Store API calls.
+ * Used for Cloud Run session affinity to route requests to the same instance.
+ */
+export declare enum DataStoreApiHeaders {
+    /** Data store ID for session affinity - routes requests for same store to same instance */
+    DATA_STORE_ID = "x-data-store-id"
+}
+export declare enum ContentObjectStatus {
+    created = "created",
+    processing = "processing",// the was created and still processing
+    ready = "ready",// the object is rendered and ready to be used
+    completed = "completed",
+    failed = "failed",
+    archived = "archived"
+}
+export type Embedding = z.infer<typeof EmbeddingSchema>;
+export type ExportContentObjectsIncludeOptions = z.infer<typeof ExportContentObjectsIncludeOptionsSchema>;
+export type ExportContentObjectsFilter = z.infer<typeof ExportContentObjectsFilterSchema>;
+/**
+ * Exported object identity and context for a single content object row.
+ */
+export interface ExportedContentObjectRecord {
+    id: string;
+    name: string;
+    location: string;
+    external_id?: string;
+    type?: {
+        ref_type?: 'stored' | 'incode' | 'untyped';
+        id?: string;
+        code?: string;
+        name?: string;
+    };
+    status?: ContentObjectStatus;
+    content?: {
+        source?: string;
+        type?: string;
+        name?: string;
+        etag?: string;
+    };
+    created_at: string;
+    updated_at: string;
+    revision?: RevisionInfo;
+    properties?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    embeddings?: Partial<Record<SupportedEmbeddingTypes, Embedding>>;
+}
+export type StartContentObjectExportRequest = z.infer<typeof StartContentObjectExportRequestSchema>;
+export type StartContentObjectExportResponse = z.infer<typeof StartContentObjectExportResponseSchema>;
+export interface ZenoBulkContentObjectExportRequest extends Omit<StartContentObjectExportRequest, 'compression'> {
+    tenant_id: string;
+    project_id: string;
+    export_id: string;
+    output_path: string;
+    filename: string;
+    manifest_path: string;
+    manifest_filename: string;
+    compression: boolean;
+}
+export interface ZenoBulkContentObjectExportShardRange {
+    min_id?: string;
+    max_id?: string;
+}
+export interface ZenoBulkContentObjectExportPlanRequest extends ZenoBulkContentObjectExportRequest {
+    target_shard_records?: number;
+    max_shards?: number;
+}
+export interface ZenoBulkContentObjectExportPlanResponse {
+    shards: ZenoBulkContentObjectExportShardRange[];
+}
+export interface ZenoBulkContentObjectExportShardRequest extends ZenoBulkContentObjectExportRequest {
+    shard_index: number;
+    shard_count: number;
+    shard: ZenoBulkContentObjectExportShardRange;
+}
+export interface ZenoBulkContentObjectExportSplitShardRequest extends ZenoBulkContentObjectExportRequest {
+    shard: ZenoBulkContentObjectExportShardRange;
+    min_split_records?: number;
+}
+export interface ZenoBulkContentObjectExportSplitShardResponse {
+    shards: ZenoBulkContentObjectExportShardRange[];
+    splittable: boolean;
+    records: number;
+}
+export interface ZenoBulkContentObjectExportShardResult {
+    status: 'completed';
+    shard_index: number;
+    shard_count: number;
+    path: string;
+    filename: string;
+    content_type: string;
+    records: number;
+    bytes: number;
+    started_at: string;
+    completed_at: string;
+    duration_ms: number;
+}
+export interface ZenoBulkContentObjectExportComposeRequest extends ZenoBulkContentObjectExportRequest {
+    parts: string[];
+    records?: number;
+    /**
+     * Export workflow start timestamp. Used to report end-to-end duration after final compose.
+     */
+    started_at?: string;
+}
+export type ContentObjectExportResult = z.infer<typeof ContentObjectExportResultSchema>;
+export type ContentObjectExportProgress = z.infer<typeof ContentObjectExportProgressSchema>;
+export type ContentObjectExportStatusResponse = z.infer<typeof ContentObjectExportStatusResponseSchema>;
+export type ContentObjectExportArtifact = z.infer<typeof ContentObjectExportArtifactSchema>;
+export type ContentObjectExportArtifactFile = z.infer<typeof ContentObjectExportArtifactFileSchema>;
+export type ListContentObjectExportsResponse = z.infer<typeof ListContentObjectExportsResponseSchema>;
+export type DeleteContentObjectExportResponse = z.infer<typeof DeleteContentObjectExportResponseSchema>;
+export type InheritedPropertyMetadata = z.infer<typeof InheritedPropertyMetadataSchema>;
+export type ContentObjectUserPermissions = z.infer<typeof ContentObjectUserPermissionsSchema>;
+export type ContentObjectTextResponse = z.infer<typeof ContentObjectTextResponseSchema>;
+export type DeleteContentObjectResult = z.infer<typeof DeleteContentObjectResultSchema>;
+export type SetObjectEmbeddingsResponse = z.infer<typeof SetObjectEmbeddingsResponseSchema>;
+export type ContentObjectApiTypeRef = z.infer<typeof ContentObjectApiTypeRefSchema>;
+export type ContentObjectApiRevision = z.infer<typeof ContentObjectApiRevisionSchema>;
+export type ContentObjectItemApiResponse = z.infer<typeof ContentObjectItemApiResponseSchema>;
+export type ContentObjectApiResponse = z.infer<typeof ContentObjectApiResponseSchema>;
+export interface ContentObject<T = JSONObject> extends ContentObjectItem<T> {
+    text?: string;
+    text_etag?: string;
+    embeddings: Partial<Record<SupportedEmbeddingTypes, Embedding>>;
+    parts?: string[];
+    parts_etag?: string;
+    transcript?: Transcript;
+    security?: Record<string, string[]>;
+    /** BLP sensitivity level — set directly or inherited from collections (max across collections). */
+    sensitivity?: number;
+    /** Compartments — set directly or inherited from collections (union across collections). */
+    compartments?: string[];
+    /**
+     * Inherited properties metadata - tracks which properties were inherited from parent collections.
+     * Used to display readonly inherited properties in the UI and enable incremental sync optimization.
+     */
+    inherited_properties?: InheritedPropertyMetadata[];
+}
+export declare enum ContentNature {
+    Video = "video",
+    Image = "image",
+    Audio = "audio",
+    Document = "document",
+    Code = "code",
+    Other = "other"
+}
+export interface Dimensions {
+    width: number;
+    height: number;
+}
+export interface Location {
+    latitude: number;
+    longitude: number;
+}
+export type GenerationRunMetadata = z.infer<typeof GenerationRunMetadataSchema>;
+export interface Rendition {
+    name: string;
+    content: ContentSource;
+}
+export interface RenditionWithDimensions extends Rendition {
+    dimensions: Dimensions;
+}
+export declare const POSTER_RENDITION_NAME = "Poster";
+export declare const AUDIO_RENDITION_NAME = "Audio";
+export declare const WEB_VIDEO_RENDITION_NAME = "Web";
+export declare const PDF_RENDITION_NAME = "PDF";
+export interface ContentMetadata {
+    type?: ContentNature;
+    size?: number;
+    languages?: string[];
+    location?: Location;
+    generation_runs?: GenerationRunMetadata[];
+    etag?: string;
+    /** ETag of text materialized from object properties by intake rendering. */
+    rendered_text_etag?: string;
+    renditions?: Rendition[];
+    /**
+     * Embedded/technical metadata harvested from the source file by intake
+     * (office docProps, PDF docinfo). Free-form, nature-appropriate keys.
+     */
+    embedded?: Record<string, unknown>;
+    /** Type-detection provenance recorded by the intake sniff pipeline. */
+    type_detection?: TypeDetectionMetadata;
+    /** Locate-pass provenance: which pages the document map found relevant. */
+    locate?: LocateMetadata;
+    /** Vision-evidence provenance for the last visual extraction run. */
+    vision_evidence?: VisionEvidenceMetadata;
+}
+/**
+ * Provenance persisted at `metadata.locate` when the intake locate (document-map) pass runs.
+ * The page list doubles as navigation metadata for the UI.
+ */
+export interface LocateMetadata {
+    /** Relevant pages proposed by the locate pass, in plan-ranked order (1-based). */
+    pages: number[];
+    /** Detail profile the plan requested for visual extraction. */
+    visual_detail?: 'low' | 'standard' | 'high';
+    /** Whether the plan asked for color rendering. */
+    needs_color?: boolean;
+    /** The model's one-line explanation of the selection. */
+    reason?: string;
+    page_count?: number;
+    /** Pages per contact sheet used for the pass (8 or 16). */
+    detail?: number;
+    sheet_count?: number;
+    located_at: string;
+}
+/**
+ * Provenance persisted at `metadata.vision_evidence` whenever intake prepares scoped page
+ * images for visual extraction (design: vision evidence spec — dropped pages are recorded,
+ * never silently batched).
+ */
+export interface VisionEvidenceMetadata {
+    /** Extraction source that requested the evidence. */
+    source_requested?: 'auto' | 'text' | 'vision' | 'mixed';
+    /** Pages rendered and sent as evidence, in ranked order (1-based). */
+    pages_sent: number[];
+    /** Resolved detail profile name. */
+    detail: 'low' | 'standard' | 'high';
+    /** Candidate pages dropped by budget clamping (recorded, not batched). */
+    dropped_pages?: number[];
+    /** The locate plan's reason, when the plan drove the page selection. */
+    plan_reason?: string;
+    /** Which clamps fired (page_count, allowed_details, token budget, page caps, payload). */
+    clamps_applied?: string[];
+    /** Estimated image tokens for the pages sent. */
+    est_tokens?: number;
+    page_count?: number;
+    prepared_at: string;
+}
+/**
+ * Durable provenance persisted at `metadata.type_detection` whenever the intake sniff pipeline
+ * runs. `method` records which mechanism decides the type: the sniff itself (high confidence),
+ * the post-conversion selector (medium/low/other), or the post-conversion selector because the
+ * document was below the small-doc page threshold.
+ */
+export interface TypeDetectionMetadata {
+    method: 'sniff' | 'post_conversion' | 'post_conversion_small_doc';
+    /** Sniffed type id, or 'other'. */
+    type?: string;
+    type_name?: string;
+    /** Sniff confidence, 0..1. */
+    confidence?: number;
+    band?: 'high' | 'medium' | 'low';
+    rationale?: string;
+    alternates?: string[];
+    /** Which evidence kinds the sniff saw. */
+    evidence?: 'text' | 'image' | 'both';
+    page_count?: number;
+    /** Why the sniff LLM call was skipped (e.g. 'below_min_pages'). */
+    skipped_reason?: string;
+    min_pages?: number;
+    detected_at: string;
+}
+export interface TemporalMediaMetadata extends ContentMetadata {
+    duration?: number;
+    transcript?: Transcript;
+}
+export interface ImageMetadata extends ContentMetadata {
+    type: ContentNature.Image;
+    dimensions?: Dimensions;
+    renditions?: RenditionWithDimensions[];
+}
+export interface AudioMetadata extends TemporalMediaMetadata {
+    type: ContentNature.Audio;
+}
+export interface VideoMetadata extends TemporalMediaMetadata {
+    type: ContentNature.Video;
+    dimensions?: Dimensions;
+    renditions?: RenditionWithDimensions[];
+    hasAudio?: boolean;
+}
+export interface TextSection {
+    description: string;
+    first_line_index: number;
+    last_line_index: number;
+}
+export interface DocumentMetadata extends ContentMetadata {
+    type: ContentNature.Document;
+    page_count?: number;
+    content_processor?: {
+        type?: string;
+        features_requested?: string[];
+        zones_requested?: string[];
+        table_count?: number;
+        image_count?: number;
+        zone_count?: number;
+        needs_ocr_count?: number;
+        /** Fingerprint of source+policy used for custom conversion, to skip re-converting unchanged docs. */
+        conversion_fingerprint?: string;
+    };
+    /**
+     * Grounded-extraction trust signal + key data. Written by the grounded pipeline
+     * (verdict, confidence, citation counts, review status, source etag, ...) and
+     * queryable for list/filter. Open-ended so more grounded key-data can be stored
+     * without a type change.
+     */
+    grounded?: GroundedMetadata;
+    sections?: TextSection[];
+}
+/** Grounded-extraction summary stored on document metadata. Additional keys allowed. */
+export interface GroundedMetadata {
+    verdict?: string;
+    confidence?: number;
+    citation_count?: number;
+    verified_citations?: number;
+    reviewed_at?: string;
+    generated_at?: string;
+    /** Source PDF content etag used by the grounded extraction. */
+    source_content_etag?: string | null;
+    /** @deprecated Grounded source identity is tracked by source_content_etag. */
+    source_text_etag?: string | null;
+    [key: string]: unknown;
+}
+export type Transcript = z.infer<typeof TranscriptSchema>;
+export declare const TextExtractionStatus: {
+    readonly success: "success";
+};
+export interface TranscriptMediaResult {
+    hasText: boolean;
+    status: typeof TextExtractionStatus.success;
+    message?: string;
+    gladiaTranscriptionId?: string;
+}
+export type TranscriptSegment = z.infer<typeof TranscriptSegmentSchema>;
+export type ContentSource = z.infer<typeof ContentSourceSchema>;
+export type RevisionInfo = z.infer<typeof RevisionInfoSchema>;
+/**
+ * The content object item is a simplified version of the ContentObject that is returned by the store API when listing objects.
+ */
+export interface ContentObjectItem<T = JSONObject> extends BaseObject {
+    parent?: string;
+    /** An optional path based location for the object */
+    location: string;
+    /**
+     * Object status.
+     * - created: the object was created and is being processed
+     * - processing: the object is being processed
+     * - completed: the object was processed and is ready to use
+     * - failed: the object processing failed
+     * - archived: the object was archived and is no longer available
+     */
+    status: ContentObjectStatus;
+    /**
+     * Object type id.
+     */
+    type?: ContentObjectTypeRef;
+    /**
+     * Content source information, typically a link to an object store
+     */
+    content?: ContentSource;
+    /**
+     * External identifier for integration with other systems
+     */
+    external_id?: string;
+    /** The object properties. This is a JSON object that describes the object, matching the object type schema */
+    properties: T;
+    /** Technical metadata of the object */
+    metadata?: VideoMetadata | AudioMetadata | ImageMetadata | DocumentMetadata | ContentMetadata | Record<string, unknown>;
+    /** Token information  */
+    tokens?: {
+        count?: number;
+        encoding?: string;
+        etag?: string;
+    };
+    /**
+     * Revision information. This is used to track the history of the object.
+     */
+    revision: RevisionInfo;
+    /**
+     * Soft delete flag. When true, the object should be considered deleted
+     * but is still retained in the database for historical purposes.
+     */
+    is_deleted?: boolean;
+    /**
+     * Soft lock flag. When true, the object should be considered read-only
+     * and modification attempts should be rejected.
+     */
+    is_locked?: boolean;
+    /**
+     * The document score, used for ranking and sorting.
+     */
+    score?: number;
+    /**
+     * Computed per-request: the current user's effective permissions on this object.
+     */
+    user_permissions?: ContentObjectUserPermissions;
+}
+type CreateContentObjectPayloadWire = z.infer<typeof CreateContentObjectPayloadSchema>;
+export type CreateContentObjectPayload<T = JSONObject> = Omit<CreateContentObjectPayloadWire, 'properties' | 'metadata'> & {
+    properties?: T;
+    /** Known metadata interfaces remain assignable; the runtime contract deliberately accepts any object keys. */
+    metadata?: ContentObjectItem['metadata'];
+};
+type LegacyContentObjectTypeRef = Partial<ContentObjectTypeRef> & {
+    ref_type?: 'stored' | 'incode';
+    id?: string;
+    code?: string;
+    name?: string;
+};
+export declare function getContentTypeRefId(type: ContentObjectTypeRef): string;
+export declare function withContentObjectTypeRefDiscriminator(type: ContentObjectTypeRef | LegacyContentObjectTypeRef): ContentObjectTypeRef;
+export type ContentObjectTypeRef = z.infer<typeof ContentObjectTypeRefSchema>;
+export type ComplexSearchPayload = z.infer<typeof ComplexSearchPayloadSchema>;
+export type ColumnLayout = z.infer<typeof ColumnLayoutSchema>;
+export type ContentObjectTypeStatus = z.infer<typeof ContentObjectTypeStatusSchema>;
+export type IntakeVisionDetail = z.infer<typeof IntakeVisionDetailSchema>;
+export type IntakePageScope = z.infer<typeof IntakePageScopeSchema>;
+/**
+ * Inclusive `[start, end]` pairs.
+ *
+ * Inferred as `number[][]` rather than the `[number, number][]` this used to declare: the published
+ * component is a uniform-items array with `minItems`/`maxItems`, which is what the scanner made of the
+ * tuple, and reproducing it is what keeps the generated clients unchanged. The length is still
+ * enforced at runtime.
+ */
+export type IntakePageRanges = z.infer<typeof IntakePageRangesSchema>;
+/** Rendering settings behind a vision detail name (platform defaults, project-overridable
+ * via `configuration.intake.vision_profiles`). */
+export interface IntakeVisionProfileSettings {
+    /** Render resolution in dots per inch. */
+    dpi: number;
+    /** Maximum height/width of the rendered page image in pixels. */
+    max_hw: number;
+    /** JPEG quality (0-100). */
+    quality: number;
+    /** grayscale renders gray always; auto keeps color when the plan asks for it. */
+    color_mode: 'grayscale' | 'auto';
+}
+export type ContentTypeExtractionGroundingReviewPolicy = z.infer<typeof ContentTypeExtractionGroundingReviewPolicySchema>;
+export type ContentTypeExtractionGroundingPolicy = z.infer<typeof ContentTypeExtractionGroundingPolicySchema>;
+export type ContentTypeIntakePolicy = z.infer<typeof ContentTypeIntakePolicySchema>;
+export type ContentTypeEditingPolicy = z.infer<typeof ContentTypeEditingPolicySchema>;
+export type ContentObjectType = z.infer<typeof ContentObjectTypeSchema>;
+export type ContentObjectTypeItem = z.infer<typeof ContentObjectTypeItemSchema>;
+export type InCodeTypeDefinition = z.infer<typeof InCodeTypeDefinitionSchema>;
+export type ContentObjectTypeCatalogEntry = z.infer<typeof ContentObjectTypeCatalogEntrySchema>;
+/**
+ * The itnerface to be used whend efining types in a plugin app.
+ */
+export type InCodeTypeSpec = Omit<InCodeTypeDefinition, 'id'>;
+/**
+ * Returns true if the type id represents an in-code type (system or app-contributed).
+ * In-code types use colon-separated ids like "sys:Invoice" or "app:myapp:Article".
+ * These types are read-only and cannot be edited through the UI.
+ */
+export declare function isInCodeType(typeId: string): boolean;
+export type CreateContentObjectTypePayload = z.infer<typeof CreateContentObjectTypePayloadSchema>;
+export type UpdateContentObjectTypePayload = z.infer<typeof UpdateContentObjectTypePayloadSchema>;
+export declare enum WorkflowRuleInputType {
+    single = "single",
+    multiple = "multiple",
+    none = "none"
+}
+export type WorkflowRuleItem = z.infer<typeof WorkflowRuleItemSchema>;
+export type WorkflowRule = z.infer<typeof WorkflowRuleSchema>;
+export type CreateWorkflowRulePayload = z.infer<typeof CreateWorkflowRulePayloadSchema>;
+export interface UploadWorkflowRulePayload extends Partial<Omit<WorkflowRule, 'id' | 'created_at' | 'updated_at' | 'owner'>> {
+}
+export declare enum ImageRenditionFormat {
+    jpeg = "jpeg",
+    png = "png",
+    webp = "webp"
+}
+export declare const MarkdownRenditionFormat: {
+    readonly docx: "docx";
+    readonly pdf: "pdf";
+};
+export type MarkdownRenditionFormat = z.infer<typeof MarkdownRenditionFormatSchema>;
+export interface GetRenditionParams {
+    format: ImageRenditionFormat | MarkdownRenditionFormat;
+    max_hw?: number;
+    generate_if_missing?: boolean;
+    sign_url?: boolean;
+    block_on_generation?: boolean;
+}
+export type GetRenditionResponse = z.infer<typeof GetRenditionResponseSchema>;
+export type ObjectSearchResponse = z.infer<typeof ObjectSearchResponseSchema>;
+export type RenditionFormat = ImageRenditionFormat | MarkdownRenditionFormat;
+/**
+ * Check if a specific rendition format can be generated from a content type.
+ *
+ * @param contentType - The MIME type of the source content (e.g., 'image/png', 'text/markdown')
+ * @param format - The desired rendition format (e.g., ImageRenditionFormat.jpeg)
+ * @returns true if the format can be generated from the content type
+ *
+ * @example
+ * canGenerateRendition('image/png', ImageRenditionFormat.jpeg) // true
+ * canGenerateRendition('text/markdown', ImageRenditionFormat.jpeg) // false
+ * canGenerateRendition('text/markdown', MarkdownRenditionFormat.pdf) // true
+ */
+export declare function canGenerateRendition(contentType: string | undefined, format: RenditionFormat | string): boolean;
+/**
+ * Get the list of rendition formats supported for a given content type.
+ *
+ * @param contentType - The MIME type of the source content
+ * @returns Array of supported rendition formats, or empty array if none
+ *
+ * @example
+ * getSupportedRenditionFormats('image/png') // [jpeg, png, webp]
+ * getSupportedRenditionFormats('text/markdown') // [pdf, docx]
+ * getSupportedRenditionFormats('text/html') // []
+ */
+export declare function getSupportedRenditionFormats(contentType: string | undefined): RenditionFormat[];
+/**
+ * Check if a content type supports visual (image) renditions.
+ * This is useful for determining if a document can have thumbnails/previews.
+ *
+ * @param contentType - The MIME type of the source content
+ * @returns true if the content type can generate JPEG renditions
+ *
+ * @example
+ * supportsVisualRendition('image/png') // true
+ * supportsVisualRendition('application/pdf') // true
+ * supportsVisualRendition('text/markdown') // false
+ */
+export declare function supportsVisualRendition(contentType: string | undefined): boolean;
+export type GetUploadUrlPayload = z.infer<typeof GetUploadUrlPayloadSchema>;
+export type GetFileUrlPayload = z.infer<typeof GetFileUrlPayloadSchema>;
+export type GetFileUrlResponse = z.infer<typeof GetFileUrlResponseSchema>;
+export type EnsureBucketReadAccessPayload = z.infer<typeof EnsureBucketReadAccessPayloadSchema>;
+export type EnsureBucketReadAccessResponse = z.infer<typeof EnsureBucketReadAccessResponseSchema>;
+export type BucketReadAccessStatusResponse = z.infer<typeof BucketReadAccessStatusResponseSchema>;
+export type FileMetadataResponse = z.infer<typeof FileMetadataResponseSchema>;
+export type SetFileMetadataPayload = z.infer<typeof SetFileMetadataPayloadSchema>;
+export type FileMetadataUpdateResult = z.infer<typeof FileMetadataUpdateResultSchema>;
+export type BulkUploadUrlsPayload = z.infer<typeof BulkUploadUrlsPayloadSchema>;
+export type BulkUploadUrlsResponse = z.infer<typeof BulkUploadUrlsResponseSchema>;
+export type FileBucketResponse = z.infer<typeof FileBucketResponseSchema>;
+export type FileListResponse = z.infer<typeof FileListResponseSchema>;
+export type FileMetadataQuery = z.infer<typeof FileMetadataQuerySchema>;
+export type FileListQuery = z.infer<typeof FileListQuerySchema>;
+export type FileDeleteQuery = z.infer<typeof FileDeleteQuerySchema>;
+export type ContentObjectTypeCatalogQuery = z.infer<typeof ContentObjectTypeCatalogQuerySchema>;
+export type ContentObjectTypeListQuery = z.infer<typeof ContentObjectTypeListQuerySchema>;
+export type CopyFilePayload = z.infer<typeof CopyFilePayloadSchema>;
+export type CopyFileResponse = z.infer<typeof CopyFileResponseSchema>;
+export type DeleteFileResult = z.infer<typeof DeleteFileResultSchema>;
+export declare enum ContentObjectProcessingPriority {
+    normal = "normal",
+    low = "low"
+}
+export {};
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: store/object-types.d.ts
+// -----------------------------------------------------------------------------
+import type { JSONSchemaType } from 'ajv';
+export interface RenditionProperties {
+    mime_type: string;
+    source_etag?: string;
+    height?: number;
+    width?: number;
+    multipart?: boolean;
+    total_parts?: number;
+}
+export declare const RenditionSchema: JSONSchemaType<RenditionProperties>;
+export interface DocumentPartProperties {
+    source_etag?: string;
+    part_number: number;
+    title?: string;
+    source_line_start?: number;
+    source_line_end?: number;
+    type?: 'text' | 'image' | 'table' | 'chart' | 'diagram' | 'code' | 'other';
+    page_number?: number;
+    description?: string;
+    height?: number;
+    width?: number;
+}
+export declare const DocumentPartSchema: JSONSchemaType<DocumentPartProperties>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: store/collections.d.ts
+// -----------------------------------------------------------------------------
+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';
+export declare enum CollectionStatus {
+    active = "active",
+    archived = "archived"
+}
+export type CreateCollectionPayload = z.infer<typeof CreateCollectionPayloadSchema>;
+export interface CollectionItem extends BaseObject {
+    /**
+     * A flag to indicate if the collection is dynamic or static.
+     * If the collection is dynamic, the members are determined by a query using the query field.
+     * If the collection is static, the members are explicitly defined using the members array.
+     */
+    dynamic: boolean;
+    status: CollectionStatus;
+    type?: ContentObjectTypeRef;
+    /**
+     * A flag to indicate whether to track and sync member HEAD revisions.
+     * The default is to sync HEAD revisions for collection members (skip_head_sync: false)
+     */
+    skip_head_sync: boolean;
+    /**
+     * The parent collections if any.
+     * A collection can have multiple parents.
+     */
+    parents?: string[] | null;
+    /**
+     * The table layout to use for the collection.
+     * The layout defined in the type could serve as a fallback if not defined here.
+     */
+    table_layout?: ColumnLayout[];
+    /**
+     * The allowed types for the collection.
+     */
+    allowed_types?: string[];
+}
+export type Collection = z.infer<typeof CollectionSchema>;
+export interface StaticCollection extends Collection {
+    dynamic: false;
+    members: string[];
+    query: never;
+}
+export interface DynamicCollection extends Collection {
+    dynamic: true;
+}
+export interface CollectionSearchPayload {
+    parent?: string | null;
+    dynamic?: boolean;
+    status?: CollectionStatus;
+    limit?: number;
+    offset?: number;
+    name?: string;
+    type?: string;
+    types?: string[];
+}
+export type CollectionMembersUpdateResult = z.infer<typeof CollectionMembersUpdateResultSchema>;
+export type CollectionSecuritySettingsResponse = z.infer<typeof CollectionSecuritySettingsResponseSchema>;
+export type CollectionPropagationResponse = z.infer<typeof CollectionPropagationResponseSchema>;
+export type CollectionChildrenUpdateResult = z.infer<typeof CollectionChildrenUpdateResultSchema>;
+export type CollectionMembersUpdatePayload = z.infer<typeof CollectionMembersUpdatePayloadSchema>;
+export type CollectionChildrenUpdatePayload = z.infer<typeof CollectionChildrenUpdatePayloadSchema>;
+export type CollectionMembersQuery = z.infer<typeof CollectionMembersQuerySchema>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: store/process.d.ts
+// -----------------------------------------------------------------------------
+import type { z } from 'zod';
+import type { BranchDefinitionSchema, BranchJoinPolicySchema, HumanTaskDefinitionSchema, JsonLogicRuleSchema, ListProcessDefinitionsQuerySchema, NodeHistoryEntrySchema, ParallelCollectDefinitionSchema, ParallelCollectFieldSchema, ParallelCollectModeSchema, ParallelFailurePolicySchema, ProcessContextDefinitionSchema, ProcessDefinitionFormatVersionSchema, ProcessDefinitionMetadataSchema, ProcessDefinitionRevisionInfoSchema, ProcessDefinitionStatusSchema, ProcessHistoryRefSchema, ProcessNodeReturnsDefinitionSchema, ProcessNodeRunTypeSchema, ProcessNodeTypeSchema, ProcessResourcesDefinitionSchema, ProcessScriptInlineSourceSchema, ProcessScriptLanguageSchema, ProcessScriptResourceSchema, ProcessScriptSourceSchema, ProcessStateSchema, PublishProcessDefinitionPayloadSchema, RevertProcessDefinitionPayloadSchema, TransitionDefinitionSchema, TransitionTriggerSchema } from '../api-schemas/process.js';
+import type { JSONSchema } from '../json-schema.js';
+export type JsonLogicRule = z.infer<typeof JsonLogicRuleSchema>;
+export type ProcessDefinitionStatus = z.infer<typeof ProcessDefinitionStatusSchema>;
+export type ListProcessDefinitionsQuery = z.infer<typeof ListProcessDefinitionsQuerySchema>;
+export declare const PROCESS_DEFINITION_FORMAT_VERSION: 1;
+export type ProcessDefinitionFormatVersion = z.infer<typeof ProcessDefinitionFormatVersionSchema>;
+export type ProcessNodeType = z.infer<typeof ProcessNodeTypeSchema>;
+export type TransitionTrigger = z.infer<typeof TransitionTriggerSchema>;
+export type ParallelFailurePolicy = z.infer<typeof ParallelFailurePolicySchema>;
+export type ProcessNodeRunType = z.infer<typeof ProcessNodeRunTypeSchema>;
+export type ParallelCollectMode = z.infer<typeof ParallelCollectModeSchema>;
+export type BranchJoinPolicy = z.infer<typeof BranchJoinPolicySchema>;
+export type ProcessDefinitionMetadata = z.infer<typeof ProcessDefinitionMetadataSchema>;
+export type ProcessScriptLanguage = z.infer<typeof ProcessScriptLanguageSchema>;
+export type ProcessScriptInlineSource = z.infer<typeof ProcessScriptInlineSourceSchema>;
+export type ProcessScriptSource = z.infer<typeof ProcessScriptSourceSchema>;
+export type ProcessScriptResource = z.infer<typeof ProcessScriptResourceSchema>;
+export type ProcessResourcesDefinition = z.infer<typeof ProcessResourcesDefinitionSchema>;
+export type ParallelCollectField = z.infer<typeof ParallelCollectFieldSchema>;
+export type TransitionDefinition = z.infer<typeof TransitionDefinitionSchema>;
+export type BranchDefinition = z.infer<typeof BranchDefinitionSchema>;
+export interface BranchNodeBranchDefinition {
+    id: string;
+    title?: string;
+    description?: string;
+    node: NodeDefinition;
+    metadata?: ProcessDefinitionMetadata;
+}
+export type HumanTaskDefinition = z.infer<typeof HumanTaskDefinitionSchema>;
+export type ProcessNodeReturnsDefinition = z.infer<typeof ProcessNodeReturnsDefinitionSchema>;
+export type ParallelCollectDefinition = z.infer<typeof ParallelCollectDefinitionSchema>;
+export interface NodeDefinition {
+    type: ProcessNodeType;
+    tool?: string;
+    /** Named entry in process resources.scripts for script nodes. */
+    script?: string;
+    /** Script execution timeout in seconds. Defaults to 300 and is capped at 600. */
+    timeout?: number;
+    interaction?: string;
+    process?: string;
+    process_definition?: ProcessDefinitionBody;
+    process_version?: number;
+    run_type?: ProcessNodeRunType;
+    returns?: ProcessNodeReturnsDefinition;
+    /**
+     * Optional JSON Schema for structured output produced by interaction and
+     * agent nodes. When omitted, the process engine derives a schema from
+     * `writes` and the process context schema.
+     */
+    result_schema?: JSONSchema;
+    prompt?: string;
+    input?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    title?: string;
+    description?: string;
+    /**
+     * End-user-facing explanation of what this node does. Authored by the
+     * process designer (often an LLM) in plain language — one or two
+     * sentences — and rendered in run observability so a human reading the
+     * run can understand why this node exists without reading the config.
+     * Distinct from `description`, which is developer-facing.
+     */
+    human_description?: string;
+    writes?: string[];
+    skippable?: boolean;
+    max_retries?: number;
+    transitions?: TransitionDefinition[];
+    tools?: string[];
+    /**
+     * Model id override for this node. If unset, falls back to the process
+     * run's `config.model`, then to the project's default. Useful when a
+     * specific node needs heavier reasoning (e.g. Opus for legal flagging)
+     * while the rest of the process uses a cheaper default.
+     */
+    model?: string;
+    task?: HumanTaskDefinition;
+    foreach?: string;
+    as?: string;
+    item_id?: string;
+    node?: NodeDefinition;
+    max_concurrency?: number;
+    collect?: string | ParallelCollectDefinition;
+    failure_policy?: ParallelFailurePolicy;
+    join?: BranchJoinPolicy;
+    branches?: BranchDefinition[] | BranchNodeBranchDefinition[];
+    metadata?: ProcessDefinitionMetadata;
+}
+export type ProcessContextDefinition = z.infer<typeof ProcessContextDefinitionSchema>;
+export interface ProcessDefinitionBody {
+    format_version: ProcessDefinitionFormatVersion;
+    process: string;
+    description?: string;
+    initial: string;
+    model?: string;
+    resources?: ProcessResourcesDefinition;
+    context: ProcessContextDefinition;
+    nodes: Record<string, NodeDefinition>;
+    metadata?: ProcessDefinitionMetadata;
+}
+export interface InCodeProcessDefinition {
+    /**
+     * Process identifier exposed by an app package. App-local ids are normalized
+     * by Studio to `app:<app-name>:<id>` when returned to callers.
+     */
+    id: string;
+    /** Human-readable or app-local process name. */
+    name: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    definition: ProcessDefinitionBody;
+}
+export type ProcessDefinitionRevisionInfo = z.infer<typeof ProcessDefinitionRevisionInfoSchema>;
+export interface ProcessDefinition {
+    id: string;
+    account: string;
+    project: string;
+    name: string;
+    description?: string;
+    status: ProcessDefinitionStatus;
+    version: number;
+    revision?: ProcessDefinitionRevisionInfo;
+    tags?: string[];
+    definition: ProcessDefinitionBody;
+    created_at: Date;
+    updated_at: Date;
+    created_by: string;
+    updated_by: string;
+}
+export type NodeHistoryEntry = z.infer<typeof NodeHistoryEntrySchema>;
+export type ProcessHistoryRef = z.infer<typeof ProcessHistoryRefSchema>;
+export interface ProcessHistoryCheckpoint {
+    sequence: number;
+    current_node: string;
+    written_at: Date | string;
+    entries: NodeHistoryEntry[];
+}
+export type ProcessState = z.infer<typeof ProcessStateSchema>;
+export interface CreateProcessDefinitionPayload {
+    name: string;
+    description?: string;
+    /**
+     * @deprecated Process definitions are created as drafts. Use the publish endpoint
+     * to create immutable published versions.
+     */
+    status?: ProcessDefinitionStatus;
+    /**
+     * @deprecated Version is server-owned. Use the publish endpoint to create the next version.
+     */
+    version?: number;
+    tags?: string[];
+    definition: ProcessDefinitionBody;
+}
+export interface UpdateProcessDefinitionPayload {
+    name?: string;
+    description?: string;
+    /**
+     * @deprecated Status is server-owned. Use publish/archive endpoints instead of updating it directly.
+     */
+    status?: ProcessDefinitionStatus;
+    /**
+     * @deprecated Version is server-owned. Use the publish endpoint to create the next version.
+     */
+    version?: number;
+    tags?: string[];
+    definition?: ProcessDefinitionBody;
+}
+export type PublishProcessDefinitionPayload = z.infer<typeof PublishProcessDefinitionPayloadSchema>;
+export type RevertProcessDefinitionPayload = z.infer<typeof RevertProcessDefinitionPayloadSchema>;
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: store/process-schema.d.ts
+// -----------------------------------------------------------------------------
+export declare const PROCESS_DEFINITION_JSON_SCHEMA_ID = "https://schemas.vertesia.com/process-definition.v1.schema.json";
+export declare const ProcessDefinitionBodyJsonSchema: {
+    $id: string;
+    type: string;
+    description: string;
+    properties: {
+        format_version: {
+            type: string;
+            const: number;
+            description: string;
+        };
+        process: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        description: {
+            type: string;
+            nullable: true;
+            description: string;
+        };
+        initial: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        model: {
+            type: string;
+            nullable: true;
+            description: string;
+        };
+        resources: {
+            $ref: string;
+        };
+        context: {
+            $ref: string;
+        };
+        nodes: {
+            type: string;
+            description: string;
+            minProperties: number;
+            required: never[];
+            additionalProperties: {
+                $ref: string;
+            };
+        };
+        metadata: {
+            $ref: string;
+        };
+    };
+    required: string[];
+    additionalProperties: false;
+    $defs: {
+        metadataDefinition: {
+            type: string;
+            nullable: true;
+            description: string;
+            required: never[];
+            additionalProperties: true;
+        };
+        processContextDefinition: {
+            type: string;
+            properties: {
+                schema: {
+                    description: string;
+                    anyOf: ({
+                        type: string;
+                        additionalProperties?: undefined;
+                    } | {
+                        type: string;
+                        additionalProperties: true;
+                    })[];
+                };
+                initial: {
+                    type: string;
+                    description: string;
+                    required: never[];
+                    additionalProperties: true;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        nodeDefinition: {
+            type: string;
+            description: string;
+            properties: {
+                type: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                tool: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                script: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                timeout: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                    nullable: true;
+                    description: string;
+                };
+                interaction: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                process: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                process_definition: {
+                    $ref: string;
+                    description: string;
+                };
+                process_version: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                run_type: {
+                    type: string;
+                    enum: string[];
+                    nullable: true;
+                    description: string;
+                };
+                returns: {
+                    $ref: string;
+                };
+                result_schema: {
+                    $ref: string;
+                    description: string;
+                };
+                prompt: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                input: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    required: never[];
+                    additionalProperties: true;
+                };
+                config: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    required: never[];
+                    additionalProperties: true;
+                };
+                title: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                human_description: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                writes: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                skippable: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                max_retries: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                transitions: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        $ref: string;
+                    };
+                };
+                tools: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                model: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                task: {
+                    $ref: string;
+                };
+                foreach: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                as: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                item_id: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                node: {
+                    $ref: string;
+                    description: string;
+                };
+                max_concurrency: {
+                    type: string;
+                    minimum: number;
+                    nullable: true;
+                    description: string;
+                };
+                collect: {
+                    description: string;
+                    oneOf: ({
+                        type: string;
+                        minLength: number;
+                        $ref?: undefined;
+                    } | {
+                        $ref: string;
+                        type?: undefined;
+                        minLength?: undefined;
+                    })[];
+                };
+                failure_policy: {
+                    type: string;
+                    enum: string[];
+                    nullable: true;
+                    description: string;
+                };
+                join: {
+                    type: string;
+                    enum: string[];
+                    nullable: true;
+                    description: string;
+                };
+                branches: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        oneOf: {
+                            $ref: string;
+                        }[];
+                    };
+                };
+                metadata: {
+                    $ref: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        transitionDefinition: {
+            type: string;
+            properties: {
+                to: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                guard: {
+                    $ref: string;
+                    description: string;
+                };
+                trigger: {
+                    type: string;
+                    enum: string[];
+                    nullable: true;
+                    description: string;
+                };
+                label: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                metadata: {
+                    $ref: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        processResourcesDefinition: {
+            type: string;
+            nullable: true;
+            properties: {
+                scripts: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    required: never[];
+                    additionalProperties: {
+                        $ref: string;
+                    };
+                };
+            };
+            required: never[];
+            additionalProperties: false;
+        };
+        processScriptResource: {
+            type: string;
+            properties: {
+                language: {
+                    type: string;
+                    enum: string[];
+                };
+                entrypoint: {
+                    type: string;
+                    minLength: number;
+                };
+                source: {
+                    $ref: string;
+                };
+                packages: {
+                    type: string;
+                    nullable: true;
+                    items: {
+                        type: string;
+                    };
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        processScriptSource: {
+            $ref: string;
+        };
+        processScriptInlineSource: {
+            type: string;
+            properties: {
+                type: {
+                    type: string;
+                    const: string;
+                    description: string;
+                };
+                files: {
+                    type: string;
+                    minProperties: number;
+                    required: never[];
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        branchDefinition: {
+            type: string;
+            properties: {
+                to: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                when: {
+                    $ref: string;
+                    description: string;
+                };
+                default: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                metadata: {
+                    $ref: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        branchNodeBranchDefinition: {
+            type: string;
+            properties: {
+                id: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                title: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                node: {
+                    $ref: string;
+                    description: string;
+                };
+                metadata: {
+                    $ref: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        humanTaskDefinition: {
+            type: string;
+            properties: {
+                title: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                assignee: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                fields: {
+                    type: string;
+                    description: string;
+                    items: {
+                        $ref: string;
+                    };
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        taskField: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                type: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                required: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                label: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                options: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                default: {
+                    description: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        processNodeReturnsDefinition: {
+            type: string;
+            properties: {
+                from: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                };
+                context: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        type: string;
+                    };
+                };
+            };
+            required: never[];
+            additionalProperties: false;
+        };
+        parallelCollectDefinition: {
+            type: string;
+            properties: {
+                into: {
+                    type: string;
+                    minLength: number;
+                    description: string;
+                };
+                mode: {
+                    type: string;
+                    enum: string[];
+                    nullable: true;
+                    description: string;
+                };
+                include: {
+                    type: string;
+                    nullable: true;
+                    description: string;
+                    items: {
+                        type: string;
+                        enum: string[];
+                    };
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        jsonLogicRule: {
+            type: string;
+            description: string;
+            required: never[];
+            additionalProperties: true;
+        };
+        jsonSchemaDefinition: {
+            type: string;
+            nullable: true;
+            description: string;
+            required: never[];
+            additionalProperties: true;
+        };
+    };
+};
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: store/workflow.d.ts
+// -----------------------------------------------------------------------------
+import type { HttpTimeoutOptions, ModelOptions } from '@llumiverse/common';
+import type { z } from 'zod';
+import type { AgentMessageDetailsSchema, CompactMessageSchema, ConversationFileSchema } from '../api-schemas/agent-runs.js';
+import type { ConversationActivityStateSchema } from '../api-schemas/app-lifecycle.js';
+import type { WorkflowExecutionStatusSchema } from '../api-schemas/document-processing.js';
+import type { PlanSchema, PlanTaskSchema, WorkflowAncestorSchema } from '../api-schemas/interaction.js';
+import type { WorkflowExecutionStartResultSchema } from '../api-schemas/process.js';
+import type { ActivityTaskSchema, AgentTaskSchema, ChildWorkflowTaskSchema, EventErrorSchema, ExecuteWorkflowPayloadSchema, ListWorkflowInteractionsResponseSchema, ListWorkflowRunsPayloadSchema, ListWorkflowRunsResponseSchema, PendingActivitySchema, SignalEventPropertiesSchema, SignalTaskSchema, TimerTaskSchema, WorkflowActionResponseSchema, WorkflowHistorySchema, WorkflowInteractionVarsSchema, WorkflowQueryResultSchema, WorkflowRunDetailsQuerySchema, WorkflowRunEventSchema, WorkflowRunSchema, WorkflowRunStreamQuerySchema, WorkflowRunUpdatesQuerySchema, WorkflowRunUpdatesResponseSchema, WorkflowRunWithDetailsSchema, WorkflowTaskSchema, WorkflowUpdatePublishResponseSchema } from '../api-schemas/workflow-runs.js';
+import type { AgentResourceReference, InteractionExecutionConfiguration } from '../interaction.js';
+import type { SupportedEmbeddingTypes } from '../project.js';
+import type { WorkflowInput } from './dsl-workflow.js';
+export declare enum ContentEventName {
+    create = "create",
+    change_type = "change_type",
+    update = "update",
+    revision_created = "revision_created",
+    delete = "delete",
+    workflow_finished = "workflow_finished",
+    workflow_execution_request = "workflow_execution_request",
+    api_request = "api_request"
+}
+export interface Queue {
+    name: string;
+    queue_suffix?: string;
+    queue_full_name?: string;
+}
+export type WorkflowAncestor = z.infer<typeof WorkflowAncestorSchema>;
+export interface WorkflowExecutionBaseParams<T = Record<string, unknown>> {
+    /**
+     * The ref of the user who initiated the workflow.
+     */
+    initiated_by?: string;
+    /**
+     * The account ID of the user who created the activity.
+     * This is useful to select the right database to work on.
+     */
+    account_id: string;
+    /**
+     * The project ID of the account who created the activity.
+     */
+    project_id: string;
+    /**
+     * The vars field is mainly used to pass the user input to the workflow.
+     * The user input ar custom user options that can be used to configure the workflow.
+     * You can see the user input as the arguments for a command line app.
+     *
+     * In the case of workflows started by event subscriptions, the user input vars
+     * are initialized from the subscription target configuration.
+     *
+     * In case of dsl workflows the workflow execution payload vars will be applied over the default vars values stored in the DSL vars field.
+     */
+    vars: T;
+    /**
+     * Auth Token to access Zeno and Composable from the workers
+     */
+    auth_token?: string;
+    /**
+     * The configuration for the workflow execution.
+     */
+    config?: {
+        studio_url: string;
+        store_url: string;
+        slack_app_url?: string;
+        enabled_integrations?: string[];
+    };
+    /**
+     * The list of endpoints to notify when the workflow finishes.
+     * It is handled by a sub-workflow execution, so the main workflow will not wait for the notification to be sent.
+     */
+    notify_endpoints?: (string | WebHookSpec)[];
+    /** If this is a child workflow, parent contains parent's ids  */
+    parent?: WorkflowAncestor;
+    /**
+     * Full ancestry chain from root to immediate parent (for hierarchical aggregation)
+     */
+    ancestors?: WorkflowAncestor[];
+    /**
+     *  List of enabled processing queues. Managed by the application.
+     */
+    _enabled_queues?: Queue[];
+}
+export interface WebHookSpec {
+    /**
+     * The webhook URL to call using POST method
+     */
+    url: string;
+    /**
+     * the API version to use if any
+     */
+    version?: number;
+    /**
+     * Custom headers to include in the webhook request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Additional custom data to include in the webhook body.
+     * When custom data is provided, the workflow result will always be nested
+     * to prevent field collisions. Use result_path to control where it's nested.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Path where the workflow result should be nested in the webhook body.
+     * Defaults to "result" when custom data is provided.
+     *
+     * Example: With result_path="workflow_result" and data={customer_id: "123"}:
+     * {
+     *   "workflow_result": { ...workflow result... },
+     *   "customer_id": "123"
+     * }
+     *
+     * Example: With data={customer_id: "123"} but no result_path (uses default):
+     * {
+     *   "result": { ...workflow result... },
+     *   "customer_id": "123"
+     * }
+     */
+    result_path?: string;
+}
+export interface WorkflowExecutionPayload<T = Record<string, unknown>, EventName extends string = string> extends WorkflowExecutionBaseParams<T> {
+    /**
+     * The event which started the workflow who created the activity.
+     */
+    event: EventName;
+    wf_rule_name?: string;
+    /**
+     * The ID of the target objects processed by the workflow (legacy format).
+     * For backward compatibility. New workflows should use the `input` field.
+     */
+    objectIds?: string[];
+    /**
+     * New format: Workflow input (either objectIds or files).
+     * Takes precedence over the legacy `objectIds` field.
+     */
+    input?: WorkflowInput;
+    /**
+     * Auth Token to access Zeno and Composable from the workers
+     */
+    auth_token: string;
+}
+export declare function getDocumentIds(payload: WorkflowExecutionPayload<Record<string, unknown>>): string[];
+export type ExecuteWorkflowPayload = z.infer<typeof ExecuteWorkflowPayloadSchema>;
+export type ConversationActivityState = z.infer<typeof ConversationActivityStateSchema>;
+export type ListWorkflowRunsPayload = z.infer<typeof ListWorkflowRunsPayloadSchema>;
+export type SignalEventProperties = z.infer<typeof SignalEventPropertiesSchema>;
+export type EventError = z.infer<typeof EventErrorSchema>;
+export type WorkflowRunEvent = z.infer<typeof WorkflowRunEventSchema>;
+export declare enum TaskStatus {
+    SCHEDULED = "scheduled",
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELED = "canceled",
+    TIMED_OUT = "timed_out",
+    TERMINATED = "terminated",
+    SENT = "sent",// for signals
+    RECEIVED = "received"
+}
+export declare enum TaskType {
+    ACTIVITY = "activity",
+    CHILD_WORKFLOW = "childWorkflow",
+    SIGNAL = "signal",
+    TIMER = "timer"
+}
+export type ActivityTask = z.infer<typeof ActivityTaskSchema>;
+export type ChildWorkflowTask = z.infer<typeof ChildWorkflowTaskSchema>;
+export type SignalTask = z.infer<typeof SignalTaskSchema>;
+export type TimerTask = z.infer<typeof TimerTaskSchema>;
+export type WorkflowTask = z.infer<typeof WorkflowTaskSchema>;
+export type WorkflowHistory = z.infer<typeof WorkflowHistorySchema>;
+export type HistoryFormat = 'events' | 'tasks' | 'agent';
+export type AgentTask = z.infer<typeof AgentTaskSchema>;
+export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
+export type PendingActivity = z.infer<typeof PendingActivitySchema>;
+export type WorkflowRunWithDetails = z.infer<typeof WorkflowRunWithDetailsSchema>;
+export type ListWorkflowRunsResponse = z.infer<typeof ListWorkflowRunsResponseSchema>;
+export type WorkflowExecutionStartResult = z.infer<typeof WorkflowExecutionStartResultSchema>;
+export type ListWorkflowInteractionsResponse = z.infer<typeof ListWorkflowInteractionsResponseSchema>;
+export type WorkflowRunUpdatesResponse = z.infer<typeof WorkflowRunUpdatesResponseSchema>;
+export type WorkflowRunDetailsQuery = z.infer<typeof WorkflowRunDetailsQuerySchema>;
+export type WorkflowRunUpdatesQuery = z.infer<typeof WorkflowRunUpdatesQuerySchema>;
+export type WorkflowRunStreamQuery = z.infer<typeof WorkflowRunStreamQuerySchema>;
+export type WorkflowUpdatePublishResponse = z.infer<typeof WorkflowUpdatePublishResponseSchema>;
+export type WorkflowActionResponse = z.infer<typeof WorkflowActionResponseSchema>;
+export type WorkflowQueryResult = z.infer<typeof WorkflowQueryResultSchema>;
+export type WorkflowInteractionVars = z.infer<typeof WorkflowInteractionVarsSchema>;
+export interface MultiDocumentsInteractionParams extends Omit<WorkflowExecutionPayload, 'config'> {
+    config: {
+        interactionName: string;
+        action: DocumentActionConfig;
+        data: Record<string, unknown>;
+    };
+}
+export interface DocumentActionConfig {
+    contentTypeName?: string;
+    setAsProperties: boolean;
+    setAsText: string;
+    setNameFrom: string;
+    upsert: boolean;
+    documentId?: string;
+    parentId?: string;
+}
+export declare const WorkflowExecutionStatusValues: {
+    readonly UNKNOWN: 0;
+    readonly RUNNING: 1;
+    readonly COMPLETED: 2;
+    readonly FAILED: 3;
+    readonly CANCELED: 4;
+    readonly TERMINATED: 5;
+    readonly CONTINUED_AS_NEW: 6;
+    readonly TIMED_OUT: 7;
+};
+export declare const WorkflowExecutionStatus: typeof WorkflowExecutionStatusValues & Readonly<Record<number, string>>;
+export type WorkflowExecutionStatus = z.infer<typeof WorkflowExecutionStatusSchema>;
+/**
+ * Basic response for anything run with an async workflow
+ */
+export interface WorkflowRunStatus {
+    workflow_id: string | null;
+    workflow_run_id: string | null;
+    status: WorkflowExecutionStatus;
+}
+/**
+ * Workflow Update Message
+ */
+export interface AgentMessage {
+    timestamp: number;
+    workflow_run_id: string;
+    type: AgentMessageType;
+    message: string;
+    details?: AgentMessageDetails;
+    workstream_id?: string;
+}
+export declare enum AgentMessageType {
+    SYSTEM = 0,
+    THOUGHT = 1,
+    PLAN = 2,
+    UPDATE = 3,
+    COMPLETE = 4,
+    WARNING = 5,
+    ERROR = 6,
+    ANSWER = 7,
+    QUESTION = 8,
+    REQUEST_INPUT = 9,
+    IDLE = 10,
+    TERMINATED = 11,
+    STREAMING_CHUNK = 12,
+    BATCH_PROGRESS = 13,
+    RESTARTING = 14
+}
+export type AgentMessageDetails = z.infer<typeof AgentMessageDetailsSchema>;
+/**
+ * Details for THOUGHT messages representing tool calls (event_class: 'activity').
+ */
+export interface ToolCallDetails {
+    event_class: 'activity';
+    tool: string;
+    tool_event?: 'started' | 'progress' | 'completed' | 'failed';
+    tool_run_id?: string;
+    tool_use_id?: string;
+    tool_status?: 'running' | 'completed' | 'error' | 'warning';
+    tool_iteration?: number;
+    message_to_human?: string;
+    duration_ms?: number;
+    activity_group_id?: string;
+    activity_id?: string;
+    files?: string[];
+    outputFiles?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Details for UPDATE messages signaling document creation or update.
+ */
+export interface DocumentEventDetails {
+    event_class: 'document_created' | 'document_updated';
+    document_id: string;
+    title?: string;
+    [key: string]: unknown;
+}
+/**
+ * Details for REQUEST_INPUT messages with UX configuration.
+ */
+export interface RequestInputDetails {
+    ux?: {
+        options?: Array<{
+            id: string;
+            label: string;
+        }>;
+        variant?: string;
+        multiSelect?: boolean;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Details for PLAN messages containing the plan structure.
+ */
+export interface PlanMessageDetails {
+    plan: PlanTask[];
+    comment?: string;
+    [key: string]: unknown;
+}
+export declare function isToolCallMessage(msg: AgentMessage): msg is AgentMessage & {
+    details: ToolCallDetails;
+};
+/** Extract the normalized resource references carried on a message's details, if any. */
+export declare function getResourcesFromMessage(msg: AgentMessage): AgentResourceReference[];
+export declare function isDocumentEventMessage(msg: AgentMessage): msg is AgentMessage & {
+    details: DocumentEventDetails;
+};
+export declare function isFileProcessingMessage(msg: AgentMessage): msg is AgentMessage & {
+    details: FileProcessingDetails;
+};
+export declare function isPlanMessage(msg: AgentMessage): msg is AgentMessage & {
+    details: PlanMessageDetails;
+};
+export declare function isRequestInputMessage(msg: AgentMessage): msg is AgentMessage & {
+    details: RequestInputDetails;
+};
+/**
+ * Details for STREAMING_CHUNK messages used for real-time LLM response streaming
+ * @deprecated Use CompactMessage with f field for streaming chunks
+ */
+export interface StreamingChunkDetails {
+    /** Unique identifier grouping chunks from the same stream */
+    streaming_id: string;
+    /** Order of this chunk within the stream (0-indexed) */
+    chunk_index?: number;
+    /** True if this is the final chunk of the stream */
+    is_final: boolean;
+    /** Activity ID for deduplication with final THOUGHT/ANSWER message */
+    activity_id?: string;
+}
+/**
+ * Compact message format for efficient wire transfer.
+ * Primary type used throughout the system.
+ * ~85% smaller than legacy AgentMessage format.
+ */
+export type CompactMessage = z.infer<typeof CompactMessageSchema>;
+/**
+ * Legacy message format for backward compatibility.
+ * @deprecated Use CompactMessage instead
+ */
+export type LegacyAgentMessage = AgentMessage;
+/**
+ * Check if a message is in compact format
+ */
+export declare function isCompactMessage(msg: unknown): msg is CompactMessage;
+/**
+ * Check if a message is in legacy format
+ */
+export declare function isLegacyMessage(msg: unknown): msg is LegacyAgentMessage;
+/**
+ * Normalize message type from string or number to AgentMessageType
+ */
+export declare function normalizeMessageType(type: string | number | AgentMessageType): AgentMessageType;
+/**
+ * Convert legacy AgentMessage to CompactMessage
+ */
+export declare function toCompactMessage(legacy: LegacyAgentMessage): CompactMessage;
+/**
+ * Parse any message format (compact or legacy) into CompactMessage.
+ * Use this as the entry point for all received messages.
+ */
+export declare function parseMessage(data: string | object): CompactMessage;
+/**
+ * Create a compact message (convenience function for server-side)
+ */
+export declare function createCompactMessage(type: AgentMessageType, options?: {
+    message?: string;
+    workstreamId?: string;
+    details?: AgentMessageDetails;
+    isFinal?: boolean;
+    timestamp?: number;
+}): CompactMessage;
+/**
+ * Convert CompactMessage back to AgentMessage (for UI components).
+ * This allows UI to continue using familiar field names while wire format is compact.
+ * @param compact The compact message to convert
+ * @param workflowRunId Optional workflow_run_id (known from SSE context, not in compact format)
+ */
+export declare function toAgentMessage(compact: CompactMessage, workflowRunId?: string): AgentMessage;
+/**
+ * Status of a single item in a batch execution
+ */
+export interface BatchItemStatus {
+    /** Unique identifier for this batch item */
+    id: string;
+    /** Current status of the item */
+    status: 'pending' | 'running' | 'success' | 'error';
+    /** Optional message (e.g., error message or result summary) */
+    message?: string;
+    /** Execution duration in milliseconds (when completed) */
+    duration_ms?: number;
+}
+/**
+ * Details for BATCH_PROGRESS messages used for batch tool execution progress
+ */
+export interface BatchProgressDetails {
+    /** Unique identifier for this batch execution */
+    batch_id: string;
+    /** Name of the tool being batch executed */
+    tool_name: string;
+    /** Total number of items in the batch */
+    total: number;
+    /** Number of items completed */
+    completed: number;
+    /** Number of items that succeeded */
+    succeeded: number;
+    /** Number of items that failed */
+    failed: number;
+    /** Status of individual items */
+    items: BatchItemStatus[];
+    /** Timestamp when batch started */
+    started_at: number;
+    /** Timestamp when batch completed (if done) */
+    completed_at?: number;
+}
+/**
+ * Status of a file being processed for conversation use.
+ */
+export declare enum FileProcessingStatus {
+    /** File is being uploaded to artifact storage */
+    UPLOADING = "uploading",
+    /** File uploaded, text extraction in progress */
+    PROCESSING = "processing",
+    /** File is ready for use in conversation */
+    READY = "ready",
+    /** File processing failed */
+    ERROR = "error"
+}
+export type ConversationFile = z.infer<typeof ConversationFileSchema>;
+/**
+ * Details for file processing SYSTEM messages.
+ * Used when type is AgentMessageType.SYSTEM with system_type: 'file_processing'.
+ */
+export interface FileProcessingDetails {
+    /** Discriminator for SYSTEM message subtypes */
+    system_type: 'file_processing';
+    /** Batch ID for grouping related file operations */
+    batch_id: string;
+    /** All files in this batch with their current status */
+    files: ConversationFile[];
+    /** Number of files still being processed */
+    pending_count: number;
+    /** Number of files ready for use */
+    ready_count: number;
+    /** Number of files that failed */
+    error_count: number;
+}
+/**
+ * Reference to a file uploaded via the UI for conversation use.
+ */
+export interface ConversationFileRef {
+    /** Client-generated unique ID */
+    id: string;
+    /** Original filename */
+    name: string;
+    /** MIME type */
+    content_type: string;
+    /** Artifact reference (e.g., "artifact:files/document.pdf") */
+    reference: string;
+    /** Artifact path without prefix (e.g., "files/document.pdf") */
+    artifact_path: string;
+}
+/**
+ * Reference to a file removed from the conversation attachment set.
+ */
+export interface ConversationFileRemovedRef {
+    /** Client-generated unique ID */
+    id: string;
+}
+/**
+ * Get the Redis pub/sub channel name for workflow messages.
+ * Used by both publishers (workflow activities, studio-server) and subscribers (zeno-server, clients).
+ * @param workflowRunId - The Temporal workflow run ID (NOT the interaction execution run ID)
+ */
+export declare function getWorkflowChannel(workflowRunId: string): string;
+/**
+ * Get the Redis list key for storing workflow message history.
+ * Messages are stored here for retrieval by reconnecting clients.
+ * @param workflowRunId - The Temporal workflow run ID (NOT the interaction execution run ID)
+ */
+export declare function getWorkflowUpdatesKey(workflowRunId: string): string;
+export type PlanTask = z.infer<typeof PlanTaskSchema>;
+export type Plan = z.infer<typeof PlanSchema>;
+export declare const LOW_PRIORITY_TASK_QUEUE = "low_priority";
+/**
+ * WebSocket message types for bidirectional communication
+ */
+export interface WebSocketSignalMessage {
+    type: 'signal';
+    signalName: string;
+    data: unknown;
+    requestId?: string | number;
+}
+export interface WebSocketPingMessage {
+    type: 'ping';
+}
+export interface WebSocketPongMessage {
+    type: 'pong';
+}
+export interface WebSocketAckMessage {
+    type: 'ack';
+    requestId: string | number;
+}
+export interface WebSocketErrorMessage {
+    type: 'error';
+    requestId?: string | number;
+    error: string;
+}
+export type WebSocketClientMessage = WebSocketSignalMessage | WebSocketPingMessage;
+export type WebSocketServerMessage = WebSocketPongMessage | WebSocketAckMessage | WebSocketErrorMessage | AgentMessage;
+/**
+ * Payload for applying actions to a workflow run (e.g., cancel, terminate).
+ */
+export interface WorkflowActionPayload {
+    /**
+     * Optional reason for the action.
+     */
+    reason?: string;
+}
+/**
+ * Parameters for the AgentIntakeWorkflow.
+ * This workflow uses an intelligent agent to process documents:
+ * - Select or create appropriate content types
+ * - Extract properties using schema-enforced interactions
+ * - File documents into relevant collections
+ */
+export interface AgentIntakeWorkflowParams {
+    /**
+     * The interaction to use for document intake agent.
+     * Defaults to "sys:DocumentIntakeAgent" if not specified.
+     * Can be overridden with a project-level interaction.
+     */
+    intakeInteraction?: string;
+    /**
+     * The interaction to use for property extraction.
+     * Defaults to "sys:ExtractInformation" if not specified.
+     * Can be overridden with a project-level interaction.
+     */
+    extractionInteraction?: string;
+    /**
+     * Whether to generate table of contents for documents.
+     * Defaults to true for documents, false for images/videos.
+     */
+    generateTableOfContents?: boolean;
+    /**
+     * Whether to generate embeddings after processing.
+     * Defaults to true.
+     */
+    generateEmbeddings?: boolean;
+    /**
+     * Max iterations for the agent workflow.
+     * Defaults to 50.
+     */
+    maxIterations?: number;
+    /**
+     * Environment ID for LLM execution.
+     */
+    environment?: string;
+    /**
+     * Model to use for the agent.
+     */
+    model?: string;
+    /**
+     * Additional model options.
+     */
+    model_options?: ModelOptions;
+    /**
+     * Per-run HTTP timeouts for upstream LLM-provider calls.
+     */
+    http_timeout?: HttpTimeoutOptions;
+    /**
+     * LLM execution config. Prefer this for event-subscription-driven execution settings.
+     */
+    config?: InteractionExecutionConfiguration;
+    /**
+     * Whether to use semantic layer (MagicPDF) for PDF processing.
+     */
+    useSemanticLayer?: boolean;
+    /**
+     * Whether to use vision for image-based extraction.
+     */
+    useVision?: boolean;
+}
+/**
+ * Result of the AgentIntakeWorkflow
+ */
+export interface AgentIntakeWorkflowResult {
+    /** The object ID that was processed */
+    objectId: string;
+    /** Whether text was extracted */
+    hasText: boolean;
+    /** Whether table of contents was generated */
+    hasTableOfContents: boolean;
+    /** The type ID assigned to the document */
+    typeId?: string;
+    /** Whether properties were extracted */
+    hasProperties: boolean;
+    /** Collection IDs the document was added to */
+    collectionIds?: string[];
+    /** Whether embeddings were generated */
+    hasEmbeddings: boolean;
+    /** Embedding kinds that were actually generated. Skipped or failed activity results are omitted. */
+    generatedEmbeddings?: SupportedEmbeddingTypes[];
+}
+/** Progress reported by a child workstream */
+export interface WorkstreamProgressInfo {
+    launch_id: string;
+    workstream_id: string;
+    phase: 'planning' | 'executing_tool' | 'synthesizing' | 'blocked' | 'done';
+    current_step?: string;
+    current_tool?: string;
+    percent?: number;
+    updated_at: number;
+}
+/** Entry returned by the ActiveWorkstreams query */
+export interface ActiveWorkstreamEntry {
+    launch_id: string;
+    workstream_id: string;
+    kind?: 'agent' | 'process';
+    interaction: string;
+    started_at: number;
+    elapsed_ms: number;
+    deadline_ms: number;
+    status: 'running' | 'canceling';
+    latest_progress?: WorkstreamProgressInfo;
+    /** Child workflow ID — use to fetch per-workstream messages */
+    child_workflow_id: string;
+    /** Child workflow run ID — use with retrieveMessages / streamMessages */
+    child_workflow_run_id?: string;
+    process_run_id?: string;
+    process_workflow_id?: string;
+    process_name?: string;
+    process_run_type?: 'programmatic' | 'supervised';
+}
+/** Recently completed workstream entry returned by the ActiveWorkstreams query */
+export interface CompletedWorkstreamEntry {
+    launch_id: string;
+    workstream_id: string;
+    kind?: 'agent' | 'process';
+    status: 'completed' | 'failed' | 'canceled' | 'timeout';
+    summary?: string;
+    error?: string;
+    duration_ms?: number;
+    started_at?: number;
+    interaction?: string;
+    last_progress?: WorkstreamProgressInfo;
+    child_workflow_id?: string;
+    child_workflow_run_id?: string;
+    process_run_id?: string;
+    process_workflow_id?: string;
+    process_name?: string;
+}
+/** Result of the ActiveWorkstreams Temporal query */
+export interface ActiveWorkstreamsQueryResult {
+    running: ActiveWorkstreamEntry[];
+    completed?: CompletedWorkstreamEntry[];
+    /** True when the workflow could not answer this optional query. */
+    unavailable?: boolean;
+}
+
+// -----------------------------------------------------------------------------
+// @vertesia/common: tool-execution.d.ts
+// -----------------------------------------------------------------------------
+/**
+ * Types for tool execution payloads shared between workflows and tool servers
+ */
+/**
+ * Endpoint configuration that can override JWT-embedded endpoints
+ */
+export interface ToolEndpointOverrides {
+    /**
+     * Studio server URL
+     */
+    studio?: string;
+    /**
+     * Store/Zeno server URL
+     */
+    store?: string;
+    /**
+     * Token server URL
+     */
+    token?: string;
+}
+/**
+ * Metadata passed with tool execution requests from workflows to tool servers
+ */
+export interface ToolExecutionMetadata {
+    /**
+     * Workflow run ID
+     */
+    run_id?: string;
+    /**
+     * Conversation storage ID for artifact operations
+     */
+    conversation_storage_id?: string;
+    /**
+     * App installation ID
+     */
+    app_install_id?: string;
+    /**
+     * App-specific settings
+     */
+    app_settings?: Record<string, unknown>;
+    /**
+     * Endpoint overrides from workflow config (takes precedence over JWT endpoints)
+     */
+    endpoints?: ToolEndpointOverrides;
+    /**
+     * Additional metadata fields
+     */
+    [key: string]: unknown;
+}
+