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

package/src/data-platform.ts

@@ -851,6 +851,99 @@ export interface DashboardQueryParameters {
     defaults: Record<string, string>;
 }
 
+/**
+ * Elasticsearch DSL supported by dashboard data sources.
+ * Queries execute through Vertesia Store, so project/security filtering remains server-side.
+ */
+export interface DashboardElasticsearchDsl {
+    query?: Record<string, unknown>;
+    aggs?: Record<string, unknown>;
+    size?: number;
+    from?: number;
+    sort?: Array<Record<string, unknown>>;
+}
+
+/**
+ * How an Elasticsearch DSL result should be converted into Vega rows.
+ */
+export type DashboardElasticsearchResultMapping =
+    | {
+          type: 'hits';
+      }
+    | {
+          type: 'aggregation_buckets';
+          /** Dot path under `aggregations` that contains a `buckets` array. */
+          path: string;
+          /** Output field name for bucket key. Defaults to `key`. */
+          keyField?: string;
+          /** Output field name for doc count. Defaults to `doc_count`. */
+          countField?: string;
+      };
+
+/**
+ * Dashboard data source backed by a Data Platform SQL query.
+ */
+export interface DashboardSqlDataSource {
+    kind: 'data_sql';
+    /** SQL query that returns all rows for the dashboard. */
+    query: string;
+    /** Maximum rows to return from the query. */
+    queryLimit?: number;
+    /** Default values for SQL {{param}} placeholders. */
+    queryParameters?: Record<string, string>;
+}
+
+/**
+ * Dashboard data source backed by Vertesia Store Elasticsearch DSL.
+ */
+export interface DashboardStoreElasticsearchDataSource {
+    kind: 'store_es_dsl';
+    /** Elasticsearch DSL query executed through the secured Store query API. */
+    dsl: DashboardElasticsearchDsl;
+    /** Result mapping. Defaults to `hits`. */
+    result?: DashboardElasticsearchResultMapping;
+}
+
+/**
+ * Data source for a Vega dashboard.
+ */
+export type DashboardDataSource = DashboardSqlDataSource | DashboardStoreElasticsearchDataSource;
+
+/**
+ * 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 interface AppDashboardDefinition {
+    /** Local app dashboard ID. */
+    id: string;
+    /** Machine-friendly dashboard name. Defaults to `id`. */
+    name?: string;
+    /** Display title. Defaults to `name` or `id`. */
+    title?: string;
+    /** User-facing description. */
+    description?: string;
+    /** Tags for discovery and filtering. */
+    tags?: string[];
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query shortcut for app dashboards backed by data stores. */
+    query?: string;
+    /** Maximum SQL rows to return. */
+    queryLimit?: number;
+    /** Default values for SQL {{param}} placeholders. */
+    queryParameters?: Record<string, string>;
+    /** Complete Vega-Lite specification for the dashboard. */
+    spec?: Record<string, unknown>;
+    /** Legacy named SQL queries. */
+    queries?: DashboardQuery[];
+    /** Legacy panel definitions. */
+    panels?: DashboardPanel[];
+    /** Legacy dashboard layout. */
+    layout?: DashboardLayout;
+}
+
 /**
  * Summary view of a dashboard (for listings).
  */
@@ -867,15 +960,22 @@ export interface DashboardItem extends BaseObject {
     last_rendered_at?: string;
     /** Tags for organization */
     tags: string[];
+    /** Source of the dashboard definition. Defaults to stored dashboards. */
+    source?: 'stored' | 'app';
+    /** App name when `source` is `app`. */
+    app_name?: string;
+    /** App dashboards are read-only until cloned into a stored dashboard. */
+    readonly?: boolean;
 }
 
 /**
  * Full dashboard with SQL query and Vega-Lite specification.
  *
  * **New architecture (v2):**
- * - Single `query` field with SQL (use JOINs/CTEs for complex data needs)
+ * - `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
@@ -885,18 +985,26 @@ export interface DashboardItem extends BaseObject {
  */
 export interface Dashboard extends DashboardItem {
     // ============= New architecture (v2) =============
+    /**
+     * Data source used to populate Vega `data.values`.
+     * When omitted, top-level `query` is treated as a SQL data source for backwards compatibility.
+     */
+    dataSource?: DashboardDataSource;
     /**
      * SQL query that returns all data for the dashboard.
      * Use JOINs, CTEs, or UNION ALL to combine data from multiple tables.
      * Can include {{param_name}} placeholders for dynamic values.
+     * @deprecated Use `dataSource: { kind: 'data_sql', query }` instead.
      */
     query?: string;
     /**
      * Maximum rows to return from the query (default: 10000).
+     * @deprecated Use `dataSource.queryLimit` instead.
      */
     queryLimit?: number;
     /**
      * Default values for SQL parameters.
+     * @deprecated Use `dataSource.queryParameters` instead.
      */
     queryParameters?: Record<string, string>;
     /**
@@ -930,15 +1038,17 @@ export interface Dashboard extends DashboardItem {
 
 /**
  * Payload for creating a new dashboard.
- * Requires query (SQL) and spec (Vega-Lite).
+ * Requires a data source and spec (Vega-Lite).
  */
 export interface CreateDashboardPayload {
     /** Dashboard name (unique within store) */
     name: string;
     /** Dashboard summary */
     summary?: string;
-    /** SQL query that returns all data for the dashboard */
-    query: string;
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard. Deprecated shortcut for a SQL data source. */
+    query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
     /** Default values for SQL {{param}} placeholders */
@@ -955,7 +1065,9 @@ export interface UpdateDashboardPayload {
     name?: string;
     /** Dashboard summary */
     summary?: string;
-    /** SQL query that returns all data for the dashboard */
+    /** Data source used to populate Vega `data.values`. */
+    dataSource?: DashboardDataSource;
+    /** SQL query that returns all data for the dashboard. Deprecated shortcut for a SQL data source. */
     query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
@@ -972,6 +1084,8 @@ export interface UpdateDashboardPayload {
  */
 export interface PreviewDashboardPayload {
     // ============= New architecture (v2) =============
+    /** 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) */
@@ -1035,6 +1149,16 @@ export interface DashboardVersion {
     version_number: number;
     /** Commit message describing the change */
     message: string;
+    /** Snapshot of v2 data source at this version */
+    dataSource?: DashboardDataSource;
+    /** Snapshot of v2 SQL query at this version */
+    query?: string;
+    /** Snapshot of v2 query limit at this version */
+    queryLimit?: number;
+    /** Snapshot of v2 query parameters at this version */
+    queryParameters?: Record<string, string>;
+    /** Snapshot of v2 Vega-Lite spec at this version */
+    spec?: Record<string, unknown>;
     /** Snapshot of queries at this version */
     queries: DashboardQuery[];
     /** Snapshot of panels at this version */

package/src/interaction.ts

@@ -26,7 +26,7 @@ import type {
 } from './prompt.js';
 import type { ExecutionRunDocRef } from './runs.js';
 import type { AgentToolApprovalMode } from './store/agent-approval.js';
-import type { ConversationState } from './store/conversation-state.js';
+import type { ConversationState, TextArtifactReference } from './store/conversation-state.js';
 import type { AccountRef } from './user.js';
 import type { LlmCallType } from './workflow-analytics.js';
 
@@ -895,6 +895,8 @@ export interface ResultStorageOptions {
     // - Otherwise → text/markdown or text/plain
 }
 
+export type AsyncCompletionMode = 'conversation_state' | 'text';
+
 /**
  * Streaming-specific options (only needed when stream=true)
  */
@@ -950,6 +952,13 @@ export interface AsyncCompletionOptions {
      * after inference completes (before completing the Temporal activity).
      */
     result_storage?: ResultStorageOptions;
+    /**
+     * Controls the value used to complete the Temporal activity.
+     * Defaults to `conversation_state` for agent resume/continuation calls.
+     * Use `text` for one-shot helper calls, such as checkpoint summaries,
+     * that need the model's text result instead of merged conversation state.
+     */
+    completion_mode?: AsyncCompletionMode;
 }
 
 interface ResumeConversationPayload {
@@ -966,6 +975,12 @@ interface ResumeConversationPayload {
 
 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[];
     /**

package/src/json-schema.ts

@@ -2,7 +2,6 @@ export type {
     JSONSchema,
     JSONSchemaArray,
     JSONSchemaObject,
-    JSONSchemaProperties,
     JSONSchemaType,
     JSONSchemaTypeName,
 } from '@llumiverse/common';

package/src/platform-event.ts

@@ -489,6 +489,59 @@ export interface ListEventDeliveriesResponse {
     deliveries: EventDeliverySummary[];
 }
 
+export interface StreamEventDeliveriesQuery {
+    limit?: number;
+    event_id?: string;
+    resource_id?: string;
+    resource_type?: string[];
+    event_category?: EventCategory[];
+    action?: string[];
+    outbox_status?: EventOutboxStatus[];
+    since_event_id?: string;
+    since_created_at?: string;
+    include_event?: boolean;
+    poll_interval_ms?: number;
+}
+
+export interface EventDeliveryStreamItem {
+    cursor: string;
+    delivery: EventDeliverySummary;
+    event?: PlatformEvent;
+}
+
+export interface EventDeliveryStreamSnapshot {
+    type: 'snapshot';
+    emitted_at: string;
+    cursor?: string;
+    deliveries: EventDeliveryStreamItem[];
+}
+
+export interface EventDeliveryStreamUpdate {
+    type: 'event';
+    emitted_at: string;
+    cursor: string;
+    item: EventDeliveryStreamItem;
+}
+
+export interface EventDeliveryStreamHeartbeat {
+    type: 'heartbeat';
+    emitted_at: string;
+    cursor?: string;
+}
+
+export interface EventDeliveryStreamError {
+    type: 'error';
+    emitted_at: string;
+    cursor?: string;
+    error: string;
+}
+
+export type EventDeliveryStreamEnvelope =
+    | EventDeliveryStreamSnapshot
+    | EventDeliveryStreamUpdate
+    | EventDeliveryStreamHeartbeat
+    | EventDeliveryStreamError;
+
 export type EventSubscriptionSortField = 'name' | 'scope' | 'target_type' | 'enabled' | 'updated_at';
 
 export interface ListEventSubscriptionsQuery {

package/src/roles.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'vitest';
+import { SystemRoles } from './project.js';
+import { AbacScopes } from './roles/types.js';
+
+describe('shared role vocabulary', () => {
+    test('exports all system roles', () => {
+        expect(Object.values(SystemRoles).sort()).toEqual(
+            [
+                'admin',
+                'app_member',
+                'application',
+                'auditor',
+                'automation',
+                'billing',
+                'consumer',
+                'content_processor',
+                'content_superadmin',
+                'developer',
+                'executor',
+                'manager',
+                'member',
+                'owner',
+                'reader',
+                'support',
+            ].sort(),
+        );
+    });
+
+    test('exports ABAC scopes used by role wire types', () => {
+        expect(AbacScopes).toEqual(['document', 'collection', 'task']);
+    });
+});

package/src/store/agent-run.ts

@@ -453,6 +453,8 @@ export interface UpdateAgentRunStatusPayload {
     title?: string;
     topic?: string;
     lessons_learned?: string[];
+    /** Shallow-merged into the run's existing properties. */
+    properties?: Record<string, unknown>;
     /** ES-only: conversation content text (not stored in MongoDB) */
     content?: string;
     /**

package/src/store/conversation-state.ts

@@ -14,6 +14,34 @@ export interface ToolReference {
     stored_at: string;
 }
 
+/** Reference to text content externalized to agent artifact storage. */
+export interface TextArtifactReference {
+    storage_id: string;
+    artifact_path: string;
+    display_ref: string;
+    sha256: string;
+    size_bytes: number;
+    content_type: string;
+}
+
+/**
+ * Sidecar metadata for generated tool input fields that were stored outside
+ * model-visible tool_input. Keyed by tool_use.id on ConversationState.
+ */
+export interface ExternalizedToolInputRef {
+    tool_name: string;
+    input_path: ['content'];
+    ref: TextArtifactReference;
+}
+
+export interface ExternalizedToolInputRefs {
+    [toolUseId: string]: ExternalizedToolInputRef[];
+}
+
+export function toolInputRefsArtifactPath(storageId: string): string {
+    return `agents/${storageId}/tool-input-refs.json`;
+}
+
 /**
  * Conversation state passed between workflow activities.
  * Contains all context needed to continue a multi-turn agent conversation.
@@ -51,6 +79,15 @@ export interface ConversationState {
     /** Compact, redacted latest user intent for reviewer-style system interactions. */
     latest_user_message?: string;
 
+    /**
+     * Transport sidecar for large generated tool input fields.
+     *
+     * These refs are intentionally kept out of tool_use.tool_input so they are
+     * not shown to the model. Tool execution hydrates them from artifact storage
+     * immediately before activity validation.
+     */
+    tool_input_refs?: ExternalizedToolInputRefs;
+
     /**
      * The output of the this conversation step
      */
@@ -204,6 +241,16 @@ export interface ConversationState {
      * to consolidate all artifacts under the parent agent run.
      */
     launch_id?: string;
+
+    /**
+     * The app version this run is pinned to (candidate testing), derived from the `@version` on the
+     * started interaction ref / the `x-vertesia-app-version` header at start. Persisted on the state
+     * so it survives resume, and applied to the activity client (`withAppVersion`) so every app-owned
+     * ref the run resolves — interactions, types, processes, tools — targets this version instead of
+     * the current/promoted one. Undefined → current/promoted. Resolution-time only; never a stored
+     * capability-ref version.
+     */
+    app_version?: string;
 }
 
 /**