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

package/dist/server/function.js

@@ -0,0 +1,337 @@
+/**
+ * Function mode for the Runner SDK.
+ *
+ * Function mode runs a tool CLI-style: the process boots, runs a single named
+ * tool from the registry, reports the result to the OE, and exits. It is the
+ * per-call counterpart to the long-running tool server (mode `tool`).
+ *
+ * Mirrors Python's `agent_engine_runner_shared/server/function.py`.
+ *
+ * How the invocation arrives: fctr seeds `RunRequest.metadata` into the guest
+ * metadata directory before the workload starts. The OE sets one key,
+ * `request`, to a JSON `ToolFunctionRequest` envelope carrying both the
+ * `ToolPodExecuteRequest` and the tool-call `step` number (required by
+ * `ToolResultRequest`, owned by OE dispatch). The result is POSTed to
+ * `{oe_url}/tool/result`, the same endpoint the AER already uses.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { z } from "zod";
+import { getLogger } from "../logger.js";
+import { ownerDelivered } from "../owner_callback.js";
+import { getCurrentExecutionMetadata, runWithCustomerOrigin, runWithExecutionContext, } from "../context.js";
+import { ToolPodExecuteRequestSchema, } from "../models.js";
+import { populateLlmRegistryFromEntrypoint } from "../hooks.js";
+import { getRequestTimeout, logToolRequest, toolRedactFields, } from "../utils.js";
+import { fetchPlatform, getFetchOptionsWithTLS } from "../tls_client.js";
+import { executeErrorResponse, requestCredentialValues, } from "../tool_api_error.js";
+import { getCurrentTraceContext } from "../tracing/setup.js";
+import { discardResponseBody, retryAfterWaitMs } from "./http_retry.js";
+import { resolveOeUrl } from "./oe_url.js";
+import { resolveOwnerUrl } from "./owner_url.js";
+const logger = getLogger("agent_engine_runner_shared.server.function");
+// Guest metadata directory, mirroring fctr's util.MetadataDir. fctr
+// materializes RunRequest.metadata into <dir>/<key> files before the
+// workload starts. A fixed convention: the platform does not announce it.
+const METADATA_DIR = "/run/meta";
+const REQUEST_KEY = "request";
+const TOOL_RESULT_PATH = "/tool/result";
+const MAX_POST_ATTEMPTS = 3;
+const POST_BASE_DELAY_MS = 100;
+/** The function-mode invocation envelope delivered at /run/meta/request. */
+export const ToolFunctionRequestSchema = z.object({
+    request: ToolPodExecuteRequestSchema,
+    step: z.number().int(),
+});
+function readMetadata(metadataDir, key) {
+    const filePath = path.join(metadataDir, key);
+    let value;
+    try {
+        value = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            throw new Error(`function mode requires metadata key '${key}' at ${filePath}`, { cause: e });
+        }
+        throw e;
+    }
+    if (!value.trim()) {
+        throw new Error(`function mode metadata key '${key}' at ${filePath} is empty`);
+    }
+    return value;
+}
+function readFunctionRequest(metadataDir) {
+    const raw = readMetadata(metadataDir, REQUEST_KEY);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`metadata key '${REQUEST_KEY}' is not a valid ToolFunctionRequest: ${e.message}`, { cause: e });
+    }
+    const result = ToolFunctionRequestSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`metadata key '${REQUEST_KEY}' is not a valid ToolFunctionRequest: ${result.error.message}`);
+    }
+    return result.data;
+}
+function buildResultRequest(request, response, step, durationMs) {
+    const { traceId, spanId } = getCurrentTraceContext();
+    return {
+        execution_id: request.execution_id,
+        step_number: step,
+        tool_name: request.tool_name,
+        status: response.status,
+        result: response.result,
+        error: response.error,
+        duration_ms: durationMs,
+        pod_name: response.pod_name,
+        kind: response.kind,
+        metadata: response.metadata ?? {},
+        trace_id: traceId ?? undefined,
+        span_id: spanId ?? undefined,
+        tool_api_error: response.tool_api_error,
+    };
+}
+/**
+ * Encode the result to a JSON-safe object for the /tool/result POST.
+ *
+ * A tool may return a value the JSON encoder cannot handle (e.g. a circular
+ * reference). Downgrade any encode failure to an error report so the OE still
+ * receives a terminal signal. Mirrors Python's _result_payload.
+ */
+export function buildResultPayload(result, executionId) {
+    try {
+        JSON.stringify(result);
+        return result;
+    }
+    catch (e) {
+        logger.error(`function mode: result for execution_id=${executionId} is not JSON-serializable: ${e.message}`);
+        return {
+            execution_id: result.execution_id,
+            step_number: result.step_number,
+            tool_name: result.tool_name,
+            status: "error",
+            result: undefined,
+            duration_ms: result.duration_ms,
+            pod_name: result.pod_name,
+            kind: result.kind,
+            metadata: {},
+            error: `tool result is not JSON-serializable: ${e.message}`,
+        };
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * POST body to url with bounded exponential backoff.
+ *
+ * Retries on transient transport errors and 5xx responses. Does not retry on
+ * 4xx. Re-throws the final error on exhaustion. Mirrors Python's
+ * post_json_with_retries and the shared postWithRetries server helper.
+ *
+ * `ownerUrl` — when given (already validated against `url` and path-appended by
+ * the caller), a single owner pre-attempt runs *before* the service loop and
+ * does not consume the service retry budget (so the trusted `url` always gets
+ * its full `maxAttempts`; total tries are `maxAttempts + 1`). The owner is
+ * best-effort: any failure — a transport error OR any non-2xx response (4xx or
+ * 5xx) — marks the replica unusable, is logged, and falls through to the
+ * service loop. The owner is never retried and an owner response never throws.
+ * When the trusted `url` returns 503 with a delta-seconds `Retry-After`, that
+ * attempt waits the capped hint instead of the exponential backoff.
+ */
+async function postWithRetries(url, body, ownerUrl, onOwnerFailure, maxAttempts = MAX_POST_ATTEMPTS, baseDelayMs = POST_BASE_DELAY_MS) {
+    const timeoutMs = getRequestTimeout() * 1000;
+    const serialized = JSON.stringify(body);
+    // Owner pre-attempt per the shared owner-callback policy (owner_callback.ts):
+    // a single best-effort POST that does not consume the service retry budget.
+    if (ownerUrl != null) {
+        if (await ownerDelivered(ownerUrl, () => ({
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: serialized,
+            signal: AbortSignal.timeout(timeoutMs),
+            ...getFetchOptionsWithTLS(ownerUrl),
+        }), (msg) => logger.warn(`function mode: /tool/result ${msg} URL ${url}`))) {
+            return;
+        }
+        onOwnerFailure?.();
+    }
+    const tlsOptions = getFetchOptionsWithTLS(url);
+    let lastError = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        let retryWaitMs = null;
+        let response;
+        try {
+            response = await fetchPlatform(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: serialized,
+                signal: AbortSignal.timeout(timeoutMs),
+                ...tlsOptions,
+            });
+        }
+        catch (e) {
+            lastError = e;
+        }
+        if (response) {
+            const ok = response.ok;
+            const status = response.status;
+            const retryAfter = response.headers?.get?.("Retry-After") ?? null;
+            await discardResponseBody(response);
+            if (ok)
+                return;
+            if (status < 500) {
+                throw new Error(`HTTP ${status} from ${url}`);
+            }
+            lastError = new Error(`HTTP ${status} from ${url}`);
+            if (status === 503) {
+                retryWaitMs = retryAfterWaitMs(retryAfter);
+            }
+        }
+        if (attempt < maxAttempts - 1) {
+            await sleep(retryWaitMs ?? baseDelayMs * 2 ** attempt);
+        }
+    }
+    throw (lastError ??
+        new Error(`postWithRetries exhausted ${maxAttempts} attempts but recorded no error`));
+}
+/**
+ * Runs one metadata-delivered tool call and exits. Not a server.
+ *
+ * Reads the ToolFunctionRequest envelope from the guest metadata directory,
+ * invokes the named tool from the registry, reports the ToolResultRequest
+ * to {oe_url}/tool/result, and returns. Mirrors Python's ToolFunctionRunner.
+ *
+ * `metadataDir` is injectable for tests.
+ */
+export class ToolFunctionRunner {
+    runtime;
+    metadataDir;
+    constructor(runtime, { metadataDir = METADATA_DIR } = {}) {
+        this.runtime = runtime;
+        this.metadataDir = metadataDir;
+    }
+    /**
+     * Run one tool from the metadata-delivered request and report the result.
+     *
+     * Re-raises if the result POST cannot be delivered after retries so fctr
+     * records the execution as failed.
+     */
+    async run() {
+        const functionRequest = readFunctionRequest(this.metadataDir);
+        const { request, step } = functionRequest;
+        // Pin the callback base to the runner's own configured OE (deploy-time
+        // OE_URL) before it is used as the callback base or the owner-URL trust
+        // anchor. The request field is only honoured when no OE_URL is stamped
+        // (local dev / tests). Resolving once here means the owner URL is validated
+        // against a trusted anchor, not the raw request value.
+        const oeUrl = resolveOeUrl(request.oe_url ?? "").replace(/\/+$/, "");
+        if (!oeUrl) {
+            throw new Error("function mode requires oe_url on the request to report the result");
+        }
+        // Prefer the replica-specific owner OE, validated against the trusted
+        // resolved oeUrl above. A forged owner URL validates to null and is ignored.
+        const ownerUrl = resolveOwnerUrl(request.oe_owner_url, oeUrl);
+        const ownerUrlFailure = { failed: false };
+        // Install before ready()/registry prep and keep through result delivery so
+        // startup and callback failures still emit platform_trace_id.
+        await runWithExecutionContext({
+            executionId: request.execution_id,
+            traceId: request.platform_trace_id,
+            wrapper: null,
+            oeUrl,
+            oeOwnerUrl: ownerUrl,
+            ownerUrlFailure,
+            userId: request.user_id,
+            sessionId: request.session_id,
+            authorization: request.authorization,
+            customHeaders: request.custom_headers,
+            payload: request.payload,
+        }, async () => {
+            await this.runtime.graphBuilder?.ready?.();
+            // Populate the named-LLM registry so a tool calling an LLM works,
+            // same as ToolServer.onStartup(). Not required if no LLMs are called,
+            // but matches the server-mode startup contract.
+            this._prepare();
+            logger.info(`function mode: invoking tool=${JSON.stringify(request.tool_name)} execution_id=${request.execution_id} step=${step}`);
+            const started = performance.now();
+            const response = await this._invokeToolFn(request, ownerUrlFailure);
+            const durationMs = performance.now() - started;
+            const payload = buildResultPayload(buildResultRequest(request, response, step, durationMs), request.execution_id);
+            try {
+                await postWithRetries(`${oeUrl}${TOOL_RESULT_PATH}`, payload, ownerUrl && !ownerUrlFailure.failed
+                    ? `${ownerUrl}${TOOL_RESULT_PATH}`
+                    : null, () => {
+                    ownerUrlFailure.failed = true;
+                });
+            }
+            catch (e) {
+                logger.error(`function mode: failed to deliver result for execution_id=${request.execution_id}: ${e.message}`);
+                throw e;
+            }
+            logger.info(`function mode: reported ${payload["status"]} result for execution_id=${request.execution_id} step=${step}`);
+        });
+    }
+    _prepare() {
+        populateLlmRegistryFromEntrypoint(this.runtime.graphBuilder, logger, {
+            entrypointFailed: "Failed to run entrypoint for LLM registration; LLM calls from this tool will fail",
+            noLlmRegistered: "Entrypoint ran but did not call app.llm(); LLM calls from this tool will fail",
+        });
+    }
+    async _invokeToolFn(request, ownerUrlFailure) {
+        const podName = os.hostname();
+        logToolRequest(request.tool_name ?? "(empty)", request.arguments, 0, "TOOL_FUNCTION", toolRedactFields(this.runtime.toolDefinitions, request.tool_name));
+        if (!request.tool_name) {
+            return {
+                status: "error",
+                error: "Tool name cannot be empty",
+                pod_name: podName,
+                metadata: {},
+            };
+        }
+        const func = this.runtime.tools[request.tool_name];
+        if (!func) {
+            return {
+                status: "error",
+                error: `Unknown tool: ${request.tool_name}`,
+                pod_name: podName,
+                metadata: {},
+            };
+        }
+        // Pin the callback base to the trusted resolved OE before it anchors the
+        // execution context and the owner-URL validation (see run()).
+        const oeUrl = resolveOeUrl(request.oe_url ?? "");
+        return runWithExecutionContext({
+            executionId: request.execution_id,
+            traceId: request.platform_trace_id,
+            wrapper: null,
+            oeUrl,
+            // Emit() from the tool prefers this owner replica, validated against
+            // the trusted resolved oeUrl above.
+            oeOwnerUrl: resolveOwnerUrl(request.oe_owner_url, oeUrl),
+            ownerUrlFailure,
+            userId: request.user_id,
+            sessionId: request.session_id,
+            authorization: request.authorization,
+            customHeaders: request.custom_headers,
+            payload: request.payload,
+        }, async () => {
+            try {
+                const maybePromise = runWithCustomerOrigin(() => func(request.arguments));
+                const result = maybePromise instanceof Promise ? await maybePromise : maybePromise;
+                const metadata = getCurrentExecutionMetadata();
+                return {
+                    status: "success",
+                    result,
+                    pod_name: podName,
+                    kind: metadata["memory"] ? "memory" : undefined,
+                    metadata,
+                };
+            }
+            catch (e) {
+                return executeErrorResponse(e, this.runtime.toolDefinitions[request.tool_name], podName, getCurrentExecutionMetadata(), requestCredentialValues());
+            }
+        });
+    }
+}

package/dist/server/http_retry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared retry-policy and bounded POST helpers for OE transports.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.http_retry`. The AER chunk/callback
+ * path (`server/aer.ts`), function mode (`server/function.ts`) and the tool
+ * result settlement loop (`secure_wrapper.ts`) share policy here so their
+ * cooperative back-pressure behaviour stays identical.
+ */
+export declare function waitForRetry(ms: number, signal: AbortSignal): Promise<boolean>;
+export declare class RetryablePostError extends Error {
+}
+export declare const RETRY_AFTER_MAX_WAIT_MS = 10000;
+/** Release an unread fetch body without changing callback delivery semantics. */
+export declare function discardResponseBody(response: Response): Promise<void>;
+/**
+ * Parse a delta-seconds `Retry-After` header; ignore the HTTP-date form.
+ *
+ * Returns the non-negative integer seconds, or `null` when the header is
+ * absent or not in delta-seconds form (an HTTP-date, or garbage). Callers fall
+ * back to their normal backoff when this returns `null`.
+ */
+export declare function parseRetryAfterSeconds(headerValue: string | null | undefined): number | null;
+/**
+ * The wait (in ms) an honored delta-seconds `Retry-After` implies, capped at
+ * {@link RETRY_AFTER_MAX_WAIT_MS}, or `null` when the header is not honorable.
+ */
+export declare function retryAfterWaitMs(headerValue: string | null | undefined): number | null;
+/**
+ * POST to OE with one optional owner attempt and bounded service retries.
+ *
+ * Transport failures and 5xx responses are retried; 4xx responses fail
+ * immediately. An owner URL gets one best-effort pre-attempt without consuming
+ * the service retry budget. A 503 `Retry-After` delta overrides the normal
+ * exponential delay up to the configured cap.
+ */
+export declare function postWithRetries(url: string, body: unknown, ownerUrl?: string | null, onOwnerFailure?: (() => void) | null, cancellationSignal?: AbortSignal, maxAttempts?: number, baseDelayMs?: number, shouldAttempt?: () => boolean): Promise<void>;
+//# sourceMappingURL=http_retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http_retry.d.ts","sourceRoot":"","sources":["../../src/server/http_retry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAKhD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,iFAAiF;AACjF,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,MAAM,GAAG,IAAI,CAOf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EACxB,cAAc,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,EACpC,kBAAkB,CAAC,EAAE,WAAW,EAChC,WAAW,SAAwB,EACnC,WAAW,SAA6B,EACxC,aAAa,CAAC,EAAE,MAAM,OAAO,GAC5B,OAAO,CAAC,IAAI,CAAC,CA6Df"}

package/dist/server/http_retry.js

@@ -0,0 +1,157 @@
+/**
+ * Shared retry-policy and bounded POST helpers for OE transports.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.http_retry`. The AER chunk/callback
+ * path (`server/aer.ts`), function mode (`server/function.ts`) and the tool
+ * result settlement loop (`secure_wrapper.ts`) share policy here so their
+ * cooperative back-pressure behaviour stays identical.
+ */
+import { getLogger } from "../logger.js";
+import { ownerDelivered as ownerPreAttemptDelivered } from "../owner_callback.js";
+import { fetchPlatform, getFetchOptionsWithTLS } from "../tls_client.js";
+import { getRequestTimeout } from "../utils.js";
+const logger = getLogger("agent_engine_runner_shared.server.http_retry");
+const REQUEST_TIMEOUT_MS = getRequestTimeout() * 1000;
+const DEFAULT_POST_ATTEMPTS = 3;
+const DEFAULT_POST_BASE_DELAY_MS = 100;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function waitForRetry(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve(false);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export class RetryablePostError extends Error {
+}
+// Ceiling on an honored `Retry-After` wait: a cooperative 503 hint is worth a
+// short pause, but the runner must not park a callback for an OE-chosen
+// duration.
+export const RETRY_AFTER_MAX_WAIT_MS = 10_000;
+/** Release an unread fetch body without changing callback delivery semantics. */
+export async function discardResponseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // The response outcome is authoritative; cleanup failure must not replace it.
+    }
+}
+/**
+ * Parse a delta-seconds `Retry-After` header; ignore the HTTP-date form.
+ *
+ * Returns the non-negative integer seconds, or `null` when the header is
+ * absent or not in delta-seconds form (an HTTP-date, or garbage). Callers fall
+ * back to their normal backoff when this returns `null`.
+ */
+export function parseRetryAfterSeconds(headerValue) {
+    if (headerValue == null)
+        return null;
+    const value = headerValue.trim();
+    // Only ASCII digits (matches Python's `str.isdigit()`): no sign, decimal, or
+    // HTTP-date. An empty string fails, so a blank header falls through.
+    if (!/^\d+$/.test(value))
+        return null;
+    return Number(value);
+}
+/**
+ * The wait (in ms) an honored delta-seconds `Retry-After` implies, capped at
+ * {@link RETRY_AFTER_MAX_WAIT_MS}, or `null` when the header is not honorable.
+ */
+export function retryAfterWaitMs(headerValue) {
+    const seconds = parseRetryAfterSeconds(headerValue);
+    if (seconds === null)
+        return null;
+    return Math.min(seconds * 1000, RETRY_AFTER_MAX_WAIT_MS);
+}
+/**
+ * POST to OE with one optional owner attempt and bounded service retries.
+ *
+ * Transport failures and 5xx responses are retried; 4xx responses fail
+ * immediately. An owner URL gets one best-effort pre-attempt without consuming
+ * the service retry budget. A 503 `Retry-After` delta overrides the normal
+ * exponential delay up to the configured cap.
+ */
+export async function postWithRetries(url, body, ownerUrl, onOwnerFailure, cancellationSignal, maxAttempts = DEFAULT_POST_ATTEMPTS, baseDelayMs = DEFAULT_POST_BASE_DELAY_MS, shouldAttempt) {
+    const serialized = JSON.stringify(body);
+    if (shouldAttempt?.() === false)
+        return;
+    if (ownerUrl != null) {
+        if (await ownerDelivered(ownerUrl, url, serialized))
+            return;
+        onOwnerFailure?.();
+    }
+    let lastError = null;
+    const tlsOptions = getFetchOptionsWithTLS(url);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        if (shouldAttempt?.() === false)
+            return;
+        let retryWaitMs = null;
+        let response;
+        try {
+            const requestSignal = cancellationSignal
+                ? AbortSignal.any([
+                    cancellationSignal,
+                    AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                ])
+                : AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+            response = await fetchPlatform(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: serialized,
+                signal: requestSignal,
+                ...tlsOptions,
+            });
+        }
+        catch (error) {
+            if (cancellationSignal?.aborted)
+                throw error;
+            lastError = new RetryablePostError(error instanceof Error ? error.message : String(error));
+        }
+        if (response) {
+            const ok = response.ok;
+            const status = response.status;
+            const retryAfter = response.headers?.get?.("Retry-After") ?? null;
+            await discardResponseBody(response);
+            if (ok)
+                return;
+            if (status < 500)
+                throw new Error(`HTTP ${status} from ${url}`);
+            lastError = new RetryablePostError(`HTTP ${status} from ${url}`);
+            if (status === 503)
+                retryWaitMs = retryAfterWaitMs(retryAfter);
+        }
+        if (attempt < maxAttempts - 1) {
+            const delayMs = retryWaitMs ?? baseDelayMs * 2 ** attempt;
+            if (cancellationSignal) {
+                if (!(await waitForRetry(delayMs, cancellationSignal))) {
+                    throw cancellationSignal.reason;
+                }
+            }
+            else {
+                await sleep(delayMs);
+            }
+        }
+    }
+    throw (lastError ??
+        new Error(`postWithRetries exhausted ${maxAttempts} attempts but recorded no error`));
+}
+async function ownerDelivered(ownerUrl, serviceUrl, serialized) {
+    return ownerPreAttemptDelivered(ownerUrl, () => ({
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: serialized,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        ...getFetchOptionsWithTLS(ownerUrl),
+    }), (message) => logger.warn(`${message} URL ${serviceUrl}`));
+}

package/dist/server/index.d.ts

@@ -0,0 +1,7 @@
+export * as chunkTypes from "./chunk_types.js";
+export * from "./base.js";
+export { AERServer } from "./aer.js";
+export { ToolServer, LLMRegistryLoadError } from "./tool.js";
+export { ToolFunctionRunner, ToolFunctionRequestSchema, buildResultPayload, type ToolFunctionRequest, } from "./function.js";
+export type { AERQueryPlugin } from "./query.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,5 @@
+export * as chunkTypes from "./chunk_types.js";
+export * from "./base.js";
+export { AERServer } from "./aer.js";
+export { ToolServer, LLMRegistryLoadError } from "./tool.js";
+export { ToolFunctionRunner, ToolFunctionRequestSchema, buildResultPayload, } from "./function.js";

package/dist/server/metadata.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Read request-scoped secrets from the fctr metadata directory.
+ *
+ * In RPC mode the OE delivers per-tool secrets via `SetMetadata` before each
+ * tool call and clears them after (when restriction is enabled). fctr
+ * materializes the keyset as files at `/run/meta/<KEY>`. This module reads
+ * those files so the tool server can inject them into `process.env` for the
+ * duration of the call — or permanently when restriction is disabled.
+ *
+ * Mirrors Python's `agent_engine_runner_shared.server.metadata`.
+ */
+/**
+ * Read all key-value pairs from the metadata directory.
+ *
+ * Returns a record mapping filename (the secret name) to file content (the
+ * secret value). Skips files that cannot be read and logs a warning. Returns
+ * an empty record when the directory does not exist.
+ */
+export declare function readMetadataSecrets(metadataDir?: string): Record<string, string>;
+/**
+ * Overwrite `process.env` from `/run/meta`; no restore or prune.
+ */
+export declare function mergeMetadataEnv(metadataDir?: string): void;
+/**
+ * Run `fn` with metadata secrets merged into `process.env`, restoring the
+ * environment afterwards (even on throw).
+ *
+ * Mirrors Python's `applied_metadata_env` context manager for non-streaming
+ * call paths.
+ *
+ * @throws if this region overlaps a concurrent secret-bearing region; see
+ * {@link applyMetadataEnv} for the fail-closed rule and the clean-vs-tainted
+ * restore semantics.
+ */
+export declare function withMetadataEnv<T>(fn: () => Promise<T>, metadataDir?: string): Promise<T>;
+/**
+ * Wrap an async generator so metadata secrets are present in `process.env`
+ * for the lifetime of the iteration, restoring the environment when iteration
+ * completes, throws, or is closed early.
+ *
+ * Mirrors Python's `applied_metadata_env` context manager for streaming call
+ * paths.
+ *
+ * @throws if this region overlaps a concurrent secret-bearing region — note a
+ * stream holds its region open for the whole iteration; see
+ * {@link applyMetadataEnv} for the fail-closed rule and the clean-vs-tainted
+ * restore semantics.
+ */
+export declare function withMetadataEnvGen<T>(genFactory: () => AsyncGenerator<T>, metadataDir?: string): AsyncGenerator<T>;
+//# sourceMappingURL=metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/server/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwBH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,GAAE,MAAqB,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBxB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,GAAE,MAAqB,GAAG,IAAI,CAQzE;AAwFD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,WAAW,GAAE,MAAqB,GACjC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAuB,kBAAkB,CAAC,CAAC,EACzC,UAAU,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,EACnC,WAAW,GAAE,MAAqB,GACjC,cAAc,CAAC,CAAC,CAAC,CAOnB"}