@vertesia/appgen-docs 1.5.0-dev.20260804.124748Z → 1.5.0-dev.20260807.073259Z

package/lib/docs/app-package-patterns.md

@@ -18,7 +18,7 @@ For package-only checks during authoring, run:
 pnpm run service:build:server
 ```
 
-The output must list the package artifacts. If an expected type, interaction, prompt, process, view, dashboard, template, widget, activity, tool, or seed script is missing from the summary, fix the exports before publishing.
+The output must list the package artifacts. If an expected type, interaction, prompt, process, view, dashboard, template, widget, activity, hook, subscription, tool, or seed script is missing from the summary, fix the exports before publishing.
 
 ## ServerConfig Checklist
 
@@ -29,9 +29,12 @@ import type { ToolServerConfig } from '@vertesia/tools-sdk';
 import {
   activities,
   dashboards,
+  hooks,
   interactions,
+  mcpProviders,
   processes,
   skills,
+  subscriptions,
   templates,
   tools,
   types,
@@ -49,9 +52,17 @@ export const ServerConfig = {
   dashboards,
   processes,
   views,
+  hooks,
+  subscriptions,
+  mcpProviders,
 } satisfies ToolServerConfig;
 ```
 
+The app module must provide a typed empty default for every supported contribution kind, even when the app does not
+currently register one. When adding a new contribution kind to the template, export its default from
+`src/modules/app/resources`, add it to the codegen `SERVER_RESOURCES` list, and let codegen regenerate
+`src/tool-server/app-server-modules.ts`. Do not put app-owned registries directly under `src/tool-server`.
+
 If a capability is authored in source but absent from the package summary, check that:
 
 1. the capability collection exports from its own `index.ts`

package/lib/docs/tool-server-resource.md

@@ -14,6 +14,9 @@ Full code examples for each resource type. SKILL.md has the workflow and decisio
 - [Interaction (code-based)](#interaction-code-based)
 - [Content Type](#content-type)
 - [Rendering Template](#rendering-template)
+- [Application lifecycle hooks](#application-lifecycle-hooks)
+- [Application event hooks](#application-event-hooks)
+- [Application event subscriptions](#application-event-subscriptions)
 - [Collection registration & icons](#collection-registration--icons)
 
 ---
@@ -373,6 +376,148 @@ export const MyTemplates = new RenderingTemplateCollection({
 
 ---
 
+## Application lifecycle hooks
+
+Lifecycle hooks are authenticated server handlers, not resource collections. They remain app-owned module
+contributions. Use them when installation must initialize project data or uninstallation must clean it up. Keep install
+hooks idempotent because they may be invoked again for recovery or reinstallation.
+
+### `src/modules/app/resources/hooks/install.ts`
+
+```typescript
+import type { AppLifecycleHook } from "@vertesia/tools-sdk";
+
+export const install = (async (context) => {
+    const client = await context.getClient();
+    const project = context.payload.project;
+    if (!project) throw new Error("Install hooks require a project-scoped token");
+    const installationId = context.metadata.app_install_id;
+    const settings = context.metadata.app_settings;
+
+    // Query existing project state first and create only what is missing.
+    console.log("Installing app", { projectId: project.id, installationId, settings });
+    void client;
+}) satisfies AppLifecycleHook;
+```
+
+An uninstall hook has the same signature and belongs in `src/modules/app/resources/hooks/uninstall.ts`.
+
+### Registration
+
+```typescript
+// src/modules/app/resources/hooks/index.ts
+import type { AppHookDefinition } from "@vertesia/tools-sdk";
+import { install } from "./install.js";
+
+export const hooks = [
+    { kind: "lifecycle", name: "install", handler: install },
+] satisfies AppHookDefinition[];
+```
+
+Registered hooks are exposed as authenticated POST endpoints at `/api/hooks/install` and `/api/hooks/uninstall`. The
+app package advertises their endpoint paths under `hooks` for inspection. Studio invokes the conventional endpoints
+directly and treats a 404 as an absent optional hook.
+
+Building an immutable version advertises these definitions but does not execute them. Studio runs the promoted
+version's install hook during promotion reconciliation and runs the previous promoted version's uninstall hook when
+it is replaced or removed. For an unpromoted candidate, validate source registration and package output only; do not
+invoke lifecycle endpoints manually or fail candidate QA because their side effects are absent.
+
+In an appgen capability manifest, declare lifecycle hooks with type `hook` and ids such as
+`app:<app-name>:install` and `app:<app-name>:uninstall`.
+
+Do not create project-local copies of app-owned package type definitions. When hooks create content objects, use the
+portable `app:<app-name>:<type-name>` type reference.
+
+---
+
+## Application event hooks
+
+Event hooks are authenticated webhook handlers for platform event deliveries. Their payload is the standard event
+envelope `{ event, delivery: { id, subscription_id, attempt } }`, and their context exposes the caller token,
+decoded token payload, and `getClient()`.
+
+### `src/modules/app/resources/hooks/content-updated.ts`
+
+```typescript
+import type { AppEventHook } from "@vertesia/tools-sdk";
+
+export const contentUpdated = (async ({ event, delivery }, context) => {
+    const client = await context.getClient();
+    console.log("Processing event", {
+        eventId: event.event_id,
+        category: event.event_category,
+        action: event.action,
+        resourceId: event.resource_id,
+        deliveryId: delivery.id,
+    });
+    void client;
+}) satisfies AppEventHook;
+```
+
+### Registration
+
+```typescript
+import type { AppHookDefinition } from "@vertesia/tools-sdk";
+import { contentUpdated } from "./content-updated.js";
+
+export const hooks = [
+    {
+        kind: "event",
+        name: "content-updated",
+        description: "Processes updated content objects.",
+        handler: contentUpdated,
+    },
+] satisfies AppHookDefinition[];
+```
+
+Event hook names must be kebab-case URL-safe segments. `install` and `uninstall` are reserved. The example is exposed
+at `POST /api/hooks/content-updated` and advertised by `/api/package?scope=hooks`.
+Represent it in an appgen capability manifest as a `hook` artifact such as
+`app:<app-name>:content-updated`.
+
+---
+
+## Application event subscriptions
+
+Subscriptions are declarative package contributions that route matching platform events to an event hook in the same
+app. They do not contain a deployment URL or project scope. Studio derives both from the version selected during
+promotion.
+
+```typescript
+// src/modules/app/resources/subscriptions/index.ts
+import type { AppEventSubscriptionDefinition } from "@vertesia/tools-sdk";
+
+export const subscriptions = [
+    {
+        id: "content-updated",
+        name: "Content updated",
+        description: "Refresh app-owned projections after content changes.",
+        hook: "content-updated",
+        filter: {
+            action: ["update"],
+            resource_type: ["content_object"],
+        },
+        run_as_role: "automation",
+        enabled: true,
+        priority: "normal",
+    },
+] satisfies AppEventSubscriptionDefinition[];
+```
+
+The `hook` value must match the `name` of a registered event hook. Package generation rejects missing hooks,
+lifecycle hooks, duplicate subscription ids, and ids that are not kebab-case. Multiple subscriptions may reference
+the same event hook with different filters. Inspect the result with `GET /api/package?scope=subscriptions`.
+Represent each definition in an appgen capability manifest as a `subscription` artifact such as
+`app:<app-name>:content-updated`.
+
+An unpromoted candidate exposes these package definitions but does not create protected Event Bus subscriptions, and
+matching events are not delivered to that candidate's hook. Candidate validation is therefore limited to source and
+package-summary wiring. Use Event Bus subscription and delivery evidence only after the version has been explicitly
+promoted.
+
+---
+
 ## Collection registration & icons
 
 ### Adding a collection to its type's index

package/lib/docs/ui-interfaces.d.ts

@@ -76,8 +76,8 @@ export * from './tooltip';
 import { type VariantProps } from 'class-variance-authority';
 import * as React from 'react';
 declare const variants: (props?: ({
-    size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
-    variant?: "default" | "legacy" | "unstyled" | "noPadding" | null | undefined;
+    size?: "lg" | "md" | "sm" | "xl" | "xs" | null | undefined;
+    variant?: "default" | "legacy" | "noPadding" | "unstyled" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 type InputVariant = 'default' | 'unstyled' | 'noPadding' | 'legacy';
 export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'onChange'> {
@@ -102,8 +102,8 @@ export { Input };
 import { type VariantProps } from 'class-variance-authority';
 import * as React from 'react';
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "destructive" | "outline" | "secondary" | "ghost" | "primary" | "unstyled" | null | undefined;
-    size?: "xs" | "sm" | "md" | "lg" | "xl" | "none" | "icon" | null | undefined;
+    variant?: "destructive" | "ghost" | "link" | "outline" | "primary" | "secondary" | "unstyled" | null | undefined;
+    size?: "icon" | "lg" | "md" | "none" | "sm" | "xl" | "xs" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;
@@ -150,7 +150,7 @@ export { Button, buttonVariants, CopyButton };
 import { type VariantProps } from 'class-variance-authority';
 import type * as React from 'react';
 declare const badgeVariants: (props?: ({
-    variant?: "done" | "default" | "destructive" | "outline" | "secondary" | "success" | "attention" | "info" | null | undefined;
+    variant?: "attention" | "default" | "destructive" | "done" | "info" | "outline" | "secondary" | "success" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface BaseBadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
     children: React.ReactNode;
@@ -158,7 +158,7 @@ interface BaseBadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantP
 }
 export declare function Badge({ className, variant, children, onClick, ...props }: BaseBadgeProps): React.JSX.Element;
 declare const dotBadgeVariants: (props?: ({
-    variant?: "done" | "default" | "destructive" | "outline" | "success" | "attention" | "info" | null | undefined;
+    variant?: "attention" | "default" | "destructive" | "done" | "info" | "outline" | "success" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface DotBadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof dotBadgeVariants> {
     children?: React.ReactNode;
@@ -743,12 +743,13 @@ interface FlexibleHeightLayoutProps {
 }
 export declare function FullHeightLayout({ className, children }: FlexibleHeightLayoutProps): React.JSX.Element;
 export declare namespace FullHeightLayout {
-    var Fixed: ({ heightClass, className, children }: FixedProps) => React.JSX.Element;
-    var Body: ({ className, children }: BodyProps) => React.JSX.Element;
-    var VR: () => React.JSX.Element;
-    var HR: () => React.JSX.Element;
-    var Flex: ({ className, children }: BodyProps) => React.JSX.Element;
-    var Tab: ({ children }: {
+    export var Fixed: ({ heightClass, className, children }: FixedProps) => React.JSX.Element;
+    var _a: ({ className, children }: BodyProps) => React.JSX.Element;
+    export { _a as Body };
+    export var VR: () => React.JSX.Element;
+    export var HR: () => React.JSX.Element;
+    export var Flex: ({ className, children }: BodyProps) => React.JSX.Element;
+    export var Tab: ({ children }: {
         children: React.ReactNode;
     }) => React.JSX.Element;
 }
@@ -783,7 +784,7 @@ export declare function SidebarSection({ children, title, action, isFooter, clas
 export declare function SidebarTooltip({ children, text }: {
     children: React.ReactNode;
     text?: string;
-}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | null | undefined;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | Iterable<import("react").ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
 export interface SidebarItemIconProps {
     className?: string;
     'aria-hidden'?: boolean | 'true' | 'false';
@@ -940,9 +941,9 @@ declare class UserSession {
         name: string;
     } | undefined;
     get project(): {
-        account: string;
         id: string;
         name: string;
+        account: string;
         restricted?: boolean | undefined;
     } | undefined;
     get accounts(): {

package/lib/docs/vertesia-client.d.ts

@@ -157,9 +157,9 @@ export declare class VertesiaClient extends AbstractFetchClient<VertesiaClient>
     getRawJWT(): Promise<string | null>;
     getDecodedJWT(): Promise<AuthTokenPayload | null>;
     getProject(): Promise<{
-        account: string;
         id: string;
         name: string;
+        account: string;
         restricted?: boolean | undefined;
     } | null>;
     getAccount(): Promise<{
@@ -234,7 +234,7 @@ export declare function decodeEndpoints(endpoints: string | Record<string, strin
 // @vertesia/client: AppsApi.d.ts
 // -----------------------------------------------------------------------------
 import { ApiTopic, type ClientBase } from '@vertesia/api-fetch-client';
-import type { AppBuildProgress, AppDeleteSummary, AppDevelopmentTaskDetails, AppDevelopmentTaskList, AppInspectionResult, AppInstallation, AppInstallationKind, AppInstallationListEntry, AppInstallationPayload, AppInstallationWithManifest, AppManifest, AppManifestData, AppPackage, AppPackageScope, AppRepoBranch, AppRepoCommits, AppRepoDocumentCommit, AppRepoRefs, AppRepoTree, AppScaffoldProgress, AppToolCollection, AppVersionListQuery, AppVersionRecord, CountResult, CreateAppRepoBranchRequest, DeleteAppVersionResponse, ProjectRef, PromoteAppVersionResponse, RequireAtLeastOne, StartAppBuildRequest, StartAppBuildResponse, StartAppScaffoldRequest, StartAppScaffoldResponse, UpsertAppVersionRequest, ValidateUrlResponse } from '@vertesia/common';
+import type { AppApiKeyCollectionParams, AppBuildProgress, AppDeleteSummary, AppDevelopmentTaskDetails, AppDevelopmentTaskList, AppInspectionResult, AppInstallation, AppInstallationKind, AppInstallationListEntry, AppInstallationPayload, AppInstallationWithManifest, AppManifest, AppManifestData, AppPackage, AppPackageScope, AppRepoBranch, AppRepoCommits, AppRepoDocumentCommit, AppRepoRefs, AppRepoTree, AppScaffoldProgress, AppToolCollection, AppVersionListQuery, AppVersionRecord, CountResult, CreateAppRepoBranchRequest, DeleteAppVersionResponse, McpApiKeyStatus, ProjectRef, PromoteAppVersionResponse, RequireAtLeastOne, StartAppBuildRequest, StartAppBuildResponse, StartAppScaffoldRequest, StartAppScaffoldResponse, UpsertAppVersionRequest, ValidateUrlResponse } from '@vertesia/common';
 export interface OrphanedAppInstallation extends Omit<AppInstallation, 'manifest'> {
     manifest: null;
 }
@@ -247,6 +247,16 @@ export default class AppsApi extends ApiTopic {
      * which the server treats as a dry-run and returns counts + paths.
      */
     previewDelete(id: string): Promise<AppDeleteSummary>;
+    /**
+     * Store the API key of an MCP tool collection declared with `auth: 'api_key'`.
+     * The key is write-only: it is encrypted server-side and never returned by any endpoint,
+     * so the response carries only the configured flag and a masked hint.
+     */
+    setMcpCollectionApiKey(appId: string, collectionId: string, apiKey: string): Promise<McpApiKeyStatus>;
+    /** Whether an MCP tool collection has an API key stored, with a masked hint for display. */
+    getMcpCollectionApiKeyStatus(appId: string, collectionId: string): Promise<McpApiKeyStatus>;
+    /** Remove the stored API key of an MCP tool collection. */
+    deleteMcpCollectionApiKey(appId: string, collectionId: string): Promise<McpApiKeyStatus>;
     /**
      * Cascade-delete an app and everything attached to it (versions,
      * installations + ACEs, git repo on the app-git server). Pass through
@@ -361,7 +371,7 @@ export default class AppsApi extends ApiTopic {
         client_id?: string;
         client_secret?: string;
         scopes?: string[];
-    }>): Promise<AppInstallation>;
+    }>, apiKeyParams?: AppApiKeyCollectionParams): Promise<AppInstallation>;
     /**
      * Remove the given app from the current project.
      * @param installationId - the id of the app installation
@@ -1435,6 +1445,10 @@ import type { BucketReadAccessStatusResponse, BulkUploadUrlsPayload, BulkUploadU
 import { StreamSource } from '../StreamSource.js';
 export declare const MEMORIES_PREFIX = "memories";
 export declare const ARTIFACTS_PREFIX = "agents";
+export declare class FileDownloadError extends Error {
+    readonly status?: number;
+    constructor(location: string, status?: number, statusText?: string, cause?: unknown);
+}
 export declare function getMemoryFilePath(name: string): string;
 /**
  * Build the storage path for an agent artifact
@@ -2410,7 +2424,7 @@ export interface GroundedMetadata {
 }
 export type Transcript = z.infer<typeof TranscriptSchema>;
 export declare const TextExtractionStatus: {
-    readonly success: "success";
+    readonly success: 'success';
 };
 export interface TranscriptMediaResult {
     hasText: boolean;
@@ -2559,8 +2573,8 @@ export declare enum ImageRenditionFormat {
     webp = "webp"
 }
 export declare const MarkdownRenditionFormat: {
-    readonly docx: "docx";
-    readonly pdf: "pdf";
+    readonly docx: 'docx';
+    readonly pdf: 'pdf';
 };
 export type MarkdownRenditionFormat = z.infer<typeof MarkdownRenditionFormatSchema>;
 export interface GetRenditionParams {
@@ -3701,6 +3715,12 @@ export declare enum FileProcessingStatus {
     ERROR = "error"
 }
 export type ConversationFile = z.infer<typeof ConversationFileSchema>;
+/**
+ * A file is deliverable when it is ready and has not yet been delivered to the agent as part
+ * of a user message. Deliverable files get attached to the next message; consumed ones stay
+ * reachable to tools via artifact_path/md_path but are not re-attached.
+ */
+export declare function isDeliverableFile(file: ConversationFile): boolean;
 /**
  * Details for file processing SYSTEM messages.
  * Used when type is AgentMessageType.SYSTEM with system_type: 'file_processing'.
@@ -3936,13 +3956,13 @@ export interface ActiveWorkstreamsQueryResult {
 // @vertesia/common: apps.d.ts
 // -----------------------------------------------------------------------------
 import type { z } from 'zod';
-import type { AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, DeleteAppVersionResponseSchema, OAuthClientCredentialsSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema } from './api-schemas/app-lifecycle.js';
-import type { AppInstallationListEntrySchema, AppInstallationSchema, AppInstallationWithManifestSchema, AppManifestDataSchema, AppManifestSchema, AppPackageSchema, AppWidgetInfoSchema, CompositeAppCardOverridesSchema, CompositeAppConfigPayloadSchema, CompositeAppConfigSchema, CompositeAppEntrySchema, CompositeAppHeaderItemKindSchema, CompositeAppHeaderItemSchema, CompositeAppHeaderItemTargetSchema, CompositeAppHeaderOverridesSchema, CompositeAppHomePluginSchema, CompositeAppLogoOverridesSchema, CompositeAppMenuSectionSchema, CompositeAppMessageOverridesSchema, CompositeAppMessageStyleSchema, CompositeAppNavItemPermissionsSchema, CompositeAppSidebarOverridesSchema, CompositeAppSwitchersOverridesSchema, CompositeAppThemeOverridesSchema, CompositeAppUserMenuOverridesSchema, PromoteAppVersionResponseSchema } from './api-schemas/app-runtime.js';
-import type { AppAccessControlSchema, AppAvailableInSchema, AppCapabilitiesSchema, AppGitSourceConfigSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPOAuthConfigSchema, MCPToolAnnotationsSchema, MCPToolCollectionObjectSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, ToolCollectionAuthTypeSchema, ToolCollectionObjectSchema, VertesiaSDKToolCollectionObjectSchema } from './api-schemas/apps.js';
+import type { AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppApiKeyCollectionParamsSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDeleteSummarySchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, DeleteAppVersionResponseSchema, McpApiKeyCredentialSchema, OAuthClientCredentialsSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema } from './api-schemas/app-lifecycle.js';
+import type { AppEventHookDeliverySchema, AppEventHookPayloadSchema, AppEventSubscriptionDefinitionSchema, AppInstallationListEntrySchema, AppInstallationSchema, AppInstallationWithManifestSchema, AppManifestDataSchema, AppManifestSchema, AppPackageEventHookSchema, AppPackageHooksSchema, AppPackageSchema, AppWidgetInfoSchema, CompositeAppCardOverridesSchema, CompositeAppConfigPayloadSchema, CompositeAppConfigSchema, CompositeAppEntrySchema, CompositeAppHeaderItemKindSchema, CompositeAppHeaderItemSchema, CompositeAppHeaderItemTargetSchema, CompositeAppHeaderOverridesSchema, CompositeAppHomePluginSchema, CompositeAppLogoOverridesSchema, CompositeAppMenuSectionSchema, CompositeAppMessageOverridesSchema, CompositeAppMessageStyleSchema, CompositeAppNavItemPermissionsSchema, CompositeAppSidebarOverridesSchema, CompositeAppSwitchersOverridesSchema, CompositeAppThemeOverridesSchema, CompositeAppUserMenuOverridesSchema, PromoteAppVersionResponseSchema } from './api-schemas/app-runtime.js';
+import type { AppAccessControlSchema, AppAvailableInSchema, AppCapabilitiesSchema, AppGitSourceConfigSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPApiKeyConfigSchema, MCPOAuthConfigSchema, MCPToolAnnotationsSchema, MCPToolCollectionObjectSchema, McpApiKeyStatusSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, SetMcpApiKeyRequestSchema, ToolCollectionAuthTypeSchema, ToolCollectionObjectSchema, VertesiaSDKToolCollectionObjectSchema } from './api-schemas/apps.js';
 import type { RemoteActivityDefinitionSchema } from './api-schemas/integrations.js';
 import type { ProjectToolInfoSchema, RenderingTemplateDefinitionRefSchema, RenderingTemplateDefinitionSchema } from './api-schemas/project.js';
 /** Allowed values for AppUINavItem.preferredSection */
-export declare const PREFERRED_SECTIONS: readonly ["default", "footer", "settings"];
+export declare const PREFERRED_SECTIONS: readonly ['default', 'footer', 'settings'];
 /**
  * Additional navigation item for an app's UI configuration.
  * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
@@ -3978,6 +3998,8 @@ export type ToolCollectionAuthType = z.infer<typeof ToolCollectionAuthTypeSchema
  */
 export type ToolCollectionType = 'mcp' | 'vertesia_sdk';
 export type MCPOAuthConfig = z.infer<typeof MCPOAuthConfigSchema>;
+/** Install-time provisioning blueprint for an `auth: 'api_key'` MCP collection. Never holds the key. */
+export type MCPApiKeyConfig = z.infer<typeof MCPApiKeyConfigSchema>;
 export type MCPToolCollectionObject = z.infer<typeof MCPToolCollectionObjectSchema>;
 export type VertesiaSDKToolCollectionObject = z.infer<typeof VertesiaSDKToolCollectionObjectSchema>;
 export type ToolCollectionObject = z.infer<typeof ToolCollectionObjectSchema>;
@@ -4030,7 +4052,7 @@ export type RemoteActivityDefinition = z.infer<typeof RemoteActivityDefinitionSc
  * 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 declare const APP_CAPABILITIES: readonly ['ui', 'tools', 'interactions', 'types', 'processes', 'views', 'templates', 'dashboards'];
 export type AppCapabilities = z.infer<typeof AppCapabilitiesSchema>;
 /**
  * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
@@ -4045,13 +4067,13 @@ export declare const APP_VERSION_HEADER = "x-vertesia-app-version";
  * {@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 declare const APP_ARTIFACT_TYPES: readonly ['interaction', 'agent', 'type', 'process', 'view', 'template', 'dashboard', 'activity', 'tool', 'hook', 'subscription'];
 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).
+ * types, `app:<name>:<process>` for processes, and `app:<name>:<local-id>` for hooks/subscriptions).
  */
 /**
  * Build progress for one artifact, maintained by the developer agent as a living checklist:
@@ -4081,10 +4103,10 @@ export interface AppPlannedArtifact {
 }
 /**
  * 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
+ * machine-readable contract for the build. The implementation MUST register every required artifact
+ * before building a candidate, then successfully exercise it after that candidate is installed and
+ * version-pinned. Persisted into the app repo as {@link APP_CAPABILITY_MANIFEST_PATH} so it survives
+ * across runs and the package-registration gate can verify 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.
  */
@@ -4253,8 +4275,13 @@ export type AppRepoBranch = z.infer<typeof AppRepoBranchSchema>;
  * 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 const APP_PACKAGE_SCOPES: readonly ["ui", "tools", "interactions", "types", "processes", "views", "templates", "dashboards", "settings", "widgets", "activities", "all"];
+export declare const APP_PACKAGE_SCOPES: readonly ['ui', 'tools', 'interactions', 'types', 'processes', 'views', 'templates', 'dashboards', 'settings', 'widgets', 'activities', 'hooks', 'subscriptions', 'all'];
 export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
+export type AppPackageEventHook = z.infer<typeof AppPackageEventHookSchema>;
+export type AppPackageHooks = z.infer<typeof AppPackageHooksSchema>;
+export type AppEventHookDelivery = z.infer<typeof AppEventHookDeliverySchema>;
+export type AppEventHookPayload = z.infer<typeof AppEventHookPayloadSchema>;
+export type AppEventSubscriptionDefinition = z.infer<typeof AppEventSubscriptionDefinitionSchema>;
 export type AppPackage = z.infer<typeof AppPackageSchema>;
 /**
  * A single diagnostic produced while inspecting an app's registration state.
@@ -4298,6 +4325,10 @@ export interface OrphanedAppInstallation extends Omit<AppInstallation, 'manifest
 }
 export type OAuthClientCredentials = z.infer<typeof OAuthClientCredentialsSchema>;
 export type AppOAuthCollectionParams = z.infer<typeof AppOAuthCollectionParamsSchema>;
+/** One installer-supplied MCP API key. */
+export type McpApiKeyCredential = z.infer<typeof McpApiKeyCredentialSchema>;
+/** Installer-supplied MCP API keys, keyed by collection id. */
+export type AppApiKeyCollectionParams = z.infer<typeof AppApiKeyCollectionParamsSchema>;
 export type AppOAuthProviderParams = z.infer<typeof AppOAuthProviderParamsSchema>;
 export type AppInstallationPayload = z.infer<typeof AppInstallationPayloadSchema>;
 export type UpdateAppInstallationToolAllowlistPayload = z.infer<typeof UpdateAppInstallationToolAllowlistPayloadSchema>;
@@ -4323,6 +4354,13 @@ export interface McpOAuthCollectionRef {
     app_install_id: string;
     collection_id: string;
 }
+/**
+ * Payload for storing the static bearer token of an `auth: 'api_key'` MCP collection.
+ * The key is write-only — it is never echoed back by any endpoint.
+ */
+export type SetMcpApiKeyRequest = z.infer<typeof SetMcpApiKeyRequestSchema>;
+/** Whether an `auth: 'api_key'` MCP collection has a key stored, plus a display-only hint. */
+export type McpApiKeyStatus = z.infer<typeof McpApiKeyStatusSchema>;
 export type McpOAuthTokenRequest = z.infer<typeof McpOAuthTokenRequestSchema>;
 export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponseSchema>;
 export type McpOAuthConnectResponse = z.infer<typeof McpOAuthConnectResponseSchema>;
@@ -4436,7 +4474,7 @@ export type CompositeAppHeaderItemKind = z.infer<typeof CompositeAppHeaderItemKi
 /** Where a header link opens. */
 export type CompositeAppHeaderItemTarget = z.infer<typeof CompositeAppHeaderItemTargetSchema>;
 /** Stable identifiers for the built-in header items. */
-export declare const COMPOSITE_APP_HEADER_BUILTIN_IDS: readonly ["app_portal", "docs", "help", "user_menu"];
+export declare const COMPOSITE_APP_HEADER_BUILTIN_IDS: readonly ['app_portal', 'docs', 'help', 'user_menu'];
 /**
  * A single button in the CompositeApp header bar.
  *
@@ -4459,18 +4497,14 @@ export type ValidateUrlResponse = z.infer<typeof ValidateUrlResponseSchema>;
  * 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.
+ *
+ * Inferred from the published component rather than hand-written: the endpoint
+ * had been declaring `CountResult`, so response validation reported a missing
+ * `count` and every field here as unexpected — and in local development, where
+ * the check fails closed, that surfaced as a 500 raised AFTER the app was
+ * already deleted. Deriving the type is what keeps the two from drifting again.
  */
-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 type AppDeleteSummary = z.infer<typeof AppDeleteSummarySchema>;
 
 // -----------------------------------------------------------------------------
 // @vertesia/common: interaction.d.ts
@@ -5233,32 +5267,32 @@ import type { AlterTableOperationSchema, AlterTablePayloadSchema, BatchQueryPayl
  * Supported column data types for DuckDB tables.
  */
 export declare const DataColumnType: {
-    readonly STRING: "STRING";
-    readonly INTEGER: "INTEGER";
-    readonly BIGINT: "BIGINT";
-    readonly FLOAT: "FLOAT";
-    readonly DOUBLE: "DOUBLE";
-    readonly DECIMAL: "DECIMAL";
-    readonly BOOLEAN: "BOOLEAN";
-    readonly DATE: "DATE";
-    readonly TIMESTAMP: "TIMESTAMP";
-    readonly JSON: "JSON";
+    readonly STRING: 'STRING';
+    readonly INTEGER: 'INTEGER';
+    readonly BIGINT: 'BIGINT';
+    readonly FLOAT: 'FLOAT';
+    readonly DOUBLE: 'DOUBLE';
+    readonly DECIMAL: 'DECIMAL';
+    readonly BOOLEAN: 'BOOLEAN';
+    readonly DATE: 'DATE';
+    readonly TIMESTAMP: 'TIMESTAMP';
+    readonly JSON: 'JSON';
 };
 export type DataColumnType = z.infer<typeof DataColumnTypeSchema>;
 /**
  * Semantic types that provide AI agents with context about column meaning.
  */
 export declare const SemanticColumnType: {
-    readonly EMAIL: "email";
-    readonly PHONE: "phone";
-    readonly URL: "url";
-    readonly CURRENCY: "currency";
-    readonly PERCENTAGE: "percentage";
-    readonly PERSON_NAME: "person_name";
-    readonly ADDRESS: "address";
-    readonly COUNTRY: "country";
-    readonly DATE_ISO: "date_iso";
-    readonly IDENTIFIER: "identifier";
+    readonly EMAIL: 'email';
+    readonly PHONE: 'phone';
+    readonly URL: 'url';
+    readonly CURRENCY: 'currency';
+    readonly PERCENTAGE: 'percentage';
+    readonly PERSON_NAME: 'person_name';
+    readonly ADDRESS: 'address';
+    readonly COUNTRY: 'country';
+    readonly DATE_ISO: 'date_iso';
+    readonly IDENTIFIER: 'identifier';
 };
 export type SemanticColumnType = z.infer<typeof SemanticColumnTypeSchema>;
 /**
@@ -5306,10 +5340,10 @@ export type DataStoreFullSchemaResponse = z.infer<typeof DataStoreFullSchemaResp
  * Data store lifecycle status.
  */
 export declare const DataStoreStatus: {
-    readonly CREATING: "creating";
-    readonly ACTIVE: "active";
-    readonly ERROR: "error";
-    readonly ARCHIVED: "archived";
+    readonly CREATING: 'creating';
+    readonly ACTIVE: 'active';
+    readonly ERROR: 'error';
+    readonly ARCHIVED: 'archived';
 };
 export type DataStoreStatus = z.infer<typeof DataStoreStatusSchema>;
 /**
@@ -5334,11 +5368,11 @@ export type GetDataStoreTableQuery = z.infer<typeof GetDataStoreTableQuerySchema
  * Import job status.
  */
 export declare const ImportStatus: {
-    readonly PENDING: "pending";
-    readonly PROCESSING: "processing";
-    readonly COMPLETED: "completed";
-    readonly FAILED: "failed";
-    readonly ROLLED_BACK: "rolled_back";
+    readonly PENDING: 'pending';
+    readonly PROCESSING: 'processing';
+    readonly COMPLETED: 'completed';
+    readonly FAILED: 'failed';
+    readonly ROLLED_BACK: 'rolled_back';
 };
 export type ImportStatus = z.infer<typeof ImportStatusSchema>;
 /**
@@ -5474,9 +5508,9 @@ export declare const DEFAULT_RETENTION_CONFIG: DataStoreRetentionConfig;
  */
 export declare const DashboardStatus: {
     /** Dashboard is active and usable */
-    readonly ACTIVE: "active";
+    readonly ACTIVE: 'active';
     /** Dashboard has been archived (soft deleted) */
-    readonly ARCHIVED: "archived";
+    readonly ARCHIVED: 'archived';
 };
 export type DashboardStatus = z.infer<typeof DashboardStatusSchema>;
 /**

package/lib/docs/vertesia-common.d.ts

@@ -61,6 +61,7 @@ export * from './secrets.js';
 export * from './skill.js';
 export * from './store/index.js';
 export type { ContentObjectExportArtifact, ContentObjectExportArtifactFile, ContentObjectExportProgress, ContentObjectExportResult, ContentObjectExportStatusResponse, DeleteContentObjectExportResponse, ExportContentObjectsFilter, ExportContentObjectsIncludeOptions, ExportedContentObjectRecord, ListContentObjectExportsResponse, StartContentObjectExportRequest, StartContentObjectExportResponse, ZenoBulkContentObjectExportComposeRequest, ZenoBulkContentObjectExportPlanRequest, ZenoBulkContentObjectExportPlanResponse, ZenoBulkContentObjectExportRequest, ZenoBulkContentObjectExportShardRange, ZenoBulkContentObjectExportShardRequest, ZenoBulkContentObjectExportShardResult, ZenoBulkContentObjectExportSplitShardRequest, ZenoBulkContentObjectExportSplitShardResponse, } from './store/store.js';
+export * from './sts-errors.js';
 export * from './sts-token-types.js';
 export * from './tenant.js';
 export * from './tool-execution.js';
@@ -84,13 +85,13 @@ export * from './workflow-analytics.js';
 // @vertesia/common: apps.d.ts
 // -----------------------------------------------------------------------------
 import type { z } from 'zod';
-import type { AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, DeleteAppVersionResponseSchema, OAuthClientCredentialsSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema } from './api-schemas/app-lifecycle.js';
-import type { AppInstallationListEntrySchema, AppInstallationSchema, AppInstallationWithManifestSchema, AppManifestDataSchema, AppManifestSchema, AppPackageSchema, AppWidgetInfoSchema, CompositeAppCardOverridesSchema, CompositeAppConfigPayloadSchema, CompositeAppConfigSchema, CompositeAppEntrySchema, CompositeAppHeaderItemKindSchema, CompositeAppHeaderItemSchema, CompositeAppHeaderItemTargetSchema, CompositeAppHeaderOverridesSchema, CompositeAppHomePluginSchema, CompositeAppLogoOverridesSchema, CompositeAppMenuSectionSchema, CompositeAppMessageOverridesSchema, CompositeAppMessageStyleSchema, CompositeAppNavItemPermissionsSchema, CompositeAppSidebarOverridesSchema, CompositeAppSwitchersOverridesSchema, CompositeAppThemeOverridesSchema, CompositeAppUserMenuOverridesSchema, PromoteAppVersionResponseSchema } from './api-schemas/app-runtime.js';
-import type { AppAccessControlSchema, AppAvailableInSchema, AppCapabilitiesSchema, AppGitSourceConfigSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPOAuthConfigSchema, MCPToolAnnotationsSchema, MCPToolCollectionObjectSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, ToolCollectionAuthTypeSchema, ToolCollectionObjectSchema, VertesiaSDKToolCollectionObjectSchema } from './api-schemas/apps.js';
+import type { AgentToolApprovalClassSchema, AgentToolDefinitionSchema, AppApiKeyCollectionParamsSchema, AppBuildProgressSchema, AppBuildProgressStatusSchema, AppBuildTriggerSchema, AppDeleteSummarySchema, AppDevelopmentTaskDetailsSchema, AppDevelopmentTaskListSchema, AppDevelopmentTaskSchema, AppInspectionCapabilityReportSchema, AppInspectionIssueSchema, AppInspectionResultSchema, AppInstallationKindSchema, AppInstallationOAuthBindingSchema, AppInstallationPayloadSchema, AppInstallationProjectsQuerySchema, AppInstallationProviderBindingSchema, AppInstallationsQuerySchema, AppOAuthCollectionParamsSchema, AppOAuthProviderParamsSchema, AppRepoBranchSchema, AppRepoCommitSchema, AppRepoCommitsSchema, AppRepoDocumentCommitSchema, AppRepoRefSchema, AppRepoRefsSchema, AppRepoTreeEntrySchema, AppRepoTreeSchema, AppScaffoldModuleSchema, AppScaffoldProgressSchema, AppScaffoldProgressStatusSchema, AppToolCollectionSchema, AppVersionGitRefTypeSchema, AppVersionGitSourceSchema, AppVersionKindSchema, AppVersionRecordSchema, AppVersionStateSchema, AppVersionStorageSchema, AppVersionTargetSchema, AppVersionUrlsSchema, DeleteAppVersionResponseSchema, McpApiKeyCredentialSchema, OAuthClientCredentialsSchema, StartAppBuildRequestSchema, StartAppBuildResponseSchema, StartAppScaffoldRequestSchema, StartAppScaffoldResponseSchema, UpdateAppInstallationToolAllowlistPayloadSchema, UpsertAppVersionRequestSchema, ValidateUrlRequestSchema, ValidateUrlResponseSchema } from './api-schemas/app-lifecycle.js';
+import type { AppEventHookDeliverySchema, AppEventHookPayloadSchema, AppEventSubscriptionDefinitionSchema, AppInstallationListEntrySchema, AppInstallationSchema, AppInstallationWithManifestSchema, AppManifestDataSchema, AppManifestSchema, AppPackageEventHookSchema, AppPackageHooksSchema, AppPackageSchema, AppWidgetInfoSchema, CompositeAppCardOverridesSchema, CompositeAppConfigPayloadSchema, CompositeAppConfigSchema, CompositeAppEntrySchema, CompositeAppHeaderItemKindSchema, CompositeAppHeaderItemSchema, CompositeAppHeaderItemTargetSchema, CompositeAppHeaderOverridesSchema, CompositeAppHomePluginSchema, CompositeAppLogoOverridesSchema, CompositeAppMenuSectionSchema, CompositeAppMessageOverridesSchema, CompositeAppMessageStyleSchema, CompositeAppNavItemPermissionsSchema, CompositeAppSidebarOverridesSchema, CompositeAppSwitchersOverridesSchema, CompositeAppThemeOverridesSchema, CompositeAppUserMenuOverridesSchema, PromoteAppVersionResponseSchema } from './api-schemas/app-runtime.js';
+import type { AppAccessControlSchema, AppAvailableInSchema, AppCapabilitiesSchema, AppGitSourceConfigSchema, AppManifestSourceSchema, AppSourceConfigSchema, AppUIConfigSchema, MCPApiKeyConfigSchema, MCPOAuthConfigSchema, MCPToolAnnotationsSchema, MCPToolCollectionObjectSchema, McpApiKeyStatusSchema, McpOAuthConnectResponseSchema, McpOAuthDisconnectResponseSchema, McpOAuthTokenRequestSchema, McpOAuthTokenResponseSchema, OAuthAuthorizeResponseSchema, OAuthAuthStatusSchema, OAuthMetadataResponseSchema, SetMcpApiKeyRequestSchema, ToolCollectionAuthTypeSchema, ToolCollectionObjectSchema, VertesiaSDKToolCollectionObjectSchema } from './api-schemas/apps.js';
 import type { RemoteActivityDefinitionSchema } from './api-schemas/integrations.js';
 import type { ProjectToolInfoSchema, RenderingTemplateDefinitionRefSchema, RenderingTemplateDefinitionSchema } from './api-schemas/project.js';
 /** Allowed values for AppUINavItem.preferredSection */
-export declare const PREFERRED_SECTIONS: readonly ["default", "footer", "settings"];
+export declare const PREFERRED_SECTIONS: readonly ['default', 'footer', 'settings'];
 /**
  * Additional navigation item for an app's UI configuration.
  * Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts.
@@ -126,6 +127,8 @@ export type ToolCollectionAuthType = z.infer<typeof ToolCollectionAuthTypeSchema
  */
 export type ToolCollectionType = 'mcp' | 'vertesia_sdk';
 export type MCPOAuthConfig = z.infer<typeof MCPOAuthConfigSchema>;
+/** Install-time provisioning blueprint for an `auth: 'api_key'` MCP collection. Never holds the key. */
+export type MCPApiKeyConfig = z.infer<typeof MCPApiKeyConfigSchema>;
 export type MCPToolCollectionObject = z.infer<typeof MCPToolCollectionObjectSchema>;
 export type VertesiaSDKToolCollectionObject = z.infer<typeof VertesiaSDKToolCollectionObjectSchema>;
 export type ToolCollectionObject = z.infer<typeof ToolCollectionObjectSchema>;
@@ -178,7 +181,7 @@ export type RemoteActivityDefinition = z.infer<typeof RemoteActivityDefinitionSc
  * 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 declare const APP_CAPABILITIES: readonly ['ui', 'tools', 'interactions', 'types', 'processes', 'views', 'templates', 'dashboards'];
 export type AppCapabilities = z.infer<typeof AppCapabilitiesSchema>;
 /**
  * Header carrying the app version a generated-app UI is running, so studio/zeno resolve app-owned
@@ -193,13 +196,13 @@ export declare const APP_VERSION_HEADER = "x-vertesia-app-version";
  * {@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 declare const APP_ARTIFACT_TYPES: readonly ['interaction', 'agent', 'type', 'process', 'view', 'template', 'dashboard', 'activity', 'tool', 'hook', 'subscription'];
 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).
+ * types, `app:<name>:<process>` for processes, and `app:<name>:<local-id>` for hooks/subscriptions).
  */
 /**
  * Build progress for one artifact, maintained by the developer agent as a living checklist:
@@ -229,10 +232,10 @@ export interface AppPlannedArtifact {
 }
 /**
  * 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
+ * machine-readable contract for the build. The implementation MUST register every required artifact
+ * before building a candidate, then successfully exercise it after that candidate is installed and
+ * version-pinned. Persisted into the app repo as {@link APP_CAPABILITY_MANIFEST_PATH} so it survives
+ * across runs and the package-registration gate can verify 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.
  */
@@ -401,8 +404,13 @@ export type AppRepoBranch = z.infer<typeof AppRepoBranchSchema>;
  * 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 const APP_PACKAGE_SCOPES: readonly ["ui", "tools", "interactions", "types", "processes", "views", "templates", "dashboards", "settings", "widgets", "activities", "all"];
+export declare const APP_PACKAGE_SCOPES: readonly ['ui', 'tools', 'interactions', 'types', 'processes', 'views', 'templates', 'dashboards', 'settings', 'widgets', 'activities', 'hooks', 'subscriptions', 'all'];
 export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
+export type AppPackageEventHook = z.infer<typeof AppPackageEventHookSchema>;
+export type AppPackageHooks = z.infer<typeof AppPackageHooksSchema>;
+export type AppEventHookDelivery = z.infer<typeof AppEventHookDeliverySchema>;
+export type AppEventHookPayload = z.infer<typeof AppEventHookPayloadSchema>;
+export type AppEventSubscriptionDefinition = z.infer<typeof AppEventSubscriptionDefinitionSchema>;
 export type AppPackage = z.infer<typeof AppPackageSchema>;
 /**
  * A single diagnostic produced while inspecting an app's registration state.
@@ -446,6 +454,10 @@ export interface OrphanedAppInstallation extends Omit<AppInstallation, 'manifest
 }
 export type OAuthClientCredentials = z.infer<typeof OAuthClientCredentialsSchema>;
 export type AppOAuthCollectionParams = z.infer<typeof AppOAuthCollectionParamsSchema>;
+/** One installer-supplied MCP API key. */
+export type McpApiKeyCredential = z.infer<typeof McpApiKeyCredentialSchema>;
+/** Installer-supplied MCP API keys, keyed by collection id. */
+export type AppApiKeyCollectionParams = z.infer<typeof AppApiKeyCollectionParamsSchema>;
 export type AppOAuthProviderParams = z.infer<typeof AppOAuthProviderParamsSchema>;
 export type AppInstallationPayload = z.infer<typeof AppInstallationPayloadSchema>;
 export type UpdateAppInstallationToolAllowlistPayload = z.infer<typeof UpdateAppInstallationToolAllowlistPayloadSchema>;
@@ -471,6 +483,13 @@ export interface McpOAuthCollectionRef {
     app_install_id: string;
     collection_id: string;
 }
+/**
+ * Payload for storing the static bearer token of an `auth: 'api_key'` MCP collection.
+ * The key is write-only — it is never echoed back by any endpoint.
+ */
+export type SetMcpApiKeyRequest = z.infer<typeof SetMcpApiKeyRequestSchema>;
+/** Whether an `auth: 'api_key'` MCP collection has a key stored, plus a display-only hint. */
+export type McpApiKeyStatus = z.infer<typeof McpApiKeyStatusSchema>;
 export type McpOAuthTokenRequest = z.infer<typeof McpOAuthTokenRequestSchema>;
 export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponseSchema>;
 export type McpOAuthConnectResponse = z.infer<typeof McpOAuthConnectResponseSchema>;
@@ -584,7 +603,7 @@ export type CompositeAppHeaderItemKind = z.infer<typeof CompositeAppHeaderItemKi
 /** Where a header link opens. */
 export type CompositeAppHeaderItemTarget = z.infer<typeof CompositeAppHeaderItemTargetSchema>;
 /** Stable identifiers for the built-in header items. */
-export declare const COMPOSITE_APP_HEADER_BUILTIN_IDS: readonly ["app_portal", "docs", "help", "user_menu"];
+export declare const COMPOSITE_APP_HEADER_BUILTIN_IDS: readonly ['app_portal', 'docs', 'help', 'user_menu'];
 /**
  * A single button in the CompositeApp header bar.
  *
@@ -607,18 +626,14 @@ export type ValidateUrlResponse = z.infer<typeof ValidateUrlResponseSchema>;
  * 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.
+ *
+ * Inferred from the published component rather than hand-written: the endpoint
+ * had been declaring `CountResult`, so response validation reported a missing
+ * `count` and every field here as unexpected — and in local development, where
+ * the check fails closed, that surfaced as a 500 raised AFTER the app was
+ * already deleted. Deriving the type is what keeps the two from drifting again.
  */
-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 type AppDeleteSummary = z.infer<typeof AppDeleteSummarySchema>;
 
 // -----------------------------------------------------------------------------
 // @vertesia/common: data-platform.d.ts
@@ -637,32 +652,32 @@ import type { AlterTableOperationSchema, AlterTablePayloadSchema, BatchQueryPayl
  * Supported column data types for DuckDB tables.
  */
 export declare const DataColumnType: {
-    readonly STRING: "STRING";
-    readonly INTEGER: "INTEGER";
-    readonly BIGINT: "BIGINT";
-    readonly FLOAT: "FLOAT";
-    readonly DOUBLE: "DOUBLE";
-    readonly DECIMAL: "DECIMAL";
-    readonly BOOLEAN: "BOOLEAN";
-    readonly DATE: "DATE";
-    readonly TIMESTAMP: "TIMESTAMP";
-    readonly JSON: "JSON";
+    readonly STRING: 'STRING';
+    readonly INTEGER: 'INTEGER';
+    readonly BIGINT: 'BIGINT';
+    readonly FLOAT: 'FLOAT';
+    readonly DOUBLE: 'DOUBLE';
+    readonly DECIMAL: 'DECIMAL';
+    readonly BOOLEAN: 'BOOLEAN';
+    readonly DATE: 'DATE';
+    readonly TIMESTAMP: 'TIMESTAMP';
+    readonly JSON: 'JSON';
 };
 export type DataColumnType = z.infer<typeof DataColumnTypeSchema>;
 /**
  * Semantic types that provide AI agents with context about column meaning.
  */
 export declare const SemanticColumnType: {
-    readonly EMAIL: "email";
-    readonly PHONE: "phone";
-    readonly URL: "url";
-    readonly CURRENCY: "currency";
-    readonly PERCENTAGE: "percentage";
-    readonly PERSON_NAME: "person_name";
-    readonly ADDRESS: "address";
-    readonly COUNTRY: "country";
-    readonly DATE_ISO: "date_iso";
-    readonly IDENTIFIER: "identifier";
+    readonly EMAIL: 'email';
+    readonly PHONE: 'phone';
+    readonly URL: 'url';
+    readonly CURRENCY: 'currency';
+    readonly PERCENTAGE: 'percentage';
+    readonly PERSON_NAME: 'person_name';
+    readonly ADDRESS: 'address';
+    readonly COUNTRY: 'country';
+    readonly DATE_ISO: 'date_iso';
+    readonly IDENTIFIER: 'identifier';
 };
 export type SemanticColumnType = z.infer<typeof SemanticColumnTypeSchema>;
 /**
@@ -710,10 +725,10 @@ export type DataStoreFullSchemaResponse = z.infer<typeof DataStoreFullSchemaResp
  * Data store lifecycle status.
  */
 export declare const DataStoreStatus: {
-    readonly CREATING: "creating";
-    readonly ACTIVE: "active";
-    readonly ERROR: "error";
-    readonly ARCHIVED: "archived";
+    readonly CREATING: 'creating';
+    readonly ACTIVE: 'active';
+    readonly ERROR: 'error';
+    readonly ARCHIVED: 'archived';
 };
 export type DataStoreStatus = z.infer<typeof DataStoreStatusSchema>;
 /**
@@ -738,11 +753,11 @@ export type GetDataStoreTableQuery = z.infer<typeof GetDataStoreTableQuerySchema
  * Import job status.
  */
 export declare const ImportStatus: {
-    readonly PENDING: "pending";
-    readonly PROCESSING: "processing";
-    readonly COMPLETED: "completed";
-    readonly FAILED: "failed";
-    readonly ROLLED_BACK: "rolled_back";
+    readonly PENDING: 'pending';
+    readonly PROCESSING: 'processing';
+    readonly COMPLETED: 'completed';
+    readonly FAILED: 'failed';
+    readonly ROLLED_BACK: 'rolled_back';
 };
 export type ImportStatus = z.infer<typeof ImportStatusSchema>;
 /**
@@ -878,9 +893,9 @@ export declare const DEFAULT_RETENTION_CONFIG: DataStoreRetentionConfig;
  */
 export declare const DashboardStatus: {
     /** Dashboard is active and usable */
-    readonly ACTIVE: "active";
+    readonly ACTIVE: 'active';
     /** Dashboard has been archived (soft deleted) */
-    readonly ARCHIVED: "archived";
+    readonly ARCHIVED: 'archived';
 };
 export type DashboardStatus = z.infer<typeof DashboardStatusSchema>;
 /**
@@ -1773,10 +1788,10 @@ export declare enum FullTextType {
 }
 export type SearchTypes = SupportedEmbeddingTypes | FullTextType;
 export declare const SearchTypes: {
-    readonly full_text: FullTextType.full_text;
     readonly text: SupportedEmbeddingTypes.text;
     readonly image: SupportedEmbeddingTypes.image;
     readonly properties: SupportedEmbeddingTypes.properties;
+    readonly full_text: FullTextType.full_text;
 };
 export type ProjectConfigurationEmbedding = z.infer<typeof ProjectConfigurationEmbeddingSchema>;
 export type ProjectConfigurationEmbeddingEnablePayload = z.infer<typeof ProjectConfigurationEmbeddingEnablePayloadSchema>;
@@ -2623,7 +2638,7 @@ export interface GroundedMetadata {
 }
 export type Transcript = z.infer<typeof TranscriptSchema>;
 export declare const TextExtractionStatus: {
-    readonly success: "success";
+    readonly success: 'success';
 };
 export interface TranscriptMediaResult {
     hasText: boolean;
@@ -2772,8 +2787,8 @@ export declare enum ImageRenditionFormat {
     webp = "webp"
 }
 export declare const MarkdownRenditionFormat: {
-    readonly docx: "docx";
-    readonly pdf: "pdf";
+    readonly docx: 'docx';
+    readonly pdf: 'pdf';
 };
 export type MarkdownRenditionFormat = z.infer<typeof MarkdownRenditionFormatSchema>;
 export interface GetRenditionParams {
@@ -3373,9 +3388,9 @@ export declare const ProcessDefinitionBodyJsonSchema: {
                         minLength: number;
                         $ref?: undefined;
                     } | {
-                        $ref: string;
                         type?: undefined;
                         minLength?: undefined;
+                        $ref: string;
                     })[];
                 };
                 failure_policy: {
@@ -4118,6 +4133,12 @@ export declare enum FileProcessingStatus {
     ERROR = "error"
 }
 export type ConversationFile = z.infer<typeof ConversationFileSchema>;
+/**
+ * A file is deliverable when it is ready and has not yet been delivered to the agent as part
+ * of a user message. Deliverable files get attached to the next message; consumed ones stay
+ * reachable to tools via artifact_path/md_path but are not re-attached.
+ */
+export declare function isDeliverableFile(file: ConversationFile): boolean;
 /**
  * Details for file processing SYSTEM messages.
  * Used when type is AgentMessageType.SYSTEM with system_type: 'file_processing'.

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/appgen-docs",
-  "version": "1.5.0-dev.20260804.124748Z",
+  "version": "1.5.0-dev.20260807.073259Z",
   "description": "Generated SDK references and development guidance for Vertesia app agents",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,11 +17,11 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "typescript": "^6.0.3",
-    "@vertesia/client": "1.5.0-dev.20260804.124748Z",
-    "@vertesia/common": "1.5.0-dev.20260804.124748Z",
+    "typescript": "7.0.2",
+    "@vertesia/client": "1.5.0-dev.20260807.073259Z",
+    "@vertesia/common": "1.5.0-dev.20260807.073259Z",
     "@vertesia/tsconfig": "0.1.0",
-    "@vertesia/ui": "1.5.0-dev.20260804.124748Z"
+    "@vertesia/ui": "1.5.0-dev.20260807.073259Z"
   },
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "documentation",
     "app-development"
   ],
-  "gitHead": "87ac9166db2b38bd1be6e37adf0414ea83e402ee",
+  "gitHead": "e6ebc1482ad6c4df965d74c79f82eb25fc6e2ce3",
   "scripts": {
     "build": "pnpm run clean && tsc -p tsconfig.json && node ./scripts/generate-docs.mjs",
     "clean": "rimraf ./lib ./docs ./tsconfig.tsbuildinfo",