@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/childStderr.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Child-process stderr guard (issue #17).
+ *
+ * MCP servers spawned through `@deepseek-ai/dsh-mcp-client` run under the MCP
+ * SDK's `StdioClientTransport`, whose stderr defaults to `'inherit'`
+ * (`stdio: ['pipe', 'pipe', server.stderr ?? 'inherit']`). An inherited fd 2
+ * is written by the CHILD process straight to the terminal device — those
+ * bytes never pass through this process's patched `process.stderr.write`
+ * (see `ink.tsx` patchStderr), so they land at the parked cursor, scroll the
+ * alt-screen, and interleave with the diff renderer's absolute-coordinate
+ * writes. A server in a reconnect loop (e.g. a proxy repeatedly printing
+ * `Error: Non-HTTPS URLs ...` + its usage line) turns that into the
+ * overlapping garbage shown in the issue screenshot.
+ *
+ * The guard patches `child_process.spawn` and rewrites requests whose stderr
+ * would be inherited (`'inherit'` as the whole-stdio string, stdio array slot
+ * 2, or raw fd 2) to a pipe, then drains the pipe line by line into a sink.
+ * Only fd 2 is touched; stdin/stdout keep their requested modes, so MCP's
+ * JSON-RPC stdio channel is unaffected.
+ *
+ * Reachability note: the MCP SDK spawns via `cross-spawn`, which reads
+ * `child_process.spawn` off the CJS exports object at call time, so this
+ * patch covers it (verified by scripts/verify-child-stderr.tsx). A consumer
+ * holding a snapshotted ESM named import (`import { spawn } from
+ * 'node:child_process'`) would bypass the patch — no known consumer in the
+ * dependency tree does that.
+ */
+/**
+ * Take over inherited child stderr for the TUI's lifetime: any `spawn` whose
+ * stderr would hit the terminal directly is piped and drained into `sink`
+ * instead. Returns a restore function that reverts the patch; in-flight
+ * children keep their (already piped) streams.
+ */
+export declare function installChildStderrGuard(sink: (line: string) => void): () => void;
+/** Notification callback signature — structurally `Channel['notify']`. */
+export interface ChildStderrNotify {
+    (text: string, options?: {
+        color?: 'error' | 'warning' | 'success';
+        timeoutMs?: number;
+    }): void;
+}
+export interface ChildStderrReporterOptions {
+    /** Quiet window that batches a burst of repeats into one notice (default 1500ms). */
+    debounceMs?: number;
+    /** After a notice, the same line stays silent for this long (default 30s). */
+    cooldownMs?: number;
+    /** Single-line length cap; longer lines are truncated with an ellipsis (default 200). */
+    maxLineLength?: number;
+}
+export interface ChildStderrReporter {
+    /** Feed one raw stderr line. */
+    push(line: string): void;
+    /** Cancel pending debounce timers (teardown). */
+    dispose(): void;
+}
+/**
+ * Turn a raw child-stderr line stream into bounded, deduplicated
+ * notifications: identical lines inside a short debounce window collapse into
+ * one "（重复 N 次）" notice, and a line that was just shown stays silent for
+ * a cooldown so a failing reconnect loop can't spam the status area.
+ */
+export declare function createChildStderrReporter(notify: ChildStderrNotify, options?: ChildStderrReporterOptions): ChildStderrReporter;
+//# sourceMappingURL=childStderr.d.ts.map

package/lib/types/dsh-adapter/childStderr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"childStderr.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/childStderr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAgEH;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CA8BhF;AAED,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAChG;AAED,MAAM,WAAW,0BAA0B;IACzC,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,iDAAiD;IACjD,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,CAqDrB"}

package/lib/types/dsh-adapter/childStderr.js

@@ -0,0 +1,180 @@
+/**
+ * Child-process stderr guard (issue #17).
+ *
+ * MCP servers spawned through `@deepseek-ai/dsh-mcp-client` run under the MCP
+ * SDK's `StdioClientTransport`, whose stderr defaults to `'inherit'`
+ * (`stdio: ['pipe', 'pipe', server.stderr ?? 'inherit']`). An inherited fd 2
+ * is written by the CHILD process straight to the terminal device — those
+ * bytes never pass through this process's patched `process.stderr.write`
+ * (see `ink.tsx` patchStderr), so they land at the parked cursor, scroll the
+ * alt-screen, and interleave with the diff renderer's absolute-coordinate
+ * writes. A server in a reconnect loop (e.g. a proxy repeatedly printing
+ * `Error: Non-HTTPS URLs ...` + its usage line) turns that into the
+ * overlapping garbage shown in the issue screenshot.
+ *
+ * The guard patches `child_process.spawn` and rewrites requests whose stderr
+ * would be inherited (`'inherit'` as the whole-stdio string, stdio array slot
+ * 2, or raw fd 2) to a pipe, then drains the pipe line by line into a sink.
+ * Only fd 2 is touched; stdin/stdout keep their requested modes, so MCP's
+ * JSON-RPC stdio channel is unaffected.
+ *
+ * Reachability note: the MCP SDK spawns via `cross-spawn`, which reads
+ * `child_process.spawn` off the CJS exports object at call time, so this
+ * patch covers it (verified by scripts/verify-child-stderr.tsx). A consumer
+ * holding a snapshotted ESM named import (`import { spawn } from
+ * 'node:child_process'`) would bypass the patch — no known consumer in the
+ * dependency tree does that.
+ */
+import childProcess from 'node:child_process';
+import { t } from '../i18n.js';
+/** Strip ANSI escape sequences (CSI/OSC) so raw child output can't inject
+ *  cursor moves or colors into the notification area. */
+// eslint-disable-next-line no-control-regex -- intentional: matching terminal escape sequences
+const ANSI_PATTERN = /[\u001b\u009b][[\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+/**
+ * Rewrite spawn options so an inherited stderr (fd 2) becomes a pipe.
+ * Returns the adjusted options, or undefined when stderr is not inherited
+ * (default/'pipe'/'ignore'/explicit stream) and the spawn needs no takeover.
+ */
+function redirectInheritedStderr(options) {
+    const stdio = options.stdio;
+    if (stdio === undefined || stdio === null)
+        return undefined;
+    if (typeof stdio === 'string') {
+        // The string form applies to all three fds; keep stdin/stdout inherited.
+        if (stdio !== 'inherit')
+            return undefined;
+        return { ...options, stdio: ['inherit', 'inherit', 'pipe'] };
+    }
+    if (Array.isArray(stdio)) {
+        // A short array leaves fd 2 at the 'pipe' default — already safe.
+        const stderr = stdio[2];
+        if (stderr !== 'inherit' && stderr !== 2)
+            return undefined;
+        const next = [...stdio];
+        next[2] = 'pipe';
+        return { ...options, stdio: next };
+    }
+    return undefined;
+}
+/** Cap on the unterminated tail: a child that never emits a newline (progress
+ * bars, single-line JSON streams) must not grow the line buffer without bound
+ * — past the cap the partial line is flushed to the sink (which applies its
+ * own display-length truncation) and the buffer restarts empty. */
+const MAX_PENDING_CHARS = 64 * 1024;
+/** Drain a piped stderr stream, forwarding complete lines (and the unterminated tail) to the sink. */
+function drainLines(stream, sink) {
+    let pending = '';
+    stream.on('data', (chunk) => {
+        pending += chunk.toString();
+        let newline = pending.indexOf('\n');
+        while (newline >= 0) {
+            sink(pending.slice(0, newline));
+            pending = pending.slice(newline + 1);
+            newline = pending.indexOf('\n');
+        }
+        if (pending.length > MAX_PENDING_CHARS) {
+            sink(pending);
+            pending = '';
+        }
+    });
+    stream.on('end', () => {
+        if (pending.length > 0)
+            sink(pending);
+    });
+    stream.on('error', () => {
+        // A broken stderr pipe must never take the TUI down.
+    });
+}
+/**
+ * Take over inherited child stderr for the TUI's lifetime: any `spawn` whose
+ * stderr would hit the terminal directly is piped and drained into `sink`
+ * instead. Returns a restore function that reverts the patch; in-flight
+ * children keep their (already piped) streams.
+ */
+export function installChildStderrGuard(sink) {
+    const original = childProcess.spawn;
+    const patched = function (command, argsOrOptions, maybeOptions) {
+        let args;
+        let options;
+        if (Array.isArray(argsOrOptions)) {
+            args = argsOrOptions;
+            options = maybeOptions ?? {};
+        }
+        else {
+            args = [];
+            // Array.isArray doesn't exclude `readonly string[]` in the else branch.
+            options = argsOrOptions ?? maybeOptions ?? {};
+        }
+        const redirected = redirectInheritedStderr(options);
+        const child = original.call(childProcess, command, args, redirected ?? options);
+        if (redirected !== undefined && child.stderr !== null) {
+            drainLines(child.stderr, sink);
+        }
+        return child;
+    };
+    childProcess.spawn = patched;
+    return () => {
+        if (childProcess.spawn === patched) {
+            childProcess.spawn = original;
+        }
+    };
+}
+/**
+ * Turn a raw child-stderr line stream into bounded, deduplicated
+ * notifications: identical lines inside a short debounce window collapse into
+ * one "（重复 N 次）" notice, and a line that was just shown stays silent for
+ * a cooldown so a failing reconnect loop can't spam the status area.
+ */
+export function createChildStderrReporter(notify, options = {}) {
+    const debounceMs = options.debounceMs ?? 1500;
+    const cooldownMs = options.cooldownMs ?? 30_000;
+    const maxLineLength = options.maxLineLength ?? 200;
+    const groups = new Map();
+    const mutedUntil = new Map();
+    return {
+        push(raw) {
+            const cleaned = raw.replace(ANSI_PATTERN, '').trim();
+            if (cleaned.length === 0)
+                return;
+            const line = cleaned.length > maxLineLength ? `${cleaned.slice(0, maxLineLength)}…` : cleaned;
+            const existing = groups.get(line);
+            if (existing !== undefined) {
+                existing.count += 1;
+                clearTimeout(existing.timer);
+                existing.timer = setTimeout(flush, debounceMs);
+                return;
+            }
+            groups.set(line, { count: 1, timer: setTimeout(flush, debounceMs) });
+            function flush() {
+                const group = groups.get(line);
+                if (group === undefined)
+                    return;
+                groups.delete(line);
+                // A burst inside the cooldown window is counted but stays silent.
+                if ((mutedUntil.get(line) ?? 0) > Date.now())
+                    return;
+                // Prune expired cooldowns on the way in: entries are child-stderr
+                // lines and a long-lived MCP reconnect loop would otherwise grow the
+                // dedup table without bound.
+                if (mutedUntil.size > 64) {
+                    const now = Date.now();
+                    for (const [key, until] of mutedUntil) {
+                        if (until <= now)
+                            mutedUntil.delete(key);
+                    }
+                }
+                mutedUntil.set(line, Date.now() + cooldownMs);
+                const text = group.count > 1
+                    ? t('child-stderr-line-repeat', { line, count: group.count })
+                    : t('child-stderr-line', { line });
+                notify(text, { color: 'error', timeoutMs: 8000 });
+            }
+        },
+        dispose() {
+            for (const group of groups.values())
+                clearTimeout(group.timer);
+            groups.clear();
+        },
+    };
+}

package/lib/types/dsh-adapter/command-attribution.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Command ownership attribution — the data source for the C-041 invoke
+ * checkpoint's per-owner grant decision.
+ *
+ * dsh-commands has NO owner concept (its `normalizeDefinition` rebuilds a
+ * frozen object and drops unknown fields, and its scoped layers key by
+ * agent, not by registrant), and neither realistic access path can carry
+ * the caller's identity to `register` for us: `ctx.get('commands')` is an
+ * accessor that bypasses cordis's `internal/get` waterfall, and an
+ * inject-declared property read resolves before it. So attribution does
+ * NOT try to spy on the registry — it is a MEDIATED REGISTRATION surface,
+ * the same honest-identity pattern as storage.local / messages.observe:
+ * the plugin-host row's `registerCommand(pluginCtx, definition)` supplies a
+ * unique wrapper handler and stamps that actual registered definition with
+ * the verified Component id and activation on success. The invoke checkpoint resolves the
+ * effective definition for its receiving agent first, then looks up that
+ * definition's handler here. This mirrors dsh-commands' scoped shadowing:
+ * same-name definitions in separate agent scopes never share attribution.
+ *
+ * A plugin that registers directly through `ctx.get('commands')` keeps its
+ * command UNATTRIBUTED: the invoke checkpoint then applies the root grant
+ * only — the documented C-070 trusted-in-process boundary, exactly like a
+ * plugin calling `ctx.commands.execute` directly. Attribution only ever
+ * TIGHTENS the check, never widens it.
+ *
+ * The map is keyed by the cordis ROOT so the row and the channel (two
+ * different contexts of one runtime) share one view.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { VerifiedComponentIdentity } from './component-identity.js';
+export interface CommandOwner {
+    componentId: string;
+    activationId: string;
+    commandId: string;
+}
+/** The registrant's display name for diagnostics only: the passed context's
+ * fiber name (nearest named ancestor), 'root' for host-side or degraded
+ * contexts. Authorization never uses this display value. */
+export declare function fiberNameOf(ctx: Context): string;
+/** Record one mediated command definition's owner after successful registration. */
+export declare function stampCommandOwner(ctx: Context, definition: unknown, identity: VerifiedComponentIdentity, commandId: string): void;
+/** Lift one definition's stamp without touching a later registration. */
+export declare function unstampCommandOwner(ctx: Context, definition: unknown, activationId: string): void;
+/**
+ * The recorded owner of the EFFECTIVE command definition, or undefined when
+ * it is unattributed (root-side/direct registrations are the documented
+ * C-070 boundary). Callers must pass `commands.find(agent, name)`, not only
+ * the command name, so agent-scoped shadows select their own owner.
+ */
+export declare function commandOwner(ctx: Context, definition: unknown): CommandOwner | undefined;
+//# sourceMappingURL=command-attribution.d.ts.map

package/lib/types/dsh-adapter/command-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-attribution.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/command-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAGxE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAQD;;4DAE4D;AAC5D,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQhD;AAYD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,OAAO,EACnB,QAAQ,EAAE,yBAAyB,EACnC,SAAS,EAAE,MAAM,GAChB,IAAI,CAUN;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAMjG;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAKxF"}

package/lib/types/dsh-adapter/command-attribution.js

@@ -0,0 +1,93 @@
+/**
+ * Command ownership attribution — the data source for the C-041 invoke
+ * checkpoint's per-owner grant decision.
+ *
+ * dsh-commands has NO owner concept (its `normalizeDefinition` rebuilds a
+ * frozen object and drops unknown fields, and its scoped layers key by
+ * agent, not by registrant), and neither realistic access path can carry
+ * the caller's identity to `register` for us: `ctx.get('commands')` is an
+ * accessor that bypasses cordis's `internal/get` waterfall, and an
+ * inject-declared property read resolves before it. So attribution does
+ * NOT try to spy on the registry — it is a MEDIATED REGISTRATION surface,
+ * the same honest-identity pattern as storage.local / messages.observe:
+ * the plugin-host row's `registerCommand(pluginCtx, definition)` supplies a
+ * unique wrapper handler and stamps that actual registered definition with
+ * the verified Component id and activation on success. The invoke checkpoint resolves the
+ * effective definition for its receiving agent first, then looks up that
+ * definition's handler here. This mirrors dsh-commands' scoped shadowing:
+ * same-name definitions in separate agent scopes never share attribution.
+ *
+ * A plugin that registers directly through `ctx.get('commands')` keeps its
+ * command UNATTRIBUTED: the invoke checkpoint then applies the root grant
+ * only — the documented C-070 trusted-in-process boundary, exactly like a
+ * plugin calling `ctx.commands.execute` directly. Attribution only ever
+ * TIGHTENS the check, never widens it.
+ *
+ * The map is keyed by the cordis ROOT so the row and the channel (two
+ * different contexts of one runtime) share one view.
+ */
+import { compositionRoot } from './host-access.js';
+const ownerMaps = new WeakMap();
+function rootKeyOf(ctx) {
+    return compositionRoot(ctx);
+}
+/** The registrant's display name for diagnostics only: the passed context's
+ * fiber name (nearest named ancestor), 'root' for host-side or degraded
+ * contexts. Authorization never uses this display value. */
+export function fiberNameOf(ctx) {
+    try {
+        const resolved = ctx.fiber?.name;
+        if (typeof resolved === 'string' && resolved !== '')
+            return resolved;
+    }
+    catch {
+        // Degraded context without fiber access: 'root'.
+    }
+    return 'root';
+}
+function handlerOf(definition) {
+    try {
+        const handler = definition?.handler;
+        return typeof handler === 'function' ? handler : undefined;
+    }
+    catch {
+        // An exotic definition cannot participate in attribution safely.
+        return undefined;
+    }
+}
+/** Record one mediated command definition's owner after successful registration. */
+export function stampCommandOwner(ctx, definition, identity, commandId) {
+    const key = rootKeyOf(ctx);
+    const handler = handlerOf(definition);
+    if (key === undefined || handler === undefined)
+        return;
+    let map = ownerMaps.get(key);
+    if (map === undefined) {
+        map = new WeakMap();
+        ownerMaps.set(key, map);
+    }
+    map.set(handler, Object.freeze({ componentId: identity.componentId, activationId: identity.activationId, commandId }));
+}
+/** Lift one definition's stamp without touching a later registration. */
+export function unstampCommandOwner(ctx, definition, activationId) {
+    const key = rootKeyOf(ctx);
+    const handler = handlerOf(definition);
+    if (key === undefined || handler === undefined)
+        return;
+    const map = ownerMaps.get(key);
+    if (map?.get(handler)?.activationId === activationId)
+        map.delete(handler);
+}
+/**
+ * The recorded owner of the EFFECTIVE command definition, or undefined when
+ * it is unattributed (root-side/direct registrations are the documented
+ * C-070 boundary). Callers must pass `commands.find(agent, name)`, not only
+ * the command name, so agent-scoped shadows select their own owner.
+ */
+export function commandOwner(ctx, definition) {
+    const key = rootKeyOf(ctx);
+    const handler = handlerOf(definition);
+    if (key === undefined || handler === undefined)
+        return undefined;
+    return ownerMaps.get(key)?.get(handler);
+}

package/lib/types/dsh-adapter/command-errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * commands contract error-code alignment (C-041,
+ * `commands.dsh/v1alpha1#Command`): the official `dsh-commands` runtime
+ * reports a duplicate registration as a plain `Error` whose MESSAGE is the
+ * only signal:
+ *
+ *   `command "<name>" is already registered (…)`
+ *   `command "<name>" is already registered in this scope`
+ *
+ * The v0.15 contract names the code `DUPLICATE_CONTRIBUTION_ID`. This module
+ * maps the message-shaped error onto an `Error` carrying that `.code`, at
+ * the HOST-MEDIATED registration/invocation points (the channel's skill
+ * command registration and registry-command execution).
+ *
+ * Known boundary (C-070, trusted-in-process): a plugin calling
+ * `ctx.commands.register` / `ctx.commands.execute` DIRECTLY bypasses this
+ * mapping — code-level wrapping can only cover the points the host owns.
+ * That is declared platform behavior, not a bug.
+ */
+/** The contract's command error vocabulary. */
+export declare const COMMAND_ERROR_CODES: readonly ["COMMAND_NOT_FOUND", "DUPLICATE_CONTRIBUTION_ID", "PERMISSION_NOT_GRANTED", "COMMAND_FAILED", "INVOCATION_CANCELLED", "INVOCATION_DEADLINE_EXCEEDED"];
+export type CommandErrorCode = (typeof COMMAND_ERROR_CODES)[number];
+/** An Error carrying a contract error code on `.code`. */
+export interface CodedCommandError extends Error {
+    code: CommandErrorCode;
+    cause?: unknown;
+}
+/**
+ * Map a thrown dsh-commands error onto its contract code. A duplicate
+ * registration comes back as a CodedCommandError with
+ * `DUPLICATE_CONTRIBUTION_ID` (original on `.cause`); every other value
+ * passes through unchanged.
+ */
+export declare function mapCommandError(error: unknown): unknown;
+/** True when `error` carries the given contract code. */
+export declare function hasCommandErrorCode(error: unknown, code: CommandErrorCode): boolean;
+/**
+ * Run `operation` and rethrow any duplicate-registration failure with its
+ * contract code attached (see {@link mapCommandError}).
+ */
+export declare function withCommandErrorMapping<T>(operation: () => T | Promise<T>): Promise<T>;
+//# sourceMappingURL=command-errors.d.ts.map

package/lib/types/dsh-adapter/command-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-errors.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/command-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,iKAOtB,CAAA;AACV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEnE,0DAA0D;AAC1D,MAAM,WAAW,iBAAkB,SAAQ,KAAK;IAC9C,IAAI,EAAE,gBAAgB,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAMnF;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM5F"}

package/lib/types/dsh-adapter/command-errors.js

@@ -0,0 +1,63 @@
+/**
+ * commands contract error-code alignment (C-041,
+ * `commands.dsh/v1alpha1#Command`): the official `dsh-commands` runtime
+ * reports a duplicate registration as a plain `Error` whose MESSAGE is the
+ * only signal:
+ *
+ *   `command "<name>" is already registered (…)`
+ *   `command "<name>" is already registered in this scope`
+ *
+ * The v0.15 contract names the code `DUPLICATE_CONTRIBUTION_ID`. This module
+ * maps the message-shaped error onto an `Error` carrying that `.code`, at
+ * the HOST-MEDIATED registration/invocation points (the channel's skill
+ * command registration and registry-command execution).
+ *
+ * Known boundary (C-070, trusted-in-process): a plugin calling
+ * `ctx.commands.register` / `ctx.commands.execute` DIRECTLY bypasses this
+ * mapping — code-level wrapping can only cover the points the host owns.
+ * That is declared platform behavior, not a bug.
+ */
+/** The contract's command error vocabulary. */
+export const COMMAND_ERROR_CODES = [
+    'COMMAND_NOT_FOUND',
+    'DUPLICATE_CONTRIBUTION_ID',
+    'PERMISSION_NOT_GRANTED',
+    'COMMAND_FAILED',
+    'INVOCATION_CANCELLED',
+    'INVOCATION_DEADLINE_EXCEEDED',
+];
+const DUPLICATE_PATTERN = /^command "[^"]+" is already registered/;
+/**
+ * Map a thrown dsh-commands error onto its contract code. A duplicate
+ * registration comes back as a CodedCommandError with
+ * `DUPLICATE_CONTRIBUTION_ID` (original on `.cause`); every other value
+ * passes through unchanged.
+ */
+export function mapCommandError(error) {
+    if (error instanceof Error && DUPLICATE_PATTERN.test(error.message)) {
+        const mapped = new Error(error.message);
+        mapped.name = error.name;
+        mapped.code = 'DUPLICATE_CONTRIBUTION_ID';
+        mapped.cause = error;
+        return mapped;
+    }
+    return error;
+}
+/** True when `error` carries the given contract code. */
+export function hasCommandErrorCode(error, code) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        error.code === code);
+}
+/**
+ * Run `operation` and rethrow any duplicate-registration failure with its
+ * contract code attached (see {@link mapCommandError}).
+ */
+export async function withCommandErrorMapping(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        throw mapCommandError(error);
+    }
+}

package/lib/types/dsh-adapter/command-trees.d.ts

@@ -0,0 +1,34 @@
+/** Provider-neutral subcommand completion registry for terminal front doors. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { CommandCompletionNode, LocalizedDescriptions } from '../commands.js';
+export interface TuiCommandTreeProvider {
+    /** Root command name without `/`. Must match the command registry entry. */
+    root: string;
+    /** Optional provider-owned translations for the root command row. */
+    descriptions?: LocalizedDescriptions;
+    /** Children for the full canonical path, including `root` at index zero. */
+    children(canonicalPath: readonly string[]): readonly CommandCompletionNode[];
+}
+/** Host-only completion access. Plugins see only their own provider through
+ * the traceable service; the channel uses this facade to merge all providers. */
+export interface TuiCommandTreeHost {
+    register(provider: TuiCommandTreeProvider): () => void;
+    children(canonicalPath: readonly string[]): readonly CommandCompletionNode[];
+    descriptions(root: string): LocalizedDescriptions | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiCommandTrees: TuiCommandTreeRuntime;
+    }
+}
+export declare const name = "dsh-tui-command-trees";
+/** Small host-only registry; command execution remains owned by dsh-commands. */
+export declare class TuiCommandTreeRuntime extends Service {
+    constructor(ctx: Context);
+    register(provider: TuiCommandTreeProvider): () => void;
+    children(canonicalPath: readonly string[]): readonly CommandCompletionNode[];
+    descriptions(root: string): LocalizedDescriptions | undefined;
+}
+export declare function getHostCommandTrees(runtime: TuiCommandTreeRuntime | undefined): TuiCommandTreeHost | undefined;
+export default TuiCommandTreeRuntime;
+//# sourceMappingURL=command-trees.d.ts.map

package/lib/types/dsh-adapter/command-trees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-trees.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/command-trees.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAQlF,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,YAAY,CAAC,EAAE,qBAAqB,CAAA;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;CAC7E;AAED;iFACiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAAA;IACtD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;IAC5E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;CAC9D;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,eAAe,EAAE,qBAAqB,CAAA;KACvC;CACF;AAED,eAAO,MAAM,IAAI,0BAA0B,CAAA;AAE3C,iFAAiF;AACjF,qBAAa,qBAAsB,SAAQ,OAAO;gBACpC,GAAG,EAAE,OAAO;IAwBxB,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAqBtD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE;IAO5E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;CAM9D;AA0CD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAO9G;AAED,eAAe,qBAAqB,CAAA"}

package/lib/types/dsh-adapter/command-trees.js

@@ -0,0 +1,111 @@
+/** Provider-neutral subcommand completion registry for terminal front doors. */
+import { Service } from '@deepseek-ai/cordis';
+import { activationFiber, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
+export const name = 'dsh-tui-command-trees';
+/** Small host-only registry; command execution remains owned by dsh-commands. */
+export class TuiCommandTreeRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiCommandTrees');
+        compositionRoot(ctx);
+        const runtime = this;
+        const state = { providers: new Map(), owners: new Map(), host: undefined, runtime: adapterRuntimeFor(ctx) };
+        state.host = Object.freeze({
+            register: (provider) => {
+                const state = commandTreeStateFor(runtime);
+                const root = provider.root.trim().toLowerCase();
+                if (!/^[a-z][a-z0-9_-]*$/u.test(root) || state.providers.has(root))
+                    return () => { };
+                const normalized = { ...provider, root };
+                state.providers.set(root, normalized);
+                return () => {
+                    if (state.providers.get(root) !== normalized)
+                        return;
+                    state.providers.delete(root);
+                    state.owners.delete(root);
+                };
+            },
+            children: path => childrenFor(runtime, path),
+            descriptions: root => descriptionsFor(runtime, root),
+        });
+        commandTreeStates.set(this, state);
+    }
+    register(provider) {
+        assertCapabilityShadowPolicy('host.command-trees.register', commandTreeStateFor(this).runtime.mode, commandTreeStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiCommandTrees.register', this);
+        const state = commandTreeStateFor(this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            throw new Error('dsh-tui: tuiCommandTrees.register requires a live activation');
+        const root = provider.root.trim().toLowerCase();
+        if (!/^[a-z][a-z0-9_-]*$/u.test(root))
+            throw new TypeError(`invalid TUI command-tree root: ${provider.root}`);
+        if (state.providers.has(root))
+            throw new Error(`TUI command-tree root "${root}" is already registered`);
+        const normalized = { ...provider, root };
+        state.providers.set(root, normalized);
+        state.owners.set(root, owner);
+        const dispose = () => {
+            if (state.providers.get(root) !== normalized)
+                return;
+            state.providers.delete(root);
+            state.owners.delete(root);
+        };
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+    children(canonicalPath) {
+        assertCapabilityShadowPolicy('host.command-trees.children', commandTreeStateFor(this).runtime.mode, commandTreeStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiCommandTrees.children', this);
+        const owner = activationFiber(caller);
+        return childrenFor(this, canonicalPath, owner);
+    }
+    descriptions(root) {
+        assertCapabilityShadowPolicy('host.command-trees.descriptions', commandTreeStateFor(this).runtime.mode, commandTreeStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiCommandTrees.descriptions', this);
+        const owner = activationFiber(caller);
+        return descriptionsFor(this, root, owner);
+    }
+}
+const commandTreeStates = new WeakMap();
+function commandTreeStateFor(runtime) {
+    const state = commandTreeStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiCommandTrees host state is unavailable');
+    return state;
+}
+function childrenFor(runtime, canonicalPath, owner) {
+    const state = commandTreeStateFor(runtime);
+    const root = canonicalPath[0]?.toLowerCase();
+    if (root === undefined || (owner !== undefined && state.owners.get(root) !== owner))
+        return [];
+    const provider = state.providers.get(root);
+    if (provider === undefined)
+        return [];
+    try {
+        return provider.children(canonicalPath);
+    }
+    catch {
+        // Completion is optional UI metadata and must never block execution.
+        return [];
+    }
+}
+function descriptionsFor(runtime, root, owner) {
+    const state = commandTreeStateFor(runtime);
+    const normalized = root.trim().toLowerCase();
+    if (owner !== undefined && state.owners.get(normalized) !== owner)
+        return undefined;
+    return state.providers.get(normalized)?.descriptions;
+}
+export function getHostCommandTrees(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return commandTreeStateFor(runtime).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+export default TuiCommandTreeRuntime;