@yadsh/dsh-qa-surface 0.10.0 → 0.11.0

package/lib/integration/answer.js

@@ -0,0 +1,100 @@
+import { messageContentText } from "../admin/conversation-log.js";
+/** The empty answer: what a turn that committed nothing readable looks like. */
+export const QA_EMPTY_ANSWER = Object.freeze({
+    answer: "",
+    interrupted: false,
+    seq: null,
+});
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Project the answer of the turn that starts after `afterSeq`.
+ *
+ * Only events after the caller's own prompt are read: a chat is continued
+ * across questions, and picking the last assistant message of the whole log
+ * would hand question #2 the answer to question #1 whenever the new turn
+ * committed nothing.
+ *
+ * @param events - durable events, in any order.
+ * @param afterSeq - the seq of the prompt whose answer is wanted.
+ * @returns the publishable answer and whether the turn was interrupted.
+ */
+export function answerAfter(events, afterSeq) {
+    const ordered = [...events].sort((left, right) => left.seq - right.seq);
+    let answer = "";
+    let seq = null;
+    let lastWasInterrupted = false;
+    for (const event of ordered) {
+        if (event.type !== "assistant/message" || event.seq <= afterSeq)
+            continue;
+        const data = record(event.data);
+        const message = record(data?.message);
+        lastWasInterrupted = data?.interrupted === true;
+        const text = messageContentText(message?.content).trim();
+        if (text === "")
+            continue;
+        answer = text;
+        seq = event.seq;
+    }
+    return Object.freeze({ answer, interrupted: lastWasInterrupted, seq });
+}
+/**
+ * Cut an answer down to the size the caller publishes.
+ *
+ * The bridge posts the answer into a ticket comment, which has a size budget
+ * of its own: an over-long comment is not rejected there, it is cut — and a cut
+ * that lands in the middle of a sentence, or worse inside a code block, reads
+ * like a broken answer. The cut therefore prefers the last paragraph break,
+ * then the last line, then the last sentence, and only then an arbitrary word
+ * boundary, and it appends an ellipsis so the reader sees that text is missing
+ * rather than finished. A boundary that would leave less than half the budget
+ * used is refused: a single early paragraph break must not turn a full answer
+ * into one line.
+ * @param answer - the settled answer, already trimmed.
+ * @param maxCharacters - the publish budget; a non-positive value never cuts.
+ * @returns the answer, or its bounded head.
+ */
+export function boundAnswer(answer, maxCharacters) {
+    if (maxCharacters <= 0 || answer.length <= maxCharacters)
+        return answer;
+    // The ellipsis itself is part of the budget, so a cut answer still fits in
+    // the limit the operator configured.
+    const head = answer.slice(0, maxCharacters - 1);
+    const floor = Math.floor(head.length / 2);
+    let kept = head;
+    for (const separator of ["\n\n", "\n", ". ", " "]) {
+        const at = head.lastIndexOf(separator);
+        if (at >= floor) {
+            kept = head.slice(0, separator === ". " ? at + 1 : at);
+            break;
+        }
+    }
+    return `${kept.replace(/\s+$/u, "")}…`;
+}
+/**
+ * The seq of the newest user-authored message in a log, which is the floor
+ * `answerAfter` reads from when the caller has just submitted a prompt.
+ * Synthetic context (injected notes, skill payloads) is skipped: it is model
+ * input recorded as a user message, and one arriving after the answer would
+ * otherwise hide it.
+ * @param events - durable events, in any order.
+ * @returns the seq, or 0 when the log holds no human prompt yet.
+ */
+export function lastPromptSeq(events) {
+    let seq = 0;
+    for (const event of events) {
+        if (event.type !== "user/message")
+            continue;
+        const data = record(event.data);
+        const source = record(data?.source);
+        if (source?.kind !== "user")
+            continue;
+        if (event.seq > seq)
+            seq = event.seq;
+    }
+    return seq;
+}
+//# sourceMappingURL=answer.js.map

package/lib/integration/answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.js","sourceRoot":"","sources":["../../src/integration/answer.ts"],"names":[],"mappings":"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"}

package/lib/integration/attachments.js

@@ -0,0 +1,231 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { QA_PDF_MEDIA_TYPE, QA_WORD_MEDIA_TYPE } from "../shared/documents.js";
+import { QaIntegrationAttachmentError, } from "./contract.js";
+/**
+ * Bringing a ticket's attachments into the prompt.
+ *
+ * An image rides the prompt inline, because that is what the harness carries.
+ * A file does not: `PromptContentPart` names one as an opaque receipt minted by
+ * the harness's own upload service, which an external caller has no session to
+ * reach — and that service is what stores the copy the model later reads with
+ * its file tools. The bridge's non-image attachments are therefore read *here*
+ * and arrive as text: a text file is decoded, a document is extracted through
+ * the deployment's own document pipeline (the same runtime, providers and
+ * limits the `document_*` tools use), and the result joins the prompt as one
+ * more text part.
+ *
+ * That is a deliberate trade. It costs the fidelity of a format the pipeline
+ * cannot read — such a request is refused with the bridge's own fallback signal
+ * rather than answered with a question the model cannot see the attachment for.
+ * It buys a path that works in every deployment shape: nothing is written into
+ * a shared workspace, the staging directory is temporary and removed after the
+ * extraction, and no second converter is grown inside this plugin.
+ */
+/**
+ * Plain-text formats the bridge sends; their bytes *are* the content, so
+ * decoding them needs no pipeline and cannot fail on a deployment.
+ */
+export const QA_INTEGRATION_TEXT_MEDIA_TYPES = Object.freeze(["text/plain", "text/csv", "text/markdown"]);
+/**
+ * Documents the deployment's pipeline is asked to extract. PDF and the OOXML
+ * family are what the bridge's own filter lets through; whether a particular
+ * one is readable is the pipeline's answer, not a list kept here.
+ */
+export const QA_INTEGRATION_DOCUMENT_MEDIA_TYPES = Object.freeze([
+    QA_PDF_MEDIA_TYPE,
+    QA_WORD_MEDIA_TYPE,
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+]);
+/** Total inlined attachment text per question, across every attachment. */
+export const QA_INTEGRATION_MAX_ATTACHMENT_CHARS = 120_000;
+/** No single attachment may claim the whole budget. */
+export const QA_INTEGRATION_MAX_ATTACHMENT_CHARS_PER_FILE = 60_000;
+/** A file name is a label in the prompt, not a path. */
+export const QA_INTEGRATION_MAX_ATTACHMENT_NAME = 120;
+/** Whether the bytes are the content: decoding needs only UTF-8. */
+export function isIntegrationTextMediaType(mediaType) {
+    return QA_INTEGRATION_TEXT_MEDIA_TYPES.includes(mediaType.trim().toLowerCase());
+}
+/** Whether the attachment has to go through the document pipeline. */
+export function isIntegrationDocumentMediaType(mediaType) {
+    return QA_INTEGRATION_DOCUMENT_MEDIA_TYPES.includes(mediaType.trim().toLowerCase());
+}
+/**
+ * Drop every C0/C1 control character and DEL.
+ *
+ * Spelled as a code-point filter rather than a character class: a name is a
+ * log field and a prompt heading, and a newline smuggled through one of those
+ * would let the caller forge lines in either.
+ */
+function stripControlCharacters(value) {
+    return Array.from(value)
+        .filter((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code > 0x1f && code !== 0x7f;
+    })
+        .join("");
+}
+/**
+ * Reduce a caller-supplied file name to the label a prompt can carry.
+ *
+ * The name arrives from another system and is used as a log field, a heading in
+ * the prompt and the file name of one temporary file — so directory parts,
+ * traversal, control characters and an unbounded length all have to go before
+ * it is any of those. An empty result is named by its media type.
+ * @param raw - the name the caller sent.
+ * @param mediaType - its media type, for the fallback name.
+ * @returns a safe, non-empty label.
+ */
+export function safeAttachmentName(raw, mediaType) {
+    const base = stripControlCharacters(path.basename(raw.replace(/\\/gu, "/")))
+        .replace(/^\.+/u, "")
+        .trim();
+    const bounded = base.slice(0, QA_INTEGRATION_MAX_ATTACHMENT_NAME);
+    if (bounded !== "")
+        return bounded;
+    const subtype = mediaType.split("/")[1] ?? "file";
+    return `attachment.${subtype.replace(/[^a-z0-9.]/giu, "")}`;
+}
+/** A human-readable size for the prompt's heading. */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${String(bytes)} Б`;
+    if (bytes < 1024 * 1024)
+        return `${String(Math.round(bytes / 1024))} КБ`;
+    const megabytes = bytes / (1024 * 1024);
+    return `${String(Math.round(megabytes * 10) / 10).replace(".", ",")} МБ`;
+}
+/**
+ * Whether a text attachment is actually text.
+ *
+ * A NUL byte in the head of a file is the cheapest reliable signal that the
+ * caller labelled something binary as text; decoding it would put replacement
+ * characters in the prompt and call it the document's content.
+ */
+function looksLikeText(bytes) {
+    return !bytes.subarray(0, 8192).includes(0);
+}
+/** Cut extracted text to the budget, on a line or word boundary where possible. */
+function boundText(text, budget) {
+    if (text.length <= budget)
+        return text;
+    const head = text.slice(0, budget);
+    const at = Math.max(head.lastIndexOf("\n"), head.lastIndexOf(" "));
+    return `${(at > 0 ? head.slice(0, at) : head).trimEnd()}…`;
+}
+/** One attachment as the prompt carries it: a heading and the readable content. */
+function attachmentBlock(input) {
+    const heading = `--- ${input.name} (${input.mediaType}, ${formatBytes(input.bytes)}) ---`;
+    const note = input.truncated
+        ? "\n\n[…текст сокращён, показано начало файла]"
+        : "";
+    return {
+        type: "text",
+        text: input.text === ""
+            ? `${heading}\n[файл прочитан, но не содержит текста]`
+            : `${heading}\n${input.text}${note}`,
+    };
+}
+/**
+ * Extract one document through the deployment's pipeline.
+ *
+ * The pipeline takes a path, not bytes, so the attachment is written to a
+ * temporary directory created for this one extraction, and that directory is
+ * the workspace root the conversion is scoped to. An unconfigured deployment
+ * therefore keeps the conversion's artifacts beside the input — inside the
+ * directory `finally` removes — while a deployment that configured its own
+ * artifact root keeps them under it, where its own retention sweep already
+ * governs them. Either way nothing lands in a workspace the deployment shares.
+ */
+async function extractDocumentText(file, name, deps) {
+    const documents = deps.documents;
+    if (documents === undefined) {
+        throw new QaIntegrationAttachmentError(name, "unavailable", "this deployment has no document pipeline");
+    }
+    const directory = await mkdtemp(path.join(tmpdir(), "qa-integration-attachment-"));
+    try {
+        const input = path.join(directory, name);
+        await writeFile(input, file.bytes, { mode: 0o600 });
+        const extracted = await documents.toMarkdown({ file: input }, {
+            workspaceRoot: directory,
+            sessionId: deps.sessionId,
+            signal: deps.signal,
+        });
+        return extracted.markdown;
+    }
+    catch (error) {
+        if (error instanceof QaIntegrationAttachmentError)
+            throw error;
+        deps.logger.warn("integration.attachment-unreadable", {
+            name,
+            mediaType: file.mediaType,
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw new QaIntegrationAttachmentError(name, "unsupported", `the document pipeline could not read ${name}`);
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Turn the request's file attachments into prompt text parts.
+ *
+ * The parts are appended after the question, in the order the caller sent them,
+ * and the question itself is untouched. A file the Host cannot read refuses the
+ * whole request: answering with the question but not its attachments would hand
+ * the model a question about material it never received, which is exactly what
+ * the bridge's 415 fallback exists to avoid.
+ *
+ * @param files - the non-image attachments of one request.
+ * @param deps - pipeline, session and budgets.
+ * @returns one text part per readable attachment, plus a note when the budget cut the list.
+ */
+export async function attachmentPromptParts(files, deps) {
+    if (files.length === 0)
+        return [];
+    const total = deps.maxChars ?? QA_INTEGRATION_MAX_ATTACHMENT_CHARS;
+    const parts = [];
+    let remaining = total;
+    let dropped = 0;
+    for (const file of files) {
+        if (remaining <= 0) {
+            dropped += 1;
+            continue;
+        }
+        const mediaType = file.mediaType.trim().toLowerCase();
+        const name = safeAttachmentName(file.name, mediaType);
+        let text;
+        if (isIntegrationTextMediaType(mediaType)) {
+            if (!looksLikeText(file.bytes)) {
+                throw new QaIntegrationAttachmentError(name, "unsupported", `${name} is not text`);
+            }
+            text = file.bytes.toString("utf8");
+        }
+        else {
+            text = await extractDocumentText(file, name, deps);
+        }
+        const budget = Math.min(remaining, QA_INTEGRATION_MAX_ATTACHMENT_CHARS_PER_FILE);
+        const bounded = boundText(text.trim(), budget);
+        remaining -= bounded.length;
+        parts.push(Object.freeze(attachmentBlock({
+            name,
+            mediaType,
+            bytes: file.bytes.length,
+            text: bounded,
+            truncated: bounded.length < text.trim().length,
+        })));
+    }
+    if (dropped > 0) {
+        parts.push({
+            type: "text",
+            text: `[${String(dropped)} вложений не показано: исчерпан предел текста вложений]`,
+        });
+    }
+    return Object.freeze(parts);
+}
+/** Re-exported so the runner does not reach into the contract for one name. */
+export { QaIntegrationAttachmentError };
+//# sourceMappingURL=attachments.js.map

package/lib/integration/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../src/integration/attachments.ts"],"names":[],"mappings":"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"}

package/lib/integration/contract.js

@@ -0,0 +1,53 @@
+/**
+ * The integration API's wire contract: what an external application may post to
+ * `/qa/api/ask`, what it gets back, and the refusal vocabulary the HTTP layer
+ * maps onto status codes.
+ *
+ * The shape follows the ticket bridge specification the deployment was asked to
+ * implement (issue #177): a Markdown `answer`, the `sources` that back it, a
+ * `confidence` bucket, an `escalate` flag for "the assistant could not answer,
+ * send it to a specialist", and a `reason` for the logs. `chat_id` is the DSH
+ * session identity: sending it back as `session_id` continues the same
+ * conversation, which is the whole point of the bridge keeping it.
+ */
+/**
+ * HTTP status per refusal. The mapping is part of the contract, not a detail:
+ * the bridge retries on 5xx and 429, falls back to a bodyless JSON request on
+ * 415, and treats 401/403 as a configuration error it must not spin on.
+ */
+export const QA_INTEGRATION_STATUS = Object.freeze({
+    unauthorized: 401,
+    forbidden: 403,
+    "not-found": 404,
+    "invalid-request": 400,
+    "unsupported-media": 415,
+    "payload-too-large": 413,
+    "rate-limited": 429,
+    busy: 429,
+    unavailable: 503,
+    timeout: 504,
+});
+/** One refusal, carrying the status the HTTP layer answers with. */
+export class QaIntegrationError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = "QaIntegrationError";
+        this.reason = reason;
+    }
+    get status() {
+        return QA_INTEGRATION_STATUS[this.reason];
+    }
+}
+/** One attachment the Host could not turn into prompt content. */
+export class QaIntegrationAttachmentError extends Error {
+    attachment;
+    reason;
+    constructor(attachment, reason, message) {
+        super(message);
+        this.attachment = attachment;
+        this.name = "QaIntegrationAttachmentError";
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=contract.js.map

package/lib/integration/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/integration/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAE9B,MAAM,CAAC,MAAM,CAAC;IAChB,YAAY,EAAE,GAAG;IACjB,SAAS,EAAE,GAAG;IACd,WAAW,EAAE,GAAG;IAChB,iBAAiB,EAAE,GAAG;IACtB,mBAAmB,EAAE,GAAG;IACxB,mBAAmB,EAAE,GAAG;IACxB,cAAc,EAAE,GAAG;IACnB,IAAI,EAAE,GAAG;IACT,WAAW,EAAE,GAAG;IAChB,OAAO,EAAE,GAAG;CACb,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,MAAM,CAAsB;IAErC,YACE,MAA2B,EAC3B,OAAe,EACf,OAAsC;QAEtC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;CACF;AA6CD,kEAAkE;AAClE,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAI1C,UAAU;IAHZ,MAAM,CAAgC;IAE/C,YACW,UAAkB,EAC3B,MAAqC,EACrC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;0BAJN,UAAU;QAKnB,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/lib/integration/host-runner.js

@@ -0,0 +1,243 @@
+import { randomUUID } from "node:crypto";
+import { SessionId } from "@deepseek-ai/dsh-session/types";
+import { WorkspaceId } from "@deepseek-ai/dsh-workspace";
+import { prepareQaUserWorkspace } from "../user-workspace.js";
+import { answerAfter, lastPromptSeq } from "./answer.js";
+import { attachmentPromptParts } from "./attachments.js";
+import { QaIntegrationTranscriptReader } from "./transcript-reader.js";
+/** Build the runner for one plugin instance. */
+export function createQaIntegrationRunner(options) {
+    const { ctx, logger } = options;
+    // One reader for the plugin's lifetime: its whole value is the windows it
+    // keeps between calls, so a per-request instance would be a slower copy of
+    // the plain projection.
+    const transcripts = new QaIntegrationTranscriptReader({
+        log: options.sessionLog,
+        logger,
+    });
+    const requireAccounts = () => {
+        const accounts = options.accounts();
+        if (accounts === undefined) {
+            throw new Error("QA accounts are not enabled on this deployment.");
+        }
+        return accounts;
+    };
+    const openChat = async (input) => {
+        const config = options.getConfig();
+        const accounts = requireAccounts();
+        const owner = accounts.accountById(input.userId);
+        if (owner === undefined) {
+            throw new Error("the integration token's account no longer exists");
+        }
+        const id = SessionId(`session-${randomUUID()}`);
+        // The ownership record is written before the session exists, exactly as
+        // the browser path does it: the id is minted here, so no other caller can
+        // claim it in between, and a failure below rolls the record back.
+        options.access.reserveSessionForUser(owner, String(id));
+        try {
+            options.admission.preflightDeployment();
+            let userCwd;
+            if (config.accounts.perUserWorkspace) {
+                const workspaceId = config.session.workspaceId;
+                if (workspaceId === null) {
+                    throw new Error("Per-user QA workspace configuration is unavailable.");
+                }
+                const workspace = ctx.workspaceRegistry.get(WorkspaceId(workspaceId));
+                if (workspace === undefined) {
+                    throw new Error(`Configured QA workspace ${workspaceId} is unavailable.`);
+                }
+                userCwd = prepareQaUserWorkspace(workspace.path, owner.id);
+            }
+            const created = await ctx.sessionController.create({
+                sessionId: id,
+                ...(userCwd !== undefined
+                    ? { cwd: userCwd }
+                    : config.session.workspaceId !== null
+                        ? { workspaceId: WorkspaceId(config.session.workspaceId) }
+                        : config.session.cwd !== null
+                            ? { cwd: config.session.cwd }
+                            : {}),
+                ...(config.session.agentPreset === null
+                    ? {}
+                    : { agentPreset: config.session.agentPreset }),
+            });
+            if (config.session.provider !== null && config.session.model !== null) {
+                await ctx.sessionController.selectModel({
+                    sessionId: created.sessionId,
+                    provider: config.session.provider,
+                    model: config.session.model,
+                    ...(config.session.reasoningEffort === null
+                        ? {}
+                        : { reasoningEffort: config.session.reasoningEffort }),
+                });
+            }
+            const sessionId = String(created.sessionId);
+            await options.admission.secureSessionForUser(owner.id, sessionId);
+            logger.info("integration.chat-opened", {
+                sessionId,
+                userId: owner.id,
+                ticketKey: input.ticketKey,
+            });
+            return sessionId;
+        }
+        catch (error) {
+            // Nothing else would ever remove the record: the chat was never
+            // returned to the caller, so no later call can name it.
+            accounts.releaseSessionReservation(owner.id, String(id));
+            throw error;
+        }
+    };
+    /** The newest durable cursor in a log, or 0 when there is nothing to read. */
+    const floorOf = async (sessionId) => {
+        const read = await options.sessionLog.read(sessionId);
+        if (!read.ok)
+            return 0;
+        return read.events.reduce((max, event) => Math.max(max, event.seq), 0);
+    };
+    /**
+     * The prompt of one question: the question, then the attachments.
+     *
+     * Images keep the shape the harness carries them in. Files are read on the
+     * Host — a text file decoded, a document extracted through the deployment's
+     * pipeline — and arrive as text under a heading per file, preceded by one
+     * lead line so the model knows why the question has more than it asked for.
+     * A file that cannot be read throws, which the service turns into the 415
+     * the caller's fallback understands: publishing an answer to a question the
+     * model could not see the attachment for is worse than asking again without
+     * it.
+     */
+    const promptParts = async (message, attachments, sessionId, signal) => {
+        const images = attachments
+            .filter((attachment) => attachment.kind === "image")
+            .map((attachment) => ({
+            type: "image",
+            mediaType: attachment.mediaType,
+            data: attachment.data,
+            ...(attachment.name === undefined ? {} : { name: attachment.name }),
+        }));
+        const files = attachments.filter((attachment) => attachment.kind === "file");
+        if (files.length === 0) {
+            return [{ type: "text", text: message }, ...images];
+        }
+        const extracted = await attachmentPromptParts(files, {
+            documents: options.documents(),
+            sessionId,
+            signal,
+            logger,
+        });
+        return [
+            { type: "text", text: message },
+            ...images,
+            { type: "text", text: QA_ATTACHMENT_LEAD },
+            ...extracted,
+        ];
+    };
+    return {
+        async run(input) {
+            const chatId = input.chatId === null
+                ? await openChat({
+                    userId: input.userId,
+                    ticketKey: input.ticketKey,
+                })
+                : input.chatId;
+            input.onChat?.(chatId);
+            if (input.chatId !== null) {
+                // A continued chat is re-attested before every question. The same call
+                // the browser makes when it opens a session: it is what refuses a
+                // chat belonging to another account (the ownership record is the
+                // authority) and what keeps the tool policy applied to a session
+                // resumed by a process that has never seen it.
+                await options.admission.secureSessionForUser(input.userId, chatId);
+            }
+            const floor = await floorOf(chatId);
+            const content = await promptParts(input.message, input.attachments, chatId, input.signal);
+            // The client mints this identity; the harness brands it. A plain UUID
+            // is exactly what a browser sends, and it is what makes the prompt
+            // idempotent if the same question is ever retried.
+            const requestId = randomUUID();
+            await ctx.sessionController.prompt({
+                requestId,
+                sessionId: SessionId(chatId),
+                mode: "queue",
+                content,
+            }, input.signal);
+            const agent = ctx.agents.get(SessionId(chatId));
+            if (agent === undefined) {
+                throw new Error("the QA session has no live agent");
+            }
+            await whenIdleOrAborted(agent, input.signal);
+            const read = await options.sessionLog.read(chatId);
+            if (!read.ok) {
+                throw new Error(`the session log is unavailable (${read.reason})`);
+            }
+            // The prompt's own event may be missing from an empty snapshot, so the
+            // floor is the later of the cursor taken before the question and the
+            // newest human prompt the log knows about. Either way the answer is the
+            // last assistant message after it, and no earlier turn can be read as
+            // this one's answer.
+            const projected = answerAfter(read.events, Math.max(floor, lastPromptSeq(read.events)));
+            return Object.freeze({
+                chatId,
+                answer: projected.answer,
+                sources: sourcesOf(chatId),
+                interrupted: projected.interrupted,
+            });
+        },
+        async transcript(input) {
+            return await transcripts.page(input.chatId, {
+                after: input.after,
+                limit: input.limit,
+            });
+        },
+        async models() {
+            const catalog = await ctx.sessionController.modelCatalog();
+            return catalog.groups.flatMap((group) => group.models.map((model) => model.id));
+        },
+    };
+    /**
+     * The evidence of the chat's latest turn, for the bridge's citations. The
+     * provenance store materializes one bundle per turn; the newest is the one
+     * that belongs to the answer just written. A deployment that switched
+     * source collection off answers with an empty list rather than no answer.
+     */
+    function sourcesOf(sessionId) {
+        try {
+            const bundles = options.provenance.bundles(sessionId);
+            return bundles.at(-1)?.sources ?? [];
+        }
+        catch (error) {
+            logger.warn("integration.sources-unavailable", {
+                sessionId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+}
+/**
+ * The one line that explains the text parts after the question. It says where
+ * the material came from and nothing about what to do with it: the deployment's
+ * own prompt notes own the instructions, and this block is content.
+ */
+const QA_ATTACHMENT_LEAD = "Вложения к этому вопросу — файлы, пришедшие из внешней системы вместе с " +
+    "обращением. Их содержимое приведено ниже под заголовком с именем файла.";
+/** Wait for the agent to reach quiescence, or for the caller to give up. */
+async function whenIdleOrAborted(agent, signal) {
+    if (signal.aborted)
+        throw abortReason(signal);
+    await Promise.race([
+        agent.whenIdle(),
+        new Promise((_resolve, reject) => {
+            signal.addEventListener("abort", () => {
+                reject(abortReason(signal));
+            }, { once: true });
+        }),
+    ]);
+}
+function abortReason(signal) {
+    const reason = signal.reason;
+    return reason instanceof Error
+        ? reason
+        : new Error("the integration request was aborted");
+}
+//# sourceMappingURL=host-runner.js.map