@jini-ai/daemon 0.6.12 → 0.6.15-rc.2

package/dist/http/tool-execution-routes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module tool-execution-routes
+ *
+ * `POST /internal/tool-executions` and `GET /internal/tool-catalog` — the server end of
+ * `createRemoteToolExecutor`. A host whose agent runtime runs in another local process mounts these
+ * over its own gated `ToolExecutor`, so that process can run tools without loading them. The wire
+ * protocol and the at-most-once rules are documented on `remote-tool-executor.ts`.
+ *
+ * Trust boundary, checked before any body byte is parsed:
+ * - a dedicated per-boot secret read from `tokenEnvVar`, compared in constant time; unset → 503 (the
+ *   route fails closed, there is no "open" mode), wrong or missing → 401;
+ * - the TCP peer (`req.socket.remoteAddress`, never a forwarded header) must be loopback → else 403.
+ * Only then does the route's own `express.json({ limit: maxBodyBytes })` run, so an unauthenticated
+ * caller cannot make the host buffer a large body, and an app-level parser with a smaller limit
+ * mounted after this route never sees these requests. Over the limit → 413.
+ *
+ * The executor below is the host's full gate (authorize, confirm, audit); this route adds no
+ * authority of its own and the serialized principal is passed through untouched for it to judge.
+ *
+ * Cancellation: the 200 headers are flushed before the executor runs, and the executor's signal
+ * aborts when the response closes before it finished (the caller destroyed its request). A request
+ * body that never completed never reaches the executor. Listeners are detached once the call
+ * settles, so a long-lived keep-alive socket never accumulates them.
+ */
+import { type ErrorRequestHandler, type RequestHandler } from 'express';
+import type { ToolDescriptor } from '@jini-ai/core';
+import type { ToolExecutor } from '../tool-executor.js';
+import { TOOL_EXECUTIONS_ROUTE_PATH } from '../remote-tool-executor.js';
+export { TOOL_EXECUTIONS_ROUTE_PATH };
+export declare const TOOL_CATALOG_ROUTE_PATH = "/internal/tool-catalog";
+export declare const DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR = "JINI_TOOL_EXEC_TOKEN";
+/** Tool inputs carry whole documents; 16 MiB matches the largest the agent side sends. */
+export declare const DEFAULT_TOOL_EXEC_MAX_BODY_BYTES: number;
+/** Anything routes can be mounted on: an Express app or a `Router`. */
+export interface ToolExecutionRouteTarget {
+    post(path: string, ...handlers: Array<RequestHandler | ErrorRequestHandler>): unknown;
+    get(path: string, ...handlers: RequestHandler[]): unknown;
+}
+/** Runs one call inside host context (e.g. an AsyncLocalStorage scope) built from the wire `context`. */
+export type RunWithToolContext = <T>(required: {
+    readonly context: unknown;
+    readonly fn: () => Promise<T>;
+}, optional?: Record<string, never>) => Promise<T>;
+export interface ToolExecutionRoutesRequired {
+    readonly app: ToolExecutionRouteTarget;
+    readonly executor: ToolExecutor;
+    /** Built fresh on every catalog request; the route never caches it. */
+    readonly listToolsFor: (required: {
+        readonly principalId: string;
+    }, optional?: Record<string, never>) => readonly ToolDescriptor[] | Promise<readonly ToolDescriptor[]>;
+}
+export interface ToolExecutionRoutesOptional {
+    /** Env var holding the shared secret. Defaults to {@link DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR}. */
+    readonly tokenEnvVar?: string;
+    /** Defaults to `process.env`; injectable so tests never mutate the real env. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Defaults to {@link DEFAULT_TOOL_EXEC_MAX_BODY_BYTES}. */
+    readonly maxBodyBytes?: number;
+    readonly runWithContext?: RunWithToolContext;
+}
+/** The token + loopback gate; mounted before any body parser. Exported for hosts that need it on another path. */
+export declare function requireToolExecutionCaller(_required: Record<string, never>, { tokenEnvVar, env }?: Pick<ToolExecutionRoutesOptional, 'tokenEnvVar' | 'env'>): RequestHandler;
+/**
+ * Mounts both routes on `app` (an Express app or a `Router`). Mount it BEFORE any app-level
+ * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
+ * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
+ */
+export declare function registerToolExecutionRoutes({ app, executor, listToolsFor }: ToolExecutionRoutesRequired, { tokenEnvVar, env, maxBodyBytes, runWithContext }?: ToolExecutionRoutesOptional): void;
+//# sourceMappingURL=tool-execution-routes.d.ts.map

package/dist/http/tool-execution-routes.js

@@ -0,0 +1,181 @@
+/**
+ * @module tool-execution-routes
+ *
+ * `POST /internal/tool-executions` and `GET /internal/tool-catalog` — the server end of
+ * `createRemoteToolExecutor`. A host whose agent runtime runs in another local process mounts these
+ * over its own gated `ToolExecutor`, so that process can run tools without loading them. The wire
+ * protocol and the at-most-once rules are documented on `remote-tool-executor.ts`.
+ *
+ * Trust boundary, checked before any body byte is parsed:
+ * - a dedicated per-boot secret read from `tokenEnvVar`, compared in constant time; unset → 503 (the
+ *   route fails closed, there is no "open" mode), wrong or missing → 401;
+ * - the TCP peer (`req.socket.remoteAddress`, never a forwarded header) must be loopback → else 403.
+ * Only then does the route's own `express.json({ limit: maxBodyBytes })` run, so an unauthenticated
+ * caller cannot make the host buffer a large body, and an app-level parser with a smaller limit
+ * mounted after this route never sees these requests. Over the limit → 413.
+ *
+ * The executor below is the host's full gate (authorize, confirm, audit); this route adds no
+ * authority of its own and the serialized principal is passed through untouched for it to judge.
+ *
+ * Cancellation: the 200 headers are flushed before the executor runs, and the executor's signal
+ * aborts when the response closes before it finished (the caller destroyed its request). A request
+ * body that never completed never reaches the executor. Listeners are detached once the call
+ * settles, so a long-lived keep-alive socket never accumulates them.
+ */
+import express, {} from 'express';
+import { createApiError } from '@jini-ai/protocol';
+import { bearerTokenFromHeader, isLoopbackPeerAddress, sendApiError, statusForError, timingSafeTokenMatch } from '@jini-ai/http-kit';
+import { TOOL_EXECUTIONS_ROUTE_PATH } from '../remote-tool-executor.js';
+export { TOOL_EXECUTIONS_ROUTE_PATH };
+export const TOOL_CATALOG_ROUTE_PATH = '/internal/tool-catalog';
+export const DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR = 'JINI_TOOL_EXEC_TOKEN';
+/** Tool inputs carry whole documents; 16 MiB matches the largest the agent side sends. */
+export const DEFAULT_TOOL_EXEC_MAX_BODY_BYTES = 16 * 1024 * 1024;
+function refusalFor({ req, expected, tokenEnvVar }) {
+    if (!expected)
+        return createApiError({ code: 'NOT_CONFIGURED', message: `${tokenEnvVar} is not set — remote tool execution is disabled` });
+    if (!isLoopbackPeerAddress({ address: req.socket?.remoteAddress })) {
+        return createApiError({ code: 'FORBIDDEN', message: 'remote tool execution accepts loopback callers only' });
+    }
+    const presented = bearerTokenFromHeader({ header: req.get('authorization') });
+    if (presented === null || !timingSafeTokenMatch({ presented, expected })) {
+        return createApiError({ code: 'UNAUTHORIZED', message: `Authorization: Bearer <${tokenEnvVar}> required` });
+    }
+    return null;
+}
+/** The token + loopback gate; mounted before any body parser. Exported for hosts that need it on another path. */
+export function requireToolExecutionCaller(_required, { tokenEnvVar = DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR, env = process.env } = {}) {
+    return (req, res, next) => {
+        const refusal = refusalFor({ req, expected: env[tokenEnvVar], tokenEnvVar });
+        if (refusal === null) {
+            next();
+            return;
+        }
+        sendApiError({ res, status: statusForError({ error: refusal }), error: refusal });
+    };
+}
+/** Maps a body-parser failure (too large, malformed, aborted mid-body) to a refusal; the executor never runs. */
+const bodyParserFailure = (error, _req, res, next) => {
+    if (res.headersSent) {
+        next(error);
+        return;
+    }
+    const tooLarge = error.status === 413;
+    const apiError = createApiError({ code: tooLarge ? 'PAYLOAD_TOO_LARGE' : 'BAD_REQUEST', message: tooLarge ? 'request body too large' : 'request body must be valid JSON' });
+    sendApiError({ res, status: tooLarge ? 413 : 400, error: apiError });
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasStringId(value) {
+    return isRecord(value) && typeof value.id === 'string' && value.id.length > 0;
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** Validates the wire body; `null` → 400. The principal object is kept whole for the host's gate. */
+function parseExecutionRequest(body) {
+    if (!isRecord(body) || !nonEmptyString(body.executionId) || !nonEmptyString(body.toolId))
+        return null;
+    if (!hasStringId(body.principal) || !hasStringId(body.run))
+        return null;
+    const run = body.run;
+    return {
+        executionId: body.executionId,
+        principal: body.principal,
+        run: { id: run.id },
+        toolId: body.toolId,
+        input: body.input,
+        ...(body.context === undefined ? {} : { context: body.context }),
+    };
+}
+function wireError(error) {
+    if (!(error instanceof Error))
+        return { name: 'Error', message: String(error) };
+    const code = error.code;
+    return { name: error.name, message: error.message, ...(typeof code === 'string' ? { code } : {}) };
+}
+/**
+ * Streams one execution as NDJSON. Headers go out first; surfaces are written as they are emitted
+ * and are dropped once the call settled; exactly one terminal line follows.
+ */
+async function streamExecution({ req, res, call, executor }, { runWithContext }) {
+    const controller = new AbortController();
+    // `res` 'close' (not `req` 'close', which fires as soon as a completed body was read) means the
+    // caller went away; after a normal end `writableFinished` is already true and nothing aborts.
+    const onClose = () => { if (!res.writableFinished)
+        controller.abort(); };
+    const onRequestError = () => controller.abort();
+    res.on('close', onClose);
+    req.on('error', onRequestError);
+    res.status(200).setHeader('content-type', 'application/x-ndjson');
+    res.setHeader('cache-control', 'no-store');
+    res.flushHeaders();
+    let settled = false;
+    const writeLine = (line) => { if (!res.writableEnded)
+        res.write(`${JSON.stringify(line)}\n`); };
+    const emitSurface = async (emission) => { if (!settled)
+        writeLine({ type: 'surface', emission }); };
+    const run = () => executor.execute({ principal: call.principal, run: call.run, toolId: call.toolId, input: call.input }, { signal: controller.signal, emitSurface });
+    try {
+        if (!req.complete || controller.signal.aborted)
+            return;
+        const result = runWithContext ? await runWithContext({ context: call.context, fn: run }) : await run();
+        writeLine({ type: 'result', result });
+    }
+    catch (error) {
+        writeLine({ type: 'throw', error: wireError(error) });
+    }
+    finally {
+        settled = true;
+        res.off('close', onClose);
+        req.off('error', onRequestError);
+        res.end();
+    }
+}
+function executionHandler({ executor }, optional) {
+    return (req, res) => {
+        const call = parseExecutionRequest(req.body);
+        if (call === null) {
+            const error = createApiError({ code: 'BAD_REQUEST', message: 'body must be { executionId, principal: { id }, run: { id }, toolId, input, context? }' });
+            sendApiError({ res, status: 400, error });
+            return;
+        }
+        void streamExecution({ req, res, call, executor }, optional);
+    };
+}
+/**
+ * Catalog for one principal. Written with `res.end` rather than `res.json` because Express adds a
+ * weak ETag to `json` GET responses, and this answer must never be served from a validator cache:
+ * plugin state and delete policy can change between two runs.
+ */
+function catalogHandler({ listToolsFor }) {
+    return async (req, res) => {
+        const principalId = req.query.principalId;
+        if (!nonEmptyString(principalId)) {
+            sendApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: 'principalId query parameter is required' }) });
+            return;
+        }
+        try {
+            const tools = await listToolsFor({ principalId });
+            res.status(200).setHeader('content-type', 'application/json; charset=utf-8');
+            res.setHeader('cache-control', 'no-store');
+            res.end(JSON.stringify({ tools }));
+        }
+        catch {
+            sendApiError({ res, status: 500, error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }) });
+        }
+    };
+}
+/**
+ * Mounts both routes on `app` (an Express app or a `Router`). Mount it BEFORE any app-level
+ * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
+ * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
+ */
+export function registerToolExecutionRoutes({ app, executor, listToolsFor }, { tokenEnvVar, env, maxBodyBytes = DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, runWithContext } = {}) {
+    const gate = requireToolExecutionCaller({}, { ...(tokenEnvVar === undefined ? {} : { tokenEnvVar }), ...(env === undefined ? {} : { env }) });
+    const parser = express.json({ limit: maxBodyBytes });
+    app.post(TOOL_EXECUTIONS_ROUTE_PATH, gate, parser, executionHandler({ executor }, runWithContext === undefined ? {} : { runWithContext }), bodyParserFailure);
+    app.get(TOOL_CATALOG_ROUTE_PATH, gate, catalogHandler({ listToolsFor }));
+}
+//# sourceMappingURL=tool-execution-routes.js.map

package/dist/http/xai.js

@@ -167,8 +167,17 @@ function resolveStorageAndSearchDeps(deps) {
 function xaiRedirectUri(resolved) {
     return `http://${resolved.callbackHost}:${resolved.callbackPort}${resolved.callbackPath}`;
 }
-/** Stops (best-effort) and clears the in-flight loopback listener, if any. Never throws — the listener self-closes on completion/timeout anyway, matching OD's origin `stopActiveListener`. */
-async function stopListener(listenerRef) {
+/** Tracks only the state's lookup key; `PendingAuthCache` remains the single-use authorization owner.
+ * Keying by the shared listener slot keeps cancellation scoped to one mounted route pack. */
+const pendingOAuthStates = new WeakMap();
+/** Revokes the pending state before stopping and clearing its listener. Listener shutdown is
+ * best-effort — the listener self-closes on completion/timeout anyway, matching OD's origin
+ * `stopActiveListener`. Revocation must precede the await so a late paste-back cannot reconnect. */
+async function stopListener({ listenerRef, pending }, _optional = {}) {
+    const state = pendingOAuthStates.get(listenerRef);
+    pendingOAuthStates.delete(listenerRef);
+    if (state !== undefined)
+        pending.consume({ state });
     const current = listenerRef.current;
     listenerRef.current = null;
     if (!current)
@@ -331,6 +340,7 @@ export const xaiOauthStartRoute = defineJsonRoute({
                     pending: resolved.pending,
                     redirectUri: xaiRedirectUri(resolved),
                 });
+                pendingOAuthStates.set(resolved.listenerRef, state);
                 const listener = await resolved.startCallbackListener({
                     host: resolved.callbackHost,
                     port: resolved.callbackPort,
@@ -348,7 +358,7 @@ export const xaiOauthStartRoute = defineJsonRoute({
                 });
             }
             catch (error) {
-                await stopListener(resolved.listenerRef);
+                await stopListener(resolved);
                 const correlationId = randomUUID();
                 resolved.onInternalError({ source: 'oauth-start', correlationId, error });
                 return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
@@ -383,7 +393,7 @@ export const xaiOauthCompleteRoute = defineJsonRoute({
             // We won the race against the loopback listener (or it was never going to resolve in the
             // first place); shut it down so the next `oauth/start` has a clean slate — matching OD's
             // origin behavior on a successful manual paste-back.
-            await stopListener(resolved.listenerRef);
+            await stopListener(resolved);
             return ok({ value: { ok: true } });
         }
         catch (error) {
@@ -410,10 +420,10 @@ export const xaiOauthCompleteRoute = defineJsonRoute({
 export const xaiOauthCancelRoute = defineJsonRoute({
     method: 'post', path: '/api/xai/oauth/cancel', parse: () => ok({ value: undefined }), handle: async ({ input: _input, deps }) => {
         const resolved = resolveXaiHttpDeps(deps);
-        // Cancel only stops the in-flight loopback listener; it must never wipe a stored token — a
-        // user clicking Cancel mid-reconnect would otherwise lose their existing grant. Disconnect
-        // (below) is the destructive path. Matches OD's origin `oauth/cancel` handler exactly.
-        await stopListener(resolved.listenerRef);
+        // Cancel revokes the pending state and stops the listener; it must never wipe a stored
+        // token — a user clicking Cancel mid-reconnect would otherwise lose their existing grant. Disconnect
+        // (below) is the destructive path. Preserves OD's origin `oauth/cancel` token-retention behavior.
+        await stopListener(resolved);
         return ok({ value: { ok: true } });
     }
 }, { requireSameOrigin: true });
@@ -449,7 +459,7 @@ export const xaiOauthDisconnectRoute = defineJsonRoute({
     method: 'post', path: '/api/xai/oauth/disconnect', parse: () => ok({ value: undefined }), handle: async ({ input: _input, deps }) => {
         const resolved = resolveXaiHttpDeps(deps);
         try {
-            await stopListener(resolved.listenerRef);
+            await stopListener(resolved);
             await clearStoredOAuthToken({ dataDir: resolved.dataDir, fileName: resolved.tokenFileName });
             return ok({ value: { ok: true } });
         }

package/dist/index.d.ts

@@ -80,9 +80,12 @@
 export * from './event-log.js';
 export * from './close-status.js';
 export * from './run-lifecycle.js';
+export * from './ai-trace-lifecycle.js';
 export * from './tool-executor.js';
 export * from './delegated-tool-bridge.js';
 export * from './remote-tool-bridge.js';
+export * from './remote-tool-executor.js';
+export * from './routing-tool-executor.js';
 export * from './frontend-session-registry.js';
 export * from './frontend-capability-tools.js';
 export * from './agent-executor.js';

package/dist/index.js

@@ -80,9 +80,12 @@
 export * from './event-log.js';
 export * from './close-status.js';
 export * from './run-lifecycle.js';
+export * from './ai-trace-lifecycle.js';
 export * from './tool-executor.js';
 export * from './delegated-tool-bridge.js';
 export * from './remote-tool-bridge.js';
+export * from './remote-tool-executor.js';
+export * from './routing-tool-executor.js';
 export * from './frontend-session-registry.js';
 export * from './frontend-capability-tools.js';
 export * from './agent-executor.js';

package/dist/remote-attachment-lookup.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module remote-attachment-lookup
+ *
+ * Client for `registerAttachmentLookupRoutes`: the two read methods of a daemon-owned
+ * `AttachmentStore`, called from another local process over `node:http`. A store rejection comes
+ * back as the same `AttachmentRejectedError` class (same `reason` and message), so a caller's
+ * `instanceof` check behaves exactly as it would against the in-process store.
+ *
+ * Exported from `@jini-ai/daemon/http` rather than the root entry because it shares that class with
+ * the attachments route pack.
+ */
+import * as http from 'node:http';
+import { type AttachmentLookup } from './http/attachment-lookup-routes.js';
+export interface RemoteAttachmentLookupRequired {
+    /** Origin of the daemon, e.g. `http://127.0.0.1:4100`. */
+    readonly baseUrl: string;
+    /** The daemon's bearer token. */
+    readonly token: string;
+}
+export interface RemoteAttachmentLookupOptional {
+    /** Injectable `node:http.request`. */
+    readonly request?: typeof http.request;
+}
+/**
+ * Creates the remote lookup.
+ * @complexity One loopback round trip per call; O(response bytes).
+ */
+export declare function createRemoteAttachmentLookup({ baseUrl, token }: RemoteAttachmentLookupRequired, { request }?: RemoteAttachmentLookupOptional): AttachmentLookup;
+//# sourceMappingURL=remote-attachment-lookup.d.ts.map

package/dist/remote-attachment-lookup.js

@@ -0,0 +1,71 @@
+/**
+ * @module remote-attachment-lookup
+ *
+ * Client for `registerAttachmentLookupRoutes`: the two read methods of a daemon-owned
+ * `AttachmentStore`, called from another local process over `node:http`. A store rejection comes
+ * back as the same `AttachmentRejectedError` class (same `reason` and message), so a caller's
+ * `instanceof` check behaves exactly as it would against the in-process store.
+ *
+ * Exported from `@jini-ai/daemon/http` rather than the root entry because it shares that class with
+ * the attachments route pack.
+ */
+import * as http from 'node:http';
+import { AttachmentRejectedError } from './http/attachments.js';
+import { ATTACHMENT_LOOKUP_ROUTE_PATH } from './http/attachment-lookup-routes.js';
+function postJson({ url, token, payload }, { request }) {
+    const body = JSON.stringify(payload);
+    return new Promise((resolve, reject) => {
+        const req = request(url, {
+            method: 'POST',
+            agent: false,
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+        }, (res) => {
+            let text = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => { text += chunk; });
+            res.on('end', () => {
+                try {
+                    resolve({ status: res.statusCode ?? 0, body: JSON.parse(text) });
+                }
+                catch {
+                    resolve({ status: res.statusCode ?? 0, body: null });
+                }
+            });
+            res.on('error', reject);
+        });
+        req.on('error', reject);
+        req.end(body);
+    });
+}
+function errorOf(body) {
+    const error = body?.error;
+    return typeof error === 'object' && error !== null ? error : {};
+}
+/** Returns `value` from a 200, rethrows a store rejection as `AttachmentRejectedError`, else a plain error naming the status. */
+function unwrap({ status, body }) {
+    if (status === 200)
+        return body?.value ?? null;
+    const error = errorOf(body);
+    if (error.code === 'ATTACHMENT_REJECTED' && typeof error.details?.reason === 'string') {
+        throw new AttachmentRejectedError({ reason: error.details.reason, message: String(error.message ?? '') });
+    }
+    const code = typeof error.code === 'string' ? ` ${error.code}` : '';
+    throw new Error(`attachment lookup failed: HTTP ${status}${code}`);
+}
+/**
+ * Creates the remote lookup.
+ * @complexity One loopback round trip per call; O(response bytes).
+ */
+export function createRemoteAttachmentLookup({ baseUrl, token }, { request = http.request } = {}) {
+    const url = new URL(ATTACHMENT_LOOKUP_ROUTE_PATH, baseUrl);
+    const call = async (payload) => unwrap(await postJson({ url, token, payload }, { request }));
+    return {
+        resolveForRun: async ({ ref, runId }) => ((await call({ op: 'resolveForRun', ref, runId })) ?? undefined),
+        listPendingForOwner: async ({ ownerId }, optional = {}) => (await call({
+            op: 'listPendingForOwner',
+            ownerId,
+            ...(optional.runId === undefined ? {} : { runId: optional.runId }),
+        })),
+    };
+}
+//# sourceMappingURL=remote-attachment-lookup.js.map

package/dist/remote-tool-executor.d.ts

@@ -0,0 +1,85 @@
+import * as http from 'node:http';
+import { type Principal, type RunRef, type SurfaceEmission } from '@jini-ai/core';
+import type { ToolExecutionResult, ToolExecutor } from './tool-executor.js';
+export type ToolRpcErrorCode = 'TOOL_NOT_DISPATCHED' | 'TOOL_OUTCOME_UNKNOWN';
+/** A remote tool call that failed in transport. `code` says whether the call may have run; see the module doc. */
+export declare class ToolRpcError extends Error {
+    readonly code: ToolRpcErrorCode;
+    constructor({ code, message }: {
+        readonly code: ToolRpcErrorCode;
+        readonly message: string;
+    }, optional?: ErrorOptions);
+}
+/** The POST body `registerToolExecutionRoutes` accepts. */
+export interface ToolExecutionWireRequest {
+    readonly executionId: string;
+    readonly principal: Principal;
+    readonly run: RunRef;
+    readonly toolId: string;
+    readonly input: unknown;
+    /** Opaque host JSON, handed to the far side's `runWithContext`. */
+    readonly context?: unknown;
+}
+/** What a far-side throw carries over the wire. */
+export interface ToolExecutionWireError {
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string;
+}
+/** One NDJSON line of a tool-execution response. */
+export type ToolExecutionWireLine = {
+    readonly type: 'surface';
+    readonly emission: SurfaceEmission;
+} | {
+    readonly type: 'result';
+    readonly result: ToolExecutionResult;
+} | {
+    readonly type: 'throw';
+    readonly error: ToolExecutionWireError;
+};
+export declare const TOOL_EXECUTIONS_ROUTE_PATH = "/internal/tool-executions";
+export interface RemoteToolExecutorRequired {
+    /** Origin of the far server, e.g. `http://127.0.0.1:3000`. */
+    readonly baseUrl: string;
+    /** Bearer secret the far route checks. */
+    readonly token: string;
+}
+export interface RemoteToolExecutorOptional {
+    /**
+     * Injectable request function for the base URL's scheme. Omitted → `node:https.request` for
+     * `https:`, else `node:http.request`. A host whose local CA is not in the process trust store wraps
+     * `https.request` with its `ca`; tests use it to observe or fail the transport.
+     */
+    readonly request?: typeof http.request;
+    /** Builds the opaque per-call `context` the far side receives. Omitted → no `context` field. */
+    readonly contextFor?: (required: {
+        readonly principal: Principal;
+        readonly run: RunRef;
+        readonly toolId: string;
+    }, optional?: Record<string, never>) => unknown;
+}
+/** Parses one NDJSON line; `null` means malformed, which the caller treats as outcome unknown. */
+export declare function parseToolExecutionLine({ text }: {
+    readonly text: string;
+}, _optional?: Record<string, never>): ToolExecutionWireLine | null;
+/**
+ * Turns a far-side throw back into an error a local caller can branch on. `ToolInputError` keeps its
+ * class, because the in-process executor throws it for an unknown tool id and callers test it with
+ * `instanceof`. Anything else becomes a plain `Error` carrying the same name, message and code.
+ */
+export declare function rehydrateToolExecutionError({ error }: {
+    readonly error: ToolExecutionWireError;
+}, _optional?: Record<string, never>): Error;
+/**
+ * Creates the client `ToolExecutor` for a far `registerToolExecutionRoutes` endpoint.
+ *
+ * - `execute` streams one call; a caller `signal` (or `cancel` with the id sent on the wire) destroys
+ *   the request, which the far route turns into its own abort, and settles locally as `cancelled`
+ *   — the same result an in-process executor gives a cancelled call.
+ * - `getAuditRecord` returns `null`: the far side owns the audit trail.
+ * - `resumeConfirmation` throws: confirmations park on, and are answered on, the far side.
+ *
+ * @complexity O(response bytes) per call; `cancel` is an O(1) map lookup.
+ */
+export declare function createRemoteToolExecutor({ baseUrl, token }: RemoteToolExecutorRequired, { request: injectedRequest, contextFor }?: RemoteToolExecutorOptional): ToolExecutor;
+//# sourceMappingURL=remote-tool-executor.d.ts.map