@vertesia/common 1.6.0-dev.20261014.015055Z → 1.6.0-dev.20261019.172735Z

package/src/api-schemas/agent-runs.ts

@@ -36,7 +36,7 @@ import {
     RecordProcessRunPayloadSchema,
 } from './process.js';
 import { AgentBudgetConfigurationSchema, AgentCheckpointConfigurationSchema } from './project-configuration.js';
-import { nullableStringSchema } from './schema-primitives.js';
+import { nullableStringSchema, PageCountSchema } from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema } from './store.js';
 
 // ----------------------------------------------------------------------------
@@ -1438,8 +1438,8 @@ export const ListAgentRunsQuerySchema = z
             .string()
             .meta({ description: 'Only return runs started at or before this date', format: 'date-time' })
             .optional(),
-        limit: z.number().meta({ description: 'Maximum number of results (default: 50)' }).optional(),
-        offset: z.number().meta({ description: 'Offset for pagination' }).optional(),
+        limit: PageCountSchema.meta({ description: 'Maximum number of results (default: 50)' }).optional(),
+        offset: PageCountSchema.meta({ description: 'Offset for pagination' }).optional(),
         cursor: z.string().meta({ description: 'Cursor for stable pagination' }).optional(),
         schedule_id: z.string().meta({ description: 'Filter by schedule ID' }).optional(),
         type: AgentRunTypeSchema.meta({ description: 'Filter by run type' }).optional(),

package/src/api-schemas/app-lifecycle.ts

@@ -1,6 +1,11 @@
 import { z } from 'zod';
 import { APPGEN_PACKAGE_SPEC_PATTERN } from '../appgen.js';
-import { AppAccessControlSchema, AppAvailableInSchema, MCPToolAnnotationsSchema } from './apps.js';
+import {
+    AppAccessControlSchema,
+    AppAvailableInSchema,
+    AppSourceConfigSchema,
+    MCPToolAnnotationsSchema,
+} from './apps.js';
 import { EventCategorySchema } from './audit-trail.js';
 import { AgentBudgetConfigurationSchema } from './project-configuration.js';
 
@@ -95,6 +100,12 @@ export const AppScaffoldModuleSchema = z
     .enum(['service', 'assistant', 'content-app', 'examples'])
     .meta({ id: 'AppScaffoldModule' });
 
+export const AppScaffoldSourceModeSchema = z.enum(['generate', 'existing']).meta({
+    id: 'AppScaffoldSourceMode',
+    description:
+        'How App Builder should use a connected source repository. `generate` writes a starter app to an empty branch; `existing` only binds the repository.',
+});
+
 export const AppBuildTriggerSchema = z.enum(['ui', 'git_push', 'agent', 'api']).meta({ id: 'AppBuildTrigger' });
 
 export const Extract_AppVersionGitRefType_branch_tag_commitSchema = z
@@ -405,6 +416,22 @@ export const AppVersionGitSourceSchema = z
     })
     .meta({ id: 'AppVersionGitSource' });
 
+export const AppGithubRepositoryCreationSchema = z
+    .strictObject({
+        name: z
+            .string()
+            .trim()
+            .min(1)
+            .max(100)
+            .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/)
+            .meta({ description: 'Name of the empty GitHub repository to create in the verified installation.' }),
+        private: z
+            .boolean()
+            .optional()
+            .meta({ description: 'Create a private repository. Defaults to true when omitted.' }),
+    })
+    .meta({ id: 'AppGithubRepositoryCreation' });
+
 export const StartAppScaffoldRequestSchema = z
     .strictObject({
         app_id: z.string().meta({
@@ -431,9 +458,115 @@ export const StartAppScaffoldRequestSchema = z
                 description: 'Start an initial app version build after the source has been pushed. Defaults to true.',
             })
             .optional(),
+        source_mode: AppScaffoldSourceModeSchema.optional().meta({
+            description:
+                'Explicit source setup behavior for external repositories. Omit to retain the legacy automatic behavior.',
+        }),
+        source: AppSourceConfigSchema.optional().meta({
+            description:
+                'Source repository to bind to the app. Omit to create and scaffold a Vertesia-managed repository.',
+        }),
+        github_connection_id: z.string().optional().meta({
+            description: 'Short-lived proof that the current user verified the selected GitHub installation.',
+        }),
+        github_repository_creation: AppGithubRepositoryCreationSchema.optional().meta({
+            description:
+                'Create an empty repository in the verified GitHub installation before generating the app source.',
+        }),
     })
     .meta({ id: 'StartAppScaffoldRequest' });
 
+export const AppGithubConfigurationSchema = z
+    .strictObject({
+        enabled: z.boolean(),
+        app_slug: z.string().optional(),
+        install_url: z.string().optional(),
+        relay_url: z.string().optional(),
+    })
+    .meta({ id: 'AppGithubConfiguration' });
+
+export const StartAppGithubAuthorizationResponseSchema = z
+    .strictObject({ authorization_url: z.string() })
+    .meta({ id: 'StartAppGithubAuthorizationResponse' });
+
+export const ExchangeAppGithubAuthorizationRequestSchema = z
+    .strictObject({ code: z.string(), state: z.string() })
+    .meta({ id: 'ExchangeAppGithubAuthorizationRequest' });
+
+export const AppGithubRepositoriesQuerySchema = z
+    .strictObject({
+        connection_id: z.string().trim().min(1),
+        installation_id: z.string().trim().min(1),
+    })
+    .meta({ id: 'AppGithubRepositoriesQuery' });
+
+export const AppGithubInstallationSchema = z
+    .strictObject({
+        id: z.string(),
+        account_login: z.string(),
+        account_type: z.string().optional(),
+        repository_selection: z.enum(['all', 'selected']),
+    })
+    .meta({ id: 'AppGithubInstallation' });
+
+export const AppGithubAccountSchema = z
+    .strictObject({
+        login: z.string(),
+        account_type: z.string(),
+        avatar_url: z.string().optional(),
+    })
+    .meta({ id: 'AppGithubAccount' });
+
+export const ExchangeAppGithubAuthorizationResponseSchema = z
+    .strictObject({
+        connection_id: z.string(),
+        installations: z.array(AppGithubInstallationSchema),
+        accounts: z.array(AppGithubAccountSchema),
+    })
+    .meta({ id: 'ExchangeAppGithubAuthorizationResponse' });
+
+export const AppGithubRepositorySchema = z
+    .strictObject({
+        name: z.string(),
+        full_name: z.string(),
+        private: z.boolean(),
+        default_branch: z.string(),
+        html_url: z.string(),
+    })
+    .meta({ id: 'AppGithubRepository' });
+
+export const AppGithubRepositoryListSchema = z
+    .strictObject({ repositories: z.array(AppGithubRepositorySchema) })
+    .meta({ id: 'AppGithubRepositoryList' });
+
+export const AppGithubRepositorySetupQuerySchema = z
+    .strictObject({
+        connection_id: z.string().trim().min(1),
+        installation_id: z.string().trim().min(1),
+        repository: z.string().trim().min(1),
+        branch: z.string().trim().min(1),
+    })
+    .meta({ id: 'AppGithubRepositorySetupQuery' });
+
+export const AppGithubBranchStateSchema = z
+    .strictObject({
+        name: z.string(),
+        exists: z.boolean(),
+        empty: z.boolean(),
+    })
+    .meta({ id: 'AppGithubBranchState' });
+
+export const AppGithubRepositorySetupSchema = z
+    .strictObject({
+        default_branch: z.string(),
+        branches: z.array(z.string()),
+        selected_branch: AppGithubBranchStateSchema,
+    })
+    .meta({
+        id: 'AppGithubRepositorySetup',
+        description: 'Branch choices and write-safety state for a verified GitHub repository.',
+    });
+
 export const StartAppDevelopmentTaskRequestSchema = z
     .strictObject({
         prompt: z.string().min(1).meta({ description: 'Development request passed to the App Builder parent.' }),
@@ -685,6 +818,7 @@ export const AppVersionStorageSchema = z
 export const AppToolCollectionSchema = z
     .strictObject({
         name: z.string().meta({ description: 'The collection name' }),
+        collection_id: z.string().optional(),
         description: z.string().meta({ description: 'Optional collection description' }).optional(),
         tools: z.array(AgentToolDefinitionSchema).meta({ description: 'the tools provided by this collection' }),
     })
@@ -855,6 +989,30 @@ export const UpsertAppVersionRequestSchema = z
 export const AppInstallationPayloadSchema = z
     .strictObject({
         app_id: z.string(),
+        instance_key: z
+            .string()
+            .regex(/^[a-z][a-z0-9_-]{0,31}$/)
+            .optional(),
+        display_name: z.string().max(120).optional().meta({
+            description: 'Optional instance label. Send an empty string to clear the saved label; omit to preserve it.',
+        }),
+        namespace_overrides: z
+            .record(
+                z.string(),
+                z
+                    .string()
+                    .max(24)
+                    .regex(/^[a-z]([a-z0-9]|_[a-z0-9])*_?$/),
+            )
+            .optional(),
+        mcp_shared_parameters: z.record(z.string(), z.string().nullable()).optional().meta({
+            description:
+                'Shared MCP parameter overrides. Omitted values are retained; null clears an override or restores its default.',
+        }),
+        mcp_parameters: z.record(z.string(), z.record(z.string(), z.string().nullable())).optional().meta({
+            description:
+                'Installation parameter overrides by MCP collection id. Omit to preserve; null clears an override. Secret inputs are write-only.',
+        }),
         settings: z.looseObject({}).optional(),
         access_control: z
             .union([AppAccessControlSchema, z.null()])
@@ -958,3 +1116,7 @@ export const SystemPackageQuerySchema = z
             .optional(),
     })
     .meta({ id: 'SystemPackageQuery' });
+
+export const AppInstanceAvailabilitySchema = z
+    .strictObject({ enabled: z.boolean() })
+    .meta({ id: 'AppInstanceAvailability' });

package/src/api-schemas/app-runtime.ts

@@ -20,6 +20,7 @@ import {
     AppSourceConfigSchema,
     AppUIConfigSchema,
     MCPOAuthConfigSchema,
+    McpConnectionParameterSchema,
     ToolCollectionObjectSchema,
 } from './apps.js';
 import { AuditMeterSchema } from './audit-trail.js';
@@ -262,12 +263,28 @@ const appOAuthApprovalSchema = z.strictObject({
     approved_at: z.string(),
 });
 
+const mcpConfigurationSchema = z.strictObject({
+    revision: z.string(),
+    values: z.record(z.string(), z.record(z.string(), z.string())),
+    configured_secrets: z.record(z.string(), z.array(z.string())),
+    shared_values: z.record(z.string(), z.string()).optional(),
+    configured_shared_secrets: z.array(z.string()).optional(),
+});
+
 export const AppInstallationSchema = z
     .strictObject({
         id: z.string(),
         project: z.string(),
+        instance_key: z.string().optional(),
+        display_name: z.string().optional(),
+        installation_version: z.literal(1).optional(),
+        namespace_overrides: z.record(z.string(), z.string()).optional(),
+        reserved_namespaces: z.array(z.string()).min(1).optional(),
+        namespace_conflicts: z.array(z.string()).optional(),
         manifest: z.string(),
+        mcp_configuration: mcpConfigurationSchema.optional(),
         oauth_approval: appOAuthApprovalSchema.optional(),
+        oauth_client_id: z.string().optional(),
         settings: z.looseObject({}).optional(),
         tool_allowlist: z
             .array(z.string())
@@ -336,9 +353,27 @@ export const AppDashboardDefinitionSchema = z
             'Dashboard definition contributed by an app package.\n\nApp dashboard IDs are local to the app. The platform exposes them as `app:<app_name>:<id>` when listing or retrieving dashboards.',
     });
 
+export const AppOAuthClientConfigSchema = z
+    .strictObject({
+        redirect_uris: z.array(z.string().url()).min(1),
+    })
+    .meta({
+        id: 'AppOAuthClientConfig',
+        description:
+            'Standalone public PKCE OAuth. Installation automatically provisions an app client with these exact callback URLs.',
+    });
+
 export const AppManifestDataSchema = z
     .strictObject({
+        parameters: z
+            .record(z.string().regex(/^[a-z][a-z0-9_]*$/), McpConnectionParameterSchema)
+            .optional()
+            .meta({
+                description:
+                    'Shared MCP installation parameters available to every collection. Collection-local names must not overlap.',
+            }),
         oauth_scopes: z.array(z.string()).optional(),
+        oauth_client: AppOAuthClientConfigSchema.optional(),
         name: z.string().meta({
             description: 'The name of the app, used as the id in the system. Must be in kebab case (e.g. my-app).',
         }),
@@ -519,7 +554,9 @@ export const CompositeAppMessageOverridesSchema = z
 
 export const AppManifestSchema = z
     .strictObject({
+        parameters: AppManifestDataSchema.shape.parameters,
         oauth_scopes: z.array(z.string()).optional(),
+        oauth_client: AppOAuthClientConfigSchema.optional(),
         edit_revision: EditRevisionSchema,
         name: z.string().meta({
             description: 'The name of the app, used as the id in the system. Must be in kebab case (e.g. my-app).',
@@ -639,7 +676,15 @@ export const AppInstallationWithManifestSchema = z
     .strictObject({
         id: z.string(),
         project: z.string(),
+        instance_key: z.string().optional(),
+        display_name: z.string().optional(),
+        installation_version: z.literal(1).optional(),
+        namespace_overrides: z.record(z.string(), z.string()).optional(),
+        reserved_namespaces: z.array(z.string()).min(1).optional(),
+        namespace_conflicts: z.array(z.string()).optional(),
+        mcp_configuration: mcpConfigurationSchema.optional(),
         oauth_approval: appOAuthApprovalSchema.optional(),
+        oauth_client_id: z.string().optional(),
         settings: z.looseObject({}).optional(),
         tool_allowlist: z
             .array(z.string())
@@ -685,7 +730,15 @@ export const AppInstallationListEntrySchema = z
     .strictObject({
         id: z.string(),
         project: z.string(),
+        instance_key: z.string().optional(),
+        display_name: z.string().optional(),
+        installation_version: z.literal(1).optional(),
+        namespace_overrides: z.record(z.string(), z.string()).optional(),
+        reserved_namespaces: z.array(z.string()).min(1).optional(),
+        namespace_conflicts: z.array(z.string()).optional(),
+        mcp_configuration: mcpConfigurationSchema.optional(),
         oauth_approval: appOAuthApprovalSchema.optional(),
+        oauth_client_id: z.string().optional(),
         settings: z.looseObject({}).optional(),
         tool_allowlist: z
             .array(z.string())
@@ -922,6 +975,7 @@ export const AppEventSubscriptionDefinitionSchema = z
 
 export const AppPackageSchema = z
     .strictObject({
+        oauth_client: AppOAuthClientConfigSchema.optional(),
         oauth_scopes: z
             .array(z.string())
             .meta({ description: 'OAuth scopes requested by the app. Users must consent to project permissions.' })

package/src/api-schemas/apps.ts

@@ -208,10 +208,39 @@ const toolCollectionBaseShape = {
     }),
 };
 
+const mcpParameterFields = {
+    title: z.string().optional(),
+    description: z.string().optional(),
+    required: z.boolean().optional(),
+};
+
+// Separate variants forbid plaintext defaults for secret parameters in the emitted contract too.
+export const McpPublicParameterSchema = z
+    .strictObject({
+        ...mcpParameterFields,
+        type: z.literal('string').optional(),
+        default: z.string().optional(),
+    })
+    .meta({ id: 'McpPublicParameter' });
+export const McpSecretParameterSchema = z
+    .strictObject({
+        ...mcpParameterFields,
+        type: z.literal('secret'),
+    })
+    .meta({ id: 'McpSecretParameter' });
+export const McpConnectionParameterSchema = z
+    .union([McpPublicParameterSchema, McpSecretParameterSchema])
+    .meta({ id: 'McpConnectionParameter' });
+
 export const MCPToolCollectionObjectSchema = z
     .strictObject({
         ...toolCollectionBaseShape,
         type: z.literal('mcp'),
+        parameters: z.record(z.string().regex(/^[a-z][a-z0-9_]*$/), McpConnectionParameterSchema).optional(),
+        headers: z.record(z.string(), z.string()).optional().meta({
+            description:
+                'HTTP header templates. Reference declared installation parameters with {{name}}. Never embed secrets.',
+        }),
         id: z.string().meta({
             description:
                 'Stable identifier for this collection. Used to key oauth_bindings on AppInstallation — ' +
@@ -318,9 +347,23 @@ export const ToolCollectionObjectSchema = z
     .discriminatedUnion('type', [MCPToolCollectionObjectSchema, VertesiaSDKToolCollectionObjectSchema])
     .meta({ id: 'ToolCollectionObject' });
 
+export const AppGitSourceProviderSchema = z.enum(['vertesia', 'github']).meta({ id: 'AppGitSourceProvider' });
+
 export const AppGitSourceConfigSchema = z
     .strictObject({
+        provider: AppGitSourceProviderSchema.optional().meta({
+            description:
+                'Repository provider. Missing values are treated as `vertesia` for apps created before provider support.',
+        }),
         url: z.string().optional(),
+        installation_id: z
+            .string()
+            .optional()
+            .meta({ description: 'Verified GitHub App installation id. Required when provider is `github`.' }),
+        repository: z
+            .string()
+            .optional()
+            .meta({ description: 'GitHub repository in `owner/name` form. Required when provider is `github`.' }),
         default_branch: z.string().optional(),
         production_branch: z.string().optional(),
         development_branch: z.string().optional(),
@@ -343,7 +386,10 @@ export const AppManifestSourceSchema = z
     .strictObject({
         kind: z.literal('git'),
         git: z.strictObject({
+            provider: AppGitSourceProviderSchema.optional(),
             url: z.string(),
+            installation_id: z.string().optional(),
+            repository: z.string().optional(),
             default_branch: z.string().optional(),
             production_branch: z.string().optional(),
             development_branch: z.string().optional(),

package/src/api-schemas/audit-trail.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { AUDIT_ACTIONS, AUDIT_AGGREGATION_DIMENSIONS } from '../audit-trail.js';
 import { NumberValueMapSchema } from './interaction.js';
+import { PageCountSchema } from './schema-primitives.js';
 
 // The audit trail: the events `GET /audit-trail` pages through and the aggregation `POST
 // /audit-trail/aggregate` computes over them.
@@ -244,11 +245,10 @@ export const AuditTrailQuerySchema = z
             .optional(),
         from: z.string().meta({ description: 'Start time (ISO string)' }).optional(),
         to: z.string().meta({ description: 'End time (ISO string)' }).optional(),
-        limit: z
-            .number()
-            .meta({ description: 'Pagination: number of items to return (default 50, max 200)' })
-            .optional(),
-        offset: z.number().meta({ description: 'Pagination: offset' }).optional(),
+        limit: PageCountSchema.meta({
+            description: 'Pagination: number of items to return (default 50, max 200)',
+        }).optional(),
+        offset: PageCountSchema.meta({ description: 'Pagination: offset' }).optional(),
     })
     .meta({ id: 'AuditTrailQuery' });
 

package/src/api-schemas/content.ts

@@ -7,7 +7,7 @@ import { ContentObjectStatus } from '../store/store.js';
 import { ContentObjectTypeRefSchema } from './app-lifecycle.js';
 import { StringArrayMapSchema } from './dashboard.js';
 import { ComputedFacetResponseSchema, FacetSpecSchema, SortOptionSchema } from './interaction.js';
-import { nullableStringSchema } from './schema-primitives.js';
+import { nullableStringSchema, PageCountSchema } from './schema-primitives.js';
 import { ColumnLayoutSchema, ContentObjectTypeSchema, EmbeddingTypeEnabledMapSchema } from './store.js';
 
 export const scoreAggregationTypesSchema = z.enum(['rrf', 'rsf', 'smart']).meta({ id: 'scoreAggregationTypes' });
@@ -457,8 +457,8 @@ export const ComplexCollectionSearchQuerySchema = z
         parent: nullableStringSchema.optional(),
         dynamic: z.boolean().optional(),
         status: CollectionStatusSchema.optional(),
-        limit: z.number().optional(),
-        offset: z.number().optional(),
+        limit: PageCountSchema.optional(),
+        offset: PageCountSchema.optional(),
         name: z.string().optional(),
         type: z.string().optional(),
         types: z.array(z.string()).optional(),
@@ -1059,8 +1059,8 @@ export const CollectionMembersQuerySchema = z
     .object({
         status: z.string().optional(),
         type: z.string().optional(),
-        limit: z.number().optional(),
-        offset: z.number().optional(),
+        limit: PageCountSchema.optional(),
+        offset: PageCountSchema.optional(),
     })
     .meta({ id: 'CollectionMembersQuery' });
 

package/src/api-schemas/interaction.ts

@@ -28,7 +28,7 @@ import { InferenceProfileIdSchema, InferenceProfileSnapshotSchema } from './infe
 import { AccountRefSchema } from './invites.js';
 import { ProcessAgentExecutionPolicySchema } from './process-agent-policy.js';
 import { AgentBudgetConfigurationSchema, AgentCheckpointConfigurationSchema } from './project-configuration.js';
-import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
+import { EditRevisionSchema, ExpectedEditRevisionSchema, PageCountSchema } from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema, RunDataStorageLevelSchema } from './store.js';
 
 /**
@@ -498,8 +498,8 @@ export const InteractionForkPayloadSchema = z
 
 export const InteractionEndpointQuerySchema = z
     .strictObject({
-        limit: z.number().optional(),
-        offset: z.number().optional(),
+        limit: PageCountSchema.optional(),
+        offset: PageCountSchema.optional(),
         status: InteractionStatusSchema.optional(),
         visibility: InteractionVisibilitySchema.optional(),
         version: z.number().optional(),
@@ -701,8 +701,10 @@ export const RunSearchQuerySchema = z
  */
 export const RunListQuerySchema = z
     .strictObject({
-        limit: z.number().int().meta({ description: 'Maximum number of runs to return.' }).optional(),
-        offset: z.number().int().meta({ description: 'Number of runs to skip.' }).optional(),
+        // Already published as `integer`, so these keep that type and only gain the lower bound a find
+        // `skip` needs; a negative count failed there as a 500.
+        limit: z.number().int().min(0).meta({ description: 'Maximum number of runs to return.' }).optional(),
+        offset: z.number().int().min(0).meta({ description: 'Number of runs to skip.' }).optional(),
         interaction: z
             .array(z.string())
             .meta({ description: 'Interaction ids, or in-code interaction names, to filter by.' })
@@ -1144,8 +1146,8 @@ export const RunSearchPayloadSchema = z
             })
             .optional(),
         query: RunSearchQuerySchema.optional(),
-        limit: z.number().optional(),
-        offset: z.number().optional(),
+        limit: PageCountSchema.optional(),
+        offset: PageCountSchema.optional(),
         select: z.string().optional(),
         all_revisions: z.boolean().optional(),
         from_root: z.string().optional(),