@crewx/sdk 0.9.0-rc.12 → 0.9.0-rc.121

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

@@ -0,0 +1,24 @@
+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 { 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, WorkspaceAppDiscoveryIncompleteReason, WorkspaceAppDiscoveryOptions, WorkspaceAppDiscoveryResult, WorkspaceAppDiagnostic, WorkspaceAppDiagnosticCode, WorkspaceAppResourceSnapshot, WorkspaceAppReservedCatalog, WorkspaceAppSource, WorkspaceAppToolNames, } from './discovery.js';
+export { createWorkspaceAppCatalog, discoverWorkspaceAppCatalog, hashAppDefinition, hashCrewxAppDefinition, listWorkspaceApps, } from './catalog.js';
+export type { CrewxAppBuiltinCatalog, CrewxAppCapability, CrewxAppCatalogOptions, CrewxAppCatalogResult, CrewxAppDefinitionHashInput, CrewxAppDefinitionSummary, CrewxAppDiagnostic, CrewxAppDiagnosticCode, CrewxAppDiagnosticSource, CrewxAppInstalledProjection, CrewxAppLocalDefinitionRef, CrewxAppOrigin, CrewxAppOwnership, CrewxAppShareability, CrewxAppSharingAvailability, CrewxAppSummary, } from './types.js';
+export { MCP_APP_PROJECTION_MAX_BYTES, buildMcpAppStateDescriptor, buildMcpAppStateProjections, buildTerminalMcpAppStateDescriptor, buildTerminalMcpAppStateProjections, createMcpAppToolResult, serializeMcpAppStateJson, serializeMcpAppStateXml, } from './projection.js';
+export { buildMcpAppsContext } from './apps-context.js';
+export type { McpAppsContext } from './apps-context.js';
+export { MCP_APP_MODEL_CONTEXT_MAX_ARRAY_LENGTH, MCP_APP_MODEL_CONTEXT_MAX_BYTES, MCP_APP_MODEL_CONTEXT_MAX_DEPTH, MCP_APP_MODEL_CONTEXT_MAX_STRING_LENGTH, sanitizeMcpAppModelContext, serializeMcpAppModelContextXml, } from './model-context.js';
+export type { McpAppModelContext, McpAppModelContextInput } from './model-context.js';
+export { resolveAgentAccess } from './agent-access.js';
+export type { McpAppAgentAccess, McpAppAgentAccessAction } from './agent-access.js';
+export { buildStateSetHandler, createStateSetHandler, } from './state-set.js';
+export type { StateSetHandlerBuildInput } from './state-set.js';
+export { SKILL_BACKEND_DEFAULT_TIMEOUT_MS, SKILL_BACKEND_MAX_INPUT_BYTES, SKILL_BACKEND_MAX_OUTPUT_BYTES, SKILL_BACKEND_SCHEMA_VERSION, buildSkillBackendHandler, } from './skill-backend.js';
+export type { SkillBackendExecutionPort, SkillBackendExecutionRequest, SkillBackendExecutionResponse, SkillBackendHandlerBuildInput, SkillBackendInfrastructureErrorCode, SkillBackendPayload, } from './skill-backend.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, McpAppLocalSingleActionToolDescriptor, McpAppLocalToolDiagnostic, 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/installed-app-ref.d.ts

@@ -0,0 +1,25 @@
+import type { UiDefinition, UiDefinitionRef } from '../ui-instance/types.js';
+export declare const INSTALLED_APP_ENTRY: "ui/index.html";
+export type InstalledAppRefErrorCode = 'APP_ID_INVALID' | 'DEFINITION_REF_INVALID' | 'ENTRY_DUPLICATE' | 'ENTRY_PATH_INVALID' | 'ENTRY_MISSING' | 'ENTRY_HASH_INVALID' | 'INSTALLED_APP_REF_INVALID';
+export declare class InstalledAppRefError extends Error {
+    readonly code: InstalledAppRefErrorCode;
+    readonly name = "InstalledAppRefError";
+    constructor(code: InstalledAppRefErrorCode, message?: string);
+}
+export interface InstalledAppRef {
+    readonly appId: string;
+    readonly definition: UiDefinitionRef;
+    readonly entry: typeof INSTALLED_APP_ENTRY;
+    readonly entryHash: string;
+}
+export interface InstalledAppPackageFile {
+    readonly path: string;
+    readonly sha256: string;
+}
+export interface BuildInstalledAppRefInput {
+    readonly appId: string;
+    readonly definition: UiDefinition;
+    readonly packageFiles: readonly InstalledAppPackageFile[];
+}
+export declare function validateInstalledAppRef(value: unknown): InstalledAppRef;
+export declare function buildInstalledAppRef(input: BuildInstalledAppRefInput): InstalledAppRef;

package/dist/mcp-app/model-context.d.ts

@@ -0,0 +1,26 @@
+import type { JsonObject } from '../ui-instance/types.js';
+export declare const MCP_APP_MODEL_CONTEXT_MAX_BYTES: number;
+export declare const MCP_APP_MODEL_CONTEXT_MAX_STRING_LENGTH = 2048;
+export declare const MCP_APP_MODEL_CONTEXT_MAX_ARRAY_LENGTH = 200;
+export declare const MCP_APP_MODEL_CONTEXT_MAX_DEPTH = 8;
+export interface McpAppModelContextInput {
+    readonly instanceId: string;
+    readonly definitionHash: string;
+    readonly revision: number;
+    readonly content?: unknown;
+    readonly structuredContent?: unknown;
+}
+export interface McpAppModelContext {
+    readonly instanceId: string;
+    readonly definitionHash: string;
+    readonly revision: number;
+    readonly content?: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+    readonly structuredContent?: JsonObject;
+}
+export declare function sanitizeMcpAppModelContext(value: unknown): McpAppModelContext;
+export declare function serializeMcpAppModelContextXml(context: McpAppModelContext, options?: {
+    readonly stale?: boolean;
+}): string;

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/projection.d.ts

@@ -0,0 +1,14 @@
+import type { JsonObject } from '../ui-instance/types.js';
+import type { McpAppServerStateInput, McpAppStateDescriptor, McpAppStateProjections, McpAppToolDescriptor, McpAppToolResult } from './types.js';
+export declare const MCP_APP_PROJECTION_MAX_BYTES: number;
+export declare const SENSITIVE_KEY: RegExp;
+export declare function buildMcpAppStateDescriptor(input: McpAppServerStateInput): McpAppStateDescriptor;
+export declare function buildTerminalMcpAppStateDescriptor(input: McpAppServerStateInput): McpAppStateDescriptor;
+export declare function serializeMcpAppStateJson(descriptor: McpAppStateDescriptor, dataPaths?: readonly string[]): string;
+export declare function serializeMcpAppStateXml(descriptor: McpAppStateDescriptor): string;
+export declare function buildMcpAppStateProjections(input: McpAppServerStateInput): McpAppStateProjections;
+export declare function buildTerminalMcpAppStateProjections(input: McpAppServerStateInput): McpAppStateProjections;
+export declare function createMcpAppToolResult(tool: Pick<McpAppToolDescriptor, 'textFallback'>, options?: {
+    structuredContent?: JsonObject;
+    meta?: JsonObject;
+}): McpAppToolResult;

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

@@ -0,0 +1,19 @@
+import { type McpAppDescriptor, type McpAppDescriptorInput, type McpAppInputSchema, 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 createMcpAppLocalActionInputSchema(actions: readonly {
+    readonly actionId: string;
+    readonly inputSchema: McpAppInputSchema;
+}[]): McpAppInputSchema;
+export declare function resolveLocalMcpAppResource(registry: McpAppWorkspaceRegistry, appId: string, definitionHash?: string): McpAppLocalResource | null;

package/dist/mcp-app/skill-backend.d.ts

@@ -0,0 +1,48 @@
+import type { JsonObject, UiExternalActionHandlerRegistration } from '../ui-instance/types.js';
+import type { UiPluginNormalizedManifestV2 } from '../ui-plugin/types.js';
+import type { WorkspaceAppSource } from './discovery.js';
+export declare const SKILL_BACKEND_SCHEMA_VERSION: 1;
+export declare const SKILL_BACKEND_MAX_INPUT_BYTES: number;
+export declare const SKILL_BACKEND_MAX_OUTPUT_BYTES: number;
+export declare const SKILL_BACKEND_DEFAULT_TIMEOUT_MS = 15000;
+export type SkillBackendInfrastructureErrorCode = 'EXEC_DENIED' | 'EXEC_TIMEOUT' | 'EXEC_OUTPUT_INVALID' | 'EXECUTION_FAILED' | 'ACTION_IN_FLIGHT' | 'INPUT_INVALID';
+export interface SkillBackendPayload {
+    readonly schemaVersion: typeof SKILL_BACKEND_SCHEMA_VERSION;
+    readonly actionId: string;
+    readonly input: JsonObject;
+    readonly state: JsonObject;
+}
+export type SkillBackendExecutionResponse = {
+    readonly state?: JsonObject;
+    readonly result?: JsonObject;
+} | {
+    readonly outcome: 'rejected' | 'failed';
+    readonly errorCode: string;
+    readonly state?: JsonObject;
+    readonly result?: JsonObject;
+};
+export interface SkillBackendExecutionRequest {
+    readonly instanceId: string;
+    readonly appId: string;
+    readonly definitionId: string;
+    readonly definitionVersion: number;
+    readonly definitionHash: string;
+    readonly actionId: string;
+    readonly source: WorkspaceAppSource;
+    readonly relativePath: string;
+    readonly command: readonly string[];
+    readonly payload: SkillBackendPayload;
+}
+export interface SkillBackendExecutionPort {
+    execute(request: SkillBackendExecutionRequest): PromiseLike<SkillBackendExecutionResponse>;
+}
+export interface SkillBackendHandlerBuildInput {
+    readonly normalized: UiPluginNormalizedManifestV2;
+    readonly actionId: string;
+    readonly source: WorkspaceAppSource;
+    readonly relativePath: string;
+    readonly execute: SkillBackendExecutionPort;
+    readonly definitionHash?: string;
+}
+export declare function buildSkillBackendHandler(normalized: UiPluginNormalizedManifestV2, actionId: string, source: WorkspaceAppSource, relativePath: string, execute: SkillBackendExecutionPort): UiExternalActionHandlerRegistration | undefined;
+export declare function buildSkillBackendHandler(input: SkillBackendHandlerBuildInput): UiExternalActionHandlerRegistration | undefined;

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

@@ -0,0 +1,394 @@
+import type { JsonObject, UiDefinition, UiDefinitionRef, UiDefinitionDisplayMode, UiDefinitionUsage, UiInstance, UiInstanceStatus, UiActionConfirmation, UiActionHandlerRegistration } from '../ui-instance/types.js';
+import type { AppDiscoveryFileSystem } from './discovery.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';
+export type McpAppTone = 'blue' | 'violet' | 'emerald' | 'amber' | 'rose' | 'sky' | 'slate' | 'indigo';
+export declare const MCP_APP_HOST_TOOL_ALLOWLIST: readonly ["crewx_app_terminal_connect", "crewx_app_html_viewer_open"];
+export type McpAppHostToolName = typeof MCP_APP_HOST_TOOL_ALLOWLIST[number];
+export interface McpUiResourceCsp {
+    readonly connectDomains?: readonly string[];
+    readonly resourceDomains?: readonly string[];
+    readonly frameDomains?: readonly string[];
+    readonly baseUriDomains?: readonly string[];
+}
+export type McpAppInputSchema = JsonObject;
+export interface McpAppToolCommonInput {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: McpAppInputSchema;
+    readonly textFallback: string;
+    readonly visibility: readonly McpAppToolVisibility[];
+}
+export interface McpAppReadToolInput extends McpAppToolCommonInput {
+    readonly kind: 'read';
+    readonly actionId?: never;
+}
+export interface McpAppSingleActionToolInput extends McpAppToolCommonInput {
+    readonly kind: 'action';
+    readonly actionId: string;
+    readonly actionIds?: never;
+}
+export interface McpAppActionDispatcherToolInput extends McpAppToolCommonInput {
+    readonly kind: 'action';
+    readonly actionId?: never;
+    readonly actionIds: readonly string[];
+}
+export type McpAppActionToolInput = McpAppSingleActionToolInput | McpAppActionDispatcherToolInput;
+export type McpAppActionToolDescriptor = (Omit<McpAppSingleActionToolInput, 'actionIds'> & {
+    readonly actionIds: readonly string[];
+}) | (Omit<McpAppActionDispatcherToolInput, 'actionId'> & {
+    readonly actionIds: readonly string[];
+});
+type McpAppToolDescriptorMetadata = {
+    readonly resourceUri: string;
+    readonly _meta: McpAppToolMetadata;
+};
+export interface McpAppHostToolInput extends Omit<McpAppToolCommonInput, 'name' | 'visibility'> {
+    readonly name: McpAppHostToolName;
+    readonly kind: 'host';
+    readonly visibility: readonly ['app'];
+    readonly actionId?: never;
+}
+export type McpAppToolInput = McpAppReadToolInput | McpAppActionToolInput | McpAppHostToolInput;
+export interface McpAppDescriptorInput {
+    readonly appId: string;
+    readonly html: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly builtinOnly?: boolean;
+    readonly csp?: McpUiResourceCsp;
+    readonly tools: readonly McpAppToolInput[];
+    readonly definition?: UiDefinition;
+}
+export interface McpAppResource {
+    readonly uri: string;
+    readonly mimeType: typeof MCP_APP_RESOURCE_MIME_TYPE;
+    readonly text: string;
+    readonly _meta?: {
+        readonly ui?: {
+            readonly csp?: McpUiResourceCsp;
+        };
+    };
+}
+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 modelActions?: readonly string[];
+    readonly actions: readonly {
+        readonly actionId: string;
+        readonly inputSchema: McpAppInputSchema;
+        readonly backend?: {
+            readonly type: 'core';
+            readonly handler: string;
+        } | {
+            readonly type: 'skill';
+            readonly command?: readonly string[];
+        };
+    }[];
+}
+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 interface McpAppLocalSingleActionToolDescriptor extends McpAppToolCommonInput {
+    readonly kind: 'action';
+    readonly resourceBinding: McpAppInstanceResourceBinding;
+    readonly actionId: string;
+    readonly actionIds: readonly [string];
+    readonly _meta: {
+        readonly ui: {
+            readonly visibility: readonly McpAppToolVisibility[];
+        };
+    };
+}
+export interface McpAppLocalToolDiagnostic {
+    readonly toolName: string;
+    readonly actionId: string;
+    readonly reason: 'name_too_long' | 'name_collision';
+}
+export type McpAppLocalToolDescriptor = McpAppLocalReadToolDescriptor | McpAppLocalActionToolDescriptor | McpAppLocalSingleActionToolDescriptor;
+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[];
+    readonly toolDiagnostics: readonly McpAppLocalToolDiagnostic[];
+}
+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;
+        readonly visibility: readonly McpAppToolVisibility[];
+    };
+}
+export type McpAppToolDescriptor = (McpAppReadToolInput & McpAppToolDescriptorMetadata) | (McpAppActionToolDescriptor & McpAppToolDescriptorMetadata) | (McpAppHostToolInput & McpAppToolDescriptorMetadata);
+export interface McpAppToolRegistration {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: McpAppInputSchema;
+    readonly _meta: McpAppToolMetadata;
+}
+export interface McpAppDescriptor {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string;
+    readonly tone?: McpAppTone;
+    readonly builtinOnly: boolean;
+    readonly csp?: McpUiResourceCsp;
+    readonly uiUri: string;
+    readonly html: string;
+    readonly definition?: UiDefinition;
+    readonly tools: readonly McpAppToolDescriptor[];
+}
+export interface McpAppToolResult {
+    readonly content: readonly [{
+        readonly type: 'text';
+        readonly text: string;
+    }];
+    readonly structuredContent?: JsonObject;
+    readonly _meta?: JsonObject;
+}
+export interface McpAppButtonInput {
+    readonly id: string;
+    readonly label: string;
+    readonly enabled: boolean;
+    readonly confirmation?: UiActionConfirmation;
+    readonly requiresHumanConfirmation?: boolean;
+    readonly disabledReason?: string;
+    readonly inputSchema: McpAppInputSchema;
+}
+export interface McpAppServerStateInput {
+    readonly source: 'server';
+    readonly instance: Pick<UiInstance, 'id' | 'definition' | 'revision' | 'status' | 'state'>;
+    readonly definition: UiDefinition;
+    readonly buttons: readonly McpAppButtonInput[];
+}
+export interface McpAppButtonDescriptor {
+    readonly id: string;
+    readonly label: string;
+    readonly enabled: boolean;
+    readonly confirmation: UiActionConfirmation;
+    readonly requiresHumanConfirmation?: boolean;
+    readonly disabledReason: string | null;
+    readonly inputSchema: McpAppInputSchema;
+}
+export interface McpAppStateDescriptor {
+    readonly schemaVersion: 1;
+    readonly source: 'server';
+    readonly instanceId: string;
+    readonly definition: UiDefinitionRef;
+    readonly revision: number;
+    readonly status: UiInstanceStatus;
+    readonly state: JsonObject;
+    readonly buttons: readonly McpAppButtonDescriptor[];
+}
+export interface McpAppStateProjections {
+    readonly descriptor: McpAppStateDescriptor;
+    readonly card: McpAppStateDescriptor;
+    readonly developer: {
+        readonly descriptor: McpAppStateDescriptor;
+        readonly json: string;
+    };
+    readonly ai: {
+        readonly descriptor: McpAppStateDescriptor;
+        readonly json: string;
+        readonly xml: string;
+        readonly omittedPaths?: readonly string[];
+    };
+    readonly focusedAi: {
+        readonly descriptor: McpAppStateDescriptor;
+        readonly json: string;
+        readonly xml: string;
+        readonly omittedPaths?: readonly string[];
+    };
+}
+export interface McpAppRegistry {
+    registerMcpApp(input: McpAppDescriptorInput): McpAppDescriptor;
+    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;
+}
+export type CrewxAppCapability = 'screen' | 'skill';
+export type CrewxAppOrigin = 'local' | 'installed' | 'builtin';
+export type CrewxAppOwnership = 'mine' | 'external' | 'unknown';
+export type CrewxAppShareability = 'shareable' | 'requiresPublish' | 'forbidden' | 'unknown';
+export type CrewxAppSharingAvailability = 'ready' | 'loginRequired' | 'unavailable';
+export interface CrewxAppLocalDefinitionRef {
+    readonly packageRoot: string;
+}
+export interface CrewxAppDefinitionSummary extends UiDefinitionRef {
+    readonly usage: UiDefinitionUsage;
+    readonly detailPanel?: boolean;
+    readonly displayModes?: readonly UiDefinitionDisplayMode[];
+}
+export interface CrewxAppDefinitionHashInput {
+    readonly screenHash?: string;
+    readonly skillHash?: string;
+    readonly relativePath?: string;
+    readonly fileBytes?: Uint8Array | ArrayBuffer | readonly number[] | string;
+}
+export interface CrewxAppSummary {
+    readonly appId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly version?: string;
+    readonly capabilities: readonly CrewxAppCapability[];
+    readonly definition?: CrewxAppDefinitionSummary;
+    readonly skillName?: string;
+    readonly localDefinitionRef?: CrewxAppLocalDefinitionRef;
+    readonly origin: CrewxAppOrigin;
+    readonly ownership: CrewxAppOwnership;
+    readonly shareability: CrewxAppShareability;
+    readonly sharingAvailability: CrewxAppSharingAvailability;
+    readonly marketplaceContentId?: string;
+    readonly slug?: string;
+    readonly definitionHash: string;
+}
+export type CrewxAppDiagnosticCode = 'MANIFEST_MISSING' | 'MANIFEST_INVALID' | 'ENTRY_INVALID' | 'INITIAL_STATE_INVALID' | 'DUPLICATE_ID' | 'RESERVED_ID' | 'PATH_ESCAPED' | 'LIMIT_EXCEEDED' | 'EXEC_DENIED' | 'SKILL_INVALID' | 'SKILL_READ_FAILED' | 'INSTALLED_MISSING' | 'INSTALLED_CONTENT_ID_MISSING' | 'INSTALLED_IDENTITY_MISMATCH' | 'BUILTIN_INVALID';
+export type CrewxAppDiagnosticSource = 'apps' | 'skills' | 'node_modules' | 'builtin' | 'installed';
+export interface CrewxAppDiagnostic {
+    readonly code: CrewxAppDiagnosticCode;
+    readonly source: CrewxAppDiagnosticSource;
+    readonly relativePath: string;
+    readonly appId?: string;
+}
+export interface CrewxAppInstalledProjection {
+    readonly packageRoot?: string;
+    readonly relativePath?: string;
+    readonly packageRootPath?: string;
+    readonly appId?: string;
+    readonly definitionHash?: string;
+    readonly marketplaceContentId?: string;
+    readonly slug?: string;
+}
+export type CrewxAppBuiltinCatalog = Pick<McpAppRegistry, 'listMcpApps' | 'listMcpAppTools'>;
+export interface CrewxAppCatalogOptions {
+    readonly filesystem?: AppDiscoveryFileSystem;
+    readonly builtinCatalog?: CrewxAppBuiltinCatalog;
+    readonly installed?: readonly CrewxAppInstalledProjection[];
+}
+export interface CrewxAppCatalogResult {
+    readonly items: readonly CrewxAppSummary[];
+    readonly diagnostics: readonly CrewxAppDiagnostic[];
+}
+export {};

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

@@ -0,0 +1,61 @@
+import { type AppDiscoveryFileSystem, type WorkspaceAppDiscoveryIncompleteReason, type WorkspaceAppDiagnostic, type WorkspaceAppDiscoveryOptions, type WorkspaceAppDiscoveryResult, type WorkspaceAppSource } from './discovery.js';
+import { type SkillBackendExecutionPort } from './skill-backend.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;
+    readonly source: WorkspaceAppSource;
+}
+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;
+    readonly skillBackend?: SkillBackendExecutionPort;
+}
+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: 'incomplete';
+    readonly reason: WorkspaceAppDiscoveryIncompleteReason;
+    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>;