@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/server/tool.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Tool Executor Pod server — executes tool functions in isolated pods.
+ *
+ * Responsibilities:
+ * - Execute registered tool functions
+ * - Invoke LLMs routed from AER via SecureWrappedLLM
+ * - Return results to OE
+ *
+ * Mirrors Python's `ToolServer` in `server/tool.py`.
+ */
+import type { ServerResponse } from "node:http";
+import type { FastifyInstance } from "fastify";
+import { BaseServer, type ITenantRuntime } from "./base.js";
+/**
+ * Max time to wait for a slow SSE client to drain before aborting the stream.
+ * Prevents unbounded buffering and long-lived holds on the credential gate
+ * when a peer never reads.
+ */
+export declare const SSE_DRAIN_TIMEOUT_MS = 30000;
+/**
+ * Pipe SSE `data:` lines to a hijacked Node response with disconnect cancel,
+ * backpressure, and no process-crashing unhandled `error` events.
+ *
+ * Fastify's `reply.hijack()` removes framework lifecycle management; this
+ * helper owns the raw socket for the rest of the stream.
+ *
+ * Disconnect is detected via the *response* `close` event when the peer drops
+ * before `end()` — not via `IncomingMessage` `close`, which also fires after a
+ * normally-consumed POST body and would abort a valid stream.
+ *
+ * `lines` may be an AsyncIterable or a factory that receives the pipe's
+ * AbortSignal so upstream generation (retries/backoff) can stop promptly.
+ *
+ * Force-close paths (peer drop, drain timeout, socket error) call
+ * `res.destroy()` rather than `res.end()`: end only queues FIN behind data
+ * already stuck in the writable buffer, which never drains for a never-reading
+ * peer and leaks the socket/FD indefinitely.
+ */
+export declare function pipeSseLinesToResponse(res: ServerResponse, lines: AsyncIterable<string> | ((signal: AbortSignal) => AsyncIterable<string>), opts?: {
+    drainTimeoutMs?: number;
+    signal?: AbortSignal;
+    onGeneratorSettled?: () => void;
+}): Promise<void>;
+/**
+ * Promise-chain mutex serializing async work within one ToolServer instance.
+ * Mirrors Python's asyncio.Lock on ToolServer._execute_gate.
+ * Exported for tests that build a ToolServer without its constructor.
+ */
+export declare class AsyncMutex {
+    private locked;
+    private acquire;
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Generator form of runExclusive: the lock is held for the lifetime of the
+     * iteration and released when it completes, throws, or is closed early.
+     */
+    runExclusiveGen<T>(genFactory: () => AsyncGenerator<T>): AsyncGenerator<T>;
+}
+/**
+ * Thrown when an LLM lookup fails because the entrypoint registry load failed.
+ *
+ * The named-LLM registry is populated by running the user entrypoint. When that
+ * run throws, the registry is left empty (or holding only import-time
+ * registrations) and every lookup of an LLM the entrypoint would have
+ * registered fails with a bare "not registered" error -- which points the agent
+ * developer at their `app.llm()` calls instead of at the transient cause that
+ * actually broke the load. The real cause is named in the message only; it is
+ * deliberately not attached as `cause`, because the caller-facing response is
+ * rendered by `formatLlmError`, which walks `cause` and would dump a raw
+ * provider `.details`/`.body` from there, bypassing the message redaction.
+ * Mirrors Python's LLMRegistryLoadError.
+ */
+export declare class LLMRegistryLoadError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class ToolServer extends BaseServer {
+    private readonly executeGate;
+    private readonly restrictionDisabled;
+    private readonly llmRegistryLock;
+    private llmRegistryLoaded;
+    private llmRegistryLoadError;
+    constructor(runtime: ITenantRuntime);
+    /**
+     * Run `fn` under restricted or unrestricted secret handling.
+     *
+     * Restricted (default): take `executeGate` and apply/restore metadata env.
+     * Unrestricted: merge metadata without restore and skip the gate.
+     */
+    private withCredentialIsolation;
+    /**
+     * Streaming variant of `withCredentialIsolation` for `/invoke_llm/stream`.
+     */
+    private withCredentialIsolationGen;
+    get modeName(): string;
+    onStartup(): Promise<void>;
+    /**
+     * Populate the registry at startup, retrying failed construction on requests.
+     * The lock ensures subsequent calls reuse successful preparation.
+     */
+    private ensureLlmRegistryLoaded;
+    onShutdown(): Promise<void>;
+    getHealthDetails(): Record<string, unknown>;
+    registerRoutes(app: FastifyInstance): void;
+    private handleGuardrailsCheck;
+    private handleExecute;
+    private doHandleExecute;
+    /**
+     * Resolve a tool name to a callable, falling back to a configured MCP tool.
+     *
+     * Mirrors Python's `ToolServer._resolve_tool()`. AER discovers remote MCP
+     * schemas at startup and forwards `mcp_server`/`mcp_tool` call metadata
+     * when invoking a Tool-Pod-dispatched MCP tool; the direct registry lookup
+     * misses for those names because MCP tools aren't pre-registered on the
+     * Tool Pod side (it skips `tools/list` startup discovery).
+     */
+    private resolveTool;
+    /**
+     * Create a BaseLLM-compatible instance for tool pod execution.
+     *
+     * Retrieves the named LLM from the registry (registered via
+     * `app.llm(llm, { llmId })`) and wraps it through the registered adapter
+     * factory. No SecureWrappedLLM needed — OE approval already happened in AER.
+     */
+    private createLlmForPod;
+    private handleInvokeLlm;
+    private doHandleInvokeLlm;
+    /**
+     * ensureLlmRegistryLoaded() then streamLlmChunks(), both inside the
+     * request's credential isolation window. Registry loading is normally a
+     * no-op after startup; the gate still covers the complete stream.
+     */
+    private loadRegistryThenStreamLlmChunks;
+    private registryLoadedLlmChunks;
+    private streamLlmChunks;
+    private handleInvokeLlmStream;
+    private invokeLlmStreamEvents;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/server/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/server/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAiE/C,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAqB,MAAM,WAAW,CAAC;AAW/E;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,cAAc,EACnB,KAAK,EACD,aAAa,CAAC,MAAM,CAAC,GACrB,CAAC,CAAC,MAAM,EAAE,WAAW,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC,EACpD,IAAI,GAAE;IACJ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;IAMrB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B,GACL,OAAO,CAAC,IAAI,CAAC,CA2Hf;AAqGD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAoC;YAEpC,OAAO;IAUf,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASvD;;;OAGG;IACI,eAAe,CAAC,CAAC,EACtB,UAAU,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,GAClC,cAAc,CAAC,CAAC,CAAC;CAQrB;AA0LD;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,qBAAa,UAAW,SAAQ,UAAU;IAKxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAU;IAE9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoB;IACpD,OAAO,CAAC,iBAAiB,CAAS;IAOlC,OAAO,CAAC,oBAAoB,CAAmC;gBAEnD,OAAO,EAAE,cAAc;IAKnC;;;;;OAKG;YACW,uBAAuB;IAQrC;;OAEG;YACY,0BAA0B;IAazC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAEK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAmChC;;;OAGG;YACW,uBAAuB;IA2B/B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAO3C,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAuH1C,OAAO,CAAC,qBAAqB,CAK3B;IAEF,OAAO,CAAC,aAAa,CAInB;YAEY,eAAe;IAyG7B;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAwCnB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAsCvB,OAAO,CAAC,eAAe,CAKrB;YAEY,iBAAiB;IA2D/B;;;;OAIG;YACY,+BAA+B;YAO/B,uBAAuB;YAQvB,eAAe;YAgFf,qBAAqB;YA0BrB,qBAAqB;CA0DrC"}