@jini-ai/http-kit 0.2.1

package/dist/remote-run-events.d.ts

@@ -0,0 +1,66 @@
+import type { Express, NextFunction, Request, Response } from 'express';
+import type { RemoteToolEventRecorder, RunLifecycle } from '@jini-ai/daemon';
+import { type AdapterContext } from './adapter.js';
+export interface RemoteToolBridgeTokenConfig {
+    /** Env var name for the required shared secret. Defaults to `JINI_REMOTE_TOOL_BRIDGE_TOKEN`. */
+    readonly tokenEnvVar?: string;
+}
+export interface RemoteRunEventInternalErrorContext {
+    readonly source: 'tool-use' | 'tool-result';
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+export interface RemoteRunEventHttpDeps {
+    /** Used to distinguish "unknown run" (404) from other outcomes before recording — same precedent as `delegated-tools.ts`'s `delegatedToolExecuteRoute` — and again afterwards to classify a recorder failure (see {@link toRemoteEventError}). */
+    readonly lifecycle: RunLifecycle;
+    readonly recorder: RemoteToolEventRecorder;
+    readonly tokenConfig?: RemoteToolBridgeTokenConfig;
+    /** Defaults to `process.env`. Threaded through so tests never have to mutate real process env. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: RemoteRunEventInternalErrorContext) => void;
+}
+/**
+ * Gates both remote-run-event routes behind a dedicated shared secret. Unlike
+ * `registerApiBearerAuthMiddleware`, there is no "unset means open" or "disabled" mode: a route
+ * that lets a caller inject events into someone else's run must never silently run unauthenticated
+ * just because a host forgot to configure the token. If the token isn't configured, the route
+ * fails closed with 503, not 200.
+ *
+ * Kept as its own middleware rather than folded into `api-security-middleware.ts`'s
+ * `requireStrictBearerToken` (which has the identical fail-closed/no-loopback-exemption posture)
+ * because these two routes own their own error codes — `REMOTE_TOOL_BRIDGE_*`, distinct from the
+ * general API token's, so an operator can tell which secret is missing from the response alone.
+ * The *decision* logic is shared: header parsing and the constant-time comparison both come from
+ * that module, so the two gates cannot drift on what counts as a well-formed header or on
+ * comparison safety.
+ */
+export declare function requireRemoteToolBridgeToken(deps: {
+    readonly tokenConfig?: RemoteToolBridgeTokenConfig;
+    readonly env?: NodeJS.ProcessEnv;
+}): (req: Request, res: Response, next: NextFunction) => void;
+export interface RemoteToolUseRequest {
+    readonly runId: string;
+    readonly toolUseId: string;
+    readonly toolId: string;
+    readonly input?: unknown;
+}
+export interface RemoteToolResultRequest {
+    readonly runId: string;
+    readonly toolUseId: string;
+    readonly content: string;
+    readonly isError?: boolean;
+}
+export interface RemoteRunEventResponse {
+    readonly recorded: true;
+}
+export declare const remoteToolUseRoute: import("./types.js").JsonRouteSpec<RemoteToolUseRequest, RemoteRunEventResponse, RemoteRunEventHttpDeps>;
+export declare const remoteToolResultRoute: import("./types.js").JsonRouteSpec<RemoteToolResultRequest, RemoteRunEventResponse, RemoteRunEventHttpDeps>;
+/**
+ * Mounts both remote-run-event routes on `app`, gated by {@link requireRemoteToolBridgeToken}.
+ * Unlike `registerRunRoutes`/`registerDelegatedToolRoutes`, these routes do not use
+ * `requireSameOrigin` — they are not meant to be called from a browser at all, only from a host's
+ * own trusted backend process, so the dedicated bearer token above is the sole gate.
+ */
+export declare function registerRemoteRunEventRoutes(app: Express, deps: RemoteRunEventHttpDeps, adapter: AdapterContext): void;
+//# sourceMappingURL=remote-run-events.d.ts.map

package/dist/remote-run-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-run-events.d.ts","sourceRoot":"","sources":["../src/remote-run-events.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExE,OAAO,KAAK,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAMpF,MAAM,WAAW,2BAA2B;IAC1C,gGAAgG;IAChG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,kPAAkP;IAClP,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,2BAA2B,CAAC;IACnD,kGAAkG;IAClG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,gIAAgI;IAChI,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,kCAAkC,KAAK,IAAI,CAAC;CAClF;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,2BAA2B,CAAC;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,IAGS,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAe/D;AAmCD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;CACzB;AAuFD,eAAO,MAAM,kBAAkB,0GAc7B,CAAC;AAEH,eAAO,MAAM,qBAAqB,6GAkBhC,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAMtH"}

package/dist/remote-run-events.js

@@ -0,0 +1,230 @@
+/**
+ * @module remote-run-events
+ *
+ * `POST /api/runs/:runId/tool-use` and `POST /api/runs/:runId/tool-result` — lets a tool call that
+ * executed in a DIFFERENT OS process from the one holding this run's `RunLifecycle` report its
+ * outcome back into the run's own event log, so SSE subscribers (a chat UI, a reattaching client)
+ * see it exactly as they would a locally-executed delegated tool call.
+ *
+ * This exists to relax `@jini-ai/daemon`'s co-location requirement (`RunLifecycle`/`ToolExecutor`
+ * previously had to live in one process per run, because `DelegatedToolBridge.execute()` calls
+ * `lifecycle.emit()` in-process with no remote path — see this repo's own `tovu-learnings.md` §1a).
+ * It does not remove any authorization: whatever executed the tool remotely already ran it through
+ * its OWN `ToolExecutor`/`ToolPolicy` gate before calling here. This route only lets that outcome
+ * be recorded into a run it does not own the process of.
+ *
+ * **Deliberately a separate trust boundary from `registerApiBearerAuthMiddleware`'s general API
+ * token** (`api-security-middleware.ts`): that token may reach browser-adjacent callers depending
+ * on deployment. This route is meant only for a host's own trusted backend-to-backend delegation
+ * (e.g. a sidecar tool-execution process reporting back to the process that owns the run), so its
+ * token has no "disabled" escape hatch and does not exempt loopback peers the way the general
+ * bearer gate does — a loopback bind is exactly the shape a same-machine but lower-trust process
+ * would also present, and this route grants direct run-event-injection, a materially different
+ * capability from what the general API token was designed to gate.
+ */
+import { randomUUID } from 'node:crypto';
+import { createApiError, isTerminalRunState } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { bearerTokenFromHeader, timingSafeTokenMatch } from './api-security-middleware.js';
+import { validationError } from './request.js';
+import { sendApiError, statusForError } from './response.js';
+import { err, ok } from './types.js';
+function defaultInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (remote-run-events/${context.source}, correlationId=${context.correlationId})`, context.error);
+}
+const DEFAULT_TOKEN_ENV_VAR = 'JINI_REMOTE_TOOL_BRIDGE_TOKEN';
+/**
+ * Gates both remote-run-event routes behind a dedicated shared secret. Unlike
+ * `registerApiBearerAuthMiddleware`, there is no "unset means open" or "disabled" mode: a route
+ * that lets a caller inject events into someone else's run must never silently run unauthenticated
+ * just because a host forgot to configure the token. If the token isn't configured, the route
+ * fails closed with 503, not 200.
+ *
+ * Kept as its own middleware rather than folded into `api-security-middleware.ts`'s
+ * `requireStrictBearerToken` (which has the identical fail-closed/no-loopback-exemption posture)
+ * because these two routes own their own error codes — `REMOTE_TOOL_BRIDGE_*`, distinct from the
+ * general API token's, so an operator can tell which secret is missing from the response alone.
+ * The *decision* logic is shared: header parsing and the constant-time comparison both come from
+ * that module, so the two gates cannot drift on what counts as a well-formed header or on
+ * comparison safety.
+ */
+export function requireRemoteToolBridgeToken(deps) {
+    const tokenEnvVar = deps.tokenConfig?.tokenEnvVar ?? DEFAULT_TOKEN_ENV_VAR;
+    const env = deps.env ?? process.env;
+    return (req, res, next) => {
+        const token = env[tokenEnvVar];
+        if (!token) {
+            const error = createApiError('REMOTE_TOOL_BRIDGE_NOT_CONFIGURED', `${tokenEnvVar} is not set — remote run-event ingestion is disabled`);
+            sendApiError(res, statusForError(error), error);
+            return;
+        }
+        const presented = bearerTokenFromHeader(req.get('authorization'));
+        if (presented === null || !timingSafeTokenMatch(presented, token)) {
+            const error = createApiError('REMOTE_TOOL_BRIDGE_TOKEN_REQUIRED', `Authorization: Bearer <${tokenEnvVar}> required`);
+            sendApiError(res, statusForError(error), error);
+            return;
+        }
+        next();
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(body, key) {
+    const value = body[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+/**
+ * Like {@link requireNonEmptyString} but accepts `''`, for the one field where empty is a real
+ * value rather than a missing one: a tool's result `content`.
+ *
+ * The local path already produces empty content legitimately — `serializeDelegatedToolOutput`
+ * (`@jini-ai/daemon`'s `delegated-tool-bridge.ts`) maps a handler returning `undefined` to `''`,
+ * and `DelegatedToolBridge.execute()` emits that verbatim as the `tool_result` event's `content`.
+ * Rejecting `''` here would mean a tool that legitimately produces no output can be reported
+ * in-process but **not** remotely — a silent semantic divergence between the two paths that would
+ * surface as a 400 on the one tool call a host least expects to fail. Identifiers (`runId`,
+ * `toolUseId`, `toolId`) keep the non-empty check: for those, empty really is missing.
+ */
+function requireString(body, key) {
+    const value = body[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function parseRunId(input) {
+    const runId = input.params.runId;
+    return typeof runId === 'string' && runId.length > 0
+        ? ok(runId)
+        : err(validationError('runId must be a non-empty path parameter'));
+}
+function parseRemoteToolUse(input) {
+    const parsedRunId = parseRunId(input);
+    if (!parsedRunId.ok)
+        return parsedRunId;
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const toolUseId = requireNonEmptyString(input.body, 'toolUseId');
+    if (toolUseId === undefined) {
+        return err(validationError('toolUseId must be a non-empty string', [{ path: 'toolUseId', message: 'required non-empty string' }]));
+    }
+    const toolId = requireNonEmptyString(input.body, 'toolId');
+    if (toolId === undefined) {
+        return err(validationError('toolId must be a non-empty string', [{ path: 'toolId', message: 'required non-empty string' }]));
+    }
+    return ok({ runId: parsedRunId.value, toolUseId, toolId, input: input.body.input });
+}
+function parseRemoteToolResult(input) {
+    const parsedRunId = parseRunId(input);
+    if (!parsedRunId.ok)
+        return parsedRunId;
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const toolUseId = requireNonEmptyString(input.body, 'toolUseId');
+    if (toolUseId === undefined) {
+        return err(validationError('toolUseId must be a non-empty string', [{ path: 'toolUseId', message: 'required non-empty string' }]));
+    }
+    // Empty is allowed here, deliberately — see `requireString`'s own doc for the local-path parity
+    // this preserves. Only a non-string (or absent) `content` is a validation failure.
+    const content = requireString(input.body, 'content');
+    if (content === undefined) {
+        return err(validationError('content must be a string', [{ path: 'content', message: 'required string' }]));
+    }
+    const isError = input.body.isError;
+    if (isError !== undefined && typeof isError !== 'boolean') {
+        return err(validationError('isError must be a boolean when provided', [{ path: 'isError', message: 'boolean when provided' }]));
+    }
+    return ok({ runId: parsedRunId.value, toolUseId, content, ...(isError === undefined ? {} : { isError }) });
+}
+/**
+ * Records a caught `recordToolUse`/`recordToolResult` throw as the right HTTP outcome.
+ *
+ * `RunLifecycle.emit()` throws for two documented reasons (see `run-lifecycle.ts`'s own `emit`) —
+ * unknown `runId` and "already terminal" — but the recorder call it sits behind can also fail for
+ * reasons that are nobody's business but the operator's: an event-log write hitting a full disk, a
+ * SQLite error naming its own file path, a driver fault carrying a credential in its message.
+ *
+ * This previously reported *every* one of those as `CONFLICT` carrying `error.message` verbatim,
+ * which turned any such fault into an unauthenticated-adjacent information leak and mislabelled a
+ * server fault as a client-resolvable conflict. So the outcome is now decided by the run's actual
+ * state rather than by whatever the exception happened to say:
+ *
+ * - run is gone -> `NOT_FOUND` (it was there for the pre-check; it isn't now).
+ * - run is terminal -> `CONFLICT`, the one legitimate business conflict. The message is
+ *   *constructed here* from data this module already owns rather than forwarded from the
+ *   exception, so even a misattributed error cannot smuggle its text out through this branch.
+ * - anything else -> SEC-005: a generic `INTERNAL_ERROR` plus a correlation id, with the real
+ *   error handed to the host's sink so it is diagnosable server-side but never echoed.
+ *
+ * Residual, deliberately accepted: a genuine storage fault that happens to coincide with an
+ * already-terminal run is reported as `CONFLICT` rather than `INTERNAL_ERROR`. Distinguishing those
+ * would require matching on `emit`'s message text, trading a rare wrong status code for a check
+ * that breaks silently the next time that string is reworded. Either way nothing leaks, which is
+ * the property that mattered.
+ */
+async function toRemoteEventError(error, runId, deps, source) {
+    const status = await deps.lifecycle.get(runId).catch(() => undefined);
+    if (status === undefined) {
+        return createApiError('NOT_FOUND', `run "${runId}" was not found`);
+    }
+    if (isTerminalRunState(status.state)) {
+        return createApiError('CONFLICT', `run "${runId}" is already terminal — no further events can be recorded`, {
+            details: { runId },
+        });
+    }
+    const correlationId = randomUUID();
+    const sink = deps.onInternalError ?? defaultInternalErrorSink;
+    sink({ source, correlationId, error });
+    return createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId });
+}
+export const remoteToolUseRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/runs/:runId/tool-use',
+    parse: parseRemoteToolUse,
+    handle: async (input, deps) => {
+        const run = await deps.lifecycle.get(input.runId);
+        if (run === undefined)
+            return err(createApiError('NOT_FOUND', `run "${input.runId}" was not found`));
+        try {
+            await deps.recorder.recordToolUse(input.runId, { toolUseId: input.toolUseId, toolId: input.toolId, input: input.input });
+            return ok({ recorded: true });
+        }
+        catch (error) {
+            return err(await toRemoteEventError(error, input.runId, deps, 'tool-use'));
+        }
+    },
+});
+export const remoteToolResultRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/runs/:runId/tool-result',
+    parse: parseRemoteToolResult,
+    handle: async (input, deps) => {
+        const run = await deps.lifecycle.get(input.runId);
+        if (run === undefined)
+            return err(createApiError('NOT_FOUND', `run "${input.runId}" was not found`));
+        try {
+            await deps.recorder.recordToolResult(input.runId, {
+                toolUseId: input.toolUseId,
+                content: input.content,
+                ...(input.isError === undefined ? {} : { isError: input.isError }),
+            });
+            return ok({ recorded: true });
+        }
+        catch (error) {
+            return err(await toRemoteEventError(error, input.runId, deps, 'tool-result'));
+        }
+    },
+});
+/**
+ * Mounts both remote-run-event routes on `app`, gated by {@link requireRemoteToolBridgeToken}.
+ * Unlike `registerRunRoutes`/`registerDelegatedToolRoutes`, these routes do not use
+ * `requireSameOrigin` — they are not meant to be called from a browser at all, only from a host's
+ * own trusted backend process, so the dedicated bearer token above is the sole gate.
+ */
+export function registerRemoteRunEventRoutes(app, deps, adapter) {
+    const gate = requireRemoteToolBridgeToken(deps);
+    app.use('/api/runs/:runId/tool-use', gate);
+    app.use('/api/runs/:runId/tool-result', gate);
+    mountJsonRoute(app, remoteToolUseRoute, deps, adapter);
+    mountJsonRoute(app, remoteToolResultRoute, deps, adapter);
+}
+//# sourceMappingURL=remote-run-events.js.map

package/dist/remote-run-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-run-events.js","sourceRoot":"","sources":["../src/remote-run-events.ts"],"names":[],"mappings":"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"}

package/dist/request.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Request-side normalization: turns a raw Express `Request` into the framework-independent
+ * `RouteInputContext` the rest of the module operates on, and builds a standard `BAD_REQUEST`
+ * `ApiError` for validation failures.
+ */
+import type { Request } from 'express';
+import { type ApiError, type ApiValidationIssue } from '@jini-ai/protocol';
+import type { RouteInputContext } from './types.js';
+/**
+ * Extracts `body`/`query`/`params` from an Express `Request` into a `RouteInputContext`, so a
+ * route's `parse` function can be unit-tested without constructing a real `Request`.
+ */
+export declare function rawInput(req: Request): RouteInputContext;
+/**
+ * Builds a `BAD_REQUEST` `ApiError` for a failed parse. When `issues` is non-empty, attaches
+ * them as structured validation details so clients can render per-field errors.
+ */
+export declare function validationError(message: string, issues?: Pick<ApiValidationIssue, 'path' | 'message'>[]): ApiError;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAMxD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC,EAAO,GAC1D,QAAQ,CAOV"}

package/dist/request.js

@@ -0,0 +1,25 @@
+import { createApiError } from '@jini-ai/protocol';
+/**
+ * Extracts `body`/`query`/`params` from an Express `Request` into a `RouteInputContext`, so a
+ * route's `parse` function can be unit-tested without constructing a real `Request`.
+ */
+export function rawInput(req) {
+    return {
+        body: req.body,
+        query: (req.query ?? {}),
+        params: (req.params ?? {}),
+    };
+}
+/**
+ * Builds a `BAD_REQUEST` `ApiError` for a failed parse. When `issues` is non-empty, attaches
+ * them as structured validation details so clients can render per-field errors.
+ */
+export function validationError(message, issues = []) {
+    if (issues.length === 0) {
+        return createApiError('BAD_REQUEST', message);
+    }
+    return createApiError('BAD_REQUEST', message, {
+        details: { kind: 'validation', issues },
+    });
+}
+//# sourceMappingURL=request.js.map

package/dist/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAA0C,MAAM,mBAAmB,CAAC;AAG3F;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,KAAK,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAA4B;QACnD,MAAM,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAA2B;KACrD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,SAAyD,EAAE;IAE3D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,cAAc,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,cAAc,CAAC,aAAa,EAAE,OAAO,EAAE;QAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAiD;KACvF,CAAC,CAAC;AACL,CAAC"}

package/dist/research.d.ts

@@ -0,0 +1,42 @@
+import type { Express } from 'express';
+import { type AdapterContext } from './adapter.js';
+export interface ResearchSource {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+    readonly publishedAt?: string;
+    readonly provider: string;
+}
+/** Matches OD's real `@open-design/contracts/api/research.ts` `ResearchFindings` shape — see module doc. */
+export interface ResearchSearchResponse {
+    readonly query: string;
+    readonly summary: string;
+    readonly sources: readonly ResearchSource[];
+    readonly provider: string;
+    readonly depth: 'shallow';
+    readonly fetchedAt: number;
+}
+export interface ResearchInternalErrorContext {
+    readonly correlationId: string;
+    readonly error: unknown;
+}
+export interface ResearchProviderCredentials {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly model?: string;
+}
+export interface ResearchHttpDeps {
+    /** Resolves per-provider credentials. Defaults to `TAVILY_API_KEY` for the built-in Tavily transport. */
+    readonly resolveCredentials?: (providerId: string) => Promise<ResearchProviderCredentials>;
+    /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
+    readonly onInternalError?: (context: ResearchInternalErrorContext) => void;
+}
+interface ResearchSearchRequest {
+    readonly query: string;
+    readonly maxSources?: number;
+}
+export declare const researchSearchRoute: import("./types.js").JsonRouteSpec<ResearchSearchRequest, ResearchSearchResponse, ResearchHttpDeps>;
+/** Mounts `POST /api/research/search` on `app`. A pack's `http(app, services)` calls this directly. */
+export declare function registerResearchRoutes(app: Express, deps: ResearchHttpDeps, adapter: AdapterContext): void;
+export {};
+//# sourceMappingURL=research.d.ts.map

package/dist/research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../src/research.ts"],"names":[],"mappings":"AAiGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAapF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,4GAA4G;AAC5G,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yGAAyG;IACzG,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC3F,gIAAgI;IAChI,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,4BAA4B,KAAK,IAAI,CAAC;CAC5E;AA8BD,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAkKD,eAAO,MAAM,mBAAmB,qGA6C9B,CAAC;AAEH,uGAAuG;AACvG,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAE1G"}