@jini-ai/cli 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# @jini-ai/cli
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- Shared sanitization now comes from core/text and loopback policy from platform/net. Public helpers use required/optional argument objects.
+- 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
+
+- Fix command and discovery test calls to match required/optional argument objects, and create the command-registry token with core's `{ id }` argument.
+
+- **BREAKING:** Remove CLI sanitizeUntrustedText/SanitizeTextOptions/stripControlSequences exports;
+  callers import core/text. Remove redactSecretLike in favor of core redactSecrets with explicit
+  aggressive policy for former direct opaque-token users. Its category markers and PII masking
+  are covered by migration vectors; core's default remains conservative. Terminal transport and
+  recursive JSON sanitization keep their frozen lowercase output.
+- Depend on platform/net for daemon URL loopback checks; recognize full IPv4 loopback range and
+  dotted localhost. Mapped IPv6 retains remote-warning behavior. Tests are written, not run.
+
+- Emit structured JSON HTTP failures through injected ports for unknown codes, response-size and
+  body-read failures. Include the truncation marker within diagnostic maxLength and correct the
+  binary version rationale. Regression tests are written, not run (owner directive).
+
+- **BREAKING:** Public helpers, command handlers/registrations and injected I/O ports now take required and optional argument objects. Output, exit, warning and file-reader ports receive `{ text }`, `{ code }`, `{ message }` and `{ path }`. See `API.md` and the archived migration inventory.
+- Expose introspection from the library barrel and declare its universal runtime without importing the binary entrypoint.
+
+- Add an introspection subpath for structural Commander trees and MCP schemas with required host exclusions and tool-name prefix.
+
+## 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/core@0.1.2
+  - @jini-ai/sidecar@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/core@0.1.1
+  - @jini-ai/sidecar@0.1.1

package/README.md

@@ -5,7 +5,7 @@ local daemon discovery, and a pluggable command registry. This is deliberately *
 slice, not the full `@jini-ai/cli` package** — it was extracted from Open Design's ~9,900-line
 `cli.ts` by keeping only the transport/plumbing primitives that have nothing to do with any
 product noun (project, plugin, brand, conversation, …); everything OD-domain-specific was left
-behind (see `source-map.md`'s classification table). The library barrel (`index.ts`) intentionally
+behind (see the archived provenance ledger's classification table). The library barrel (`index.ts`) intentionally
 registers nothing — it ships the building blocks a host pack uses to register real commands, plus
 a small set of concrete commands (`run`, `daemon`, `version`) that wrap `@jini-ai/http`'s actual
 routes, and a bootable `jini` binary (`src/main.ts`, wired via `package.json`'s `bin` field) that
@@ -33,27 +33,27 @@ No peer dependencies. Depends on `@jini-ai/core` (for the `token()`-based transp
 - **Structured errors** — `exitWithStructuredError`, `DEFAULT_CLI_EXIT_CODES`,
   `structuredErrorData` — maps an error code to a stable exit code and a `{ error: { code,
   message, data } }` stderr envelope.
-- **Command registry** — `CommandRegistry` (`.add(name, handler, { usage?, override? })`,
-  `.dispatch(argv, { valueFlags? })`), `CommandDispatchResult`, `CommandHandler` — the generic
+- **Command registry** — `CommandRegistry` (`.add({ name, handler }, { usage?, override? })`,
+  `.dispatch({ argv }, { valueFlags? })`), `CommandDispatchResult`, `CommandHandler` — the generic
   "first-non-flag-token dispatch" shape a pack's `Pack['cli']` hook registers against.
 - **Built-in commands** — `registerRunCommands` (`run start|list|get|cancel|watch`),
   `registerDaemonCommands` (`daemon status|stop`), `registerVersionCommand` (`version`) — each a
   thin transport over `@jini-ai/http`'s run/daemon-status routes.
 - **Prompt/body input helpers** — `readPromptFromFlags`/`readBodyFromFlags` (`--prompt`/
-  `--prompt-file`/stdin conventions) and `redact.ts`'s `stripControlSequences`.
+  `--prompt-file`/stdin conventions) and `@jini-ai/core/text`'s `stripControlSequences`.
 
 ## Usage
 
 ```ts
 import { CommandRegistry, resolveDaemonUrl, registerRunCommands, exitWithStructuredError } from '@jini-ai/cli';
 
-const registry = new CommandRegistry();
+const registry = new CommandRegistry({});
 
-registerRunCommands(registry, {
-  resolveBaseUrl: () => resolveDaemonUrl({ envVarName: 'JINI_DAEMON_URL', defaultUrl: 'http://127.0.0.1:4317' }),
+registerRunCommands({ registry,
+  resolveBaseUrl: () => resolveDaemonUrl({}, { envVarName: 'JINI_DAEMON_URL', defaultUrl: 'http://127.0.0.1:4317' }),
 });
 
-const result = await registry.dispatch(process.argv.slice(2));
+const result = await registry.dispatch({ argv: process.argv.slice(2) });
 if (result.kind === 'not-found') {
   exitWithStructuredError({ code: 'invalid-flag', message: `unknown command "${result.name}"` });
 }
@@ -64,9 +64,11 @@ and run its `jini` binary directly (`npx jini run list --daemon-url http://127.0
 
 ## What's swappable
 
+Command handlers and registrars receive `resolveBaseUrl` in the required argument object; optional I/O ports belong in the second object. Call a discovery probe with `discover({ env }, { timeoutMs })`.
+
 `resolveDaemonUrl`'s `discover` callback is the intended injection point for daemon-discovery
 strategy — `createLocalDaemonDiscovery` is the one concrete implementation shipped, but any
-`(env, timeoutMs) => Promise<string | null>` works. `CommandRegistry` itself is the seam a pack
+`({ env }, { timeoutMs }) => Promise<string | null>` works. `CommandRegistry` itself is the seam a pack
 uses to add or `override` commands. The exit-code table (`DEFAULT_CLI_EXIT_CODES`) is a small
 default a caller extends with its own `code → exitCode` entries rather than a fixed, closed set.
 
@@ -77,4 +79,19 @@ 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.
+
+## Introspection and I/O ports
+
+The universal `./introspection` entry reads structural Commander trees and builds MCP schemas with caller-owned exclusions and tool-name prefixes. It is also exported from the Node library barrel. The binary stays separate. See [API.md](https://github.com/AINSEP/Jini/blob/main/packages/cli/API.md) for the object argument convention, including injected I/O ports.
+
+## Design decisions
+
+- [Introspection derives from the live command tree](docs/decisions/DR-001-live-command-introspection.md).
+
+
+Text sanitization and terminal control stripping now live at `@jini-ai/core/text`, with their
+bounded lowercase-marker output preserved. Former direct `redactSecretLike` callers use core
+`redactSecrets({ input }, { policy: 'aggressive' })`; this explicit policy emits category markers
+and also masks recognized PII. Core's default stays conservative for diagnostics. The CLI keeps
+`sanitizeUnknownDeep` for bounded recursive JSON. Loopback warnings use `@jini-ai/platform/net`.

package/dist/command-registry.d.ts

@@ -2,14 +2,16 @@
  * @module command-registry
  *
  * The generic dispatcher shape behind OD's `SUBCOMMAND_MAP` (see
- * `source-map.md`): look at the first non-flag `argv` token, dispatch to a
+ * `archived provenance ledger`): look at the first non-flag `argv` token, dispatch to a
  * registered handler, or report that nothing matched so the caller can fall
  * back to root help. OD's actual map (33 product command names) was not
  * ported — only the registrar pattern, which is what `@jini-ai/core`'s
  * `Pack['cli']` hook (`cli?: (reg: unknown, services: Services) => void`)
  * needs a concrete `reg` type for.
  */
-export type CommandHandler = (args: readonly string[]) => void | Promise<void>;
+export type CommandHandler = (requiredArgs: {
+    args: readonly string[];
+}) => void | Promise<void>;
 export type CommandDispatchResult = {
     kind: 'handled';
 } | {
@@ -53,17 +55,25 @@ export interface CommandDispatchOptions {
  * to skip over a value-flag's value while scanning for the command name.
  */
 export declare class CommandRegistry {
+    constructor(_requiredArgs?: Record<string, never>);
     private readonly commands;
     /**
      * Register a command. Throws if `name` is already registered — pass
      * `{ override: true }` to intentionally replace an existing registration.
      */
-    add(name: string, handler: CommandHandler, opts?: AddCommandOptions): this;
-    has(name: string): boolean;
+    add({ name, handler }: {
+        name: string;
+        handler: CommandHandler;
+    }, opts?: AddCommandOptions): this;
+    has({ name }: {
+        name: string;
+    }): boolean;
     /** The usage text registered alongside `name`, if any. */
-    usageFor(name: string): string | undefined;
+    usageFor({ name }: {
+        name: string;
+    }): string | undefined;
     /** Every registered command name, insertion order. */
-    names(): string[];
+    names(_requiredArgs?: Record<string, never>): string[];
     /**
      * Find the first non-`-`-prefixed token in `argv`, look up its handler,
      * and invoke it with every other token (flags before *and* after the
@@ -77,6 +87,8 @@ export declare class CommandRegistry {
      * `options.valueFlags` — the set of global `--flag` names that consume the
      * next token as a value — so the scan skips over it instead.
      */
-    dispatch(argv: readonly string[], options?: CommandDispatchOptions): Promise<CommandDispatchResult>;
+    dispatch({ argv }: {
+        argv: readonly string[];
+    }, options?: CommandDispatchOptions): Promise<CommandDispatchResult>;
 }
 //# sourceMappingURL=command-registry.d.ts.map

package/dist/command-registry.js

@@ -2,7 +2,7 @@
  * @module command-registry
  *
  * The generic dispatcher shape behind OD's `SUBCOMMAND_MAP` (see
- * `source-map.md`): look at the first non-flag `argv` token, dispatch to a
+ * `archived provenance ledger`): look at the first non-flag `argv` token, dispatch to a
  * registered handler, or report that nothing matched so the caller can fall
  * back to root help. OD's actual map (33 product command names) was not
  * ported — only the registrar pattern, which is what `@jini-ai/core`'s
@@ -18,27 +18,28 @@
  * to skip over a value-flag's value while scanning for the command name.
  */
 export class CommandRegistry {
+    constructor(_requiredArgs = {}) { }
     commands = new Map();
     /**
      * Register a command. Throws if `name` is already registered — pass
      * `{ override: true }` to intentionally replace an existing registration.
      */
-    add(name, handler, opts = {}) {
+    add({ name, handler }, opts = {}) {
         if (this.commands.has(name) && opts.override !== true) {
             throw new Error(`command "${name}" is already registered; pass { override: true } to replace it intentionally`);
         }
         this.commands.set(name, { name, handler, ...(opts.usage !== undefined ? { usage: opts.usage } : {}) });
         return this;
     }
-    has(name) {
+    has({ name }) {
         return this.commands.has(name);
     }
     /** The usage text registered alongside `name`, if any. */
-    usageFor(name) {
+    usageFor({ name }) {
         return this.commands.get(name)?.usage;
     }
     /** Every registered command name, insertion order. */
-    names() {
+    names(_requiredArgs = {}) {
         return [...this.commands.keys()];
     }
     /**
@@ -54,7 +55,7 @@ export class CommandRegistry {
      * `options.valueFlags` — the set of global `--flag` names that consume the
      * next token as a value — so the scan skips over it instead.
      */
-    async dispatch(argv, options = {}) {
+    async dispatch({ argv }, options = {}) {
         const valueFlags = options.valueFlags ?? new Set();
         let index = -1;
         for (let i = 0; i < argv.length; i++) {
@@ -81,7 +82,7 @@ export class CommandRegistry {
         if (command === undefined)
             return { kind: 'not-found', name };
         const rest = [...argv.slice(0, index), ...argv.slice(index + 1)];
-        await command.handler(rest);
+        await command.handler({ args: rest });
         return { kind: 'handled' };
     }
 }

package/dist/daemon-command.d.ts

@@ -3,7 +3,7 @@
  *
  * `daemon status` / `daemon stop` — concrete commands over `@jini-ai/http-kit`'s
  * `daemonStatusRoute`/`daemonShutdownRoute` (`packages/http/src/daemon-status.ts`).
- * `packages/cli/source-map.md`'s original UNCLEAR verdict on these two
+ * `packages/cli/archived provenance ledger`'s original UNCLEAR verdict on these two
  * blocked on `@jini-ai/http-kit` being a stub with no `/status`/`/shutdown` route to
  * call; that blocker no longer holds (both routes exist and are tested), and
  * `run-command.ts` is now a real, established "first concrete command"
@@ -23,20 +23,35 @@ export interface DaemonCommandDeps {
     /** Resolves the daemon HTTP base URL once per command invocation (e.g. wraps `resolveDaemonUrl`). */
     resolveBaseUrl: () => Promise<string> | string;
     /** Defaults to `process.stdout.write`; inject for tests. Used for successful command output. */
-    write?: (text: string) => void;
+    write?: (requiredArgs: {
+        text: string;
+    }) => void;
     /** Defaults to `process.stderr.write`; inject for tests. Used for usage/validation errors. */
-    writeErr?: (text: string) => void;
+    writeErr?: (requiredArgs: {
+        text: string;
+    }) => void;
     /** Defaults to the global `fetch`; inject for tests. */
     fetchImpl?: typeof fetch;
     /** Defaults to `process.exit`; inject for tests (must not return). */
-    exit?: (code: number) => never;
+    exit?: (requiredArgs: {
+        code: number;
+    }) => never;
     /** Extra/overriding `code -> exitCode` entries layered on the package default table. */
     exitCodes?: ExitCodeTable;
 }
 /** `daemon status` */
-export declare function daemonStatusCommand(args: readonly string[], deps: DaemonCommandDeps): Promise<void>;
+export declare function daemonStatusCommand({ args, resolveBaseUrl }: {
+    args: readonly string[];
+    resolveBaseUrl: DaemonCommandDeps["resolveBaseUrl"];
+}, optionalArgs?: Omit<DaemonCommandDeps, "resolveBaseUrl">): Promise<void>;
 /** `daemon stop` */
-export declare function daemonStopCommand(args: readonly string[], deps: DaemonCommandDeps): Promise<void>;
+export declare function daemonStopCommand({ args, resolveBaseUrl }: {
+    args: readonly string[];
+    resolveBaseUrl: DaemonCommandDeps["resolveBaseUrl"];
+}, optionalArgs?: Omit<DaemonCommandDeps, "resolveBaseUrl">): Promise<void>;
 /** Registers `daemon` (dispatching `status`/`stop` on the first remaining token) against `registry`. */
-export declare function registerDaemonCommands(registry: CommandRegistry, deps: DaemonCommandDeps): void;
+export declare function registerDaemonCommands({ registry, resolveBaseUrl }: {
+    registry: CommandRegistry;
+    resolveBaseUrl: DaemonCommandDeps["resolveBaseUrl"];
+}, optionalArgs?: Omit<DaemonCommandDeps, "resolveBaseUrl">): void;
 //# sourceMappingURL=daemon-command.d.ts.map

package/dist/daemon-command.js

@@ -3,7 +3,7 @@
  *
  * `daemon status` / `daemon stop` — concrete commands over `@jini-ai/http-kit`'s
  * `daemonStatusRoute`/`daemonShutdownRoute` (`packages/http/src/daemon-status.ts`).
- * `packages/cli/source-map.md`'s original UNCLEAR verdict on these two
+ * `packages/cli/archived provenance ledger`'s original UNCLEAR verdict on these two
  * blocked on `@jini-ai/http-kit` being a stub with no `/status`/`/shutdown` route to
  * call; that blocker no longer holds (both routes exist and are tested), and
  * `run-command.ts` is now a real, established "first concrete command"
@@ -20,29 +20,20 @@
 import { exitWithStructuredError } from './errors.js';
 import { getJsonFromDaemon, postJsonToDaemon } from './http.js';
 import { renderUsage } from './usage.js';
-function defaultWrite(text) {
+function defaultWrite({ text }) {
     process.stdout.write(text);
 }
-function defaultWriteErr(text) {
+function defaultWriteErr({ text }) {
     process.stderr.write(text);
 }
-const DAEMON_STATUS_USAGE = renderUsage({
-    usage: ['daemon status'],
-    description: 'Reports the running daemon\'s version/host/port/dataDir/shutdown state.',
-});
-const DAEMON_STOP_USAGE = renderUsage({
-    usage: ['daemon stop'],
-    description: 'Schedules a graceful daemon shutdown. Responds once the shutdown is scheduled, not once the process has actually exited.',
-});
-const DAEMON_USAGE = renderUsage({
-    usage: ['daemon <status|stop> ...'],
-    description: 'Inspect or control a running Jini daemon over HTTP.',
-});
+const DAEMON_STATUS_USAGE = renderUsage({ usage: ['daemon status'] }, { description: 'Reports the running daemon\'s version/host/port/dataDir/shutdown state.' });
+const DAEMON_STOP_USAGE = renderUsage({ usage: ['daemon stop'] }, { description: 'Schedules a graceful daemon shutdown. Responds once the shutdown is scheduled, not once the process has actually exited.' });
+const DAEMON_USAGE = renderUsage({ usage: ['daemon <status|stop> ...'] }, { description: 'Inspect or control a running Jini daemon over HTTP.' });
 /** Builds `{write, exit, exitCodes?}` for `errors.ts`'s structured-error helpers, never assigning `exitCodes` when unset (required under `exactOptionalPropertyTypes`). */
 function errorOptions(deps) {
     return {
         write: deps.writeErr ?? defaultWriteErr,
-        exit: deps.exit ?? ((code) => process.exit(code)),
+        exit: deps.exit ?? (({ code }) => process.exit(code)),
         ...(deps.exitCodes !== undefined ? { exitCodes: deps.exitCodes } : {}),
     };
 }
@@ -59,45 +50,48 @@ function invalidFlag(deps, message) {
     return exitWithStructuredError({ code: 'invalid-flag', message }, errorOptions(deps));
 }
 function printJsonResult(deps, value) {
-    (deps.write ?? defaultWrite)(`${JSON.stringify(value)}\n`);
+    (deps.write ?? defaultWrite)({ text: `${JSON.stringify(value)}\n` });
 }
 /** `daemon status` */
-export async function daemonStatusCommand(args, deps) {
+export async function daemonStatusCommand({ args, resolveBaseUrl }, optionalArgs = {}) {
+    const deps = { resolveBaseUrl, ...optionalArgs };
     if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)(`${DAEMON_STATUS_USAGE}\n`);
+        (deps.write ?? defaultWrite)({ text: `${DAEMON_STATUS_USAGE}\n` });
         return;
     }
     const baseUrl = await deps.resolveBaseUrl();
-    const result = await getJsonFromDaemon(baseUrl, '/api/daemon/status', transportOptions(deps));
+    const result = await getJsonFromDaemon({ base: baseUrl, route: '/api/daemon/status' }, transportOptions(deps));
     printJsonResult(deps, result);
 }
 /** `daemon stop` */
-export async function daemonStopCommand(args, deps) {
+export async function daemonStopCommand({ args, resolveBaseUrl }, optionalArgs = {}) {
+    const deps = { resolveBaseUrl, ...optionalArgs };
     if (args.includes('--help') || args.includes('-h')) {
-        (deps.write ?? defaultWrite)(`${DAEMON_STOP_USAGE}\n`);
+        (deps.write ?? defaultWrite)({ text: `${DAEMON_STOP_USAGE}\n` });
         return;
     }
     const baseUrl = await deps.resolveBaseUrl();
-    const result = await postJsonToDaemon(baseUrl, '/api/daemon/shutdown', {}, transportOptions(deps));
+    const result = await postJsonToDaemon({ base: baseUrl, route: '/api/daemon/shutdown', body: {} }, transportOptions(deps));
     printJsonResult(deps, result);
 }
 /** Registers `daemon` (dispatching `status`/`stop` on the first remaining token) against `registry`. */
-export function registerDaemonCommands(registry, deps) {
-    registry.add('daemon', async (args) => {
-        const [sub, ...rest] = args;
-        switch (sub) {
-            case 'status':
-                return daemonStatusCommand(rest, deps);
-            case 'stop':
-                return daemonStopCommand(rest, deps);
-            case undefined:
-            case '--help':
-            case '-h':
-                (deps.write ?? defaultWrite)(`${DAEMON_USAGE}\n`);
-                return;
-            default:
-                invalidFlag(deps, `unknown "daemon" subcommand: ${sub}`);
-        }
-    }, { usage: DAEMON_USAGE });
+export function registerDaemonCommands({ registry, resolveBaseUrl }, optionalArgs = {}) {
+    const deps = { resolveBaseUrl, ...optionalArgs };
+    registry.add({ name: 'daemon', handler: async ({ args }) => {
+            const [sub, ...rest] = args;
+            switch (sub) {
+                case 'status':
+                    return daemonStatusCommand({ args: rest, resolveBaseUrl: resolveBaseUrl }, optionalArgs);
+                case 'stop':
+                    return daemonStopCommand({ args: rest, resolveBaseUrl: resolveBaseUrl }, optionalArgs);
+                case undefined:
+                case '--help':
+                case '-h':
+                    (deps.write ?? defaultWrite)({ text: `${DAEMON_USAGE}\n` });
+                    return;
+                default:
+                    invalidFlag(deps, `unknown "daemon" subcommand: ${sub}`);
+            }
+        } }, { usage: DAEMON_USAGE });
 }
 //# sourceMappingURL=daemon-command.js.map

package/dist/daemon-url.d.ts

@@ -2,7 +2,7 @@
  * @module daemon-url
  *
  * Generic daemon-URL resolution, generalized from OD's
- * `apps/daemon/src/daemon-url.ts` (see `source-map.md`). The *order* —
+ * `apps/daemon/src/daemon-url.ts` (see `archived provenance ledger`). The *order* —
  * explicit flag, then an env var, then an injected discovery probe, then a
  * caller-supplied default — is the reusable part. OD's own implementation
  * hardcodes its sidecar IPC protocol and a `pnpm exec tools-dev status`
@@ -26,7 +26,11 @@ export interface ResolveDaemonUrlOptions {
      * `null` when nothing was discovered so resolution falls through to
      * `defaultUrl`.
      */
-    discover?: (env: NodeJS.ProcessEnv, timeoutMs: number) => Promise<string | null>;
+    discover?: (requiredArgs: {
+        env: NodeJS.ProcessEnv;
+    }, optionalArgs: {
+        timeoutMs: number;
+    }) => Promise<string | null>;
     /** Discovery timeout in ms. Defaults to 800ms so an absent daemon doesn't stall CLI startup. */
     timeoutMs?: number;
     /** Returned when the flag, env, and discovery steps all come up empty. */
@@ -36,7 +40,9 @@ export interface ResolveDaemonUrlOptions {
      * succeeds. Defaults to a no-op. A user's own daemon may legitimately run
      * on a remote, non-HTTPS host, so this only warns — it never rejects.
      */
-    warn?: (message: string) => void;
+    warn?: (requiredArgs: {
+        message: string;
+    }) => void;
 }
 /**
  * Resolve a daemon HTTP base URL for a CLI client command.
@@ -47,7 +53,7 @@ export interface ResolveDaemonUrlOptions {
  * `http://127.0.0.1:0`-style fallback would be worse than a clear error,
  * and this package has no locked default port to fall back to on its own.
  */
-export declare function resolveDaemonUrl(options?: ResolveDaemonUrlOptions): Promise<string>;
+export declare function resolveDaemonUrl(_requiredArgs: Record<string, never>, options?: ResolveDaemonUrlOptions): Promise<string>;
 /**
  * Return `url` with any embedded userinfo (`user:pass@host`) stripped, safe to include in a
  * printed error message, log line, or structured-error envelope. Per SEC-RB-009
@@ -56,7 +62,9 @@ export declare function resolveDaemonUrl(options?: ResolveDaemonUrlOptions): Pro
  * reach stderr/stdout verbatim. Returns `url` unchanged when it has no userinfo, so normal URLs
  * are never reformatted/normalized as a side effect of display-sanitizing them.
  */
-export declare function sanitizeDaemonUrlForDisplay(url: string): string;
+export declare function sanitizeDaemonUrlForDisplay({ url }: {
+    url: string;
+}): string;
 /**
  * Non-fatal policy check for a resolved daemon URL: warn (never throw or reject) when it is
  * neither loopback nor HTTPS, since that combination sends CLI traffic — including whatever
@@ -64,5 +72,7 @@ export declare function sanitizeDaemonUrlForDisplay(url: string): string;
  * `null` when the URL looks safe or doesn't parse (a parse failure is reported elsewhere, by
  * whatever code actually tries to use the URL).
  */
-export declare function daemonUrlPolicyWarning(url: string): string | null;
+export declare function daemonUrlPolicyWarning({ url }: {
+    url: string;
+}): string | null;
 //# sourceMappingURL=daemon-url.d.ts.map

package/dist/daemon-url.js

@@ -1,15 +1,4 @@
-/**
- * @module daemon-url
- *
- * Generic daemon-URL resolution, generalized from OD's
- * `apps/daemon/src/daemon-url.ts` (see `source-map.md`). The *order* —
- * explicit flag, then an env var, then an injected discovery probe, then a
- * caller-supplied default — is the reusable part. OD's own implementation
- * hardcodes its sidecar IPC protocol and a `pnpm exec tools-dev status`
- * fallback; neither belongs in a product-neutral package, so both are
- * replaced with an injected `discover` callback the caller (e.g. a future
- * `@jini-ai/sidecar`-backed adapter) supplies.
- */
+import { isLoopbackHostname } from '@jini-ai/platform/net';
 /**
  * Resolve a daemon HTTP base URL for a CLI client command.
  *
@@ -19,13 +8,13 @@
  * `http://127.0.0.1:0`-style fallback would be worse than a clear error,
  * and this package has no locked default port to fall back to on its own.
  */
-export async function resolveDaemonUrl(options = {}) {
+export async function resolveDaemonUrl(_requiredArgs, options = {}) {
     const env = options.env ?? process.env;
     const warn = options.warn ?? (() => { });
     const report = (url) => {
-        const warning = daemonUrlPolicyWarning(url);
+        const warning = daemonUrlPolicyWarning({ url });
         if (warning !== null)
-            warn(warning);
+            warn({ message: warning });
         return url;
     };
     const flagUrl = options.flagUrl ?? null;
@@ -37,7 +26,7 @@ export async function resolveDaemonUrl(options = {}) {
             return report(envUrl);
     }
     if (options.discover !== undefined) {
-        const discovered = await options.discover(env, options.timeoutMs ?? 800);
+        const discovered = await options.discover({ env }, { timeoutMs: options.timeoutMs ?? 800 });
         if (discovered !== null && discovered.length > 0)
             return report(discovered);
     }
@@ -58,7 +47,7 @@ const USERINFO_PREFIX_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^/@]*@/;
  * reach stderr/stdout verbatim. Returns `url` unchanged when it has no userinfo, so normal URLs
  * are never reformatted/normalized as a side effect of display-sanitizing them.
  */
-export function sanitizeDaemonUrlForDisplay(url) {
+export function sanitizeDaemonUrlForDisplay({ url }) {
     let parsed;
     try {
         parsed = new URL(url);
@@ -72,10 +61,6 @@ export function sanitizeDaemonUrlForDisplay(url) {
     parsed.password = '';
     return parsed.toString();
 }
-const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
-function isLoopbackHostname(hostname) {
-    return LOOPBACK_HOSTNAMES.has(hostname.toLowerCase());
-}
 /**
  * Non-fatal policy check for a resolved daemon URL: warn (never throw or reject) when it is
  * neither loopback nor HTTPS, since that combination sends CLI traffic — including whatever
@@ -83,7 +68,7 @@ function isLoopbackHostname(hostname) {
  * `null` when the URL looks safe or doesn't parse (a parse failure is reported elsewhere, by
  * whatever code actually tries to use the URL).
  */
-export function daemonUrlPolicyWarning(url) {
+export function daemonUrlPolicyWarning({ url }) {
     let parsed;
     try {
         parsed = new URL(url);
@@ -91,9 +76,9 @@ export function daemonUrlPolicyWarning(url) {
     catch {
         return null;
     }
-    if (parsed.protocol === 'https:' || isLoopbackHostname(parsed.hostname))
+    if (parsed.protocol === 'https:' || isLoopbackHostname({ hostname: parsed.hostname }))
         return null;
-    return (`daemon URL ${sanitizeDaemonUrlForDisplay(url)} is neither loopback nor HTTPS; ` +
+    return (`daemon URL ${sanitizeDaemonUrlForDisplay({ url: url })} is neither loopback nor HTTPS; ` +
         'traffic to a remote, non-HTTPS daemon is not encrypted.');
 }
 //# sourceMappingURL=daemon-url.js.map