@opengeni/runtime 4.3.0 → 4.4.0-canary.36927100590001

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/dist/agent-instructions/base-behavior.d.ts +8 -0
  2. package/dist/agent-instructions/compose.d.ts +59 -0
  3. package/dist/agent-instructions/identity.d.ts +21 -0
  4. package/dist/agent-instructions/index.d.ts +6 -0
  5. package/dist/agent-instructions/modules/admin.d.ts +3 -0
  6. package/dist/agent-instructions/modules/artifacts.d.ts +7 -0
  7. package/dist/agent-instructions/modules/attachments.d.ts +3 -0
  8. package/dist/agent-instructions/modules/environment.d.ts +11 -0
  9. package/dist/agent-instructions/modules/goals.d.ts +3 -0
  10. package/dist/agent-instructions/modules/knowledge.d.ts +6 -0
  11. package/dist/agent-instructions/modules/machines.d.ts +3 -0
  12. package/dist/agent-instructions/modules/renderer-markdown.d.ts +6 -0
  13. package/dist/agent-instructions/modules/repositories.d.ts +7 -0
  14. package/dist/agent-instructions/modules/sandbox.d.ts +3 -0
  15. package/dist/agent-instructions/modules/skills.d.ts +3 -0
  16. package/dist/agent-instructions/modules/subagents.d.ts +3 -0
  17. package/dist/agent-instructions/runtime-mechanics.d.ts +7 -0
  18. package/dist/agent-instructions/types.d.ts +55 -0
  19. package/dist/assets/codemode-client.json +1 -1
  20. package/dist/{chunk-JUFVYQCY.js → chunk-VDXKKMMD.js} +457 -165
  21. package/dist/chunk-VDXKKMMD.js.map +1 -0
  22. package/dist/{chunk-22M75RJF.js → chunk-ZY655LYR.js} +1636 -709
  23. package/dist/chunk-ZY655LYR.js.map +1 -0
  24. package/dist/claude-subscription-usage.d.ts +3 -1
  25. package/dist/first-party-client.d.ts +1 -0
  26. package/dist/index.d.ts +37 -28
  27. package/dist/index.js +28 -2
  28. package/dist/input-wait-yield.d.ts +4 -0
  29. package/dist/interaction-tools.d.ts +1 -0
  30. package/dist/lazy-tool-transport.d.ts +6 -2
  31. package/dist/mcp-run-credentials.d.ts +3 -2
  32. package/dist/mcp-transport-logger.d.ts +10 -0
  33. package/dist/model-context-inspector.d.ts +17 -1
  34. package/dist/model-preparation-diagnostics.d.ts +9 -0
  35. package/dist/model-provider-routing.d.ts +4 -0
  36. package/dist/model-provider.d.ts +1 -0
  37. package/dist/model-request-capture.d.ts +9 -0
  38. package/dist/replayable-json-body.d.ts +2 -1
  39. package/dist/responses-terminal-error.d.ts +17 -0
  40. package/dist/sandbox/codemode-authority.d.ts +1 -0
  41. package/dist/sandbox/index.d.ts +3 -3
  42. package/dist/sandbox/index.js +5 -1
  43. package/dist/sandbox/provider-command-session.d.ts +6 -0
  44. package/dist/sandbox/providers/modal-command-control.d.ts +7 -0
  45. package/dist/sandbox/providers/modal-command-router-wire.d.ts +8 -0
  46. package/dist/sandbox/providers/modal-command-session.d.ts +2 -1
  47. package/dist/sandbox/providers/modal-command-start-errors.d.ts +9 -0
  48. package/dist/sandbox/providers/modal.d.ts +3 -0
  49. package/dist/sandbox/routing/routing-session.d.ts +5 -4
  50. package/dist/workspace-tool-gateway.js +2 -2
  51. package/package.json +12 -12
  52. package/src/agent-instructions/PROMPT_CHANGELOG.md +149 -0
  53. package/src/agent-instructions/base-behavior.ts +120 -0
  54. package/src/agent-instructions/compose.ts +153 -0
  55. package/src/agent-instructions/identity.ts +42 -0
  56. package/src/agent-instructions/index.ts +24 -0
  57. package/src/agent-instructions/modules/admin.ts +25 -0
  58. package/src/agent-instructions/modules/artifacts.ts +39 -0
  59. package/src/agent-instructions/modules/attachments.ts +12 -0
  60. package/src/agent-instructions/modules/environment.ts +60 -0
  61. package/src/agent-instructions/modules/goals.ts +15 -0
  62. package/src/agent-instructions/modules/knowledge.ts +21 -0
  63. package/src/agent-instructions/modules/machines.ts +17 -0
  64. package/src/agent-instructions/modules/renderer-markdown.ts +17 -0
  65. package/src/agent-instructions/modules/repositories.ts +28 -0
  66. package/src/agent-instructions/modules/sandbox.ts +63 -0
  67. package/src/agent-instructions/modules/skills.ts +19 -0
  68. package/src/agent-instructions/modules/subagents.ts +42 -0
  69. package/src/agent-instructions/runtime-mechanics.ts +55 -0
  70. package/src/agent-instructions/types.ts +83 -0
  71. package/src/bundled_default_skills/opengeni-client/SKILL.md +116 -37
  72. package/src/bundled_default_skills/opengeni-client/references/agent-recipes.md +18 -8
  73. package/src/bundled_default_skills/opengeni-client/references/api-workflows.md +24 -4
  74. package/src/bundled_default_skills/opengeni-client/references/chat-facade-fallback.md +23 -4
  75. package/src/bundled_default_skills/opengeni-client/references/compatibility-and-troubleshooting.md +34 -1
  76. package/src/bundled_default_skills/opengeni-client/references/configure-the-agent.md +248 -0
  77. package/src/bundled_default_skills/opengeni-client/references/customer-skill-template.md +2 -1
  78. package/src/bundled_default_skills/opengeni-client/references/data-tools-and-credentials.md +15 -4
  79. package/src/bundled_default_skills/opengeni-client/references/discovery-and-autonomy.md +2 -2
  80. package/src/bundled_default_skills/opengeni-client/references/isolation-and-authorization.md +5 -3
  81. package/src/bundled_default_skills/opengeni-client/references/product-integration-shapes.md +6 -5
  82. package/src/bundled_default_skills/opengeni-client/references/product-shapes-and-ui.md +36 -3
  83. package/src/bundled_default_skills/opengeni-client/references/proxy-from-any-backend.md +170 -0
  84. package/src/bundled_default_skills/opengeni-client/references/session-history-import.md +147 -0
  85. package/src/bundled_default_skills/opengeni-client/references/usage-allowances.md +189 -0
  86. package/src/bundled_default_skills/opengeni-help/SKILL.md +1 -1
  87. package/src/claude-subscription-usage.ts +23 -4
  88. package/src/first-party-client.ts +4 -0
  89. package/src/index.ts +260 -146
  90. package/src/input-wait-yield.ts +7 -0
  91. package/src/interaction-tools.ts +16 -2
  92. package/src/lazy-tool-transport.ts +46 -16
  93. package/src/mcp-run-credentials.ts +18 -3
  94. package/src/mcp-transport-logger.ts +46 -0
  95. package/src/model-context-inspector.ts +37 -3
  96. package/src/model-preparation-diagnostics.ts +48 -1
  97. package/src/model-provider-client.ts +5 -1
  98. package/src/model-provider-routing.ts +95 -1
  99. package/src/model-provider.ts +1 -0
  100. package/src/model-request-capture.ts +28 -1
  101. package/src/provider-history-adapter.ts +24 -3
  102. package/src/replayable-json-body.ts +19 -2
  103. package/src/responses-terminal-error.ts +136 -0
  104. package/src/sandbox/codemode-authority.ts +4 -0
  105. package/src/sandbox/codemode-client.ts +18 -16
  106. package/src/sandbox/index.ts +45 -9
  107. package/src/sandbox/provider-command-session.ts +12 -0
  108. package/src/sandbox/providers/modal-command-control.ts +118 -12
  109. package/src/sandbox/providers/modal-command-router-wire.ts +40 -4
  110. package/src/sandbox/providers/modal-command-session.ts +36 -1
  111. package/src/sandbox/providers/modal-command-start-errors.ts +27 -0
  112. package/src/sandbox/providers/modal-legacy-command-control.ts +60 -30
  113. package/src/sandbox/providers/modal.ts +43 -2
  114. package/src/sandbox/routing/routing-session.ts +61 -6
  115. package/src/sandbox/turn-tool-cancellation.ts +8 -1
  116. package/dist/chunk-22M75RJF.js.map +0 -1
  117. package/dist/chunk-JUFVYQCY.js.map +0 -1
package/src/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { measureMcpPhase } from "@opengeni/observability";
2
+ import { createMcpTransportLogger } from "./mcp-transport-logger";
2
3
  import {
3
4
  withPreparedCompactionRequest,
4
5
  deferCompactionToModelBoundary,
@@ -101,6 +102,9 @@ import {
101
102
  GenerateVideoToolInput,
102
103
  GetVideoGenerationCapabilitiesToolInput,
103
104
  RequestHumanInputToolInput,
105
+ resolveAgentToolFamilies,
106
+ resolveAgentMediaToolSurface,
107
+ type ResolvedAgentConfig,
104
108
  AttemptToolResult,
105
109
  type AttemptToolCatalog,
106
110
  type AttemptToolResult as AttemptToolResultValue,
@@ -267,6 +271,33 @@ import { z } from "zod";
267
271
 
268
272
  import { sanitizeHistoryItemsForModel } from "./history-sanitizer";
269
273
  import { OPENGENI_OPERATIONAL_INSTRUCTIONS } from "./operational-instructions";
274
+ import {
275
+ composeModularAgentInstructions,
276
+ resolveAgentIdentity,
277
+ rigInstructions,
278
+ workspaceEnvironmentInstructions,
279
+ type AgentPromptResources,
280
+ type RigInstructionsContext,
281
+ type WorkspaceEnvironmentContext,
282
+ } from "./agent-instructions";
283
+ export {
284
+ AGENT_PROMPT_MODULES,
285
+ DEFAULT_AGENT_IDENTITY,
286
+ INSTRUCTION_PRECEDENCE,
287
+ SESSION_INSTRUCTIONS_PREAMBLE,
288
+ composeModularAgentInstructions,
289
+ composeOperationalContract,
290
+ identityFromLegacyTemplate,
291
+ resolveAgentIdentity,
292
+ rigInstructions,
293
+ workspaceEnvironmentInstructions,
294
+ type AgentPromptContext,
295
+ type AgentPromptResources,
296
+ type ComposeModularAgentInstructionsInput,
297
+ type ModularInstructionLayer,
298
+ type RigInstructionsContext,
299
+ type WorkspaceEnvironmentContext,
300
+ } from "./agent-instructions";
270
301
  import {
271
302
  CompactionProviderResponseError,
272
303
  EmptyCompactionSummaryError,
@@ -280,7 +311,9 @@ import {
280
311
  import {
281
312
  createSandboxClient,
282
313
  isModalTaskExecStartPreDispatchUnavailableError,
314
+ isModalCommandStartOutcomeUnknownError,
283
315
  isRoutingMutationOutcomeUnknownError,
316
+ renderRoutingMutationOutcomeUnknownToolResult,
284
317
  repairSerializedRunStateExposedPorts,
285
318
  restoredSandboxSessionStateFromEntry,
286
319
  setOpenSandboxApplyDiff,
@@ -369,10 +402,13 @@ import {
369
402
  ModelRequestCaptureProvider,
370
403
  notifyModelRequestCapture,
371
404
  withModelRequestCapture,
405
+ withModelCallLifecycle,
406
+ type ModelCallLifecycle,
372
407
  type ModelRequestCapture,
373
408
  nextModelContextCaptureIndex,
374
409
  } from "./model-request-capture";
375
410
  import { decodeValidatedViewImageDataUrl } from "./view-image-validation";
411
+ export { beforeModelRequest as awaitModelCallAdmission } from "./model-request-capture";
376
412
  import {
377
413
  baseModelInputFilterForSettings,
378
414
  boundModelToolOutputsFilterForSettings,
@@ -458,6 +494,7 @@ export {
458
494
  MultiProviderModelProvider,
459
495
  OpenGeniChatCompletionsModel,
460
496
  OpenGeniResponsesModel,
497
+ ResponsesStreamingTerminalError,
461
498
  UNKNOWN_MODEL_FINISH_REASON_CODE,
462
499
  UnknownModelFinishReasonError,
463
500
  WorkspaceGatewayUnavailableError,
@@ -1995,6 +2032,8 @@ const modelMcpCallIdentity = new AsyncLocalStorage<{
1995
2032
  const agentInputWaitYields = new WeakMap<object, InputWaitYield>();
1996
2033
 
1997
2034
  export type BuildAgentOptions = {
2035
+ /** Durable router use survives capability and tool-policy changes. */
2036
+ toolRouterInHistory?: boolean;
1998
2037
  /** Live authority fence for intrinsic sandbox tools outside the MCP gateway. */
1999
2038
  authorizeAttemptExecution?: () => Promise<void> | void;
2000
2039
  /** Trusted attempt-local wait receipt shared with prepared tools. */
@@ -2212,6 +2251,24 @@ export type BuildAgentOptions = {
2212
2251
  * metadata no longer enters the prompt-cache-critical system instructions.
2213
2252
  */
2214
2253
  persistentSessionSettings?: PersistentSessionSettings;
2254
+ /**
2255
+ * The session's frozen agent configuration. Absent or null keeps the legacy
2256
+ * instructions byte-for-byte and the historical tool/provider request surface;
2257
+ * a configuration selects the modular composer (identity, base behavior,
2258
+ * runtime mechanics, capability modules) and gates tool families.
2259
+ */
2260
+ agentConfig?: ResolvedAgentConfig | null;
2261
+ /**
2262
+ * Modular composer only: the workspace identity tier (explicit workspace
2263
+ * default identity, else the legacy `agentInstructions` persona). Unlike
2264
+ * `instructionsTemplate`, workspace governance never drops it.
2265
+ */
2266
+ workspaceAgentIdentity?: string;
2267
+ /**
2268
+ * Modular composer only: resource facts for module selection. Derived from
2269
+ * the build resources and options when omitted.
2270
+ */
2271
+ agentPromptResources?: AgentPromptResources;
2215
2272
  // Per-call agent persona override (the white-label surface). Resolved by the
2216
2273
  // caller as session > workspace > deployment default; when omitted the
2217
2274
  // runtime falls back to settings.agentInstructionsTemplate. The runtime
@@ -2248,63 +2305,11 @@ export type BuildAgentOptions = {
2248
2305
  onToolCancellationFence?: (fence: TurnToolCancellationFence) => void;
2249
2306
  };
2250
2307
 
2251
- /**
2252
- * Operator-facing metadata for the workspace environment attached to a run.
2253
- * Surfaced verbatim in the agent instructions: the description is where
2254
- * operators document how the exported credentials are meant to be used
2255
- * (e.g. which variable holds a deploy key and how to clone with it), so an
2256
- * agent must not have to rediscover that by enumerating `env` and guessing.
2257
- * Only metadata belongs here — never variable values.
2258
- */
2259
- export type WorkspaceEnvironmentContext = {
2260
- name: string;
2261
- description?: string | null;
2262
- variableNames?: string[];
2263
- };
2264
-
2265
2308
  /** @deprecated Persistent display metadata is no longer model-visible. */
2266
2309
  export type PersistentSessionSettings = {
2267
2310
  titleIsSet: boolean;
2268
2311
  };
2269
2312
 
2270
- /**
2271
- * The rig a session rides (M3): its name + the active version pinned onto the
2272
- * session. Surfaced verbatim in the non-bypassable CORE instructions so the
2273
- * agent understands its sandbox is a disposable fork of a shared, versioned
2274
- * machine definition and how to promote a durable change. Absent for rig-less
2275
- * sessions (the block never renders).
2276
- */
2277
- export type RigInstructionsContext = {
2278
- name: string;
2279
- version: number;
2280
- };
2281
-
2282
- export function rigInstructions(rig: RigInstructionsContext): string[] {
2283
- return [
2284
- `This session uses sandbox environment "${rig.name}" (active version v${rig.version}) — a versioned definition of custom sandbox setup and health checks.`,
2285
- "Your sandbox is an EPHEMERAL FORK of this environment. You may install tools here, but local changes do not update the environment definition or other sessions.",
2286
- "To make a verified setup change available to future sessions using this environment, call rig_propose_change with the exact command that already worked here. Never assume an unverified change propagates.",
2287
- "If tooling you expect is missing, consult rig_get to see the sandbox environment's current setup and checks before reinstalling.",
2288
- ];
2289
- }
2290
-
2291
- export function workspaceEnvironmentInstructions(
2292
- environment: WorkspaceEnvironmentContext,
2293
- ): string[] {
2294
- const lines = [
2295
- `A workspace environment named "${environment.name}" is attached to this session; its variables are exported in the sandbox shell environment.`,
2296
- ];
2297
- const variableNames = (environment.variableNames ?? []).filter((name) => name.length > 0);
2298
- if (variableNames.length > 0) {
2299
- lines.push(`Exported environment variables: ${[...variableNames].sort().join(", ")}.`);
2300
- }
2301
- const description = environment.description?.trim();
2302
- if (description) {
2303
- lines.push(`Environment notes from the operator: ${description}`);
2304
- }
2305
- return lines;
2306
- }
2307
-
2308
2313
  /**
2309
2314
  * The non-bypassable CORE of the agent instructions: the goal-loop ownership
2310
2315
  * line (which names the opengeni__goal_* tools and is what keeps a long-running
@@ -2322,6 +2327,7 @@ export function coreInstructions(
2322
2327
  ): string[] {
2323
2328
  return [
2324
2329
  "If the session has a goal, you own it: keep working until you call opengeni__goal_complete with concrete evidence or opengeni__goal_pause with a rationale; revise it with opengeni__goal_update; create one with opengeni__goal_set when given a long-running objective. Resume a paused goal with opengeni__goal_resume when the user asks you to continue, regardless of who paused it, or when the blocker you paused for has cleared. A question alone is not such a request: answer it and leave the goal paused.",
2330
+ "Goal completion records short ledger proof, not the user-facing deliverable. After goal_complete succeeds, finish the same turn with the requested answer, or a concise summary and retained artifact link. Never use evidence as the final reply. A later child result after completion is context to integrate, not a reason to stay silent or restart the completed goal.",
2325
2331
  'Choose durable storage by purpose, including requests to "remember this" or keep something "for future sessions". Knowledge is retrieval-only information, not standing behavior. Use instruction_policy_get then instruction_policy_save for short always-on workspace rules, such as "Keep replies concise; expand when asked." Use Skills for reusable procedures and context-specific or personal behavioral preferences; make the Skill description state when it applies so the prompt index can guide skill_read. Do not save behavioral preferences as Knowledge by rephrasing them as facts like "the user prefers concise replies". Preserve the intended scope: do not turn a personal preference into a workspace-wide rule; use an authorized personal Skill when appropriate, or explain the unavailable scope. Split mixed requests into a short rule and detailed Skill steps without duplicating them in Knowledge.',
2326
2332
  "Before changing workspace instructions, read the current instruction and exact baseline, preserve unrelated rules, append new rules, and use only a localized exact anchored edit for updates or removals. Agents cannot replace the complete instruction; whole-policy rewrites belong in the manual workspace editor. Do not bypass a destination's Agent learning setting, review, scope, limits, or unavailable tools by saving to another destination. Report the actual destination and receipt: active, pending review, or not saved. Do not promise future behavior from a Knowledge save.",
2327
2333
  "Use knowledge_search and knowledge_get when retained information is relevant. For questions about what the workspace knows, ground the answer in authorized Knowledge and attached sources. Missing internal facts remain unknown; do not infer a person's role or cite unrelated public search results as evidence. Keep any relevant external research clearly separate from workspace records. Default retrieval returns published information. Before retaining or correcting anything, also search view=needs_review for existing pending entries and collections; read those with knowledge_get view=needs_review. Pending means unapproved: you may inspect and improve it, but do not present it as accepted knowledge or activate behavioral guidance from it. Reuse the existing entryId and current version instead of creating another proposal each run. Save durable facts, decisions, requirements, incidents, fixes and outcomes autonomously with knowledge_save only when they help a plausible future task. Do not retain routine approvals, acknowledgments, temporary task instructions, status chatter or raw screenshots merely because they occurred. Before saving, use knowledge_prepare_save when available to fetch the authorized collection map with descriptions and parent IDs plus related published and pending entries; otherwise search both views and browse collections. Skip unchanged duplicates, improve the existing entry when appropriate, and create a new entry only for distinct useful information. Read the current entry before correcting it and preserve uncertainty, conflicting evidence and existing relationships. When a user supplies or confirms a durable fact, use knowledge_retain_message to retain the actual message and cite its returned entryId/revisionId in the finding evidence. Preserve existing source evidence and relationships when correcting an entry; do not replace them with empty arrays merely because the user confirmed a new value. Explicit confirmation can supersede a conflicting pending proposal, but explain that outcome to the user. Preserve uncertainty and exact supporting evidence; the fact label is not a verification claim. Chat attachments retain their original files for the conversation without automatically publishing OCR or source text into Knowledge. Inspect an image visually in the current task; save only a useful supported observation, requirement or incident when warranted. Use knowledge_retain_file purpose=evidence only when a selected finding needs the original as supporting evidence, or purpose=reference when deliberately retaining a reusable source document. Supporting sources remain accessible through evidence links and explicit includeEvidence searches, but do not fill ordinary Knowledge discovery. An upload alone is not a reason to save Knowledge. A source entry contains retained original text; a finding states a useful conclusion and cites the exact source revision. Do not create both when they would simply repeat the same text. Reuse collections for customers, products, systems or subjects across sources, and link one entry to multiple collections instead of copying it. Technical incidents belong with the affected system and should include cause, fix and outcome when known. Reorganize references when useful; do not erase source evidence or revision history. Private tasks author personal Knowledge; shared tasks author workspace Knowledge. Automatic publishes immediately, Review first keeps a pending proposal without pausing your task, and Off prevents authoring while permitting retrieval. Never bypass review by making a new entry, switching tools, or asking for another approval. Reuse the same operationId and exact request after an uncertain save, including recovery. Use task_note_save for temporary coordination in this task tree. Conversation history is separate. Workspace instructions are concise standing rules; Skills are reusable procedures with their own Agent learning settings. Do not save the same content in multiple authorities.",
@@ -2402,10 +2408,84 @@ function gitBindingDiscoveryApplies(
2402
2408
  return [...bindingsByProvider.values()].some((ids) => ids.size > 1);
2403
2409
  }
2404
2410
 
2411
+ /**
2412
+ * Resource facts for modular module selection. Every input is a session- or
2413
+ * turn-level fact, so the composed prefix changes only when they change.
2414
+ */
2415
+ export function agentPromptResourcesFor(
2416
+ settings: Settings,
2417
+ resources: readonly ResourceRef[],
2418
+ options: Pick<
2419
+ BuildAgentOptions,
2420
+ | "activeSandboxBackend"
2421
+ | "fileResourceDownloads"
2422
+ | "gitCredentialBindings"
2423
+ | "gitTokenSeed"
2424
+ | "gitTokenSeeds"
2425
+ | "workspaceEnvironment"
2426
+ | "rig"
2427
+ >,
2428
+ ): AgentPromptResources {
2429
+ const backend = options.activeSandboxBackend ?? settings.sandboxBackend;
2430
+ const connectedMachine = backend === "selfhosted";
2431
+ const managedSandbox = backend !== "none" && !connectedMachine;
2432
+ const gitTokenSeeds = Object.values(options.gitTokenSeeds ?? {}).filter(Boolean);
2433
+ return {
2434
+ managedSandbox,
2435
+ connectedMachine,
2436
+ // A Connected Machine never receives platform clones.
2437
+ repositories: managedSandbox && resources.some((resource) => resource.kind === "repository"),
2438
+ gitCredentials:
2439
+ managedSandbox &&
2440
+ (Boolean(options.gitTokenSeed) ||
2441
+ gitTokenSeeds.length > 0 ||
2442
+ (options.gitCredentialBindings?.length ?? 0) > 0),
2443
+ attachments:
2444
+ (managedSandbox || connectedMachine) &&
2445
+ (resources.some((resource) => resource.kind === "file") ||
2446
+ (options.fileResourceDownloads?.length ?? 0) > 0),
2447
+ ...(options.workspaceEnvironment ? { workspaceEnvironment: options.workspaceEnvironment } : {}),
2448
+ ...(options.rig ? { rig: options.rig } : {}),
2449
+ };
2450
+ }
2451
+
2452
+ function inspectModularAgentInstructions(
2453
+ settings: Settings,
2454
+ config: ResolvedAgentConfig,
2455
+ options: BuildAgentOptions,
2456
+ ): PersistentAgentInstructionInspection {
2457
+ const identity = resolveAgentIdentity({
2458
+ sessionIdentity: config.identity,
2459
+ workspaceIdentity: options.workspaceAgentIdentity ?? options.instructionsTemplate,
2460
+ deploymentTemplate: settings.agentInstructionsTemplate,
2461
+ });
2462
+ const composed = composeModularAgentInstructions({
2463
+ capabilities: config.capabilities,
2464
+ renderer: config.renderer,
2465
+ identity,
2466
+ resources: options.agentPromptResources ?? agentPromptResourcesFor(settings, [], options),
2467
+ ...(codemodeIsAvailable(options) ? { codemode: CODEMODE_PROGRAMMATIC_DIRECTIVE } : {}),
2468
+ ...(options.codeSearchAvailable ? { codeSearch: CODE_SEARCH_DIRECTIVE } : {}),
2469
+ ...(gitBindingDiscoveryApplies(options.gitCredentialBindings, options.activeSandboxBackend)
2470
+ ? { gitBindings: GIT_BINDING_DISCOVERY_DIRECTIVE }
2471
+ : {}),
2472
+ ...(options.skillCatalog && !options.skillCatalogInHistory
2473
+ ? { skillCatalog: formatSkillCatalog(options.skillCatalog) }
2474
+ : {}),
2475
+ workspaceGovernance: options.workspaceGovernance,
2476
+ workspaceMemory: options.workspaceMemory,
2477
+ sessionInstructions: options.sessionInstructions,
2478
+ });
2479
+ return { layers: composed.layers, composed: composed.composed };
2480
+ }
2481
+
2405
2482
  export function inspectPersistentAgentInstructions(
2406
2483
  settings: Settings,
2407
2484
  options: BuildAgentOptions,
2408
2485
  ): PersistentAgentInstructionInspection {
2486
+ if (options.agentConfig) {
2487
+ return inspectModularAgentInstructions(settings, options.agentConfig, options);
2488
+ }
2409
2489
  const personaAndCore = composeAgentInstructions(
2410
2490
  options.instructionsTemplate ?? settings.agentInstructionsTemplate,
2411
2491
  options.workspaceEnvironment,
@@ -2679,6 +2759,10 @@ export function buildOpenGeniAgent(
2679
2759
  resources: ResourceRef[],
2680
2760
  options: BuildAgentOptions = {},
2681
2761
  ): Agent<any, any> {
2762
+ if (resolveAgentToolFamilies(options.agentConfig).skills === false) {
2763
+ const { skillActivations: _disabledActivations, ...withoutSkills } = options;
2764
+ options = { ...withoutSkills, skillCatalog: [] };
2765
+ }
2682
2766
  if (Boolean(options.codemodeTokenSeed) !== Boolean(options.codemodeTokenSessionId)) {
2683
2767
  throw new Error("codemodeTokenSeed and codemodeTokenSessionId must be supplied together");
2684
2768
  }
@@ -2712,12 +2796,24 @@ export function buildOpenGeniAgent(
2712
2796
  const instructionOptions: BuildAgentOptions = {
2713
2797
  ...options,
2714
2798
  ...(skillCatalog !== undefined ? { skillCatalog } : {}),
2799
+ ...(options.agentConfig && !options.agentPromptResources
2800
+ ? { agentPromptResources: agentPromptResourcesFor(settings, resources, options) }
2801
+ : {}),
2715
2802
  };
2716
2803
  // Resolved per-turn gating. Each override defaults to today's settings-derived
2717
2804
  // behaviour, so the legacy global-client callers (no resolved model) build the
2718
2805
  // exact same agent as before; the multi-provider worker path passes the
2719
2806
  // resolved provider's api/window/web-search instead.
2720
- const hostedWebSearch = options.hostedWebSearch ?? settings.webSearchEnabled;
2807
+ const toolFamilies = resolveAgentToolFamilies(options.agentConfig, {
2808
+ hasSkills: (skillCatalog?.length ?? 0) > 0,
2809
+ webSearch: options.hostedWebSearch ?? settings.webSearchEnabled,
2810
+ humanInput: options.humanInputEnabled !== false,
2811
+ });
2812
+ const hostedWebSearch = toolFamilies.webSearch;
2813
+ const mediaTools = resolveAgentMediaToolSurface(options.agentConfig, {
2814
+ image: options.imageGeneration?.kind ?? null,
2815
+ video: Boolean(options.videoGeneration),
2816
+ });
2721
2817
  const encryptedReasoning = options.encryptedReasoning ?? settings.openaiReasoningEncryptedContent;
2722
2818
  // Wire value must be provider-mapped by the caller (OpenAI `fast`, Azure/Codex
2723
2819
  // `priority`). Do not fall back to latencyMode itself — that would send
@@ -2739,28 +2835,29 @@ export function buildOpenGeniAgent(
2739
2835
  // [...agent.tools, ...capability.tools()]), so hosted web_search coexists with
2740
2836
  // both rather than overriding them.
2741
2837
  const hostedTools: Tool[] = hostedWebSearch ? [webSearchTool()] : [];
2742
- if (options.imageGeneration?.kind === "native_hosted") {
2838
+ if (mediaTools.hosted.includes("image_generation")) {
2743
2839
  hostedTools.push(imageGenerationTool({ model: "gpt-image-2" }));
2744
2840
  }
2745
- const providerImageGenerationTool =
2746
- options.imageGeneration?.kind === "provider_adapter"
2747
- ? agentTool({
2748
- name: "generate_image",
2749
- description:
2750
- "Generate or edit exactly one image. Optionally provide up to four ordered references using exact /workspace paths, workspace File IDs, or generated-image artifact IDs; every reference must be a PNG, JPEG, or WebP image, so convert SVG or other formats first. Describe each reference's role by position in the prompt. The result is a permanent image artifact and its exact sandbox path. Do not call repeatedly unless the user requested multiple distinct images.",
2751
- parameters: GenerateImageToolInput,
2752
- errorFunction: null,
2753
- execute: async (input, _context, details) => {
2754
- const toolCallId = details?.toolCall?.callId;
2755
- if (!toolCallId) throw new Error("Image-generation tool call has no durable identity");
2756
- if (options.imageGeneration?.kind !== "provider_adapter") {
2757
- throw new Error("Image-generation adapter changed during execution");
2758
- }
2759
- return await options.imageGeneration.execute(input, { toolCallId });
2760
- },
2761
- })
2762
- : null;
2763
- const videoGenerationCapabilityTool = options.videoGeneration
2841
+ const providerImageGenerationTool = mediaTools.runtime.includes("generate_image")
2842
+ ? agentTool({
2843
+ name: "generate_image",
2844
+ description:
2845
+ "Generate or edit exactly one image. Optionally provide up to four ordered references using exact /workspace paths, workspace File IDs, or generated-image artifact IDs; every reference must be a PNG, JPEG, or WebP image, so convert SVG or other formats first. Describe each reference's role by position in the prompt. The result is a permanent image artifact and its exact sandbox path. Do not call repeatedly unless the user requested multiple distinct images.",
2846
+ parameters: GenerateImageToolInput,
2847
+ errorFunction: null,
2848
+ execute: async (input, _context, details) => {
2849
+ const toolCallId = details?.toolCall?.callId;
2850
+ if (!toolCallId) throw new Error("Image-generation tool call has no durable identity");
2851
+ if (options.imageGeneration?.kind !== "provider_adapter") {
2852
+ throw new Error("Image-generation adapter changed during execution");
2853
+ }
2854
+ return await options.imageGeneration.execute(input, { toolCallId });
2855
+ },
2856
+ })
2857
+ : null;
2858
+ const videoGenerationCapabilityTool = mediaTools.runtime.includes(
2859
+ "get_video_generation_capabilities",
2860
+ )
2764
2861
  ? agentTool({
2765
2862
  name: "get_video_generation_capabilities",
2766
2863
  description:
@@ -2774,7 +2871,7 @@ export function buildOpenGeniAgent(
2774
2871
  },
2775
2872
  })
2776
2873
  : null;
2777
- const videoGenerationTool = options.videoGeneration
2874
+ const videoGenerationTool = mediaTools.runtime.includes("generate_video")
2778
2875
  ? agentTool({
2779
2876
  name: "generate_video",
2780
2877
  description:
@@ -2790,54 +2887,53 @@ export function buildOpenGeniAgent(
2790
2887
  },
2791
2888
  })
2792
2889
  : null;
2793
- const humanInputTool =
2794
- options.humanInputEnabled === false
2795
- ? null
2796
- : agentTool({
2797
- name: HUMAN_INPUT_TOOL_NAME,
2798
- description:
2799
- "Pause this turn and request structured human input. Use for decisions or missing information that only a person can provide. Supports free text, single-select, multi-select, multiple questions, explicit skip policy, and an optional expiry. Every single-select or multi-select question also gives the person an Other field for an exact free-text answer; interpret that answer normally and make a new request only if genuine clarification is still needed.",
2800
- parameters: RequestHumanInputToolInput,
2801
- needsApproval: true,
2802
- inputGuardrails: [
2803
- {
2804
- name: "validate_human_input_request",
2805
- run: async ({ toolCall }) => {
2806
- let input: unknown;
2807
- try {
2808
- input = JSON.parse(toolCall.arguments);
2809
- } catch {
2810
- return ToolGuardrailFunctionOutputFactory.rejectContent(
2811
- "Invalid request_human_input arguments. Call the tool again with valid JSON matching its schema.",
2812
- );
2813
- }
2814
- if (!RequestHumanInputToolInput.safeParse(input).success) {
2815
- return ToolGuardrailFunctionOutputFactory.rejectContent(
2816
- "Invalid request_human_input arguments. Call the tool again with an object matching its schema; questions must be an array, not JSON text.",
2817
- );
2818
- }
2819
- return ToolGuardrailFunctionOutputFactory.allow();
2820
- },
2890
+ const humanInputTool = !toolFamilies.humanInput
2891
+ ? null
2892
+ : agentTool({
2893
+ name: HUMAN_INPUT_TOOL_NAME,
2894
+ description:
2895
+ "Pause this turn and request structured human input. Use for decisions or missing information that only a person can provide. Supports free text, single-select, multi-select, multiple questions, explicit skip policy, and an optional expiry. Every single-select or multi-select question also gives the person an Other field for an exact free-text answer; interpret that answer normally and make a new request only if genuine clarification is still needed.",
2896
+ parameters: RequestHumanInputToolInput,
2897
+ needsApproval: true,
2898
+ inputGuardrails: [
2899
+ {
2900
+ name: "validate_human_input_request",
2901
+ run: async ({ toolCall }) => {
2902
+ let input: unknown;
2903
+ try {
2904
+ input = JSON.parse(toolCall.arguments);
2905
+ } catch {
2906
+ return ToolGuardrailFunctionOutputFactory.rejectContent(
2907
+ "Invalid request_human_input arguments. Call the tool again with valid JSON matching its schema.",
2908
+ );
2909
+ }
2910
+ if (!RequestHumanInputToolInput.safeParse(input).success) {
2911
+ return ToolGuardrailFunctionOutputFactory.rejectContent(
2912
+ "Invalid request_human_input arguments. Call the tool again with an object matching its schema; questions must be an array, not JSON text.",
2913
+ );
2914
+ }
2915
+ return ToolGuardrailFunctionOutputFactory.allow();
2821
2916
  },
2822
- ],
2823
- // A missing/mismatched durable response is a protocol integrity failure,
2824
- // not model-visible tool output the agent may reason past.
2825
- errorFunction: null,
2826
- execute: (_input, _context, details) => {
2827
- const settled = options.humanInputResponse;
2828
- if (!settled) {
2829
- throw new Error("Human-input tool resumed without a durable response");
2830
- }
2831
- const resumedCallId = details?.toolCall?.callId;
2832
- if (resumedCallId && resumedCallId !== settled.toolCallId) {
2833
- throw new Error("Human-input response does not belong to the resumed tool call");
2834
- }
2835
- return JSON.stringify({
2836
- requestId: settled.requestId,
2837
- ...settled.response,
2838
- });
2839
2917
  },
2840
- });
2918
+ ],
2919
+ // A missing/mismatched durable response is a protocol integrity failure,
2920
+ // not model-visible tool output the agent may reason past.
2921
+ errorFunction: null,
2922
+ execute: (_input, _context, details) => {
2923
+ const settled = options.humanInputResponse;
2924
+ if (!settled) {
2925
+ throw new Error("Human-input tool resumed without a durable response");
2926
+ }
2927
+ const resumedCallId = details?.toolCall?.callId;
2928
+ if (resumedCallId && resumedCallId !== settled.toolCallId) {
2929
+ throw new Error("Human-input response does not belong to the resumed tool call");
2930
+ }
2931
+ return JSON.stringify({
2932
+ requestId: settled.requestId,
2933
+ ...settled.response,
2934
+ });
2935
+ },
2936
+ });
2841
2937
  const agentTools = [
2842
2938
  ...hostedTools,
2843
2939
  ...(providerImageGenerationTool ? [providerImageGenerationTool] : []),
@@ -2846,7 +2942,9 @@ export function buildOpenGeniAgent(
2846
2942
  ...(humanInputTool ? [humanInputTool] : []),
2847
2943
  ];
2848
2944
  const embeddedSkillReadTool =
2849
- !hostSuppliedSkillCatalog && skillComposition.artifacts.length > 0
2945
+ toolFamilies.allowsFunctionTool("skill_read") &&
2946
+ !hostSuppliedSkillCatalog &&
2947
+ skillComposition.artifacts.length > 0
2850
2948
  ? agentTool({
2851
2949
  name: "skill_read",
2852
2950
  description:
@@ -3107,11 +3205,13 @@ function maybeInstallLazyToolTransport(
3107
3205
  settings: Settings,
3108
3206
  options: BuildAgentOptions,
3109
3207
  ): void {
3110
- const transport = options.lazyToolTransport;
3208
+ const transport =
3209
+ options.lazyToolTransport ??
3210
+ (options.agentConfig && options.toolRouterInHistory ? "generic_dispatch" : undefined);
3111
3211
  if (!transport) return;
3112
3212
  const enabled =
3113
3213
  transport === "codex_native" ? settings.codexToolSearchEnabled : settings.lazyToolSearchEnabled;
3114
- if (!enabled) return;
3214
+ if (!enabled && !(options.agentConfig && options.toolRouterInHistory)) return;
3115
3215
 
3116
3216
  const mcpServers = options.mcpServers ?? [];
3117
3217
  // Prepared servers use exact model-name mappings, not SDK lifecycle names
@@ -3141,6 +3241,8 @@ function maybeInstallLazyToolTransport(
3141
3241
  }
3142
3242
  return identities;
3143
3243
  },
3244
+ options.agentConfig != null,
3245
+ options.toolRouterInHistory === true,
3144
3246
  );
3145
3247
  }
3146
3248
 
@@ -3873,6 +3975,15 @@ function buildAgentCapabilitiesFromComposition(
3873
3975
  // readiness proof, which reaches bounded same-turn recovery.
3874
3976
  execCommandErrorFunction: (_context, error) => {
3875
3977
  if (isModalTaskExecStartPreDispatchUnavailableError(error)) throw error;
3978
+ if (isRoutingMutationOutcomeUnknownError(error)) {
3979
+ // The outer physical fence must retain the exact process before
3980
+ // rendering uncertainty. Platform/setup calls still throw normally.
3981
+ if (toolCancellation) throw error;
3982
+ return renderRoutingMutationOutcomeUnknownToolResult(error);
3983
+ }
3984
+ if (isModalCommandStartOutcomeUnknownError(error)) {
3985
+ return "Managed sandbox command start outcome unknown. The command may have executed. Do not blindly retry it; inspect the existing sandbox state before taking further action.";
3986
+ }
3876
3987
  const details = error instanceof Error ? error.toString() : String(error);
3877
3988
  return `An error occurred while running the tool. Please try again. Error: ${details}`;
3878
3989
  },
@@ -4009,6 +4120,8 @@ export type PrepareToolsOptions = {
4009
4120
  executionGeneration?: number;
4010
4121
  subjectId?: string;
4011
4122
  subjectLabel?: string;
4123
+ /** Trusted immutable setup ceiling from the accepted execution policy. */
4124
+ credentialRestriction?: "developer_setup";
4012
4125
  // Immutable human authority used only for subject-owned connection lookup.
4013
4126
  // This is intentionally separate from the worker's first-party MCP identity.
4014
4127
  credentialSubjectId?: string;
@@ -4378,6 +4491,7 @@ export async function prepareAgentTools(
4378
4491
  settings.mcpServers.filter(
4379
4492
  (config) =>
4380
4493
  tools.some((tool) => tool.id === config.id) &&
4494
+ !config.connectionRef &&
4381
4495
  !localRegistry.has(config.id) &&
4382
4496
  !isFirstPartyMcpServer(settings, config) &&
4383
4497
  !isCodexAppsMcpServer(config),
@@ -5001,6 +5115,7 @@ export function selectedSessionRemoteMcpTargets(
5001
5115
  if (configs.length !== 1) return [];
5002
5116
  const config = configs[0]!;
5003
5117
  if (
5118
+ config.connectionRef ||
5004
5119
  isFirstPartyMcpServer(settings, config) ||
5005
5120
  isCodexAppsMcpServer(config) ||
5006
5121
  BUILT_IN_MCP_BRIDGE_ADAPTERS.some((adapter) =>
@@ -6309,6 +6424,7 @@ type McpPublicErrorFields = {
6309
6424
  };
6310
6425
 
6311
6426
  type McpPublicFailureCode =
6427
+ | "mcp_cleanup_failed"
6312
6428
  | "mcp_connect_failed"
6313
6429
  | "mcp_close_failed"
6314
6430
  | "mcp_transport_failed"
@@ -6669,27 +6785,7 @@ function exactMcpLifecycleError(error: unknown, options: McpTransportErrorOption
6669
6785
  }
6670
6786
 
6671
6787
  function mcpTransportLogger(serverId: string) {
6672
- const logFailure = (_message: string, ...args: unknown[]) => {
6673
- let error: unknown;
6674
- for (let index = args.length - 1; index >= 0; index -= 1) {
6675
- if (args[index] instanceof Error) {
6676
- error = args[index];
6677
- break;
6678
- }
6679
- }
6680
- console.warn(
6681
- "[mcp] transport operation failed",
6682
- mcpErrorFields(error, "mcp_transport_failed", serverId),
6683
- );
6684
- };
6685
- return {
6686
- namespace: "opengeni:mcp-transport",
6687
- debug: () => undefined,
6688
- error: logFailure,
6689
- warn: logFailure,
6690
- dontLogModelData: true,
6691
- dontLogToolData: true,
6692
- };
6788
+ return createMcpTransportLogger(serverId, mcpErrorFields);
6693
6789
  }
6694
6790
 
6695
6791
  async function mcpServerRequestInit(
@@ -6777,6 +6873,9 @@ async function signFirstPartyDelegatedBearer(
6777
6873
  workspaceId: options.workspaceId,
6778
6874
  subjectId: options.subjectId ?? "worker:first-party-mcp",
6779
6875
  ...(options.subjectLabel ? { subjectLabel: options.subjectLabel } : {}),
6876
+ ...(options.credentialRestriction
6877
+ ? { credentialRestriction: options.credentialRestriction }
6878
+ : {}),
6780
6879
  permissions: options.firstPartyPermissions ?? [...DEFAULT_FIRST_PARTY_MCP_PERMISSIONS],
6781
6880
  principalKind: hasExactAttemptClaims ? "agent_attempt" : "service",
6782
6881
  firstPartyMcpTools: options.firstPartyTools ?? [...DEFAULT_FIRST_PARTY_MCP_TOOLS],
@@ -8050,6 +8149,10 @@ export async function prepareRunInput(
8050
8149
  }
8051
8150
 
8052
8151
  export type RunAgentStreamOptions = {
8152
+ /** Producer-side gate before calling any resolved model/provider. */
8153
+ beforeModelRequest?: ModelCallLifecycle["beforeModelRequest"];
8154
+ /** Register terminal response settlement before the next producer model request. */
8155
+ onModelResponse?: ModelCallLifecycle["onModelResponse"];
8053
8156
  /** Abort the provider/tool loop when the owning activity is cancelled. */
8054
8157
  signal?: AbortSignal;
8055
8158
  /** Nonblocking phase measurements for request preparation before provider I/O. */
@@ -8261,6 +8364,8 @@ function bindModelVisibleContextCapture(
8261
8364
  body,
8262
8365
  ...(unavailableReason ? { unavailableReason } : {}),
8263
8366
  requestIndex: index ?? nextModelContextCaptureIndex(agent),
8367
+ persistentLayers: persistentAgentInstructionInspectionFor(agent).layers,
8368
+ genesisTitleDirective: GENESIS_TITLE_DIRECTIVE,
8264
8369
  }),
8265
8370
  );
8266
8371
  };
@@ -8293,8 +8398,17 @@ export async function runAgentStream(
8293
8398
  const scope = gate?.beginStream(overrides.signal);
8294
8399
  try {
8295
8400
  if (scope) agent.toolUseBehavior = scope.toolUseBehavior;
8296
- const stream = await withPreparedCompactionRequest(agent, () =>
8297
- runAgentStreamInternal(agent, input, settings, overrides, scope),
8401
+ const stream = await withModelCallLifecycle(
8402
+ {
8403
+ ...(overrides.beforeModelRequest
8404
+ ? { beforeModelRequest: overrides.beforeModelRequest }
8405
+ : {}),
8406
+ ...(overrides.onModelResponse ? { onModelResponse: overrides.onModelResponse } : {}),
8407
+ },
8408
+ () =>
8409
+ withPreparedCompactionRequest(agent, () =>
8410
+ runAgentStreamInternal(agent, input, settings, overrides, scope),
8411
+ ),
8298
8412
  );
8299
8413
  // Observe the SDK's own settlement promise before exposing the stream. Do
8300
8414
  // not wrap/replace SDK history, errors, cancellation, or stream iteration.
@@ -127,6 +127,13 @@ export class InputWaitYield {
127
127
  await this.drain(this.scope, signal);
128
128
  }
129
129
 
130
+ /** A settled stream may need one final-reply handoff before attempt closure.
131
+ * Drain already-admitted receipts without reopening that stream's admission.
132
+ */
133
+ async drainForHandoff(signal = this.scope.signal): Promise<void> {
134
+ await this.drain(this.scope, signal);
135
+ }
136
+
130
137
  private endStream(scope: StreamScope): void {
131
138
  scope.phase = "settled";
132
139
  scope.ended = true;