@jini-ai/mcp 0.3.4 → 0.4.1

package/dist/index.d.ts

@@ -7,11 +7,177 @@
  *
  * 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.
  */
 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';
-export { generateCodeVerifier, deriveCodeChallenge, generateState, discoverProtectedResource, discoverAuthServer, registerClient, getOrRegisterClient, buildAuthorizeUrl, exchangeCodeForToken, refreshAccessToken, PendingAuthCache, beginAuth, } from './core/index.js';
-export type { ProtectedResourceMetadata, AuthorizationServerMetadata, RegisteredClient, OAuthTokenResponse, PendingAuthState, AuthorizeUrlInput, ExchangeCodeInput, RefreshTokenInput, BeginAuthInput, BeginAuthResult, } from './core/index.js';
 export { sanitizeTokensFile, readTokensFile, getToken, setToken, clearToken, readAllTokens, isTokenExpired, } from './core/index.js';
 export type { StoredMcpToken, McpTokensFile } from './core/index.js';
 export { buildMcpInstallPayload } from './core/index.js';
@@ -27,4 +193,11 @@ export { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool,
 export type { CreateExecuteDelegatedToolToolOptions } from './server/index.js';
 export { AGENT_SLUGS, isAgentSlug, planAgentInstall, applyJsonInstall, removeJsonInstall, } from './agent-install/index.js';
 export type { AgentSlug, McpLaunchSpec, PlanContext, CliInstallPlan, JsonInstallPlan, ManualInstallPlan, InstallPlan, } from './agent-install/index.js';
+export type { McpConfigFilesystemPort } from './core/config.js';
+export type { McpTokenClockOptions, McpTokenStoreOptions } from './core/tokens.js';
+export type { BuildMcpInstallPayloadOptions } from './core/install-info.js';
+export type { McpIdleTimerPort } from './client/client.js';
+export type { McpToolServerRequiredArgs } from './server/tool-server.js';
+export type { CreateExecuteDelegatedToolToolRequiredArgs } from './server/tools/delegated-tool.js';
+export { DaemonHttpError } from './server/daemon-client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -7,11 +7,180 @@
  *
  * 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.
  */
+// 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: OAuth 2.1 / PKCE flow ─────────────────────────────────────────────
-export { generateCodeVerifier, deriveCodeChallenge, generateState, discoverProtectedResource, discoverAuthServer, registerClient, getOrRegisterClient, buildAuthorizeUrl, exchangeCodeForToken, refreshAccessToken, PendingAuthCache, beginAuth, } from './core/index.js';
 // ── core: token store ───────────────────────────────────────────────────────
 export { sanitizeTokensFile, readTokensFile, getToken, setToken, clearToken, readAllTokens, isTokenExpired, } from './core/index.js';
 // ── core: install-info payload ──────────────────────────────────────────────
@@ -30,4 +199,5 @@ export { searchComponentsTool, describeComponentTool, COMPONENT_CATALOG_TOOLS }
 export { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool, DEFAULT_DELEGATED_TOOL_TIMEOUT_MS, } from './server/index.js';
 // ── agent-install: register an MCP server into external agents ──────────────
 export { AGENT_SLUGS, isAgentSlug, planAgentInstall, applyJsonInstall, removeJsonInstall, } from './agent-install/index.js';
+export { DaemonHttpError } from './server/daemon-client.js';
 //# sourceMappingURL=index.js.map

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

@@ -5,12 +5,17 @@
  */
 export declare class DaemonHttpError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    constructor({ message, status }: {
+        message: string;
+        status: number;
+    });
 }
 /** Thrown internally when a response exceeds its byte cap; always translated to a plain `Error` before it crosses this module's public functions. */
 export declare class DaemonResponseTooLargeError extends Error {
     readonly limitBytes: number;
-    constructor(limitBytes: number);
+    constructor({ limitBytes }: {
+        limitBytes: number;
+    });
 }
 export interface DaemonRequestOptions {
     /** Defaults to the global `fetch`; inject for tests. */
@@ -24,7 +29,14 @@ export interface DaemonRequestOptions {
     signal?: AbortSignal;
 }
 /** `GET <baseUrl><route>` and return the parsed JSON response, throwing on network failure or a non-2xx status. */
-export declare function getDaemonJson<T = unknown>(baseUrl: string, route: string, options?: DaemonRequestOptions): Promise<T>;
+export declare function getDaemonJson<T = unknown>({ baseUrl, route }: {
+    baseUrl: string;
+    route: string;
+}, options?: DaemonRequestOptions): Promise<T>;
 /** `POST body` (JSON-serialized) to `<baseUrl><route>` and return the parsed JSON response, throwing on network failure or a non-2xx status. */
-export declare function postDaemonJson<T = unknown>(baseUrl: string, route: string, body: unknown, options?: DaemonRequestOptions): Promise<T>;
+export declare function postDaemonJson<T = unknown>({ baseUrl, route, body }: {
+    baseUrl: string;
+    route: string;
+    body: unknown;
+}, options?: DaemonRequestOptions): Promise<T>;
 //# sourceMappingURL=daemon-client.d.ts.map

package/dist/server/daemon-client.js

@@ -6,7 +6,7 @@
  * (`../client/client.js`'s `createMcpIdleExitController` is the other half of
  * the mechanism; this module is the network half).
  *
- * Deliberately NOT `@jini-ai/cli`'s `getJsonFromDaemon`/`postJsonToDaemon`
+ * 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
@@ -19,14 +19,14 @@
  * 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 (unlike `../core/oauth.ts`'s `safeOAuthFetch`): the
+ * 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 `@jini-ai/cli/http.ts`'s own posture for the identical "fetch my
+ * This mirrors the CLI HTTP transport's own posture for the identical "fetch my
  * own daemon" concern (no `assertSafePublicUrl` there either).
  */
-import { sanitizeUntrustedText } from '@jini-ai/cli';
+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. */
 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. */
@@ -38,7 +38,7 @@ const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
  */
 export class DaemonHttpError extends Error {
     status;
-    constructor(message, status) {
+    constructor({ message, status }) {
         super(message);
         this.status = status;
         this.name = 'DaemonHttpError';
@@ -47,7 +47,7 @@ export class DaemonHttpError extends Error {
 /** Thrown internally when a response exceeds its byte cap; always translated to a plain `Error` before it crosses this module's public functions. */
 export class DaemonResponseTooLargeError extends Error {
     limitBytes;
-    constructor(limitBytes) {
+    constructor({ limitBytes }) {
         super(`daemon response exceeded the ${limitBytes}-byte limit`);
         this.limitBytes = limitBytes;
         this.name = 'DaemonResponseTooLargeError';
@@ -76,7 +76,7 @@ async function readJsonWithLimit(resp, maxBytes) {
     if (contentLength !== null && contentLength !== undefined) {
         const declared = Number(contentLength);
         if (Number.isFinite(declared) && declared > maxBytes)
-            throw new DaemonResponseTooLargeError(maxBytes);
+            throw new DaemonResponseTooLargeError({ limitBytes: maxBytes });
     }
     const body = resp.body;
     if (body != null && typeof body.getReader === 'function') {
@@ -92,7 +92,7 @@ async function readJsonWithLimit(resp, maxBytes) {
                 if (value !== undefined) {
                     total += value.byteLength;
                     if (total > maxBytes)
-                        throw new DaemonResponseTooLargeError(maxBytes);
+                        throw new DaemonResponseTooLargeError({ limitBytes: maxBytes });
                     text += decoder.decode(value, { stream: true });
                 }
             }
@@ -105,7 +105,7 @@ async function readJsonWithLimit(resp, maxBytes) {
     }
     const text = await resp.text();
     if (Buffer.byteLength(text, 'utf8') > maxBytes)
-        throw new DaemonResponseTooLargeError(maxBytes);
+        throw new DaemonResponseTooLargeError({ limitBytes: maxBytes });
     return parseJsonLoose(text);
 }
 /** Formats a `fetch()` rejection (network-unreachable) into a message safe to surface as an MCP tool error. */
@@ -115,18 +115,40 @@ function formatConnectionFailure(err, baseUrl) {
         ? cause.code
         : null;
     if (code === 'ECONNREFUSED' || code === 'ENOTFOUND') {
-        return `cannot reach the daemon at ${baseUrl}. Is it running?`;
+        return safeDiagnostic({ text: `cannot reach the daemon at ${baseUrl}. Is it running?` });
     }
     const message = err instanceof Error ? err.message : String(err);
-    return sanitizeUntrustedText(message);
+    return safeDiagnostic({ text: message });
+}
+/** Remove URL credentials, queries and fragments before ordinary secret/control redaction.
+ * Even short query tokens are secrets; token-length heuristics cannot protect them.
+ * @complexity O(n) in diagnostic text, plus URL parsing for each URL.
+ */
+function safeDiagnostic({ text }) {
+    const redacted = text.replace(/https?:\/\/[^\s<>"']+/gi, url => {
+        try {
+            const parsed = new URL(url);
+            if (!parsed.username && !parsed.password && !parsed.search && !parsed.hash)
+                return url;
+            parsed.username = '';
+            parsed.password = '';
+            parsed.search = '';
+            parsed.hash = '';
+            return parsed.toString();
+        }
+        catch {
+            return '[redacted URL]';
+        }
+    });
+    return sanitizeUntrustedText({ text: redacted });
 }
 /** Formats a non-2xx daemon response into a message safe to surface as an MCP tool error. */
 function formatDaemonHttpError(status, url, data) {
     const envelope = data;
-    const code = typeof envelope.error?.code === 'string' ? envelope.error.code : undefined;
-    const rawMessage = typeof envelope.error?.message === 'string' ? envelope.error.message : undefined;
-    const detail = rawMessage !== undefined ? sanitizeUntrustedText(rawMessage) : `HTTP ${status}`;
-    return code !== undefined ? `daemon ${status} on ${url}: ${code}: ${detail}` : `daemon ${status} on ${url}: ${detail}`;
+    const code = typeof envelope?.error?.code === 'string' ? envelope.error.code : undefined;
+    const rawMessage = typeof envelope?.error?.message === 'string' ? envelope.error.message : undefined;
+    const detail = rawMessage ?? `HTTP ${status}`;
+    return safeDiagnostic({ text: code !== undefined ? `daemon ${status} on ${url}: ${code}: ${detail}` : `daemon ${status} on ${url}: ${detail}` });
 }
 /**
  * Shared transport core behind {@link getDaemonJson} and {@link postDaemonJson}: fetch
@@ -165,12 +187,12 @@ async function requestDaemonJson(baseUrl, route, init, options = {}) {
         }
         catch (err) {
             if (err instanceof DaemonResponseTooLargeError) {
-                throw new Error(`response from ${url} exceeded the ${err.limitBytes}-byte limit`);
+                throw new Error(safeDiagnostic({ text: `response from ${url} exceeded the ${err.limitBytes}-byte limit` }));
             }
             throw err;
         }
         if (!resp.ok) {
-            throw new DaemonHttpError(formatDaemonHttpError(resp.status, url, data), resp.status);
+            throw new DaemonHttpError({ message: formatDaemonHttpError(resp.status, url, data), status: resp.status });
         }
         return data;
     }
@@ -179,11 +201,11 @@ async function requestDaemonJson(baseUrl, route, init, options = {}) {
     }
 }
 /** `GET <baseUrl><route>` and return the parsed JSON response, throwing on network failure or a non-2xx status. */
-export async function getDaemonJson(baseUrl, route, options) {
+export async function getDaemonJson({ baseUrl, route }, options) {
     return requestDaemonJson(baseUrl, route, { method: 'GET' }, options);
 }
 /** `POST body` (JSON-serialized) to `<baseUrl><route>` and return the parsed JSON response, throwing on network failure or a non-2xx status. */
-export async function postDaemonJson(baseUrl, route, body, options) {
+export async function postDaemonJson({ baseUrl, route, body }, options) {
     return requestDaemonJson(baseUrl, route, { method: 'POST', body }, options);
 }
 //# sourceMappingURL=daemon-client.js.map

package/dist/server/ports.d.ts

@@ -0,0 +1,9 @@
+/** Transport port. The default adapter translates SDK callbacks to object arguments. */
+export interface McpTransportLike {
+    onmessage?: ((args: {
+        message: unknown;
+    }) => void) | undefined;
+    onclose?: (() => void) | undefined;
+    close(required: Record<string, never>): Promise<void>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/server/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/server/resource-protocol.d.ts

@@ -17,12 +17,18 @@ export interface McpResourceDef {
     readonly name: string;
     readonly description?: string;
     readonly mimeType?: string;
-    readonly read: (ctx: McpToolContext) => Promise<McpResourceReadResult> | McpResourceReadResult;
+    readonly read: (requiredArgs: {
+        ctx: McpToolContext;
+    }) => Promise<McpResourceReadResult> | McpResourceReadResult;
 }
 /** Projects a resource list into the `Resource[]` shape `resources/list` returns. */
-export declare function resourcesToList(resources: readonly McpResourceDef[]): Resource[];
+export declare function resourcesToList({ resources }: {
+    resources: readonly McpResourceDef[];
+}): Resource[];
 /** Builds a uri -> def lookup, throwing if two resources in `resources` share a uri (a caller-configuration bug, surfaced eagerly at server-construction time rather than letting the second registration shadow the first). */
-export declare function buildResourceIndex(resources: readonly McpResourceDef[]): Map<string, McpResourceDef>;
+export declare function buildResourceIndex({ resources }: {
+    resources: readonly McpResourceDef[];
+}): Map<string, McpResourceDef>;
 /**
  * `resources/read` dispatch: looks up `uri` in `resources` and runs its `read`. Unlike
  * {@link import('./tool-protocol.js').handleToolCall}, a failure here *throws* rather than
@@ -34,5 +40,9 @@ export declare function buildResourceIndex(resources: readonly McpResourceDef[])
  * it leaves this function, the same conservative posture `handleToolCall` uses — a `read`
  * implementation may re-throw text that traces back to an untrusted daemon response.
  */
-export declare function handleResourceRead(uri: string, resources: ReadonlyMap<string, McpResourceDef>, ctx: McpToolContext): Promise<ReadResourceResult>;
+export declare function handleResourceRead({ uri, resources, ctx }: {
+    uri: string;
+    resources: ReadonlyMap<string, McpResourceDef>;
+    ctx: McpToolContext;
+}): Promise<ReadResourceResult>;
 //# sourceMappingURL=resource-protocol.d.ts.map