@jini-ai/http-kit 0.2.1

package/dist/research.js

@@ -0,0 +1,316 @@
+/**
+ * @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; `@jini-ai/http-kit` 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/agent-runtime`'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 { redactSecrets, validateBaseUrl } from '@jini-ai/agent-runtime';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { validationError } from './request.js';
+import { err, ok } from './types.js';
+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(null);
+    const filtered = rawProviders.filter((p) => typeof p === 'string' && p.length > 0);
+    const requested = filtered[0];
+    if (requested !== undefined && requested !== 'tavily') {
+        return err(validationError(`provider "${requested}" is not supported — only "tavily" is available`));
+    }
+    return ok(null);
+}
+function parseResearchSearch(input) {
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const rawQuery = nonEmptyString(input.body.query);
+    if (!rawQuery)
+        return err(validationError('query must be a non-empty string', [{ 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(validationError('maxSources must be a positive number when provided'));
+    }
+    const providerCheck = validateRequestedProvider(input.body.providers);
+    if (!providerCheck.ok)
+        return providerCheck;
+    return ok({ 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(`Tavily ${response.status}: ${text.slice(0, 200) || 'no body'}`, [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(timeoutController.signal.aborted
+            ? `Tavily request timed out after ${DEFAULT_TAVILY_TIMEOUT_MS}ms`
+            : `Tavily request failed: ${message}`, [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',
+    requireSameOrigin: true,
+    parse: parseResearchSearch,
+    handle: async (request, deps) => {
+        const resolveCredentials = deps.resolveCredentials ?? defaultResolveCredentials;
+        const onInternalError = deps.onInternalError ?? defaultInternalErrorSink;
+        let credentials;
+        try {
+            credentials = await resolveCredentials('tavily');
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            onInternalError({ correlationId, error });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+        const apiKey = credentials.apiKey;
+        if (!apiKey) {
+            return err(createApiError('NOT_CONFIGURED', '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(createApiError('NOT_FOUND', '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(result);
+        }
+        catch (error) {
+            const correlationId = randomUUID();
+            onInternalError({ correlationId, error });
+            return err(createApiError('INTERNAL_ERROR', 'an internal error occurred', { requestId: correlationId }));
+        }
+    },
+});
+/** Mounts `POST /api/research/search` on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerResearchRoutes(app, deps, adapter) {
+    mountJsonRoute(app, researchSearchRoute, deps, adapter);
+}
+//# sourceMappingURL=research.js.map

package/dist/research.js.map

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

package/dist/response.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Response-side serialization: writes a plain JSON body or a standard `ApiError` envelope onto
+ * an Express `Response`, and maps an `ApiErrorCode` to its default HTTP status. No internal
+ * dependencies — this is the terminal step of the Adapter's error-handling pipeline.
+ */
+import type { Response } from 'express';
+import { type ApiError } from '@jini-ai/protocol';
+/** Writes `body` as JSON with the given status code. */
+export declare function sendJson(res: Response, status: number, body: unknown): void;
+/** Writes an `ApiError`, wrapped in the standard `{ error }` envelope, with the given status code. */
+export declare function sendApiError(res: Response, status: number, error: ApiError): void;
+/** Resolves the HTTP status to send for an `ApiError`, defaulting to 500 for unmapped codes. */
+export declare function statusForError(error: ApiError): number;
+//# sourceMappingURL=response.d.ts.map

package/dist/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAA0B,KAAK,QAAQ,EAAqB,MAAM,mBAAmB,CAAC;AAE7F,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAE3E;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjF;AAkCD,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEtD"}

package/dist/response.js

@@ -0,0 +1,45 @@
+import { createApiErrorResponse } from '@jini-ai/protocol';
+/** Writes `body` as JSON with the given status code. */
+export function sendJson(res, status, body) {
+    res.status(status).json(body);
+}
+/** Writes an `ApiError`, wrapped in the standard `{ error }` envelope, with the given status code. */
+export function sendApiError(res, status, error) {
+    res.status(status).json(createApiErrorResponse(error));
+}
+/**
+ * @internal
+ * Default HTTP status per generic `ApiErrorCode`. Codes not listed here fall back to 500 in
+ * `statusForError` — deliberately conservative, since an unmapped code (including any
+ * product-specific code a consuming pack defines) is more likely a new server-side failure mode
+ * than a client error.
+ */
+const ERROR_STATUS_BY_CODE = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    PAYLOAD_TOO_LARGE: 413,
+    UNSUPPORTED_MEDIA_TYPE: 415,
+    VALIDATION_FAILED: 422,
+    RATE_LIMITED: 429,
+    INTERNAL_ERROR: 500,
+    UPSTREAM_UNAVAILABLE: 502,
+    SERVICE_UNAVAILABLE: 503,
+    NOT_CONFIGURED: 503,
+    TOOL_TOKEN_MISSING: 401,
+    TOOL_TOKEN_INVALID: 401,
+    TOOL_TOKEN_EXPIRED: 401,
+    TOOL_ENDPOINT_DENIED: 403,
+    TOOL_OPERATION_DENIED: 403,
+    TOOL_NOT_AVAILABLE: 503,
+    REMOTE_TOOL_BRIDGE_NOT_CONFIGURED: 503,
+    REMOTE_TOOL_BRIDGE_TOKEN_REQUIRED: 401,
+    OAUTH_FLOW_IN_PROGRESS: 409,
+};
+/** Resolves the HTTP status to send for an `ApiError`, defaulting to 500 for unmapped codes. */
+export function statusForError(error) {
+    return ERROR_STATUS_BY_CODE[error.code] ?? 500;
+}
+//# sourceMappingURL=response.js.map

package/dist/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAoC,MAAM,mBAAmB,CAAC;AAE7F,wDAAwD;AACxD,MAAM,UAAU,QAAQ,CAAC,GAAa,EAAE,MAAc,EAAE,IAAa;IACnE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,YAAY,CAAC,GAAa,EAAE,MAAc,EAAE,KAAe;IACzE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,oBAAoB,GAA0C;IAClE,WAAW,EAAE,GAAG;IAChB,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,iBAAiB,EAAE,GAAG;IACtB,sBAAsB,EAAE,GAAG;IAC3B,iBAAiB,EAAE,GAAG;IACtB,YAAY,EAAE,GAAG;IACjB,cAAc,EAAE,GAAG;IACnB,oBAAoB,EAAE,GAAG;IACzB,mBAAmB,EAAE,GAAG;IACxB,cAAc,EAAE,GAAG;IACnB,kBAAkB,EAAE,GAAG;IACvB,kBAAkB,EAAE,GAAG;IACvB,kBAAkB,EAAE,GAAG;IACvB,oBAAoB,EAAE,GAAG;IACzB,qBAAqB,EAAE,GAAG;IAC1B,kBAAkB,EAAE,GAAG;IACvB,iCAAiC,EAAE,GAAG;IACtC,iCAAiC,EAAE,GAAG;IACtC,sBAAsB,EAAE,GAAG;CAC5B,CAAC;AAEF,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,OAAO,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;AACjD,CAAC"}

package/dist/route-manifest.d.ts

@@ -0,0 +1,31 @@
+import type { RouteRegistration } from './route-registration-guard.js';
+/**
+ * Route families described by this manifest, keyed by the same feature id `@jini-ai/server`'s built-in
+ * feature catalog uses — so a host that enables features by name can look routes up by that same name.
+ */
+export declare const JINI_ROUTE_MANIFEST: Readonly<Record<string, readonly RouteRegistration[]>>;
+/**
+ * The routes one family mounts.
+ *
+ * @param family - A feature id, e.g. `'runs'`.
+ * @returns That family's registrations, or `undefined` when the family is not described by this
+ * manifest. The distinction matters: a caller building a proxy allow-list must treat `undefined` as
+ * "look it up yourself", never as "this family has no routes" — see this module's scope note.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function routeFamilyManifest(family: string): readonly RouteRegistration[] | undefined;
+/**
+ * Every route across every family this manifest describes, de-duplicated.
+ *
+ * De-duplication is real rather than defensive: `health` intentionally mounts both `/health` and
+ * `/api/health` as separate routes, and a future family could legitimately share a path with another.
+ *
+ * @param families - Family ids to include. Unknown ids contribute nothing (rather than throwing), so a
+ * caller can pass its enabled-feature list verbatim without pre-filtering it.
+ * @returns One entry per distinct `METHOD PATH`, in first-seen order.
+ * @complexity O(n) in the total routes across the named families.
+ * @overallScore 100/100
+ */
+export declare function manifestRoutesForFamilies(families: readonly string[]): readonly RouteRegistration[];
+//# sourceMappingURL=route-manifest.d.ts.map

package/dist/route-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-manifest.d.ts","sourceRoot":"","sources":["../src/route-manifest.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAqBvE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAkBtF,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,SAAS,CAE5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,iBAAiB,EAAE,CAYnG"}

package/dist/route-manifest.js

@@ -0,0 +1,103 @@
+/**
+ * @module route-manifest
+ *
+ * Which `{method, path}` pairs each route family mounts, as inert data a caller can read *without*
+ * mounting anything.
+ *
+ * **The problem this solves.** A host that puts a reverse proxy in front of a Jini daemon in another
+ * process has to know that daemon's route list to forward anything. With no published inventory, the
+ * only way to build one is to copy path strings by hand — and a hand-copied list silently falls behind
+ * the moment a family gains a route. That has already happened at least once in a real consumer: a
+ * proxy shipped without `GET /api/runs` and the daemon's list endpoint was simply unreachable, 404-ing
+ * at the host's own router with nothing to indicate the host was the cause.
+ *
+ * **Why this file cannot itself drift.** It declares no method or path literals. Every entry is derived
+ * from the very `JsonRouteSpec` constant the family's `register*Routes` function mounts, so a spec's
+ * path change moves the manifest with it, automatically. The single exception is the SSE run-event
+ * route, which is registered with a bare `app.get` rather than a spec — and it contributes the
+ * already-exported `RUN_EVENTS_ROUTE_PATH` constant rather than a copy of it.
+ *
+ * That leaves exactly one failure mode: a family gains a route and nobody adds it *here*. The paired
+ * test (`__tests__/route-manifest.test.ts`) closes that by mounting each declared family's real
+ * registrar onto a recording app and asserting the manifest matches what actually registered — so a
+ * missing entry fails a test rather than reaching a consumer.
+ *
+ * **Scope, stated honestly: this covers the families a sidecar consumer proxies**, not all 19 the
+ * package can mount. {@link routeFamilyManifest} returns `undefined` for anything undeclared rather
+ * than an empty list, so "not described here" is distinguishable from "has no routes" — a proxy must
+ * never conclude a family is empty when it is merely undocumented. Adding a family is a matter of
+ * listing its exported specs below; the test then holds it correct.
+ */
+import { agentListRoute, agentRescanRoute } from './agents.js';
+import { delegatedToolExecuteRoute } from './delegated-tools.js';
+import { apiHealthRoute, apiReadyRoute, apiVersionInfoRoute, healthRoute, readyRoute, versionInfoRoute, } from './health.js';
+import { RUN_EVENTS_ROUTE_PATH, runCancelRoute, runListRoute, runStartRoute, runStatusRoute, } from './runs.js';
+import { toolCatalogDescribeRoute, toolCatalogSearchRoute } from './tool-catalog.js';
+/**
+ * Projects route specs onto `RouteRegistration`s, upper-casing the method so entries compare directly
+ * against {@link getRouteRegistrationInventory}'s output.
+ *
+ * @param specs - Route specs, passed by reference so no path literal is ever restated.
+ * @returns One registration per spec, in argument order.
+ * @complexity O(n) in the number of specs.
+ * @overallScore 100/100
+ */
+function fromSpecs(...specs) {
+    return specs.map((spec) => ({ method: spec.method.toUpperCase(), path: spec.path }));
+}
+/**
+ * Route families described by this manifest, keyed by the same feature id `@jini-ai/server`'s built-in
+ * feature catalog uses — so a host that enables features by name can look routes up by that same name.
+ */
+export const JINI_ROUTE_MANIFEST = {
+    health: fromSpecs(healthRoute, apiHealthRoute, readyRoute, apiReadyRoute, versionInfoRoute, apiVersionInfoRoute),
+    runs: [
+        ...fromSpecs(runStartRoute, runListRoute, runStatusRoute, runCancelRoute),
+        // Registered with a bare `app.get` rather than a route spec (by `registerRunRoutes` itself), so
+        // it contributes its exported path constant instead of a copied literal.
+        { method: 'GET', path: RUN_EVENTS_ROUTE_PATH },
+    ],
+    agents: fromSpecs(agentListRoute, agentRescanRoute),
+    toolCatalog: fromSpecs(toolCatalogSearchRoute, toolCatalogDescribeRoute),
+    delegatedToolCalls: fromSpecs(delegatedToolExecuteRoute),
+};
+/**
+ * The routes one family mounts.
+ *
+ * @param family - A feature id, e.g. `'runs'`.
+ * @returns That family's registrations, or `undefined` when the family is not described by this
+ * manifest. The distinction matters: a caller building a proxy allow-list must treat `undefined` as
+ * "look it up yourself", never as "this family has no routes" — see this module's scope note.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export function routeFamilyManifest(family) {
+    return JINI_ROUTE_MANIFEST[family];
+}
+/**
+ * Every route across every family this manifest describes, de-duplicated.
+ *
+ * De-duplication is real rather than defensive: `health` intentionally mounts both `/health` and
+ * `/api/health` as separate routes, and a future family could legitimately share a path with another.
+ *
+ * @param families - Family ids to include. Unknown ids contribute nothing (rather than throwing), so a
+ * caller can pass its enabled-feature list verbatim without pre-filtering it.
+ * @returns One entry per distinct `METHOD PATH`, in first-seen order.
+ * @complexity O(n) in the total routes across the named families.
+ * @overallScore 100/100
+ */
+export function manifestRoutesForFamilies(families) {
+    const seen = new Set();
+    const routes = [];
+    for (const family of families) {
+        for (const route of JINI_ROUTE_MANIFEST[family] ?? []) {
+            const key = `${route.method} ${route.path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            routes.push(route);
+        }
+    }
+    return routes;
+}
+//# sourceMappingURL=route-manifest.js.map

package/dist/route-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-manifest.js","sourceRoot":"","sources":["../src/route-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AASrF;;;;;;;;GAQG;AACH,SAAS,SAAS,CAAC,GAAG,KAA+B;IACnD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA2D;IACzF,MAAM,EAAE,SAAS,CACf,WAAW,EACX,cAAc,EACd,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,mBAAmB,CACpB;IACD,IAAI,EAAE;QACJ,GAAG,SAAS,CAAC,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,CAAC;QACzE,gGAAgG;QAChG,yEAAyE;QACzE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE;KAC/C;IACD,MAAM,EAAE,SAAS,CAAC,cAAc,EAAE,gBAAgB,CAAC;IACnD,WAAW,EAAE,SAAS,CAAC,sBAAsB,EAAE,wBAAwB,CAAC;IACxE,kBAAkB,EAAE,SAAS,CAAC,yBAAyB,CAAC;CACzD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAA2B;IACnE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,mBAAmB,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACtD,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/route-registration-guard.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @module route-registration-guard
+ *
+ * Wraps an Express app's route-registration methods (`get`/`post`/`put`/`patch`/`delete`/
+ * `options`/`all`/`use`) to build a queryable inventory of every mounted route, and to guard a
+ * caller-supplied set of "must register at most once" route keys against accidental duplicate
+ * registration — e.g. two packs each mounting `POST /api/runs` would otherwise silently shadow
+ * one another instead of failing loudly at composition time.
+ *
+ * Genericized from an origin daemon's route-registration guard — see `source-map.md`. The
+ * origin hardcoded a fixed two-route guarded set (product routes with no meaning in the generic
+ * engine); here the guarded set is an injectable `ReadonlySet<string>` that defaults to empty, so
+ * installing this guard with no options is a pure inventory tap with no enforcement.
+ */
+import type { Express } from 'express';
+/** One recorded route registration: the HTTP verb and the literal string path it was mounted on. */
+export interface RouteRegistration {
+    method: string;
+    path: string;
+}
+/**
+ * Builds the `METHOD PATH` key used to check `guardedRouteKeys` membership.
+ *
+ * @param method - The Express registration method name (any case; normalized to upper-case in the key).
+ * @param path - The first argument passed to that method. Only a string path can collide — a
+ * RegExp or array-of-paths route is never tracked, matching the inventory's own string-only
+ * recording below.
+ * @param guardedRouteKeys - The set of `METHOD PATH` keys this call installed a duplicate-registration
+ * guard for.
+ * @returns The matching key if `path` is a string and the key is in `guardedRouteKeys`, otherwise `null`.
+ * @complexity O(1) — a single `Set` lookup.
+ * @overallScore 100/100
+ */
+export declare function guardedRouteKey(method: string, path: unknown, guardedRouteKeys: ReadonlySet<string>): string | null;
+export interface InstallRouteRegistrationGuardOptions {
+    /** `METHOD PATH` keys (e.g. `'POST /api/runs'`) that must be registered at most once on `app`. Defaults to none — installing the guard with no options only builds the inventory, it enforces nothing. */
+    guardedRouteKeys?: ReadonlySet<string>;
+}
+/**
+ * Monkey-patches `app`'s route-registration methods to record every string-path registration into
+ * a per-app inventory (retrievable via {@link getRouteRegistrationInventory}) and to throw if any
+ * `options.guardedRouteKeys` entry is registered a second time.
+ *
+ * @param app - The Express app to instrument. Must not already have this guard installed (installing
+ * twice would double-wrap every method and double-count the inventory — not guarded against here
+ * since `createLocalNodeDaemon` and every other caller in this codebase calls this exactly once
+ * per app at composition time).
+ * @param options.guardedRouteKeys - See {@link InstallRouteRegistrationGuardOptions}.
+ * @returns Nothing — mutates `app` in place and stashes its inventory under a well-known `Symbol.for` key.
+ * @throws If a `guardedRouteKeys` entry is registered more than once, at the moment of the second registration.
+ * @complexity O(1) setup (patches 8 fixed methods); each wrapped call is O(1) beyond the wrapped original.
+ * @overallScore 100/100
+ */
+export declare function installRouteRegistrationGuard(app: Express, options?: InstallRouteRegistrationGuardOptions): void;
+/**
+ * Reads back every route {@link installRouteRegistrationGuard} recorded for `app`.
+ *
+ * @param app - An app the guard was installed on. Safe to call on an app with no guard installed
+ * (returns an empty array rather than throwing).
+ * @returns A fresh array copy each call — the caller can never mutate the guard's own internal inventory through the returned reference.
+ * @complexity O(n) in the number of routes registered so far.
+ * @overallScore 100/100
+ */
+export declare function getRouteRegistrationInventory(app: Express): RouteRegistration[];
+//# sourceMappingURL=route-registration-guard.d.ts.map

package/dist/route-registration-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-registration-guard.d.ts","sourceRoot":"","sources":["../src/route-registration-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GACpC,MAAM,GAAG,IAAI,CAIf;AAED,MAAM,WAAW,oCAAoC;IACnD,0MAA0M;IAC1M,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,oCAAyC,GACjD,IAAI,CAyBN;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,EAAE,CAE/E"}