@vertesia/common 1.5.0-dev.20260714.072725Z → 1.5.0-dev.20260722.120446Z

package/lib/apikey.d.ts

@@ -125,6 +125,7 @@ export interface AuthTokenPayload {
         studio: string;
         store: string;
         token?: string;
+        git?: string;
     };
     iss: string;
     aud: string;

package/lib/apikey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apikey.d.ts","sourceRoot":"","sources":["../src/apikey.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apikey.d.ts","sourceRoot":"","sources":["../src/apikey.ts"],"names":[],"mappings":"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"}

package/lib/apikey.js.map

@@ -1 +1 @@
-{"version":3,"file":"apikey.js","sourceRoot":"","sources":["../src/apikey.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAN,IAAY,WAEX;AAFD,WAAY,WAAW;IACnB,4BAAa,CAAA;AACjB,CAAC,EAFW,WAAW,KAAX,WAAW,QAEtB;AAgJD,MAAM,CAAN,IAAY,aAQX;AARD,WAAY,aAAa;IACrB,8BAAa,CAAA;IACb,6CAA4B,CAAA;IAC5B,gCAAe,CAAA;IACf,kCAAiB,CAAA;IACjB,mDAAkC,CAAA;IAClC,gCAAe,CAAA;IACf,sCAAqB,CAAA;AACzB,CAAC,EARW,aAAa,KAAb,aAAa,QAQxB"}
+{"version":3,"file":"apikey.js","sourceRoot":"","sources":["../src/apikey.ts"],"names":[],"mappings":"AA8BA,MAAM,CAAN,IAAY,WAEX;AAFD,WAAY,WAAW;IACnB,4BAAa,CAAA;AACjB,CAAC,EAFW,WAAW,KAAX,WAAW,QAEtB;AAiJD,MAAM,CAAN,IAAY,aAQX;AARD,WAAY,aAAa;IACrB,8BAAa,CAAA;IACb,6CAA4B,CAAA;IAC5B,gCAAe,CAAA;IACf,kCAAiB,CAAA;IACjB,mDAAkC,CAAA;IAClC,gCAAe,CAAA;IACf,sCAAqB,CAAA;AACzB,CAAC,EARW,aAAa,KAAb,aAAa,QAQxB"}

package/lib/apps.d.ts

@@ -1,6 +1,8 @@
 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';
+import type { InCodeViewDefinition } from './views.js';
 /** Allowed values for AppUINavItem.preferredSection */
 export declare const PREFERRED_SECTIONS: readonly ["default", "footer", "settings"];
 /**
@@ -314,8 +316,315 @@ export interface RemoteActivityDefinition {
     /** Suggested timeout and retry configuration */
     options?: DSLActivityOptions;
 }
-export type AppCapabilities = 'ui' | 'tools' | 'interactions' | 'types' | 'processes' | 'templates';
+/**
+ * Canonical app capabilities Studio renders/supports. The public type is derived from
+ * this list so runtime validation and TypeScript cannot drift.
+ */
+export declare const APP_CAPABILITIES: readonly ["ui", "tools", "interactions", "types", "processes", "views", "templates", "dashboards"];
+export type AppCapabilities = (typeof APP_CAPABILITIES)[number];
+/**
+ * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
+ * capability refs (`app:<app>:...`) against that exact version instead of the promoted version.
+ * 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 declare const APP_ARTIFACT_TYPES: readonly ["interaction", "agent", "type", "process", "view", "template", "dashboard", "activity", "tool"];
+export type AppArtifactType = (typeof APP_ARTIFACT_TYPES)[number];
+/**
+ * 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 building a deployable version. Persisted into the app repo as
+ * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the version-build
+ * 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 version-build gates. */
+export declare const APP_CAPABILITY_MANIFEST_PATH = "docs/app-capability-manifest.json";
 export type AppAvailableIn = 'app_portal' | 'composite_app';
+export type AppVersionKind = 'design' | 'version';
+export type AppVersionState = 'ready' | 'failed' | 'expired';
+export type AppVersionTarget = 'static' | 'service';
+export type AppVersionGitRefType = 'branch' | 'tag' | 'commit' | 'detached';
+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. Immutable
+     * app versions use the exact commit SHA rather than a mutable branch or tag.
+     */
+    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;
+    promoted?: boolean;
+    target?: AppVersionTarget;
+    agent_run_id?: string;
+    /** Temporal workflow that produced this version. */
+    build_workflow_id?: string;
+    /** Temporal run that produced this version. */
+    build_workflow_run_id?: string;
+    sandbox_id?: string;
+    title?: string;
+    description?: string;
+    storage?: AppVersionStorage;
+    /** Exact Git commit used to build this immutable version. */
+    source_commit?: string;
+    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;
+    built_at?: string;
+    checked_at?: string;
+    expires_at?: string;
+}
+export interface DeleteAppVersionResponse {
+    id: string;
+    app_id: string;
+    version_id: string;
+    storage_prefix?: string;
+    deleted: boolean;
+    warnings: string[];
+}
+export interface UpsertAppVersionRequest {
+    /** Existing version record to update in place, used by reproducible rebuilds. */
+    record_id?: string;
+    app?: string;
+    app_id: string;
+    app_name?: string;
+    version_id: string;
+    kind: AppVersionKind;
+    state?: AppVersionState;
+    target?: AppVersionTarget;
+    agent_run_id?: string;
+    build_workflow_id?: string;
+    build_workflow_run_id?: string;
+    sandbox_id?: string;
+    title?: string;
+    description?: string;
+    storage?: AppVersionStorage;
+    /** Exact Git commit used to build this immutable version. */
+    source_commit?: string;
+    urls?: AppVersionUrls;
+    manifest?: Record<string, unknown>;
+    files?: string[];
+    file_count?: number;
+    source_file_count?: number;
+    screenshot_artifact?: string;
+    checks?: string[];
+    built_at?: string;
+    checked_at?: string;
+    expires_at?: string;
+}
+export interface AppVersionListQuery {
+    app_id?: string;
+    kind?: AppVersionKind;
+    include_expired?: boolean;
+    limit?: number;
+}
+export interface PromoteAppVersionResponse {
+    version: AppVersionRecord;
+    app?: AppManifest;
+}
+export interface StartAppBuildRequest {
+    /**
+     * Source branch, tag, or commit to build. When omitted, the app source
+     * configuration chooses its default branch.
+     */
+    source_ref?: string;
+    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
+    trigger?: AppBuildTrigger;
+    target?: AppVersionTarget;
+    title?: string;
+    description?: string;
+}
+export interface StartAppBuildResponse {
+    workflow_id: string;
+    run_id: string;
+    app_id: string;
+    version_id?: string;
+    rebuild_version_record_id?: string;
+    source_ref?: string;
+    source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
+}
+export interface AppBuildWorkflowInput extends StartAppBuildRequest {
+    app_id: string;
+    app_record_id?: string;
+    /** Rebuild this persisted version record at its original commit and target. */
+    rebuild_version_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, 'version'>;
+    state: AppVersionState;
+    source_commit: string;
+    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;
+    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;
+}
+export type AppScaffoldModule = 'service' | 'assistant' | 'content-app' | 'examples';
+export interface StartAppScaffoldRequest {
+    /**
+     * App id / package name to create. It is normalized to the same slug rules
+     * used by @vertesia/create-plugin.
+     */
+    app_id: string;
+    title?: string;
+    description?: string;
+    modules?: AppScaffoldModule[];
+    /**
+     * Start an initial app version build after the source has been pushed.
+     * Defaults to true.
+     */
+    create_version?: boolean;
+}
+export interface StartAppScaffoldResponse {
+    workflow_id: string;
+    run_id: string;
+    app_id: string;
+    app_record_id?: string;
+    git_url?: string;
+    create_version: boolean;
+}
+export interface AppScaffoldWorkflowInput extends StartAppScaffoldRequest {
+}
+export interface AppScaffoldWorkflowResult {
+    app_id: string;
+    app_record_id?: string;
+    git_url?: string;
+    source_git?: AppVersionGitSource;
+    files?: number;
+    initial_version_build?: StartAppBuildResponse;
+}
+export type AppScaffoldProgressStatus = 'queued' | 'reserving' | 'scaffolding' | 'pushing' | 'building' | 'completed' | 'failed';
+export interface AppScaffoldProgress {
+    status: AppScaffoldProgressStatus;
+    step: string;
+    app_id?: string;
+    app_record_id?: string;
+    git_url?: string;
+    files?: number;
+    initial_version_build?: StartAppBuildResponse;
+    error?: string;
+    error_details?: string[];
+    updated_at: string;
+}
 /**
  * Access control policy for an app installation.
  * Declares which access surfaces are gated by per-user ACEs.
@@ -368,6 +677,17 @@ export interface AppManifestData {
      * If not specified a random color will be picked.
      */
     color?: string;
+    /**
+     * Optional preview screenshot for the app-management UI, captured by the builder during a
+     * build/QA run. Resolved client-side from the owning agent run's artifact storage, so it
+     * carries both the run id and the artifact path.
+     */
+    preview_screenshot?: {
+        /** Agent run id whose artifact storage holds the screenshot. */
+        agent_run_id: string;
+        /** Artifact path within that storage, e.g. "preview-checks/app-preview-<ts>.png". */
+        artifact: string;
+    };
     status: 'beta' | 'stable' | 'deprecated';
     /**
      * The UI configuration of the app. If not specified and the app "ui" is in the app capabilities
@@ -416,6 +736,8 @@ export interface AppManifestData {
      * - interactions
      * - types
      * - processes
+     * - templates
+     * - dashboards
      * - settings
      * - all (the default if no scope is provided)
      *  You can also use comma-separated values to combine scopes (e.g. "ui,tools").
@@ -435,6 +757,13 @@ export interface AppManifestData {
      * 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 development lanes; immutable app versions
+     * record their exact source commit in AppVersionRecord.source_commit and
+     * 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
@@ -448,11 +777,16 @@ export interface AppManifestData {
      */
     access_control?: AppAccessControl;
 }
-/**
- * Returns true if the given environment name is allowed as an endpoint override key.
- * Any non-empty name is accepted except the reserved shared-deployment names.
- */
-export declare function isValidEndpointOverrideEnv(envName: string): boolean;
+export interface AppGitSourceConfig {
+    url?: string;
+    default_branch?: string;
+    production_branch?: string;
+    development_branch?: string;
+}
+export interface AppSourceConfig {
+    kind: 'git';
+    git?: AppGitSourceConfig;
+}
 /**
  * Deployment-time URL endpoints that can be referenced in app manifest URLs
  * via `{{key}}` placeholders. The caller (typically studio-server) supplies
@@ -468,37 +802,92 @@ export interface Endpoints {
     token?: string;
     /** The browser-facing Studio UI (composable-ui) base URL */
     ui?: string;
+    /** The Smart HTTP app source git server base URL */
+    git?: string;
+    /** The appgen app-gateway base URL (serves promoted app bundles + their `/api` runtime). */
+    gateway?: string;
+}
+/** One entry in an app git-repo directory listing (see {@link AppRepoTree}). */
+export interface AppRepoTreeEntry {
+    /** File or directory name (last path segment). */
+    name: string;
+    /** Path relative to the repo root. */
+    path: string;
+    /** Whether the entry is a file (`blob`) or a directory (`tree`). */
+    type: 'blob' | 'tree';
+}
+/** A non-recursive listing of an app git repo directory at a given ref. */
+export interface AppRepoTree {
+    /** The ref the listing was read at (empty/undefined = default branch / HEAD). */
+    ref?: string;
+    /** The directory prefix that was listed (empty = repo root). */
+    prefix?: string;
+    entries: AppRepoTreeEntry[];
+}
+/** Browser-side limits mirrored by the app Git service document endpoint. */
+export declare const APP_REPO_DOCUMENT_UPLOAD_MAX_FILE_BYTES: number;
+export declare const APP_REPO_DOCUMENT_UPLOAD_MAX_TOTAL_BYTES: number;
+export declare const APP_REPO_DOCUMENT_UPLOAD_MAX_FILES = 20;
+export declare const APP_REPO_DOCUMENT_UPLOAD_PREFIX = "docs/";
+/** Result of committing one or more uploaded documents to an app repository. */
+export interface AppRepoDocumentCommit {
+    /** Updated branch name. */
+    ref: string;
+    /** Branch HEAD before the commit. */
+    previous_commit: string;
+    /** Newly created commit SHA. */
+    commit: string;
+    /** Repository paths changed by the commit. */
+    paths: string[];
+}
+/** One commit that inserted or changed a file in an app git repository. */
+export interface AppRepoCommit {
+    /** Full commit SHA. */
+    commit: string;
+    /** Complete commit message. */
+    message: string;
+    /** Commit author name, when available. */
+    author?: string;
+    /** Commit author date as an ISO-8601 string, when available. */
+    date?: string;
+}
+/** Commit history in an app git repository, optionally filtered to a file. */
+export interface AppRepoCommits {
+    /** Ref from which history traversal started (empty/undefined = default branch / HEAD). */
+    ref?: string;
+    /** File path relative to the repository root, when history was filtered to a file. */
+    path?: string;
+    /** Commits ordered newest first. */
+    commits: AppRepoCommit[];
+    /** Pass this cursor to retrieve the next page. Absent when history is exhausted. */
+    next_cursor?: string;
+}
+/** A branch or tag in an app git repo, resolved to its latest commit. */
+export interface AppRepoRef {
+    /** Short ref name (e.g. `main`, `v1.0.0`). */
+    name: string;
+    /** Commit hash the ref points at (annotated tags are peeled to their commit). */
+    commit: string;
+    /** First line of the commit message, when available. */
+    commit_subject?: string;
+    /** Commit date as an ISO-8601 string, when available. */
+    commit_date?: string;
+    /** Commit author name, when available. */
+    commit_author?: string;
+}
+/** The branches and tags of an app git repo (see {@link AppRepoRef}). */
+export interface AppRepoRefs {
+    /** The repository's default branch (HEAD target), when resolvable. */
+    default_branch?: string;
+    branches: AppRepoRef[];
+    tags: AppRepoRef[];
 }
 /**
- * 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, 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.
+ * Canonical package scopes, including the catch-all `all`. The public type is derived
+ * from this list so request parsing and TypeScript cannot drift.
  */
-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' | 'settings' | 'widgets' | 'activities' | 'all';
+export declare const APP_PACKAGE_SCOPES: readonly ["ui", "tools", "interactions", "types", "processes", "views", "templates", "dashboards", "settings", "widgets", "activities", "all"];
+export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -527,10 +916,18 @@ export interface AppPackage {
      * A list of process definitions exposed by the app.
      */
     processes?: InCodeProcessDefinition[];
+    /**
+     * View Experiences exposed by the app as in-code definitions.
+     */
+    views?: InCodeViewDefinition[];
     /**
      * Templates provided by the app.
      */
     templates?: RenderingTemplateDefinitionRef[];
+    /**
+     * Dashboards provided by the app.
+     */
+    dashboards?: AppDashboardDefinition[];
     /**
      * Widgets provided by the app.
      */
@@ -546,6 +943,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 promoted 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 promoted 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 promoted 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 promoted 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;
@@ -587,6 +1036,7 @@ export interface AppManifestSource {
     git: {
         url: string;
         default_branch?: string;
+        production_branch?: string;
         development_branch?: string;
     };
 }
@@ -1072,5 +1522,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