@crewx/sdk 0.9.0-rc.136 → 0.9.0-rc.137

package/dist/ui-plugin/app-manifest.d.ts

@@ -0,0 +1,59 @@
+import type { JsonValue } from '../ui-instance/types.js';
+import type { UiPluginManifestMode, UiPluginManifestV2, UiPluginValidationErrorCode } from './types.js';
+export declare const APP_MANIFEST_FILE = "manifest.json";
+export declare const LEGACY_APP_MANIFEST_FILE = "ui-plugin.json";
+export declare const APP_MANIFEST_FILES: readonly ["manifest.json", "ui-plugin.json"];
+export type AppManifestFileName = (typeof APP_MANIFEST_FILES)[number];
+export declare const MCPB_MANIFEST_VERSION = "0.3";
+export declare const CREWX_META_NAMESPACE = "dev.crewx";
+export declare const MCPB_MANIFEST_KEYS: readonly ["manifest_version", "name", "display_name", "version", "description", "long_description", "author", "repository", "homepage", "documentation", "support", "icon", "icons", "screenshots", "localization", "server", "tools", "tools_generated", "prompts", "prompts_generated", "keywords", "license", "privacy_policies", "compatibility", "user_config", "_meta"];
+export declare const APP_MANIFEST_REQUIRED_KEYS: readonly ["manifest_version", "name", "display_name", "version", "description", "_meta"];
+export declare const APP_MANIFEST_PASSTHROUGH_KEYS: readonly ("name" | "description" | "tools" | "server" | "version" | "_meta" | "icon" | "manifest_version" | "display_name" | "long_description" | "author" | "repository" | "homepage" | "documentation" | "support" | "icons" | "screenshots" | "localization" | "tools_generated" | "prompts" | "prompts_generated" | "keywords" | "license" | "privacy_policies" | "compatibility" | "user_config")[];
+export declare const CREWX_META_REQUIRED_KEYS: readonly ["entry", "surfaces", "size", "stateProjection", "actions"];
+export declare const CREWX_META_OPTIONAL_KEYS: readonly ["definitionId", "definitionVersion", "icon", "tone", "entryHash", "runtime", "initialState", "usage", "detailPanel", "displayModes", "summaryProjection", "dataPaths", "focusedAiDataPaths", "csp"];
+export declare function isAppSemver(value: unknown): value is string;
+export interface AppManifestReason {
+    readonly path: string;
+    readonly rule: string;
+    readonly message?: string;
+    readonly file?: AppManifestFileName;
+}
+export type AppManifestRejectionCode = UiPluginValidationErrorCode | 'MANIFEST_DUAL_MISMATCH';
+export interface AppManifestRejection {
+    readonly code: AppManifestRejectionCode;
+    readonly reason: AppManifestReason;
+    readonly files: readonly AppManifestFileName[];
+}
+export interface AppManifestIdentity {
+    readonly pluginId: string;
+    readonly definitionId?: string;
+    readonly definitionVersion?: number;
+}
+export interface AppManifestFileResult {
+    readonly file: AppManifestFileName;
+    readonly manifest: UiPluginManifestV2;
+    readonly v2Input: Readonly<Record<string, unknown>>;
+    readonly releaseVersion?: string;
+    readonly mcpb?: Readonly<Record<string, JsonValue>>;
+}
+export interface AppManifestSource extends AppManifestFileResult {
+    readonly ok: true;
+    readonly identity: AppManifestIdentity;
+    readonly files: readonly AppManifestFileName[];
+}
+export interface AppManifestFailure {
+    readonly ok: false;
+    readonly rejection: AppManifestRejection;
+    readonly parseFailure: boolean;
+    readonly identity?: AppManifestIdentity;
+    readonly builtinOnly: boolean;
+}
+export type AppManifestResult = AppManifestSource | AppManifestFailure;
+export interface AppManifestOptions {
+    readonly mode?: UiPluginManifestMode;
+    readonly maxBytes?: number;
+}
+export type AppManifestFileBytes = Partial<Record<AppManifestFileName, Uint8Array>>;
+export declare function claimsCrewxNamespace(bytes: Uint8Array): boolean;
+export declare function appManifestDefinitionHash(manifest: UiPluginManifestV2): string;
+export declare function resolveAppManifest(files: AppManifestFileBytes, options?: AppManifestOptions): AppManifestResult;

package/dist/ui-plugin/index.d.ts

@@ -1,4 +1,6 @@
 export { canonicalManifestJson, manifestHash } from './manifest.js';
+export { APP_MANIFEST_FILE, APP_MANIFEST_FILES, APP_MANIFEST_PASSTHROUGH_KEYS, APP_MANIFEST_REQUIRED_KEYS, CREWX_META_NAMESPACE, CREWX_META_OPTIONAL_KEYS, CREWX_META_REQUIRED_KEYS, LEGACY_APP_MANIFEST_FILE, MCPB_MANIFEST_KEYS, MCPB_MANIFEST_VERSION, appManifestDefinitionHash, claimsCrewxNamespace, isAppSemver, resolveAppManifest, } from './app-manifest.js';
+export type { AppManifestFailure, AppManifestFileBytes, AppManifestFileName, AppManifestFileResult, AppManifestIdentity, AppManifestOptions, AppManifestReason, AppManifestRejection, AppManifestRejectionCode, AppManifestResult, AppManifestSource, } from './app-manifest.js';
 export { UiPluginValidationError, normalizeManifest, validateInitialState, validateManifest, validatePayload, } from './validator.js';
 export { UI_PLUGIN_CAPABILITY_PATTERN, UI_PLUGIN_HANDLER_PATTERN, UI_PLUGIN_IDENTIFIER_PATTERN, UI_PLUGIN_MAX_ACTIONS, UI_PLUGIN_MAX_ARRAY_LENGTH, UI_PLUGIN_MAX_CANDIDATE_DEPTH, UI_PLUGIN_MAX_COMMAND_LENGTH, UI_PLUGIN_MAX_COMMAND_PARTS, UI_PLUGIN_MAX_DISCOVERED_APPS, UI_PLUGIN_MAX_DISCOVERY_TIME_MS, UI_PLUGIN_MAX_HEIGHT, UI_PLUGIN_MAX_INITIAL_STATE_BYTES, UI_PLUGIN_MAX_JSON_DEPTH, UI_PLUGIN_MAX_MANIFEST_BYTES, UI_PLUGIN_MAX_PROJECTION_PATHS, UI_PLUGIN_MAX_SCHEMA_DEPTH, UI_PLUGIN_MAX_SCHEMA_PROPERTIES, UI_PLUGIN_MAX_STRING_LENGTH, UI_PLUGIN_MAX_SUBTREE_BYTES, UI_PLUGIN_MAX_SURFACES, UI_PLUGIN_RESERVED_STATE_KEYS, UI_PLUGIN_SAFE_PATH_PATTERN, UI_PLUGIN_SAFE_PATH_SEGMENT_PATTERN, UI_PLUGIN_SKILL_TOKEN_PATTERN, UI_PLUGIN_SURFACES, UI_PLUGIN_TONES, isUiPluginReservedStateKey, } from './limits.js';
 export type { UiPluginActivation, UiPluginAction, UiPluginBackend, UiPluginCardShellNode, UiPluginCoreBackend, UiPluginFieldSchema, UiPluginHeadingNode, UiPluginInputSchema, UiPluginJsonSchema, UiPluginJsonSchemaType, UiPluginLabeledTextNode, UiPluginLayoutNode, UiPluginLayout, UiPluginManifest, UiPluginManifestMode, UiPluginManifestV1, UiPluginManifestV2, UiPluginRuntimeRequest, UiPluginMetaBannerNode, UiPluginNormalizedManifestV2, UiPluginNormalizedV2, UiPluginPayload, UiPluginPayloadValue, UiPluginPrimitive, UiPluginProjectionPolicy, UiPluginResourceMetadata, UiPluginResourceRef, UiPluginSchemaType, UiPluginSchema, UiPluginSize, UiPluginSkillBackend, UiPluginStep, UiPluginStepFlowNode, UiPluginStepListSchema, UiPluginTextListNode, UiPluginTextListSchema, UiPluginTextSchema, UiPluginSurface, UiPluginTone, UiPluginHandlerMetadata, UiPluginValidationErrorCode, UiPluginValidationOptions, } from './types.js';

package/dist/ui-plugin/validator.d.ts

@@ -2,8 +2,11 @@ import type { UiPluginManifest, UiPluginManifestV1, UiPluginManifestV2, UiPlugin
 import type { JsonObject } from '../ui-instance/types.js';
 export declare class UiPluginValidationError extends Error {
     readonly code: UiPluginValidationErrorCode;
+    readonly path?: string | undefined;
+    readonly rule?: string | undefined;
     readonly name = "UiPluginValidationError";
-    constructor(code: UiPluginValidationErrorCode, message?: string);
+    constructor(code: UiPluginValidationErrorCode, message?: string, path?: string | undefined, rule?: string | undefined);
+    withPathPrefix(prefix: string): UiPluginValidationError;
 }
 export declare function validateInitialState(value: unknown, dataPaths?: readonly string[]): JsonObject;
 export declare function validateManifest(input: UiPluginManifestV1, options?: UiPluginValidationOptions): UiPluginManifestV1;

package/dist/utils/env-defaults.d.ts

@@ -1,4 +1,5 @@
 import { type CrewxExecutableResolution } from './crewx-executable';
+export declare function resolveCrewxCliDisplay(env?: Readonly<Record<string, string | undefined>>): string;
 export declare function resolveCrewxCli(): string;
 export declare function resolveCrewxCliArgv(): CrewxExecutableResolution;
 export declare function resolveCrewxWorkspace(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/sdk",
-  "version": "0.9.0-rc.136",
+  "version": "0.9.0-rc.137",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=20.19.0"
@@ -83,6 +83,11 @@
       "import": "./dist/account/index.js",
       "require": "./dist/account/index.js"
     },
+    "./app": {
+      "types": "./dist/app/index.d.ts",
+      "import": "./dist/app/index.js",
+      "require": "./dist/app/index.js"
+    },
     "./package.json": "./package.json"
   },
   "browser": {
@@ -102,6 +107,8 @@
     "./dist/esm/publish/index.js": false,
     "./dist/account/index.js": false,
     "./dist/esm/account/index.js": false,
+    "./dist/app/index.js": false,
+    "./dist/esm/app/index.js": false,
     "./dist/skills/index.js": false,
     "./dist/esm/skills/index.js": false
   },
@@ -163,7 +170,7 @@
     "vitest": "3.2.4"
   },
   "scripts": {
-    "prebuild": "node scripts/generate-pricing.mjs && node scripts/generate-models.mjs",
+    "prebuild": "node ../../scripts/check-sdk-app-imports.mjs && node scripts/generate-pricing.mjs && node scripts/generate-models.mjs",
     "build:cjs": "tsup --config tsup.cjs.js",
     "build:esm": "tsup --config tsup.esm.js",
     "build:browser": "tsup --config tsup.browser.js",

package/templates/agents/default.yaml

@@ -287,15 +287,20 @@ layouts:
         {{env.CREWX_CLI}} notify "<title>" [--level=info|warning|critical] [--body="..."]
         ```
         ### App (`{{env.CREWX_CLI}} app`)
-        Open CrewX Apps in this conversation and run allowed actions. Never click the screen instead.
+        CrewX Apps are screens that you and the user work on together (tables, boards, planners, viewers). When an App fits the request, put the result in the App instead of writing a long chat answer.
+
+        Drill down in this order. Do NOT guess action names or inputs.
         ```bash
-        {{env.CREWX_CLI}} app list
-        {{env.CREWX_CLI}} app open <appId>
-        {{env.CREWX_CLI}} app state <instanceId>
+        {{env.CREWX_CLI}} app list                     # 1. which Apps exist{{#if apps.availableRendered}} (the same list is in <available_apps> below){{/if}}
+        {{env.CREWX_CLI}} app usage <appId>            # 2. that App's manual and action table. Read it before the first run
+        {{env.CREWX_CLI}} app open <appId>             # 3. open it in this conversation -> instanceId
         {{env.CREWX_CLI}} app run <instanceId|appId> <actionId> [--input <JSON>|-] [--request-id <id>]
+        {{env.CREWX_CLI}} app state <instanceId>       # 4. confirm what actually changed
         {{env.CREWX_CLI}} app receipt <receiptId>
         ```
-        Cite the receiptId in your report. On exit 3, 9, 10, or 11, do not work around it; report that you could not use the App route.
+        Never click the screen instead. Exit 8 = waiting for the user's one-time approval in the App window: keep this turn running and wait with `{{env.CREWX_CLI}} app receipt <receiptId> --wait=60` (repeat on exit 124); ending the turn cancels the request.
+        On exit 3, 9, 10, or 11, do not work around it; report that you could not use the App route. Cite the receiptId in your report.
+        → Full usage: `{{env.CREWX_CLI}} app usage`
         </builtin_tools>
         {{/if}}
 
@@ -318,6 +323,10 @@ layouts:
         {{/if}}
         {{/if}}
 
+      {{#if apps.availableRendered}}
+      {{{apps.availableRendered}}}
+      {{/if}}
+
         {{#if props.showCREWXMDHint}}
         <important>
           **AGENTS.md contains user's project information.**
@@ -429,6 +438,9 @@ layouts:
       </messages>
       {{/if}}
       {{#if apps.rendered}}
+      {{#if apps.guidanceRendered}}
+      {{{apps.guidanceRendered}}}
+      {{/if}}
       {{{apps.rendered}}}
       {{/if}}
       {{#if (eq platform 'channel/slack')}}