@opengeni/runtime 4.0.3 → 4.1.0-canary.36239117573001

package/src/knowledge-model-projection.ts

@@ -0,0 +1,169 @@
+import {
+  KnowledgeEntryListResponse,
+  KnowledgeSavePreparationResponse,
+  type AttemptToolIdentity,
+  type AttemptToolResult as AttemptToolResultValue,
+} from "@opengeni/contracts";
+
+type JsonRecord = Record<string, unknown>;
+
+type KnowledgeModelProjection = "entry_list" | "save_preparation";
+
+/**
+ * The model-visible copy of a Knowledge discovery result.
+ *
+ * `knowledge_search` (first-party and Docs servers) and `knowledge_prepare_save`
+ * return the complete contract to every caller. Codemode and other programmatic
+ * callers keep those exact bytes; only the model caller receives this
+ * projection (see `projectAttemptToolResultForCaller`). It is the same JSON with
+ * bookkeeping and repeated text removed:
+ *
+ * - entry timestamps, rank score, revision lineage/session/batch/number fields;
+ * - defaults: `archived: false`, `change: "upsert"`, `sourceKind: null`, and a
+ *   collection's `descriptionTruncated: false`;
+ * - `publishedRevisionId`/`latestRevisionId` and `revision.entryId` when they
+ *   repeat `revision.id`/`id` (a differing value is kept);
+ * - `revision.preview` only when its complete text already appears verbatim in
+ *   the title or an excerpt, and title-field excerpts contained in the title;
+ * - a collection descriptor's `revisionId` (collections are saved by `id` and
+ *   `version` and read by `view`; they are never cited as evidence).
+ *
+ * Everything needed to act is kept: entry and collection IDs, `version` (the
+ * `expectedVersion` for an update), `revision.id` (evidence pins), scope,
+ * view/outcome status, titles, kinds, group/parent IDs, descriptions, excerpts
+ * with their offsets, index status and pagination cursors. Nothing is truncated.
+ * A result that is an error, carries structured content, or does not strictly
+ * match the contract is returned unchanged.
+ */
+export function projectKnowledgeToolResultForModel(
+  identity: AttemptToolIdentity,
+  result: AttemptToolResultValue,
+): AttemptToolResultValue {
+  const projection = knowledgeModelProjection(identity);
+  if (!projection || result.isError === true || result.structuredContent !== undefined) {
+    return result;
+  }
+  if (result.content.length !== 1) return result;
+  const [content] = result.content;
+  if (content?.type !== "text") return result;
+  let value: unknown;
+  try {
+    value = JSON.parse(content.text);
+  } catch {
+    return result;
+  }
+  const compact =
+    projection === "entry_list" ? compactEntryList(value) : compactSavePreparation(value);
+  if (!compact) return result;
+  const text = JSON.stringify(compact);
+  if (text.length >= content.text.length) return result;
+  return { ...result, content: [{ ...content, text }] };
+}
+
+function knowledgeModelProjection(identity: AttemptToolIdentity): KnowledgeModelProjection | null {
+  if (
+    identity.toolName === "knowledge_search" &&
+    (identity.serverId === "opengeni" || identity.serverId === "docs")
+  ) {
+    return "entry_list";
+  }
+  if (identity.toolName === "knowledge_prepare_save" && identity.serverId === "opengeni") {
+    return "save_preparation";
+  }
+  return null;
+}
+
+function compactEntryList(value: unknown): JsonRecord | null {
+  if (!KnowledgeEntryListResponse.safeParse(value).success) return null;
+  return compactListResponse(value as JsonRecord);
+}
+
+function compactSavePreparation(value: unknown): JsonRecord | null {
+  if (!KnowledgeSavePreparationResponse.safeParse(value).success) return null;
+  const response = value as JsonRecord & {
+    collections: JsonRecord & { entries: JsonRecord[] };
+    matches: JsonRecord & { published: JsonRecord; needs_review: JsonRecord };
+  };
+  return {
+    ...response,
+    collections: {
+      ...response.collections,
+      entries: response.collections.entries.map(compactCollection),
+    },
+    matches: {
+      ...response.matches,
+      published: compactListResponse(response.matches.published),
+      needs_review: compactListResponse(response.matches.needs_review),
+    },
+  };
+}
+
+function compactListResponse(response: JsonRecord): JsonRecord {
+  return { ...response, entries: (response.entries as JsonRecord[]).map(compactEntrySummary) };
+}
+
+function compactCollection(collection: JsonRecord): JsonRecord {
+  const { revisionId: _revisionId, descriptionTruncated, ...kept } = collection;
+  return { ...kept, ...(descriptionTruncated === false ? {} : { descriptionTruncated }) };
+}
+
+function compactEntrySummary(entry: JsonRecord): JsonRecord {
+  const {
+    score: _score,
+    createdAt: _createdAt,
+    updatedAt: _updatedAt,
+    archived,
+    publishedRevisionId,
+    latestRevisionId,
+    excerpts,
+    revision,
+    ...kept
+  } = entry;
+  const {
+    entryId,
+    number: _number,
+    change,
+    previousRevisionId: _previousRevisionId,
+    restoredFromRevisionId: _restoredFromRevisionId,
+    createdAt: _revisionCreatedAt,
+    createdBySessionId: _createdBySessionId,
+    reviewBatchId: _reviewBatchId,
+    sourceKind,
+    preview,
+    ...keptRevision
+  } = revision as JsonRecord;
+  const revisionId = keptRevision.id;
+  const excerptList = (excerpts ?? []) as JsonRecord[];
+  return {
+    ...kept,
+    ...(archived === false ? {} : { archived }),
+    ...(publishedRevisionId === revisionId ? {} : { publishedRevisionId }),
+    ...(latestRevisionId === revisionId ? {} : { latestRevisionId }),
+    revision: {
+      ...keptRevision,
+      ...(entryId === entry.id ? {} : { entryId }),
+      ...(change === "upsert" ? {} : { change }),
+      ...(sourceKind === null ? {} : { sourceKind }),
+      ...(previewAlreadyShown(preview, excerptList) ? {} : { preview }),
+    },
+    ...(excerpts === undefined ? {} : { excerpts }),
+  };
+}
+
+/**
+ * The preview is the start of the entry's content. It is redundant only when
+ * it is empty or a content excerpt that starts at offset 0 already begins with
+ * it. The title never counts: a short content (a decision's answer) can be a
+ * substring of its title and still be the only place the answer appears.
+ */
+function previewAlreadyShown(preview: unknown, excerpts: readonly JsonRecord[]): boolean {
+  if (typeof preview !== "string") return false;
+  if (preview === "") return true;
+  return excerpts.some(
+    (excerpt) =>
+      excerpt.field === "content" &&
+      excerpt.start === 0 &&
+      typeof excerpt.text === "string" &&
+      excerpt.text.startsWith(preview),
+  );
+}

package/src/lazy-tool-transport.ts

@@ -38,6 +38,10 @@ const ALWAYS_VISIBLE_BASE_TOOL_NAMES: ReadonlySet<string> = new Set([
   "repository_skill_read",
   "request_human_input",
   "list_models",
+  // Jev-backed code search. Present only when the deployment and workspace
+  // enable it; hiding it behind search would spend a model round trip to find
+  // the tool that exists to save round trips.
+  "code_search",
 ]);
 const DISPATCH_MARKER_KEY = "opengeni.lazy_dispatch.v1";
 const SEARCH_MARKER_KEY = "opengeni.lazy_search.v1";

package/src/metrics.ts

@@ -15,6 +15,23 @@ export const MCP_LIFECYCLE_PHASES = ["connect", "close"] as const;
 export const MCP_LIFECYCLE_POLICIES = ["strict", "best_effort"] as const;
 export const MCP_LIFECYCLE_OUTCOMES = ["completed", "failed"] as const;
 
+/**
+ * Closed outcomes of one fresh-box command-readiness replacement decision:
+ * the replacement became ready, it also missed readiness, it failed for another
+ * typed reason, cancellation won the pause or the replacement, or the turn
+ * attempt had already spent its single replacement.
+ */
+export const SANDBOX_READINESS_REPLACEMENT_OUTCOMES = [
+  "replaced",
+  "failed_again",
+  "replacement_failed",
+  "cancelled",
+  "budget_spent",
+] as const;
+
+export type SandboxReadinessReplacementOutcome =
+  (typeof SANDBOX_READINESS_REPLACEMENT_OUTCOMES)[number];
+
 export type McpLifecyclePhase = (typeof MCP_LIFECYCLE_PHASES)[number];
 export type McpLifecyclePolicy = (typeof MCP_LIFECYCLE_POLICIES)[number];
 export type McpLifecycleOutcome = (typeof MCP_LIFECYCLE_OUTCOMES)[number];
@@ -35,6 +52,15 @@ export type RuntimeMetricsHooks = {
     backend: string;
     stage: "exec_readiness" | "sibling_warming";
   }) => void;
+  /**
+   * One fresh-box readiness replacement decision. The first readiness miss is
+   * still counted by `onSandboxWarmingTimeout`; this hook says whether the
+   * single per-turn-attempt replacement happened and whether it worked.
+   */
+  onSandboxReadinessReplacement?: (input: {
+    backend: string;
+    outcome: SandboxReadinessReplacementOutcome;
+  }) => void;
   onSandboxProviderApiThrottle?: (input: {
     backend: string;
     operation: "create" | "renew";

package/src/model-context-inspector.ts

@@ -101,6 +101,7 @@ const LAYER_TITLES: Record<ModelContextInstructionLayerId, string> = {
   session_instructions: "Session instructions",
   workspace_memory: "Workspace memory",
   codemode: "Codemode",
+  code_search: "Code search",
   git_bindings: "Git credential bindings",
   genesis_title: "Missing-title directive",
   sdk_capability_instructions: "SDK capability instructions",

package/src/model-provider-client.ts

@@ -28,6 +28,7 @@ import { isModelCallFetch, vercelGatewayRoutingFetch } from "./model-provider-tr
 import { ReplayableJsonOpenAI } from "./replayable-json-body";
 import { recordModelTransportStarted } from "./model-preparation-diagnostics";
 import { captureProviderRequestBody } from "./model-request-capture";
+import { withoutQuotaExhaustedRetries } from "./provider-quota";
 
 let runtimeMetricsHooks: RuntimeMetricsHooks | null = null;
 
@@ -85,7 +86,10 @@ export function buildOpenAIClientFromSettings(
           settings.azureOpenaiAdToken && !settings.azureOpenaiApiKey
             ? { Authorization: `Bearer ${settings.azureOpenaiAdToken}` }
             : undefined,
-        fetch: instrumentedModelFetch(providerId, globalThis.fetch),
+        fetch: sdkRetryingModelFetch(
+          settings.openaiMaxRetries,
+          instrumentedModelFetch(providerId, globalThis.fetch),
+        ),
       },
       { modelRequestPolicy: azureModelRequestPolicy },
     );
@@ -94,10 +98,23 @@ export function buildOpenAIClientFromSettings(
     apiKey: settings.openaiApiKey ?? process.env.OPENAI_API_KEY,
     ...(settings.openaiBaseUrl ? { baseURL: settings.openaiBaseUrl } : {}),
     maxRetries: settings.openaiMaxRetries,
-    fetch: instrumentedModelFetch(providerId, globalThis.fetch),
+    fetch: sdkRetryingModelFetch(
+      settings.openaiMaxRetries,
+      instrumentedModelFetch(providerId, globalThis.fetch),
+    ),
   });
 }
 
+/**
+ * A client that lets the OpenAI SDK retry 429s must not replay an exhausted
+ * provider quota: the refusal cannot clear within the SDK's backoff, and each
+ * retry only delays the typed turn failure. Clients with SDK retries disabled
+ * need no veto.
+ */
+function sdkRetryingModelFetch(maxRetries: number, inner: typeof fetch): typeof fetch {
+  return maxRetries > 0 ? withoutQuotaExhaustedRetries(inner) : inner;
+}
+
 /**
  * One OpenAI client per deployment-scoped provider configuration, built lazily
  * and cached for the process. Workspace-connection providers are deliberately
@@ -282,6 +299,11 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
     throw new WorkspaceGatewayUnavailableError();
   }
   const anonymousProvider = provider.kind === "anonymous";
+  // Gateway and OpenRouter requests can incur upstream work or charges
+  // before a retryable response failure reaches this process. Neither
+  // transport has a provider idempotency key tied to our durable call,
+  // so never let the SDK replay them blindly.
+  const registryMaxRetries = gatewayProvider || openRouterProvider ? 0 : settings.openaiMaxRetries;
   const client = provider.builtin
     ? buildOpenAIClientFromSettings(settings, provider.id)
     : provider.kind === "codex-subscription"
@@ -342,24 +364,23 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
                   ? { apiKey: provider.apiKey }
                   : {}),
               ...(provider.baseUrl ? { baseURL: provider.baseUrl } : {}),
-              // Gateway and OpenRouter requests can incur upstream work or charges
-              // before a retryable response failure reaches this process. Neither
-              // transport has a provider idempotency key tied to our durable call,
-              // so never let the SDK replay them blindly.
-              maxRetries: gatewayProvider || openRouterProvider ? 0 : settings.openaiMaxRetries,
+              maxRetries: registryMaxRetries,
               ...(provider.defaultQuery ? { defaultQuery: provider.defaultQuery } : {}),
               ...(provider.defaultHeaders ? { defaultHeaders: provider.defaultHeaders } : {}),
-              fetch: anonymousProvider
-                ? withoutAuthenticationHeaders(
-                    instrumentedModelFetch(provider.id, globalThis.fetch),
-                  )
-                : gatewayProvider
-                  ? vercelGatewayRoutingFetch(
-                      provider.kind as "vercel-gateway-managed" | "vercel-gateway-workspace",
+              fetch: sdkRetryingModelFetch(
+                registryMaxRetries,
+                anonymousProvider
+                  ? withoutAuthenticationHeaders(
                       instrumentedModelFetch(provider.id, globalThis.fetch),
-                      gatewayPolicies,
                     )
-                  : instrumentedModelFetch(provider.id, globalThis.fetch),
+                  : gatewayProvider
+                    ? vercelGatewayRoutingFetch(
+                        provider.kind as "vercel-gateway-managed" | "vercel-gateway-workspace",
+                        instrumentedModelFetch(provider.id, globalThis.fetch),
+                        gatewayPolicies,
+                      )
+                    : instrumentedModelFetch(provider.id, globalThis.fetch),
+              ),
             },
             { modelRequestPolicy: modelRequestPolicyForProvider(provider, gatewayPolicies) },
           );

package/src/model-provider-routing.ts

@@ -163,6 +163,16 @@ export class MultiProviderModelProvider implements ModelProvider {
   constructor(private readonly settings: Settings) {}
 
   async getModel(modelName?: string): Promise<Model> {
+    return this.resolveBinding(modelName).model;
+  }
+
+  /**
+   * The provider, owned client, and upstream model id that `getModel` binds.
+   * Standalone requests outside an agent run (the session-title sidecar) use
+   * this to call the provider directly instead of the runner-facing
+   * `Model.getResponse()`, which requires an active trace.
+   */
+  resolveBinding(modelName?: string): ModelProviderBinding {
     if (modelName) {
       const resolved = resolveTurnModel(
         settingsForRunScopedModelResolution(this.settings, modelName),
@@ -189,7 +199,12 @@ export class MultiProviderModelProvider implements ModelProvider {
         ) {
           throw new XaiSubscriptionUnavailableError(modelName);
         }
-        return resolved.model;
+        return {
+          provider: resolved.provider,
+          client: resolved.client,
+          model: resolved.model,
+          modelId: resolved.configured.upstreamModelId,
+        };
       }
       // A `codex/<slug>` id only resolves when the per-workspace worker overlay
       // (settingsWithCodexCredential) has injected the synthetic codex-subscription
@@ -215,14 +230,25 @@ export class MultiProviderModelProvider implements ModelProvider {
     // JSON parse/stringify transport wrapper on the fallback path.
     const builtin = configuredProviders(this.settings)[0];
     if (!builtin) throw new Error("Built-in model provider is unavailable");
-    return new OpenGeniResponsesModel(
-      buildProviderClient(builtin, this.settings),
-      modelName ?? this.settings.openaiModel,
-      builtin,
-    );
+    const client = buildProviderClient(builtin, this.settings);
+    const modelId = modelName ?? this.settings.openaiModel;
+    return {
+      provider: builtin,
+      client,
+      model: new OpenGeniResponsesModel(client, modelId, builtin),
+      modelId,
+    };
   }
 }
 
+export type ModelProviderBinding = {
+  provider: ResolvedModelProvider;
+  client: OpenAI;
+  model: Model;
+  /** The id sent on the provider wire (the upstream id for a registry model). */
+  modelId: string;
+};
+
 function settingsForRunScopedModelResolution(settings: Settings, modelName: string): Settings {
   if (modelName !== settings.openaiModel) {
     return settings;

package/src/operational-instructions.ts

@@ -156,7 +156,7 @@ Skills are reusable instructions supplied dynamically for the current session. W
 
 # Integration setup
 
-Use available integration tools directly. If the task needs an integration you cannot access, discover it with \`capability_catalog_search\` before declaring a setup blocker. For a suitable match with \`setup.nextAction\`, call \`capability_authorization_request\` with the returned capability ID and a brief task-specific rationale to show its Connect card in chat. Requesting the card does not need integration-management permission; the authenticated human must authorize setup. A card is for an integration required by the authorized design, including established or delegated choices. Resolve out-of-scope architecture choices before requesting setup. After setup, rediscover the tools and continue the task, verifying the access it needs. If access remains blocked, explain the specific blocker from the returned facts. If either setup tool is unavailable, report the missing setup path.
+Use available integration tools directly. If access is missing, search \`capability_catalog_search\` first. For a suitable match with \`setup.nextAction\`, call \`capability_authorization_request\` with its ID and a task-specific rationale. If no match exists and the task needs a remote MCP whose exact HTTPS URL the user supplied or reliable documentation establishes, call \`custom_mcp_setup_request\` with its name, URL, and rationale. Never invent URLs or request credentials in chat. Showing either card does not need integration-management permission and grants no access; the authenticated human must authorize setup. A card is for an integration required by the authorized design, including established or delegated choices. Resolve out-of-scope architecture choices before requesting setup. After setup, rediscover tools and verify access. If blocked or a setup tool is unavailable, explain the specific gap.
 
 # Session coordination