@opengeni/config 0.2.5 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/config",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "description": "OpenGeni runtime configuration: settings resolution, deployment knobs, and config validation shared across the server packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,15 +32,12 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "tsup"
+    "build": "tsup",
+    "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
     "@opengeni/codex": "^0.2.1",
-    "@opengeni/contracts": "^0.7.0",
+    "@opengeni/contracts": "^0.9.0",
     "zod": "^4.2.1"
-  },
-  "devDependencies": {
-    "tsup": "^8.5.0",
-    "typescript": "^6.0.3"
   }
 }

package/src/index.ts

@@ -101,6 +101,16 @@ export const DEFAULT_AGENT_INSTRUCTIONS = [
   AGENT_INSTRUCTIONS_CORE_PLACEHOLDER,
 ].join(" ");
 
+export const McpServerConnectionRefSchema = z.object({
+  connectionId: z.string().uuid().optional(),
+  providerDomain: z.string().min(1),
+  kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
+  scopes: z.array(z.string().min(1)).optional(),
+  resource: z.string().min(1).optional(),
+  subjectScope: z.enum(["workspace", "subject"]).optional(),
+}).strict();
+export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRefSchema>;
+
 const SettingsSchema = z.object({
   serviceName: z.string().default("opengeni"),
   environment: z.string().default("local"),
@@ -152,7 +162,13 @@ const SettingsSchema = z.object({
   // holder of stream:control gets 403 until this flips. Keeps stream:control a
   // declared-but-inert permission so later hardening is a flag flip.
   streamControlEnabled: EnvBoolean.default(false),
+  toolspaceEnabled: EnvBoolean.default(false),
+  toolspaceMaxCallsPerTurn: z.coerce.number().int().positive().default(200),
   environmentsEncryptionKey: z.string().optional(),
+  integrationsEnabled: EnvBoolean.default(false),
+  integrationsStateSecret: z.string().optional(),
+  integrationsAllowPrivateNetworkTargets: EnvBoolean.default(false),
+  integrationsOauthClientsJson: z.string().default("{}"),
   // Session goal guard rails. Goals are designed for runs that legitimately
   // span days, so length is bounded by pathology detection (no-progress
   // streaks, budget exhaustion), never by count. goalMaxAutoContinuations is
@@ -189,15 +205,26 @@ const SettingsSchema = z.object({
   // derived from these settings on the server path, and use the same numbers to
   // budget the client path.
   contextWindowTokens: z.coerce.number().int().positive().default(1_050_000),
+  // Proactive compaction threshold as a ratio of the model context window.
+  // Defaults to 60% and is clamped to [0.3, 0.9] so deployments can tune the
+  // trigger without accidentally disabling compaction or waiting until the
+  // provider is already at the cliff.
+  contextCompactionThresholdRatio: z.coerce.number().default(0.6).transform((value) => {
+    if (!Number.isFinite(value)) {
+      return 0.6;
+    }
+    return Math.min(0.9, Math.max(0.3, value));
+  }),
   // Tokens reserved for model output; subtracted from the window to get the
   // usable input budget B = contextWindowTokens - contextReservedOutputTokens.
   contextReservedOutputTokens: z.coerce.number().int().nonnegative().default(128_000),
   // Server path only: explicit compact_threshold (tokens) handed to the SDK's
-  // StaticCompactionPolicy. Defaults to floor(B * contextCompactSoftFraction)
-  // when unset.
+  // StaticCompactionPolicy. Defaults to floor(contextWindowTokens *
+  // contextCompactionThresholdRatio) when unset.
   contextServerCompactThresholdTokens: z.coerce.number().int().positive().optional(),
-  // Server path/back-compat knobs. The client compaction path ignores these:
-  // it uses Codex-parity 0.9 * (window - reserved output - 20k summary buffer).
+  // Deprecated back-compat knobs. The threshold is now controlled by
+  // contextCompactionThresholdRatio; these remain parsed so older deployments do
+  // not fail boot when their env still contains them.
   contextCompactSoftFraction: z.coerce.number().positive().max(1).default(0.70),
   contextCompactHardFraction: z.coerce.number().positive().max(1).default(0.85),
   // Deprecated for the client path; parsed for env/back-compat only.
@@ -290,6 +317,15 @@ const SettingsSchema = z.object({
   dockerNetwork: z.string().optional(),
   modalAppName: z.string().default("opengeni-sandbox"),
   modalImageRef: z.string().optional(),
+  // Name of a Modal Secret (containing REGISTRY_USERNAME + REGISTRY_PASSWORD) used
+  // to authenticate the pull of `modalImageRef` from a PRIVATE registry. When UNSET
+  // (the default), the sandbox image is pulled UNAUTHENTICATED — i.e. it must be a
+  // PUBLIC registry tag, which is the only shape the Agents-extension Modal backend
+  // supports out of the box (`Image.fromRegistry(tag)` with no secret). Set this to
+  // run a private image (e.g. a cloud-hosted ACR/ECR/GCR digest): the runtime resolves
+  // the named Secret and builds the image via `fromRegistry(tag, secret)` before the
+  // first sandbox is created. Knob: OPENGENI_MODAL_IMAGE_REGISTRY_SECRET.
+  modalImageRegistrySecret: z.string().optional(),
   // Modal's hard sandbox lifetime (timeoutMs = this * 1000), counted from each
   // create/resume — it is the BACKSTOP that reclaims a box if the reaper/worker is
   // down, NOT the warm-window controller (that's sandboxIdleGraceMs). It must
@@ -584,6 +620,14 @@ const SettingsSchema = z.object({
     allowedTools: z.array(z.string().min(1)).optional(),
     timeoutMs: z.number().int().positive().optional(),
     cacheToolsList: z.boolean().default(false),
+    /**
+     * Human-approval policy for this server's tools, overlaid per-run from a
+     * session MCP server row (never from OPENGENI_MCP_SERVERS). `true` = all
+     * tools require approval; a string[] = only the listed UNPREFIXED tool
+     * names do; absent = auto-run (the historical default). Enforced in the
+     * runtime by attaching `needsApproval` to the matching MCP tools.
+     */
+    requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
     /**
      * Extra request headers sent to this MCP server (credential injection
      * for workspace-enabled capability MCPs). Populated at runtime from
@@ -591,6 +635,7 @@ const SettingsSchema = z.object({
      * OPENGENI_MCP_SERVERS.
      */
     headers: z.record(z.string(), z.string()).optional(),
+    connectionRef: McpServerConnectionRefSchema.optional(),
   })).default([]),
 });
 
@@ -663,6 +708,13 @@ const RegistryProviderSchema = z.object({
 });
 export type RegistryProvider = z.infer<typeof RegistryProviderSchema>;
 
+export const IntegrationOAuthClientConfigSchema = z.object({
+  clientId: z.string().min(1),
+  clientSecret: z.string().min(1).optional(),
+  tokenEndpointAuthMethod: z.enum(["none", "client_secret_post", "client_secret_basic"]).default("none"),
+});
+export type IntegrationOAuthClientConfig = z.infer<typeof IntegrationOAuthClientConfigSchema>;
+
 /**
  * Runtime-resolved provider (built-in or registry), client-construction-ready.
  * The built-in OpenAI/Azure provider is always present and always "responses";
@@ -864,13 +916,20 @@ export function getSettings(): Settings {
     delegationSecret: optional("OPENGENI_DELEGATION_SECRET"),
     streamTokenSecret: optional("OPENGENI_STREAM_TOKEN_SECRET"),
     streamControlEnabled: optional("OPENGENI_STREAM_CONTROL_ENABLED"),
+    toolspaceEnabled: optional("OPENGENI_TOOLSPACE_ENABLED"),
+    toolspaceMaxCallsPerTurn: optional("OPENGENI_TOOLSPACE_MAX_CALLS_PER_TURN"),
     environmentsEncryptionKey: optional("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY"),
+    integrationsEnabled: optional("OPENGENI_INTEGRATIONS_ENABLED"),
+    integrationsStateSecret: optional("OPENGENI_INTEGRATIONS_STATE_SECRET"),
+    integrationsAllowPrivateNetworkTargets: optional("OPENGENI_INTEGRATIONS_ALLOW_PRIVATE_NETWORK_TARGETS"),
+    integrationsOauthClientsJson: optional("OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON"),
     goalMaxAutoContinuations: optional("OPENGENI_GOAL_MAX_AUTO_CONTINUATIONS"),
     goalNoProgressLimit: optional("OPENGENI_GOAL_NO_PROGRESS_LIMIT"),
     agentMaxModelCallsPerTurn: optional("OPENGENI_AGENT_MAX_MODEL_CALLS_PER_TURN"),
     sessionHistorySource: optional("OPENGENI_SESSION_HISTORY_SOURCE"),
     contextCompactionMode: optional("OPENGENI_CONTEXT_COMPACTION_MODE"),
     contextWindowTokens: optional("OPENGENI_CONTEXT_WINDOW_TOKENS"),
+    contextCompactionThresholdRatio: optional("OPENGENI_COMPACTION_THRESHOLD_RATIO"),
     contextReservedOutputTokens: optional("OPENGENI_CONTEXT_RESERVED_OUTPUT_TOKENS"),
     contextServerCompactThresholdTokens: optional("OPENGENI_CONTEXT_SERVER_COMPACT_THRESHOLD_TOKENS"),
     contextCompactSoftFraction: optional("OPENGENI_CONTEXT_COMPACT_SOFT_FRACTION"),
@@ -918,6 +977,7 @@ export function getSettings(): Settings {
     dockerNetwork: optional("OPENGENI_DOCKER_NETWORK"),
     modalAppName: optional("OPENGENI_MODAL_APP_NAME"),
     modalImageRef: optional("OPENGENI_MODAL_IMAGE_REF"),
+    modalImageRegistrySecret: optional("OPENGENI_MODAL_IMAGE_REGISTRY_SECRET"),
     modalTimeoutSeconds: optional("OPENGENI_MODAL_TIMEOUT_SECONDS"),
     modalTokenId: optional("OPENGENI_MODAL_TOKEN_ID"),
     modalTokenSecret: optional("OPENGENI_MODAL_TOKEN_SECRET"),
@@ -1310,11 +1370,11 @@ export function contextInputBudgetTokens(settings: Pick<Settings, "contextWindow
  * floor(B * softFraction). This is what sidesteps the SDK's wrong 240k
  * fallback for gpt-5.5 (which is absent from its hardcoded window map).
  */
-export function contextServerCompactThreshold(settings: Pick<Settings, "contextWindowTokens" | "contextReservedOutputTokens" | "contextServerCompactThresholdTokens" | "contextCompactSoftFraction">): number {
+export function contextServerCompactThreshold(settings: Pick<Settings, "contextWindowTokens" | "contextReservedOutputTokens" | "contextServerCompactThresholdTokens" | "contextCompactSoftFraction" | "contextCompactionThresholdRatio">): number {
   if (settings.contextServerCompactThresholdTokens) {
     return settings.contextServerCompactThresholdTokens;
   }
-  return Math.floor(contextInputBudgetTokens(settings) * settings.contextCompactSoftFraction);
+  return Math.floor(settings.contextWindowTokens * settings.contextCompactionThresholdRatio);
 }
 
 export function configuredStaticUsageLimits(settings: Settings): StaticUsageLimitsConfig {
@@ -1434,6 +1494,7 @@ export function collectGitIdentityEnvironment(settings: Settings): Record<string
 export function stableSandboxEnvironmentForRun(
   settings: Settings,
   workspaceEnvironment: Record<string, string> = {},
+  options: { workspaceId?: string } = {},
 ): Record<string, string> {
   const environment: Record<string, string> = {
     ...collectSandboxEnvironment(settings),
@@ -1455,6 +1516,12 @@ export function stableSandboxEnvironmentForRun(
   // VALUE lives exclusively in the file (agent-managed, refreshable mid-turn), never
   // the manifest env.
   environment.OPENGENI_GIT_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/git-token`;
+  if (settings.toolspaceEnabled) {
+    environment.OPENGENI_TOOLSPACE_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/toolspace-token`;
+    if (options.workspaceId) {
+      environment.OPENGENI_TOOLSPACE_URL ??= firstPartyMcpWorkspaceUrl(settings, options.workspaceId);
+    }
+  }
   return environment;
 }
 
@@ -1699,6 +1766,34 @@ export function parseModelProvidersJson(raw: string): RegistryProvider[] {
   });
 }
 
+export function parseIntegrationsOauthClientsJson(raw: string | undefined): Record<string, IntegrationOAuthClientConfig> {
+  if (!raw?.trim() || raw.trim() === "{}") {
+    return {};
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON must be valid JSON: ${message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON must be a JSON object keyed by authorization-server issuer or URL");
+  }
+  const out: Record<string, IntegrationOAuthClientConfig> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!key.trim()) {
+      throw new Error("OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON contains an empty issuer key");
+    }
+    const result = IntegrationOAuthClientConfigSchema.safeParse(value);
+    if (!result.success) {
+      throw new Error(`OPENGENI_INTEGRATIONS_OAUTH_CLIENTS_JSON client for ${key} is invalid: ${result.error.message}`);
+    }
+    out[key] = result.data;
+  }
+  return out;
+}
+
 export function parseStaticUsageLimitsJson(raw: string): StaticUsageLimitsConfig {
   if (!raw.trim() || raw.trim() === "{}") {
     return {};
@@ -1792,7 +1887,7 @@ function ensureBuiltInMcpServers(settings: Settings): Settings["mcpServers"] {
       id: "docs",
       name: "Document Search",
       url: firstPartyDocsMcpUrl,
-      allowedTools: ["search_documents", "fetch_document_chunk", "list_document_bases"],
+      allowedTools: ["search_documents", "fetch_document_chunk", "list_document_bases", "knowledge_search", "knowledge_fetch", "memory_search", "memory_propose"],
       cacheToolsList: false,
     }]),
     ...existing,
@@ -1824,6 +1919,18 @@ export function firstPartyMcpBaseUrl(settings: Settings): string {
   return settings.opengeniMcpUrl ?? `http://127.0.0.1:${settings.apiPort}/v1/workspaces/{workspaceId}/mcp`;
 }
 
+export function firstPartyMcpWorkspaceUrl(settings: Settings, workspaceId: string): string {
+  const raw = firstPartyMcpBaseUrl(settings);
+  if (raw.includes("{workspaceId}")) {
+    return raw.replaceAll("{workspaceId}", workspaceId);
+  }
+  const url = new URL(raw);
+  url.pathname = `/v1/workspaces/${workspaceId}/mcp`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
 function firstPartyMcpServerUrl(settings: Settings): string {
   return firstPartyMcpBaseUrl(settings);
 }
@@ -1833,6 +1940,9 @@ function firstPartyDocumentsMcpServerUrl(mcpUrl: string): string {
 }
 
 function validateSettings(settings: Settings): void {
+  if (settings.toolspaceEnabled && !settings.delegationSecret) {
+    throw new Error("OPENGENI_DELEGATION_SECRET is required when OPENGENI_TOOLSPACE_ENABLED=true");
+  }
   if (settings.productAccessMode === "managed") {
     if (!settings.publicBaseUrl) {
       throw new Error("OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_PRODUCT_ACCESS_MODE=managed");
@@ -1851,6 +1961,18 @@ function validateSettings(settings: Settings): void {
     }
   }
   environmentsEncryptionKeyBytes(settings);
+  if (settings.integrationsEnabled) {
+    if (settings.productAccessMode === "managed" && !settings.publicBaseUrl) {
+      throw new Error("OPENGENI_PUBLIC_BASE_URL is required when OPENGENI_INTEGRATIONS_ENABLED=true and OPENGENI_PRODUCT_ACCESS_MODE=managed");
+    }
+    if (settings.publicBaseUrl && !settings.publicBaseUrl.startsWith("https://") && !["local", "test"].includes(settings.environment)) {
+      throw new Error("OPENGENI_PUBLIC_BASE_URL must use https when OPENGENI_INTEGRATIONS_ENABLED=true outside local/test");
+    }
+    if (!settings.integrationsStateSecret && !["local", "test"].includes(settings.environment)) {
+      throw new Error("OPENGENI_INTEGRATIONS_STATE_SECRET is required when OPENGENI_INTEGRATIONS_ENABLED=true outside local/test");
+    }
+  }
+  parseIntegrationsOauthClientsJson(settings.integrationsOauthClientsJson);
   if (
     settings.productAccessMode === "configured"
     && !["local", "test"].includes(settings.environment)