@jini-ai/daemon 0.3.8 → 0.5.1

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

@@ -0,0 +1,70 @@
+import type { Express, NextFunction, Request, Response } from 'express';
+import type { RemoteToolEventRecorder, RunLifecycle } from '../index.js';
+import { type AdapterContext } from '@jini-ai/http-kit';
+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(_required: Record<string, never>, deps?: {
+    readonly tokenConfig?: RemoteToolBridgeTokenConfig | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+}): (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("@jini-ai/http-kit").JsonRouteSpec<RemoteToolUseRequest, RemoteRunEventResponse, RemoteRunEventHttpDeps>;
+export declare const remoteToolResultRoute: import("@jini-ai/http-kit").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, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: RemoteRunEventHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+//# sourceMappingURL=remote-run-events.d.ts.map

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

@@ -0,0 +1,224 @@
+/**
+ * @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 reporting path).
+ * 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 '@jini-ai/http-kit';
+import { bearerTokenFromHeader, timingSafeTokenMatch } from '@jini-ai/http-kit';
+import { validationError } from '@jini-ai/http-kit';
+import { sendApiError, statusForError } from '@jini-ai/http-kit';
+import { err, ok } from '@jini-ai/http-kit';
+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(_required, 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({ code: 'REMOTE_TOOL_BRIDGE_NOT_CONFIGURED', message: `${tokenEnvVar} is not set — remote run-event ingestion is disabled` });
+            sendApiError({ res, status: statusForError({ error }), error });
+            return;
+        }
+        const presented = bearerTokenFromHeader({ header: req.get('authorization') });
+        if (presented === null || !timingSafeTokenMatch({ presented, expected: token })) {
+            const error = createApiError({ code: 'REMOTE_TOOL_BRIDGE_TOKEN_REQUIRED', message: `Authorization: Bearer <${tokenEnvVar}> required` });
+            sendApiError({ res, status: 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({ value: runId })
+        : err({ error: validationError({ message: '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({ error: validationError({ message: 'body must be a JSON object' }) });
+    const toolUseId = requireNonEmptyString(input.body, 'toolUseId');
+    if (toolUseId === undefined) {
+        return err({ error: validationError({ message: 'toolUseId must be a non-empty string' }, { issues: [{ path: 'toolUseId', message: 'required non-empty string' }] }) });
+    }
+    const toolId = requireNonEmptyString(input.body, 'toolId');
+    if (toolId === undefined) {
+        return err({ error: validationError({ message: 'toolId must be a non-empty string' }, { issues: [{ path: 'toolId', message: 'required non-empty string' }] }) });
+    }
+    return ok({ value: { 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({ error: validationError({ message: 'body must be a JSON object' }) });
+    const toolUseId = requireNonEmptyString(input.body, 'toolUseId');
+    if (toolUseId === undefined) {
+        return err({ error: validationError({ message: 'toolUseId must be a non-empty string' }, { issues: [{ 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({ error: validationError({ message: 'content must be a string' }, { issues: [{ path: 'content', message: 'required string' }] }) });
+    }
+    const isError = input.body.isError;
+    if (isError !== undefined && typeof isError !== 'boolean') {
+        return err({ error: validationError({ message: 'isError must be a boolean when provided' }, { issues: [{ path: 'isError', message: 'boolean when provided' }] }) });
+    }
+    return ok({ value: { 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({ code: 'NOT_FOUND', message: `run "${runId}" was not found` });
+    }
+    if (isTerminalRunState({ state: status.state })) {
+        return createApiError({ code: 'CONFLICT', message: `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({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId });
+}
+export const remoteToolUseRoute = defineJsonRoute({
+    method: 'post', path: '/api/runs/:runId/tool-use', parse: parseRemoteToolUse, handle: async ({ input: input, deps: deps }) => {
+        const run = await deps.lifecycle.get({ runId: input.runId });
+        if (run === undefined)
+            return err({ error: createApiError({ code: 'NOT_FOUND', message: `run "${input.runId}" was not found` }) });
+        try {
+            await deps.recorder.recordToolUse({ runId: input.runId, record: { toolUseId: input.toolUseId, toolId: input.toolId, input: input.input } });
+            return ok({ value: { recorded: true } });
+        }
+        catch (error) {
+            return err({ error: 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: input, deps: deps }) => {
+        const run = await deps.lifecycle.get({ runId: input.runId });
+        if (run === undefined)
+            return err({ error: createApiError({ code: 'NOT_FOUND', message: `run "${input.runId}" was not found` }) });
+        try {
+            await deps.recorder.recordToolResult({ runId: input.runId, record: {
+                    toolUseId: input.toolUseId,
+                    content: input.content,
+                    ...(input.isError === undefined ? {} : { isError: input.isError }),
+                } });
+            return ok({ value: { recorded: true } });
+        }
+        catch (error) {
+            return err({ error: 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 }, _optional = {}) {
+    const gate = requireRemoteToolBridgeToken({}, deps);
+    app.use('/api/runs/:runId/tool-use', gate);
+    app.use('/api/runs/:runId/tool-result', gate);
+    mountJsonRoute({ app, spec: remoteToolUseRoute, deps, adapter });
+    mountJsonRoute({ app, spec: remoteToolResultRoute, deps, adapter });
+}
+//# sourceMappingURL=remote-run-events.js.map

package/dist/http/research.d.ts

@@ -0,0 +1,48 @@
+import type { Express } from 'express';
+import { type AdapterContext } from '@jini-ai/http-kit';
+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 }: {
+        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("@jini-ai/http-kit").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, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: ResearchHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+export {};
+//# sourceMappingURL=research.d.ts.map

package/dist/http/research.js

@@ -0,0 +1,315 @@
+import { redactSecrets } from '@jini-ai/core';
+/**
+ * @module research
+ *
+ * `POST /api/research/search` — a thin route wrapper over Tavily's real Search API
+ * (`POST {baseUrl}/search`), ported from OD's `apps/daemon/src/research/tavily.ts` (the low-level
+ * Tavily client) **and** `apps/daemon/src/research/index.ts#searchResearch` (the findings-assembly
+ * wrapper the real `/api/research/search` route in `apps/daemon/src/routes/media.ts` actually
+ * calls). Verified against a **live** boot of OD's real daemon (`apps/daemon/bin/od.mjs`, from the
+ * sibling `/Users/la/Desktop/Programming/OSS-Repos/open-design` checkout on this machine) hitting
+ * the real route with a mock Tavily backend, not just static reading — see the field-by-field notes
+ * below for what that live diff actually found. The request/response shape and defaults are ported
+ * (`search_depth: 'basic'`, `include_answer: true`, `include_raw_content: false`, a 20-result hard
+ * cap, the `results[]` -> `ResearchSource[]` mapping, the 1000-char query cap, the
+ * `Math.floor`+clamp-to-`[1,20]` `maxSources` normalization, and the `NO_RESEARCH_SOURCES`-style
+ * "zero sources is a failure, not an empty success" behavior) — OD's own `TavilyError`/
+ * `ResearchError` classes and `requestInit.dispatcher` passthrough are not carried over; this route
+ * pack's own SEC-005 error-handling convention (a generic `INTERNAL_ERROR` + correlation id,
+ * matching every other route pack in this package) replaces the origin's thrown-error shape for
+ * genuinely unexpected failures. OD's `AbortController`-based 30s timeout **is** carried over
+ * (added after an external audit flagged its absence — a stalled/malicious upstream could otherwise
+ * hold a request indefinitely, since bare `fetch` has no default timeout): `tavilySearch` aborts
+ * the request after `DEFAULT_TAVILY_TIMEOUT_MS` and clears the timer in a `finally` regardless of
+ * outcome. No other request-level knobs (connection pooling, `dispatcher`) are exposed yet — a
+ * future pass can add them the same way `media.ts#MediaGenerationRequestInit` optionally threads a
+ * `dispatcher` through, if a real need for one shows up.
+ *
+ * **`ResearchSource` field names match OD's real `@open-design/contracts/api/research.ts`
+ * `ResearchSource` shape** (`title`/`url`/`snippet`/`publishedAt?`/`provider`). **`ResearchSearchResponse`
+ * matches that same contract file's `ResearchFindings` shape** (`query`/`summary`/`sources`/
+ * `provider`/`depth`/`fetchedAt`) — an earlier version of this port conflated the *raw Tavily
+ * client's* return shape (`tavily.ts`'s `{ answer, sources }`) with the *route's actual HTTP
+ * response* shape (`research/index.ts#searchResearch`'s `ResearchFindings`), which the live daemon
+ * diff caught: hitting the real `/api/research/search` with a mock Tavily backend returned
+ * `{"query":"...","summary":"...","sources":[...],"provider":"tavily","depth":"shallow",
+ * "fetchedAt":<ms>}`, never `{answer, sources}`. `depth` is hardcoded to the `'shallow'` literal
+ * (rather than OD's full `'shallow' | 'medium' | 'deep'` `ResearchDepth` union) since this port, like
+ * OD's real Phase-1 `searchResearch`, only ever produces `'shallow'` — there is no depth-selection
+ * request field on either side yet.
+ *
+ * **`providers` request field**: OD's real route accepts an optional `providers: string[]` and only
+ * inspects `providers[0]` (defaulting to `'tavily'` when absent/empty); a non-array value is treated
+ * as absent (not rejected), and a first element other than `'tavily'` is rejected with a 400 before
+ * credentials are even resolved (`UNSUPPORTED_RESEARCH_PROVIDER` in OD; this port's own generic
+ * `BAD_REQUEST` validation-error convention here, same as every other `parse`-time rejection in this
+ * file). Confirmed live: `providers: ["bing"]` 400s on the real daemon, `providers: ["tavily"]`
+ * succeeds identically to omitting the field.
+ *
+ * **Credential resolution**: `resolveCredentials` defaults to this transport's narrow
+ * `TAVILY_API_KEY` environment seam. A host with its own secrets layer supplies its own resolver
+ * instead; this daemon route pack deliberately does not depend on the incubating media implementation
+ * package. Note OD's real env-var precedence is
+ * `['OD_TAVILY_API_KEY', 'TAVILY_API_KEY']` (checked live via `apps/daemon/tests/research.test.ts`'s
+ * `TAVILY_ENV_KEYS`) — this package's own `@jini-ai/media#PROVIDER_CREDENTIAL_ENV_VARS.tavily` only
+ * lists `['TAVILY_API_KEY']`, deliberately dropping the `OD_`-prefixed variant: this repo's own
+ * `AGENTS.md` boundary rule bans product-identity strings (including the `OD_` prefix) inside
+ * `packages/@jini-ai/**`, so that omission is a hard constraint, not a port gap.
+ *
+ * **Missing credentials is a clean `NOT_CONFIGURED` (503), not an `INTERNAL_ERROR`.** No API key
+ * configured is an expected, non-exceptional state (matching `connectors.ts`'s "capability exists,
+ * reachable, inert until configured" shape) — it never reaches the SEC-005 sink, since there is no
+ * real exception or secret to hide, just an honest "not set up yet" answer. OD's real behavior here
+ * (confirmed live) is a 400 `TAVILY_API_KEY_MISSING`, not a 503 — this is a deliberate, documented
+ * divergence from OD (this package's own generic-error-code convention, applied consistently across
+ * every route pack) rather than an oversight, so it is intentionally **not** changed to match OD's
+ * 400.
+ *
+ * **Zero sources is a `NOT_FOUND` (404), not a `200` with an empty array.** OD's real
+ * `searchResearch` throws `ResearchError('no sources found', 404, 'NO_RESEARCH_SOURCES')` when
+ * Tavily's `results[]` maps to zero usable sources (confirmed live against a mock Tavily backend
+ * that returns `results: []`) — this port matches that with the package's own generic `NOT_FOUND`
+ * code (mapped to 404 by `response.ts#ERROR_STATUS_BY_CODE`) rather than inventing a
+ * research-specific code, same rationale as the `NOT_CONFIGURED` choice above.
+ *
+ * **Query normalization**: OD's real `searchResearch` trims the query and caps it at 1000 characters
+ * before ever calling Tavily (`(input.query?.trim() || '').slice(0, 1000)`) — confirmed live by
+ * sending a padded, 1112-char query and observing the daemon forward exactly 1000 trimmed
+ * characters to the mock Tavily backend. This port replicates both the trim and the cap in
+ * `parseResearchSearch`.
+ *
+ * **`maxSources` normalization**: OD's real `clampMaxSources` is `Math.max(1, Math.min(Math.floor(value),
+ * 20))` — confirmed live by sending `maxSources: 2.7` and observing `max_results: 2` (not `2.7`) on
+ * the wire to the mock Tavily backend. An earlier version of this port only clamped the range
+ * (`Math.max(0, Math.min(value, 20))`) without flooring, which could forward a fractional
+ * `max_results` straight to Tavily's real API for any non-integer input (e.g. `maxSources: 0.5`
+ * would have clamped to `0.5`, not `1`); this port now floors first, matching OD.
+ *
+ * **SEC-005 for everything else**: a genuine Tavily request/response failure is caught, reported
+ * through `onInternalError` (defaults to `console.error`, matching every other route pack), and
+ * surfaced to the caller as a generic `INTERNAL_ERROR` — the raw error message (which can echo
+ * request details) is never sent to the HTTP caller directly. `redactSecrets` (reused from
+ * `@jini-ai/core`'s `connection-guard.ts`, already reachable via this package's existing
+ * `@jini-ai/agent-runtime` dependency — the same "shared primitive, one implementation" reuse this
+ * task's agent-runtime work applied to `sse-decode.ts`/`turn-end-guard.ts`) strips the bearer
+ * token out of any upstream error text before it is even logged, belt-and-braces alongside the
+ * generic-message substitution.
+ */
+import { randomUUID } from 'node:crypto';
+import { validateBaseUrl } from '@jini-ai/agent-runtime';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
+import { validationError } from '@jini-ai/http-kit';
+import { err, ok } from '@jini-ai/http-kit';
+const DEFAULT_TAVILY_BASE_URL = 'https://api.tavily.com';
+/** Tavily's own documented cap on `max_results` (see OD's `tavily.ts#TAVILY_MAX_RESULTS_LIMIT`). */
+const TAVILY_MAX_RESULTS_LIMIT = 20;
+const DEFAULT_MAX_SOURCES = 5;
+/** Matches OD's own `tavily.ts` timeout — see module doc. */
+const DEFAULT_TAVILY_TIMEOUT_MS = 30_000;
+/** Matches OD's real `research/index.ts#searchResearch` query cap — see module doc. */
+const MAX_QUERY_LENGTH = 1000;
+function defaultInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (research/search, correlationId=${context.correlationId})`, context.error);
+}
+/**
+ * Default `ResearchHttpDeps.resolveCredentials`: reads `TAVILY_API_KEY` from the environment.
+ *
+ * Takes no `providerId` even though the `resolveCredentials` dep type supplies one (a function of
+ * fewer parameters is assignable, so this still satisfies the interface). It used to accept one and
+ * return `{}` for anything other than `'tavily'`, but that arm was unreachable twice over: the only
+ * call site below passes the literal `'tavily'`, and `validateRequestedProvider` already rejects any
+ * other provider name at parse time. A host that supports a second provider injects its own
+ * `resolveCredentials` rather than reaching this function with a different id.
+ */
+async function defaultResolveCredentials() {
+    const apiKey = process.env.TAVILY_API_KEY?.trim();
+    return apiKey ? { apiKey } : {};
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+/**
+ * Only `'tavily'` is a supported provider (matches OD's real Phase-1 `searchResearch` — see module
+ * doc). OD only inspects `providers[0]` and treats a non-array `providers` value as absent rather
+ * than rejecting it; this mirrors both.
+ */
+function validateRequestedProvider(rawProviders) {
+    if (!Array.isArray(rawProviders))
+        return ok({ value: null });
+    const filtered = rawProviders.filter((p) => typeof p === 'string' && p.length > 0);
+    const requested = filtered[0];
+    if (requested !== undefined && requested !== 'tavily') {
+        return err({ error: validationError({ message: `provider "${requested}" is not supported — only "tavily" is available` }) });
+    }
+    return ok({ value: null });
+}
+function parseResearchSearch(input) {
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+    const rawQuery = nonEmptyString(input.body.query);
+    if (!rawQuery)
+        return err({ error: validationError({ message: 'query must be a non-empty string' }, { issues: [{ path: 'query', message: 'required non-empty string' }] }) });
+    const query = rawQuery.trim().slice(0, MAX_QUERY_LENGTH);
+    const maxSources = input.body.maxSources;
+    if (maxSources !== undefined && (typeof maxSources !== 'number' || !Number.isFinite(maxSources) || maxSources <= 0)) {
+        return err({ error: validationError({ message: 'maxSources must be a positive number when provided' }) });
+    }
+    const providerCheck = validateRequestedProvider(input.body.providers);
+    if (!providerCheck.ok)
+        return providerCheck;
+    return ok({ value: { query, ...(maxSources !== undefined ? { maxSources: maxSources } : {}) } });
+}
+/**
+ * Calls Tavily's real `POST /search` endpoint directly — see module doc for the port's exact
+ * scope/provenance. Throws (never a `Result`) on any failure; the route handler below is the one
+ * place that converts a thrown error into the package's SEC-005 response shape.
+ *
+ * `apiKey` is a separate, non-optional parameter rather than being read off `credentials`, so the
+ * "credential is present" invariant is carried by the type system instead of by a runtime guard.
+ * This function used to take only `credentials` and re-check `credentials.apiKey` itself, but the
+ * sole caller below already returns `NOT_CONFIGURED` before it ever gets here — the check was
+ * unreachable by construction, so it is now expressed as a required argument instead of dead code.
+ * `credentials` is still passed for its optional transport config (`baseUrl`).
+ */
+async function tavilySearch(apiKey, credentials, request) {
+    const baseUrl = credentials.baseUrl ?? DEFAULT_TAVILY_BASE_URL;
+    const baseUrlCheck = validateBaseUrl({ baseUrl });
+    if (baseUrlCheck.error) {
+        throw new Error(baseUrlCheck.error);
+    }
+    const base = baseUrl.replace(/\/+$/, '');
+    // Floor before clamping, matching OD's real `clampMaxSources` — see module doc. Without the
+    // floor, a fractional `maxSources` (e.g. `2.7`, or `0.5` before the `Math.max(1, ...)` floor
+    // below) would forward a non-integer `max_results` straight to Tavily's real API.
+    const maxResults = Math.max(1, Math.min(Math.floor(request.maxSources ?? DEFAULT_MAX_SOURCES), TAVILY_MAX_RESULTS_LIMIT));
+    const body = {
+        query: request.query,
+        search_depth: 'basic',
+        max_results: maxResults,
+        include_answer: true,
+        include_raw_content: false,
+    };
+    // The timeout must stay armed for the full operation, not just until `fetch` resolves —
+    // `fetch` resolves as soon as response headers arrive, before the body is read. A round-2
+    // external audit caught (and locally reproduced) an earlier version of this fix that cleared
+    // the timer right after `fetch` resolved, leaving `response.text()`/`response.json()` below
+    // completely unbounded against a server that sends headers promptly and then stalls the body.
+    //
+    // `TavilyHttpError` marks an error already redacted and formatted by the `!response.ok` branch
+    // below, so the outer catch can rethrow it verbatim instead of wrapping it a second time (which
+    // would otherwise produce a "Tavily request failed: Tavily 429: ..." double-prefixed message).
+    class TavilyHttpError extends Error {
+    }
+    const timeoutController = new AbortController();
+    const timeoutHandle = setTimeout(() => timeoutController.abort(), DEFAULT_TAVILY_TIMEOUT_MS);
+    // Assigned in the `try` and returned *after* the `finally`, rather than returned from inside the
+    // `try`. Both forms behave identically, but a return-through-`finally` compiles to three copies of
+    // the `finally` body (normal completion, return, throw) and one of those is unreachable here — the
+    // `try` cannot fall off its end and the `catch` always throws. Falling through to a single return
+    // keeps the cleanup path honestly measurable instead of permanently one-third uncovered.
+    let output;
+    try {
+        const response = await fetch(`${base}/search`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+            body: JSON.stringify(body),
+            signal: timeoutController.signal,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new TavilyHttpError(redactSecrets({ input: `Tavily ${response.status}: ${text.slice(0, 200) || 'no body'}` }, { exactSecrets: [apiKey] }));
+        }
+        const json = (await response.json());
+        const answer = typeof json.answer === 'string' ? json.answer : '';
+        const rawResults = Array.isArray(json.results) ? json.results : [];
+        const sources = [];
+        for (const raw of rawResults) {
+            const url = typeof raw.url === 'string' ? raw.url : '';
+            if (!url)
+                continue;
+            const publishedAt = typeof raw.published_date === 'string' && raw.published_date.trim() ? raw.published_date.trim() : undefined;
+            sources.push({
+                title: typeof raw.title === 'string' && raw.title.trim() ? raw.title.trim() : url,
+                url,
+                snippet: typeof raw.content === 'string' ? raw.content.trim().slice(0, 800) : '',
+                provider: 'tavily',
+                ...(publishedAt ? { publishedAt } : {}),
+            });
+        }
+        output = { answer, sources };
+    }
+    catch (error) {
+        if (!timeoutController.signal.aborted && error instanceof TavilyHttpError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(redactSecrets({
+            input: timeoutController.signal.aborted
+                ? `Tavily request timed out after ${DEFAULT_TAVILY_TIMEOUT_MS}ms`
+                : `Tavily request failed: ${message}`,
+        }, { exactSecrets: [apiKey] }));
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+    return output;
+}
+/** Ported verbatim from OD's real `research/index.ts#synthesizeFallbackSummary` — see module doc. Used when Tavily returns no `answer` text so the caller still gets a usable `summary`. */
+function synthesizeFallbackSummary(sources) {
+    const lead = sources
+        .slice(0, 5)
+        .map((s, i) => `- [${i + 1}] ${s.title}: ${s.snippet.slice(0, 200)}`)
+        .join('\n');
+    return `(No provider summary; top snippets follow.)\n${lead}`;
+}
+export const researchSearchRoute = defineJsonRoute({
+    method: 'post', path: '/api/research/search', parse: parseResearchSearch, handle: async ({ input: request, deps }) => {
+        const resolveCredentials = deps.resolveCredentials ?? defaultResolveCredentials;
+        const onInternalError = deps.onInternalError ?? defaultInternalErrorSink;
+        let credentials;
+        try {
+            credentials = await resolveCredentials({ providerId: 'tavily' });
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            onInternalError({ correlationId, error });
+            return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
+        }
+        const apiKey = credentials.apiKey;
+        if (!apiKey) {
+            return err({ error: createApiError({ code: 'NOT_CONFIGURED', message: 'tavily provider not configured' }) });
+        }
+        try {
+            const raw = await tavilySearch(apiKey, credentials, request);
+            // Matches OD's real `NO_RESEARCH_SOURCES` (404) — see module doc. Zero usable sources is a
+            // failure, not an empty success, even when the upstream Tavily call itself succeeded.
+            if (raw.sources.length === 0) {
+                return err({ error: createApiError({ code: 'NOT_FOUND', message: 'no sources found' }) });
+            }
+            const result = {
+                query: request.query,
+                summary: raw.answer || synthesizeFallbackSummary(raw.sources),
+                sources: raw.sources,
+                provider: 'tavily',
+                depth: 'shallow',
+                fetchedAt: Date.now(),
+            };
+            return ok({ value: result });
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            onInternalError({ correlationId, error });
+            return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
+        }
+    }
+}, { requireSameOrigin: true });
+/** Mounts `POST /api/research/search` on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerResearchRoutes({ app, deps, adapter }, _optional = {}) {
+    mountJsonRoute({ app, spec: researchSearchRoute, deps, adapter });
+}
+//# sourceMappingURL=research.js.map