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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.4.0-dev.20260615.051508Z",
+  "version": "1.4.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./lib/index.js",
@@ -20,14 +20,14 @@
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
-    "rollup": "^4.61.0",
+    "rollup": "^4.61.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.9",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@llumiverse/common": "1.3.0"
+    "@llumiverse/common": "1.4.0"
   },
   "repository": {
     "type": "git",
@@ -46,7 +46,8 @@
     "lint": "biome lint src",
     "test": "vitest run",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
-    "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && tsc && pnpm exec rollup -c",
-    "clean": "rm -rf ./node_modules ./lib ./tsconfig.tsbuildinfo"
+    "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",
+    "build": "pnpm run clean:lib && tsc -p tsconfig.json && pnpm exec rollup -c",
+    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
   }
 }

package/src/access-control.ts

@@ -4,7 +4,7 @@
  * Access control interfaces
  */
 
-import type { ProjectRoles } from './project.js';
+import type { SystemRoles } from './project.js';
 
 export enum Permission {
     int_read = 'interaction:read',
@@ -112,7 +112,7 @@ export interface AceConditions {
 }
 
 export interface AccessControlEntry {
-    role: ProjectRoles;
+    role: SystemRoles;
     resource_type: AccessControlResourceType;
     resource: string; //objectId
     principal_type: AccessControlPrincipalType;
@@ -134,10 +134,9 @@ export interface ACECreatePayload extends Omit<AccessControlEntry, 'created_at'
 
 export interface ACEUpdatePayload extends Partial<ACECreatePayload> {}
 
-export interface RoleDefinition {
-    name: ProjectRoles;
-    permissions: Permission[];
-}
+// RoleDefinition + SystemRoleDefinition now live in `./roles/types.js` to
+// avoid a circular import with `RoleDomain`. They remain re-exported via
+// the package's index.ts so consumers see no path change.
 
 // ============================================================================
 // BLP Security Levels

package/src/apikey.ts

@@ -1,6 +1,6 @@
 import type { PropertyConditions } from './access-control.js';
 import type { UserGroupRef } from './group.js';
-import type { ProjectRef, ProjectRoles } from './project.js';
+import type { ProjectRef, SystemRoles } from './project.js';
 import type { AccountRef } from './user.js';
 
 /**
@@ -21,7 +21,7 @@ export interface ApiKey {
     id: string;
     name: string;
     type: ApiKeyTypes;
-    role: ProjectRoles;
+    role: SystemRoles;
     maskedValue?: string; //masked value
     can_retrieve_value?: boolean;
     account: string; // the account id
@@ -71,11 +71,11 @@ export interface AuthTokenPayload {
     type: PrincipalType;
     account: AccountRef;
 
-    account_roles: ProjectRoles[];
+    account_roles: SystemRoles[];
     accounts: AccountRef[];
 
     project?: ProjectRef;
-    project_roles?: ProjectRoles[];
+    project_roles?: SystemRoles[];
 
     /**
      * The app names enabled for this token. Defaults to an empty array if no apps are enabled.
@@ -121,7 +121,6 @@ export interface AuthTokenPayload {
               studio: string;
               store: string;
               token?: string;
-              git?: string;
           };
 
     iss: string; //issuer

package/src/apps.ts

@@ -1,5 +1,4 @@
 import type { JSONObject, JSONSchema, ToolDefinition } from '@llumiverse/common';
-import type { AppDashboardDefinition } from './data-platform.js';
 import type { CatalogInteractionRef } from './interaction.js';
 import type { DSLActivityOptions, InCodeProcessDefinition, InCodeTypeDefinition } from './store/index.js';
 
@@ -303,6 +302,16 @@ export interface MCPToolAnnotations {
     openWorldHint?: boolean;
 }
 
+/**
+ * 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 = 'read_only' | 'side_effecting' | 'control' | 'requires_confirmation';
+
 /**
  * Tool definition with optional activation control for agent exposure.
  */
@@ -334,15 +343,10 @@ export interface AgentToolDefinition extends ToolDefinition {
      */
     annotations?: MCPToolAnnotations;
     /**
-     * When true, agents must obtain explicit user confirmation via `ask_user`
-     * (Yes/No) before invoking this tool. If the user answers No, the tool
-     * must not run and should return an error indicating the user declined.
-     *
-     * Stronger than `annotations.destructiveHint` (which is only a hint) —
-     * this is a hard contract the agent is expected to honor. Set on tools
-     * that perform irreversible or destructive actions (e.g. delete_*).
+     * Approval classification used by interactive agent approval modes.
+     * Use `requires_confirmation` for actions that must prompt even in full-control mode.
      */
-    requires_user_confirmation?: boolean;
+    approval_class?: AgentToolApprovalClass;
 }
 
 /**
@@ -372,183 +376,9 @@ export interface RemoteActivityDefinition {
     options?: DSLActivityOptions;
 }
 
-export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates' | 'dashboards';
+export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates';
 export type AppAvailableIn = 'app_portal' | 'composite_app';
 
-export type AppVersionKind = 'design' | 'preview' | 'published';
-export type AppVersionState = 'ready' | 'failed' | 'expired';
-export type AppVersionTarget = 'static' | 'service';
-export type AppVersionGitRefType = 'branch' | 'tag' | 'commit' | 'detached';
-export type AppBuildIntent = 'preview' | 'publish';
-export type AppBuildTrigger = 'ui' | 'git_push' | 'agent' | 'api';
-
-export interface AppVersionStorage {
-    tenant_id?: string;
-    app_prefix?: string;
-    artifacts_prefix?: string;
-    source_archive?: string;
-    source_git?: AppVersionGitSource;
-    build_prefix?: string;
-    manifest_path?: string;
-    service_archive?: string;
-    live_metadata_path?: string;
-}
-
-export interface AppVersionGitSource {
-    url?: string;
-    remote?: string;
-    /**
-     * The source ref that should be used to reproduce this version. For immutable
-     * app versions this is normally the tag created during preview/publish.
-     */
-    ref?: string;
-    ref_type?: AppVersionGitRefType;
-    branch?: string;
-    tag?: string;
-    commit?: string;
-    dirty?: boolean;
-    pushed?: boolean;
-    push_warning?: string;
-}
-
-export interface AppVersionUrls {
-    live_url?: string;
-    app_url?: string;
-    plugin_url?: string;
-    package_url?: string;
-    internal_preview_url?: string;
-}
-
-export interface AppVersionRecord {
-    id: string;
-    account: string;
-    project: string;
-    app?: string;
-    app_id: string;
-    app_name: string;
-    version_id: string;
-    kind: AppVersionKind;
-    state: AppVersionState;
-    active?: boolean;
-    target?: AppVersionTarget;
-    agent_run_id?: string;
-    sandbox_id?: string;
-    title?: string;
-    description?: string;
-    storage?: AppVersionStorage;
-    urls?: AppVersionUrls;
-    manifest?: Record<string, unknown>;
-    files?: string[];
-    file_count?: number;
-    source_file_count?: number;
-    screenshot_artifact?: string;
-    checks?: string[];
-    created_by?: string;
-    created_at: string;
-    updated_at: string;
-    published_at?: string;
-    checked_at?: string;
-    expires_at?: string;
-}
-
-export interface UpsertAppVersionRequest {
-    app?: string;
-    app_id: string;
-    app_name?: string;
-    version_id: string;
-    kind: AppVersionKind;
-    state?: AppVersionState;
-    active?: boolean;
-    target?: AppVersionTarget;
-    agent_run_id?: string;
-    sandbox_id?: string;
-    title?: string;
-    description?: string;
-    storage?: AppVersionStorage;
-    urls?: AppVersionUrls;
-    manifest?: Record<string, unknown>;
-    files?: string[];
-    file_count?: number;
-    source_file_count?: number;
-    screenshot_artifact?: string;
-    checks?: string[];
-    published_at?: string;
-    checked_at?: string;
-    expires_at?: string;
-}
-
-export interface AppVersionListQuery {
-    app_id?: string;
-    kind?: AppVersionKind;
-    include_expired?: boolean;
-    limit?: number;
-}
-
-export interface ActivateAppVersionResponse {
-    version: AppVersionRecord;
-    app?: AppManifest;
-}
-
-export interface StartAppBuildRequest {
-    /**
-     * Source branch, tag, or commit to build. When omitted, the app source
-     * configuration chooses the dev branch for previews and production branch
-     * for publishes.
-     */
-    source_ref?: string;
-    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
-    intent?: AppBuildIntent;
-    trigger?: AppBuildTrigger;
-    target?: AppVersionTarget;
-    activate?: boolean;
-    title?: string;
-    description?: string;
-}
-
-export interface StartAppBuildResponse {
-    workflow_id: string;
-    run_id: string;
-    app_id: string;
-    intent: AppBuildIntent;
-    source_ref?: string;
-    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
-}
-
-export interface AppBuildWorkflowInput extends StartAppBuildRequest {
-    app_id: string;
-    app_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, 'preview' | 'published'>;
-    state: AppVersionState;
-    source_git?: AppVersionGitSource;
-    urls?: AppVersionUrls;
-    file_count?: number;
-}
-
-export type AppBuildProgressStatus = 'queued' | 'resolving' | 'building' | 'completed' | 'failed';
-
-export interface AppBuildProgress {
-    status: AppBuildProgressStatus;
-    step: string;
-    app_id?: string;
-    version_id?: string;
-    intent?: AppBuildIntent;
-    source_ref?: string;
-    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
-    source_commit?: string;
-    file_count?: number;
-    app_url?: string;
-    error?: string;
-    updated_at: string;
-}
-
 /**
  * Access control policy for an app installation.
  * Declares which access surfaces are gated by per-user ACEs.
@@ -609,18 +439,6 @@ export interface AppManifestData {
      */
     color?: string;
 
-    /**
-     * Optional preview screenshot for the app-management UI, captured by the builder during a
-     * build/QA run. Resolved client-side from the owning agent run's artifact storage, so it
-     * carries both the run id and the artifact path.
-     */
-    preview_screenshot?: {
-        /** Agent run id whose artifact storage holds the screenshot. */
-        agent_run_id: string;
-        /** Artifact path within that storage, e.g. "preview-checks/app-preview-<ts>.png". */
-        artifact: string;
-    };
-
     status: 'beta' | 'stable' | 'deprecated';
 
     /**
@@ -677,8 +495,6 @@ export interface AppManifestData {
      * - interactions
      * - types
      * - processes
-     * - templates
-     * - dashboards
      * - settings
      * - all (the default if no scope is provided)
      *  You can also use comma-separated values to combine scopes (e.g. "ui,tools").
@@ -701,13 +517,6 @@ export interface AppManifestData {
      */
     version?: string;
 
-    /**
-     * Source repository configuration for apps generated and maintained through
-     * AppGen. Branches are mutable deployment lanes; immutable app versions
-     * record their exact source tag/commit in AppVersionRecord.storage.source_git.
-     */
-    source?: AppSourceConfig;
-
     /**
      * Free-form tags used for classification and filtering. Platform apps
      * carry `"system"` so UIs can skip install/uninstall/manage-permission
@@ -723,18 +532,6 @@ export interface AppManifestData {
     access_control?: AppAccessControl;
 }
 
-export interface AppGitSourceConfig {
-    url?: string;
-    default_branch?: string;
-    production_branch?: string;
-    development_branch?: string;
-}
-
-export interface AppSourceConfig {
-    kind: 'git';
-    git?: AppGitSourceConfig;
-}
-
 /**
  * Reserved deployment environment names that may never be used as endpoint
  * override keys. Reserving them prevents a manifest from hijacking auto-resolution
@@ -766,8 +563,6 @@ export interface Endpoints {
     token?: string;
     /** The browser-facing Studio UI (composable-ui) base URL */
     ui?: string;
-    /** The Smart HTTP app source git server base URL */
-    git?: string;
 }
 
 /**
@@ -868,7 +663,6 @@ export type AppPackageScope =
     | 'types'
     | 'processes'
     | 'templates'
-    | 'dashboards'
     | 'settings'
     | 'widgets'
     | 'activities'
@@ -912,11 +706,6 @@ export interface AppPackage {
      */
     templates?: RenderingTemplateDefinitionRef[];
 
-    /**
-     * Dashboards provided by the app.
-     */
-    dashboards?: AppDashboardDefinition[];
-
     /**
      * Widgets provided by the app.
      */
@@ -935,61 +724,6 @@ export interface AppPackage {
     settings_schema?: JSONSchema;
 }
 
-/**
- * A single diagnostic produced while inspecting an app's registration state.
- */
-export interface AppInspectionIssue {
-    severity: 'error' | 'warning';
-    /** The capability this issue relates to, when applicable (e.g. 'types'). */
-    capability?: AppPackageScope;
-    /** Stable machine code, e.g. 'capability_declared_but_empty', 'endpoint_unreachable', 'not_installed'. */
-    code: string;
-    /** Human-readable explanation, safe to surface to the model and the UI. */
-    message: string;
-}
-
-/**
- * Per-capability report of what an app's published package actually exposes,
- * compared against what its manifest declares.
- */
-export interface AppInspectionCapabilityReport {
-    capability: AppPackageScope;
-    /** True when the manifest's `capabilities` array declares this capability. */
-    declared: boolean;
-    /** The local ids the published package actually serves for this capability. */
-    exposed_ids: string[];
-    /** Convenience count of `exposed_ids`. */
-    exposed_count: number;
-}
-
-/**
- * Result of inspecting an app's registration: the resolved manifest state, what
- * the published 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 interface AppInspectionResult {
-    app_id: string;
-    name: string;
-    version?: string;
-    /** The resolved package endpoint for the current environment, if any. */
-    endpoint?: string;
-    /** True when the package endpoint responded to the capability probe. */
-    endpoint_reachable: boolean;
-    /** True when the app is installed in the current project. */
-    installed: boolean;
-    access_control?: string;
-    /** The capabilities declared on the manifest. */
-    capabilities: AppPackageScope[];
-    /** What the published package exposes, per capability. */
-    package: AppInspectionCapabilityReport[];
-    /** Diagnostics — errors and warnings about the registration state. */
-    issues: AppInspectionIssue[];
-    /** Populated when the package probe itself failed (endpoint error/unreachable). */
-    probe_error?: string;
-}
-
 export interface AppWidgetInfo {
     collection: string;
     skill: string;
@@ -1397,7 +1131,7 @@ export interface CompositeAppNavItemPermissions {
     groupsAllowed?: string[];
     /** User IDs who can see this item. */
     usersAllowed?: string[];
-    /** ProjectRoles values (e.g. "developer", "manager") whose holders can see this item. */
+    /** SystemRoles values (e.g. "developer", "manager") whose holders can see this item. */
     rolesAllowed?: string[];
 }
 
@@ -1505,20 +1239,3 @@ export interface ValidateUrlRequest {
 export interface ValidateUrlResponse {
     valid: true;
 }
-
-/**
- * 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[];
-}

package/src/ask-user.ts

@@ -14,7 +14,27 @@ export interface AskUserOption {
     description?: string;
 }
 
-/** UX configuration for ask_user messages */
+/** Identifies an MCP server the user is asked to connect to (request_mcp_connection). */
+export interface McpConnectUxConfig {
+    /** The app installation id owning the collection (used for the OAuth flow). */
+    app_install_id: string;
+    /** The MCP tool-collection id. */
+    collection_id: string;
+    /** Human-readable server name shown in the prompt. */
+    name: string;
+}
+
+/** Optional free-form response rendered alongside predefined options. */
+export interface AskUserFreeResponseConfig {
+    /** Placeholder text for the input. */
+    placeholder?: string;
+    /** Label for the submit button. */
+    submit_label?: string;
+    /** Extra metadata sent with the user input signal when submitted. */
+    metadata?: Record<string, unknown>;
+}
+
+/** UX configuration for ask_user / request_mcp_connection messages */
 export interface AskUserUxConfig {
     /** Predefined options for the user to select from */
     options?: AskUserOption[];
@@ -22,6 +42,16 @@ export interface AskUserUxConfig {
     variant?: 'default' | 'warning' | 'info' | 'success';
     /** Allow selecting multiple options (renders checkboxes instead of buttons) */
     multiSelect?: boolean;
+    /**
+     * Render a free-form response input. When options are also present, this is
+     * treated as an alternate response path.
+     */
+    free_response?: AskUserFreeResponseConfig;
+    /**
+     * Renders an MCP "Connect" button instead of plain options. Set by the
+     * request_mcp_connection tool when the agent needs the user to connect a server.
+     */
+    mcp_connect?: McpConnectUxConfig;
 }
 
 /** Message details structure for REQUEST_INPUT messages with UX config */