@jini-ai/daemon 0.3.8 → 0.5.1

package/dist/http/terminals.js

@@ -0,0 +1,325 @@
+/**
+ * @module terminals
+ *
+ * Interactive-terminal HTTP surface, mirroring OD's
+ * `apps/daemon/src/routes/terminal.ts` (`/api/projects/:id/terminals` +
+ * `.../:tid/{stream,stdin,resize,kill}`) generalized under `/api/terminals`.
+ * See `ADS-memory/reports/proposals/PROP-http-route-packs-terminal-pty-2026-07-21.md`
+ * for the design discussion and `@jini-ai/daemon`'s `terminal-session.ts` module
+ * doc for the session-ownership/gating decisions this route pack calls into.
+ *
+ * This file is deliberately thin — no PTY spawning, no session registry, no
+ * ownership logic lives here (that is `@jini-ai/daemon`'s `TerminalSessionManager`,
+ * injected as `deps.manager`). This package only:
+ *
+ * - Resolves a `POST /api/terminals` request's `resourceRef` to a spawn `cwd`
+ *   via `workspace-root.ts` (the same port `host-tools.ts`'s open-in route
+ *   uses), then routes creation through `deps.toolExecutor.execute(...,
+ *   'terminal.create', ...)` — the one call `@jini-ai/daemon`'s module gates by
+ *   policy (matching `db-ops.ts`'s tool-execution-boundary precedent).
+ * - Routes `stdin`/`resize`/`kill`/`stream` directly to `deps.manager`'s
+ *   lighter, session-ownership-checked methods — deliberately **not** through
+ *   `ToolExecutor` again (see the daemon module's doc for why a full
+ *   authorize/confirm round-trip per keystroke would make a terminal
+ *   unusable).
+ * - Adapts `deps.manager.attach`'s push/end sink to `sse.ts`'s generic SSE
+ *   channel, the same way `runs.ts` adapts `RunLifecycle.stream`.
+ */
+import { randomUUID } from 'node:crypto';
+import { TERMINAL_CREATE_TOOL_ID } from '../index.js';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
+import { guardSameOrigin } from '@jini-ai/http-kit';
+import { validationError } from '@jini-ai/http-kit';
+import { sendApiError, statusForError } from '@jini-ai/http-kit';
+import { createSseChannel, requestedAfterCursor } from '@jini-ai/http-kit';
+import { denyAllWorkspaceRoots, resolveWorkspaceRoot, WorkspaceRootDeniedError } from './workspace-root.js';
+import { err, ok } from '@jini-ai/http-kit';
+function defaultTerminalsInternalErrorSink(context) {
+    // eslint-disable-next-line no-console
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Every one-off `terminal.create` tool call gets its own opaque `RunRef` — matching `db-ops.ts`'s `freshRun()`: these are single requests, not steps of a longer-lived agent run. */
+function freshRun() {
+    return { id: randomUUID() };
+}
+function toolResultToApiResult(deps, result) {
+    switch (result.status) {
+        case 'completed':
+            return ok({ value: result.output });
+        case 'denied':
+            return err({ error: createApiError({ code: 'TOOL_OPERATION_DENIED', message: 'this operation was denied by policy' }) });
+        case 'confirmation-denied':
+            return err({ error: createApiError({ code: 'TOOL_OPERATION_DENIED', message: 'this operation was denied during confirmation' }) });
+        case 'timed-out':
+        case 'cancelled':
+        case 'failed': {
+            const correlationId = randomUUID();
+            const sink = deps.onInternalError ?? defaultTerminalsInternalErrorSink;
+            sink({ source: 'terminal-create', correlationId, error: result.status === 'failed' ? result.error : result.status });
+            return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
+        }
+    }
+}
+function parseTerminalCreate(input) {
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+    const resourceRef = input.body.resourceRef;
+    if (typeof resourceRef !== 'string' || resourceRef.length === 0) {
+        return err({ error: validationError({ message: 'resourceRef is required' }, { issues: [{ path: 'resourceRef', message: 'required non-empty string' }] }) });
+    }
+    const detail = input.body.detail;
+    if (detail !== undefined && (typeof detail !== 'string' || detail.length === 0)) {
+        return err({ error: validationError({ message: 'detail must be a non-empty string when provided' }) });
+    }
+    const cols = input.body.cols;
+    if (cols !== undefined && typeof cols !== 'number') {
+        return err({ error: validationError({ message: 'cols must be a number when provided' }) });
+    }
+    const rows = input.body.rows;
+    if (rows !== undefined && typeof rows !== 'number') {
+        return err({ error: validationError({ message: 'rows must be a number when provided' }) });
+    }
+    const shell = input.body.shell;
+    if (shell !== undefined && (typeof shell !== 'string' || shell.length === 0)) {
+        return err({ error: validationError({ message: 'shell must be a non-empty string when provided' }) });
+    }
+    return ok({
+        value: {
+            resourceRef,
+            ...(detail === undefined ? {} : { detail }),
+            ...(cols === undefined ? {} : { cols }),
+            ...(rows === undefined ? {} : { rows }),
+            ...(shell === undefined ? {} : { shell }),
+        }
+    });
+}
+/**
+ * `POST /api/terminals` — the one gated call (see module doc). Resolves
+ * `resourceRef` to a working directory the same way `host-tools.ts`'s
+ * open-in route does, then authorizes+spawns the session through
+ * `ToolExecutor.execute(..., 'terminal.create', ...)`.
+ */
+export const terminalCreateRoute = defineJsonRoute({
+    method: 'post', path: '/api/terminals', parse: parseTerminalCreate, handle: async ({ input, deps }) => {
+        let cwd;
+        try {
+            cwd = await resolveWorkspaceRoot({ request: { resourceRef: input.resourceRef, ...(input.detail === undefined ? {} : { detail: input.detail }) } }, { resolver: deps.resolveRoot ?? denyAllWorkspaceRoots });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceRootDeniedError) {
+                return err({ error: createApiError({ code: 'NOT_FOUND', message: `resource "${input.resourceRef}" was not found` }) });
+            }
+            throw error;
+        }
+        const toolInput = {
+            resourceRef: input.resourceRef,
+            cwd,
+            ...(input.cols === undefined ? {} : { cols: input.cols }),
+            ...(input.rows === undefined ? {} : { rows: input.rows }),
+            ...(input.shell === undefined ? {} : { shell: input.shell }),
+        };
+        const result = await deps.toolExecutor.execute({ principal: deps.principal, run: freshRun(), toolId: TERMINAL_CREATE_TOOL_ID, input: toolInput });
+        return toolResultToApiResult(deps, result);
+    }
+}, { requireSameOrigin: true, successStatus: 201 });
+function parseTerminalList(input) {
+    const value = input.query.resourceRef;
+    if (value === undefined)
+        return ok({ value: {} });
+    if (typeof value !== 'string' || value.length === 0) {
+        return err({ error: validationError({ message: 'resourceRef must be a non-empty string when provided' }) });
+    }
+    return ok({ value: { resourceRef: value } });
+}
+/** `GET /api/terminals` — sessions the calling principal owns, optionally narrowed by `resourceRef`. Never gated through `ToolExecutor` — a read scoped to the caller's own sessions, matching `runs.ts`'s `runListRoute` precedent. */
+export const terminalListRoute = defineJsonRoute({
+    method: 'get', path: '/api/terminals', parse: parseTerminalList, handle: ({ input, deps }) => ok({ value: { terminals: deps.manager.list({ principal: deps.principal }, { filter: input.resourceRef === undefined ? {} : { resourceRef: input.resourceRef } }) } })
+});
+function parseTerminalId(input) {
+    const id = input.params.id;
+    return typeof id === 'string' && id.length > 0 ? ok({ value: id }) : err({ error: validationError({ message: 'id must be a non-empty path parameter' }) });
+}
+/**
+ * Exported (not just internal) so the `result.session === null` branch — a real race
+ * (`write`/`resize`/`kill` finding metadata for an id whose underlying session was concurrently
+ * killed between the ownership check and the critical section, per `@jini-ai/daemon`'s
+ * `terminal-session.ts` `currentSnapshot`) — is directly unit-testable against a synthetic
+ * `TerminalSessionActionResult` rather than requiring a real, hard-to-deterministically-force race
+ * through the full `TerminalSessionManager`. Matches this file's own `createDeferredEndGate`
+ * precedent for the same "extract into a directly-testable pure function" shape.
+ */
+export function actionResultToApiResult({ result, notFoundMessage }, _optional = {}) {
+    if (result.status === 'not-found')
+        return err({ error: createApiError({ code: 'NOT_FOUND', message: notFoundMessage }) });
+    return ok({ value: { ok: result.ok, ...(result.session ? { terminal: result.session } : {}) } });
+}
+function parseStdinInput(input) {
+    const parsedId = parseTerminalId(input);
+    if (!parsedId.ok)
+        return parsedId;
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+    const data = input.body.data;
+    if (typeof data !== 'string') {
+        return err({ error: validationError({ message: 'data (string) is required' }, { issues: [{ path: 'data', message: 'required string' }] }) });
+    }
+    return ok({ value: { id: parsedId.value, data } });
+}
+/** `POST /api/terminals/:id/stdin` — writes `data` to the session's pty. Ownership-checked by `deps.manager.write` directly, not re-gated through `ToolExecutor` (see module doc). */
+export const terminalStdinRoute = defineJsonRoute({
+    method: 'post', path: '/api/terminals/:id/stdin', parse: parseStdinInput, handle: async ({ input, deps }) => {
+        const result = await deps.manager.write({ principal: deps.principal, id: input.id, input: input.data });
+        return actionResultToApiResult({ result, notFoundMessage: `terminal "${input.id}" was not found` });
+    }
+}, { requireSameOrigin: true });
+function parseResizeInput(input) {
+    const parsedId = parseTerminalId(input);
+    if (!parsedId.ok)
+        return parsedId;
+    if (!isRecord(input.body))
+        return err({ error: validationError({ message: 'body must be a JSON object' }) });
+    const cols = Number(input.body.cols);
+    const rows = Number(input.body.rows);
+    if (!Number.isFinite(cols) || !Number.isFinite(rows)) {
+        return err({ error: validationError({ message: 'cols and rows (numbers) are required' }) });
+    }
+    return ok({ value: { id: parsedId.value, cols, rows } });
+}
+/** `POST /api/terminals/:id/resize` — resizes the session's pty. */
+export const terminalResizeRoute = defineJsonRoute({
+    method: 'post', path: '/api/terminals/:id/resize', parse: parseResizeInput, handle: async ({ input, deps }) => {
+        const result = await deps.manager.resize({ principal: deps.principal, id: input.id, cols: input.cols, rows: input.rows });
+        return actionResultToApiResult({ result, notFoundMessage: `terminal "${input.id}" was not found` });
+    }
+}, { requireSameOrigin: true });
+function handleKill(id, deps) {
+    return deps.manager.kill({ principal: deps.principal, id }, { signal: 'SIGTERM' }).then((result) => actionResultToApiResult({ result, notFoundMessage: `terminal "${id}" was not found` }));
+}
+/** `POST /api/terminals/:id/kill` — sends `SIGTERM` to the session's pty. */
+export const terminalKillRoute = defineJsonRoute({ method: 'post', path: '/api/terminals/:id/kill', parse: parseTerminalId, handle: ({ input: id, deps }) => handleKill(id, deps) }, { requireSameOrigin: true });
+/** `DELETE /api/terminals/:id` — alias for `kill`, matching OD's dual `POST .../kill` / `DELETE` routes. */
+export const terminalDeleteRoute = defineJsonRoute({ method: 'delete', path: '/api/terminals/:id', parse: parseTerminalId, handle: ({ input: id, deps }) => handleKill(id, deps) }, { requireSameOrigin: true });
+/**
+ * The `channelOpened`/`endRequestedBeforeOpen` state machine `registerTerminalEventStream`'s
+ * `TerminalSseSink.end()` needs, extracted into its own directly-testable unit — see that
+ * function's inline comment for *why* the deferral exists (an already-exited session's replay
+ * path can call `end()` before `open()` has ever run).
+ *
+ * **On the `markOpened()`-then-`end()` ordering (opened=true when `end()` runs):** this is the
+ * ordering every *currently reachable* production call graph in this repo takes for a live
+ * session that exits while already streaming — but it is unreachable through that graph, not
+ * unreachable in principle. `@jini-ai/platform`'s `TerminalService.finish()` (`packages/platform/src/
+ * terminal.ts`) calls `sink.send('exit', ...)` immediately before `sink.end()` for every live
+ * client; `send()` here forwards straight to `channel.enqueue()`, whose `isEndEvent: (e) => e.kind
+ * === 'exit'` match auto-closes the channel *synchronously inside that same `enqueue()` call* —
+ * which synchronously runs `registerTerminalEventStream`'s own `channel.onClose` callback, which
+ * detaches this sink from `TerminalService`'s `session.clients` before `finish()`'s own, separate
+ * `sink.end()` loop ever runs. That loop iterates `session.clients` fresh at call time (not a
+ * snapshot taken before `emit()`), so by the time it runs, this sink has already removed itself —
+ * `sink.end()` is consequently never invoked while `channelOpened` is `true` via any call graph
+ * this repo's own `@jini-ai/platform` + `@jini-ai/daemon/http` composition can currently produce (confirmed by
+ * instrumenting the real call path directly, not inferred from reading the source — a synchronous
+ * console probe in `end()` never fired across this file's full "live-exit-while-streaming" test).
+ * That is a fact about today's specific `TerminalService`/`SseChannel` wiring, not a proof that no
+ * future caller of `TerminalSseSink` could ever call `end()` post-open (a hypothetical non-SSE
+ * sink, or a future `TerminalService` exit reason not preceded by a matching `send()`, would hit
+ * exactly this branch) — so the branch stays as real, intentional defensive code, tested directly
+ * here rather than deleted for being unreachable *today* or left silently uncovered.
+ */
+export function createDeferredEndGate({ channel }, _optional = {}) {
+    let opened = false;
+    let endRequestedBeforeOpen = false;
+    return {
+        markOpened() {
+            opened = true;
+            // Idempotent-safe even if the queued 'exit' event already auto-closed the channel via
+            // `isEndEvent` during `open()`'s own drain (`channel.end()` is documented safe to call twice).
+            if (endRequestedBeforeOpen)
+                channel.end();
+        },
+        end() {
+            if (opened) {
+                channel.end();
+            }
+            else {
+                endRequestedBeforeOpen = true;
+            }
+        },
+    };
+}
+/**
+ * `GET /api/terminals/:id/stream` — SSE, with `Last-Event-ID`/`afterCursor`
+ * reconnect replay (via `sse.ts`'s `requestedAfterCursor`, the same helper
+ * `runs.ts` uses). Adapts `deps.manager.attach`'s push/end
+ * `TerminalSseSink` to `sse.ts`'s generic channel, mirroring
+ * `registerRunEventStream`'s adaptation of `RunLifecycle.stream`.
+ *
+ * Bypasses `mountJsonRoute` (raw `app.get`, for the SSE response shape), so it does not get
+ * `requireSameOrigin` for free the way the JSON routes above do — the guard is applied here
+ * directly, before the SSE channel is opened, so a cross-origin request never gets a stream.
+ */
+export function registerTerminalEventStream({ app, deps, adapter }, _optional = {}) {
+    app.get('/api/terminals/:id/stream', (req, res) => {
+        const origin = guardSameOrigin({ req, origin: adapter });
+        if (!origin.ok) {
+            sendApiError({ res, status: statusForError({ error: origin.error }), error: origin.error });
+            return;
+        }
+        const id = req.params.id;
+        if (typeof id !== 'string' || id.length === 0) {
+            sendApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: 'id must be a non-empty path parameter' }) });
+            return;
+        }
+        const cursor = requestedAfterCursor(req);
+        const lastEventId = cursor === null ? 0 : Number(cursor);
+        const channel = createSseChannel({ res }, { isEndEvent: ({ event }) => event.kind === 'exit' });
+        // `deps.manager.attach` can call `sink.end()` synchronously, from inside the very call below
+        // (an already-exited session's replay path) — before the channel has ever been `open()`ed. If
+        // `end()` mapped straight to `channel.end()`, that would end the response with the queued
+        // backlog never flushed (headers never even sent). `createDeferredEndGate` defers the actual
+        // `channel.end()` call until after `open()` has drained whatever `send()` already queued — see
+        // that function's own doc for the full reachability analysis of its other branch.
+        const deferredEnd = createDeferredEndGate({ channel });
+        const sink = {
+            send(event, data, eventId) {
+                channel.enqueue({ event: { opaqueCursor: String(eventId), kind: event, data } });
+            },
+            end() {
+                deferredEnd.end();
+            },
+        };
+        let attachedSink = null;
+        channel.onClose({
+            callback: () => {
+                if (attachedSink)
+                    deps.manager.detach({ id, sink: attachedSink });
+            }
+        });
+        const result = deps.manager.attach({ principal: deps.principal, id, lastEventId, sink });
+        if (result === 'not-found') {
+            channel.abandon();
+            sendApiError({ res, status: 404, error: createApiError({ code: 'NOT_FOUND', message: `terminal "${id}" was not found` }) });
+            return;
+        }
+        if (result === 'attached') {
+            attachedSink = sink;
+        }
+        channel.open();
+        deferredEnd.markOpened();
+    });
+}
+/** Mounts every terminal route (`list`/`create`/`stdin`/`resize`/`kill`/`delete`/`stream`) on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerTerminalRoutes({ app, deps, adapter }, _optional = {}) {
+    mountJsonRoute({ app, spec: terminalListRoute, deps, adapter });
+    mountJsonRoute({ app, spec: terminalCreateRoute, deps, adapter });
+    mountJsonRoute({ app, spec: terminalStdinRoute, deps, adapter });
+    mountJsonRoute({ app, spec: terminalResizeRoute, deps, adapter });
+    mountJsonRoute({ app, spec: terminalKillRoute, deps, adapter });
+    mountJsonRoute({ app, spec: terminalDeleteRoute, deps, adapter });
+    registerTerminalEventStream({ app, deps, adapter });
+}
+//# sourceMappingURL=terminals.js.map

package/dist/http/tool-catalog.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module tool-catalog
+ *
+ * `GET /api/tools/search` / `GET /api/tools/:id` — the discovery half of
+ * `ai-control-plane.md` §29 / `PROP-tool-catalog-discovery-2026-07-26.md` §6.1's staged verbs
+ * (`search_tools`/`describe_tool`), v0 scope: no principal scoping, no versioning, no schema
+ * narrowing. `@jini-ai/mcp`'s `search_tools`/`describe_tool` tool defs proxy these two routes,
+ * exactly mirroring how `run-tools.ts`'s tools proxy `runs.ts`.
+ *
+ * This module does not depend on `@jini-ai/sqlite-chat` or `better-sqlite3` — `ToolCatalogQuery` is a
+ * plain injected interface, structurally compatible with `@jini-ai/sqlite-chat`'s
+ * `searchToolCatalog`/`getToolCatalogEntry` so a caller wires those in with zero adapter code,
+ * matching `db-ops.ts`'s established convention.
+ *
+ * **Deliberately not routed through `ToolExecutor`.** Unlike `db-ops.ts`'s three tools, nothing
+ * here executes a handler or has a side effect — it is a read over a snapshot table. `PROP` §6.3:
+ * "discovery is not permission... the catalog is never consulted for authorization." The actual
+ * gate is still `ToolExecutor`, reached only via `execute_delegated_tool`
+ * (`packages/daemon/src/delegated-tool-bridge.ts`) — finding a tool id here grants nothing.
+ */
+import type { Express } from 'express';
+import { type AdapterContext } from '@jini-ai/http-kit';
+export interface ToolCatalogSearchHit {
+    readonly id: string;
+    readonly description: string;
+    readonly source: string;
+    readonly score: number;
+}
+export interface ToolCatalogEntry {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema?: unknown;
+    readonly source: string;
+}
+/** Structurally identical to `@jini-ai/sqlite-chat`'s `searchToolCatalog`/`getToolCatalogEntry` — defined locally so this package incurs no `better-sqlite3` dependency. */
+export interface ToolCatalogQuery {
+    readonly search: ({ query }: {
+        readonly query: string;
+    }, optionalArgs?: {
+        readonly limit?: number | undefined;
+    }) => readonly ToolCatalogSearchHit[];
+    readonly describe: ({ id }: {
+        readonly id: string;
+    }, _optional?: Record<string, never>) => ToolCatalogEntry | null;
+}
+export interface ToolCatalogHttpDeps {
+    readonly catalog: ToolCatalogQuery;
+}
+/** `GET /api/tools/search?q=...&limit=...` — ranked candidates only, never schemas (`PROP` §6.1). */
+export declare const toolCatalogSearchRoute: import("@jini-ai/http-kit").JsonRouteSpec<{
+    query: string;
+    limit: number;
+}, {
+    hits: readonly ToolCatalogSearchHit[];
+}, ToolCatalogHttpDeps>;
+/**
+ * `GET /api/tools/:id` — full descriptor (schema included), paid for only once a candidate survives
+ * search.
+ *
+ * An unknown tool id is **404 `NOT_FOUND`**, not 400. A well-formed request naming a catalog entry
+ * that does not exist is a missing resource, not a malformed request — and the three sibling route
+ * families in this package that have the same "the referenced thing isn't there" case
+ * (`memory.ts`'s `memory not found`, `routines.ts`'s `routine not found`, `media.ts`'s
+ * `media task not found`) all already answer 404. This route answered 400 until 2026-07-29 purely
+ * because it reached for `validationError` — the same helper its `parse` step uses, where 400 *is*
+ * correct — so a caller could not distinguish "you sent a bad request" from "that tool is gone".
+ * `parse` failures here (a missing `:id` segment) are still 400.
+ */
+export declare const toolCatalogDescribeRoute: import("@jini-ai/http-kit").JsonRouteSpec<{
+    id: string;
+}, ToolCatalogEntry, ToolCatalogHttpDeps>;
+/** Mounts both tool-catalog routes on `app`. A pack's `http({ app, services })` calls this directly. */
+export declare function registerToolCatalogRoutes({ app, deps, adapter }: {
+    readonly app: Express;
+    readonly deps: ToolCatalogHttpDeps;
+    readonly adapter: AdapterContext;
+}, _optional?: Record<string, never>): void;
+//# sourceMappingURL=tool-catalog.d.ts.map

package/dist/http/tool-catalog.js

@@ -0,0 +1,66 @@
+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 MAX_SEARCH_LIMIT = 25;
+const DEFAULT_SEARCH_LIMIT = 10;
+function parseSearchInput(input) {
+    const rawQuery = input.query.q;
+    if (typeof rawQuery !== 'string' || rawQuery.trim().length === 0) {
+        return err({ error: validationError({ message: 'q (search query) is required and must be a non-empty string' }) });
+    }
+    const rawLimit = input.query.limit;
+    if (rawLimit === undefined)
+        return ok({ value: { query: rawQuery, limit: DEFAULT_SEARCH_LIMIT } });
+    if (typeof rawLimit !== 'string' || !/^[0-9]+$/.test(rawLimit)) {
+        return err({ error: validationError({ message: 'limit must be a single positive-integer query-string value when provided' }) });
+    }
+    const parsed = Number(rawLimit);
+    if (parsed < 1)
+        return err({ error: validationError({ message: 'limit must be at least 1' }) });
+    return ok({ value: { query: rawQuery, limit: Math.min(parsed, MAX_SEARCH_LIMIT) } });
+}
+/** `GET /api/tools/search?q=...&limit=...` — ranked candidates only, never schemas (`PROP` §6.1). */
+export const toolCatalogSearchRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/tools/search',
+    parse: parseSearchInput,
+    handle: ({ input, deps }) => ok({ value: { hits: deps.catalog.search({ query: input.query }, { limit: input.limit }) } }),
+}, { requireSameOrigin: true });
+function parseDescribeInput(input) {
+    const id = input.params.id;
+    if (typeof id !== 'string' || id.length === 0) {
+        return err({ error: validationError({ message: 'id path segment is required' }) });
+    }
+    return ok({ value: { id } });
+}
+/**
+ * `GET /api/tools/:id` — full descriptor (schema included), paid for only once a candidate survives
+ * search.
+ *
+ * An unknown tool id is **404 `NOT_FOUND`**, not 400. A well-formed request naming a catalog entry
+ * that does not exist is a missing resource, not a malformed request — and the three sibling route
+ * families in this package that have the same "the referenced thing isn't there" case
+ * (`memory.ts`'s `memory not found`, `routines.ts`'s `routine not found`, `media.ts`'s
+ * `media task not found`) all already answer 404. This route answered 400 until 2026-07-29 purely
+ * because it reached for `validationError` — the same helper its `parse` step uses, where 400 *is*
+ * correct — so a caller could not distinguish "you sent a bad request" from "that tool is gone".
+ * `parse` failures here (a missing `:id` segment) are still 400.
+ */
+export const toolCatalogDescribeRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/tools/:id',
+    parse: parseDescribeInput,
+    handle: ({ input, deps }) => {
+        const entry = deps.catalog.describe({ id: input.id });
+        if (!entry)
+            return err({ error: createApiError({ code: 'NOT_FOUND', message: `no catalog entry for tool id "${input.id}"` }) });
+        return ok({ value: entry });
+    },
+}, { requireSameOrigin: true });
+/** Mounts both tool-catalog routes on `app`. A pack's `http({ app, services })` calls this directly. */
+export function registerToolCatalogRoutes({ app, deps, adapter }, _optional = {}) {
+    mountJsonRoute({ app, spec: toolCatalogSearchRoute, deps, adapter });
+    mountJsonRoute({ app, spec: toolCatalogDescribeRoute, deps, adapter });
+}
+//# sourceMappingURL=tool-catalog.js.map

package/dist/http/workspace-root.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Generic, host-injectable "workspace root" resolution port.
+ *
+ * Several OD route packs need the same thing at the boundary: "given some
+ * opaque resource reference, what filesystem directory does a spawned
+ * process or launched editor run in?" OD answers that with
+ * `ctx.projectStore.getProject` + `ctx.projectFiles.resolveProjectDir` — a
+ * project-store lookup plus a metadata-driven directory resolver, both
+ * product-specific (see `packages/http/archived provenance ledger`'s routes-classification
+ * table, rows `#11 terminal.ts` and `#23 host-tools.ts`, both of which name
+ * exactly this dependency as the reason `POST /api/projects/:id/open-in` and
+ * the interactive-terminal spawn route were not ported earlier). The kernel
+ * has no concept of "project," so it cannot hardcode that lookup — but it
+ * also must not silently invent a directory (guessing `process.cwd()` or an
+ * OS temp dir would let one request's resource reference leak into an
+ * unrelated working directory).
+ *
+ * Follows the same explicit-injection, conservative-default shape this repo
+ * already established for `@jini-ai/cli`'s `resolveDaemonUrl`
+ * (`packages/cli/src/daemon-url.ts`): a host supplies a resolver callback; the
+ * built-in default resolves nothing and the resolution function throws
+ * rather than guessing. It also mirrors `active-context.ts`'s
+ * `resolveResource` DI shape (a caller-supplied lookup replacing OD's
+ * `getProject`) and its `resourceRef`/`detail` field naming.
+ */
+/** What a route needs resolved: an opaque resource reference, plus an optional sub-locator within it (e.g. a specific file), matching `active-context.ts`'s `resourceRef`/`detail` naming. */
+export interface WorkspaceRootRequest {
+    readonly resourceRef: string;
+    readonly detail?: string | null;
+}
+/**
+ * Host-supplied lookup: given a {@link WorkspaceRootRequest}, return the
+ * absolute filesystem path a process/editor should be rooted at, or a
+ * nullish value when this host has no directory for that resource (an
+ * unknown id, a resource with no on-disk representation, or a caller not
+ * permitted to resolve it — the resolver decides, the kernel does not).
+ */
+export type WorkspaceRootResolver = (requiredArgs: {
+    readonly request: WorkspaceRootRequest;
+}) => string | null | undefined | Promise<string | null | undefined>;
+/** Thrown by {@link resolveWorkspaceRoot} when no root could be resolved — the caller has nothing safe to spawn a process or open an editor against. */
+export declare class WorkspaceRootDeniedError extends Error {
+    readonly resourceRef: string;
+    constructor({ resourceRef }: {
+        readonly resourceRef: string;
+    }, { reason }?: {
+        readonly reason?: string | undefined;
+    });
+}
+/**
+ * The built-in, zero-config default resolver: resolves nothing, for every
+ * request. A host that never wires its own resolver gets a hard denial from
+ * every call site that needs a workspace root — never a guessed path. This
+ * is the "conservative default that denies rather than guessing" half of
+ * the port, matching the task's explicit precedent
+ * (`ToolPolicy`/`resolveDaemonUrl`).
+ */
+export declare const denyAllWorkspaceRoots: WorkspaceRootResolver;
+export interface ResolveWorkspaceRootOptions {
+    /** Defaults to {@link denyAllWorkspaceRoots} — a host must explicitly opt in to resolving real paths. */
+    readonly resolver?: WorkspaceRootResolver;
+}
+/**
+ * Resolves a workspace root for `request` via `options.resolver`.
+ *
+ * @throws {WorkspaceRootDeniedError} If the resolver is omitted, or returns
+ * `null`/`undefined`/an empty string. This function never falls back to a
+ * guessed path (`process.cwd()`, an OS temp dir, `resourceRef` itself
+ * treated as a path) — a route that cannot resolve a real root has nothing
+ * safe to act on.
+ * @complexity O(1) plus the injected resolver's own cost.
+ * @overallScore 100/100
+ */
+export declare function resolveWorkspaceRoot({ request }: {
+    readonly request: WorkspaceRootRequest;
+}, options?: ResolveWorkspaceRootOptions): Promise<string>;
+//# sourceMappingURL=workspace-root.d.ts.map

package/dist/http/workspace-root.js

@@ -0,0 +1,63 @@
+/**
+ * Generic, host-injectable "workspace root" resolution port.
+ *
+ * Several OD route packs need the same thing at the boundary: "given some
+ * opaque resource reference, what filesystem directory does a spawned
+ * process or launched editor run in?" OD answers that with
+ * `ctx.projectStore.getProject` + `ctx.projectFiles.resolveProjectDir` — a
+ * project-store lookup plus a metadata-driven directory resolver, both
+ * product-specific (see `packages/http/archived provenance ledger`'s routes-classification
+ * table, rows `#11 terminal.ts` and `#23 host-tools.ts`, both of which name
+ * exactly this dependency as the reason `POST /api/projects/:id/open-in` and
+ * the interactive-terminal spawn route were not ported earlier). The kernel
+ * has no concept of "project," so it cannot hardcode that lookup — but it
+ * also must not silently invent a directory (guessing `process.cwd()` or an
+ * OS temp dir would let one request's resource reference leak into an
+ * unrelated working directory).
+ *
+ * Follows the same explicit-injection, conservative-default shape this repo
+ * already established for `@jini-ai/cli`'s `resolveDaemonUrl`
+ * (`packages/cli/src/daemon-url.ts`): a host supplies a resolver callback; the
+ * built-in default resolves nothing and the resolution function throws
+ * rather than guessing. It also mirrors `active-context.ts`'s
+ * `resolveResource` DI shape (a caller-supplied lookup replacing OD's
+ * `getProject`) and its `resourceRef`/`detail` field naming.
+ */
+/** Thrown by {@link resolveWorkspaceRoot} when no root could be resolved — the caller has nothing safe to spawn a process or open an editor against. */
+export class WorkspaceRootDeniedError extends Error {
+    resourceRef;
+    constructor({ resourceRef }, { reason } = {}) {
+        super(reason ?? `no workspace root available for resource "${resourceRef}"`);
+        this.name = 'WorkspaceRootDeniedError';
+        this.resourceRef = resourceRef;
+    }
+}
+/**
+ * The built-in, zero-config default resolver: resolves nothing, for every
+ * request. A host that never wires its own resolver gets a hard denial from
+ * every call site that needs a workspace root — never a guessed path. This
+ * is the "conservative default that denies rather than guessing" half of
+ * the port, matching the task's explicit precedent
+ * (`ToolPolicy`/`resolveDaemonUrl`).
+ */
+export const denyAllWorkspaceRoots = () => null;
+/**
+ * Resolves a workspace root for `request` via `options.resolver`.
+ *
+ * @throws {WorkspaceRootDeniedError} If the resolver is omitted, or returns
+ * `null`/`undefined`/an empty string. This function never falls back to a
+ * guessed path (`process.cwd()`, an OS temp dir, `resourceRef` itself
+ * treated as a path) — a route that cannot resolve a real root has nothing
+ * safe to act on.
+ * @complexity O(1) plus the injected resolver's own cost.
+ * @overallScore 100/100
+ */
+export async function resolveWorkspaceRoot({ request }, options = {}) {
+    const resolver = options.resolver ?? denyAllWorkspaceRoots;
+    const root = await resolver({ request });
+    if (typeof root !== 'string' || root.length === 0) {
+        throw new WorkspaceRootDeniedError({ resourceRef: request.resourceRef });
+    }
+    return root;
+}
+//# sourceMappingURL=workspace-root.js.map