@vertesia/common 1.2.0 → 1.3.0-dev.20260620.091720Z

package/lib/{types/apps.d.ts → apps.d.ts}

@@ -1,6 +1,7 @@
-import { JSONObject, JSONSchema, ToolDefinition } from "@llumiverse/common";
-import { CatalogInteractionRef } from "./interaction.js";
-import { DSLActivityOptions, InCodeTypeDefinition } from "./store/index.js";
+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';
 /** Allowed values for AppUINavItem.preferredSection */
 export declare const PREFERRED_SECTIONS: readonly ["default", "footer", "settings"];
 /**
@@ -41,7 +42,7 @@ export interface AppUIConfig {
      * - shadow - use Shadow DOM to fully isolate the plugin from the host.
      * - css - use CSS processing (like prefixing or other isolation techniques). Ligther but plugins may conflict with the host
      */
-    isolation?: "shadow" | "css";
+    isolation?: 'shadow' | 'css';
     /**
      * Navigation items for the app's sidebar UI.
      * Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell).
@@ -66,11 +67,11 @@ export interface AppInstallationsQuery {
 /**
  * Authentication type for tool collections
  */
-export type ToolCollectionAuthType = "oauth" | "other";
+export type ToolCollectionAuthType = 'oauth' | 'other';
 /**
  * Tool collection type
  */
-export type ToolCollectionType = "mcp" | "vertesia_sdk";
+export type ToolCollectionType = 'mcp' | 'vertesia_sdk';
 /**
  * Base tool collection configuration
  */
@@ -120,7 +121,7 @@ export interface MCPOAuthConfig {
  * MCP tool collection configuration (requires name, description, and namespace)
  */
 export interface MCPToolCollectionObject extends BaseToolCollectionObject {
-    type: "mcp";
+    type: 'mcp';
     /**
      * Stable identifier for this collection.
      * Used to key oauth_bindings on AppInstallation — protects against collection renames.
@@ -176,7 +177,7 @@ export interface MCPToolCollectionObject extends BaseToolCollectionObject {
  * Vertesia SDK tool collection configuration
  */
 export interface VertesiaSDKToolCollectionObject extends BaseToolCollectionObject {
-    type: "vertesia_sdk";
+    type: 'vertesia_sdk';
     /**
      * Optional namespace to use for tool names from this collection.
      * If not provided, the tool server default will be used.
@@ -196,13 +197,16 @@ export interface VertesiaSDKToolCollectionObject extends BaseToolCollectionObjec
 /**
  * Tool collection configuration (object format)
  */
+/**
+ * @discriminator type
+ */
 export type ToolCollectionObject = MCPToolCollectionObject | VertesiaSDKToolCollectionObject;
 /**
- * Tool collection can be either:
- * - A string URL (legacy format, with "mcp:" prefix for MCP servers)
- * - An object with url, type, and optional auth (new format)
+ * Backward-compatible TypeScript alias. Public API payloads should reference
+ * ToolCollectionObject directly so generated clients do not create a wrapper
+ * model around the discriminated union.
  */
-export type ToolCollection = string | ToolCollectionObject;
+export type ToolCollection = ToolCollectionObject;
 export declare const MCP_COLLECTION_ID_PATTERN: RegExp;
 export declare const MCP_COLLECTION_NAMESPACE_PATTERN: RegExp;
 export declare function isValidMCPCollectionId(id: string): boolean;
@@ -211,12 +215,14 @@ export declare function deriveMCPCollectionId(input: string): string;
 export declare function getDefaultOAuthAppNameForCollectionId(collectionId: string): string;
 /**
  * Normalizes a tool collection to the object format.
- * Handles backward compatibility with string URLs.
+ * Applies optional `{{var}}` substitution to the URL so manifests can reference
+ * deployment-time variables like `{{studio_ui}}`.
  *
- * @param collection - String URL or ToolCollectionObject
+ * @param collection - ToolCollectionObject
+ * @param vars - Optional endpoint variables to substitute in URLs
  * @returns Normalized ToolCollectionObject
  */
-export declare function normalizeToolCollection(collection: ToolCollection): ToolCollectionObject;
+export declare function normalizeToolCollection(collection: ToolCollectionObject, vars?: Endpoints): ToolCollectionObject;
 /**
  * Metadata hints from MCP tool annotations (per MCP spec).
  */
@@ -249,18 +255,29 @@ export interface AgentToolDefinition extends ToolDefinition {
     /**
      * Whether this tool is available by default.
      * - true/undefined: Tool is always available to agents
-     * - false: Tool is only available when activated by a skill's related_tools
+     * - false: Tool is only available when enabled by a skill via `tools`
      */
     default?: boolean;
     /**
-     * For skill tools (learn_*): list of related tool names that become available
-     * when this skill is called. Used for dynamic tool discovery.
+     * For skill tools (`learn_*`): the tool names this skill enables when called.
+     * Matches the `tools:` key used in SKILL.md frontmatter and built-in skill
+     * definitions — one name across the whole stack.
      */
-    related_tools?: string[];
+    tools?: string[];
     /**
      * MCP tool annotations providing hints about tool behavior and safety.
      */
     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_*).
+     */
+    requires_user_confirmation?: boolean;
 }
 /**
  * Definition of a remote activity exposed by a tool server for use in DSL workflows.
@@ -277,9 +294,9 @@ export interface RemoteActivityDefinition {
     /** Description of what the activity does */
     description?: string;
     /** JSON Schema for the activity input parameters */
-    input_schema?: Record<string, any>;
+    input_schema?: Record<string, unknown>;
     /** JSON Schema for the activity output */
-    output_schema?: Record<string, any>;
+    output_schema?: Record<string, unknown>;
     /**
      * The activity execution URL. Can be absolute or relative to the tool server base URL.
      * If not provided, the collection-specific activities endpoint is used.
@@ -288,8 +305,279 @@ export interface RemoteActivityDefinition {
     /** Suggested timeout and retry configuration */
     options?: DSLActivityOptions;
 }
-export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'templates';
+export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates' | 'dashboards';
+/**
+ * Canonical runtime list of {@link AppCapabilities} — the app capabilities Studio
+ * renders/supports. Co-located with the type so TypeScript rejects any drift between
+ * the two. Consumers (publish manifest derivation, etc.) must use this rather than
+ * re-listing the values.
+ */
+export declare const APP_CAPABILITIES: readonly AppCapabilities[];
+/**
+ * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
+ * capability refs (`app:<app>:...`) against that version (candidate testing) instead of current.
+ * Resolution-time only; never persisted. Set by the generated app template via client.withAppVersion.
+ */
+export declare const APP_VERSION_HEADER = "x-vertesia-app-version";
+/**
+ * The platform-artifact types an app build can be required to create. A finer-grained
+ * counterpart to {@link AppCapabilities}: a single `interactions` capability may comprise
+ * several `interaction` artifacts plus `agent`, `activity`, and `tool` artifacts that
+ * {@link AppCapabilities} folds together. Used by the App Solution Architect manifest and
+ * the publish-time capability gate.
+ */
+export type AppArtifactType = 'interaction' | 'agent' | 'type' | 'process' | 'template' | 'dashboard' | 'activity' | 'tool';
+export declare const APP_ARTIFACT_TYPES: readonly AppArtifactType[];
+/**
+ * A single platform artifact the App Solution Architect requires the build to create.
+ * `id` is the app-owned in-code id the implementation must register and reference
+ * (e.g. `app:<name>:main:extract-item` for interactions/agents, `app:<name>:<type>` for
+ * types, `app:<name>:<process>` for processes).
+ */
+/**
+ * Build progress for one artifact, maintained by the developer agent as a living checklist:
+ *  - `pending` — defined by the architect, not yet built.
+ *  - `built`   — registered in the package, not yet successfully exercised.
+ *  - `done`    — built AND successfully exercised against real data.
+ * This is the agent's self-reported claim for tracking/handoff; the capability gate verifies
+ * the truth independently via package registration + run/data telemetry and does not trust it.
+ */
+export type AppArtifactStatus = 'pending' | 'built' | 'done';
+export declare const APP_ARTIFACT_STATUSES: readonly AppArtifactStatus[];
+export interface AppPlannedArtifact {
+    /** App-owned in-code id the build must register and reference. */
+    id: string;
+    type: AppArtifactType;
+    /** Short human label. */
+    name?: string;
+    /** Why this artifact exists / what it does — carried into the build checklist. */
+    purpose?: string;
+    /**
+     * When false, the artifact is planned but optional: the capability gate warns rather
+     * than blocks if it is missing or never exercised. Defaults to required (true).
+     */
+    required?: boolean;
+    /** Build progress, updated by the developer agent. Defaults to `pending`. */
+    status?: AppArtifactStatus;
+}
+/**
+ * Structured result the App Solution Architect emits alongside its prose artifacts — the
+ * machine-readable contract for the build. The implementation MUST create and successfully
+ * exercise every required artifact before preview/publish. Persisted into the app repo as
+ * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the publish-time
+ * capability gate can verify against it deterministically. If the builder finds the plan
+ * wrong or insufficient, the orchestrator relaunches the architect to revise the manifest;
+ * the gate always checks against the latest committed copy.
+ */
+export interface AppCapabilityManifest {
+    /** Artifact-storage ref to the prose architecture spec (e.g. the architecture `.md`). */
+    spec_artifact: string;
+    /** Platform artifacts the build must create. */
+    artifacts: AppPlannedArtifact[];
+    /**
+     * Monotonic revision, starting at 1, bumped each time the architect evolves the manifest for
+     * the SAME app on a later iteration (read the committed manifest, preserve untouched artifacts,
+     * add/modify/remove, then bump). Lets downstream agents tell which contract they are building to.
+     */
+    revision?: number;
+    /**
+     * Newest-first change notes, one entry per revision (what was added/modified/removed and why).
+     * How manifest changes are communicated to downstream agents across iterations.
+     */
+    changelog?: string[];
+    /** Optional free-form notes the architect wants the builder to honor. */
+    notes?: string;
+}
+/** Repo-relative path the capability manifest is committed to, read by the publish gate. */
+export declare const APP_CAPABILITY_MANIFEST_PATH = "docs/app-capability-manifest.json";
 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.
+ *
+ * - 'all' (default): every surface (UI portal, tool/endpoint use, contributions) requires
+ *   an explicit app_member ACE — the historical behavior.
+ * - 'ui': UI portal visibility requires an ACE, but tool/endpoint use and contributions
+ *   are open to anyone in the project.
+ * - 'none': fully open within the project — no ACE required for any surface.
+ *
+ * Declared on the manifest as the app's default. May be overridden per-installation.
+ */
+export type AppAccessControl = 'all' | 'ui' | 'none';
+/**
+ * Resolve the effective access_control policy for an installed app:
+ * installation override wins, then manifest default, then `'all'`.
+ *
+ * Shared by the STS (JWT generation), the studio-server (validation), and the UI (badge display)
+ * so the resolution rule lives in exactly one place. Named `effectiveAppAccessControl` (not just
+ * `effectiveAccessControl`) because exports from `@vertesia/common` are flattened — the broader
+ * name would risk colliding with other access-control families added later.
+ */
+export declare function effectiveAppAccessControl(installation: {
+    access_control?: AppAccessControl;
+} | null | undefined, manifest: {
+    access_control?: AppAccessControl;
+} | null | undefined): AppAccessControl;
 export interface AppManifestData {
     /**
      * The name of the app, used as the id in the system.
@@ -302,7 +590,7 @@ export interface AppManifestData {
      * - "private": visible only to the owning account
      * - "vertesia": visible only to Vertesia team members (any project)
      */
-    visibility: "public" | "private" | "vertesia";
+    visibility: 'public' | 'private' | 'vertesia';
     title: string;
     description: string;
     publisher: string;
@@ -315,7 +603,18 @@ export interface AppManifestData {
      * If not specified a random color will be picked.
      */
     color?: string;
-    status: "beta" | "stable" | "deprecated";
+    /**
+     * 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';
     /**
      * The UI configuration of the app. If not specified and the app "ui" is in the app capabilities
      * then the ui configuration will be fetched from the endpoint property.
@@ -325,7 +624,7 @@ export interface AppManifestData {
      * A list of tool collections endpoints to be used by this app.
      * Prefer using endpoint over tool_collections.
      */
-    tool_collections?: ToolCollection[];
+    tool_collections?: ToolCollectionObject[];
     /**
      * Named OAuth providers shared across multiple MCP tool collections.
      * Keys must be kebab-case identifiers. Each value is an MCPOAuthConfig blueprint.
@@ -362,6 +661,9 @@ export interface AppManifestData {
      * - tools
      * - 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").
@@ -377,18 +679,100 @@ export interface AppManifestData {
      * Only dev environment names are allowed as keys (starting with "desktop-" or "dev-").
      */
     endpoint_overrides?: Record<string, string>;
+    /**
+     * Optional app version string (e.g. "1.0.0") — informational.
+     */
+    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
+     * controls that don't apply to synthetic installations.
+     */
+    tags?: string[];
+    /**
+     * Access control policy for the app. Defaults to 'all' (ACE-gated everywhere)
+     * when undefined. See {@link AppAccessControl} for semantics. May be overridden
+     * on the AppInstallation.
+     */
+    access_control?: AppAccessControl;
+}
+export interface AppGitSourceConfig {
+    url?: string;
+    default_branch?: string;
+    production_branch?: string;
+    development_branch?: string;
+}
+export interface AppSourceConfig {
+    kind: 'git';
+    git?: AppGitSourceConfig;
 }
 /**
  * Returns true if the given environment name is allowed as an endpoint override key.
- * Only "desktop-" or "dev-" prefixed names are valid.
+ * Any non-empty name is accepted except the reserved shared-deployment names.
  */
 export declare function isValidEndpointOverrideEnv(envName: string): boolean;
 /**
- * Resolves the effective endpoint for an app given an optional environment name.
- * Returns the override endpoint if the env name matches a valid dev environment, otherwise the default endpoint.
+ * Deployment-time URL endpoints that can be referenced in app manifest URLs
+ * via `{{key}}` placeholders. The caller (typically studio-server) supplies
+ * these from environment config so that system apps can ship a single manifest
+ * with endpoints like `{{studio}}/api/package` that resolve per deployment.
+ */
+export interface Endpoints {
+    /** The Studio API (studio-server) base URL */
+    studio?: string;
+    /** The Store API (zeno-server) base URL */
+    store?: string;
+    /** The token server base URL */
+    token?: string;
+    /** The browser-facing Studio UI (composable-ui) base URL */
+    ui?: string;
+    /** The Smart HTTP app source git server base URL */
+    git?: string;
+    /** The appgen app-gateway base URL (serves published app bundles + their `/api` runtime). */
+    gateway?: string;
+}
+/**
+ * Substitutes `{{key}}` placeholders in a URL with the matching endpoint.
+ * Unknown placeholders are left untouched (so failures surface as fetch errors
+ * with the unresolved placeholder visible, rather than silently pointing nowhere).
+ * Trailing slashes on replacement values are stripped to avoid `//api/...` joins.
+ */
+export declare function substituteEndpoints(url: string, endpoints?: Endpoints): string;
+/**
+ * Resolves the effective endpoint for an app.
+ *
+ * Order of resolution:
+ * 1. If `requestedOverride` matches an `endpoint_overrides` key, use that URL
+ *    (caller must verify the user is allowed to use the override).
+ * 2. Else if `envName` matches an `endpoint_overrides` key, use that URL
+ *    (auto-resolution from the studio-server's deployment env).
+ * 3. Otherwise use the main `endpoint`.
+ * 4. Apply `{{var}}` substitution using `vars`.
  */
-export declare function resolveAppEndpoint(manifest: Pick<AppManifestData, 'endpoint' | 'endpoint_overrides'>, envName?: string): string | undefined;
-export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'templates' | 'settings' | 'widgets' | 'activities' | 'all';
+export declare function resolveAppEndpoint(manifest: Pick<AppManifestData, 'endpoint' | 'endpoint_overrides'>, envName?: string, vars?: Endpoints, requestedOverride?: string): string | undefined;
+/**
+ * Resolves all URL placeholders in a manifest in place (both `endpoint` and
+ * `tool_collections[].url`). Intended for server-side serialization — clients and
+ * downstream workers receive already-substituted URLs so they don't need to know
+ * about deployment-time vars.
+ *
+ * Mutates the manifest rather than returning a copy so it works cleanly with
+ * Mongoose populated subdocs.
+ */
+export declare function resolveManifestUrls(manifest: Partial<AppManifestData> | null | undefined, envName?: string, vars?: Endpoints, requestedOverride?: string): void;
+export type AppPackageScope = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates' | 'dashboards' | 'settings' | 'widgets' | 'activities' | 'all';
+/**
+ * Canonical runtime list of {@link AppPackageScope} — every package scope, including the
+ * catch-all `'all'`. Co-located with the type so TypeScript rejects drift. Consumers (the
+ * /package?scope= parser, the inspection report) must use this rather than re-listing.
+ */
+export declare const APP_PACKAGE_SCOPES: readonly AppPackageScope[];
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -398,6 +782,13 @@ export interface AppPackage {
      * A list of tools exposed by the app.
      */
     tools?: AgentToolDefinition[];
+    /**
+     * A list of skills (`learn_*` tools) exposed by the app. Kept separate from
+     * `tools` so clients can render them distinctly — consumers that don't care
+     * (e.g. the worker building a combined tool registry) should concatenate
+     * the two lists.
+     */
+    skills?: AgentToolDefinition[];
     /**
      * A list of interactions exposed by the app
      */
@@ -406,10 +797,18 @@ export interface AppPackage {
      * A list of types.
      */
     types?: InCodeTypeDefinition[];
+    /**
+     * A list of process definitions exposed by the app.
+     */
+    processes?: InCodeProcessDefinition[];
     /**
      * Templates provided by the app.
      */
     templates?: RenderingTemplateDefinitionRef[];
+    /**
+     * Dashboards provided by the app.
+     */
+    dashboards?: AppDashboardDefinition[];
     /**
      * Widgets provided by the app.
      */
@@ -425,6 +824,58 @@ 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;
@@ -498,7 +949,7 @@ export interface AppInstallation {
     id: string;
     project: string;
     manifest: string;
-    settings?: Record<string, any>;
+    settings?: Record<string, unknown>;
     /**
      * Admin-managed allowlist of tool names permitted for this installation.
      * When undefined, all tools from the app are permitted.
@@ -517,6 +968,12 @@ export interface AppInstallation {
      * Multiple collections sharing the same provider all resolve to the same OAuth provider.
      */
     provider_bindings?: AppInstallationProviderBinding[];
+    /**
+     * Per-installation override of the manifest's access_control policy.
+     * When set, takes precedence over the manifest value. When undefined, the
+     * manifest value (or 'all' default) applies.
+     */
+    access_control?: AppAccessControl;
     created_at: string;
     updated_at: string;
 }
@@ -545,7 +1002,20 @@ export type AppOAuthCollectionParams = Record<string, OAuthClientCredentials>;
 export type AppOAuthProviderParams = Record<string, OAuthClientCredentials>;
 export interface AppInstallationPayload {
     app_id: string;
-    settings?: Record<string, any>;
+    settings?: Record<string, unknown>;
+    /**
+     * Per-installation override of the manifest's `access_control` policy. When provided, takes precedence
+     * over the manifest default for every access check. Sibling of `settings` — admin-controlled, not
+     * part of the app's own settings JSON.
+     *
+     * Three send-time semantics on update:
+     *  - Field omitted entirely from the payload → leave the existing override unchanged.
+     *  - Explicit `null` → clear the override, fall back to the manifest default.
+     *  - String enum → set the override to that value.
+     *
+     * (On install, the same shape applies; omit or pass `null` to use the manifest default.)
+     */
+    access_control?: AppAccessControl | null;
     /**
      * OAuth credentials for each collection, keyed by collection.id.
      * Legacy callers may still use collection.name for older manifests.
@@ -605,7 +1075,7 @@ export interface ProjectToolInfo {
      * The app installation settings.
      * Only included for agent tokens, not user tokens (security: may contain API keys).
      */
-    settings?: Record<string, any>;
+    settings?: Record<string, unknown>;
 }
 /**
  * OAuth authentication status for an MCP tool collection
@@ -676,7 +1146,7 @@ export interface CompositeAppLogoOverrides {
 }
 /**
  * Message banner overrides for the shell header.
-*/
+ */
 export type CompositeAppMessageStyle = 'foreground' | 'info' | 'success' | 'attention' | 'destructive';
 export interface CompositeAppMessageOverrides {
     /** Message text to display */
@@ -763,7 +1233,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[];
 }
 /**
@@ -826,7 +1296,7 @@ export interface CompositeAppConfig {
     /**
      * The unique identifier for this CompositeApp configuration
      * Undefined if the configuration doesn't exists yet.
-    */
+     */
     id?: string;
     /** The project this CompositeApp belongs to */
     project: string;
@@ -864,4 +1334,21 @@ 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[];
+}
 export {};
+//# sourceMappingURL=apps.d.ts.map