@crewx/sdk 0.9.0-rc.103 → 0.9.0-rc.105

package/dist/lifecycle/task-stop.d.ts

@@ -1,4 +1,4 @@
-import type { FinalizeTaskForHostShutdownOptions, FinalizeTaskForHostShutdownOutcome, FinalizeTaskStopOptions, TaskRepository, TaskRow, TaskStopRequestResult } from '../repository/task.repository.js';
+import type { FinalizeTaskForHostShutdownOptions, FinalizeTaskForHostShutdownOutcome, FinalizeTaskStopOptions, TaskRepository, TaskRow, TaskStopOrigin, TaskStopRequestResult } from '../repository/task.repository.js';
 import { checkProcessOwnershipAsync as defaultCheckProcessOwnershipAsync, terminateProcessTree as defaultTerminateProcessTree, type ProcessControlOptions } from '../process/process-control.js';
 export declare const TASK_STOP_DEFAULT_GRACE_MS = 5000;
 export declare const TASK_STOP_DEFAULT_POLL_MS = 250;
@@ -17,6 +17,9 @@ export interface StopTaskProcessControl {
     terminateProcessTree?: typeof defaultTerminateProcessTree;
 }
 export interface StopTaskOptions {
+    origin?: TaskStopOrigin;
+    callerPid?: number;
+    callerTaskId?: string;
     graceMs?: number;
     pollMs?: number;
     platform?: NodeJS.Platform;

package/dist/mcp-app/discovery.d.ts

@@ -0,0 +1,105 @@
+import type { JsonObject, UiDefinition } from '../ui-instance/types.js';
+import type { UiPluginHandlerMetadata, UiPluginManifestV2, UiPluginNormalizedManifestV2 } from '../ui-plugin/types.js';
+import { AppDiscoveryFsError, NodeAppDiscoveryFs, NodeAppDiscoveryFsAdapter, defaultAppDiscoveryFs, defaultNodeAppDiscoveryFs, type AppDiscoveryFsErrorCode } from './node-app-discovery-fs.js';
+import type { McpAppRegistry } from './types.js';
+export type WorkspaceAppSource = 'apps' | 'skills';
+export type WorkspaceAppDiagnosticCode = 'MANIFEST_INVALID' | 'ENTRY_INVALID' | 'INITIAL_STATE_INVALID' | 'DUPLICATE_ID' | 'RESERVED_ID' | 'PATH_ESCAPED' | 'LIMIT_EXCEEDED' | 'EXEC_DENIED';
+export interface WorkspaceAppDiagnostic {
+    readonly code: WorkspaceAppDiagnosticCode;
+    readonly pluginId?: string;
+    readonly source: WorkspaceAppSource;
+    readonly relativePath: string;
+}
+export type McpAppDiscoveryDiagnostic = WorkspaceAppDiagnostic;
+export type AppDiscoveryDiagnostic = WorkspaceAppDiagnostic;
+export type AppDiscoveryDirectoryEntryKind = 'file' | 'directory' | 'symlink' | 'other';
+export interface AppDiscoveryDirectoryEntry {
+    readonly name: string;
+    readonly kind: AppDiscoveryDirectoryEntryKind;
+}
+export type AppDiscoveryDirectoryListing = readonly AppDiscoveryDirectoryEntry[] | readonly string[];
+export type AppDiscoveryBytes = Uint8Array | ArrayBuffer | readonly number[];
+export type AppDiscoveryMaybePromise<T> = T | PromiseLike<T>;
+export interface AppDiscoveryFileSystem {
+    readonly listDirectory?: (root: string, relativePath: string) => AppDiscoveryMaybePromise<AppDiscoveryDirectoryListing>;
+    readonly readDirectory?: (root: string, relativePath: string) => AppDiscoveryMaybePromise<AppDiscoveryDirectoryListing>;
+    readonly readdir?: (root: string, relativePath: string) => AppDiscoveryMaybePromise<AppDiscoveryDirectoryListing>;
+    readonly readVerifiedFile?: (root: string, relativePath: string, byteLimit: number) => AppDiscoveryMaybePromise<AppDiscoveryBytes>;
+    readonly readFileVerified?: (root: string, relativePath: string, byteLimit: number) => AppDiscoveryMaybePromise<AppDiscoveryBytes>;
+}
+export interface WorkspaceAppReservedCatalog {
+    readonly appIds?: Iterable<string>;
+    readonly definitionIds?: Iterable<string>;
+    readonly toolNames?: Iterable<string>;
+}
+export type WorkspaceAppBuiltinCatalog = Pick<McpAppRegistry, 'listMcpApps' | 'listMcpAppTools'>;
+export interface WorkspaceAppDiscoveryOptions {
+    readonly filesystem?: AppDiscoveryFileSystem;
+    readonly fileSystem?: AppDiscoveryFileSystem;
+    readonly fs?: AppDiscoveryFileSystem;
+    readonly clock?: () => number;
+    readonly reserved?: WorkspaceAppReservedCatalog;
+    readonly builtin?: WorkspaceAppReservedCatalog;
+    readonly builtins?: WorkspaceAppReservedCatalog | WorkspaceAppBuiltinCatalog;
+    readonly builtinCatalog?: WorkspaceAppBuiltinCatalog;
+    readonly reservedAppIds?: Iterable<string>;
+    readonly reservedDefinitionIds?: Iterable<string>;
+    readonly reservedToolNames?: Iterable<string>;
+}
+export interface WorkspaceAppToolNames {
+    readonly read: string;
+    readonly action?: string;
+}
+export interface WorkspaceAppResourceSnapshot {
+    readonly entry: {
+        readonly path: 'ui/index.html';
+        readonly hash: string;
+        readonly bytes: readonly number[];
+    };
+    readonly initialState?: {
+        readonly path: 'ui/state.json';
+        readonly hash: string;
+        readonly bytes: readonly number[];
+    };
+}
+export interface WorkspaceAppCandidate {
+    readonly appId: string;
+    readonly pluginId: string;
+    readonly definitionId: string;
+    readonly version: number;
+    readonly source: WorkspaceAppSource;
+    readonly relativePath: string;
+    readonly manifest: UiPluginManifestV2;
+    readonly normalized: UiPluginNormalizedManifestV2;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: UiPluginManifestV2['tone'];
+    readonly definition: UiDefinition;
+    readonly handlers: Readonly<Record<string, UiPluginHandlerMetadata>>;
+    readonly resources: WorkspaceAppResourceSnapshot;
+    readonly html: string;
+    readonly entryBytes: readonly number[];
+    readonly entryHash: string;
+    readonly initialState: JsonObject;
+    readonly initialStateBytes?: readonly number[];
+    readonly initialStateHash?: string;
+    readonly sourceHash: string;
+    readonly toolNames: WorkspaceAppToolNames;
+}
+export interface WorkspaceAppDiscoveryResult {
+    readonly apps: readonly WorkspaceAppCandidate[];
+    readonly diagnostics: readonly WorkspaceAppDiagnostic[];
+    readonly candidates?: readonly WorkspaceAppCandidate[];
+}
+export declare const WORKSPACE_APP_TOOL_PREFIX = "crewx_local_app_";
+export declare const LOCAL_APP_TOOL_PREFIX = "crewx_local_app_";
+export declare const MCP_APP_WORKSPACE_TOOL_PREFIX = "crewx_local_app_";
+export declare function deriveWorkspaceAppToolNames(pluginId: string): WorkspaceAppToolNames;
+export declare function deriveWorkspaceAppToolName(pluginId: string, kind?: 'read' | 'action'): string;
+export declare function discoverWorkspaceApps(workspaceRoot: string, fs?: AppDiscoveryFileSystem, options?: WorkspaceAppDiscoveryOptions): Promise<WorkspaceAppDiscoveryResult>;
+export declare function discoverWorkspaceApps(workspaceRoot: string, options?: WorkspaceAppDiscoveryOptions): Promise<WorkspaceAppDiscoveryResult>;
+export declare const discoverWorkspaceAppCandidates: typeof discoverWorkspaceApps;
+export declare const scanWorkspaceApps: typeof discoverWorkspaceApps;
+export { AppDiscoveryFsError, NodeAppDiscoveryFs, NodeAppDiscoveryFsAdapter, defaultAppDiscoveryFs, defaultNodeAppDiscoveryFs, };
+export type { AppDiscoveryFsErrorCode };

package/dist/mcp-app/index.d.ts

@@ -2,7 +2,13 @@ export type { McpAppContractErrorCode } from './errors.js';
 export { McpAppContractError } from './errors.js';
 export { INSTALLED_APP_ENTRY, InstalledAppRefError, buildInstalledAppRef, validateInstalledAppRef, } from './installed-app-ref.js';
 export type { BuildInstalledAppRefInput, InstalledAppPackageFile, InstalledAppRef, InstalledAppRefErrorCode, } from './installed-app-ref.js';
-export { createMcpAppRegistry, createBuiltinMcpAppRegistry, registerMcpApp, resolveMcpAppResource, requireMcpAppResource, toMcpAppToolRegistration, } from './registry.js';
+export { MAX_HTML_LENGTH, createMcpAppRegistry, createBuiltinMcpAppRegistry, buildMcpAppLocalRegistration, createMcpAppLocalRegistration, registerLocalMcpApp, createMcpAppWorkspaceRegistry, createWorkspaceAppRegistry, createWorkspaceMcpAppRegistry, registerMcpApp, resolveMcpAppResource, resolveLocalMcpAppResource, requireMcpAppResource, toMcpAppToolRegistration, } from './registry.js';
+export { AppDiscoveryFsError, NodeAppDiscoveryFs, NodeAppDiscoveryFsAdapter, defaultAppDiscoveryFs, defaultNodeAppDiscoveryFs, deriveWorkspaceAppToolName, deriveWorkspaceAppToolNames, discoverWorkspaceAppCandidates, discoverWorkspaceApps, LOCAL_APP_TOOL_PREFIX, MCP_APP_WORKSPACE_TOOL_PREFIX, scanWorkspaceApps, WORKSPACE_APP_TOOL_PREFIX, } from './discovery.js';
+export type { AppDiscoveryBytes, AppDiscoveryDiagnostic, AppDiscoveryDirectoryEntry, AppDiscoveryDirectoryEntryKind, AppDiscoveryDirectoryListing, AppDiscoveryFileSystem, AppDiscoveryFsErrorCode, AppDiscoveryMaybePromise, WorkspaceAppDiscoveryOptions as AppDiscoveryOptions, McpAppDiscoveryDiagnostic, WorkspaceAppBuiltinCatalog, WorkspaceAppCandidate, WorkspaceAppDiscoveryOptions, WorkspaceAppDiscoveryResult, WorkspaceAppDiagnostic, WorkspaceAppDiagnosticCode, WorkspaceAppResourceSnapshot, WorkspaceAppReservedCatalog, WorkspaceAppSource, WorkspaceAppToolNames, } from './discovery.js';
 export { buildMcpAppStateDescriptor, buildMcpAppStateProjections, buildTerminalMcpAppStateDescriptor, buildTerminalMcpAppStateProjections, createMcpAppToolResult, serializeMcpAppStateJson, serializeMcpAppStateXml, } from './projection.js';
-export { MCP_APP_HOST_TOOL_ALLOWLIST, MCP_APP_RESOURCE_MIME_TYPE, MCP_APP_RESOURCE_URI_PREFIX, } from './types.js';
-export type { McpAppActionDispatcherToolInput, McpAppActionToolDescriptor, McpAppActionToolInput, McpAppButtonDescriptor, McpAppButtonInput, McpAppDescriptor, McpAppDescriptorInput, McpAppInputSchema, McpAppTone, McpUiResourceCsp, McpAppRegistry, McpAppResource, McpAppServerStateInput, McpAppStateDescriptor, McpAppStateProjections, McpAppHostToolInput, McpAppHostToolName, McpAppReadToolInput, McpAppSingleActionToolInput, McpAppToolCommonInput, McpAppToolDescriptor, McpAppToolInput, McpAppToolMetadata, McpAppToolRegistration, McpAppToolResult, McpAppToolVisibility, } from './types.js';
+export { buildStateSetHandler, createStateSetHandler, } from './state-set.js';
+export type { StateSetHandlerBuildInput } from './state-set.js';
+export { MCP_APP_HOST_TOOL_ALLOWLIST, MCP_APP_LOCAL_RESOURCE_MIME_TYPE, MCP_APP_RESOURCE_MIME_TYPE, MCP_APP_RESOURCE_URI_PREFIX, } from './types.js';
+export type { McpAppActionDispatcherToolInput, McpAppActionToolDescriptor, McpAppActionToolInput, McpAppButtonDescriptor, McpAppButtonInput, McpAppDescriptor, McpAppDescriptorInput, McpAppInputSchema, McpAppTone, McpUiResourceCsp, McpAppRegistry, McpAppResource, McpAppServerStateInput, McpAppStateDescriptor, McpAppStateProjections, McpAppHostToolInput, McpAppHostToolName, McpAppReadToolInput, McpAppSingleActionToolInput, McpAppToolCommonInput, McpAppToolDescriptor, McpAppToolInput, McpAppToolMetadata, McpAppToolRegistration, McpAppToolResult, McpAppToolVisibility, McpAppInstanceResourceBinding, McpAppMcpResourceBinding, McpAppResourceBinding, McpAppLocalResource, McpAppLocalRegistrationInput, McpAppLocalReadToolDescriptor, McpAppLocalActionToolDescriptor, McpAppLocalToolDescriptor, McpAppLocalRegistration, McpAppBuiltinRegistration, McpAppResolvedRegistration, McpAppLocalLauncher, McpAppBuiltinLauncher, McpAppLauncher, WorkspaceAppLauncher, WorkspaceAppResolvedRegistration, McpAppWorkspaceRegistry, WorkspaceAppRegistry, McpAppWorkspaceRegistryInput, } from './types.js';
+export { buildWorkspaceAppSnapshot, discoverWorkspaceAppSnapshot, reconfirmWorkspaceAppSnapshot, } from './workspace-snapshot.js';
+export type { WorkspaceAppSnapshot, WorkspaceAppSnapshotBuildOptions, WorkspaceAppSnapshotOptions, WorkspaceAppSnapshotReconfirmResult, WorkspaceAppSnapshotResource, WorkspaceAppSnapshotInitialState, WorkspaceAppInitialState, } from './workspace-snapshot.js';

package/dist/mcp-app/node-app-discovery-fs.d.ts

@@ -0,0 +1,20 @@
+export type AppDiscoveryFsErrorCode = 'NOT_FOUND' | 'READ_DENIED' | 'LIMIT_EXCEEDED' | 'PATH_ESCAPED' | 'IDENTITY_CHANGED' | 'TOCTOU' | 'UNSUPPORTED';
+export declare class AppDiscoveryFsError extends Error {
+    readonly code: AppDiscoveryFsErrorCode;
+    readonly name = "AppDiscoveryFsError";
+    constructor(code: AppDiscoveryFsErrorCode);
+}
+export interface NodeAppDiscoveryDirectoryEntry {
+    readonly name: string;
+    readonly kind: 'file' | 'directory' | 'symlink' | 'other';
+}
+export declare class NodeAppDiscoveryFs {
+    listDirectory(root: string, relativePath: string): Promise<readonly NodeAppDiscoveryDirectoryEntry[]>;
+    readdir(root: string, relativePath: string): Promise<readonly NodeAppDiscoveryDirectoryEntry[]>;
+    readDirectory(root: string, relativePath: string): Promise<readonly NodeAppDiscoveryDirectoryEntry[]>;
+    readVerifiedFile(root: string, relativePath: string, byteLimit: number): Promise<Uint8Array>;
+    readFileVerified(root: string, relativePath: string, byteLimit: number): Promise<Uint8Array>;
+}
+export declare const defaultAppDiscoveryFs: NodeAppDiscoveryFs;
+export declare const defaultNodeAppDiscoveryFs: NodeAppDiscoveryFs;
+export declare const NodeAppDiscoveryFsAdapter: typeof NodeAppDiscoveryFs;

package/dist/mcp-app/registry.d.ts

@@ -1,7 +1,15 @@
-import { type McpAppDescriptor, type McpAppDescriptorInput, type McpAppRegistry, type McpAppResource, type McpAppToolDescriptor, type McpAppToolRegistration } from './types.js';
+import { type McpAppDescriptor, type McpAppDescriptorInput, type McpAppLocalRegistration, type McpAppLocalRegistrationInput, type McpAppLocalResource, type McpAppRegistry, type McpAppResource, type McpAppWorkspaceRegistry, type McpAppWorkspaceRegistryInput, type McpAppToolDescriptor, type McpAppToolRegistration } from './types.js';
+export declare const MAX_HTML_LENGTH: number;
 export declare function createMcpAppRegistry(): McpAppRegistry;
 export declare function createBuiltinMcpAppRegistry(): McpAppRegistry;
 export declare function registerMcpApp(registry: McpAppRegistry, input: McpAppDescriptorInput): McpAppDescriptor;
 export declare function resolveMcpAppResource(registry: McpAppRegistry, uri: string): McpAppResource | null;
 export declare function requireMcpAppResource(registry: McpAppRegistry, uri: string): McpAppResource;
 export declare function toMcpAppToolRegistration(tool: McpAppToolDescriptor): McpAppToolRegistration;
+export declare function buildMcpAppLocalRegistration(input: McpAppLocalRegistrationInput): McpAppLocalRegistration;
+export declare const createMcpAppLocalRegistration: typeof buildMcpAppLocalRegistration;
+export declare const registerLocalMcpApp: typeof buildMcpAppLocalRegistration;
+export declare function createMcpAppWorkspaceRegistry(input?: McpAppWorkspaceRegistryInput): McpAppWorkspaceRegistry;
+export declare const createWorkspaceAppRegistry: typeof createMcpAppWorkspaceRegistry;
+export declare const createWorkspaceMcpAppRegistry: typeof createMcpAppWorkspaceRegistry;
+export declare function resolveLocalMcpAppResource(registry: McpAppWorkspaceRegistry, appId: string, definitionHash?: string): McpAppLocalResource | null;

package/dist/mcp-app/state-set.d.ts

@@ -0,0 +1,9 @@
+import type { UiStateActionHandlerRegistration } from '../ui-instance/types.js';
+import type { UiPluginNormalizedManifestV2 } from '../ui-plugin/types.js';
+export interface StateSetHandlerBuildInput {
+    readonly normalized: UiPluginNormalizedManifestV2;
+    readonly actionId: string;
+}
+export declare function buildStateSetHandler(normalized: UiPluginNormalizedManifestV2, actionId: string): UiStateActionHandlerRegistration | undefined;
+export declare function buildStateSetHandler(input: StateSetHandlerBuildInput): UiStateActionHandlerRegistration | undefined;
+export declare const createStateSetHandler: typeof buildStateSetHandler;

package/dist/mcp-app/types.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject, UiDefinition, UiDefinitionRef, UiInstance, UiInstanceStatus, UiActionConfirmation } from '../ui-instance/types.js';
+import type { JsonObject, UiDefinition, UiDefinitionRef, UiInstance, UiInstanceStatus, UiActionConfirmation, UiActionHandlerRegistration } from '../ui-instance/types.js';
 export declare const MCP_APP_RESOURCE_MIME_TYPE: "text/html;profile=mcp-app";
 export declare const MCP_APP_RESOURCE_URI_PREFIX = "ui://crewx/";
 export type McpAppToolVisibility = 'model' | 'app';
@@ -72,6 +72,139 @@ export interface McpAppResource {
         };
     };
 }
+export declare const MCP_APP_LOCAL_RESOURCE_MIME_TYPE: "text/html";
+export interface McpAppInstanceResourceBinding {
+    readonly kind: 'instance';
+}
+export interface McpAppMcpResourceBinding {
+    readonly kind: 'mcp';
+    readonly uri: string;
+}
+export type McpAppResourceBinding = McpAppInstanceResourceBinding | McpAppMcpResourceBinding;
+export interface McpAppLocalResource {
+    readonly mimeType: typeof MCP_APP_LOCAL_RESOURCE_MIME_TYPE;
+    readonly entryHash: string;
+    readonly html: string;
+    readonly bytes: readonly number[];
+    readonly initialState?: {
+        readonly hash: string;
+        readonly bytes: readonly number[];
+    };
+}
+export interface McpAppLocalRegistrationInput {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly csp?: McpUiResourceCsp;
+    readonly definition: UiDefinition;
+    readonly html: string;
+    readonly entryHash: string;
+    readonly entryBytes?: readonly number[];
+    readonly initialState?: JsonObject;
+    readonly initialStateHash?: string;
+    readonly initialStateBytes?: readonly number[];
+    readonly readToolName: string;
+    readonly actionToolName?: string;
+    readonly actions: readonly {
+        readonly actionId: string;
+        readonly inputSchema: McpAppInputSchema;
+    }[];
+}
+export interface McpAppLocalReadToolDescriptor extends McpAppToolCommonInput {
+    readonly kind: 'read';
+    readonly resourceBinding: McpAppInstanceResourceBinding;
+    readonly actionIds?: never;
+}
+export interface McpAppLocalActionToolDescriptor extends McpAppToolCommonInput {
+    readonly kind: 'action';
+    readonly resourceBinding: McpAppInstanceResourceBinding;
+    readonly actionIds: readonly string[];
+}
+export type McpAppLocalToolDescriptor = McpAppLocalReadToolDescriptor | McpAppLocalActionToolDescriptor;
+export interface McpAppLocalRegistration {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly builtinOnly: false;
+    readonly definition: UiDefinition;
+    readonly resourceBinding: McpAppInstanceResourceBinding;
+    readonly resource: McpAppLocalResource;
+    readonly tools: readonly McpAppLocalToolDescriptor[];
+}
+export interface McpAppBuiltinRegistration {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly builtinOnly: boolean;
+    readonly uiUri: string;
+    readonly definition?: UiDefinition;
+    readonly resourceBinding: McpAppMcpResourceBinding;
+    readonly resource: McpAppResource;
+    readonly tools: readonly McpAppToolDescriptor[];
+    readonly descriptor: McpAppDescriptor;
+}
+export type McpAppResolvedRegistration = McpAppLocalRegistration | McpAppBuiltinRegistration;
+export interface McpAppLocalLauncher {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly builtinOnly: false;
+    readonly definition: UiDefinitionRef;
+    readonly entryHash: string;
+    readonly resourceBinding: McpAppInstanceResourceBinding;
+    readonly tools: readonly McpAppLocalToolDescriptor[];
+}
+export interface McpAppBuiltinLauncher {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly builtinOnly: boolean;
+    readonly uiUri: string;
+    readonly definition?: UiDefinitionRef;
+    readonly resourceBinding: McpAppMcpResourceBinding;
+    readonly tools: readonly McpAppToolDescriptor[];
+}
+export type McpAppLauncher = McpAppLocalLauncher | McpAppBuiltinLauncher;
+export type WorkspaceAppLauncher = McpAppLauncher;
+export type WorkspaceAppResolvedRegistration = McpAppResolvedRegistration;
+export interface McpAppWorkspaceRegistry {
+    getMcpApp(appId: string): McpAppDescriptor | null;
+    listMcpApps(): readonly McpAppDescriptor[];
+    listMcpAppTools(): readonly McpAppToolDescriptor[];
+    resolveMcpAppTool(toolName: string): McpAppToolDescriptor | null;
+    resolveMcpAppResource(uri: string): McpAppResource | null;
+    requireMcpAppResource(uri: string): McpAppResource;
+    listLocalMcpApps(): readonly McpAppLocalRegistration[];
+    getLocalMcpApp(appId: string): McpAppLocalRegistration | null;
+    listLocalMcpAppTools(): readonly McpAppLocalToolDescriptor[];
+    resolveLocalMcpAppTool(toolName: string): McpAppLocalToolDescriptor | null;
+    resolveLocalMcpAppResource(appId: string, definitionHash?: string): McpAppLocalResource | null;
+    listRegistrations(): readonly McpAppResolvedRegistration[];
+    getRegistration(appId: string): McpAppResolvedRegistration | null;
+    listLaunchers(): readonly McpAppLauncher[];
+    getLauncher(appId: string): McpAppLauncher | null;
+    resolveDefinition(ref: UiDefinitionRef): UiDefinition | null;
+    resolveActionHandler(definitionId: string, version: number, actionId: string): UiActionHandlerRegistration | null;
+}
+export type WorkspaceAppRegistry = McpAppWorkspaceRegistry;
+export interface McpAppWorkspaceRegistryInput {
+    readonly builtins?: McpAppRegistry;
+    readonly builtin?: McpAppRegistry;
+    readonly localApps?: readonly McpAppLocalRegistration[];
+    readonly locals?: readonly McpAppLocalRegistration[];
+    readonly definitions?: readonly UiDefinition[];
+    readonly handlers?: readonly UiActionHandlerRegistration[];
+}
 export interface McpAppToolMetadata {
     readonly ui: {
         readonly resourceUri: string;

package/dist/mcp-app/workspace-snapshot.d.ts

@@ -0,0 +1,53 @@
+import { type AppDiscoveryFileSystem, type WorkspaceAppDiagnostic, type WorkspaceAppDiscoveryOptions, type WorkspaceAppDiscoveryResult } from './discovery.js';
+import type { JsonObject, UiActionHandlerRegistration, UiDefinition, UiDefinitionRef } from '../ui-instance/types.js';
+import type { McpAppLauncher, McpAppLocalResource, McpAppRegistry, McpAppWorkspaceRegistry } from './types.js';
+export interface WorkspaceAppSnapshotResource extends McpAppLocalResource {
+    readonly appId: string;
+    readonly definition: UiDefinitionRef;
+}
+export interface WorkspaceAppSnapshotInitialState {
+    readonly appId: string;
+    readonly definition: UiDefinitionRef;
+    readonly hash: string;
+    readonly bytes: readonly number[];
+    readonly state: JsonObject;
+}
+export type WorkspaceAppInitialState = WorkspaceAppSnapshotInitialState;
+export interface WorkspaceAppSnapshotBuildOptions {
+    readonly builtins?: McpAppRegistry;
+    readonly builtin?: McpAppRegistry;
+    readonly registry?: McpAppRegistry;
+}
+export type WorkspaceAppSnapshotOptions = WorkspaceAppDiscoveryOptions & WorkspaceAppSnapshotBuildOptions;
+export interface WorkspaceAppSnapshot {
+    readonly snapshotHash: string;
+    readonly launchers: readonly McpAppLauncher[];
+    readonly definitions: readonly UiDefinition[];
+    readonly actionHandlers: readonly UiActionHandlerRegistration[];
+    readonly resources: readonly WorkspaceAppSnapshotResource[];
+    readonly initialStates: readonly WorkspaceAppSnapshotInitialState[];
+    readonly diagnostics: readonly WorkspaceAppDiagnostic[];
+    readonly registry: McpAppWorkspaceRegistry;
+    resolveDefinition(ref: UiDefinitionRef): UiDefinition | null;
+    resolveActionHandler(definitionId: string, version: number, actionId: string): UiActionHandlerRegistration | null;
+    resolveResource(appId: string, definitionHash?: string): WorkspaceAppSnapshotResource | null;
+}
+export type WorkspaceAppSnapshotReconfirmResult = {
+    readonly kind: 'same_generation';
+    readonly snapshot: WorkspaceAppSnapshot;
+    readonly diagnostics: readonly WorkspaceAppDiagnostic[];
+} | {
+    readonly kind: 'new_generation';
+    readonly previousSnapshot: WorkspaceAppSnapshot;
+    readonly snapshot: WorkspaceAppSnapshot;
+    readonly diagnostics: readonly WorkspaceAppDiagnostic[];
+} | {
+    readonly kind: 'io_error';
+    readonly snapshot: WorkspaceAppSnapshot;
+    readonly diagnostics: readonly WorkspaceAppDiagnostic[];
+};
+export declare function buildWorkspaceAppSnapshot(discovery: WorkspaceAppDiscoveryResult, options?: WorkspaceAppSnapshotBuildOptions): WorkspaceAppSnapshot;
+export declare function discoverWorkspaceAppSnapshot(workspaceRoot: string, options?: WorkspaceAppSnapshotOptions): Promise<WorkspaceAppSnapshot>;
+export declare function discoverWorkspaceAppSnapshot(workspaceRoot: string, filesystem: AppDiscoveryFileSystem, options?: WorkspaceAppSnapshotOptions): Promise<WorkspaceAppSnapshot>;
+export declare function reconfirmWorkspaceAppSnapshot(workspaceRoot: string, currentSnapshot: WorkspaceAppSnapshot, options?: WorkspaceAppSnapshotOptions): Promise<WorkspaceAppSnapshotReconfirmResult>;
+export declare function reconfirmWorkspaceAppSnapshot(workspaceRoot: string, currentSnapshot: WorkspaceAppSnapshot, filesystem: AppDiscoveryFileSystem, options?: WorkspaceAppSnapshotOptions): Promise<WorkspaceAppSnapshotReconfirmResult>;

package/dist/migrations/0027_task_stop_scope_cleanup.sql

@@ -0,0 +1,5 @@
+UPDATE `tasks`
+SET `stop_requested_at` = NULL,
+    `stop_requested_epoch` = NULL
+WHERE `status` IN ('success', 'failed')
+  AND (`stop_requested_at` IS NOT NULL OR `stop_requested_epoch` IS NOT NULL);

package/dist/migrations/0027_ui_instance_active_unique.sql

@@ -0,0 +1,2 @@
+DROP INDEX IF EXISTS `ui_instances_workspace_thread_app_uq`;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS `ui_instances_workspace_thread_app_uq` ON `ui_instances` (`workspace_id`,`thread_id`,`app_id`) WHERE "status" = 'active';

package/dist/migrations/0029_nice_rhino.sql

@@ -0,0 +1 @@
+ALTER TABLE `tasks` ADD `cwd` text;