@vertesia/common 1.5.0-dev.20260717.131047Z → 1.5.0-dev.20260725.083715Z

package/src/apps.ts

@@ -1,7 +1,13 @@
 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 {
+    AgentRunSearchHit,
+    DSLActivityOptions,
+    InCodeProcessDefinition,
+    InCodeTypeDefinition,
+} from './store/index.js';
+import type { InCodeViewDefinition } from './views.js';
 
 /** Allowed values for AppUINavItem.preferredSection */
 export const PREFERRED_SECTIONS = ['default', 'footer', 'settings'] as const;
@@ -383,27 +389,26 @@ export interface RemoteActivityDefinition {
     options?: DSLActivityOptions;
 }
 
-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.
+ * Canonical app capabilities Studio renders/supports. The public type is derived from
+ * this list so runtime validation and TypeScript cannot drift.
  */
-export const APP_CAPABILITIES: readonly AppCapabilities[] = [
+export const APP_CAPABILITIES = [
     'ui',
     'tools',
     'interactions',
     'types',
     'processes',
+    'views',
     'templates',
     'dashboards',
-];
+] as const;
+
+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 version (candidate testing) instead of current.
+ * 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 const APP_VERSION_HEADER = 'x-vertesia-app-version';
@@ -414,26 +419,19 @@ export 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 type AppArtifactType =
-    | 'interaction'
-    | 'agent'
-    | 'type'
-    | 'process'
-    | 'template'
-    | 'dashboard'
-    | 'activity'
-    | 'tool';
-
-export const APP_ARTIFACT_TYPES: readonly AppArtifactType[] = [
+export const APP_ARTIFACT_TYPES = [
     'interaction',
     'agent',
     'type',
     'process',
+    'view',
     'template',
     'dashboard',
     'activity',
     'tool',
-];
+] as const;
+
+export type AppArtifactType = (typeof APP_ARTIFACT_TYPES)[number];
 
 /**
  * A single platform artifact the App Solution Architect requires the build to create.
@@ -473,8 +471,8 @@ 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 preview/publish. Persisted into the app repo as
- * {@link APP_CAPABILITY_MANIFEST_PATH} so it survives across runs and the publish-time
+ * 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.
@@ -499,16 +497,14 @@ export interface AppCapabilityManifest {
     notes?: string;
 }
 
-/** Repo-relative path the capability manifest is committed to, read by the publish gate. */
+/** Repo-relative path the capability manifest is committed to, read by version-build gates. */
 export 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 AppVersionKind = 'design' | 'version';
 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 {
@@ -527,8 +523,8 @@ 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.
+     * 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;
@@ -558,13 +554,21 @@ export interface AppVersionRecord {
     version_id: string;
     kind: AppVersionKind;
     state: AppVersionState;
-    active?: boolean;
+    promoted?: boolean;
     target?: AppVersionTarget;
     agent_run_id?: string;
+    /** Development task that produced this version, when built by the app assistant. */
+    development_task_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[];
@@ -575,25 +579,41 @@ export interface AppVersionRecord {
     created_by?: string;
     created_at: string;
     updated_at: string;
-    published_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;
-    active?: boolean;
     target?: AppVersionTarget;
     agent_run_id?: string;
+    /** Development task that produced this version, when built by the app assistant. */
+    development_task_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[];
@@ -601,7 +621,7 @@ export interface UpsertAppVersionRequest {
     source_file_count?: number;
     screenshot_artifact?: string;
     checks?: string[];
-    published_at?: string;
+    built_at?: string;
     checked_at?: string;
     expires_at?: string;
 }
@@ -613,7 +633,7 @@ export interface AppVersionListQuery {
     limit?: number;
 }
 
-export interface ActivateAppVersionResponse {
+export interface PromoteAppVersionResponse {
     version: AppVersionRecord;
     app?: AppManifest;
 }
@@ -621,15 +641,12 @@ export interface ActivateAppVersionResponse {
 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.
+     * configuration chooses its default branch.
      */
     source_ref?: string;
     source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
-    intent?: AppBuildIntent;
     trigger?: AppBuildTrigger;
     target?: AppVersionTarget;
-    activate?: boolean;
     title?: string;
     description?: string;
 }
@@ -638,7 +655,8 @@ export interface StartAppBuildResponse {
     workflow_id: string;
     run_id: string;
     app_id: string;
-    intent: AppBuildIntent;
+    version_id?: string;
+    rebuild_version_record_id?: string;
     source_ref?: string;
     source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
 }
@@ -646,6 +664,8 @@ export interface StartAppBuildResponse {
 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;
@@ -654,8 +674,9 @@ export interface AppBuildWorkflowInput extends StartAppBuildRequest {
 export interface AppBuildWorkflowResult {
     app_id: string;
     version_id: string;
-    kind: Extract<AppVersionKind, 'preview' | 'published'>;
+    kind: Extract<AppVersionKind, 'version'>;
     state: AppVersionState;
+    source_commit: string;
     source_git?: AppVersionGitSource;
     urls?: AppVersionUrls;
     file_count?: number;
@@ -668,7 +689,6 @@ export interface AppBuildProgress {
     step: string;
     app_id?: string;
     version_id?: string;
-    intent?: AppBuildIntent;
     source_ref?: string;
     source_ref_type?: Extract<AppVersionGitRefType, 'branch' | 'tag' | 'commit'>;
     source_commit?: string;
@@ -678,6 +698,68 @@ export interface AppBuildProgress {
     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;
+    installation_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;
+    installation_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.
@@ -832,8 +914,9 @@ export interface AppManifestData {
 
     /**
      * 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.
+     * 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;
 
@@ -881,7 +964,7 @@ export interface Endpoints {
     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). */
+    /** The appgen app-gateway base URL (serves promoted app bundles + their `/api` runtime). */
     gateway?: string;
 }
 
@@ -927,14 +1010,46 @@ export interface AppRepoTree {
     entries: AppRepoTreeEntry[];
 }
 
-/** The content of a single file read from an app git repo at a given ref. */
-export interface AppRepoFile {
-    /** Path relative to the repo root. */
-    path: string;
-    /** The ref the file was read at (empty/undefined = default branch / HEAD). */
+/** Browser-side limits mirrored by the app Git service document endpoint. */
+export const APP_REPO_DOCUMENT_UPLOAD_MAX_FILE_BYTES = 20 * 1024 * 1024;
+export const APP_REPO_DOCUMENT_UPLOAD_MAX_TOTAL_BYTES = 80 * 1024 * 1024;
+export const APP_REPO_DOCUMENT_UPLOAD_MAX_FILES = 20;
+export 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;
-    /** UTF-8 file content. */
-    content: 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. */
@@ -959,37 +1074,64 @@ export interface AppRepoRefs {
     tags: AppRepoRef[];
 }
 
-export type AppPackageScope =
-    | 'ui'
-    | 'tools'
-    | 'interactions'
-    | 'types'
-    | 'processes'
-    | 'templates'
-    | 'dashboards'
-    | 'settings'
-    | 'widgets'
-    | 'activities'
-    | 'all';
+/** A mutable app development task represented by an `agent/*` Git branch. */
+export interface AppDevelopmentTask {
+    /** Task slug derived from the branch name. */
+    id: string;
+    /** Complete Git branch name. */
+    branch: string;
+    /** Commit currently at the branch head. */
+    source_commit: string;
+    /** Branch-head commit date, when available. */
+    commit_date?: string;
+}
+
+/** Git-backed development tasks and the branch used for new tasks by default. */
+export interface AppDevelopmentTaskList {
+    /** Repository default branch, when resolvable. */
+    default_branch?: string;
+    tasks: AppDevelopmentTask[];
+}
+
+/** Development task details, including the latest parent assistant run when one exists. */
+export interface AppDevelopmentTaskDetails extends AppDevelopmentTask {
+    /** Latest Studio Assistant run started for this task branch. */
+    agent_run?: AgentRunSearchHit;
+}
+
+/** Request to create a branch from an existing branch, tag, or commit. */
+export interface CreateAppRepoBranchRequest {
+    name: string;
+    source_ref: string;
+}
+
+/** A newly created app repository branch. */
+export interface AppRepoBranch {
+    name: string;
+    commit: string;
+    source_ref: string;
+}
 
 /**
- * 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.
+ * Canonical package scopes, including the catch-all `all`. The public type is derived
+ * from this list so request parsing and TypeScript cannot drift.
  */
-export const APP_PACKAGE_SCOPES: readonly AppPackageScope[] = [
+export const APP_PACKAGE_SCOPES = [
     'ui',
     'tools',
     'interactions',
     'types',
     'processes',
+    'views',
     'templates',
     'dashboards',
     'settings',
     'widgets',
     'activities',
     'all',
-];
+] as const;
+
+export type AppPackageScope = (typeof APP_PACKAGE_SCOPES)[number];
 export interface AppPackage {
     /**
      * The UI configuration of the app
@@ -1024,6 +1166,11 @@ export interface AppPackage {
      */
     processes?: InCodeProcessDefinition[];
 
+    /**
+     * View Experiences exposed by the app as in-code definitions.
+     */
+    views?: InCodeViewDefinition[];
+
     /**
      * Templates provided by the app.
      */
@@ -1066,14 +1213,14 @@ export interface AppInspectionIssue {
 }
 
 /**
- * Per-capability report of what an app's published package actually exposes,
+ * 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 published package actually serves for this capability. */
+    /** The local ids the promoted package actually serves for this capability. */
     exposed_ids: string[];
     /** Convenience count of `exposed_ids`. */
     exposed_count: number;
@@ -1081,7 +1228,7 @@ export interface AppInspectionCapabilityReport {
 
 /**
  * Result of inspecting an app's registration: the resolved manifest state, what
- * the published package actually exposes per capability, and diagnostics. This
+ * 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.
@@ -1099,7 +1246,7 @@ export interface AppInspectionResult {
     access_control?: string;
     /** The capabilities declared on the manifest. */
     capabilities: AppPackageScope[];
-    /** What the published package exposes, per capability. */
+    /** What the promoted package exposes, per capability. */
     package: AppInspectionCapabilityReport[];
     /** Diagnostics — errors and warnings about the registration state. */
     issues: AppInspectionIssue[];

package/src/audit-trail.ts

@@ -19,6 +19,8 @@ export const AUDIT_ACTIONS = [
     'inference',
     'embedding',
     'image_generation',
+    // Content processing outcomes
+    'document_processed',
 ] as const;
 
 export type KnownAuditAction = (typeof AUDIT_ACTIONS)[number];
@@ -113,3 +115,84 @@ export interface AuditTrailResponse {
     limit: number;
     offset: number;
 }
+
+export const AUDIT_AGGREGATION_DIMENSIONS = [
+    'time',
+    'action',
+    'resource_type',
+    'event_category',
+    'provider',
+    'project_id',
+    'details.pipeline',
+    'details.verdict',
+    'details.workflow_type',
+    'details.rule_id',
+    'model',
+] as const;
+
+export type AuditAggregationDimension = (typeof AUDIT_AGGREGATION_DIMENSIONS)[number];
+export type AuditAggregationResolution = 'hour' | 'day' | 'week' | 'month';
+export type AuditAggregationDetailField = 'pipeline' | 'verdict' | 'workflow_type' | 'rule_id';
+export type AuditAggregationOperation = 'count' | 'count_distinct' | 'sum_meter' | 'average_meter';
+export type AuditAggregationDistinctField = 'resource_id' | 'request_id';
+
+export interface AuditAggregationGroup {
+    dimension: AuditAggregationDimension;
+    /** Required for the time dimension; defaults to day. */
+    resolution?: AuditAggregationResolution;
+}
+
+export interface AuditAggregationMetric {
+    /** Stable key used in response rows. Must contain only letters, numbers, underscores, or hyphens. */
+    id: string;
+    operation: AuditAggregationOperation;
+    /** Required for count_distinct. */
+    field?: AuditAggregationDistinctField;
+    /** Required for meter operations. */
+    meterCategory?: string;
+    /** Required for meter operations. */
+    meterType?: string;
+}
+
+export interface AuditAggregationDetailFilter {
+    field: AuditAggregationDetailField;
+    values: string[];
+}
+
+export interface AuditAggregationFilter {
+    actions?: AuditAction[];
+    resourceTypes?: string[];
+    eventCategories?: EventCategory[];
+    providers?: string[];
+    success?: boolean;
+    details?: AuditAggregationDetailFilter[];
+}
+
+/**
+ * Safe audit aggregation query. The server always applies the authenticated account scope and,
+ * for project-scoped principals, replaces projectId with the authenticated project.
+ */
+export interface AuditAggregationQuery {
+    /** Optional account-admin project filter. Ignored for project-scoped principals. */
+    projectId?: string;
+    /** Start time; defaults to 30 days before to. The server caps the range at 366 days. */
+    from?: string;
+    /** End time; defaults to the current time. */
+    to?: string;
+    filter?: AuditAggregationFilter;
+    groupBy?: AuditAggregationGroup[];
+    metrics: AuditAggregationMetric[];
+    /** Maximum groups returned (default 50, max 200). */
+    limit?: number;
+}
+
+export interface AuditAggregationRow {
+    dimensions: Partial<Record<AuditAggregationDimension, string | null>>;
+    metrics: Record<string, number>;
+}
+
+export interface AuditAggregationResponse {
+    rows: AuditAggregationRow[];
+    from: string;
+    to: string;
+}

package/src/environment.ts

@@ -91,6 +91,8 @@ export interface TextFallbackOptions {
 export interface ExecutionEnvironmentSettings {
     [key: string]: unknown;
     bucket_access_principal?: string;
+    /** Custom HTTP headers sent by OpenAI-compatible environments. */
+    default_headers?: Record<string, string>;
 }
 
 /**

package/src/index.ts

@@ -37,6 +37,7 @@ export * from './rate-limiter.js';
 export * from './refs.js';
 export * from './roles/types.js';
 export * from './runs.js';
+export * from './schema-for-extraction.js';
 export * from './secrets.js';
 export * from './skill.js';
 export * from './store/index.js';
@@ -74,4 +75,15 @@ export * from './utils/auth.js';
 export * from './utils/schemas.js';
 export type * from './utils/type-helpers.js';
 export * from './versions.js';
+export * from './view-configuration-validation.js';
+export * from './view-query-validation.js';
+export * from './view-validation-helpers.js';
+export * from './views.js';
+export * from './views-schema.js';
+export {
+    type AppViewExperienceId,
+    parseAppViewExperienceId,
+    type ViewValidationIssue,
+    validateViewExperienceId,
+} from './views-validation.js';
 export * from './workflow-analytics.js';