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

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

@@ -0,0 +1,9 @@
+const dispatchers = new WeakMap();
+export function bindChannelCommands(state, commands) {
+    dispatchers.set(state, commands);
+    // Keep the revoked dispatcher installed: late async work must fail closed,
+    // not revert to the bare-embedder path after production teardown.
+}
+export function channelCommands(state) {
+    return dispatchers.get(state) ?? state;
+}

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

@@ -0,0 +1,19 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChannelOwner } from './owner.js';
+import type { ChannelState } from './types.js';
+type CompactionState = Pick<ChannelState, 'agentId' | 'cwd' | 'working'>;
+type Notify = ChannelState['notify'];
+/** Owns the one manual compaction transaction that must settle before a switch. */
+export declare function createManualCompaction(ctx: Context, state: CompactionState, deps: {
+    owner: Pick<ChannelOwner, 'current' | 'signal' | 'own'>;
+    agent(): Agent;
+    withDecisionPending<T>(name: string, pending: Promise<T>): Promise<T>;
+    notify: Notify;
+    onComplete(): void;
+}): {
+    compact: () => void;
+    settle: () => Promise<void>;
+};
+export {};
+//# sourceMappingURL=compaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAO9C,KAAK,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC,CAAA;AACxE,KAAK,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;AAEpC,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE;IACJ,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC,CAAA;IACvD,KAAK,IAAI,KAAK,CAAA;IACd,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACrE,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,IAAI,IAAI,CAAA;CACnB;mBAuBmB,IAAI;kBAlBC,OAAO,CAAC,IAAI,CAAC;EAwGvC"}

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

@@ -0,0 +1,116 @@
+import { t } from '../../i18n.js';
+import { dispatchTuiDecision, normalizeCancelDecision } from '../extension-events.js';
+import { serviceForAgent } from '../presets.js';
+/** Owns the one manual compaction transaction that must settle before a switch. */
+export function createManualCompaction(ctx, state, deps) {
+    let active;
+    const cancelled = new WeakSet();
+    const settle = async () => {
+        const transaction = active;
+        if (transaction === undefined)
+            return;
+        active = undefined;
+        cancelled.add(transaction.controller);
+        transaction.controller.abort(new Error('session switch'));
+        deps.notify(t('compact-cancelled-switch'), { color: 'warning', timeoutMs: 4000 });
+        let timeout;
+        try {
+            await Promise.race([
+                transaction.settled,
+                new Promise(resolve => { timeout = setTimeout(resolve, 3000); }),
+            ]);
+        }
+        finally {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+        }
+    };
+    const compact = () => {
+        if (!deps.owner.current() || deps.owner.signal.aborted || active !== undefined)
+            return;
+        const originAgent = deps.agent();
+        const compactService = serviceForAgent(ctx, originAgent, 'compaction');
+        if (!compactService) {
+            deps.notify(t('compact-unavailable'), { color: 'warning' });
+            return;
+        }
+        if (state.working) {
+            deps.notify(t('compact-while-working'), { color: 'warning' });
+            return;
+        }
+        const controller = new AbortController();
+        const isCurrent = () => deps.owner.current()
+            && !deps.owner.signal.aborted
+            && !cancelled.has(controller)
+            && deps.agent() === originAgent;
+        const releaseOwner = deps.owner.own(() => {
+            cancelled.add(controller);
+            controller.abort(new Error('channel lifetime ended'));
+        });
+        const originAgentId = state.agentId;
+        let finished = false;
+        const settled = (async () => {
+            try {
+                const decision = await deps.withDecisionPending('tui/compact', dispatchTuiDecision(ctx, 'tui/compact', {
+                    sessionId: originAgentId,
+                    cwd: state.cwd,
+                }, normalizeCancelDecision));
+                // A revoked owner stays silent, but retain the original stale-agent
+                // classification when this channel remains active on a new binding.
+                if (!deps.owner.current() || deps.owner.signal.aborted || cancelled.has(controller))
+                    return;
+                if (deps.agent() !== originAgent) {
+                    deps.notify(t('ext-compact-stale'), { color: 'warning', timeoutMs: 4000 });
+                    return;
+                }
+                if (decision !== undefined) {
+                    deps.notify(decision.reason ?? t('ext-action-cancelled'), { color: 'warning', timeoutMs: 4000 });
+                    return;
+                }
+                if (state.working) {
+                    deps.notify(t('compact-while-working'), { color: 'warning' });
+                    return;
+                }
+                deps.notify(t('compact-working'));
+                try {
+                    // Compact the entry agent, never a later binding read after await.
+                    const result = await compactService.compactNow(originAgent, controller.signal);
+                    if (!isCurrent())
+                        return;
+                    deps.notify(result ? t('compact-done') : t('compact-nothing'));
+                    if (result)
+                        deps.onComplete();
+                }
+                catch (error) {
+                    if (!isCurrent() || cancelled.has(controller))
+                        return;
+                    if (error.code === 'persistence') {
+                        deps.notify(t('compact-flush-failed'), { color: 'warning', timeoutMs: 12000 });
+                        return;
+                    }
+                    deps.notify(t('compact-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'error', timeoutMs: 8000 });
+                }
+            }
+            catch (error) {
+                // dispatch is normally isolated, but do not create an unhandled
+                // rejection if an embedder's pending wrapper fails.
+                if (!isCurrent())
+                    return;
+                deps.notify(t('compact-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'error', timeoutMs: 8000 });
+            }
+            finally {
+                finished = true;
+                releaseOwner();
+                const currentTransaction = active;
+                if (currentTransaction?.controller === controller)
+                    active = undefined;
+            }
+        })();
+        // Install before the decision await so a switch/fork settles a pending
+        // decision too, rather than letting it start compaction after its seed.
+        // A synchronous embedder failure is already handled by the IIFE above.
+        if (!finished)
+            active = { controller, settled };
+    };
+    return { compact, settle };
+}

package/lib/types/dsh-adapter/channel/composer-images.d.ts

@@ -0,0 +1,57 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChannelOwner } from './owner.js';
+import type { ChannelImageBlock, ComposerImageRef, StagedImageHandle, StagedImageInput, TranscriptImage } from './types.js';
+/** Every visible composer placeholder token, in source order. */
+export declare const COMPOSER_IMAGE_TOKEN: RegExp;
+/** One whole placeholder token; the distinction matters because a mention
+ *  reference needs an `@` prefix while an image token must stay verbatim. */
+export declare const COMPOSER_IMAGE_TOKEN_EXACT: RegExp;
+export declare const formatMissingReference: (reference: string) => string;
+/** Resolve only capabilities explicitly carried by this draft, in first
+ *  textual-occurrence order. The visible token is presentation, never
+ *  identity: raw history/rewind text has no stageId and therefore resolves
+ *  to nothing even if a later draft happens to display the same number. */
+export declare function orderedComposerImages<T>(text: string, refs: readonly ComposerImageRef[], staged: ReadonlyMap<string, T>): Map<string, T>;
+/** The FIRST placeholder in `text` that resolved to no live capability: an
+ *  evicted (FIFO cap) or foreign draft's token would otherwise ship as plain
+ *  text with no image attached. Callers warn once and deliver unchanged. */
+export declare function firstStaleComposerToken(text: string, ordered: ReadonlyMap<string, unknown>): string | undefined;
+export interface ComposerImageLimits {
+    readonly maxImageBytes: number;
+    readonly maxImagesPerMessage: number;
+}
+/** The composer's staged-image capability store plus its draft-binding rules. */
+export interface ComposerImages {
+    /** Current composer generation. Async paste continuations capture this
+     *  before I/O and must not mutate a different session's draft. */
+    stagedImageGeneration(): number;
+    /** Validate and persist an image, returning the historical scene-facing
+     *  `[Image #N]` token accepted by submit/steer/registry commands. */
+    stageImage(input: StagedImageInput): Promise<string>;
+    /** Draft-safe composer companion: bind persistence to one session epoch
+     *  and return an opaque capability whose visible label belongs to Prompt. */
+    stageComposerImage(input: StagedImageInput, generation: number): Promise<StagedImageHandle>;
+    hasStagedImage(stageId: string): boolean;
+    discardStagedImage(stageId: string): void;
+    stagedImage(stageId: string): TranscriptImage | undefined;
+    stagedImageLimits(): ComposerImageLimits | undefined;
+    /** Revoke every capability of the session being replaced and bump the
+     *  generation so in-flight saves cannot register into the new one. */
+    clearStagedImages(): void;
+    /** Immutable view of the live capabilities (stageId → durable reference). */
+    snapshot(): ReadonlyMap<string, ChannelImageBlock['attachment']>;
+    /** Add scene-era token bindings only when the caller did not supply an
+     *  explicit draft capability for that visible token. */
+    includeLegacyImageRefs(text: string, images: readonly ComposerImageRef[]): readonly ComposerImageRef[];
+    /** Enqueue-time capture: legacy bindings merged, one object per ref. */
+    captureDraftImages(text: string, images: readonly ComposerImageRef[]): readonly ComposerImageRef[];
+}
+/**
+ * Owns the editable-composer image capabilities: the session epoch, the
+ * capability map, its preview facades and the `[Image #N]` compatibility
+ * bindings minted by the public scene `stageImage()` API.
+ */
+export declare function createComposerImages(ctx: Context, owner: ChannelOwner, deps: {
+    generation(): number;
+}): ComposerImages;
+//# sourceMappingURL=composer-images.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composer-images.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/composer-images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,QAAqB,CAAA;AAEtD;6EAC6E;AAC7E,eAAO,MAAM,0BAA0B,QAAsB,CAAA;AAE7D,eAAO,MAAM,sBAAsB,GAAI,WAAW,MAAM,KAAG,MACe,CAAA;AAE1E;;;2EAG2E;AAC3E,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,gBAAgB,EAAE,EACjC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,GAC7B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAehB;AAED;;4EAE4E;AAC5E,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,MAAM,GAAG,SAAS,CAKpB;AAOD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;CACrC;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B;sEACkE;IAClE,qBAAqB,IAAI,MAAM,CAAA;IAC/B;yEACqE;IACrE,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACpD;iFAC6E;IAC7E,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC3F,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;IACxC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAA;IACzD,iBAAiB,IAAI,mBAAmB,GAAG,SAAS,CAAA;IACpD;0EACsE;IACtE,iBAAiB,IAAI,IAAI,CAAA;IACzB,6EAA6E;IAC7E,QAAQ,IAAI,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAA;IAChE;4DACwD;IACxD,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,gBAAgB,EAAE,CAAA;IACtG,wEAAwE;IACxE,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,gBAAgB,EAAE,CAAA;CACnG;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE;IAAE,UAAU,IAAI,MAAM,CAAA;CAAE,GAC7B,cAAc,CAsKhB"}

package/lib/types/dsh-adapter/channel/composer-images.js

@@ -0,0 +1,217 @@
+import { randomUUID } from 'node:crypto';
+import { rememberImagePath, transcriptImageFromAttachment } from '../transcript-images.js';
+import { mentionAttachments } from './mentions.js';
+/** Every visible composer placeholder token, in source order. */
+export const COMPOSER_IMAGE_TOKEN = /\[Image #\d+\]/gu;
+/** One whole placeholder token; the distinction matters because a mention
+ *  reference needs an `@` prefix while an image token must stay verbatim. */
+export const COMPOSER_IMAGE_TOKEN_EXACT = /^\[Image #\d+\]$/u;
+export const formatMissingReference = (reference) => COMPOSER_IMAGE_TOKEN_EXACT.test(reference) ? reference : `@${reference}`;
+/** Resolve only capabilities explicitly carried by this draft, in first
+ *  textual-occurrence order. The visible token is presentation, never
+ *  identity: raw history/rewind text has no stageId and therefore resolves
+ *  to nothing even if a later draft happens to display the same number. */
+export function orderedComposerImages(text, refs, staged) {
+    const byToken = new Map();
+    for (const ref of refs) {
+        if (!byToken.has(ref.token))
+            byToken.set(ref.token, ref.stageId);
+    }
+    const ordered = new Map();
+    for (const match of text.matchAll(COMPOSER_IMAGE_TOKEN)) {
+        const token = match[0];
+        if (ordered.has(token))
+            continue;
+        const stageId = byToken.get(token);
+        if (stageId === undefined)
+            continue;
+        const image = staged.get(stageId);
+        if (image !== undefined)
+            ordered.set(token, image);
+    }
+    return ordered;
+}
+/** The FIRST placeholder in `text` that resolved to no live capability: an
+ *  evicted (FIFO cap) or foreign draft's token would otherwise ship as plain
+ *  text with no image attached. Callers warn once and deliver unchanged. */
+export function firstStaleComposerToken(text, ordered) {
+    for (const match of text.matchAll(COMPOSER_IMAGE_TOKEN)) {
+        if (!ordered.has(match[0]))
+            return match[0];
+    }
+    return undefined;
+}
+/** Insertion-order FIFO bound on live capabilities. References are
+ *  content-addressed and durable; this map only connects editable
+ *  placeholders to them. */
+const STAGED_IMAGE_LIMIT = 128;
+/**
+ * Owns the editable-composer image capabilities: the session epoch, the
+ * capability map, its preview facades and the `[Image #N]` compatibility
+ * bindings minted by the public scene `stageImage()` API.
+ */
+export function createComposerImages(ctx, owner, deps) {
+    /** Session epoch for the staged-image maps: bumped by every clear so a
+     *  `saveImage` that was still in flight when the session changed cannot
+     *  register its capability in the NEW session. */
+    let stagedImageEpoch = 0;
+    const stagedImages = new Map();
+    /** Compatibility bindings minted by the public scene `stageImage()` API.
+     * New Prompt drafts carry explicit opaque refs instead. */
+    const legacyStagedImageRefs = new Map();
+    let legacyStagedImageSequence = 0;
+    /** UI facades for staged capabilities, one stable object per id so the
+     *  component-side decode cache (keyed by object identity) can hit. Keys
+     *  mirror `stagedImages` exactly — same insert, evict and clear. */
+    const stagedImageViews = new Map();
+    const deleteStagedImage = (stageId) => {
+        stagedImages.delete(stageId);
+        stagedImageViews.delete(stageId);
+        for (const [token, candidate] of legacyStagedImageRefs) {
+            if (candidate === stageId)
+                legacyStagedImageRefs.delete(token);
+        }
+    };
+    const clearStagedImages = () => {
+        stagedImageEpoch += 1;
+        stagedImages.clear();
+        stagedImageViews.clear();
+        legacyStagedImageRefs.clear();
+        legacyStagedImageSequence = 0;
+    };
+    /** The binding generation the live capabilities belong to. Every entry
+     *  point re-checks it, so a replacement session revokes the old draft's
+     *  capabilities BEFORE any subscriber can observe it — the invariant the
+     *  single-file channel got by clearing immediately after the agent rebind,
+     *  made independent of the caller's ordering. */
+    let syncedGeneration;
+    const syncSession = () => {
+        const generation = deps.generation();
+        if (syncedGeneration === undefined) {
+            syncedGeneration = generation;
+            return;
+        }
+        if (generation === syncedGeneration)
+            return;
+        syncedGeneration = generation;
+        clearStagedImages();
+    };
+    const includeLegacyImageRefs = (text, images) => {
+        if (legacyStagedImageRefs.size === 0)
+            return images;
+        const merged = images.map(image => ({ ...image }));
+        const claimed = new Set(merged.map(image => image.token));
+        for (const match of text.matchAll(COMPOSER_IMAGE_TOKEN)) {
+            const token = match[0];
+            if (claimed.has(token))
+                continue;
+            const stageId = legacyStagedImageRefs.get(token);
+            if (stageId === undefined || !stagedImages.has(stageId))
+                continue;
+            merged.push({ token, stageId });
+            claimed.add(token);
+        }
+        return merged;
+    };
+    const persistComposerImage = async (input, generation) => {
+        syncSession();
+        const attachments = mentionAttachments(ctx);
+        if (attachments === undefined)
+            throw new Error('image attachments are unavailable in this profile');
+        if (generation !== stagedImageEpoch) {
+            throw new Error('the session changed while the image was being staged');
+        }
+        if (!attachments.imageLimits.mediaTypes.includes(input.mediaType)) {
+            throw new Error(`${input.mediaType} images are not accepted by this profile`);
+        }
+        if (input.data.byteLength > attachments.imageLimits.maxImageBytes) {
+            throw new Error(`image exceeds this profile's per-image size limit`);
+        }
+        // The source path is TUI-side display metadata; the store only sees the
+        // fields its contract names.
+        const { path, ...stored } = input;
+        const attachment = await attachments.saveImage(stored);
+        // A session change (/new, resume, rewind, model switch, background)
+        // cleared the maps while the save was in flight: the durable object is
+        // harmless, but the OLD session's capability must not reach the new one.
+        syncSession();
+        if (generation !== stagedImageEpoch) {
+            throw new Error('the session changed while the image was being staged');
+        }
+        const stageId = randomUUID();
+        stagedImages.set(stageId, attachment);
+        if (path !== undefined)
+            rememberImagePath(String(attachment.attachmentId), path);
+        const view = transcriptImageFromAttachment(attachment, () => ctx.get('attachments'));
+        if (view !== undefined)
+            stagedImageViews.set(stageId, view);
+        while (stagedImages.size > STAGED_IMAGE_LIMIT) {
+            const oldest = stagedImages.keys().next().value;
+            if (oldest === undefined)
+                break;
+            deleteStagedImage(oldest);
+        }
+        return { stageId };
+    };
+    return {
+        stagedImageGeneration() {
+            syncSession();
+            return stagedImageEpoch;
+        },
+        async stageImage(input) {
+            owner.assertActive();
+            syncSession();
+            const generation = stagedImageEpoch;
+            const { stageId } = await persistComposerImage(input, generation);
+            legacyStagedImageSequence += 1;
+            const token = `[Image #${legacyStagedImageSequence}]`;
+            legacyStagedImageRefs.set(token, stageId);
+            return token;
+        },
+        stageComposerImage(input, generation) {
+            owner.assertActive();
+            syncSession();
+            return persistComposerImage(input, generation);
+        },
+        hasStagedImage(stageId) {
+            syncSession();
+            return stagedImages.has(stageId);
+        },
+        discardStagedImage(stageId) {
+            // Revocation stays callable after disposal: the composer's own cleanup
+            // paths release capabilities they already own.
+            syncSession();
+            deleteStagedImage(stageId);
+        },
+        stagedImage(stageId) {
+            syncSession();
+            return stagedImageViews.get(stageId);
+        },
+        stagedImageLimits() {
+            syncSession();
+            const limits = mentionAttachments(ctx)?.imageLimits;
+            if (limits === undefined)
+                return undefined;
+            return {
+                maxImageBytes: limits.maxImageBytes,
+                maxImagesPerMessage: limits.maxImagesPerMessage,
+            };
+        },
+        clearStagedImages() {
+            syncSession();
+            clearStagedImages();
+        },
+        snapshot() {
+            syncSession();
+            return new Map(stagedImages);
+        },
+        includeLegacyImageRefs(text, images) {
+            syncSession();
+            return includeLegacyImageRefs(text, images);
+        },
+        captureDraftImages(text, images) {
+            syncSession();
+            return includeLegacyImageRefs(text, images).map(image => ({ ...image }));
+        },
+    };
+}

package/lib/types/dsh-adapter/channel/composer-mentions.d.ts

@@ -0,0 +1,15 @@
+import type { MentionAttachments, MentionExpansion, MentionFs, MentionImageBlock } from './types.js';
+/**
+ * Expand a submitted text's `@` mentions (issue #15) into model-facing
+ * attachment blocks: supported image files become durable image blocks,
+ * other files contribute capped text, and directories contribute a shallow
+ * listing. Reads always go through the active fs service, so provider-owned
+ * workspaces keep their routing semantics. The typed text stays first and
+ * verbatim. Best-effort failures degrade to `missing`, never a failed send.
+ *
+ * Staged composer images (`[Image #N]`) share ONE admission queue with
+ * `@image` files: the earliest reference in the user's text wins both the
+ * per-message count and byte budgets, and image blocks preserve that order.
+ */
+export declare function expandComposerMentions(fs: MentionFs | undefined, cwd: string, text: string, attachments?: MentionAttachments, stagedImages?: ReadonlyMap<string, MentionImageBlock['attachment']>): Promise<MentionExpansion>;
+//# sourceMappingURL=composer-mentions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composer-mentions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/composer-mentions.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEpG;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,kBAAkB,EAChC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC,GAClE,OAAO,CAAC,gBAAgB,CAAC,CAqL3B"}

package/lib/types/dsh-adapter/channel/composer-mentions.js

@@ -0,0 +1,200 @@
+import { isAbsolute, join } from 'node:path';
+import { extractMentions } from '../../utils/mentions.js';
+import { COMPOSER_IMAGE_TOKEN } from './composer-images.js';
+import { MENTION_MAX_DIR_ENTRIES, MENTION_MAX_FILE_CHARS, MENTION_MAX_TOTAL_CHARS, mentionImageMediaType, tryResolveMention, } from './mentions.js';
+import { basename } from './paths.js';
+/**
+ * Expand a submitted text's `@` mentions (issue #15) into model-facing
+ * attachment blocks: supported image files become durable image blocks,
+ * other files contribute capped text, and directories contribute a shallow
+ * listing. Reads always go through the active fs service, so provider-owned
+ * workspaces keep their routing semantics. The typed text stays first and
+ * verbatim. Best-effort failures degrade to `missing`, never a failed send.
+ *
+ * Staged composer images (`[Image #N]`) share ONE admission queue with
+ * `@image` files: the earliest reference in the user's text wins both the
+ * per-message count and byte budgets, and image blocks preserve that order.
+ */
+export async function expandComposerMentions(fs, cwd, text, attachments, stagedImages) {
+    const blocks = [{ type: 'text', text }];
+    const attached = [];
+    const missing = [];
+    const mentions = extractMentions(text);
+    let budget = MENTION_MAX_TOTAL_CHARS;
+    let imageCount = 0;
+    let imageBytes = 0;
+    const references = fs === undefined
+        ? []
+        : mentions.map(mention => ({ kind: 'mention', start: mention.start, mention }));
+    if (stagedImages !== undefined) {
+        const seen = new Set();
+        for (const match of text.matchAll(COMPOSER_IMAGE_TOKEN)) {
+            const token = match[0];
+            if (seen.has(token))
+                continue;
+            seen.add(token);
+            const attachment = stagedImages.get(token);
+            if (attachment === undefined)
+                continue;
+            references.push({
+                kind: 'staged-image',
+                start: match.index,
+                token,
+                attachment,
+            });
+        }
+    }
+    references.sort((a, b) => a.start - b.start);
+    // `@image` files and staged `[Image #N]` capabilities share one admission
+    // queue. The earliest reference in the user's text wins both the per-
+    // message count and byte budgets, and image blocks preserve that order.
+    for (const reference of references) {
+        if (reference.kind === 'staged-image') {
+            const { attachment, token } = reference;
+            // A referenced-but-dropped staged image must be loud: silently sending
+            // the bare token would leave the user believing the image reached the
+            // model. Reuse the missing-mention warning channel.
+            if (attachments === undefined) {
+                missing.push(token);
+                continue;
+            }
+            const limits = attachments.imageLimits;
+            if (imageCount >= limits.maxImagesPerMessage
+                || imageBytes + attachment.bytes > limits.maxMessageImageBytes
+                || !limits.mediaTypes.includes(attachment.mediaType)) {
+                missing.push(token);
+                continue;
+            }
+            blocks.push({ type: 'image', attachment });
+            imageCount += 1;
+            imageBytes += attachment.bytes;
+            continue;
+        }
+        if (fs === undefined)
+            continue;
+        const { mention } = reference;
+        const display = mention.literal ?? mention.path;
+        const imageMediaType = mentionImageMediaType(mention.path);
+        // A depleted text budget must not hide a later image reference: image
+        // admission has independent limits and still follows source order.
+        if (budget <= 0 && imageMediaType === undefined)
+            continue;
+        // Mentions resolve against the session cwd, same as the model-facing fs
+        // tools; absolute paths pass through untouched. A `#L12-14` line suffix
+        // (issue #359) is stripped before resolution; when the stripped path
+        // misses, the typed literal (suffix intact) gets ONE fallback try so
+        // filenames genuinely containing `#L…` still resolve as whole files.
+        const absolute = isAbsolute(mention.path) ? mention.path : join(cwd, mention.path);
+        let resolved = await tryResolveMention(fs, absolute);
+        let literalFallback = false;
+        if (resolved === undefined && mention.literal !== undefined) {
+            const literalPath = isAbsolute(mention.literal) ? mention.literal : join(cwd, mention.literal);
+            resolved = await tryResolveMention(fs, literalPath);
+            literalFallback = resolved !== undefined;
+        }
+        if (resolved === undefined) {
+            missing.push(display);
+            continue;
+        }
+        const { target, info } = resolved;
+        // On a literal-fallback hit the attached file IS the typed name — the
+        // model must see that path, not the suffix-stripped one.
+        const shownPath = literalFallback ? display : mention.path;
+        // …and judge image-ness by the typed extension in that case too.
+        const imageType = literalFallback && mention.literal !== undefined
+            ? mentionImageMediaType(mention.literal)
+            : imageMediaType;
+        if (info?.type === 'file') {
+            if (imageType !== undefined && attachments !== undefined && fs.readBytes !== undefined) {
+                const limits = attachments.imageLimits;
+                if (!limits.mediaTypes.includes(imageType) || imageCount >= limits.maxImagesPerMessage) {
+                    missing.push(display);
+                    continue;
+                }
+                try {
+                    const data = await fs.readBytes(target, undefined, limits.maxImageBytes);
+                    if (imageBytes + data.byteLength > limits.maxMessageImageBytes) {
+                        missing.push(display);
+                        continue;
+                    }
+                    const attachment = await attachments.saveImage({
+                        data,
+                        mediaType: imageType,
+                        name: basename(target.displayPath),
+                    });
+                    blocks.push({ type: 'image', attachment });
+                    imageCount += 1;
+                    imageBytes += data.byteLength;
+                    attached.push(display);
+                }
+                catch {
+                    missing.push(display);
+                }
+                continue;
+            }
+            try {
+                const cap = Math.min(MENTION_MAX_FILE_CHARS, budget);
+                const content = await fs.readText(target);
+                let body = content;
+                let truncated = false;
+                let header = `<attached-file path="${shownPath}">`;
+                if (mention.startLine !== undefined && !literalFallback) {
+                    // Line-range slice (issue #359): 1-based inclusive. An endLine
+                    // past EOF clamps to the file; a startLine past EOF falls back
+                    // to the whole file with an in-band note — never a silent
+                    // empty attach. Line ranges never apply to literal-fallback
+                    // hits (those files really are named `…#L…`, no suffix typed).
+                    const lines = content.split('\n');
+                    if (mention.startLine > lines.length) {
+                        header = `<attached-file path="${shownPath}" lines="${mention.startLine}-${mention.endLine}" note="requested lines beyond EOF (file has ${lines.length} line${lines.length === 1 ? '' : 's'}); whole file attached">`;
+                    }
+                    else {
+                        const endLine = Math.min(mention.endLine ?? mention.startLine, lines.length);
+                        header = `<attached-file path="${shownPath}" lines="${mention.startLine}${endLine === mention.startLine ? '' : `-${endLine}`}">`;
+                        body = lines.slice(mention.startLine - 1, endLine).join('\n');
+                    }
+                }
+                if (body.length > cap) {
+                    body = body.slice(0, cap);
+                    truncated = true;
+                }
+                budget -= body.length;
+                blocks.push({
+                    type: 'text',
+                    text: `${header}\n${body}${truncated ? '\n[… truncated]' : ''}\n</attached-file>`,
+                });
+                attached.push(display);
+            }
+            catch {
+                // Binary/undecodable or unreadable — report it like a miss.
+                missing.push(display);
+            }
+            continue;
+        }
+        if (info?.type === 'directory') {
+            try {
+                const entries = await fs.listDir(target);
+                const listing = entries
+                    .slice(0, MENTION_MAX_DIR_ENTRIES)
+                    .map(entry => (entry.type === 'directory' ? `${entry.name}/` : entry.name));
+                if (entries.length > MENTION_MAX_DIR_ENTRIES) {
+                    listing.push(`… (${entries.length - MENTION_MAX_DIR_ENTRIES} more)`);
+                }
+                const body = listing.join('\n');
+                budget -= body.length;
+                blocks.push({
+                    type: 'text',
+                    text: `<attached-directory path="${shownPath}">\n${body}\n</attached-directory>`,
+                });
+                attached.push(display);
+            }
+            catch {
+                missing.push(display);
+            }
+            continue;
+        }
+        // Absent (stat → undefined) or a special file.
+        missing.push(display);
+    }
+    return { blocks, attached, missing };
+}