@opengeni/config 0.16.2 → 0.19.0-canary.0

package/dist/index.d.ts

@@ -4,8 +4,13 @@ import { z } from "zod";
 export declare const SANDBOX_ARCHIVE_CAPTURE_MAX_TIMEOUT_MS: number;
 export declare const SANDBOX_ARCHIVE_CAPTURE_SETTLEMENT_GRACE_MS = 10000;
 export declare const SANDBOX_SNAPSHOT_MAX_TIMEOUT_MS: number;
+export declare const GOOGLE_DRIVE_PROVIDER_REQUEST_TIMEOUT_MAX_MS = 60000;
+export declare const GOOGLE_DRIVE_PROVIDER_RETRY_DELAY_MAX_MS = 60000;
 export declare const SANDBOX_LIFECYCLE_TRANSITION_MAX_WAIT_MS: number;
 export declare const SANDBOX_LIFECYCLE_RETRY_HANDOFF_GRACE_MS = 10000;
+/** Default pacing between consecutive no-input goal continuations. */
+export declare const DEFAULT_GOAL_IDLE_BACKOFF_MS: readonly number[];
+export declare const DEFAULT_GOAL_IDLE_BACKOFF_MAX_MS = 600000;
 export declare const sandboxPreparationProfiles: Record<string, {
     env: string[];
     hooks: string[];
@@ -113,6 +118,7 @@ declare const SettingsSchema: z.ZodObject<{
         local: "local";
         managed: "managed";
     }>>;
+    organizationTenancyCanonicalActivationEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     billingMode: z.ZodDefault<z.ZodEnum<{
         disabled: "disabled";
         stripe: "stripe";
@@ -151,6 +157,8 @@ declare const SettingsSchema: z.ZodObject<{
         browser_tabs: "browser_tabs";
         capability_authorization_request: "capability_authorization_request";
         capability_catalog_search: "capability_catalog_search";
+        company_profile_confirm: "company_profile_confirm";
+        company_profile_propose: "company_profile_propose";
         computer_act: "computer_act";
         computer_clipboard: "computer_clipboard";
         computer_lifecycle: "computer_lifecycle";
@@ -185,11 +193,16 @@ declare const SettingsSchema: z.ZodObject<{
         goal_progress: "goal_progress";
         goal_set: "goal_set";
         goal_update: "goal_update";
+        goal_wait: "goal_wait";
+        instruction_policy_propose: "instruction_policy_propose";
         interaction_discover: "interaction_discover";
         interaction_request_human: "interaction_request_human";
+        knowledge_correct: "knowledge_correct";
+        knowledge_propose: "knowledge_propose";
         memory_correct: "memory_correct";
         memory_save: "memory_save";
         memory_search: "memory_search";
+        preference_propose: "preference_propose";
         preference_registry_get: "preference_registry_get";
         preference_registry_summary: "preference_registry_summary";
         reddit_accounts_list: "reddit_accounts_list";
@@ -198,6 +211,8 @@ declare const SettingsSchema: z.ZodObject<{
         reddit_posts_sync: "reddit_posts_sync";
         reddit_search_live: "reddit_search_live";
         reddit_thread_fetch: "reddit_thread_fetch";
+        remember: "remember";
+        remember_confirm: "remember_confirm";
         rig_get: "rig_get";
         rig_list: "rig_list";
         rig_promote: "rig_promote";
@@ -205,6 +220,7 @@ declare const SettingsSchema: z.ZodObject<{
         rig_verify: "rig_verify";
         run_on: "run_on";
         sandbox_attach: "sandbox_attach";
+        sandbox_file_publish: "sandbox_file_publish";
         sandbox_provision: "sandbox_provision";
         sandbox_swap: "sandbox_swap";
         sandboxes_list: "sandboxes_list";
@@ -220,10 +236,12 @@ declare const SettingsSchema: z.ZodObject<{
         session_create: "session_create";
         session_events: "session_events";
         session_get: "session_get";
+        session_human_input_respond: "session_human_input_respond";
         session_pause: "session_pause";
         session_resume: "session_resume";
         session_send_message: "session_send_message";
         session_steer: "session_steer";
+        session_wait: "session_wait";
         sessions_list: "sessions_list";
         set_other_session_title: "set_other_session_title";
         set_session_title: "set_session_title";
@@ -235,6 +253,7 @@ declare const SettingsSchema: z.ZodObject<{
         slack_bot_list_files: "slack_bot_list_files";
         slack_bot_list_users: "slack_bot_list_users";
         slack_bot_post_message: "slack_bot_post_message";
+        slack_bot_search: "slack_bot_search";
         slack_bot_thread_replies: "slack_bot_thread_replies";
         social_connections_list: "social_connections_list";
         social_daily_analysis_context: "social_daily_analysis_context";
@@ -245,6 +264,10 @@ declare const SettingsSchema: z.ZodObject<{
         social_search_live: "social_search_live";
         social_thread_fetch: "social_thread_fetch";
         task_note_archive: "task_note_archive";
+        task_note_promote_instruction_policy: "task_note_promote_instruction_policy";
+        task_note_promote_knowledge: "task_note_promote_knowledge";
+        task_note_promote_preference: "task_note_promote_preference";
+        task_note_replace: "task_note_replace";
         task_note_save: "task_note_save";
         task_notes_list: "task_notes_list";
         variable_set_get_variable: "variable_set_get_variable";
@@ -278,6 +301,8 @@ declare const SettingsSchema: z.ZodObject<{
         browser_tabs: "browser_tabs";
         capability_authorization_request: "capability_authorization_request";
         capability_catalog_search: "capability_catalog_search";
+        company_profile_confirm: "company_profile_confirm";
+        company_profile_propose: "company_profile_propose";
         computer_act: "computer_act";
         computer_clipboard: "computer_clipboard";
         computer_lifecycle: "computer_lifecycle";
@@ -312,11 +337,16 @@ declare const SettingsSchema: z.ZodObject<{
         goal_progress: "goal_progress";
         goal_set: "goal_set";
         goal_update: "goal_update";
+        goal_wait: "goal_wait";
+        instruction_policy_propose: "instruction_policy_propose";
         interaction_discover: "interaction_discover";
         interaction_request_human: "interaction_request_human";
+        knowledge_correct: "knowledge_correct";
+        knowledge_propose: "knowledge_propose";
         memory_correct: "memory_correct";
         memory_save: "memory_save";
         memory_search: "memory_search";
+        preference_propose: "preference_propose";
         preference_registry_get: "preference_registry_get";
         preference_registry_summary: "preference_registry_summary";
         reddit_accounts_list: "reddit_accounts_list";
@@ -325,6 +355,8 @@ declare const SettingsSchema: z.ZodObject<{
         reddit_posts_sync: "reddit_posts_sync";
         reddit_search_live: "reddit_search_live";
         reddit_thread_fetch: "reddit_thread_fetch";
+        remember: "remember";
+        remember_confirm: "remember_confirm";
         rig_get: "rig_get";
         rig_list: "rig_list";
         rig_promote: "rig_promote";
@@ -332,6 +364,7 @@ declare const SettingsSchema: z.ZodObject<{
         rig_verify: "rig_verify";
         run_on: "run_on";
         sandbox_attach: "sandbox_attach";
+        sandbox_file_publish: "sandbox_file_publish";
         sandbox_provision: "sandbox_provision";
         sandbox_swap: "sandbox_swap";
         sandboxes_list: "sandboxes_list";
@@ -347,10 +380,12 @@ declare const SettingsSchema: z.ZodObject<{
         session_create: "session_create";
         session_events: "session_events";
         session_get: "session_get";
+        session_human_input_respond: "session_human_input_respond";
         session_pause: "session_pause";
         session_resume: "session_resume";
         session_send_message: "session_send_message";
         session_steer: "session_steer";
+        session_wait: "session_wait";
         sessions_list: "sessions_list";
         set_other_session_title: "set_other_session_title";
         set_session_title: "set_session_title";
@@ -362,6 +397,7 @@ declare const SettingsSchema: z.ZodObject<{
         slack_bot_list_files: "slack_bot_list_files";
         slack_bot_list_users: "slack_bot_list_users";
         slack_bot_post_message: "slack_bot_post_message";
+        slack_bot_search: "slack_bot_search";
         slack_bot_thread_replies: "slack_bot_thread_replies";
         social_connections_list: "social_connections_list";
         social_daily_analysis_context: "social_daily_analysis_context";
@@ -372,6 +408,10 @@ declare const SettingsSchema: z.ZodObject<{
         social_search_live: "social_search_live";
         social_thread_fetch: "social_thread_fetch";
         task_note_archive: "task_note_archive";
+        task_note_promote_instruction_policy: "task_note_promote_instruction_policy";
+        task_note_promote_knowledge: "task_note_promote_knowledge";
+        task_note_promote_preference: "task_note_promote_preference";
+        task_note_replace: "task_note_replace";
         task_note_save: "task_note_save";
         task_notes_list: "task_notes_list";
         variable_set_get_variable: "variable_set_get_variable";
@@ -386,19 +426,33 @@ declare const SettingsSchema: z.ZodObject<{
     }>>>>;
     streamTokenSecret: z.ZodOptional<z.ZodString>;
     streamControlEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
-    codemodeMaxCallsPerTurn: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     ogtoolPackageSpec: z.ZodOptional<z.ZodString>;
     environmentsEncryptionKey: z.ZodOptional<z.ZodString>;
     integrationsEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     integrationsStateSecret: z.ZodOptional<z.ZodString>;
     integrationsAllowPrivateNetworkTargets: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     integrationsOauthClientsJson: z.ZodDefault<z.ZodString>;
-    gmailRestAdapterEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     slackClientId: z.ZodOptional<z.ZodString>;
     slackClientSecret: z.ZodOptional<z.ZodString>;
     slackSigningSecret: z.ZodOptional<z.ZodString>;
+    slackBotDisplayName: z.ZodDefault<z.ZodEnum<{
+        OpenGeni: "OpenGeni";
+        "OpenGeni Staging": "OpenGeni Staging";
+    }>>;
+    slackCommand: z.ZodDefault<z.ZodString>;
     googleDriveClientId: z.ZodOptional<z.ZodString>;
     googleDriveClientSecret: z.ZodOptional<z.ZodString>;
+    googleDriveSyncMaxItems: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveSyncMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveSyncMaxFileBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveSyncMaxProviderRequests: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveSyncMaxElapsedSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveSyncMaxFailureDetails: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveProviderRequestTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveProviderRetryAttempts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveProviderRetryInitialDelayMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveProviderRetryMaxDelayMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    googleDriveProviderRetryBudgetMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     fikenClientId: z.ZodOptional<z.ZodString>;
     fikenClientSecret: z.ZodOptional<z.ZodString>;
     googleDriveWorkspaceEventsEnabled: z.ZodOptional<z.ZodPreprocess<z.ZodBoolean>>;
@@ -407,7 +461,10 @@ declare const SettingsSchema: z.ZodObject<{
     maxNestedAgentDepth: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     socialOauthClientsJson: z.ZodDefault<z.ZodString>;
     goalMaxAutoContinuations: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
-    goalNoProgressLimit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    goalIdleBackoffMs: z.ZodDefault<z.ZodPreprocess<z.ZodReadonly<z.ZodArray<z.ZodNumber>>>>;
+    goalIdleBackoffMaxMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    childLifecycleNoticesEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    slackWorkspaceRoutingEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     agentMaxModelCallsPerTurn: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     contextWindowTokens: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     contextEffectiveWindowTokens: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -422,6 +479,7 @@ declare const SettingsSchema: z.ZodObject<{
     apiHost: z.ZodDefault<z.ZodString>;
     apiPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     workerHttpPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    opengeniMcpInternalUrl: z.ZodOptional<z.ZodString>;
     opengeniMcpUrl: z.ZodOptional<z.ZodString>;
     corsAllowOriginRegex: z.ZodDefault<z.ZodString>;
     openaiProvider: z.ZodDefault<z.ZodEnum<{
@@ -467,6 +525,7 @@ declare const SettingsSchema: z.ZodObject<{
     modelProvidersJson: z.ZodDefault<z.ZodString>;
     codexSubscriptionEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     supergrokSubscriptionEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    supergrokResponseStreamIdleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     codexConnectedAppsEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     codexProductSku: z.ZodOptional<z.ZodString>;
     codexToolSearchEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
@@ -512,6 +571,7 @@ declare const SettingsSchema: z.ZodObject<{
         local: "local";
         modal: "modal";
         none: "none";
+        opensandbox: "opensandbox";
         runloop: "runloop";
         selfhosted: "selfhosted";
         vercel: "vercel";
@@ -596,6 +656,17 @@ declare const SettingsSchema: z.ZodObject<{
     vercelProjectId: z.ZodOptional<z.ZodString>;
     vercelTeamId: z.ZodOptional<z.ZodString>;
     vercelRuntime: z.ZodOptional<z.ZodString>;
+    openSandboxBaseUrl: z.ZodOptional<z.ZodString>;
+    openSandboxApiKey: z.ZodOptional<z.ZodString>;
+    openSandboxImage: z.ZodOptional<z.ZodString>;
+    openSandboxTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    openSandboxUseServerProxy: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    openSandboxSignedEndpoints: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    openSandboxSignedEndpointTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    openSandboxChannelBPublicBaseUrl: z.ZodOptional<z.ZodString>;
+    openSandboxInteractionFrameProxy: z.ZodOptional<z.ZodPreprocess<z.ZodBoolean>>;
+    openSandboxPoolRef: z.ZodOptional<z.ZodString>;
+    openSandboxKubernetesInventoryNamespace: z.ZodOptional<z.ZodString>;
     sandboxOwnershipEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     rigVerificationLeaseOwnershipEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
     sandboxLazyProvisionEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
@@ -625,6 +696,7 @@ declare const SettingsSchema: z.ZodObject<{
     sandboxLeaseTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     sandboxLeaseWarmingTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     sandboxWarmingTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    workspaceControlLockTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rigSetupTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     sandboxWarmRateMicrosPerSecondJson: z.ZodDefault<z.ZodString>;
     sandboxMaxWarmSecondsPerWorkspace: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -681,6 +753,10 @@ declare const SettingsSchema: z.ZodObject<{
     githubAppId: z.ZodOptional<z.ZodString>;
     githubClientId: z.ZodOptional<z.ZodString>;
     githubClientSecret: z.ZodOptional<z.ZodString>;
+    githubRestMcpEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    githubPersonalOauthEnabled: z.ZodDefault<z.ZodPreprocess<z.ZodBoolean>>;
+    githubPersonalOauthClientId: z.ZodOptional<z.ZodString>;
+    githubPersonalOauthClientSecret: z.ZodOptional<z.ZodString>;
     githubAppSlug: z.ZodOptional<z.ZodString>;
     githubWebhookSecret: z.ZodOptional<z.ZodString>;
     githubAppPrivateKey: z.ZodOptional<z.ZodString>;
@@ -728,6 +804,34 @@ declare const SettingsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Settings = z.infer<typeof SettingsSchema>;
 export type McpServerConfig = Settings["mcpServers"][number];
+export type GoogleDriveProviderRetryOptions = {
+    requestTimeoutMs: number;
+    attempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    budgetMs: number;
+};
+/** Freeze one validated provider-neutral budget into every newly created or
+ * updated Google Drive knowledge-source schedule. Existing schedules retain
+ * their persisted limits until an authorized source save updates them. */
+export declare function configuredGoogleDriveSyncLimits(settings: Settings): {
+    maxItems: number;
+    maxBytes: number;
+    maxFileBytes: number;
+    maxProviderRequests: number;
+    maxElapsedSeconds: number;
+    maxConcurrency: number;
+    maxFailureDetails: number;
+};
+/** Bounded in-activity retry policy for individual Google Drive requests. The
+ * durable sync workflow remains authoritative after this local budget ends. */
+export declare function googleDriveProviderRetryOptions(settings: Settings): GoogleDriveProviderRetryOptions;
+/** Return only a credential-free HTTP(S) origin. Reject path, user-info, query,
+ * and fragment input instead of reflecting it into callbacks or evidence. */
+export declare function canonicalPublicOrigin(publicBaseUrl: string | undefined): string | null;
+export declare function googleDriveOAuthCallbackUrl(publicBaseUrl: string | undefined): string | null;
+/** Exact callback registered on the environment-specific personal GitHub OAuth App. */
+export declare function personalGitHubOAuthCallbackUrl(publicBaseUrl: string | undefined): string | null;
 /** Declarative voice-input transcription provider ids. */
 export type VoiceInputProviderId = "openai" | "azure-openai" | "codex-subscription" | "supergrok-subscription";
 export type VoiceInputProviderConfig = {
@@ -978,7 +1082,7 @@ export type ModelExecutionLimitsV1 = {
 };
 export type CredentialSourceV1 = {
     kind: "deployment";
-    mechanism: "api_key" | "azure_ad_bearer";
+    mechanism: "api_key" | "azure_ad_bearer" | "none";
 } | {
     kind: "connected_subscription";
     provider: "codex" | "xai";
@@ -1002,12 +1106,24 @@ export declare const ModelProviderApi: z.ZodEnum<{
     responses: "responses";
 }>;
 export type ModelProviderApi = z.infer<typeof ModelProviderApi>;
+/**
+ * Provider-specific request semantics that are independent of the endpoint's
+ * OpenAI-compatible wire API. Secondary Azure resources still speak the
+ * Responses API, but need Azure's stricter computer-call normalization.
+ */
+export declare const ModelProviderWireProfile: z.ZodEnum<{
+    "azure-openai": "azure-openai";
+    openai: "openai";
+}>;
+export type ModelProviderWireProfile = z.infer<typeof ModelProviderWireProfile>;
 /**
  * Registry provider kind. "api-key" providers carry their own static key/headers;
- * connected-subscription providers resolve a workspace account token at call
- * time and never carry a static key in the registry definition.
+ * "anonymous" providers intentionally send no credential and are externally
+ * metered; connected-subscription providers resolve a workspace account token
+ * at call time and never carry a static key in the registry definition.
  */
 export declare const RegistryProviderKind: z.ZodEnum<{
+    anonymous: "anonymous";
     "api-key": "api-key";
     "codex-subscription": "codex-subscription";
     "vercel-gateway-managed": "vercel-gateway-managed";
@@ -1018,6 +1134,7 @@ export type RegistryProviderKind = z.infer<typeof RegistryProviderKind>;
 /** A non-built-in provider declared by the host via OPENGENI_MODEL_PROVIDERS_JSON. */
 declare const RegistryProviderSchema: z.ZodObject<{
     kind: z.ZodDefault<z.ZodEnum<{
+        anonymous: "anonymous";
         "api-key": "api-key";
         "codex-subscription": "codex-subscription";
         "vercel-gateway-managed": "vercel-gateway-managed";
@@ -1030,6 +1147,10 @@ declare const RegistryProviderSchema: z.ZodObject<{
         chat: "chat";
         responses: "responses";
     }>>;
+    wireProfile: z.ZodDefault<z.ZodEnum<{
+        "azure-openai": "azure-openai";
+        openai: "openai";
+    }>>;
     baseUrl: z.ZodString;
     apiKey: z.ZodOptional<z.ZodString>;
     apiKeyEnv: z.ZodOptional<z.ZodString>;
@@ -1243,6 +1364,7 @@ export interface ResolvedModelProvider {
     label: string;
     kind: RegistryProviderKind;
     api: ModelProviderApi;
+    wireProfile: ModelProviderWireProfile;
     builtin: boolean;
     baseUrl?: string | undefined;
     apiKey?: string | undefined;
@@ -1396,6 +1518,17 @@ export declare function allowedFirstPartyMcpToolsForSession(settings: Pick<Setti
  * to be persisted).
  */
 export declare function effectiveModalIdleTimeoutSeconds(settings: Settings): number;
+export type EffectiveSandboxLifecycle = {
+    hardLifetimeMs: number | null;
+    renewableTtlSeconds: number | null;
+    providerIdleTimeoutMs: number | null;
+    rotationLeadMs: number | null;
+};
+/** Resolve provider lifecycle clocks without teaching generic callers Modal or
+ * OpenSandbox field names. Modal's returned values are exactly the pre-existing
+ * hard/idle/rotation values; OpenSandbox instead exposes a renewable TTL and no
+ * finite-deadline rotation. */
+export declare function effectiveSandboxLifecycle(settings: Settings, backend?: z.infer<typeof SandboxBackend>): EffectiveSandboxLifecycle;
 /**
  * One shared upper bound for the durable provider-capture claim and for command
  * admission waiting behind it. The SDK request itself is bounded by
@@ -1740,18 +1873,11 @@ export declare function parseSocialOauthClientsJson(raw: string | undefined): Pa
 export declare function parseStaticUsageLimitsJson(raw: string): StaticUsageLimitsConfig;
 export declare function parseStaticEntitlementsJson(raw: string): EntitlementsConfig;
 /**
- * The base URL of OpenGeni's own first-party MCP endpoint, as a `{workspaceId}`
- * template — the SINGLE source of truth for the `opengeniMcpUrl`-or-loopback
- * decision. Every site that needs the first-party MCP base (config's tool
- * registry here, and the worker-side `firstPartyMcpServerUrlForRun` /
- * `firstPartyMcpUrls` in @opengeni/runtime) MUST route through this so the
- * default lives in exactly one place.
+ * The sandbox/external base URL of OpenGeni's first-party MCP endpoint, as a
+ * `{workspaceId}` template. Codemode and remote placements use this route.
  *
  * BINDING CONTRACT (`opengeniMcpUrl`):
- *   - STANDALONE (unset): falls back to the loopback default
- *     `http://127.0.0.1:${apiPort}/v1/workspaces/{workspaceId}/mcp` — the worker
- *     and API are in/next to the same host:port, so loopback resolves the
- *     workspace-scoped MCP. Byte-for-byte today's behavior.
+ *   - STANDALONE (unset): falls back to the loopback default.
  *   - EMBEDDED / MOUNTED (must set): when OpenGeni's API is mounted as a host
  *     sub-app under a prefix (e.g. `https://host/og/v1/...`), the loopback
  *     default is WRONG — the worker runs in the host process and `127.0.0.1:
@@ -1761,7 +1887,14 @@ export declare function parseStaticEntitlementsJson(raw: string): EntitlementsCo
  *     the one binding a mounted embed cannot leave unset.
  */
 export declare function firstPartyMcpBaseUrl(settings: Settings): string;
+/**
+ * Worker-side first-party MCP base. It never inherits the public/tunnel URL:
+ * an operator may intentionally expose that route to Modal or a Connected
+ * Machine, while the worker should still use loopback or cluster service DNS.
+ */
+export declare function firstPartyMcpInternalBaseUrl(settings: Settings): string;
 export declare function firstPartyMcpWorkspaceUrl(settings: Settings, workspaceId: string): string;
+export declare function firstPartyMcpInternalWorkspaceUrl(settings: Settings, workspaceId: string): string;
 export declare function codemodeWorkspaceUrl(settings: Settings, workspaceId: string): string;
 /**
  * Resolve the secret used to sign/verify scoped stream tokens (sandbox contract
@@ -1819,7 +1952,7 @@ export declare function resolveNatsCalloutConfig(settings: Settings): NatsCallou
  * The PRIVILEGED control-plane NATS login (api/worker). Present only when BOTH a
  * user and password are set; otherwise null and the bus connects anonymously (local
  * dev / a NATS without auth_callout). When the callout plane is on, this is the
- * static account user permitted to request `agent.*.rpc`.
+ * static account user permitted to request exact generation-fenced agent RPC subjects.
  */
 export interface NatsControlPlaneAuth {
     user: string;