@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/channel/command-completions.js

@@ -0,0 +1,94 @@
+import { completeCommands, isCommandCompletionToken } from '../../commands.js';
+import { SESSION_COLOR_NAMES } from '../../terminal-utils/sessionColors.js';
+import { getLang, LANGS } from '../../i18n.js';
+import { AUTO_THEME_NAME } from '../../theme.js';
+import { listThemeCatalog } from '../../themeCatalog.js';
+import { PRESET_NAMES } from '../../components/activityFrames.js';
+/** Owns slash completion composition and cache warming; it has no lifecycle effects. */
+export function createCommandCompletions(deps) {
+    const { themeHost, commandTrees, workspaceCommands, model } = deps;
+    return (input) => {
+        const state = deps.state();
+        const head = input.slice(1).split(/[\t ]/)[0]?.toLowerCase() ?? '';
+        if (head !== '') {
+            if ('model'.startsWith(head))
+                model.warmModelNodes();
+            if ('preset'.startsWith(head))
+                model.warmPresetOptions();
+            if ('effort'.startsWith(head))
+                model.warmEffortLevels();
+        }
+        return completeCommands(input, state.commandList, path => {
+            if (path.length === 1 && path[0] === 'model') {
+                model.warmModelNodes();
+                return model.modelNodes();
+            }
+            if (path.length === 1 && path[0] === 'lang')
+                return [
+                    { name: 'status', description: 'Show the current UI language', descriptionKey: 'sugg-status-desc' },
+                    ...LANGS.map(lang => ({ name: lang, description: `Switch the UI language to ${lang}`, descriptionKey: lang === 'zh' ? 'sugg-lang-zh-desc' : 'sugg-lang-en-desc', ...(getLang() === lang ? { tag: 'current' } : {}) })),
+                ];
+            if (path.length === 1 && path[0] === 'theme')
+                return [
+                    { name: 'status', description: 'Show the current theme', descriptionKey: 'sugg-status-desc' },
+                    { name: AUTO_THEME_NAME, description: 'Follow the terminal background', descriptionKey: 'sugg-theme-auto-desc' },
+                    ...listThemeCatalog(themeHost).filter(entry => entry.name !== AUTO_THEME_NAME).map(entry => {
+                        const base = entry.base ?? 'dark';
+                        if (entry.source === 'builtin')
+                            return { name: entry.name, description: `Built-in theme ${entry.name}`, descriptionKey: 'sugg-theme-builtin-desc' };
+                        if (entry.source === 'runtime')
+                            return { name: entry.name, description: `Plugin theme (${base} base)`, descriptionKey: 'sugg-theme-plugin-desc' };
+                        return { name: entry.name, description: `User theme (${base} base)`, descriptionKey: 'sugg-theme-user-desc' };
+                    }),
+                ];
+            if (path.length === 1 && path[0] === 'color')
+                return [
+                    { name: 'status', description: 'Show the current session color', descriptionKey: 'sugg-status-desc' },
+                    { name: 'reset', description: 'Clear the session color', descriptionKey: 'sugg-color-reset-desc' },
+                    ...SESSION_COLOR_NAMES.map(name => ({ name, description: 'Session accent color', descriptionKey: 'sugg-color-name-desc', ...(state.sessionColor === name ? { tag: 'current' } : {}) })),
+                ];
+            if (path.length === 1 && path[0] === 'effort') {
+                model.warmEffortLevels();
+                return [{ name: 'status', description: 'Show the current reasoning effort', descriptionKey: 'sugg-status-desc' }, ...(state.effortLevels ?? []).map(id => ({ name: id, description: 'Reasoning effort level', descriptionKey: 'sugg-effort-level-desc', ...(state.reasoningEffort === id ? { tag: 'current' } : {}) }))];
+            }
+            if (path.length === 1 && path[0] === 'preset') {
+                model.warmPresetOptions();
+                return [{ name: 'status', description: 'Show the current agent preset', descriptionKey: 'sugg-status-desc' }, ...model.presetOptions().map(preset => ({ name: preset.id, description: preset.description ?? preset.name ?? preset.id, ...(preset.id === state.agentPreset ? { tag: 'current' } : preset.isDefault ? { tag: 'default' } : {}) }))];
+            }
+            if (path.length === 1 && path[0] === 'activity')
+                return [
+                    { name: 'status', description: 'Show the current activity preset', descriptionKey: 'sugg-status-desc' },
+                    { name: 'frames', description: 'List or switch frame presets', descriptionKey: 'sugg-activity-frames-desc' },
+                ];
+            if (path.length === 2 && path[0] === 'activity' && path[1] === 'frames')
+                return PRESET_NAMES.map(name => ({ name, description: 'Animation frame preset', descriptionKey: 'sugg-activity-frame-desc', ...(state.activityFrames === name ? { tag: 'current' } : {}) }));
+            if (path.length === 1 && path[0] === 'workspace') {
+                const builtins = [
+                    { name: 'resume', description: 'Switch to another workspace', descriptionKey: 'cmd-desc-workspace-resume' },
+                    { name: 'rename', description: 'Rename the current workspace', descriptionKey: 'cmd-desc-workspace-rename' },
+                    { name: 'open', description: 'Open a path or workspace URI', descriptionKey: 'cmd-desc-workspace-open' },
+                ];
+                const reserved = new Set(builtins.map(command => command.name));
+                return [...builtins, ...workspaceCommands().filter(command => !reserved.has(command.name.toLowerCase())).map(command => ({
+                        name: command.name,
+                        ...(command.aliases === undefined ? {} : { aliases: command.aliases }),
+                        description: command.description ?? '',
+                    }))];
+            }
+            if (path.length === 1 && path[0] === 'permission') {
+                const snapshot = state.permissionPresets();
+                return snapshot.options.filter(option => isCommandCompletionToken(option.value)).map(option => ({
+                    name: option.value, description: option.description ?? option.name,
+                    ...(option.value === 'read-only' ? { descriptionKey: 'permission-preset-readonly-desc' } : option.value === 'workspace-write' ? { descriptionKey: 'permission-preset-workspace-write-desc' } : option.value === 'danger-full-access' ? { descriptionKey: 'permission-preset-full-access-desc' } : {}),
+                    ...(snapshot.current?.kind === 'preset' && snapshot.current.value === option.value ? { tag: 'current' } : {}),
+                }));
+            }
+            if (path.length === 1 && path[0] === 'plan')
+                return [
+                    { name: 'on', description: 'Enter plan mode: read-only, plan before acting', descriptionKey: 'plan-mode-on-desc' },
+                    { name: 'off', description: 'Exit plan mode, back to normal execution', descriptionKey: 'plan-mode-off-desc' },
+                ];
+            return commandTrees?.children(path) ?? [];
+        });
+    };
+}

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

@@ -0,0 +1,8 @@
+/** Internal command composition follows the same production UI dispatcher.
+ * A bare createChannel embedder intentionally keeps its direct local API.
+ */
+import type { ChannelUi } from '../../adapter/channel/ui-policy.js';
+import type { ChannelState } from './types.js';
+export declare function bindChannelCommands(state: ChannelState, commands: ChannelUi): void;
+export declare function channelCommands(state: ChannelState): ChannelUi | ChannelState;
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/commands.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAI9C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI,CAIlF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,GAAG,YAAY,CAE7E"}

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,18 @@
+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;
+}): {
+    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;CACf;mBAuBmB,IAAI;kBAlBC,OAAO,CAAC,IAAI,CAAC;EAuGvC"}

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

@@ -0,0 +1,114 @@
+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'));
+                }
+                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,62 @@
+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;
+    /** Per-side intrinsic pixel cap mirrored from the upstream store so the
+     *  ingress gate can resample before staging (issue #938). */
+    readonly maxImageDimension: number;
+    /** Total-pixel cap ditto. */
+    readonly maxImagePixels: 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;AAMlD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAEhB,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;IACpC;iEAC6D;IAC7D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,6BAA6B;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;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;AA0BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE;IAAE,UAAU,IAAI,MAAM,CAAA;CAAE,GAC7B,cAAc,CAyPhB"}

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

@@ -0,0 +1,316 @@
+import { randomUUID } from 'node:crypto';
+import { rememberImagePath, transcriptImageFromAttachment } from '../transcript-images.js';
+import { probeImageSize, adaptImageForAdmission, withinDimensionLimits } from '../../utils/imageResize.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;
+/** Failure text for a refusal the ingress gate can state before the store:
+ *  every reason except a missing sharp describes an image the deployment
+ *  would reject anyway, so the paste is refused with the cause named. */
+function admissionFailure(outcome, context) {
+    switch (outcome.reason) {
+        case 'sharp-missing':
+            return context.probe !== null
+                ? `image is ${context.probe.width}×${context.probe.height} (over ${context.limits.maxImageDimension}px) and sharp is unavailable to resample it`
+                : `${context.mediaType} is not accepted by this profile and sharp is unavailable to convert it`;
+        case 'animated-unsupported':
+            return `resizing or converting this animated image cannot keep its frames (${outcome.detail})`;
+        default:
+            return `image could not be decoded to resize or convert it (${outcome.detail})`;
+    }
+}
+/** A store-reported pixel dimension, or the gate's own value when the store
+ *  reported none (lean attachment fakes in the verify scripts). */
+const positiveOr = (value, fallback) => typeof value === 'number' && value > 0 ? value : fallback;
+/**
+ * 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 (input.data.byteLength > attachments.imageLimits.maxImageBytes) {
+            throw new Error(`image exceeds this profile's per-image size limit`);
+        }
+        // Ingress adaptation (issue #938): the store admits by media type, byte
+        // budget and the per-side / total pixel caps, and refuses on all of them
+        // when the bytes reach it. Measure and re-encode HERE instead, while the
+        // paste can still be explained to the user. Admission is judged against
+        // the pair this gate HANDS OVER (the store may normalize further on its
+        // own — that step is outside this feature), and both triggers are
+        // size-independent:
+        //   * a source media type the profile does not accept is converted, so a
+        //     small PNG is never refused while a large one succeeds;
+        //   * a probe-recognized image inside the caps skips sharp entirely;
+        //   * an unrecognized format is decoded for measurement (never trusted by
+        //     byte budget alone — the #432 gap);
+        //   * with sharp absent the image goes to the store unchanged ONLY while
+        //     it is still admissible as-is — an accepted format whose size the
+        //     probe could not prove fits (upstream stays the backstop); a measured
+        //     oversize, a decode failure, an unaccepted format or a multi-frame
+        //     image this gate would have to re-encode is reported now instead of
+        //     becoming a token that dies at save time.
+        // The runtime guards keep older attachment fakes (whose imageLimits
+        // predate the dimension fields) on the legacy synchronous path.
+        const dimensionCap = attachments.imageLimits.maxImageDimension;
+        const pixelCap = attachments.imageLimits.maxImagePixels;
+        let mediaType = input.mediaType;
+        let data = input.data;
+        let adapted;
+        if (typeof dimensionCap === 'number' && typeof pixelCap === 'number'
+            && Number.isFinite(dimensionCap) && Number.isFinite(pixelCap)) {
+            const dimensionLimits = { maxImageDimension: dimensionCap, maxImagePixels: pixelCap };
+            const probe = probeImageSize(data);
+            const sourceAccepted = attachments.imageLimits.mediaTypes.includes(mediaType);
+            // Only a probe-measured oversize is *known* to be refused by the store;
+            // an unmeasurable image may well be admissible, which is what keeps the
+            // sharp-less degradation a degradation rather than a guess.
+            const knownOversize = probe !== null && !withinDimensionLimits(probe, dimensionLimits);
+            if (!sourceAccepted || probe === null || knownOversize) {
+                const outcome = await adaptImageForAdmission(data, mediaType, dimensionLimits, attachments.imageLimits.mediaTypes);
+                if (outcome.kind === 'adapted') {
+                    // outcome.mediaType comes from the accepted list inside the gate, so
+                    // it is one of the profile's media types at runtime — narrowing,
+                    // not trusting.
+                    mediaType = outcome.mediaType;
+                    data = outcome.data;
+                    adapted = outcome;
+                    if (data.byteLength > attachments.imageLimits.maxImageBytes) {
+                        throw new Error(`image still exceeds this profile's per-image size limit after resampling`);
+                    }
+                }
+                else if (outcome.kind === 'unavailable') {
+                    // Degrade ONLY when the paste is still admissible as-is: an accepted
+                    // format whose size the probe could not prove fits. Everything else
+                    // (measured oversize, unaccepted format, decode failure, animation
+                    // that cannot survive) is a refusal we can state now.
+                    const degraded = outcome.reason === 'sharp-missing' && sourceAccepted && !knownOversize;
+                    if (!degraded)
+                        throw new Error(admissionFailure(outcome, { probe, mediaType, limits: dimensionLimits }));
+                }
+            }
+        }
+        // What the store will actually see: an accepted media type, inside the
+        // byte cap. A media type can still be unaccepted here only when the
+        // adaptation did not run (legacy limits) or could not produce one.
+        if (!attachments.imageLimits.mediaTypes.includes(mediaType)) {
+            throw new Error(`${mediaType} images are not accepted by this profile`);
+        }
+        // The source path is TUI-side display metadata; the store only sees the
+        // fields its contract names. mediaType/data may be the adapted pair from
+        // the ingress gate above.
+        const { path, ...stored } = input;
+        const attachment = await attachments.saveImage({ ...stored, mediaType, data });
+        // 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);
+        }
+        // The adjustment travels with the capability so the composer can say what
+        // happened instead of letting a rewritten image reach the store silently.
+        // Its numbers come from the STORE's own report, not from what this gate
+        // handed over: the store normalizes further (dimensions, and the media type
+        // too), and a notice quoting the gate's numbers would contradict the
+        // preview card the user is looking at.
+        const adjustment = adapted === undefined ? undefined : {
+            sourceMediaType: input.mediaType,
+            mediaType: attachment.mediaType,
+            width: positiveOr(attachment.width, adapted.width),
+            height: positiveOr(attachment.height, adapted.height),
+            resized: adapted.resized
+                || positiveOr(attachment.width, adapted.width) !== adapted.width
+                || positiveOr(attachment.height, adapted.height) !== adapted.height,
+            flattened: adapted.flattened,
+        };
+        return adjustment === undefined ? { stageId } : { stageId, adjustment };
+    };
+    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,
+                maxImageDimension: limits.maxImageDimension,
+                maxImagePixels: limits.maxImagePixels,
+            };
+        },
+        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 }));
+        },
+    };
+}