@jini-ai/mcp 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,151 @@
+# @jini-ai/mcp
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- OAuth implementations and the CLI sanitizer dependency were retired; core text and platform filesystem/network entries are canonical. Approval fingerprint domains, wire codes and messages are host-supplied; approval tenancy is optional scope.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+- Enforce fresh consent for destructive federated calls across both remembered scopes. Destructive
+  cards offer no remember buttons, matching chat grants cannot bypass them, and forged remember
+  choices are not saved. Keep ordinary, non-destructive remembered approvals and fingerprint bytes.
+
+- Repair package compilation against strict optional properties and current object-call contracts,
+  including the test fixtures. Omit absent HTTP signals and approval/revocation scopes; unscoped
+  memory approval records omit `scope`. Preserve supplied values, assertions and security guards.
+
+- Use core/primitives path containment after host path resolution. Legal managed directory names beginning with `..` are now accepted; traversal and sibling-prefix escapes remain refused.
+
+- **BREAKING:** Federation prose uses required host messages (`defaultFederationMessages` is
+  neutral English); fingerprint domains and error namespaces are required wire arguments.
+  Missing confirmation channels derive `${errorCode}_NO_CONFIRMATION_CHANNEL`. Opaque optional
+  scope replaces workspace-shaped repository/roster/webhook inputs; approval-duration fields stay.
+- **BREAKING:** Bootstrap/reload use core Logger and approval/token clocks use core Clock.nowMs().
+  The private secret writer is removed; stores use platform's async atomic writer at 0600 with
+  owner-only verification, file/directory fsync and parent creation. Directory-sync errors can
+  follow successful replacement. Default info logs use console.info with `agent-daemon` prefix.
+- Remove the CLI runtime dependency, including executable URL resolution. Sanitization imports
+  core/text; loopback checks use platform/net. Fingerprint and key byte compatibility are pinned
+  in tests. The stdio stderr scrubber retains its lowercase marker/minimum length contract.
+
+- Align trust comments with protected-action-only confirmation and preserve the distinct HTTP 401
+  and 403 outcomes. Count UTF-8 result/response bytes, cap aggregate serialized images, bound shutdown
+  DELETE and all stdio connection phases, pin install data roots, redact diagnostic URLs and use
+  declared run statuses. Regression tests are written, not run (owner directive).
+
+- Isolate HTTP 401 challenge-hook failures through the injected logger and bound observer waits by
+  the existing request timeout and caller cancellation. Preserve typed authentication failures for
+  auth-revocation handlers; hooks may consume the request signal through optional second arguments.
+  Regression tests are written and not run (owner directive).
+
+- Finish pass: reconcile `./federation`, `./federation/approvals`, `./federation/stdio`,
+  `./federation/testing`, and `./tools/ask-choice` with their entry metadata, source barrels,
+  injected ports, and generalized characterization suites. Add declarations/import conditions
+  to the existing `./bin` executable entry. The core dependency is declared; lockfile refresh
+  remains with the coordinator. Tests, typechecks, build, and packing are not run (owner directive).
+- BREAKING: effectful lifecycle methods (`run`, `close`, `reload`, `noteActivity`, `dispose`),
+  preset reset, and empty memory-store construction take an empty required object. SDK callbacks
+  and zero-argument getters retain their ABI. Question-shape errors take `{ message }, { cause? }`;
+  their messages and error classification are preserved. No exports are renamed in this pass.
+  Correlation-id generators and idle/request-work callbacks receive an empty object; clocks,
+  URL/connection resolvers, list getters, and native scheduler/SDK callbacks keep their ABI.
+- Security defaults: reject explicitly invalid transport/auth modes instead of inferring a policy.
+  Incomplete configured stdio toolchains now refuse launch; hosts can explicitly opt into
+  `allowIdentityFallback: true` with a warning. Unconfigured ordinary launches remain identity
+  launches. Protocol bytes, approval fingerprints, timeouts, environment inheritance, and version
+  remain unchanged. New regression tests describe these changes and await execution.
+
+- Add `./tools/ask-choice`: a product-neutral human-question tool factory with injected
+  policy, presentation, result copy, exchange storage, and pending-question storage.
+  Includes an optional clock/ID-injected single-use answer-ticket adapter, generalized
+  characterization tests, and a package source neutrality guard. Existing exports and
+  the package version are unchanged. Verification deferred by owner directive.
+
+- Add `./federation`, `./federation/stdio`, `./federation/testing`, and
+  `./federation/approvals`, completing the new subpaths alongside `./tools/ask-choice`.
+  Federation injects client identity, permission, session, credential, resolver, human
+  confirmation, approval storage, and current-roster ports. Preserve the approval fingerprint
+  format and pinned vector. Declare the core dependency and per-entry runtimes.
+- BREAKING: public helpers and factories take required objects and optional settings objects.
+  Tool handlers take `{ args, ctx }`, resource readers take `{ ctx }`, and ask-choice handlers
+  take `{ ctx }`. Daemon GET/POST helpers and error constructors use named objects.
+  Server/transport, federation callback, channel, and resolver ports use named objects;
+  cancellation and HTTP body options are second objects. Config/token stores inject filesystem
+  and clock ports. `requireString({ value, name })` returns the string; `isAgentSlug(args)`
+  narrows `args.value`; `serve({}, deps)` uses `{ text }`/`{ code }` error/exit ports.
+  Persisted data and MCP wire formats remain unchanged.
+- BREAKING: retire the duplicated MCP OAuth implementation and its root exports. Use the
+  independent OAuth package through host credential ports; MCP does not import that engine.
+  The root API test now asserts the retired exports remain absent.
+- Complete root type exports and reconcile core registry calls, delegated gateway construction,
+  daemon proxy callers, test fixtures, and package-wide source neutrality checks. No version bump.
+  Verification is not run (owner directive).
+
+## 0.1.2
+
+### Patch Changes
+
+- Add top-level `main`/`types` fields alongside the existing `exports` map. A consumer on
+  TypeScript's classic `moduleResolution: "node"` (node10) — which ignores `package.json#exports`
+  entirely — could not resolve this package's types at all (`TS2307: Cannot find module`) even
+  after the previous exports-map fix restored `require()` at runtime; type resolution and runtime
+  resolution are separate algorithms. Verified against a real external consumer (whose
+  tsconfig uses this legacy resolution mode): adding these two fields, with its tsconfig completely
+  unchanged, made the error disappear. Also fixes absolute-path `require()` (distinct from a bare
+  specifier, which already worked) for the same reason — `main` was previously absent.
+
+  Purely additive: every modern resolver (Node's own runtime `exports` resolution, TypeScript's
+  `bundler`/`node16`/`nodenext`) prefers `exports` over `main`/`types` when both are present, so
+  this changes nothing for a consumer already on a modern resolver.
+
+- Updated dependencies
+  - @jini-ai/cli@0.1.2
+  - @jini-ai/platform@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Add a `"default"` export condition to every published package's `exports` map — every one of
+  them lacked it, which meant `require()` failed with `ERR_PACKAGE_PATH_NOT_EXPORTED` for any
+  CommonJS consumer (found via a real external integration attempt; Node needs `require(esm)`
+  support, i.e. Node >=22.12, for this to resolve).
+
+  `@jini-ai/agent-runtime`:
+
+  - **New**: `RuntimeBuildOptions.permissionMode` (`'bypass' | 'restricted'`) lets a caller opt a
+    run OUT of the auto-approve-every-permission-prompt flag every def with one
+    (`bypassPermissions` / `--yolo` / `--dangerously-skip-permissions`) previously pushed
+    unconditionally, with no way to turn it off. Omitting it keeps today's default (bypass)
+    behavior unchanged.
+  - **New**: `ClaudeStreamEvent`, `CopilotStreamEvent`, and `QoderEvent` are now real exported
+    discriminated unions instead of `Record<string, unknown>` — a real external consumer guessed a
+    nonexistent field name (`event.text` instead of the actual `event.delta`) against the old
+    untyped sink and silently lost every streamed token with no compile or runtime error.
+  - Fixed a doc/implementation mismatch in `claude-stream.ts`: the module doc claimed `tool_result`
+    events carry `{ tool_use_id, content, is_error }`; the actual emitted shape is
+    `{ toolUseId, content, isError }`.
+
+  `@jini-ai/daemon`: `AgentExecutorRunInput.permissionMode` forwards the new
+  `RuntimeBuildOptions.permissionMode` through to `buildArgs`, so a host can actually reach the new
+  opt-out from the daemon's real run-input surface, not just from `@jini-ai/agent-runtime` in
+  isolation.
+
+  `@jini-ai/agentic`: `setAtPointer` no longer throws on a malformed (e.g. missing leading `/`)
+  `updateDataModel` path — degrades to a no-op like its sibling `getAtPointer`, matching this
+  package's own "a bad binding must not crash the renderer" contract. That path is agent-authored
+  wire data with no error boundary above it in any host, so the uncaught throw could unmount an
+  entire chat UI from ~40 bytes of malformed input.
+
+  `@jini-ai/chat-react`: a local (client-resolved) A2UI button action is no longer a silent no-op —
+  `A2uiSurfaceCard` now surfaces the resolved value. New `ExtEventErrorBoundary` confines a
+  `kind: 'ext'` event group's renderer to its own card instead of letting a render/effect-phase
+  throw from agent-controlled content unmount the whole chat root (there was no error boundary
+  anywhere in this package or its hosts before this).
+
+- Updated dependencies
+  - @jini-ai/platform@0.1.1
+  - @jini-ai/cli@0.1.1

package/README.md

@@ -4,8 +4,8 @@ Everything a Jini host needs on both sides of the Model Context Protocol. On the
 a generic mechanism for hosting a bounded set of MCP tools and read-only resources over stdio, plus
 the kernel run tools (`start_run`, `get_run`, `cancel_run`, `list_agents`) already defined against
 it, and a bootable `jini-mcp` binary an MCP client can spawn directly. On the **client/config** side:
-a validated `mcp.json` schema with sanitizing read/write, an OAuth 2.1 + PKCE flow with a token
-store, and installation planning that registers an MCP server into external coding agents. Nothing
+a validated `mcp.json` schema with sanitizing read/write, a token
+store with host-owned OAuth orchestration, and installation planning that registers an MCP server into external coding agents. Nothing
 here assumes a product layout — a caller injects the daemon URL, the tool list, and the fetch
 implementation.
 
@@ -15,12 +15,13 @@ implementation.
 npm install @jini-ai/mcp
 ```
 
-No peer dependencies. `@modelcontextprotocol/sdk`, `undici`, `@jini-ai/cli`, and `@jini-ai/platform`
+No peer dependencies. `@modelcontextprotocol/sdk`, `undici`, `@cfworker/json-schema`,
+`@jini-ai/core`, `@jini-ai/cli`, and `@jini-ai/platform`
 are regular dependencies, installed automatically. Nothing here needs a native compile.
 
 ## What you get
 
-**Hosting an MCP server** — `createMcpToolServer(options)` returns a handle whose `run()` serves your
+**Hosting an MCP server** — `createMcpToolServer(requiredArgs, optionalArgs)` returns a handle whose `run({})` serves your
 `McpToolDef[]` (and optional `McpResourceDef[]`) over this process's stdin/stdout. Duplicate tool
 names or resource URIs throw at construction time. Supporting pieces: `buildToolIndex`,
 `handleToolCall`, `toolsToList`, `buildResourceIndex`, `handleResourceRead`, `resourcesToList`,
@@ -29,9 +30,10 @@ names or resource URIs throw at construction time. Supporting pieces: `buildTool
 
 **Kernel tool and resource definitions** — `RUN_TOOLS` plus its members `startRunTool`, `getRunTool`,
 `cancelRunTool`, `listAgentsTool`, `getActiveContextTool`; `KERNEL_RESOURCES` and
-`activeContextResource`; and `createExecuteDelegatedToolTool(options)` for the MCP-callback delegated
+`activeContextResource`; and `createExecuteDelegatedToolTool({ runId }, optionalArgs)` for the MCP-callback delegated
 tool-execution path. Daemon HTTP access for those definitions goes through `getDaemonJson` /
-`postDaemonJson`, which raise `DaemonResponseTooLargeError` rather than buffering an unbounded body.
+`postDaemonJson`, which bound response bytes and translate an internal `DaemonResponseTooLargeError`
+into a redacted public error rather than buffering an unbounded body.
 
 **The `jini-mcp` binary** — `package.json` declares `"bin": { "jini-mcp": "./dist/bin/serve.js" }`.
 One process serves exactly one run for its lifetime: the spawning daemon injects the run id into the
@@ -45,21 +47,48 @@ trusting a model-supplied one. The daemon URL comes from an environment variable
 `inferMcpAuthModeForUrl`, and `isManagedProjectCwd`. Per-agent config emitters:
 `buildClaudeMcpJson`, `buildAcpMcpServers`, `buildOpenCodeMcpConfigContent`.
 
-**OAuth 2.1 / PKCE** — `generateCodeVerifier`, `deriveCodeChallenge`, `generateState`,
-`discoverProtectedResource`, `discoverAuthServer`, `registerClient`, `getOrRegisterClient`,
-`buildAuthorizeUrl`, `exchangeCodeForToken`, `refreshAccessToken`, `PendingAuthCache`, and the
-one-call `beginAuth`.
+**Authentication** — OAuth is supplied by the host through credential and challenge ports.
+The earlier in-package OAuth implementation has been retired. MCP neither imports an OAuth
+engine nor retries a challenged request automatically.
 
 **Token store** — `readTokensFile`, `sanitizeTokensFile`, `getToken`, `setToken`, `clearToken`,
 `readAllTokens`, `isTokenExpired`.
 
-**Installing into external agents** — `AGENT_SLUGS` / `isAgentSlug`, `planAgentInstall(context)`
+**Installing into external agents** — `AGENT_SLUGS` / `isAgentSlug`, `planAgentInstall({ slug, spec, ctx })`
 returning a discriminated `InstallPlan` (`CliInstallPlan` | `JsonInstallPlan` | `ManualInstallPlan`),
 and `applyJsonInstall` / `removeJsonInstall` to execute the JSON-file variant. Plus
 `buildMcpInstallPayload` for the install-info payload a UI renders.
 
 **Client-side runtime helpers** — `extractRelativeRefs`, `isTextualMime`.
 
+## Argument convention (breaking)
+
+Public APIs take a required argument object and, when applicable, an optional settings object.
+For example: `writeMcpConfig({ dataDir, body }, { filesystem })`,
+`buildClaudeMcpJson({ servers }, { tokens })`, and
+`handleToolCall({ name, tools, ctx }, { rawArgs })`.
+Tool handlers receive `{ args, ctx }`; resource readers receive `{ ctx }`.
+`requireString({ value, name })` returns the validated string, and
+`isAgentSlug(args)` narrows `args.value` on a successful guard.
+The binary's library entry point is `serve({}, deps)`; its error/exit ports take
+`{ text }` and `{ code }`. SDK-facing signatures stay inside the adapters.
+
+Daemon helpers use `getDaemonJson({ baseUrl, route }, options)` and
+`postDaemonJson({ baseUrl, route, body }, options)`. Error constructors use `{ message, status }`
+or `{ limitBytes }`. See [API.md](https://github.com/AINSEP/Jini/blob/main/packages/mcp/API.md) for the current contracts and the package integration
+report for source provenance and deferred host rewiring.
+
+Effectful lifecycle methods use empty objects: `handle.run({})`, `session.close({})`,
+`channel.close({})`, `coordinator.reload({})`, `idle.noteActivity({})`, and `idle.dispose({})`.
+SDK callbacks and zero-argument getters retain their ABI. Config sanitization rejects supplied
+invalid transport/authentication modes. A configured but incomplete bundled stdio toolchain refuses
+launch unless the host explicitly sets `{ allowIdentityFallback: true }` in resolver options;
+allowed fallback carries a warning. Both toolchain variables absent selects ordinary identity
+launching. See [API.md](https://github.com/AINSEP/Jini/blob/main/packages/mcp/API.md) for the security and port contracts.
+
+Optional approval/revocation scopes and HTTP cancellation signals are omitted when absent.
+Supplied scopes and signals are forwarded unchanged; unscoped memory approval records omit `scope`.
+
 ## Usage
 
 ```ts
@@ -80,10 +109,9 @@ const greetTool: McpToolDef = {
     properties: { name: { type: 'string' } },
     required: ['name'],
   },
-  handler: async (args) => {
-    const who = args.name;
-    requireString(who, 'name'); // asserts, throws a caller-facing error otherwise
-    return okResult(`hello ${who}`);
+  handler: async ({ args }) => {
+    const who = requireString({ value: args.name, name: 'name' });
+    return okResult({ payload: `hello ${who}` });
   },
 };
 
@@ -91,12 +119,13 @@ const server = createMcpToolServer({
   name: 'example-mcp',
   version: '1.0.0',
   tools: [...RUN_TOOLS, greetTool],
-  resources: KERNEL_RESOURCES,
   resolveBaseUrl: () => process.env.EXAMPLE_DAEMON_URL ?? 'http://127.0.0.1:4173',
+}, {
+  resources: KERNEL_RESOURCES,
   instructions: 'Use start_run to launch work; poll get_run for status.',
 });
 
-await server.run(); // serves over this process's stdio until idle-exit
+await server.run({}); // serves over this process's stdio until idle-exit
 ```
 
 Read `McpToolDef` in `src/server/` before writing your own tool — the exact `handler` and
@@ -109,16 +138,62 @@ Read `McpToolDef` in `src/server/` before writing your own tool — the exact `h
 without spawning a process or opening a socket. The tool and resource lists are yours — `RUN_TOOLS`
 and `KERNEL_RESOURCES` are convenience defaults, not a fixed set. `createExecuteDelegatedToolTool`
 takes its run scoping from the caller. Fixed and not replaceable: the MCP wire framing itself (that
-is `@modelcontextprotocol/sdk`'s job), the config sanitizers' validation rules, and the OAuth flow's
-step ordering.
+is `@modelcontextprotocol/sdk`'s job), the config sanitizers' validation rules, and the MCP handshake's step ordering.
 
 ## Runtime
 
-`jini.runtime: "node"` — stdio streams, `node:fs` for the config and token stores, `node:crypto` for
-PKCE.
+`jini.runtime: "node"` — stdio streams, `node:fs` for the config and token stores, `node:crypto` for approval fingerprints. Universal entries are the ask-choice tool and
+federation test doubles; federation and approvals require Node for hashing. The stdio entry
+adds process, filesystem, and environment adapters.
 ESM only — ships `"type": "module"` with no CommonJS `require` build.
 
 ## Provenance
 
-See [source-map.md](./source-map.md) for per-file provenance and scope decisions. Apache-2.0,
+See the archived provenance ledger for per-file provenance and scope decisions. Apache-2.0,
 inherited from Open Design — see the repo `NOTICE`.
+
+## Federation entries
+
+`@jini-ai/mcp/federation` exposes admission/trust, protocol/HTTP sessions, bootstrap, reload,
+fingerprints, and approval/revocation orchestration. Import process adapters and launch resolvers
+from `@jini-ai/mcp/federation/stdio`, and in-memory sessions, scripted transports, and approval
+stores from `@jini-ai/mcp/federation/testing`. The focused approval entry is
+`@jini-ai/mcp/federation/approvals`. These stay separate from the root barrel to avoid naming
+collisions and accidental process-adapter loading.
+
+The host supplies product name, client information, credential policy, permission evaluator,
+confirmation UI/exchanges, and current connection roster. A revocation gate checks the current
+row on every call; the host composes its credential checks, including preset credentials.
+See [API.md](https://github.com/AINSEP/Jini/blob/main/packages/mcp/API.md) for concrete object-argument examples.
+
+All test, compiler, build, and pack verification is deferred under the owner directive.
+
+## Design decisions
+
+- [Remote annotations can narrow authority but cannot grant it](docs/decisions/DR-001-federation-admission.md).
+- [Preserve structured protocol resources without exposing human secrets](docs/decisions/DR-002-protocol-resource-boundary.md).
+- [Federation presets compose trusted ports](docs/decisions/DR-003-trusted-federation-composition.md).
+- [Parked human exchanges need explicit deadlines](docs/decisions/DR-004-parked-human-exchange-deadlines.md).
+
+
+Federation hosts supply `messages`, `errorCode` and `fingerprintDomain` explicitly. Import
+`defaultFederationMessages` as neutral English or replace the full object with host wording.
+Optional opaque `scope` travels separately from approval duration through store and webhook
+ports. Existing approvals retain their fingerprint and storage-key bytes when the host supplies
+its existing domain and partition. Logger and clock ports come from `@jini-ai/core/primitives`.
+See `API.md` for the breaking signatures and the shared atomic writer's durability semantics.
+MCP imports core text sanitization directly and has no dependency on the CLI shell.
+
+## Managed project containment
+
+Managed-project detection resolves real/lexical paths as before, then uses the
+browser-safe `pathContains` helper from `@jini-ai/core/primitives`. Comparison
+follows the host's path case policy and respects directory boundaries. A legal
+project directory beginning with `..` is accepted; escaping the managed root
+or selecting the root itself is still refused. Platform remains required for
+other Node integrations, not for this pure containment check.
+
+Permanent deletion always needs a fresh one-call confirmation. Destructive cards offer neither
+chat nor always approval; matching remembered grants cannot skip them, and forged remember choices
+are discarded. Write-shaped protected calls also remain unrememberable. The host must keep its
+persisted fingerprint domain stable when adopting federation; changing it invalidates saved grants.

package/dist/agent-install/install.d.ts

@@ -18,7 +18,11 @@ export type AgentSlug = (typeof AGENT_SLUGS)[number];
  * @param value The string to test.
  * @returns `true` if `value` is a valid `AgentSlug`, `false` otherwise.
  */
-export declare function isAgentSlug(value: string): value is AgentSlug;
+export declare function isAgentSlug(args: {
+    value: string;
+}): args is {
+    value: AgentSlug;
+};
 /** The resolved stdio launch spec — mirrors the relevant fields of
  *  McpInstallPayload (command/args/env). */
 export interface McpLaunchSpec {
@@ -78,7 +82,13 @@ export type InstallPlan = CliInstallPlan | JsonInstallPlan | ManualInstallPlan;
  * Build the registration plan for one agent. Pure — all IO happens in the
  * executor. Throws on an unknown slug so callers surface a clear error.
  */
-export declare function planAgentInstall(slug: AgentSlug, spec: McpLaunchSpec, ctx: PlanContext): InstallPlan;
+export declare function planAgentInstall({ slug, spec, ctx }: {
+    slug: AgentSlug;
+    spec: McpLaunchSpec;
+    ctx: PlanContext;
+}, { env }?: {
+    env?: NodeJS.ProcessEnv;
+}): InstallPlan;
 /**
  * Merge one server entry into existing config text without disturbing the
  * rest. Missing intermediate objects are created. Returns pretty JSON with
@@ -86,12 +96,18 @@ export declare function planAgentInstall(slug: AgentSlug, spec: McpLaunchSpec, c
  * (caller decides whether to bail or back up), or if `plan.keyPath` /
  * `plan.serverKey` contains a dangerous object-path segment (CR-007).
  */
-export declare function applyJsonInstall(existingText: string | null, plan: JsonInstallPlan): string;
+export declare function applyJsonInstall({ existingText, plan }: {
+    existingText: string | null;
+    plan: JsonInstallPlan;
+}): string;
 /**
  * Remove the server entry. Returns the new text, or null when the file did
  * not exist / had nothing to remove (caller treats null as a no-op). Throws
  * if `plan.keyPath` / `plan.serverKey` contains a dangerous object-path
  * segment (CR-007).
  */
-export declare function removeJsonInstall(existingText: string | null, plan: JsonInstallPlan): string | null;
+export declare function removeJsonInstall({ existingText, plan }: {
+    existingText: string | null;
+    plan: JsonInstallPlan;
+}): string | null;
 //# sourceMappingURL=install.d.ts.map

package/dist/agent-install/install.js

@@ -57,8 +57,8 @@ export const AGENT_SLUGS = [
  * @param value The string to test.
  * @returns `true` if `value` is a valid `AgentSlug`, `false` otherwise.
  */
-export function isAgentSlug(value) {
-    return AGENT_SLUGS.includes(value);
+export function isAgentSlug(args) {
+    return AGENT_SLUGS.includes(args.value);
 }
 // RESIDUAL RISK (CR-006 / SEC-RB-002): `-e`/`--env KEY=VALUE` is claude's,
 // codex's, and kimi's own documented `mcp add` CLI contract for passing
@@ -102,7 +102,7 @@ function jsonEntry(spec, extra = {}, envKey = 'env') {
  * Build the registration plan for one agent. Pure — all IO happens in the
  * executor. Throws on an unknown slug so callers surface a clear error.
  */
-export function planAgentInstall(slug, spec, ctx) {
+export function planAgentInstall({ slug, spec, ctx }, { env = process.env } = {}) {
     const { home, platform, serverName } = ctx;
     switch (slug) {
         // ----- CLI-driven agents (idempotent via the agent's own tool) -----
@@ -172,7 +172,7 @@ export function planAgentInstall(slug, spec, ctx) {
             return {
                 kind: 'json',
                 slug,
-                configPath: clineConfigPath(home, platform),
+                configPath: clineConfigPath(home, platform, env.APPDATA),
                 keyPath: ['mcpServers'],
                 serverKey: serverName,
                 entry: jsonEntry(spec, { disabled: false, autoApprove: [] }),
@@ -219,7 +219,7 @@ export function planAgentInstall(slug, spec, ctx) {
             return {
                 kind: 'json',
                 slug,
-                configPath: traeConfigPath(home, platform),
+                configPath: traeConfigPath(home, platform, env.APPDATA),
                 keyPath: ['mcpServers'],
                 serverKey: serverName,
                 entry: jsonEntry(spec),
@@ -263,23 +263,23 @@ export function planAgentInstall(slug, spec, ctx) {
         }
     }
 }
-function clineConfigPath(home, platform) {
+function clineConfigPath(home, platform, suppliedAppData) {
     const rel = path.join('globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json');
     if (platform === 'darwin') {
         return path.join(home, 'Library', 'Application Support', 'Code', 'User', rel);
     }
     if (platform === 'win32') {
-        const appData = process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming');
+        const appData = suppliedAppData ?? path.join(home, 'AppData', 'Roaming');
         return path.join(appData, 'Code', 'User', rel);
     }
     return path.join(home, '.config', 'Code', 'User', rel);
 }
-function traeConfigPath(home, platform) {
+function traeConfigPath(home, platform, suppliedAppData) {
     if (platform === 'darwin') {
         return path.join(home, 'Library', 'Application Support', 'Trae', 'User', 'mcp.json');
     }
     if (platform === 'win32') {
-        const appData = process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming');
+        const appData = suppliedAppData ?? path.join(home, 'AppData', 'Roaming');
         return path.join(appData, 'Trae', 'User', 'mcp.json');
     }
     return path.join(home, '.config', 'Trae', 'User', 'mcp.json');
@@ -317,7 +317,7 @@ function assertSafeJsonInstallPlan(plan) {
  * (caller decides whether to bail or back up), or if `plan.keyPath` /
  * `plan.serverKey` contains a dangerous object-path segment (CR-007).
  */
-export function applyJsonInstall(existingText, plan) {
+export function applyJsonInstall({ existingText, plan }) {
     assertSafeJsonInstallPlan(plan);
     const root = parseJsonObject(existingText, plan.configPath);
     let cursor = root;
@@ -337,7 +337,7 @@ export function applyJsonInstall(existingText, plan) {
  * if `plan.keyPath` / `plan.serverKey` contains a dangerous object-path
  * segment (CR-007).
  */
-export function removeJsonInstall(existingText, plan) {
+export function removeJsonInstall({ existingText, plan }) {
     assertSafeJsonInstallPlan(plan);
     if (existingText == null || existingText.trim() === '')
         return null;

package/dist/bin/serve.d.ts

@@ -4,13 +4,13 @@
  *
  * The bootable `jini-mcp` binary (`package.json`'s `"bin": { "jini-mcp": "./dist/bin/serve.js" }`)
  * — the real executable entry point gap 3's MCP-callback continuation-transport spike needed and
- * did not have (see `packages/daemon/source-map.md`'s "run/chat orchestration gap 3, part 1"
- * addition, and this package's own dated section in `source-map.md`). `../server/tool-server.js`'s
+ * did not have (see `packages/daemon/archived provenance ledger`'s "run/chat orchestration gap 3, part 1"
+ * addition, and this package's own dated section in `archived provenance ledger`). `../server/tool-server.js`'s
  * `createMcpToolServer` was always designed to run as *this process's own* stdio — meant to be a
  * script a client (Claude Code) spawns as its own child subprocess and talks to over that child's
  * stdin/stdout — but until this file, nothing in this package actually was that script.
  *
- * Follows `@jini-ai/cli/main.ts`'s established shape for a bootable, side-effect-guarded, `#!/usr/bin/env
+ * Follows the CLI entry point's established shape for a bootable, side-effect-guarded, `#!/usr/bin/env
  * node` entry point: a named, fully-dependency-injected `serve()` export (importable for tests, or
  * for a consumer building its own bin wrapper around it) plus a bottom-of-file guard that only
  * calls it for real when this module is the actual process entrypoint — mirrors that file's own
@@ -29,19 +29,18 @@
  * other tool this server hosts (`RUN_TOOLS`, `../server/tools/run-tools.js`) is run-agnostic and
  * needed no such scoping.
  *
- * **Daemon-URL resolution** mirrors `@jini-ai/cli/main.ts`'s own posture: no baked-in default, just
- * `resolveDaemonUrl` (`@jini-ai/cli`) wired to a `--daemon-url`-shaped precedence chain — except this
+ * **Daemon-URL resolution** follows the spawning host's environment: no baked-in default, just
+ * `resolveDaemonUrl` (the CLI transport) wired to a `--daemon-url`-shaped precedence chain — except this
  * process has no argv to parse (an MCP client launches it with a fixed `command`/`args`/`env`, not
  * interactive flags), so only the env-var step applies: {@link DAEMON_URL_ENV_VAR}. When unset,
  * `resolveDaemonUrl` throws, and this file's own top-level error boundary turns that into a clean
  * stderr message + non-zero exit rather than an unhandled rejection.
  */
 import type { Readable, Writable } from 'node:stream';
-import { resolveDaemonUrl as resolveDaemonUrlDefault } from '@jini-ai/cli';
 import { createMcpToolServer as createMcpToolServerDefault } from '../server/tool-server.js';
 /** The one run this process is scoped to for its entire lifetime. Set by the spawning daemon, never by the MCP client. */
 export declare const RUN_ID_ENV_VAR = "JINI_RUN_ID";
-/** Checked (only) when resolving the daemon HTTP base URL — see `resolveDaemonUrl`'s own docs; matches `@jini-ai/cli/main.ts`'s identically-named constant. */
+/** Checked (only) when resolving the daemon HTTP base URL — see `resolveDaemonUrl`'s own docs; matches the CLI entry point's identically-named constant. */
 export declare const DAEMON_URL_ENV_VAR = "JINI_DAEMON_URL";
 /**
  * Bearer credential for this process's daemon callbacks, set by the spawning daemon when it issued
@@ -72,15 +71,19 @@ export interface ServeDeps {
     /** @default process.env */
     readonly env?: NodeJS.ProcessEnv;
     /** @default process.stderr.write */
-    readonly writeErr?: (text: string) => void;
+    readonly writeErr?: (args: {
+        text: string;
+    }) => void;
     /** @default process.exit; inject for tests (must not return) */
-    readonly exit?: (code: number) => never;
-    /** @default the real @jini-ai/cli resolveDaemonUrl */
-    readonly resolveDaemonUrl?: typeof resolveDaemonUrlDefault;
+    readonly exit?: (args: {
+        code: number;
+    }) => never;
+    /** @default the real environment-only daemon URL resolution */
+    readonly resolveDaemonUrl?: (required: Record<string, never>, options: McpDaemonUrlOptions) => Promise<string>;
     /** @default the real createMcpToolServer */
     readonly createMcpToolServer?: typeof createMcpToolServerDefault;
     /** Threaded into `execute_delegated_tool`'s per-call correlation id. @default node:crypto randomUUID */
-    readonly generateToolUseId?: () => string;
+    readonly generateToolUseId?: (required: Record<string, never>) => string;
     /** Threaded into every tool's daemon call. @default the global fetch */
     readonly fetchImpl?: typeof fetch;
     /** @default process.stdin */
@@ -88,6 +91,15 @@ export interface ServeDeps {
     /** @default process.stdout */
     readonly stdout?: Writable;
 }
+/** This executable has no flags or discovery phase: its spawning host supplies the environment. */
+export interface McpDaemonUrlOptions {
+    flagUrl: null;
+    env: NodeJS.ProcessEnv;
+    envVarName: string;
+    warn: (required: {
+        message: string;
+    }) => void;
+}
 /**
  * Assembles and runs the `jini-mcp` stdio MCP server: `RUN_ID_ENV_VAR` (required — this process
  * has no meaningful default run to serve) plus `DAEMON_URL_ENV_VAR` resolution, then hosts
@@ -96,5 +108,5 @@ export interface ServeDeps {
  * idle-exit window elapses (`createMcpToolServer`'s own default) — never bare-throws: every error
  * path below writes a message to `writeErr` and calls `exit(1)` instead.
  */
-export declare function serve(deps?: ServeDeps): Promise<void>;
+export declare function serve(_requiredArgs: Record<string, never>, deps?: ServeDeps): Promise<void>;
 //# sourceMappingURL=serve.d.ts.map