@deepseek-harness-tui/dsh-tui 0.10.0 → 0.10.2

package/lib/types/dsh-adapter/channel/context-bookkeeping.d.ts

@@ -0,0 +1,26 @@
+import type { ComposerImageRef, PendingMessage } from './types.js';
+/** Small mutable cells for Channel-local warning and pending-message state. */
+export declare function createContextBookkeeping(state: () => {
+    contextWindow: number | undefined;
+    tokens: {
+        input: number;
+    };
+    pending: PendingMessage[];
+    emit(): void;
+}, notify: (text: string, options: {
+    color: 'warning';
+    timeoutMs: number;
+}) => unknown, lowContextText: (percent: number) => string, warningBufferTokens: number): {
+    warning: {
+        value: boolean;
+    };
+    resetContextWarning: () => void;
+    checkContextWarning: () => void;
+    trackPending: (message: {
+        id: string;
+        text: string;
+        images?: readonly ComposerImageRef[];
+    }, placement: PendingMessage["placement"]) => void;
+    untrackPending: (messageId: string) => void;
+};
+//# sourceMappingURL=context-bookkeeping.d.ts.map

package/lib/types/dsh-adapter/channel/context-bookkeeping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-bookkeeping.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/context-bookkeeping.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAElE,+EAA+E;AAC/E,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM;IACX,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACzB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,IAAI,IAAI,CAAA;CACb,EACD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,EACnF,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,EAC3C,mBAAmB,EAAE,MAAM;;;;+BAwBK,IAAI;+BArBJ,IAAI;4BAUL;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;KAAE,aAAa,cAAc,CAAC,WAAW,CAAC,KAAG,IAAI;gCAK7G,MAAM,KAAG,IAAI;EAQjD"}

package/lib/types/dsh-adapter/channel/context-bookkeeping.js

@@ -0,0 +1,30 @@
+/** Small mutable cells for Channel-local warning and pending-message state. */
+export function createContextBookkeeping(state, notify, lowContextText, warningBufferTokens) {
+    const warning = { value: false };
+    const checkContextWarning = () => {
+        const channel = state();
+        if (warning.value || channel.contextWindow === undefined)
+            return;
+        const remaining = channel.contextWindow - channel.tokens.input;
+        if (remaining >= warningBufferTokens)
+            return;
+        warning.value = true;
+        notify(lowContextText(Math.max(0, Math.round((remaining / channel.contextWindow) * 100))), {
+            color: 'warning', timeoutMs: 8000,
+        });
+    };
+    const trackPending = (message, placement) => {
+        const channel = state();
+        channel.pending = [...channel.pending, { id: message.id, text: message.text, images: message.images ?? [], placement }];
+        channel.emit();
+    };
+    const untrackPending = (messageId) => {
+        const channel = state();
+        const before = channel.pending.length;
+        channel.pending = channel.pending.filter(item => item.id !== messageId);
+        if (channel.pending.length !== before)
+            channel.emit();
+    };
+    const resetContextWarning = () => { warning.value = false; };
+    return { warning, resetContextWarning, checkContextWarning, trackPending, untrackPending };
+}

package/lib/types/dsh-adapter/channel/decisions.d.ts

@@ -0,0 +1,19 @@
+import type { TuiInputDecision, TuiRewindPromptDecision } from '../extension-events.js';
+/** `tui/input` return normalization: transform/handled/cancel or no opinion.
+ *  A blank `{ text }` rewrite is NOT a decision — it is logged and the chain
+ *  continues so a later veto listener still runs. */
+export declare function normalizeInputDecision(result: unknown, warn: (what: string) => void): TuiInputDecision | undefined;
+/** `tui/rewind-prompt` return normalization: cancel/modes or no opinion.
+ *  Modes are COPIED with only validated, sanitized scalar fields — the raw
+ *  plugin object must never reach the render path (a `description: {}` would
+ *  crash ListItem's `.replace`, and control chars would corrupt the pane).
+ *  Notices/reasons are toast-bound plugin text: sanitized too (see
+ *  ./sanitize.js — the one implementation of the render-path contract). */
+export declare function normalizeRewindPromptDecision(result: unknown, warn: (what: string) => void): TuiRewindPromptDecision | undefined;
+/** Toast-bound plugin text (veto reasons, handled notices, rewind summaries)
+ *  is render-path data too: same sanitization, toast-width cap. */
+export declare const NOTICE_CELLS = 200;
+/** `tui/rewind-done` return normalization: the first non-empty STRING is the
+ *  summary; anything else is not a decision. */
+export declare function normalizeRewindDoneSummary(result: unknown, warn: (what: string) => void): string | undefined;
+//# sourceMappingURL=decisions.d.ts.map

package/lib/types/dsh-adapter/channel/decisions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/decisions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,uBAAuB,EACxB,MAAM,wBAAwB,CAAA;AAG/B;;qDAEqD;AACrD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3B,gBAAgB,GAAG,SAAS,CAwB9B;AAED;;;;;2EAK2E;AAC3E,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3B,uBAAuB,GAAG,SAAS,CAkCrC;AAED;mEACmE;AACnE,eAAO,MAAM,YAAY,MAAM,CAAA;AAE/B;gDACgD;AAChD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,GAAG,SAAS,CAQ5G"}

package/lib/types/dsh-adapter/channel/decisions.js

@@ -0,0 +1,90 @@
+import { cleanRenderText, cleanScalarText } from '../sanitize.js';
+/** `tui/input` return normalization: transform/handled/cancel or no opinion.
+ *  A blank `{ text }` rewrite is NOT a decision — it is logged and the chain
+ *  continues so a later veto listener still runs. */
+export function normalizeInputDecision(result, warn) {
+    if (result === undefined || result === null || result === false)
+        return undefined;
+    if (typeof result !== 'object') {
+        warn(`a non-object (${typeof result})`);
+        return undefined;
+    }
+    const record = result;
+    if (record.cancel === true) {
+        const reason = cleanScalarText(record.reason, NOTICE_CELLS);
+        return { cancel: true, ...(reason === '' ? {} : { reason }) };
+    }
+    if (record.handled === true) {
+        const notice = cleanScalarText(record.notice, NOTICE_CELLS);
+        return { handled: true, ...(notice === '' ? {} : { notice }) };
+    }
+    if (typeof record.text === 'string') {
+        if (record.text.trim() === '') {
+            warn('a blank {text} rewrite');
+            return undefined;
+        }
+        return { text: record.text };
+    }
+    warn('an unrecognized decision shape');
+    return undefined;
+}
+/** `tui/rewind-prompt` return normalization: cancel/modes or no opinion.
+ *  Modes are COPIED with only validated, sanitized scalar fields — the raw
+ *  plugin object must never reach the render path (a `description: {}` would
+ *  crash ListItem's `.replace`, and control chars would corrupt the pane).
+ *  Notices/reasons are toast-bound plugin text: sanitized too (see
+ *  ./sanitize.js — the one implementation of the render-path contract). */
+export function normalizeRewindPromptDecision(result, warn) {
+    if (result === undefined || result === null || result === false)
+        return undefined;
+    if (typeof result !== 'object') {
+        warn(`a non-object (${typeof result})`);
+        return undefined;
+    }
+    const record = result;
+    if (record.cancel === true) {
+        const reason = cleanScalarText(record.reason, NOTICE_CELLS);
+        return { cancel: true, ...(reason === '' ? {} : { reason }) };
+    }
+    if (Array.isArray(record.modes)) {
+        const modes = [];
+        for (const raw of record.modes) {
+            if (modes.length >= 8)
+                break;
+            if (raw === null || typeof raw !== 'object')
+                continue;
+            const candidate = raw;
+            if (typeof candidate.id !== 'string' || candidate.id.trim() === '')
+                continue;
+            const label = typeof candidate.label === 'string' ? cleanRenderText(candidate.label, 120) : '';
+            if (label === '')
+                continue;
+            const description = typeof candidate.description === 'string' && candidate.description.trim() !== ''
+                ? cleanRenderText(candidate.description, 400)
+                : undefined;
+            modes.push({ id: candidate.id, label, ...(description === undefined ? {} : { description }) });
+        }
+        if (modes.length === 0) {
+            warn('an empty or invalid {modes} list');
+            return undefined;
+        }
+        return { modes };
+    }
+    warn('an unrecognized decision shape');
+    return undefined;
+}
+/** Toast-bound plugin text (veto reasons, handled notices, rewind summaries)
+ *  is render-path data too: same sanitization, toast-width cap. */
+export const NOTICE_CELLS = 200;
+/** `tui/rewind-done` return normalization: the first non-empty STRING is the
+ *  summary; anything else is not a decision. */
+export function normalizeRewindDoneSummary(result, warn) {
+    if (result === undefined || result === null || result === false)
+        return undefined;
+    if (typeof result === 'string') {
+        const summary = cleanRenderText(result, NOTICE_CELLS);
+        return summary === '' ? undefined : summary;
+    }
+    warn('a non-string summary');
+    return undefined;
+}

package/lib/types/dsh-adapter/channel/emitter.d.ts

@@ -0,0 +1,10 @@
+import type { ChannelState } from './types.js';
+export declare function createChannelEmitter(getState: () => Pick<ChannelState, 'rows' | 'version'>, 
+/** Returns true when the deferred projector changed renderer-visible data. */
+beforeStream: () => boolean): {
+    subscribe(listener: () => void): () => void;
+    emit(): void;
+    emitStream(): void;
+    dispose(): void;
+};
+//# sourceMappingURL=emitter.d.ts.map

package/lib/types/dsh-adapter/channel/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/emitter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;AACtD,8EAA8E;AAC9E,YAAY,EAAE,MAAM,OAAO;wBAmBL,MAAM,IAAI;;;;EAkCjC"}

package/lib/types/dsh-adapter/channel/emitter.js

@@ -0,0 +1,71 @@
+/** One owner for synchronous versions and frame-coalesced renderer wakeups. */
+import { swallowNestedUpdateOverflow } from '../../ink/update-overflow-guard.js';
+import { foldRows, MAX_ROWS } from './transcript.js';
+export function createChannelEmitter(getState, 
+/** Returns true when the deferred projector changed renderer-visible data. */
+beforeStream) {
+    const listeners = new Set();
+    const foldCursor = { rows: undefined, index: 0 };
+    let timer;
+    let disposed = false;
+    const wake = (source) => {
+        const state = getState();
+        // Folding mutates retained transcript rows after a reader may have
+        // cached the ingress revision. Publish that completed fold separately so
+        // listeners cannot observe a stale or mixed same-version snapshot.
+        if (foldRows(state.rows, MAX_ROWS, foldCursor) > 0)
+            state.version += 1;
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                if (!swallowNestedUpdateOverflow(error, source))
+                    throw error;
+            }
+        }
+    };
+    return {
+        subscribe(listener) {
+            if (disposed)
+                return () => undefined;
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        emit() {
+            if (disposed)
+                return;
+            getState().version += 1;
+            wake('channel.emit');
+        },
+        emitStream() {
+            if (disposed)
+                return;
+            getState().version += 1;
+            if (timer !== undefined)
+                return;
+            timer = setTimeout(() => {
+                timer = undefined;
+                if (disposed)
+                    return;
+                // emitStream bumps on ingress so ordinary stream state is observable
+                // immediately. A deferred projector can then publish its completed
+                // snapshot as a distinct revision, preventing a pre-flush read from
+                // surviving the wakeup with stale rows.
+                if (beforeStream())
+                    getState().version += 1;
+                wake('channel.emitStream');
+            }, 16);
+            timer.unref();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            listeners.clear();
+        },
+    };
+}

package/lib/types/dsh-adapter/channel/external-commands.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CommandRuntime } from '@deepseek-ai/dsh-commands';
+import { type ComposerImages } from './composer-images.js';
+import type { ComposerImageRef, ExternalCommandOutcome, MentionAttachments } from './types.js';
+/** Plugin-command invocation has one owner: this module owns gates, image
+ *  encoding and the settled draft-consumption outcome. */
+export declare function createExternalCommandInvoker(ctx: Context, deps: {
+    commandService: CommandRuntime | undefined;
+    runtime: {
+        mode: string;
+        slices: readonly string[];
+    };
+    agent(): Agent;
+    capture(): unknown;
+    bindingCurrent(capture: unknown): boolean;
+    allows(subject: {
+        componentId: string;
+        activationId?: string;
+    }, permission: string, scope: string): boolean;
+    composer: ComposerImages;
+    attachments(): MentionAttachments | undefined;
+    notify(text: string, options?: {
+        color?: 'success' | 'error' | 'warning';
+        timeoutMs?: number;
+    }): void;
+}): {
+    invoke: (name: string, rawInput: string, imageRefs?: readonly ComposerImageRef[]) => Promise<ExternalCommandOutcome | undefined>;
+    invokeText: (name: string, rawInput: string, imageRefs?: readonly ComposerImageRef[]) => Promise<string | undefined>;
+};
+//# sourceMappingURL=external-commands.d.ts.map

package/lib/types/dsh-adapter/channel/external-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-commands.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/external-commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAKjF,OAAO,EAAkD,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1G,OAAO,KAAK,EAAqB,gBAAgB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAcjH;0DAC0D;AAC1D,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;IACJ,cAAc,EAAE,cAAc,GAAG,SAAS,CAAA;IAC1C,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAA;IACpD,KAAK,IAAI,KAAK,CAAA;IACd,OAAO,IAAI,OAAO,CAAA;IAClB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;IACzC,MAAM,CAAC,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IAC3G,QAAQ,EAAE,cAAc,CAAA;IACxB,WAAW,IAAI,kBAAkB,GAAG,SAAS,CAAA;IAC7C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CACtG;mBA+HO,MAAM,YACF,MAAM,cACL,SAAS,gBAAgB,EAAE,KACrC,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;uBA2EtC,MAAM,YACF,MAAM,cACL,SAAS,gBAAgB,EAAE,KACrC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;EAG/B"}

package/lib/types/dsh-adapter/channel/external-commands.js

@@ -0,0 +1,187 @@
+import { installedMeetsVersion } from '../contract.js';
+import { commandOwner } from '../command-attribution.js';
+import { assertCapabilityShadowPolicy } from '../../adapter/kernel/runtime.js';
+import { t } from '../../i18n.js';
+import { firstStaleComposerToken, orderedComposerImages } from './composer-images.js';
+/** Plugin-command invocation has one owner: this module owns gates, image
+ *  encoding and the settled draft-consumption outcome. */
+export function createExternalCommandInvoker(ctx, deps) {
+    /** Whether the installed command service takes composer images: version
+     *  gate (composer images arrived on 0.1.0-rc.8 and every later family —
+     *  0.1.1 included — keeps the 4-param shape) with a structural fallback,
+     *  so a failed manifest probe (bundlers, exotic loaders) still lands on
+     *  the 4-param rc.8 shape at runtime. */
+    const supportsImages = (service) => installedMeetsVersion('@deepseek-ai/dsh-commands', '0.1.0-rc.8')
+        || (typeof service.execute.length === 'number' && service.execute.length >= 4);
+    const authorize = (definition, name) => {
+        // Derive identity from the effective definition, never the display name:
+        // scoped same-name handlers can have different verified owners.
+        const owner = commandOwner(ctx, definition);
+        const rootScope = owner?.commandId ?? (/^[a-z][a-z0-9]*(?:[.-][a-z0-9][a-z0-9-]*)+$/u.test(name) ? name : `dsh-tui.${name.toLowerCase().replace(/[^a-z0-9-]+/gu, '-').replace(/^-+|-+$/gu, '') || 'command'}`);
+        if (!deps.allows({ componentId: 'root' }, 'commands.invoke', rootScope)) {
+            ctx.logger.warn('dsh-tui: registry command invocation denied (commands.invoke revoked for "root" in the grants file)');
+            ctx.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'permission', id: `root:commands.invoke:${rootScope}` }, result: 'failed', errorCode: 'PERMISSION_NOT_GRANTED' }, ctx);
+            return t('command-invoke-denied');
+        }
+        if (owner !== undefined && !deps.allows({ componentId: owner.componentId, activationId: owner.activationId }, 'commands.invoke', owner.commandId)) {
+            ctx.logger.warn(`dsh-tui: registry command "/${name}" invocation denied — owner Component "${owner.componentId}" lost commands.invoke for "${owner.commandId}"`);
+            ctx.get('tuiEffectLedger')?.record({ operation: 'bind', resource: { kind: 'permission', id: `${owner.componentId}:commands.invoke:${owner.commandId}` }, result: 'failed', errorCode: 'PERMISSION_NOT_GRANTED' }, ctx);
+            return t('command-invoke-denied-owner', { name, owner: owner.componentId });
+        }
+        return undefined;
+    };
+    /** Encode the staged `@`-mention images the user pasted for THIS command
+     *  line into rc.8's `EncodedImageAttachment` payloads; `kind: 'legacy'`
+     *  means the installed dsh-commands line predates composer images
+     *  (rc.7/rc.6), so the caller uses the legacy 3-arg invoke. Matches the
+     *  submit pipeline's token rule (expandComposerMentions): a staged image
+     *  attaches only when the line references its token. The composer
+     *  preflights `input.images`, but this adapter still forwards every
+     *  supplied image: rc.8 owns admission, so non-UI callers cannot
+     *  accidentally bypass the registry contract. Preparation is atomic:
+     *  limits are checked from durable metadata before any read/base64 work,
+     *  and one missing or unreadable image prevents the handler from running
+     *  with a silently truncated batch. */
+    const registryCommandImages = async (service, line, imageRefs, staged, signal) => {
+        const ordered = orderedComposerImages(line, imageRefs, staged);
+        // A `[Image #N]` with no live staging is plain text here, exactly as on
+        // the submit path: warn once, keep the line unchanged. Only referenced,
+        // staged images take part in the batch below.
+        const stale = firstStaleComposerToken(line, ordered);
+        if (stale !== undefined) {
+            deps.notify(t('input-image-token-stale', { token: stale }), { color: 'warning', timeoutMs: 5000 });
+        }
+        if (!supportsImages(service)) {
+            return ordered.size > 0
+                ? { kind: 'error', reason: 'runtime', tokens: [...ordered.keys()] }
+                : { kind: 'legacy' };
+        }
+        if (ordered.size === 0)
+            return { kind: 'ready', images: [] };
+        const store = deps.attachments();
+        if (typeof store?.readImage !== 'function') {
+            return { kind: 'error', reason: 'missing', tokens: [...ordered.keys()] };
+        }
+        const { imageLimits: limits } = store;
+        let declaredBytes = 0;
+        for (const attachment of ordered.values()) {
+            if (!Number.isSafeInteger(attachment.bytes)
+                || attachment.bytes <= 0
+                || attachment.bytes > limits.maxImageBytes
+                || !limits.mediaTypes.includes(attachment.mediaType)) {
+                return { kind: 'error', reason: 'limits', tokens: [...ordered.keys()] };
+            }
+            declaredBytes += attachment.bytes;
+        }
+        if (ordered.size > limits.maxImagesPerMessage
+            || declaredBytes > limits.maxMessageImageBytes) {
+            return { kind: 'error', reason: 'limits', tokens: [...ordered.keys()] };
+        }
+        const loaded = [];
+        let actualBytes = 0;
+        for (const [token, attachment] of ordered) {
+            try {
+                const stored = await store.readImage(attachment, signal);
+                if (!(stored?.data instanceof Uint8Array) || stored.data.byteLength <= 0) {
+                    return { kind: 'error', reason: 'missing', tokens: [token] };
+                }
+                actualBytes += stored.data.byteLength;
+                if (stored.data.byteLength > limits.maxImageBytes
+                    || actualBytes > limits.maxMessageImageBytes) {
+                    return { kind: 'error', reason: 'limits', tokens: [...ordered.keys()] };
+                }
+                loaded.push({ token, attachment, data: stored.data });
+            }
+            catch {
+                return { kind: 'error', reason: 'missing', tokens: [token] };
+            }
+        }
+        return {
+            kind: 'ready',
+            images: loaded.map(({ attachment, data }) => ({
+                // Older image-only runtimes ignore the discriminator; 0.1.5 uses it
+                // to distinguish encoded images from stored file attachments.
+                type: 'image',
+                mediaType: attachment.mediaType,
+                data: Buffer.from(data).toString('base64'),
+                name: attachment.name,
+            })),
+        };
+    };
+    /** Run one DSH registry command (`/plan`, …) on the live agent while
+     *  preserving its settled result kind for composer admission. */
+    const invoke = async (name, rawInput, imageRefs = []) => {
+        const capture = deps.capture();
+        assertCapabilityShadowPolicy('host.commands.invoke', deps.runtime.mode, deps.runtime.slices);
+        const service = deps.commandService;
+        if (service === undefined)
+            return undefined;
+        const commandAgent = deps.agent();
+        const stagedSnapshot = deps.composer.snapshot();
+        // Resolve the exact definition that execute() will select for this agent.
+        // Same names may exist in distinct agent scopes, so a name-only lookup can
+        // apply another scope's owner policy.
+        const definition = service.find(commandAgent, name);
+        try {
+            const signal = new AbortController().signal;
+            const line = `/${name}${rawInput}`;
+            const batch = await registryCommandImages(service, line, deps.composer.includeLegacyImageRefs(line, imageRefs), stagedSnapshot, signal);
+            if (batch.kind === 'error') {
+                const text = batch.reason === 'runtime'
+                    ? t('command-images-runtime-unsupported', { name })
+                    : batch.reason === 'limits'
+                        ? t('command-images-limit', { name })
+                        : t('command-images-missing', { name, paths: batch.tokens.join(' ') });
+                return { kind: 'error', text, consumeDraft: false };
+            }
+            // Image preparation can await storage. Do not authorize definition A
+            // and then execute a newly registered same-name definition B after A
+            // was unloaded while those reads were pending.
+            if (service.find(commandAgent, name) !== definition) {
+                return { kind: 'error', text: t('command-changed', { name }), consumeDraft: false };
+            }
+            if (!deps.bindingCurrent(capture)) {
+                deps.notify(t('ext-stale-dropped'), { color: 'warning', timeoutMs: 4000 });
+                return { kind: 'error', text: '', consumeDraft: false };
+            }
+            // Grants are a live per-operation decision. Image reads above may
+            // park, so take the single authoritative snapshot only now — after
+            // preparation/identity guards and immediately before execute.
+            const denied = authorize(definition, name);
+            if (denied !== undefined)
+                return { kind: 'error', text: denied, consumeDraft: false };
+            // rc.8 moved the signal to the 4th parameter and added composer
+            // images; older lines (rc.7/rc.6) take (agent, line, signal).
+            const execution = batch.kind === 'legacy'
+                ? await service.execute(commandAgent, line, signal)
+                : await service.execute(commandAgent, line, batch.images, signal);
+            // The handler itself may park. Its durable lifecycle belongs to the
+            // old agent, but its toast/consume acknowledgment must never land on a
+            // replacement session after /new, resume, rewind, or model switch.
+            if (!deps.bindingCurrent(capture))
+                return { kind: 'error', text: '', consumeDraft: false };
+            if (execution === undefined)
+                return undefined;
+            return execution.result.kind === 'success'
+                ? { kind: 'success', text: execution.result.text ?? '', consumeDraft: true }
+                : {
+                    kind: 'error',
+                    text: execution.result.text,
+                    // Upstream composers retain image-bearing handler failures so
+                    // the user can fix the grammar without rebuilding attachments;
+                    // imageless handler errors remain consumed durable outcomes.
+                    consumeDraft: batch.kind === 'ready' ? batch.images.length === 0 : true,
+                };
+        }
+        catch (error) {
+            return {
+                kind: 'error',
+                text: error instanceof Error ? error.message : String(error),
+                consumeDraft: false,
+            };
+        }
+    };
+    /** Text-only companion kept for the public scene-facing API. */
+    const invokeText = async (name, rawInput, imageRefs = []) => (await invoke(name, rawInput, imageRefs))?.text;
+    return { invoke, invokeText };
+}

package/lib/types/dsh-adapter/channel/file-actions.d.ts

@@ -0,0 +1,20 @@
+import type { FileCandidate } from '../../utils/fileSuggestions.js';
+import type { MentionFs } from './types.js';
+/** Workspace file queries and their per-cwd scan cache. */
+export declare function createFileActions(deps: {
+    owner: {
+        current(): boolean;
+        readonly signal: AbortSignal;
+    };
+    capture(): unknown;
+    current(capture: unknown): boolean;
+    cwd(): string;
+    fs(): MentionFs | undefined;
+}): {
+    listFileCandidates: (query: string, options?: {
+        signal?: AbortSignal;
+        topK?: number;
+    }) => Promise<readonly FileCandidate[]>;
+    listFiles: () => Promise<readonly string[]>;
+};
+//# sourceMappingURL=file-actions.d.ts.map

package/lib/types/dsh-adapter/channel/file-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-actions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/file-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAGnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,KAAK,EAAE;QAAE,OAAO,IAAI,OAAO,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;KAAE,CAAA;IAC3D,OAAO,IAAI,OAAO,CAAA;IAClB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;IAClC,GAAG,IAAI,MAAM,CAAA;IACb,EAAE,IAAI,SAAS,GAAG,SAAS,CAAA;CAC5B;gCAQU,MAAM,YACH;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAChD,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;qBA2BR,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;EAQvD"}

package/lib/types/dsh-adapter/channel/file-actions.js

@@ -0,0 +1,45 @@
+import { isPathLikeQuery, rankFileCandidates } from '../../utils/fileSuggestions.js';
+import { listFilesDeepCandidates, listPathCandidates } from './paths.js';
+/** Workspace file queries and their per-cwd scan cache. */
+export function createFileActions(deps) {
+    let cache = { cwd: '' };
+    const isCurrent = (capture, cwd) => deps.owner.current() && deps.current(capture) && deps.cwd() === cwd;
+    const withOwnerSignal = (signal) => signal === undefined ? deps.owner.signal : AbortSignal.any([signal, deps.owner.signal]);
+    const listFileCandidates = async (query, options) => {
+        const capture = deps.capture();
+        const cwd = deps.cwd();
+        const fs = deps.fs();
+        const signal = withOwnerSignal(options?.signal);
+        if (!fs || signal.aborted || !isCurrent(capture, cwd))
+            return [];
+        if (isPathLikeQuery(query)) {
+            const result = await listPathCandidates(fs, cwd, query, signal, options?.topK ?? 50);
+            return isCurrent(capture, cwd) && !signal.aborted ? result : [];
+        }
+        if (cache.cwd !== cwd)
+            cache = { cwd };
+        const scan = cache;
+        // The scan belongs to this Channel/CWD cache entry, not to its first
+        // waiter. A caller cancellation only suppresses that caller's result;
+        // owner disposal remains the shared scan's cancellation fence.
+        scan.load ??= listFilesDeepCandidates(fs, cwd, deps.owner.signal).then(candidates => {
+            // Do not retain a cancelled/empty observation; a later request may have
+            // a live owner or find files that appeared after this scan. An older
+            // CWD scan must not clear a newer entry after it settles.
+            if (candidates.length === 0 && cache === scan)
+                scan.load = undefined;
+            return candidates;
+        });
+        const candidates = await scan.load;
+        if (!isCurrent(capture, cwd) || signal.aborted)
+            return [];
+        return rankFileCandidates(candidates, query, options?.topK ?? 50);
+    };
+    const listFiles = async () => {
+        const capture = deps.capture();
+        const cwd = deps.cwd();
+        const candidates = await listFilesDeepCandidates(deps.fs(), cwd, deps.owner.signal);
+        return isCurrent(capture, cwd) ? candidates.map(candidate => candidate.path) : [];
+    };
+    return { listFileCandidates, listFiles };
+}

package/lib/types/dsh-adapter/channel/input-actions.d.ts

@@ -0,0 +1,13 @@
+/** Input actions own cancellation/requeue convergence, not session binding. */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ChannelState, ComposerImageRef } from './types.js';
+export interface InputConvergence {
+    cancelInFlight: boolean;
+    interruptSeq: number;
+}
+export declare function createInputActions(getState: () => Pick<ChannelState, 'agentId' | 'pending' | 'cancelPending' | 'emit' | 'notify'>, getAgent: () => Agent, owner: {
+    assertActive(): void;
+}, input: InputConvergence, composer: {
+    includeLegacyImageRefs(text: string, images: readonly ComposerImageRef[]): readonly ComposerImageRef[];
+}, dispatchUserText: (text: string, placement: 'steer' | 'followup', images?: readonly ComposerImageRef[]) => void, runLocalCommand: (command: string, includeInContext: boolean) => Promise<void>): Pick<ChannelState, 'submit' | 'steer' | 'removePending' | 'cancel' | 'interruptAndDeliver'>;
+//# sourceMappingURL=input-actions.d.ts.map

package/lib/types/dsh-adapter/channel/input-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-actions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/input-actions.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAInD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAsB,MAAM,YAAY,CAAA;AAEpF,MAAM,WAAW,gBAAgB;IAAG,cAAc,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE;AACnF,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,eAAe,GAAG,MAAM,GAAG,QAAQ,CAAC,EAC/F,QAAQ,EAAE,MAAM,KAAK,EACrB,KAAK,EAAE;IAAE,YAAY,IAAI,IAAI,CAAA;CAAE,EAC/B,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE;IAAE,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,gBAAgB,EAAE,CAAA;CAAE,EACpH,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,UAAU,EAAE,MAAM,CAAC,EAAE,SAAS,gBAAgB,EAAE,KAAK,IAAI,EAC/G,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAC7E,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,OAAO,GAAG,eAAe,GAAG,QAAQ,GAAG,qBAAqB,CAAC,CAgI7F"}