@vertesia/common 1.4.0-dev.20260615.051508Z → 1.4.0

package/src/data-platform.ts

@@ -79,6 +79,8 @@ export interface DataColumn {
     default?: string;
     /** Whether this is the primary key */
     primary_key?: boolean;
+    /** Whether this column should use a sequence-backed auto-increment default */
+    auto_increment?: boolean;
     /** Whether values must be unique */
     unique?: boolean;
     /** Semantic type for AI understanding */
@@ -516,6 +518,32 @@ export interface QueryPayload {
     version_id?: string;
 }
 
+/**
+ * Payload for mutating data rows with a single SQL statement.
+ */
+export interface DataStoreMutateRowsPayload {
+    /** SQL statement. Only UPDATE and DELETE statements are accepted. */
+    sql: string;
+    /** Commit message recorded on the resulting data store version. */
+    message: string;
+    /** Allow UPDATE/DELETE statements without a WHERE clause. Defaults to false. */
+    allow_full_table?: boolean;
+}
+
+/**
+ * Result from mutating rows in a data store.
+ */
+export interface DataStoreMutateRowsResult {
+    /** Resulting data store version ID */
+    version_id: string;
+    /** Tables affected by the statement */
+    affected_tables: string[];
+    /** Current row counts for affected tables after the mutation */
+    row_counts: Record<string, number>;
+    /** Statement execution time in milliseconds */
+    execution_time_ms: number;
+}
+
 /**
  * Column metadata in query results.
  */
@@ -629,6 +657,8 @@ export interface DataColumnForAI {
     nullable: boolean;
     /** Whether primary key */
     primary_key: boolean;
+    /** Whether sequence-backed auto-increment is enabled */
+    auto_increment: boolean;
     /** Example values */
     examples?: string[];
 }
@@ -821,99 +851,6 @@ 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).
  */
@@ -930,22 +867,15 @@ 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):**
- * - `dataSource` field with either SQL or Store Elasticsearch DSL
+ * - Single `query` field with SQL (use JOINs/CTEs for complex data needs)
  * - 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
@@ -955,26 +885,18 @@ 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>;
     /**
@@ -1008,17 +930,15 @@ export interface Dashboard extends DashboardItem {
 
 /**
  * Payload for creating a new dashboard.
- * Requires a data source and spec (Vega-Lite).
+ * Requires query (SQL) and spec (Vega-Lite).
  */
 export interface CreateDashboardPayload {
     /** Dashboard name (unique within store) */
     name: string;
     /** Dashboard summary */
     summary?: 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;
+    /** 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 {{param}} placeholders */
@@ -1035,9 +955,7 @@ export interface UpdateDashboardPayload {
     name?: string;
     /** Dashboard summary */
     summary?: 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. */
+    /** SQL query that returns all data for the dashboard */
     query?: string;
     /** Maximum rows to return from the query (default: 10000) */
     queryLimit?: number;
@@ -1054,8 +972,6 @@ 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) */
@@ -1119,16 +1035,6 @@ 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/environment.ts

@@ -1,4 +1,4 @@
-import type { AIModel, ProviderParams, TextFallbackOptions } from '@llumiverse/common';
+import type { AIModel, ProviderParams } from '@llumiverse/common';
 import { ProviderList, Providers } from '@llumiverse/common';
 
 // Virtual providers from studio
@@ -77,6 +77,17 @@ export interface MediatorEnvConfig {
     model_options?: TextFallbackOptions;
 }
 
+export interface TextFallbackOptions {
+    _option_id: 'text-fallback';
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    stop_sequence?: string[];
+}
+
 export interface ExecutionEnvironmentSettings {
     [key: string]: unknown;
     bucket_access_principal?: string;

package/src/index.ts

@@ -33,7 +33,7 @@ export * from './prompt.js';
 export * from './query.js';
 export * from './rate-limiter.js';
 export * from './refs.js';
-export * from './roles.js';
+export * from './roles/types.js';
 export * from './runs.js';
 export * from './secrets.js';
 export * from './skill.js';

package/src/interaction.ts

@@ -25,7 +25,8 @@ import type {
     TemplateType,
 } from './prompt.js';
 import type { ExecutionRunDocRef } from './runs.js';
-import type { ConversationState, TextArtifactReference } from './store/conversation-state.js';
+import type { AgentToolApprovalMode } from './store/agent-approval.js';
+import type { ConversationState } from './store/conversation-state.js';
 import type { AccountRef } from './user.js';
 import type { LlmCallType } from './workflow-analytics.js';
 
@@ -719,6 +720,9 @@ export {
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
     type: 'conversation';
 
+    /** Effective tool approval mode for interactive agent conversations. */
+    tool_approval_mode?: AgentToolApprovalMode;
+
     /**
      * Visibility determine if the conversation should be seen by the user only or by anyone with access to the project
      * If not specified, the default is project
@@ -764,6 +768,14 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     collection_id?: string;
 
+    /**
+     * Denylist of MCP tool-collection ids deactivated for this conversation.
+     * `undefined`/empty means all installed/connected MCP collections are active (back-compat,
+     * and new servers stay active by default). Listed collections are excluded even if connected.
+     * Can be updated mid-conversation via the MCP config signal.
+     */
+    disabled_mcp_collections?: string[];
+
     /**
      * The token threshold in thousands (K) for creating checkpoints.
      * If total tokens exceed this value, a checkpoint will be created.
@@ -954,12 +966,6 @@ 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,6 +2,7 @@ export type {
     JSONSchema,
     JSONSchemaArray,
     JSONSchemaObject,
+    JSONSchemaProperties,
     JSONSchemaType,
     JSONSchemaTypeName,
 } from '@llumiverse/common';

package/src/oauth-scopes.ts

@@ -3,10 +3,13 @@ import { Permission } from './access-control.js';
 export const OAUTH_SCOPE_OPENID = 'openid';
 export const OAUTH_SCOPE_PROFILE = 'profile';
 export const OAUTH_SCOPE_OFFLINE_ACCESS = 'offline_access';
+export const OAUTH_SCOPE_PROJECT_SWITCH = 'project_switch';
 
 export const OAUTH_STANDARD_SCOPES = [OAUTH_SCOPE_OPENID, OAUTH_SCOPE_PROFILE, OAUTH_SCOPE_OFFLINE_ACCESS] as const;
+export const OAUTH_PLATFORM_SCOPES = [OAUTH_SCOPE_PROJECT_SWITCH] as const;
 
 export type OAuthStandardScope = (typeof OAUTH_STANDARD_SCOPES)[number];
+export type OAuthPlatformScope = (typeof OAUTH_PLATFORM_SCOPES)[number];
 
 const NON_OAUTH_PERMISSION_SCOPES = new Set<Permission>([
     Permission.api_key_secret_read,
@@ -17,6 +20,7 @@ const NON_OAUTH_PERMISSION_SCOPES = new Set<Permission>([
 ]);
 const OAUTH_PERMISSION_SCOPES = Object.values(Permission).filter((scope) => !NON_OAUTH_PERMISSION_SCOPES.has(scope));
 const OAUTH_STANDARD_SCOPE_SET = new Set<string>(OAUTH_STANDARD_SCOPES);
+const OAUTH_PLATFORM_SCOPE_SET = new Set<string>(OAUTH_PLATFORM_SCOPES);
 const OAUTH_PERMISSION_SCOPE_SET = new Set<string>(OAUTH_PERMISSION_SCOPES);
 const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/i;
 const OAUTH_PROJECT_BINDING_SCOPE_PREFIX = 'project:';
@@ -29,12 +33,16 @@ export function isOAuthStandardScope(scope: string): scope is OAuthStandardScope
     return OAUTH_STANDARD_SCOPE_SET.has(scope);
 }
 
+export function isOAuthPlatformScope(scope: string): scope is OAuthPlatformScope {
+    return OAUTH_PLATFORM_SCOPE_SET.has(scope);
+}
+
 export function isOAuthPermissionScope(scope: string): scope is Permission {
     return OAUTH_PERMISSION_SCOPE_SET.has(scope);
 }
 
 export function isOAuthSupportedScope(scope: string): boolean {
-    return isOAuthStandardScope(scope) || isOAuthPermissionScope(scope);
+    return isOAuthStandardScope(scope) || isOAuthPlatformScope(scope) || isOAuthPermissionScope(scope);
 }
 
 export function isOAuthProjectBindingScope(scope: string): boolean {
@@ -60,6 +68,10 @@ export function hasOAuthOfflineAccessScope(scopes: readonly string[]): boolean {
     return scopes.includes(OAUTH_SCOPE_OFFLINE_ACCESS);
 }
 
+export function hasOAuthProjectSwitchScope(scopes: readonly string[]): boolean {
+    return scopes.includes(OAUTH_SCOPE_PROJECT_SWITCH);
+}
+
 export function getOAuthScopesWithProfileDependency(scopes: readonly string[]): string[] {
     if (!hasOAuthOpenIdScope(scopes)) {
         return scopes.filter((scope) => scope !== OAUTH_SCOPE_PROFILE);

package/src/oauth-server.ts

@@ -40,6 +40,13 @@ export interface OAuthClientData {
     status: OAuthClientStatus;
     project_binding_mode: OAuthProjectBindingMode;
     fixed_project_id?: string;
+    /**
+     * When true (the default for new clients), the client may only be authorized for projects in its
+     * owning account/organization. Set to false to allow authorization for any project the approving
+     * user can access, regardless of account — required for OAuth/MCP clients used across
+     * organizations. The owning account itself is internal and not exposed here.
+     */
+    restrict_to_owner_account?: boolean;
     metadata?: Record<string, unknown>;
     created_by?: string;
     client_secret_configured?: boolean;
@@ -119,6 +126,7 @@ export interface CreateOAuthClientPayload {
     default_scopes?: string[];
     project_binding_mode?: OAuthProjectBindingMode;
     fixed_project_id?: string;
+    restrict_to_owner_account?: boolean;
     client_secret?: string;
     metadata?: Record<string, unknown>;
 }
@@ -134,6 +142,7 @@ export interface UpdateOAuthClientPayload {
     status?: OAuthClientStatus;
     project_binding_mode?: OAuthProjectBindingMode;
     fixed_project_id?: string;
+    restrict_to_owner_account?: boolean;
     client_secret?: string;
     metadata?: Record<string, unknown>;
 }
@@ -203,6 +212,14 @@ export interface OAuthAuthorizationRequest {
     requested_project_id?: string;
     project_binding_mode: OAuthProjectBindingMode;
     fixed_project_id?: string;
+    /**
+     * When true, the consent UI must constrain project selection to {@link owner_account_id}: the
+     * client may only be authorized for projects in its owning account. False (default) lets the user
+     * authorize any project they can access. Mirrors the server-side authorization enforcement.
+     */
+    restrict_to_owner_account?: boolean;
+    /** The owning account the client is restricted to, when {@link restrict_to_owner_account} is true. */
+    owner_account_id?: string;
     status: OAuthAuthorizationRequestStatus;
     created_at: string;
     expires_at: string;

package/src/project.ts

@@ -9,7 +9,7 @@ export interface ICreateProjectPayload {
     description?: string;
     auto_config?: boolean;
 }
-export enum ProjectRoles {
+export enum SystemRoles {
     owner = 'owner', // all permissions
     admin = 'admin', // all permissions
     manager = 'manager', // all permissions but manage_account, manage_billing
@@ -30,14 +30,14 @@ export enum ProjectRoles {
 
 export function isRoleIncludedIn(role: string, includingRole: string) {
     switch (includingRole) {
-        case ProjectRoles.owner:
+        case SystemRoles.owner:
             return true; // includes billing to?
-        case ProjectRoles.admin:
-            return role !== ProjectRoles.billing && role !== ProjectRoles.owner;
-        case ProjectRoles.developer:
-            return role === ProjectRoles.developer;
-        case ProjectRoles.billing:
-            return role === ProjectRoles.billing;
+        case SystemRoles.admin:
+            return role !== SystemRoles.billing && role !== SystemRoles.owner;
+        case SystemRoles.developer:
+            return role === SystemRoles.developer;
+        case SystemRoles.billing:
+            return role === SystemRoles.billing;
         default:
             return false;
     }

package/src/roles/types.ts

@@ -0,0 +1,58 @@
+import type { Permission } from '../access-control.js';
+
+/**
+ * Pure types & constants for the role system. This file is intentionally
+ * `class`-free — it is what stays in `@vertesia/common` when the class
+ * hierarchy (`classes.ts`) eventually moves to `studio-utils`. Client SDKs
+ * depend ONLY on these types, never on the registry runtime.
+ */
+
+/**
+ * Kind of object a ContentSet's `resource_props` matches at query time. Used
+ * in `AceConditions.scope` (validated at runtime against this list) and as
+ * the prefix in JWT `content_security` keys (e.g. `collection:read`).
+ *
+ * Each scope is owned by exactly one partition. When adding a new partition
+ * (e.g. tasks), extend this list with the new scope(s) AND extend `RoleDomain`
+ * with the new domain.
+ */
+export const AbacScopes = ['document', 'collection', 'task'] as const;
+export type AbacScope = (typeof AbacScopes)[number];
+
+/**
+ * Logical grouping of roles by the service area that owns them. One domain may
+ * declare roles applicable to multiple scopes (e.g. the `content` domain owns
+ * roles applicable to both `document` and `collection` scopes). The `system`
+ * domain owns the built-in foundational roles (currently exposed as
+ * `SystemRoles`) — registered first so domain partitions cannot shadow them.
+ */
+export type RoleDomain = 'system' | 'content' | 'tasks';
+
+/**
+ * Wire shape of a role returned by the IAM `/roles` endpoint.
+ *
+ * Permissions are typed `string[]` because role names span multiple partitions
+ * (system, content, future tasks/etc.) and each partition has its own
+ * vocabulary. For the tightly-typed system-only view (with `permissions:
+ * Permission[]`) use `SystemRoleDefinition` and the `/roles/system` endpoint.
+ *
+ * NOTE: this interface is intentionally non-generic. The OpenAPI generator
+ * doesn't handle TypeScript generics cleanly in array response types and
+ * produces a degenerate `RoleDefinitionArray` schema. Keeping the wire shapes
+ * concrete avoids that. `SystemRoleDefinition` extends and narrows
+ * `permissions` to `Permission[]`.
+ */
+export interface RoleDefinition {
+    name: string;
+    permissions: string[];
+    domain: RoleDomain;
+}
+
+/**
+ * Tightly-typed view of a system-domain role: permissions are central
+ * `Permission` enum values. Returned by `client.iam.roles.listSystem()` and
+ * by the server's `/roles/system` endpoint.
+ */
+export interface SystemRoleDefinition extends RoleDefinition {
+    permissions: Permission[];
+}

package/src/store/agent-approval.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeAgentToolApprovalMode } from './agent-approval.js';
+
+describe('normalizeAgentToolApprovalMode', () => {
+    it('defaults interactive runs to full_control when no mode is supplied', () => {
+        expect(normalizeAgentToolApprovalMode(undefined, true)).toBe('full_control');
+    });
+
+    it('keeps supplied modes for interactive runs', () => {
+        expect(normalizeAgentToolApprovalMode('ask', true)).toBe('ask');
+        expect(normalizeAgentToolApprovalMode('auto_review', true)).toBe('auto_review');
+    });
+
+    it('forces non-interactive runs to full_control', () => {
+        expect(normalizeAgentToolApprovalMode('ask', false)).toBe('full_control');
+        expect(normalizeAgentToolApprovalMode('auto_review', undefined)).toBe('full_control');
+    });
+});

package/src/store/agent-approval.ts

@@ -0,0 +1,33 @@
+import type { ToolResult } from '../interaction.js';
+
+export const AgentToolApprovalModes = ['ask', 'auto_review', 'full_control'] as const;
+
+export type AgentToolApprovalMode = (typeof AgentToolApprovalModes)[number];
+
+export interface ToolApprovalGrant {
+    key: string;
+    tool_name: string;
+    target?: string;
+    granted_at: string;
+}
+
+export interface PendingToolApprovalResults {
+    results: ToolResult[];
+    reason: 'denied' | 'denied_with_feedback' | 'timeout' | 'reviewer_denied';
+    message: string;
+    created_at: string;
+}
+
+export function normalizeAgentToolApprovalMode(
+    mode: AgentToolApprovalMode | undefined,
+    interactive: boolean | undefined,
+): AgentToolApprovalMode {
+    if (interactive !== true) {
+        return 'full_control';
+    }
+    return mode ?? 'full_control';
+}
+
+export function isAgentToolApprovalMode(value: unknown): value is AgentToolApprovalMode {
+    return typeof value === 'string' && (AgentToolApprovalModes as readonly string[]).includes(value);
+}

package/src/store/agent-run.ts

@@ -21,8 +21,9 @@ import type {
     RunSource,
 } from '../interaction.js';
 import type { AgentEvent } from '../workflow-analytics.js';
+import type { AgentToolApprovalMode } from './agent-approval.js';
 import type { ProcessDefinitionBody, ProcessState } from './process.js';
-import type { UserInputSignal } from './signals.js';
+import type { StopSignal, UserInputSignal } from './signals.js';
 import type { ContentObjectTypeRef } from './store.js';
 import type {
     AgentMessage,
@@ -158,12 +159,22 @@ export interface AgentRunBase<TData = Record<string, unknown>, TProperties = Rec
     /** Whether the agent accepts user input */
     interactive?: boolean;
 
+    /** How side-effecting tool actions are approved for interactive runs. */
+    tool_approval_mode?: AgentToolApprovalMode;
+
     /** Tools configured for this run (+/- syntax supported) */
     tool_names?: string[];
 
     /** Scoped collection (if any) */
     collection_id?: string;
 
+    /**
+     * Denylist of MCP tool-collection ids deactivated for this run.
+     * `undefined`/empty means all installed/connected MCP collections are active (back-compat,
+     * and new servers stay active by default). Listed collections are excluded even if connected.
+     */
+    disabled_mcp_collections?: string[];
+
     /** Content type linked to this run — defines the schema for `properties` */
     content_type?: ContentObjectTypeRef;
 
@@ -427,10 +438,15 @@ 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;
+    /**
+     * MCP collections deactivated for this run. Persisted when the user toggles activation
+     * mid-conversation so a page reload reflects the live state. An empty array clears the denylist.
+     */
+    disabled_mcp_collections?: string[];
+    /** Tool approval mode persisted for interactive agent runs. */
+    tool_approval_mode?: AgentToolApprovalMode;
     /** Archive state fields (set by the archive workflow) */
     archive_state?: AgentRunArchiveState;
     archived_at?: string;
@@ -445,6 +461,7 @@ export interface UpdateAgentRunStatusPayload {
  */
 export type SignalAgentPayload =
     | UserInputSignal
+    | StopSignal
     | ConversationFileRef
     | ConversationFileRemovedRef
     | Record<string, unknown>;