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

package/src/apps.ts

@@ -1,8 +1,28 @@
+import type { AuthTokenPayload } from './apikey.js';
 import type * as Wire from './wire-types.generated.js';
 
 /** Allowed values for AppUINavItem.preferredSection */
 export const PREFERRED_SECTIONS = ['default', 'footer', 'settings'] as const;
 
+function trimBoundaryHyphens(value: string): string {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === '-') start++;
+    while (end > start && value[end - 1] === '-') end--;
+    return value.slice(start, end);
+}
+
+/** Convert an app display/package name into the canonical persisted app id. */
+export function slugifyAppId(value: string): string {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-');
+    const slug = trimBoundaryHyphens(normalized).slice(0, 80);
+    if (!slug) throw new Error('App name must contain at least one letter or number');
+    return slug;
+}
+
 // The app-manifest closure is declared once, as the Zod schemas in `./api-schemas/apps.ts`, and
 // inferred below. The documentation moved with it: what a published component says about a field now
 // comes from the schema's own `.meta({ description })` rather than from a TSDoc comment a generator
@@ -41,6 +61,7 @@ export interface AppUINavItem {
 }
 
 export type AppUIConfig = Wire.AppUIConfig;
+export type AppOAuthClientConfig = Wire.AppOAuthClientConfig;
 
 export type AppInstallationProjectsQuery = Wire.AppInstallationProjectsQuery;
 
@@ -81,11 +102,24 @@ function deriveMCPCollectionId(input: string): string {
  * @param vars - Optional endpoint variables to substitute in URLs
  * @returns Normalized ToolCollectionObject
  */
-export function normalizeToolCollection(collection: ToolCollectionObject, vars?: Endpoints): ToolCollectionObject {
+export function normalizeToolCollection(
+    collection: ToolCollectionObject,
+    vars?: Endpoints,
+    sharedParameters?: MCPToolCollectionObject['parameters'],
+): ToolCollectionObject {
     if (!collection || typeof collection !== 'object') {
         throw new TypeError('Tool collection must be an object');
     }
-    const substitutedUrl = vars && collection.url ? substituteEndpoints(collection.url, vars) : collection.url;
+    const substitutedUrl =
+        vars && collection.url
+            ? substituteEndpoints(
+                  collection.url,
+                  vars,
+                  collection.type === 'mcp'
+                      ? [...Object.keys(sharedParameters ?? {}), ...Object.keys(collection.parameters ?? {})]
+                      : [],
+              )
+            : collection.url;
     const urlChanged = substitutedUrl !== collection.url;
     if (collection.type === 'mcp') {
         const fallbackId = deriveMCPCollectionId(collection.id || collection.name || collection.url);
@@ -191,10 +225,26 @@ export type AppBuildProgress = Wire.AppBuildProgress;
 
 export type AppScaffoldModule = Wire.AppScaffoldModule;
 
+export type AppScaffoldSourceMode = Wire.AppScaffoldSourceMode;
+
 export type StartAppScaffoldRequest = Wire.StartAppScaffoldRequest;
 
 export type StartAppScaffoldResponse = Wire.StartAppScaffoldResponse;
 
+export type AppGithubConfiguration = Wire.AppGithubConfiguration;
+export type StartAppGithubAuthorizationResponse = Wire.StartAppGithubAuthorizationResponse;
+export type ExchangeAppGithubAuthorizationRequest = Wire.ExchangeAppGithubAuthorizationRequest;
+export type AppGithubRepositoriesQuery = Wire.AppGithubRepositoriesQuery;
+export type AppGithubInstallation = Wire.AppGithubInstallation;
+export type AppGithubAccount = Wire.AppGithubAccount;
+export type ExchangeAppGithubAuthorizationResponse = Wire.ExchangeAppGithubAuthorizationResponse;
+export type AppGithubRepository = Wire.AppGithubRepository;
+export type AppGithubRepositoryCreation = Wire.AppGithubRepositoryCreation;
+export type AppGithubRepositoryList = Wire.AppGithubRepositoryList;
+export type AppGithubRepositorySetupQuery = Wire.AppGithubRepositorySetupQuery;
+export type AppGithubBranchState = Wire.AppGithubBranchState;
+export type AppGithubRepositorySetup = Wire.AppGithubRepositorySetup;
+
 export type StartAppDevelopmentTaskRequest = Wire.StartAppDevelopmentTaskRequest;
 
 export type AppScaffoldProgressStatus = Wire.AppScaffoldProgressStatus;
@@ -232,6 +282,7 @@ export type AppManifestData = Wire.AppManifestData;
 export type UpdateAppPayload = Wire.UpdateAppPayload;
 
 export type AppGitSourceConfig = Wire.AppGitSourceConfig;
+export type AppGitSourceProvider = Wire.AppGitSourceProvider;
 
 export type AppSourceConfig = Wire.AppSourceConfig;
 
@@ -262,9 +313,11 @@ export interface Endpoints {
  * with the unresolved placeholder visible, rather than silently pointing nowhere).
  * Trailing slashes on replacement values are stripped to avoid `//api/...` joins.
  */
-function substituteEndpoints(url: string, endpoints?: Endpoints): string {
+function substituteEndpoints(url: string, endpoints?: Endpoints, parameterNames: string[] = []): string {
     if (!url || !endpoints) return url;
     return url.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key: string) => {
+        // Explicit installation parameters take precedence over legacy platform endpoint placeholders.
+        if (parameterNames.includes(key)) return match;
         const value = (endpoints as Record<string, string | undefined>)[key];
         if (typeof value !== 'string' || !value) return match;
         return trimTrailingSlashes(value);
@@ -632,3 +685,63 @@ export type ValidateUrlResponse = Wire.ValidateUrlResponse;
 export type AppDeleteSummary = Wire.AppDeleteSummary;
 
 export type UpdateAppInstallationOAuthApprovalPayload = Wire.UpdateAppInstallationOAuthApprovalPayload;
+
+/** Check exact installation grants; legacy app-name grants authorize only the default instance. */
+export function hasAppInstallationAccess(
+    token: AuthTokenPayload,
+    installation: { id: string; project: string; instance_key?: string; manifest: { name: string } },
+    ui = false,
+): boolean {
+    if (token.project?.id !== installation.project) return false;
+    const grants = token.app_installations;
+    if (grants !== undefined) {
+        if (grants.version !== 1 || grants.project_id !== installation.project) return false;
+        if (grants.ids.includes(installation.id)) {
+            return !ui || !grants.ui_restrictions?.includes(installation.id);
+        }
+    }
+    // Default app-name grants survive reinstalling the same app with a new installation ID.
+    // Named instances never inherit these grants, including on refreshed running-agent tokens.
+    return (
+        (!installation.instance_key || installation.instance_key === 'default') &&
+        (token.apps ?? []).includes(installation.manifest.name) &&
+        (!ui || !token.ui_restrictions?.includes(installation.manifest.name))
+    );
+}
+
+/** Persist this effective collection in catalogs so discovery and execution use the same namespace. */
+export function resolveInstallationCollection(
+    collection: ToolCollectionObject,
+    installation: Pick<AppInstallation, 'instance_key' | 'namespace_overrides' | 'namespace_conflicts'>,
+): ToolCollectionObject {
+    if (collection.type === 'mcp' && installation.namespace_conflicts?.includes(collection.id)) {
+        throw new Error(`Namespace conflict for MCP collection '${collection.id}'; resolve it in project app settings`);
+    }
+    if (collection.type !== 'mcp') return collection;
+    const overrides = installation.namespace_overrides;
+    if (overrides && Object.hasOwn(overrides, collection.id)) {
+        const namespace = overrides[collection.id];
+        if (typeof namespace === 'string' && namespace.length > 0) return { ...collection, namespace };
+    } else if (!installation.instance_key || installation.instance_key === 'default') {
+        return collection;
+    }
+    throw new Error(`Namespace allocation required for MCP collection '${collection.id}'`);
+}
+
+export type AppInstanceAvailability = Wire.AppInstanceAvailability;
+export type McpPublicParameter = Wire.McpPublicParameter;
+export type McpSecretParameter = Wire.McpSecretParameter;
+export type McpConnectionParameter = Wire.McpConnectionParameter;
+
+/** Whether a manifest can safely back an additional MCP-only installation. */
+export function isMcpOnlyInstanceManifest(
+    manifest: Pick<AppManifestData, 'endpoint' | 'ui' | 'capabilities' | 'tool_collections'>,
+): boolean {
+    return (
+        !manifest.endpoint &&
+        !manifest.ui &&
+        !manifest.capabilities?.some((capability) => capability !== 'tools') &&
+        !!manifest.tool_collections?.length &&
+        manifest.tool_collections.every((collection) => normalizeToolCollection(collection).type === 'mcp')
+    );
+}

package/src/interaction.ts

@@ -2,6 +2,7 @@ import type {
     CompletionResult,
     ExecutionTokenUsage,
     JSONSchema,
+    // biome-ignore lint/suspicious/noDeprecatedImports: Legacy output_modality contracts still require this enum.
     Modalities,
     PromptCacheDiagnostic,
     StatelessExecutionOptions,

package/src/oauth-server.ts

@@ -62,3 +62,13 @@ export type OAuthLoginPayload = Wire.OAuthLoginPayload;
 export type OAuthLoginDecisionResponse = Wire.OAuthLoginDecisionResponse;
 
 export type OAuthLoginUserNotFoundResponse = Wire.OAuthLoginUserNotFoundResponse;
+
+export type OidcFederationConnectionPayload = Wire.OidcFederationConnectionPayload;
+
+export type OidcFederationConnection = Wire.OidcFederationConnection;
+
+export type OidcFederationConnectionArray = Wire.OidcFederationConnectionArray;
+
+export type OAuthTokenExchangeRequest = Wire.OAuthTokenExchangeRequest;
+
+export type OAuthTokenExchangeResponse = Wire.OAuthTokenExchangeResponse;

package/src/store/index.ts

@@ -15,4 +15,5 @@ export * from './schedule.js';
 export * from './signals.js';
 export * from './store.js';
 export * from './task.js';
+export * from './text-limits.js';
 export * from './workflow.js';

package/src/store/intake-policy-schema.generated.ts

@@ -509,6 +509,16 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                         type: 'string',
                     },
                 },
+                effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
+                reasoning_effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
+                verbosity: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high'],
+                },
                 include_thoughts: {
                     type: 'boolean',
                 },
@@ -731,6 +741,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                     type: 'string',
                     const: 'bedrock-nova',
                 },
+                effort: {
+                    $ref: '#/$defs/ReasoningEffort',
+                },
                 max_tokens: {
                     type: 'number',
                 },
@@ -1223,8 +1236,7 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                     },
                 },
                 effort: {
-                    type: 'string',
-                    enum: ['none', 'high'],
+                    $ref: '#/$defs/ReasoningEffort',
                 },
                 random_seed: {
                     type: 'integer',
@@ -1610,6 +1622,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
                 image_generation: {
                     $ref: '#/$defs/OpenAiImageGenerationOptions',
                 },
+                seed: {
+                    type: 'number',
+                },
                 max_tokens: {
                     type: 'number',
                 },
@@ -1732,6 +1747,9 @@ export const ContentTypeIntakePolicySchema: JSONObject = {
         OpenRouterTextOptions: {
             type: 'object',
             properties: {
+                seed: {
+                    type: 'number',
+                },
                 max_tokens: {
                     type: 'number',
                 },

package/src/store/store.ts

@@ -136,6 +136,8 @@ export type ContentObjectUserPermissions = Wire.ContentObjectUserPermissions;
 
 export type ContentObjectTextResponse = Wire.ContentObjectTextResponse;
 
+export type SetObjectTextPayload = Wire.SetObjectTextPayload;
+
 export type DeleteContentObjectResult = Wire.DeleteContentObjectResult;
 
 export type SetObjectEmbeddingsResponse = Wire.SetObjectEmbeddingsResponse;

package/src/store/text-limits.ts

@@ -0,0 +1,64 @@
+/** Maximum UTF-8 size persisted for extracted document text. */
+export const MAX_EXTRACTED_TEXT_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Request-body allowance for the JSON envelope carrying extracted text and its source etag.
+ * This is transport headroom, not a larger stored-text limit.
+ */
+export const SET_OBJECT_TEXT_BODY_LIMIT_BYTES = 16 * 1024 * 1024;
+
+export const EXTRACTED_TEXT_TRUNCATION_MARKER = '\n\n[... truncated at max text limit 10 MiB ...]';
+
+export interface ExtractedTextLimitResult {
+    text: string;
+    truncated: boolean;
+}
+
+/**
+ * Retain the largest Unicode-safe prefix that fits together with the truncation marker.
+ * The marker is part of the byte budget, so persisted text never exceeds the declared limit.
+ */
+export function truncateExtractedText(text: string): ExtractedTextLimitResult {
+    if (utf8PrefixEnd(text, MAX_EXTRACTED_TEXT_BYTES) === text.length) {
+        return { text, truncated: false };
+    }
+
+    const markerBytes = utf8ByteLength(EXTRACTED_TEXT_TRUNCATION_MARKER);
+    const prefixEnd = utf8PrefixEnd(text, MAX_EXTRACTED_TEXT_BYTES - markerBytes);
+    return {
+        text: text.slice(0, prefixEnd) + EXTRACTED_TEXT_TRUNCATION_MARKER,
+        truncated: true,
+    };
+}
+
+function utf8ByteLength(text: string): number {
+    let bytes = 0;
+    for (let index = 0; index < text.length; ) {
+        const codePoint = text.codePointAt(index) ?? 0;
+        bytes += utf8CodePointBytes(codePoint);
+        index += codePoint > 0xffff ? 2 : 1;
+    }
+    return bytes;
+}
+
+function utf8PrefixEnd(text: string, maxBytes: number): number {
+    let bytes = 0;
+    let index = 0;
+    while (index < text.length) {
+        const codePoint = text.codePointAt(index) ?? 0;
+        const codePointBytes = utf8CodePointBytes(codePoint);
+        if (bytes + codePointBytes > maxBytes) {
+            break;
+        }
+        bytes += codePointBytes;
+        index += codePoint > 0xffff ? 2 : 1;
+    }
+    return index;
+}
+
+function utf8CodePointBytes(codePoint: number): number {
+    if (codePoint <= 0x7f) return 1;
+    if (codePoint <= 0x7ff) return 2;
+    if (codePoint <= 0xffff) return 3;
+    return 4;
+}