@jini-ai/mcp 0.4.1 → 0.4.2

package/dist/core/secure-write.js

@@ -0,0 +1,72 @@
+/**
+ * @module @jini-ai/mcp/core/secure-write
+ * Shared atomic, owner-only-permission (0600) secret-file writer used by
+ * every secret-bearing on-disk store in this package: the server config
+ * store (env vars / `Authorization` headers), the OAuth dynamic-client-
+ * registration cache (`clientSecret`), and the OAuth token store (bearer /
+ * refresh tokens, confidential-client secrets). CR-006 / SEC-RB-002.
+ *
+ * The previous pattern in each of those stores wrote the temp file with
+ * default permissions and either never restricted it (config, OAuth client
+ * cache) or `chmod(0600)`'d it *after* the atomic rename and silently
+ * continued when the chmod failed (tokens) — both leave a window where the
+ * file exists world/group-readable, and the latter makes the "protection"
+ * advisory rather than enforced. This writer instead:
+ *
+ *   1. Creates the temp file *exclusively* (`wx`) with mode 0600 supplied to
+ *      the same `open()`/`writeFile()` call that creates it — POSIX applies
+ *      the requested mode atomically at creation time, so there is no
+ *      window where the file exists with a broader mode. This repo already
+ *      relies on `writeFile`'s `mode` option alone for a secret file with no
+ *      separate chmod step (see `packages/agent-runtime/src/prompt-file.ts`);
+ *      this module follows that same precedent rather than inventing a new one.
+ *   2. On POSIX platforms, verifies the on-disk mode actually landed as
+ *      owner-only before renaming into place, and fails closed — removing
+ *      the temp file and throwing — if it did not (e.g. an unusual umask or
+ *      a filesystem that doesn't honor `mode`).
+ *   3. Skips that verification on `win32`: Windows has no POSIX permission-
+ *      bit model (`mode` there only toggles the read-only attribute), so
+ *      there is nothing meaningful to enforce or fail closed on — matching
+ *      this repo's only other cross-platform file-mode precedent, which
+ *      also does not branch on Windows.
+ *
+ * Part of the MCP `core` kernel; not part of the package's public barrel —
+ * imported directly by sibling `core/*.ts` files.
+ */
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+const SECRET_FILE_MODE = 0o600;
+/**
+ * Atomically write `contents` to `finalPath` via a same-directory temp file
+ * created exclusively with mode 0600. On POSIX platforms, verifies no
+ * group/other permission bit made it onto disk before renaming into place;
+ * throws (after removing the temp file) if verification fails or the write
+ * itself fails, so a caller never observes a partially-written or
+ * insufficiently-restricted secret file.
+ * @param finalPath Absolute path the secret file should end up at.
+ * @param contents UTF-8 text to write.
+ * @param options `platform` override for tests; defaults to `process.platform`.
+ */
+export async function writeSecretFileAtomic(finalPath, contents, options = {}) {
+    const platform = options.platform ?? process.platform;
+    await mkdir(path.dirname(finalPath), { recursive: true });
+    const tmp = `${finalPath}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        await writeFile(tmp, contents, { encoding: 'utf8', mode: SECRET_FILE_MODE, flag: 'wx' });
+        if (platform !== 'win32') {
+            const info = await stat(tmp);
+            const bits = info.mode & 0o777;
+            if ((bits & 0o077) !== 0) {
+                throw new Error(`refusing to persist secret-bearing file with non-owner-only permissions ` +
+                    `(mode 0${bits.toString(8)}): ${finalPath}`);
+            }
+        }
+        await rename(tmp, finalPath);
+    }
+    catch (err) {
+        await rm(tmp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+//# sourceMappingURL=secure-write.js.map

package/dist/federation/ports.d.ts

@@ -1,3 +1,28 @@
+/**
+ * @file The typed boundary for OUTBOUND MCP federation: the host daemon acting as a client of
+ * third-party servers. Inbound MCP injection hands an agent access to the host's own catalog;
+ * outbound federation accepts another party's tool surface, so its trust question is different.
+ *
+ * Why a declared port rather than `@modelcontextprotocol/sdk`: the SDK is not a dependency and
+ * would add a transitive tree to the boot path for a small JSON-RPC surface. A real adapter and
+ * a memory double share one interface instead.
+ *
+ * Layered seams are deliberate. McpSessionPort is the outer seam for trust and registration tests
+ * without protocol I/O. McpStdioChannel and McpHttpExchange are the inner seams, so the real
+ * client's framing, handshake, pagination, cancellation and timeouts run against scripted bytes.
+ * A fake at the outer seam alone would test the fake, which would not satisfy the constraint of
+ * exercising protocol behavior without a live third-party server. Both transports share protocol
+ * logic above those seams; adding a hosted transport does not redesign the federation boundary.
+ *
+ * All remote names, descriptions, schemas, annotations and results are untrusted input. These
+ * declarations type them; trust.ts vets them before they reach a registry or model.
+ */
+/**
+ * Remote behavior hints are self-declared by the party being classified. A host's native risk
+ * catalog refuses to let a tool downgrade its own risk by editing one word; letting a remote
+ * server change its annotations would make the same mistake with a party the host cannot control.
+ * Hints are carried and logged, but trust.ts only lets them make a tool LESS available, never more.
+ */
 export interface RemoteToolAnnotations {
     readonly title?: string | undefined;
     readonly readOnlyHint?: boolean | undefined;

package/dist/federation/ports.js

@@ -1,3 +1,22 @@
+/**
+ * @file The typed boundary for OUTBOUND MCP federation: the host daemon acting as a client of
+ * third-party servers. Inbound MCP injection hands an agent access to the host's own catalog;
+ * outbound federation accepts another party's tool surface, so its trust question is different.
+ *
+ * Why a declared port rather than `@modelcontextprotocol/sdk`: the SDK is not a dependency and
+ * would add a transitive tree to the boot path for a small JSON-RPC surface. A real adapter and
+ * a memory double share one interface instead.
+ *
+ * Layered seams are deliberate. McpSessionPort is the outer seam for trust and registration tests
+ * without protocol I/O. McpStdioChannel and McpHttpExchange are the inner seams, so the real
+ * client's framing, handshake, pagination, cancellation and timeouts run against scripted bytes.
+ * A fake at the outer seam alone would test the fake, which would not satisfy the constraint of
+ * exercising protocol behavior without a live third-party server. Both transports share protocol
+ * logic above those seams; adding a hosted transport does not redesign the federation boundary.
+ *
+ * All remote names, descriptions, schemas, annotations and results are untrusted input. These
+ * declarations type them; trust.ts vets them before they reach a registry or model.
+ */
 /** Narrows a {@link McpLaunchSpec} to its hosted arm. */
 export function isHttpLaunchSpec(input) {
     return "url" in input.spec;

package/dist/federation/testing/adapter.memory.d.ts

@@ -50,16 +50,17 @@ export declare class InMemoryMcpSession implements McpSessionPort {
     constructor({ tools }: {
         tools: readonly RemoteToolDescriptor[];
     }, options?: {
-        /** Defaults to echoing the call back, which is enough for most wiring assertions. */
+        /** Defaults to echoing the call back, which is enough for most wiring assertions.
+         * The injected remote receives the same optional cancellation object as a real session. */
         onCall?: ((required: {
             name: string;
             args: Record<string, unknown>;
-        }) => RemoteToolResult | Promise<RemoteToolResult>) | undefined;
+        }, options?: McpToolCallOptions) => RemoteToolResult | Promise<RemoteToolResult>) | undefined;
         /** Overrides `listTools` wholesale, for the "the remote is down at connect time" cases. */
         onListTools?: (() => Promise<RemoteToolDescriptor[]>) | undefined;
     });
     listTools(): Promise<RemoteToolDescriptor[]>;
-    callTool(request: McpToolCallRequiredArgs, _options?: McpToolCallOptions): Promise<RemoteToolResult>;
+    callTool(request: McpToolCallRequiredArgs, options?: McpToolCallOptions): Promise<RemoteToolResult>;
     close(_required: Record<string, never>): Promise<void>;
 }
 /** One JSON-RPC message the fake channel received from the client under test. */

package/dist/federation/testing/adapter.memory.js

@@ -51,9 +51,10 @@ export class InMemoryMcpSession {
             return this.listToolsBehaviour();
         return [...this.tools];
     }
-    async callTool(request, _options = {}) {
+    async callTool(request, options = {}) {
         this.calls.push({ name: request.name, arguments: request.arguments });
-        return this.handler({ name: request.name, args: request.arguments });
+        // The injected remote must see cancellation too, so wiring tests can exercise the real ABI.
+        return this.handler({ name: request.name, args: request.arguments }, options);
     }
     async close(_required) {
         this.closed = true;

package/dist/federation/testing/tool-approvals.memory.js

@@ -30,6 +30,14 @@ export function createInMemoryConversationToolApprovalStore(_required) {
         async has(key) {
             return rows.get(keyOf(key)) === key.fingerprint;
         },
+        async hasIdentity(key) {
+            for (const [encoded, fingerprint] of rows) {
+                const [, principalId, connectionId, toolName] = JSON.parse(encoded);
+                if (principalId === key.principalId && connectionId === key.connectionId && toolName === key.toolName && fingerprint === key.fingerprint)
+                    return true;
+            }
+            return false;
+        },
         async grant({ key }) {
             rows.set(keyOf(key), key.fingerprint);
         },

package/dist/federation/tool-approvals.d.ts

@@ -89,6 +89,9 @@ export interface ConversationToolApprovalKey {
 export interface ConversationToolApprovalStore {
     /** True only for this conversation AND this person AND this exact fingerprint. */
     has(key: ConversationToolApprovalKey): Promise<boolean>;
+    /** Native escalation consent can outlive the invoking chat, while remaining person/identity bound.
+     * Hosts namespace connectionId by workspace and behavior; deletion of all granting chats revokes it. */
+    hasIdentity?(key: Omit<ConversationToolApprovalKey, "conversationId">): Promise<boolean>;
     grant(input: {
         key: ConversationToolApprovalKey;
         grantedAt: string;

package/dist/index.d.ts

@@ -1,180 +1,9 @@
 /**
  * @module @jini-ai/mcp
- * Public barrel for the MCP (Model Context Protocol) domain. External code
- * imports MCP capabilities only from here — never from a subdirectory — so the
- * internal split (`core` kernel + `client` / `agent-install` concerns) can move
- * without touching consumers.
- *
- * Re-exports are explicit and named (no `export *`) so the public surface is
- * visible here and name collisions surface at build time.
-
- * Archived provenance rationale:
- * ## What was dropped (and why)
- *
- * - **`live-artifacts/` (entire subdir)** — the OD per-run "live artifacts" MCP
- *   tool surface. An OD-product feature, out of scope per the port brief.
- * - **The `od mcp` stdio server** in `client/client.ts` — `runMcpStdio`,
- *   `TOOL_DEFS`, `handleMcpToolCall`, and every tool handler (`get_artifact`,
- *   `create_project`, `start_run`, project/active-context resolution, studio deep
- *   links, run polling, …). This is not a generic MCP client: it is an
- *   OD-product MCP **server** hardwired to Open Design's REST API
- *   (`/api/projects`, `/api/skills`, `/api/design-systems`, `/api/runs`, …) and
- *   concepts (design systems, skills, plugins, artifacts, runs, studio, the
- *   `od://` resource scheme). It also imports the OD-only `@open-design/contracts`
- *   package (`buildProjectRawFileUrl`), the OD daemon-internal
- *   `../../artifacts/create.js`, and the `@modelcontextprotocol/sdk` — none of
- *   which exist in this repo. Faithfully porting it would mean importing OD
- *   product surface, so it was dropped and only its generic primitives salvaged.
- * - **`MCP_TEMPLATES` catalog + template types + `templateId`** in `config.ts` —
- *   a large, design-tool-tilted curated catalog of third-party MCP servers with
- *   OD marketing prose. Zero functional coupling; dropped for neutrality (same
- *   rationale `@jini/sqlite` used to drop the OD "templates" table).
- *
- * ### The `list_agents` decision
- *
- * Investigated before building anything, per the task brief. `@jini/agent-runtime`'s
- * barrel (`packages/agent-runtime/src/index.ts` → `export * from './registry.js'`)
- * already exports `AGENT_DEFS: RuntimeAgentDef[]` — the exact static, in-memory
- * list of every registered agent def (`registry.ts`'s `BASE_AGENT_DEFS`, 24
- * entries). `RuntimeAgentDef` has plain `id`/`name` fields (plus a large surface
- * of CLI-spawn internals: `bin`, `buildArgs`, `env`, `listModels`, etc. — no
- * `available`/live-detection field at all). No HTTP projection of this list
- * existed anywhere in `packages/http/src/*.ts` before this pass. Building
- * `GET /api/agents` returning `{agents: [{id, name}]}` needed no design judgment
- * call beyond "project the two safe fields" — no timeout/caching/probing
- * decisions, unlike OD's own `list_agents` (`listAgents`, mcp.ts:1034-1057),
- * which filters on a *live-detected* `available: boolean` field (OD's
- * `/api/agents` route actually probes each agent binary for installation/version
- * at request time — a real design decision this pass deliberately did not need
- * to make, since Jini has no such probing route or field to project). So it was
- * built: `packages/http/src/agents.ts`'s `agentListRoute` (`GET /api/agents`,
- * `AgentsHttpDeps.listAgents: () => readonly {id, name}[]` injected — DI,
- * matching `daemon-status.ts`/`active-context.ts`'s convention, so `@jini/http`
- * does not take on a new `@jini/agent-runtime` package dependency for a
- * two-field projection) plus `@jini/mcp`'s `list_agents` tool
- * (`server/tools/run-tools.ts`) proxying it. OD's `includeUnavailable` flag and
- * per-agent `installUrl`/`modelsCount` enrichment were **not** ported — those
- * exist only because OD's route does live probing, which this pass's route does
- * not attempt.
- *
- * ### What was explicitly excluded (and why)
- *
- * Per the task brief, only the mechanism plus tools mapping to real kernel
- * primitives were ported. The other 13 of OD's 18 `TOOL_DEFS` were **not**
- * ported — all are OD's project/file/artifact/skill/plugin model, none of which
- * exists in the Jini kernel (extraction-plan §2.1's "no Project, Conversation,
- * Brand, DesignSystem, Plugin/marketplace, or Automation noun" holds here
- * exactly as it did for `@jini/cli`'s own `mcp` row):
- * `list_projects`, `get_artifact`, `get_project`, `get_file`, `search_files`,
- * `list_files`, `create_artifact`, `write_file`, `delete_file`, `delete_project`,
- * `create_project`, `list_skills`, `list_plugins`. Also not ported: the
- * `ListResourcesRequestSchema`/`ReadResourceRequestSchema` resource surface
- * (`od://focus/active`, `od://skills/...`, `od://design-systems/...` — resources
- * require a skill/design-system store this kernel doesn't have), the studio
- * deep-link builder (`buildStudioUrl`, `getDefaultConversationId`,
- * `getWebBaseUrl`), the project-name-resolution cache (`resolveProjectId`,
- * `fetchProjectList`, `resolveProjectArg`), and the SSE-transcript reassembly
- * (`fetchRunAgentMessage`) — every one of these exists only in service of a
- * dropped tool.
- *
- * ### Design decision: the hosting-mechanism shape
- *
- * `createMcpToolServer({name, version, tools, resolveBaseUrl, instructions?,
- * idleMs?, fetchImpl?, stdin?, stdout?, createServer?, createTransport?})`
- * returns `{run(): Promise<void>}`. Construction (tool-name-uniqueness
- * validation via `buildToolIndex`) is synchronous and side-effect-free; all I/O
- * — resolving the daemon URL, connecting the transport, serving requests —
- * happens in `run()`. This is genuinely new kernel-adjacent surface (a new
- * package capability, not a file port), justified per extraction-plan §7's
- * two-consumer rule by the user's explicit request plus the stated expectation
- * that Zana/Open-Marketing will each want their own product-specific MCP
- * server built on the same hosting mechanism later — so the mechanism accepts
- * an arbitrary, caller-registered `McpToolDef[]`, not the 3-5 tools this pass
- * ships as its first real, working example.
- *
- * `McpServerLike`/`McpTransportLike` (in `tool-server.ts`) are narrow structural
- * interfaces covering only what this module calls on a `Server` instance
- * (`setRequestHandler`, `connect`) and a transport (`onmessage`, `onclose`,
- * `close`) — not literal re-exports of the SDK's own types, which can't be
- * satisfied by a plain object (the SDK's `Server` class has private fields, so
- * it's nominally, not structurally, typed). The default `createServer`/
- * `createTransport` factories construct the real SDK classes and cast through
- * `unknown` to these narrower interfaces (the same `as unknown as X` pattern
- * `core/oauth.ts` already uses to bridge undici's types); a caller may override
- * either factory to inject a test double. This is what makes `run()`'s full
- * orchestration — activity wrapping, message/close composition, the stdin-close
- * race, idle-triggered shutdown — deterministically unit-testable without a
- * real subprocess or real timers (see `tool-server.test.ts`), while one
- * dedicated test (`'wires the real @modelcontextprotocol/sdk Server +
- * StdioServerTransport when no factories are injected'`) still exercises the
- * true default path end-to-end with real `node:stream` `PassThrough` streams,
- * proving the DI seam isn't hiding a real-SDK integration bug.
- *
- * **Why `daemon-client.ts` is not `@jini/cli`'s `getJsonFromDaemon`/
- * `postJsonToDaemon`.** The architectural brief called for reusing
- * `@jini/cli`'s already-hardened daemon-fetch helpers "the way
- * `packages/cli/src/run-command.ts` already does." Checked directly: those two
- * functions map every failure — network-unreachable, non-2xx, oversized
- * response — onto `process.exit()` (via `exitWithStructuredError`), which is
- * correct for a one-shot CLI invocation but fatal for a long-lived stdio MCP
- * server, where a single failed tool call must return an `{isError:true}` MCP
- * result and the process must keep serving the next call. Routing around this
- * by injecting an `exit` callback that throws instead of exiting was considered
- * and rejected: it would require also capturing/re-parsing whatever
- * `postJsonToDaemon` had already written through its `write` callback to
- * reconstruct an error message, which is more convoluted than porting OD's own
- * already-throw-based `getJson`/`postJson` mechanism with the same bounded-I/O
- * hardening added. What **is** reused directly from `@jini/cli` (both pure,
- * non-`process.exit` functions): `sanitizeUntrustedText` (redacts daemon-
- * supplied error text before it reaches an MCP result) and, per the
- * architecture note about `daemon-url.ts`, `resolveDaemonUrl`/
- * `sanitizeDaemonUrlForDisplay` are available for a caller's `resolveBaseUrl`
- * implementation to use directly (this package does not re-wrap them — a
- * caller passes `() => resolveDaemonUrl({...})` straight into
- * `createMcpToolServer`'s `resolveBaseUrl` option; no `packages/mcp`-local
- * daemon-URL-resolution equivalent was built, since one already exists and nothing
- * about MCP's use case differs from a CLI command's). This cross-import
- * (`@jini/mcp` -> `@jini/cli`) is allowed by `scripts/check-engine-boundaries.ts`'s
- * R7 rule: R7 only restricts a **locked** package (the extraction-plan §3
- * fourteen) importing an **unlocked** one below `"stable"` status; `@jini/mcp`
- * is itself unlocked (`UNLOCKED.md`), so it importing the locked, stable
- * `@jini/cli` package is unrestricted. Confirmed via `pnpm guard` after wiring
- * the dependency (see below) — zero violations.
- *
- * No SSRF hardening (`assertSafePublicUrl`/`createValidatingLookup`, the
- * pattern `core/oauth.ts` uses for its own outbound fetches) was added to
- * `daemon-client.ts` — deliberately: `assertSafePublicUrl` actively *rejects*
- * loopback/private addresses, which is exactly where a real daemon lives. The
- * daemon URL here is a caller-resolved, typically-loopback target the user
- * already trusts enough to run (the same trust boundary `@jini/cli/http.ts`
- * already accepts for the identical "fetch my own daemon" concern), not an
- * attacker- or remote-metadata-controlled URL the way an external MCP server's
- * OAuth endpoints are.
- *
- * ### `daemonCallOptions(ctx)` — why a helper for two fields
- *
- * Nine call sites across `tools/` and `resources/` each wrote `{ fetchImpl: ctx.fetchImpl }` inline. Adding
- * a second field that must travel with the first creates a failure mode that is *not* a compile error: miss
- * one site and that single tool 401s while its neighbours keep working, which reaches a user as "some of
- * these tools just don't do anything". Every site now routes through one mapping, so a newly added tool is
- * authenticated by construction.
- *
- * The guarantee is a test rather than a convention. `server/__tests__/auth-propagation.test.ts` enumerates
- * the **real** registries (`RUN_TOOLS`, `TOOL_CATALOG_TOOLS`, `createExecuteDelegatedToolTool`,
- * `KERNEL_RESOURCES` — 8 tools + 1 resource), drives each handler through a spy `fetch`, and asserts the
- * header on every request each one makes; a matching pass asserts **no** `Authorization` key at all when no
- * credential was issued. It also asserts the surface list itself, so emptying or renaming a registry cannot
- * make the loops vacuously pass.
- *
- * That test was verified to actually catch the bug it exists for: reverting one call site to the inline form
- * fails it, naming the offending tool and URL.
- *
- * No transport change was needed — `daemon-client.ts`'s `DaemonRequestOptions` already carried `headers`.
- *
- * **Verified, personally, this session**: `pnpm --filter @jini-ai/mcp run typecheck` clean; full suite
- * **332/332 passing** (18 files), including 21 new propagation tests and 4 new `serve()` credential tests.
- * The pre-existing tool/resource suites, which assert the exact options object passed to the daemon client,
- * pass **unmodified** — the evidence that the no-credential path is byte-identical.
+ * Import capabilities through the public barrel or declared stable subpaths; internal source
+ * paths remain private so the core/client/install/hosting split can move without consumer churn.
+ * Explicit named exports expose the public surface and catch collisions. Core binding, hosting,
+ * daemon I/O and auth propagation are documented at their respective owners below.
  */
 export { inferMcpAuthModeForUrl, sanitizeMcpServer, sanitizeMcpConfig, readMcpConfig, writeMcpConfig, isManagedProjectCwd, buildClaudeMcpJson, buildAcpMcpServers, buildOpenCodeMcpConfigContent, } from './core/index.js';
 export type { McpTransport, McpAuthMode, McpServerConfig, McpConfig, AcpMcpServer, OpenCodeConfigBuildOptions, } from './core/index.js';

package/dist/index.js

@@ -1,184 +1,10 @@
 /**
  * @module @jini-ai/mcp
- * Public barrel for the MCP (Model Context Protocol) domain. External code
- * imports MCP capabilities only from here — never from a subdirectory — so the
- * internal split (`core` kernel + `client` / `agent-install` concerns) can move
- * without touching consumers.
- *
- * Re-exports are explicit and named (no `export *`) so the public surface is
- * visible here and name collisions surface at build time.
-
- * Archived provenance rationale:
- * ## What was dropped (and why)
- *
- * - **`live-artifacts/` (entire subdir)** — the OD per-run "live artifacts" MCP
- *   tool surface. An OD-product feature, out of scope per the port brief.
- * - **The `od mcp` stdio server** in `client/client.ts` — `runMcpStdio`,
- *   `TOOL_DEFS`, `handleMcpToolCall`, and every tool handler (`get_artifact`,
- *   `create_project`, `start_run`, project/active-context resolution, studio deep
- *   links, run polling, …). This is not a generic MCP client: it is an
- *   OD-product MCP **server** hardwired to Open Design's REST API
- *   (`/api/projects`, `/api/skills`, `/api/design-systems`, `/api/runs`, …) and
- *   concepts (design systems, skills, plugins, artifacts, runs, studio, the
- *   `od://` resource scheme). It also imports the OD-only `@open-design/contracts`
- *   package (`buildProjectRawFileUrl`), the OD daemon-internal
- *   `../../artifacts/create.js`, and the `@modelcontextprotocol/sdk` — none of
- *   which exist in this repo. Faithfully porting it would mean importing OD
- *   product surface, so it was dropped and only its generic primitives salvaged.
- * - **`MCP_TEMPLATES` catalog + template types + `templateId`** in `config.ts` —
- *   a large, design-tool-tilted curated catalog of third-party MCP servers with
- *   OD marketing prose. Zero functional coupling; dropped for neutrality (same
- *   rationale `@jini/sqlite` used to drop the OD "templates" table).
- *
- * ### The `list_agents` decision
- *
- * Investigated before building anything, per the task brief. `@jini/agent-runtime`'s
- * barrel (`packages/agent-runtime/src/index.ts` → `export * from './registry.js'`)
- * already exports `AGENT_DEFS: RuntimeAgentDef[]` — the exact static, in-memory
- * list of every registered agent def (`registry.ts`'s `BASE_AGENT_DEFS`, 24
- * entries). `RuntimeAgentDef` has plain `id`/`name` fields (plus a large surface
- * of CLI-spawn internals: `bin`, `buildArgs`, `env`, `listModels`, etc. — no
- * `available`/live-detection field at all). No HTTP projection of this list
- * existed anywhere in `packages/http/src/*.ts` before this pass. Building
- * `GET /api/agents` returning `{agents: [{id, name}]}` needed no design judgment
- * call beyond "project the two safe fields" — no timeout/caching/probing
- * decisions, unlike OD's own `list_agents` (`listAgents`, mcp.ts:1034-1057),
- * which filters on a *live-detected* `available: boolean` field (OD's
- * `/api/agents` route actually probes each agent binary for installation/version
- * at request time — a real design decision this pass deliberately did not need
- * to make, since Jini has no such probing route or field to project). So it was
- * built: `packages/http/src/agents.ts`'s `agentListRoute` (`GET /api/agents`,
- * `AgentsHttpDeps.listAgents: () => readonly {id, name}[]` injected — DI,
- * matching `daemon-status.ts`/`active-context.ts`'s convention, so `@jini/http`
- * does not take on a new `@jini/agent-runtime` package dependency for a
- * two-field projection) plus `@jini/mcp`'s `list_agents` tool
- * (`server/tools/run-tools.ts`) proxying it. OD's `includeUnavailable` flag and
- * per-agent `installUrl`/`modelsCount` enrichment were **not** ported — those
- * exist only because OD's route does live probing, which this pass's route does
- * not attempt.
- *
- * ### What was explicitly excluded (and why)
- *
- * Per the task brief, only the mechanism plus tools mapping to real kernel
- * primitives were ported. The other 13 of OD's 18 `TOOL_DEFS` were **not**
- * ported — all are OD's project/file/artifact/skill/plugin model, none of which
- * exists in the Jini kernel (extraction-plan §2.1's "no Project, Conversation,
- * Brand, DesignSystem, Plugin/marketplace, or Automation noun" holds here
- * exactly as it did for `@jini/cli`'s own `mcp` row):
- * `list_projects`, `get_artifact`, `get_project`, `get_file`, `search_files`,
- * `list_files`, `create_artifact`, `write_file`, `delete_file`, `delete_project`,
- * `create_project`, `list_skills`, `list_plugins`. Also not ported: the
- * `ListResourcesRequestSchema`/`ReadResourceRequestSchema` resource surface
- * (`od://focus/active`, `od://skills/...`, `od://design-systems/...` — resources
- * require a skill/design-system store this kernel doesn't have), the studio
- * deep-link builder (`buildStudioUrl`, `getDefaultConversationId`,
- * `getWebBaseUrl`), the project-name-resolution cache (`resolveProjectId`,
- * `fetchProjectList`, `resolveProjectArg`), and the SSE-transcript reassembly
- * (`fetchRunAgentMessage`) — every one of these exists only in service of a
- * dropped tool.
- *
- * ### Design decision: the hosting-mechanism shape
- *
- * `createMcpToolServer({name, version, tools, resolveBaseUrl, instructions?,
- * idleMs?, fetchImpl?, stdin?, stdout?, createServer?, createTransport?})`
- * returns `{run(): Promise<void>}`. Construction (tool-name-uniqueness
- * validation via `buildToolIndex`) is synchronous and side-effect-free; all I/O
- * — resolving the daemon URL, connecting the transport, serving requests —
- * happens in `run()`. This is genuinely new kernel-adjacent surface (a new
- * package capability, not a file port), justified per extraction-plan §7's
- * two-consumer rule by the user's explicit request plus the stated expectation
- * that Zana/Open-Marketing will each want their own product-specific MCP
- * server built on the same hosting mechanism later — so the mechanism accepts
- * an arbitrary, caller-registered `McpToolDef[]`, not the 3-5 tools this pass
- * ships as its first real, working example.
- *
- * `McpServerLike`/`McpTransportLike` (in `tool-server.ts`) are narrow structural
- * interfaces covering only what this module calls on a `Server` instance
- * (`setRequestHandler`, `connect`) and a transport (`onmessage`, `onclose`,
- * `close`) — not literal re-exports of the SDK's own types, which can't be
- * satisfied by a plain object (the SDK's `Server` class has private fields, so
- * it's nominally, not structurally, typed). The default `createServer`/
- * `createTransport` factories construct the real SDK classes and cast through
- * `unknown` to these narrower interfaces (the same `as unknown as X` pattern
- * `core/oauth.ts` already uses to bridge undici's types); a caller may override
- * either factory to inject a test double. This is what makes `run()`'s full
- * orchestration — activity wrapping, message/close composition, the stdin-close
- * race, idle-triggered shutdown — deterministically unit-testable without a
- * real subprocess or real timers (see `tool-server.test.ts`), while one
- * dedicated test (`'wires the real @modelcontextprotocol/sdk Server +
- * StdioServerTransport when no factories are injected'`) still exercises the
- * true default path end-to-end with real `node:stream` `PassThrough` streams,
- * proving the DI seam isn't hiding a real-SDK integration bug.
- *
- * **Why `daemon-client.ts` is not `@jini/cli`'s `getJsonFromDaemon`/
- * `postJsonToDaemon`.** The architectural brief called for reusing
- * `@jini/cli`'s already-hardened daemon-fetch helpers "the way
- * `packages/cli/src/run-command.ts` already does." Checked directly: those two
- * functions map every failure — network-unreachable, non-2xx, oversized
- * response — onto `process.exit()` (via `exitWithStructuredError`), which is
- * correct for a one-shot CLI invocation but fatal for a long-lived stdio MCP
- * server, where a single failed tool call must return an `{isError:true}` MCP
- * result and the process must keep serving the next call. Routing around this
- * by injecting an `exit` callback that throws instead of exiting was considered
- * and rejected: it would require also capturing/re-parsing whatever
- * `postJsonToDaemon` had already written through its `write` callback to
- * reconstruct an error message, which is more convoluted than porting OD's own
- * already-throw-based `getJson`/`postJson` mechanism with the same bounded-I/O
- * hardening added. What **is** reused directly from `@jini/cli` (both pure,
- * non-`process.exit` functions): `sanitizeUntrustedText` (redacts daemon-
- * supplied error text before it reaches an MCP result) and, per the
- * architecture note about `daemon-url.ts`, `resolveDaemonUrl`/
- * `sanitizeDaemonUrlForDisplay` are available for a caller's `resolveBaseUrl`
- * implementation to use directly (this package does not re-wrap them — a
- * caller passes `() => resolveDaemonUrl({...})` straight into
- * `createMcpToolServer`'s `resolveBaseUrl` option; no `packages/mcp`-local
- * daemon-URL-resolution equivalent was built, since one already exists and nothing
- * about MCP's use case differs from a CLI command's). This cross-import
- * (`@jini/mcp` -> `@jini/cli`) is allowed by `scripts/check-engine-boundaries.ts`'s
- * R7 rule: R7 only restricts a **locked** package (the extraction-plan §3
- * fourteen) importing an **unlocked** one below `"stable"` status; `@jini/mcp`
- * is itself unlocked (`UNLOCKED.md`), so it importing the locked, stable
- * `@jini/cli` package is unrestricted. Confirmed via `pnpm guard` after wiring
- * the dependency (see below) — zero violations.
- *
- * No SSRF hardening (`assertSafePublicUrl`/`createValidatingLookup`, the
- * pattern `core/oauth.ts` uses for its own outbound fetches) was added to
- * `daemon-client.ts` — deliberately: `assertSafePublicUrl` actively *rejects*
- * loopback/private addresses, which is exactly where a real daemon lives. The
- * daemon URL here is a caller-resolved, typically-loopback target the user
- * already trusts enough to run (the same trust boundary `@jini/cli/http.ts`
- * already accepts for the identical "fetch my own daemon" concern), not an
- * attacker- or remote-metadata-controlled URL the way an external MCP server's
- * OAuth endpoints are.
- *
- * ### `daemonCallOptions(ctx)` — why a helper for two fields
- *
- * Nine call sites across `tools/` and `resources/` each wrote `{ fetchImpl: ctx.fetchImpl }` inline. Adding
- * a second field that must travel with the first creates a failure mode that is *not* a compile error: miss
- * one site and that single tool 401s while its neighbours keep working, which reaches a user as "some of
- * these tools just don't do anything". Every site now routes through one mapping, so a newly added tool is
- * authenticated by construction.
- *
- * The guarantee is a test rather than a convention. `server/__tests__/auth-propagation.test.ts` enumerates
- * the **real** registries (`RUN_TOOLS`, `TOOL_CATALOG_TOOLS`, `createExecuteDelegatedToolTool`,
- * `KERNEL_RESOURCES` — 8 tools + 1 resource), drives each handler through a spy `fetch`, and asserts the
- * header on every request each one makes; a matching pass asserts **no** `Authorization` key at all when no
- * credential was issued. It also asserts the surface list itself, so emptying or renaming a registry cannot
- * make the loops vacuously pass.
- *
- * That test was verified to actually catch the bug it exists for: reverting one call site to the inline form
- * fails it, naming the offending tool and URL.
- *
- * No transport change was needed — `daemon-client.ts`'s `DaemonRequestOptions` already carried `headers`.
- *
- * **Verified, personally, this session**: `pnpm --filter @jini-ai/mcp run typecheck` clean; full suite
- * **332/332 passing** (18 files), including 21 new propagation tests and 4 new `serve()` credential tests.
- * The pre-existing tool/resource suites, which assert the exact options object passed to the daemon client,
- * pass **unmodified** — the evidence that the no-credential path is byte-identical.
+ * Import capabilities through the public barrel or declared stable subpaths; internal source
+ * paths remain private so the core/client/install/hosting split can move without consumer churn.
+ * Explicit named exports expose the public surface and catch collisions. Core binding, hosting,
+ * daemon I/O and auth propagation are documented at their respective owners below.
  */
-// The original root-only boundary above describes the initial core/client/server split.
-// Stable public subpaths now also host federation, approvals, stdio, testing, and ask-choice;
-// internal source paths remain private so consumers can follow their declared runtime entry.
 // ── core: config schema + IO ────────────────────────────────────────────────
 export { inferMcpAuthModeForUrl, sanitizeMcpServer, sanitizeMcpConfig, readMcpConfig, writeMcpConfig, isManagedProjectCwd, buildClaudeMcpJson, buildAcpMcpServers, buildOpenCodeMcpConfigContent, } from './core/index.js';
 // ── core: token store ───────────────────────────────────────────────────────

package/dist/server/daemon-client.d.ts

@@ -1,7 +1,6 @@
 /**
- * Thrown for a non-2xx daemon response. The message is unchanged from the plain `Error` this used to
- * be; `status` is what lets a tool tell "this daemon does not serve the route" (404) apart from any
- * other failure instead of pattern-matching the message.
+ * Thrown for a non-2xx daemon response. `status` lets a tool distinguish an unsupported route (404)
+ * from other failures without pattern-matching the public error message.
  */
 export declare class DaemonHttpError extends Error {
     readonly status: number;

package/dist/server/daemon-client.js

@@ -1,30 +1,12 @@
 /**
  * @module @jini-ai/mcp/server/daemon-client
+ * Bounded-I/O JSON GET/POST against a caller-resolved trusted daemon base URL.
+ * A long-lived MCP server must report a failed call and keep serving, so this transport throws
+ * redacted errors for handleToolCall to convert rather than using the CLI transport's process.exit.
+ * Bounded reads, timeouts and redaction follow CR-004/SEC-RB-009.
  *
- * Bounded-I/O JSON GET/POST against a trusted daemon base URL — the transport
- * primitive every proxy tool `createMcpToolServer` hosts is built on
- * (`../client/client.js`'s `createMcpIdleExitController` is the other half of
- * the mechanism; this module is the network half).
- *
- * Deliberately NOT the CLI transport's `getJsonFromDaemon`/`postJsonToDaemon`
- * (`packages/cli/src/http.ts`): those map a failure onto `process.exit`,
- * which is the right contract for a one-shot CLI invocation but wrong here —
- * a stdio MCP server is a long-lived process serving many tool calls, and one
- * failed call must return an MCP `{isError:true}` result and keep serving the
- * next call, not terminate the process. This module ports the same
- * bounded-read / timeout / redaction posture `http.ts` established
- * (CR-004/SEC-RB-009 — see `ADS-memory/reports/code-review/CR-remaining-backend-audit-2026-07-21.md`,
- * `ADS-memory/reports/security/SEC-remaining-backend-audit-2026-07-21.md`) as
- * a throw-based primitive instead: a failed request throws a plain,
- * already-redacted `Error` whose message a tool handler's caller
- * (`handleToolCall` in `./tool-protocol.js`) turns into that MCP error result.
- *
- * No SSRF hardening here: the
- * target is a caller-resolved, typically-loopback daemon the user already
- * trusts enough to run — not an attacker- or server-metadata-controlled
- * remote URL the way a configured external MCP server's OAuth endpoints are.
- * This mirrors the CLI HTTP transport's own posture for the identical "fetch my
- * own daemon" concern (no `assertSafePublicUrl` there either).
+ * This is a trusted, typically-loopback daemon URL, not attacker-controlled server metadata or
+ * an external MCP OAuth endpoint; public-URL SSRF validation is therefore outside this contract.
  */
 import { sanitizeUntrustedText } from '@jini-ai/core/text';
 /** Request deadline. Generous enough for a slow tool call, short enough that a stalled daemon doesn't hang a stdio server turn forever. */
@@ -32,9 +14,8 @@ const DEFAULT_TIMEOUT_MS = 15_000;
 /** Cap on a daemon response body. Comfortably larger than any real status/run envelope, small enough to bound worst-case memory from a hostile/broken daemon. */
 const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 /**
- * Thrown for a non-2xx daemon response. The message is unchanged from the plain `Error` this used to
- * be; `status` is what lets a tool tell "this daemon does not serve the route" (404) apart from any
- * other failure instead of pattern-matching the message.
+ * Thrown for a non-2xx daemon response. `status` lets a tool distinguish an unsupported route (404)
+ * from other failures without pattern-matching the public error message.
  */
 export class DaemonHttpError extends Error {
     status;