@addozhang/dsh-discord 0.1.0

package/lib/features/approval-view.js

@@ -0,0 +1,48 @@
+/**
+ * Approval control rendering (design.md §8, task 13.1). A pending DSH
+ * approval renders as Allow once / Reject buttons whose custom_ids are
+ * opaque registry keys minted per control — session, rpc, approval, tool,
+ * and reason data never ride the Discord wire. Visible text reuses the
+ * activity surface's safe allowlisted labels (generic fallback) and the
+ * outbound mention posture: the host-supplied reason is mention-neutralized
+ * and bounded before display.
+ */
+import { DISCORD_SUPPRESS_NOTIFICATIONS_FLAG } from '../policy/disclosure.js';
+import { suppressMentionSyntax } from '../policy/suppress.js';
+import { toolLabel } from '../stream/tool-view.js';
+/** The reason text cap; the host decides content, the adapter decides size. */
+const REASON_MAX = 300;
+/** Discord interactive-component ids (action row = 1, button = 2). */
+const ACTION_ROW = 1;
+const BUTTON = 2;
+const BUTTON_STYLE_SUCCESS = 3;
+const BUTTON_STYLE_DANGER = 4;
+function boundedReason(reason) {
+    const neutralized = suppressMentionSyntax(reason);
+    return neutralized.length <= REASON_MAX ? neutralized : `${neutralized.slice(0, REASON_MAX)}…`;
+}
+/**
+ * Render one pending approval. Both controls resolve through the registry to
+ * `{ approvalId, action, expiresAtMs }`, so routing (13.2/13.3) recovers the
+ * pending record from durable state, never from the wire.
+ */
+export function renderApprovalControls(input) {
+    const { registry } = input;
+    const allowId = registry.register({ approvalId: input.approvalId, action: 'allow', expiresAtMs: input.expiresAtMs });
+    const rejectId = registry.register({ approvalId: input.approvalId, action: 'reject', expiresAtMs: input.expiresAtMs });
+    const reason = input.reason === undefined ? '' : `\n${boundedReason(input.reason)}`;
+    const content = `Approval required — ${toolLabel(input.toolName)}${reason}`;
+    return {
+        content,
+        flags: DISCORD_SUPPRESS_NOTIFICATIONS_FLAG,
+        components: [
+            {
+                type: ACTION_ROW,
+                components: [
+                    { type: BUTTON, style: BUTTON_STYLE_SUCCESS, label: 'Allow once', custom_id: allowId },
+                    { type: BUTTON, style: BUTTON_STYLE_DANGER, label: 'Reject', custom_id: rejectId },
+                ],
+            },
+        ],
+    };
+}

package/lib/features/ask-wiring.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Composition wiring for the answerable server-request face (approvals and
+ * questions): ownership resolution, record opening, control rendering, and
+ * render-failure abandonment in one testable unit. This is the layer where
+ * the live incidents lived (an actor lost across turns, a batch built from
+ * the wrong field names) — so the wiring is a module, not inline glue.
+ *
+ * Ownership rule: the active turn's Discord author wins; when DSH starts
+ * follow-up turns without a new submission the durable thread creator falls
+ * back as owner (Milestone 1: one thread, one session, one owner).
+ */
+import type { ComponentRegistry } from '../discord/components.js';
+import type { ApprovalStore } from './approval-store.js';
+import type { QuestionStore } from './question-store.js';
+import type { DshTurnCancelPort } from './question-expiry.js';
+/** One approval ask projected from the Host mux frame. */
+export interface ApprovalAskInput {
+    sessionId: string;
+    threadId: string;
+    rpcId: string;
+    approvalId: string;
+    toolName: string;
+    reason?: string | undefined;
+    expiresAtMs: number;
+}
+/** One question ask projected from the Host mux frame (raw question rows). */
+export interface QuestionAskInput {
+    sessionId: string;
+    threadId: string;
+    rpcId: string;
+    expiresAtMs: number;
+    questions: ReadonlyArray<Record<string, unknown>>;
+}
+export interface AskWiringDeps {
+    registry: ComponentRegistry;
+    approvals: ApprovalStore;
+    questions: QuestionStore;
+    /** Cancellation face for asks that can never be answered. */
+    cancelPort: DshTurnCancelPort;
+    nowMs(): number;
+    log(event: string, detail?: unknown): void;
+    /** Request id of the adapter-owned active turn, when the adapter owns one. */
+    activeTurnRequestId(sessionId: string): string | undefined;
+    /** The Discord author recorded for a submitted request id. */
+    turnActor(requestId: string): string | undefined;
+    /** The durable thread binding's creator, when the thread is bound. */
+    threadOwner(threadId: string): string | undefined;
+    /**
+     * Post one rendered control message into the ask's thread. `stored` is
+     * true only when Discord accepted the message and returned its id;
+     * otherwise `reason` carries the failure cause for the log.
+     */
+    postMessage(threadId: string, payload: unknown): Promise<{
+        stored: boolean;
+        reason?: string;
+        messageId?: string;
+    }>;
+}
+export declare function createAskWiring(deps: AskWiringDeps): {
+    /** Retire a rendered control (clear components) once the ask is settled. */
+    disableControl(key: string): Promise<void>;
+    onApprovalRequested(input: ApprovalAskInput): void;
+    onApprovalResolved(input: {
+        sessionId: string;
+        approvalId: string;
+        outcome?: string | undefined;
+    }): void;
+    onQuestionRequested(input: QuestionAskInput): void;
+    onQuestionResolved(input: {
+        sessionId: string;
+        questionRpcId: string;
+        outcome: 'answered' | 'cancelled';
+    }): void;
+};

package/lib/features/ask-wiring.js

@@ -0,0 +1,151 @@
+/**
+ * Composition wiring for the answerable server-request face (approvals and
+ * questions): ownership resolution, record opening, control rendering, and
+ * render-failure abandonment in one testable unit. This is the layer where
+ * the live incidents lived (an actor lost across turns, a batch built from
+ * the wrong field names) — so the wiring is a module, not inline glue.
+ *
+ * Ownership rule: the active turn's Discord author wins; when DSH starts
+ * follow-up turns without a new submission the durable thread creator falls
+ * back as owner (Milestone 1: one thread, one session, one owner).
+ */
+import { renderApprovalControls } from './approval-view.js';
+import { renderQuestionControls } from './question-view.js';
+import { abandonUnrenderableQuestion } from './question-expiry.js';
+import { handleRemoteResolution } from './question-routing.js';
+export function createAskWiring(deps) {
+    /** Discord message refs for rendered controls, keyed by ask id. */
+    const controlMessages = new Map();
+    const disableControl = async (key) => {
+        const target = controlMessages.get(key);
+        if (target === undefined)
+            return;
+        controlMessages.delete(key);
+        // Retirement is best-effort: a failed disable must never fail the ask's
+        // settled outcome — the registry TTL keeps stray clicks answerable.
+        try {
+            const posted = await deps.postMessage(target.channelId, { components: [] });
+            if (!posted.stored)
+                deps.log('discord_control_disable_failed', { key });
+        }
+        catch (cause) {
+            deps.log('discord_control_disable_failed', { key, cause: String(cause) });
+        }
+    };
+    function resolveAskActor(sessionId, threadId) {
+        const requestId = deps.activeTurnRequestId(sessionId);
+        if (requestId !== undefined) {
+            const actor = deps.turnActor(requestId);
+            if (actor !== undefined)
+                return { actorUserId: actor, actorSource: 'turn' };
+        }
+        const owner = deps.threadOwner(threadId);
+        if (owner !== undefined)
+            return { actorUserId: owner, actorSource: 'thread-binding' };
+        return { actorUserId: '', actorSource: 'none' };
+    }
+    return {
+        disableControl,
+        onApprovalRequested: (input) => {
+            const { actorUserId, actorSource } = resolveAskActor(input.sessionId, input.threadId);
+            const requestId = deps.activeTurnRequestId(input.sessionId) ?? '';
+            deps.log('discord_approval_opened', {
+                approvalId: input.approvalId, requestId, actorUserId, actorSource,
+                sessionId: input.sessionId, threadId: input.threadId,
+            });
+            deps.approvals.open({
+                approvalId: input.approvalId,
+                sessionId: input.sessionId,
+                threadId: input.threadId,
+                requestId,
+                rpcId: input.rpcId,
+                actorUserId,
+                toolName: input.toolName,
+                reason: input.reason,
+                expiresAtMs: input.expiresAtMs,
+                state: 'pending',
+            });
+            const payload = renderApprovalControls({
+                registry: deps.registry,
+                sessionId: input.sessionId,
+                rpcId: input.rpcId,
+                approvalId: input.approvalId,
+                toolName: input.toolName,
+                reason: input.reason,
+                expiresAtMs: input.expiresAtMs,
+            });
+            void deps.postMessage(input.threadId, payload)
+                .then(sent => {
+                if (sent.stored && sent.messageId !== undefined) {
+                    controlMessages.set(input.approvalId, { channelId: input.threadId, messageId: sent.messageId });
+                }
+            })
+                .catch((cause) => { deps.log('discord_approval_render_failed', String(cause)); });
+        },
+        onApprovalResolved: (input) => {
+            const record = deps.approvals.get(input.approvalId);
+            if (record !== undefined && record.state === 'pending') {
+                void deps.approvals.markResolved(input.approvalId, input.outcome === 'allowed-once' ? 'allowed-once' : 'rejected', deps.nowMs());
+            }
+            void disableControl(input.approvalId);
+        },
+        onQuestionRequested: (input) => {
+            const { actorUserId, actorSource } = resolveAskActor(input.sessionId, input.threadId);
+            const requestId = deps.activeTurnRequestId(input.sessionId) ?? '';
+            deps.log('discord_question_opened', {
+                questionRpcId: input.rpcId, requestId, actorUserId, actorSource,
+                sessionId: input.sessionId, threadId: input.threadId,
+            });
+            const batch = {
+                questionRpcId: input.rpcId,
+                sessionId: input.sessionId,
+                threadId: input.threadId,
+                requestId,
+                actorUserId,
+                expiresAtMs: input.expiresAtMs,
+                questions: input.questions.map(question => ({
+                    id: typeof question['id'] === 'string' ? question['id'] : '',
+                    question: typeof question['question'] === 'string' ? question['question'] : '',
+                    header: typeof question['header'] === 'string' ? question['header'] : undefined,
+                    options: Array.isArray(question['options'])
+                        ? question['options'].map(option => ({
+                            label: typeof option.label === 'string'
+                                ? option.label
+                                : '',
+                        }))
+                        : undefined,
+                    multiSelect: question['multiSelect'] === true,
+                })),
+            };
+            const opened = deps.questions.open(batch);
+            if (!opened.ok) {
+                deps.log('discord_question_open_rejected', { error: opened.error });
+                return;
+            }
+            const payload = renderQuestionControls({ registry: deps.registry, batch });
+            // Controls that never reached Discord can never be answered: cancel
+            // the owning Turn now instead of letting the sweep wait out the
+            // deadline with DSH's tool call hanging.
+            const abandonQuestion = (cause) => {
+                deps.log('discord_question_render_failed', cause);
+                void abandonUnrenderableQuestion({ store: deps.questions, cancelPort: deps.cancelPort, nowMs: () => deps.nowMs() }, input.rpcId).catch(() => { });
+            };
+            void deps.postMessage(input.threadId, payload)
+                .then(sent => {
+                if (!sent.stored || sent.messageId === undefined) {
+                    abandonQuestion(sent.reason ?? 'post rejected');
+                    return;
+                }
+                controlMessages.set(input.rpcId, { channelId: input.threadId, messageId: sent.messageId });
+            })
+                .catch((cause) => { abandonQuestion(String(cause)); });
+        },
+        onQuestionResolved: (input) => {
+            void handleRemoteResolution({
+                store: deps.questions,
+                controls: { disable: key => disableControl(key) },
+                nowMs: () => deps.nowMs(),
+            }, { questionRpcId: input.questionRpcId, outcome: input.outcome }).catch((cause) => { deps.log('discord_question_remote_resolve_failed', String(cause)); });
+        },
+    };
+}

package/lib/features/host-status.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `/host status` and the process-management refusal (design.md Non-Goals,
+ * task 10.5). The adapter reports connectivity and version metadata and does
+ * nothing else to its host: start/stop/restart/upgrade requests refuse
+ * explicitly and ephemerally — the embedded adapter cannot manage the
+ * process it lives in.
+ */
+export interface DshHostPort {
+    status(): Promise<{
+        outcome: 'completed';
+        connected: boolean;
+        version: string | undefined;
+    } | {
+        outcome: 'failed';
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+export type HostStatusView = {
+    outcome: 'ok';
+    connected: boolean;
+    version: string | undefined;
+} | {
+    outcome: 'failed';
+    reason: 'host-status-unavailable' | 'host-status-unknown';
+};
+export declare function hostStatus(port: DshHostPort): Promise<HostStatusView>;
+export type ProcessActionResult = {
+    outcome: 'refused';
+    reason: 'process-management-unavailable';
+    response: 'ephemeral';
+};
+/**
+ * Refuse any host process action. The optional control surface exists only
+ * so tests can prove the refusal never reaches for it.
+ */
+export declare function planProcessAction(request: {
+    action: 'start' | 'stop' | 'restart' | 'upgrade';
+}, deps?: {
+    processControl?: (...args: never[]) => unknown;
+}): Promise<ProcessActionResult>;

package/lib/features/host-status.js

@@ -0,0 +1,24 @@
+/**
+ * `/host status` and the process-management refusal (design.md Non-Goals,
+ * task 10.5). The adapter reports connectivity and version metadata and does
+ * nothing else to its host: start/stop/restart/upgrade requests refuse
+ * explicitly and ephemerally — the embedded adapter cannot manage the
+ * process it lives in.
+ */
+export async function hostStatus(port) {
+    const status = await port.status();
+    if (status.outcome === 'failed')
+        return { outcome: 'failed', reason: 'host-status-unavailable' };
+    if (status.outcome === 'unknown')
+        return { outcome: 'failed', reason: 'host-status-unknown' };
+    return { outcome: 'ok', connected: status.connected, version: status.version };
+}
+/**
+ * Refuse any host process action. The optional control surface exists only
+ * so tests can prove the refusal never reaches for it.
+ */
+export function planProcessAction(request, deps = {}) {
+    void request;
+    void deps;
+    return Promise.resolve({ outcome: 'refused', reason: 'process-management-unavailable', response: 'ephemeral' });
+}

package/lib/features/image-collection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bounded image collection (design.md §12, task 12.2). Every download is
+ * bounded four ways: the DECLARED size is checked before any fetch, the
+ * ACTUAL byte count of the response body is checked against the aggregate
+ * cap before the image is accepted, an aggregate cap spans the whole
+ * message, and a timeout stops a hung transfer. The HTTP port hands back one
+ * complete body, so peak memory for a single image is that body's size —
+ * bounded in practice by Discord CDN attachment limits and the aggregate
+ * cap, not by streaming. Refusals are plain values.
+ */
+/** Per-image cap (design: bounded by DSH-advertised limits; adapter-capped). */
+export declare const MAX_IMAGE_BYTES: number;
+/** Aggregate cap across all images of one message. */
+export declare const MAX_AGGREGATE_IMAGE_BYTES: number;
+export interface ImageDownloadPort {
+    download(request: {
+        url: string;
+    }): Promise<{
+        outcome: 'downloaded';
+        mediaType: string;
+        body: Uint8Array;
+    } | {
+        outcome: 'unsupported-media-type';
+    } | {
+        outcome: 'rejected-host';
+    } | {
+        outcome: 'malformed-url';
+    } | {
+        outcome: 'too-many-redirects';
+    } | {
+        outcome: 'http-error';
+        status: number;
+    }>;
+}
+export interface ImageAttachment {
+    url: string;
+    declaredSize: number;
+    contentType: string;
+}
+export type ImageCollectionResult = {
+    outcome: 'collected';
+    images: number;
+    totalBytes: number;
+} | {
+    outcome: 'too-large';
+    reason: 'declared' | 'actual' | 'aggregate';
+} | {
+    outcome: 'timeout';
+} | {
+    outcome: 'download-failed';
+};
+export declare function collectImages(port: ImageDownloadPort, request: {
+    nowMs: number;
+    timeoutMs: number;
+    attachments: ReadonlyArray<ImageAttachment>;
+}): Promise<ImageCollectionResult>;

package/lib/features/image-collection.js

@@ -0,0 +1,79 @@
+/**
+ * Bounded image collection (design.md §12, task 12.2). Every download is
+ * bounded four ways: the DECLARED size is checked before any fetch, the
+ * ACTUAL byte count of the response body is checked against the aggregate
+ * cap before the image is accepted, an aggregate cap spans the whole
+ * message, and a timeout stops a hung transfer. The HTTP port hands back one
+ * complete body, so peak memory for a single image is that body's size —
+ * bounded in practice by Discord CDN attachment limits and the aggregate
+ * cap, not by streaming. Refusals are plain values.
+ */
+/** Per-image cap (design: bounded by DSH-advertised limits; adapter-capped). */
+export const MAX_IMAGE_BYTES = 8 * 1_024 * 1_024;
+/** Aggregate cap across all images of one message. */
+export const MAX_AGGREGATE_IMAGE_BYTES = 24 * 1_024 * 1_024;
+/**
+ * Wrap the safe download boundary with byte-count enforcement: the body size
+ * is checked against the remaining aggregate budget before it is accepted,
+ * so memory stays bounded no matter what the peer sends.
+ */
+function boundedDownloadPort(inner, state) {
+    return {
+        download: async (request) => {
+            const result = await inner.download(request);
+            if (result.outcome !== 'downloaded')
+                return result;
+            if (result.body.byteLength > state.remainingBytes) {
+                return { outcome: 'http-error', status: 413 };
+            }
+            state.remainingBytes -= result.body.byteLength;
+            return result;
+        },
+    };
+}
+export function collectImages(port, request) {
+    let remainingAggregate = MAX_AGGREGATE_IMAGE_BYTES;
+    let images = 0;
+    let totalBytes = 0;
+    const inner = port;
+    async function run() {
+        for (const attachment of request.attachments) {
+            // Declared size: checked BEFORE the fetch.
+            if (attachment.declaredSize > MAX_IMAGE_BYTES) {
+                return { outcome: 'too-large', reason: 'declared' };
+            }
+            if (attachment.declaredSize > remainingAggregate) {
+                return { outcome: 'too-large', reason: 'aggregate' };
+            }
+            const bounded = boundedDownloadPort(inner, { remainingBytes: Math.min(MAX_IMAGE_BYTES, remainingAggregate) });
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => { resolve('timeout'); }, request.timeoutMs);
+            });
+            const downloaded = await Promise.race([
+                bounded.download({ url: attachment.url }).then((result) => result),
+                timeout,
+            ]).finally(() => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            });
+            if (downloaded === 'timeout')
+                return { outcome: 'timeout' };
+            if (downloaded.outcome === 'downloaded') {
+                if (downloaded.body.byteLength > MAX_IMAGE_BYTES) {
+                    return { outcome: 'too-large', reason: 'actual' };
+                }
+                images += 1;
+                totalBytes += downloaded.body.byteLength;
+                remainingAggregate -= downloaded.body.byteLength;
+                continue;
+            }
+            if (downloaded.outcome === 'http-error' && downloaded.status === 413) {
+                return { outcome: 'too-large', reason: 'actual' };
+            }
+            return { outcome: 'download-failed' };
+        }
+        return { outcome: 'collected', images, totalBytes };
+    }
+    return run();
+}

package/lib/features/image-download.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The safe image download boundary (design.md §12, task 12.1). Images enter
+ * only from allowlisted Discord CDN hosts over HTTPS with supported media
+ * types. Redirects are followed at most ONE hop and every hop revalidates
+ * against the same host/protocol rules — an open redirect cannot leak the
+ * bot's fetch authority to a foreign server. Every rejection is a value
+ * decided BEFORE any network activity where possible.
+ */
+export type ImageUrlValidation = {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+};
+/**
+ * Validate an untrusted image URL: HTTPS, an exact allowlisted host, and a
+ * parseable URL. Host matching is exact — suffix lookalikes
+ * (`cdn.discordapp.com.evil.com`) refuse.
+ */
+export declare function validateImageUrl(rawUrl: string): ImageUrlValidation;
+/** The fetch surface the downloader uses (no redirect following built in). */
+export interface HttpFetchPort {
+    fetch(url: string): Promise<{
+        status: number;
+        contentType: string | undefined;
+        location?: string | undefined;
+        body?: Uint8Array | undefined;
+    }>;
+}
+export type SafeImageResult = {
+    outcome: 'downloaded';
+    mediaType: string;
+    body: Uint8Array;
+} | {
+    outcome: 'malformed-url';
+} | {
+    outcome: 'rejected-host';
+} | {
+    outcome: 'unsupported-media-type';
+} | {
+    outcome: 'too-many-redirects';
+} | {
+    outcome: 'http-error';
+    status: number;
+};
+export declare function fetchSafeImage(port: HttpFetchPort, request: {
+    url: string;
+}): Promise<SafeImageResult>;

package/lib/features/image-download.js

@@ -0,0 +1,77 @@
+/**
+ * The safe image download boundary (design.md §12, task 12.1). Images enter
+ * only from allowlisted Discord CDN hosts over HTTPS with supported media
+ * types. Redirects are followed at most ONE hop and every hop revalidates
+ * against the same host/protocol rules — an open redirect cannot leak the
+ * bot's fetch authority to a foreign server. Every rejection is a value
+ * decided BEFORE any network activity where possible.
+ */
+const ALLOWED_HOSTS = new Set([
+    'cdn.discordapp.com',
+    'media.discordapp.net',
+]);
+const SUPPORTED_MEDIA_TYPES = new Set([
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+    'image/gif',
+]);
+const MAX_REDIRECTS = 1;
+/**
+ * Validate an untrusted image URL: HTTPS, an exact allowlisted host, and a
+ * parseable URL. Host matching is exact — suffix lookalikes
+ * (`cdn.discordapp.com.evil.com`) refuse.
+ */
+export function validateImageUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return { ok: false };
+    }
+    if (url.protocol !== 'https:')
+        return { ok: false };
+    if (!ALLOWED_HOSTS.has(url.hostname))
+        return { ok: false };
+    return { ok: true, url };
+}
+async function fetchOnce(port, hopsLeft, request) {
+    const validation = validateImageUrl(request.url);
+    if (!validation.ok) {
+        return isParseable(request.url) ? { outcome: 'rejected-host' } : { outcome: 'malformed-url' };
+    }
+    const response = await port.fetch(request.url);
+    if (response.status >= 300 && response.status < 400) {
+        if (hopsLeft === 0)
+            return { outcome: 'too-many-redirects' };
+        const location = response.location;
+        if (location === undefined)
+            return { outcome: 'http-error', status: response.status };
+        return fetchOnce(port, hopsLeft - 1, { url: location });
+    }
+    if (response.status !== 200) {
+        return { outcome: 'http-error', status: response.status };
+    }
+    const contentType = (response.contentType ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
+    if (!SUPPORTED_MEDIA_TYPES.has(contentType)) {
+        return { outcome: 'unsupported-media-type' };
+    }
+    return {
+        outcome: 'downloaded',
+        mediaType: contentType,
+        body: response.body ?? new Uint8Array(),
+    };
+}
+function isParseable(rawUrl) {
+    try {
+        void new URL(rawUrl);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function fetchSafeImage(port, request) {
+    return fetchOnce(port, MAX_REDIRECTS, request);
+}

package/lib/features/image-submission.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Image submission through `session.prompt` (design.md §12, task 12.3).
+ * Mixed text/images encode into ordered prompt parts; the model's modality
+ * is checked BEFORE any DSH call; and the request id claims an intent so a
+ * duplicate Discord delivery never resubmits. Host outcomes map to values
+ * with the intent state kept honest (failed on rejection, unknown preserved
+ * for reconciliation).
+ */
+import { type IntentStore } from '../state/intents.js';
+export type PromptPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+};
+export interface DshImagePromptPort {
+    submit(request: {
+        requestId: string;
+        sessionId: string;
+        parts: readonly PromptPart[];
+    }): Promise<{
+        outcome: 'accepted';
+    } | {
+        outcome: 'rejected';
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+export interface ImageSubmissionDeps {
+    prompts: DshImagePromptPort;
+    intents: IntentStore;
+    /** Whether the session's current model accepts image parts. */
+    modality: () => boolean;
+    nowMs: () => number;
+}
+export type ImageSubmissionResult = {
+    outcome: 'accepted';
+} | {
+    outcome: 'rejected';
+} | {
+    outcome: 'unknown';
+} | {
+    outcome: 'already-submitted';
+} | {
+    outcome: 'conflict';
+} | {
+    outcome: 'refused';
+    reason: 'unsupported-modality';
+};
+/** Encode text plus images into ordered prompt parts. */
+export declare function encodePromptParts(text: string, images: ReadonlyArray<{
+    mediaType: string;
+    base64: string;
+}>): PromptPart[];
+export declare function createImageSubmissionFlow(deps: ImageSubmissionDeps): {
+    submit(request: {
+        requestId: string;
+        sessionId: string;
+        text: string;
+        images: ReadonlyArray<{
+            mediaType: string;
+            base64: string;
+        }>;
+    }): Promise<ImageSubmissionResult>;
+};