@yadsh/dsh-qa-surface 0.10.0 → 0.11.1

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
 import type { QaTurnSources } from "./provenance/types.js";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaDocumentPreview, QaLockdownProof, QaOwnershipEntry, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaWorkspaceFile, QaWorkspaceListing, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaUserQuery } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaDocumentPreview, QaIssuedServiceToken, QaLockdownProof, QaOwnershipEntry, QaPasswordResetRequest, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaServiceTokenCreateInput, QaServiceTokenSummary, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaAdminSkillScope, QaAdminSkillsView, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaWorkspaceFile, QaWorkspaceListing, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaUserQuery } from "./types.js";
 export declare const name = "qa-surface";
 export declare const inject: string[];
 import { QA_SURFACE_SETTINGS_NAMESPACE } from "./shared/settings.js";
@@ -51,6 +51,14 @@ export declare class QaSurface extends TypertRemoteService {
     private webServer;
     private disposeRoute;
     private routeKey;
+    /**
+     * The HTTP API an external application asks questions through. Constructed
+     * always — it is cheap and stateless until a request arrives — and exposed
+     * on the network only while the deployment turns it on.
+     */
+    private readonly integration;
+    private disposeIntegrationRoutes;
+    private integrationRouteKey;
     /**
      * The quality store opens its file on first use, so a deployment that never
      * opens the admin console never grows one.
@@ -108,6 +116,15 @@ export declare class QaSurface extends TypertRemoteService {
     accountsRegister(email: string, password: string): QaAccountSession;
     accountsLogin(email: string, password: string): QaAccountSession;
     /** Identity probe; safe to call with an empty or expired token. */
+    accountsChangePassword(token: string, currentPassword: string, nextPassword: string): QaAccountSession;
+    /**
+     * The sign-in screen's "забыли пароль?" path. It answers the same way for
+     * every address: whether an account exists is not something this endpoint
+     * tells a caller.
+     */
+    accountsRequestPasswordReset(email: string): {
+        readonly accepted: true;
+    };
     accountsWhoami(token: string): QaWhoamiResult;
     /**
      * Migrate a browser's local chat index into server-side ownership. The
@@ -140,6 +157,29 @@ export declare class QaSurface extends TypertRemoteService {
      * deployment's limits are enforced in the store before anything is written.
      */
     accountsUpdateStarters(token: string, input: QaAccountStartersInput): QaAccountUserPublic;
+    /**
+     * The caller's own integration tokens. The list is the account's own: the
+     * token names it, and a secret is never part of a summary, so reading this
+     * cannot repeat a credential that was already handed over.
+     */
+    accountsListServiceTokens(token: string): {
+        readonly tokens: readonly QaServiceTokenSummary[];
+    };
+    /**
+     * Mint one integration token for the caller. The answer carries the
+     * plaintext exactly once — nothing stores it, so nothing can repeat it — and
+     * the account is always the authenticated one: there is no owner field on
+     * the wire.
+     */
+    accountsCreateServiceToken(token: string, input: QaServiceTokenCreateInput): QaIssuedServiceToken;
+    /**
+     * Revoke one of the caller's own integration tokens. This is the immediate
+     * kill switch the profile page offers: the next request that presents the
+     * credential is refused, without waiting for its expiry.
+     */
+    accountsRevokeServiceToken(token: string, tokenId: string): {
+        readonly revoked: boolean;
+    };
     /**
      * Serve the effective QA configuration to the browser. The DSH gateway pins
      * settings RPCs to loopback, so a browser served over the LAN always sees
@@ -171,12 +211,35 @@ export declare class QaSurface extends TypertRemoteService {
     accessUpdateSkillOverride(token: string, input: QaSkillAssignmentOverride): readonly QaSkillAssignmentOverride[];
     /** What each skill activation actually granted in this session. */
     accessSkillActivations(token: string, sessionId: string): readonly QaSkillActivationRecord[];
+    /**
+     * The skill catalog of one scope: the deployment's shared skills, or the
+     * personal skills of the account the scope names. Reading another account's
+     * skills is an administrative act, so it needs `skills.manage`.
+     */
+    adminSkills(token: string, scope: QaAdminSkillScope): Promise<QaAdminSkillsView>;
+    /** One skill file with the body, revision and administrator mark. */
+    adminSkill(token: string, scope: QaAdminSkillScope, name: string): Promise<QaSkillDocument>;
+    /**
+     * Create (`name` null) or replace one skill in place. The write is recorded
+     * as this administrator's, and the owner sees that it was.
+     */
+    adminSkillSave(token: string, scope: QaAdminSkillScope, name: string | null, input: QaSkillDraftInput): Promise<QaSkillDocument>;
+    /** Remove one skill into the trash beside its own skills root. */
+    adminSkillDelete(token: string, scope: QaAdminSkillScope, name: string, expectedRevision: string | null): Promise<QaSkillRemoval>;
+    /** The file a save would write, plus every diagnostic for the draft. */
+    adminSkillValidate(token: string, scope: QaAdminSkillScope, name: string | null, input: QaSkillDraftInput): Promise<QaSkillValidation>;
+    /** The tool catalog the picker offers for one scope. */
+    adminSkillTools(token: string, scope: QaAdminSkillScope): Promise<{
+        readonly tools: readonly QaSkillToolDescriptor[];
+    }>;
     /** Counters, attention lines and the newest quality signals. */
     adminOverview(token: string): Promise<QaAdminOverview>;
     adminUsers(token: string, query: QaUserQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaAdminUserRow>>;
     adminUser(token: string, userId: string): Promise<QaAdminUserDetail>;
     /** Authorization role, status and subrole assignment of one account. */
     adminUpdateUser(token: string, userId: string, update: QaAdminUserUpdate): Promise<QaAdminUserDetail>;
+    adminPasswordResetRequests(token: string): Promise<readonly QaPasswordResetRequest[]>;
+    adminResetPassword(token: string, userId: string, password: string): Promise<QaAdminUserDetail>;
     adminConversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaConversationSummary>>;
     /** One conversation with its messages, tool calls and review state. */
     adminConversation(token: string, conversationId: string): Promise<QaConversationDetail>;
@@ -322,6 +385,15 @@ export declare class QaSurface extends TypertRemoteService {
      * the transcript row is read from.
      */
     slashExecute(token: string, sessionId: string, line: string, attachments: readonly QaSlashSubmitAttachment[]): Promise<QaSlashExecution>;
+    /**
+     * Register (or drop) the integration API's routes for the current config.
+     *
+     * The key is the whole registration decision — whether the API is on and
+     * where it lives — so a config change that does not move the endpoints
+     * leaves the live routes alone, and turning the API off disposes them
+     * immediately rather than at the next restart.
+     */
+    private refreshIntegrationRoutes;
     private refreshRoute;
     /**
      * A deployment that set `lockdown.allowSlashCommands: true` before this

package/lib/types/integration/answer.d.ts

@@ -0,0 +1,65 @@
+import type { StoredSessionEvent } from "../admin/conversation-log.js";
+/**
+ * Reading one answered turn out of a session log.
+ *
+ * The log is the durable record of the conversation, and it is what the
+ * integration API publishes: the live assistant stream is a presentation
+ * channel that can be abandoned mid-attempt, while `assistant/message` events
+ * are what was actually committed. A turn with tools in it commits several
+ * assistant messages — the intermediate steps carry tool calls and usually no
+ * prose — so the answer is the *last one that has text*, not simply the last
+ * one written. If a later empty message follows a text one, publishing the
+ * empty message would answer the bridge with nothing.
+ */
+/** The answer of one settled turn, plus how the turn ended. */
+export interface QaTurnAnswer {
+    /** The publishable text; empty when the turn committed no prose at all. */
+    readonly answer: string;
+    /** True when the last committed assistant message was interrupted. */
+    readonly interrupted: boolean;
+    /** Durable seq of the message the answer came from, when there was one. */
+    readonly seq: number | null;
+}
+/** The empty answer: what a turn that committed nothing readable looks like. */
+export declare const QA_EMPTY_ANSWER: QaTurnAnswer;
+/**
+ * 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 declare function answerAfter(events: readonly StoredSessionEvent[], afterSeq: number): QaTurnAnswer;
+/**
+ * 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 declare function boundAnswer(answer: string, maxCharacters: number): string;
+/**
+ * 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 declare function lastPromptSeq(events: readonly StoredSessionEvent[]): number;
+//# sourceMappingURL=answer.d.ts.map

package/lib/types/integration/attachments.d.ts

@@ -0,0 +1,85 @@
+import type { PromptContentPart } from "@deepseek-ai/dsh-api-session-controller";
+import type { DocumentsFace } from "@yadsh/dsh-documents";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import { QaIntegrationAttachmentError, type QaFileAttachment } 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 declare const QA_INTEGRATION_TEXT_MEDIA_TYPES: readonly string[];
+/**
+ * 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 declare const QA_INTEGRATION_DOCUMENT_MEDIA_TYPES: readonly string[];
+/** Total inlined attachment text per question, across every attachment. */
+export declare const QA_INTEGRATION_MAX_ATTACHMENT_CHARS = 120000;
+/** No single attachment may claim the whole budget. */
+export declare const QA_INTEGRATION_MAX_ATTACHMENT_CHARS_PER_FILE = 60000;
+/** A file name is a label in the prompt, not a path. */
+export declare const QA_INTEGRATION_MAX_ATTACHMENT_NAME = 120;
+/** Whether the bytes are the content: decoding needs only UTF-8. */
+export declare function isIntegrationTextMediaType(mediaType: string): boolean;
+/** Whether the attachment has to go through the document pipeline. */
+export declare function isIntegrationDocumentMediaType(mediaType: string): boolean;
+/**
+ * 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 declare function safeAttachmentName(raw: string, mediaType: string): string;
+/** What the extraction needs from the Host, as a port. */
+export interface QaAttachmentDependencies {
+    /** The document pipeline, or undefined on a deployment without it. */
+    readonly documents: DocumentsFace | undefined;
+    /** The chat the prompt belongs to; the pipeline records artifacts against it. */
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+    readonly logger: PluginLogger;
+    /** Total inlined characters for this question. */
+    readonly maxChars?: number;
+}
+/**
+ * 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 declare function attachmentPromptParts(files: readonly QaFileAttachment[], deps: QaAttachmentDependencies): Promise<readonly PromptContentPart[]>;
+/** Re-exported so the runner does not reach into the contract for one name. */
+export { QaIntegrationAttachmentError };
+//# sourceMappingURL=attachments.d.ts.map

package/lib/types/integration/contract.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 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.
+ */
+import type { QaSourceReference } from "../provenance/types.js";
+/** Why one integration request was refused, in the bridge's own vocabulary. */
+export type QaIntegrationReason = "unauthorized" | "forbidden" | "not-found" | "invalid-request" | "unsupported-media" | "payload-too-large" | "rate-limited" | "busy" | "unavailable" | "timeout";
+/**
+ * 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 declare const QA_INTEGRATION_STATUS: Readonly<Record<QaIntegrationReason, number>>;
+/** One refusal, carrying the status the HTTP layer answers with. */
+export declare class QaIntegrationError extends Error {
+    readonly reason: QaIntegrationReason;
+    constructor(reason: QaIntegrationReason, message: string, options?: {
+        readonly cause?: unknown;
+    });
+    get status(): number;
+}
+/** One image the caller attached, already bounded and decoded to base64. */
+export interface QaInlineImageAttachment {
+    readonly kind: "image";
+    /** A raster media type; anything else is refused before it gets here. */
+    readonly mediaType: string;
+    /** base64 bytes, exactly as the harness prompt content carries them. */
+    readonly data: string;
+    readonly name?: string;
+}
+/**
+ * One non-image file the caller attached, still as bytes.
+ *
+ * Files cannot ride a prompt the way images do: the harness carries a file as
+ * an opaque receipt minted by its own upload service, which an external caller
+ * has no session to reach. What the bridge sends instead is read on the Host —
+ * text files decoded, documents extracted through the deployment's document
+ * pipeline — and the resulting text joins the prompt, which is the same
+ * material the model would have read out of the stored copy.
+ */
+export interface QaFileAttachment {
+    readonly kind: "file";
+    readonly mediaType: string;
+    readonly name: string;
+    /** Raw bytes, bounded by the configured per-attachment ceiling. */
+    readonly bytes: Buffer;
+}
+/** One attachment of a parsed request, in the order the caller sent it. */
+export type QaIntegrationAttachment = QaInlineImageAttachment | QaFileAttachment;
+/**
+ * Why one attachment could not become prompt content, in the vocabulary the
+ * service maps onto HTTP.
+ *
+ * `unsupported` is the bridge's own fallback signal (415): repeat the question
+ * without attachments. `unavailable` is the same answer for a document the
+ * deployment cannot read right now, and the two are deliberately distinct only
+ * in the log — a caller sees one status either way.
+ */
+export type QaIntegrationAttachmentReason = "unsupported" | "unavailable";
+/** One attachment the Host could not turn into prompt content. */
+export declare class QaIntegrationAttachmentError extends Error {
+    readonly attachment: string;
+    readonly reason: QaIntegrationAttachmentReason;
+    constructor(attachment: string, reason: QaIntegrationAttachmentReason, message: string);
+}
+/** A parsed `POST /qa/api/ask` body, whichever encoding carried it. */
+export interface QaAskRequest {
+    /** The question; at least one non-whitespace character. */
+    readonly message: string;
+    /** Product version the bridge extracted from the ticket, when it knew one. */
+    readonly version: string | null;
+    /** The chat to continue, or null for a new one. */
+    readonly sessionId: string | null;
+    /** Ticket metadata the operator sees in the log line. */
+    readonly context: QaAskContext;
+    readonly attachments: readonly QaIntegrationAttachment[];
+}
+/** The ticket metadata the bridge sends along; all of it is optional. */
+export interface QaAskContext {
+    readonly ticketKey: string | null;
+    readonly reporter: string | null;
+    readonly reporterName: string | null;
+}
+/** A successful answer, in the exact shape the bridge publishes. */
+export interface QaAskAnswer {
+    readonly chatId: string;
+    readonly answer: string;
+    readonly sources: readonly string[];
+    readonly confidence: "high" | "medium" | "low";
+    /** True when the assistant produced nothing worth publishing. */
+    readonly escalate: boolean;
+    /** Why it escalated — for the bridge's log, never for a client. */
+    readonly reason: string;
+}
+/**
+ * One message of a conversation as an external caller reads it.
+ *
+ * The text is the same flattening the answer itself uses (prose only, with
+ * attachments named), so a caller that keeps asking questions and a caller
+ * that reads back the transcript never see two versions of one message.
+ */
+export interface QaIntegrationMessage {
+    /** Durable position of the message; the cursor for the next read. */
+    readonly seq: number;
+    readonly role: "user" | "assistant";
+    readonly text: string;
+    /** ISO timestamp, when the log recorded one for the event. */
+    readonly at?: string;
+}
+/**
+ * A conversation as the caller that owns it reads it back.
+ *
+ * `sessions:read` exists for exactly this: a bridge that escalated a question,
+ * or that wants to show the specialist what was already said, reads the chat
+ * it started without asking it again. The read is bounded from both ends —
+ * `after` is the caller's own cursor, the newest `limit` messages are the
+ * window — so a long conversation costs one page, not one transcript per call.
+ */
+export interface QaIntegrationTranscript {
+    readonly chatId: string;
+    /** The window, oldest first. */
+    readonly messages: readonly QaIntegrationMessage[];
+    /** Newest seq the caller has now seen; 0 when the chat holds no messages. */
+    readonly lastSeq: number;
+    /** True when older messages exist below the window. */
+    readonly truncated: boolean;
+}
+/** `GET /qa/api/health` payload; the bridge only needs `ok`. */
+export interface QaHealth {
+    readonly ok: boolean;
+    readonly version: string;
+    readonly models: readonly string[];
+    readonly uptimeS: number;
+}
+/**
+ * What one answered turn hands back to the service: the answer text, the
+ * sources that back it and whether the turn was cut short. The runner owns the
+ * session mechanics; nothing about sessions leaks into the wire contract.
+ */
+export interface QaIntegrationTurn {
+    readonly chatId: string;
+    readonly answer: string;
+    readonly sources: readonly QaSourceReference[];
+    /** True when the turn was cancelled or the log recorded an interruption. */
+    readonly interrupted: boolean;
+}
+/** The one host capability the integration service needs, as a port. */
+export interface QaIntegrationRunner {
+    /**
+     * Send one question into a chat and resolve once its turn has settled.
+     *
+     * Implementations must enforce that `userId` may use `chatId` — the service
+     * has already checked the credential, and whoever owns session creation owns
+     * the ownership boundary that goes with it.
+     */
+    run(input: {
+        readonly userId: string;
+        /** The chat to continue, or null for a new conversation. */
+        readonly chatId: string | null;
+        readonly message: string;
+        readonly attachments: readonly QaIntegrationAttachment[];
+        readonly ticketKey: string | null;
+        readonly signal: AbortSignal;
+        /**
+         * Called as soon as the chat exists, before the turn settles. The service
+         * needs the identity of a chat whose answer it may never see: a timed-out
+         * question still has to hand the bridge a chat it can continue.
+         */
+        readonly onChat?: (chatId: string) => void;
+    }): Promise<QaIntegrationTurn>;
+    /**
+     * Read back the messages of one conversation.
+     *
+     * The service has already authenticated the credential and established that
+     * the chat belongs to that account; the implementation reads the log and
+     * projects it, and reports an unreadable log rather than an empty answer.
+     */
+    transcript(input: {
+        readonly chatId: string;
+        /** Exclusive lower bound: only messages after this seq are returned. */
+        readonly after: number;
+        /** Newest messages to return; older ones are reported as truncated. */
+        readonly limit: number;
+    }): Promise<QaIntegrationTranscript>;
+    /** Model ids the deployment can route right now, for the health payload. */
+    models(): Promise<readonly string[]>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/integration/host-runner.d.ts

@@ -0,0 +1,44 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaAccessService } from "../access/service.js";
+import type { QaAccounts } from "../accounts/store.js";
+import type { QaSessionLogReader } from "../admin/session-log.js";
+import type { QaProvenanceHost } from "../provenance/host-store.js";
+import type { QaPolicyAdmission } from "../secure-session.js";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+import type { DocumentsFace } from "@yadsh/dsh-documents";
+import type { QaIntegrationRunner } from "./contract.js";
+/**
+ * The session half of the integration API: open a chat, send one question,
+ * wait for the turn, read the answer.
+ *
+ * It is deliberately not a new turn engine. Opening a chat goes through the
+ * same three steps the browser's `createSession` takes — the deployment
+ * preflight, the per-user workspace, then `secureSession` — because that last
+ * call is what pins the QA tool policy, attaches the QA catalog and records
+ * the chat as attested. A question is admitted with
+ * `sessionController.prompt`, the same call the browser makes; the wait is
+ * `agent.whenIdle()`, which is the harness's own definition of "this turn is
+ * over"; the answer is read back from the durable log rather than from the
+ * live assistant stream, so what the bridge publishes is what was committed.
+ */
+export interface QaIntegrationRunnerOptions {
+    ctx: Context;
+    getConfig(): ResolvedQaSurfaceConfig;
+    /** The accounts store, or undefined while accounts are disabled. */
+    accounts(): QaAccounts | undefined;
+    admission: QaPolicyAdmission;
+    access: QaAccessService;
+    sessionLog: QaSessionLogReader;
+    provenance: QaProvenanceHost;
+    /**
+     * The deployment's document pipeline, resolved per call so a provider that
+     * installs later still counts. Absent on a deployment that has none, where
+     * document attachments are refused with the caller's own fallback signal.
+     */
+    documents(): DocumentsFace | undefined;
+    logger: PluginLogger;
+}
+/** Build the runner for one plugin instance. */
+export declare function createQaIntegrationRunner(options: QaIntegrationRunnerOptions): QaIntegrationRunner;
+//# sourceMappingURL=host-runner.d.ts.map

package/lib/types/integration/http.d.ts

@@ -0,0 +1,79 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { WebServer } from "@deepseek-ai/dsh-host-webserver";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+import { type QaAskRequest } from "./contract.js";
+import type { QaIntegrationService } from "./service.js";
+/** The bridge's own ceiling: five attachments per question. */
+export declare const QA_INTEGRATION_MAX_FILES = 5;
+export interface QaIntegrationRouteOptions {
+    config: ResolvedQaSurfaceConfig;
+    service: QaIntegrationService;
+    logger: PluginLogger;
+}
+/**
+ * Register the integration routes on the host web server.
+ * @param webServer - the route table owner.
+ * @param options - resolved config, the service and the plugin logger.
+ * @returns the disposer removing every route this call registered.
+ */
+export declare function registerQaIntegrationRoutes(webServer: Pick<WebServer, "register">, options: QaIntegrationRouteOptions): () => void;
+/** The page size a caller gets when it does not ask for one. */
+export declare const QA_INTEGRATION_DEFAULT_TRANSCRIPT_LIMIT = 50;
+/**
+ * Parse one `POST /ask` body out of whichever encoding carried it.
+ *
+ * JSON is the primary form. Multipart exists because the bridge sends the
+ * ticket's attachments through it, and images ride a prompt inline in this
+ * harness — so an image-only multipart request is answered like a JSON one. A
+ * non-image attachment has nowhere to go: files reach a prompt as a receipt
+ * minted by the browser upload path, which an external caller has no session
+ * to mint. That request is refused with 415, which is exactly the signal the
+ * bridge's own fallback waits for: it repeats the question without
+ * attachments rather than failing.
+ *
+ * @param body - the raw request body.
+ * @param contentType - the request's content type, parameters included.
+ * @param config - resolved config, for the attachment ceilings.
+ * @returns the normalized request.
+ */
+export declare function parseAskBody(body: Buffer, contentType: string | undefined, config: ResolvedQaSurfaceConfig): QaAskRequest;
+/** One image part of a multipart body, bounded as it was read. */
+interface MultipartFile {
+    readonly filename: string;
+    readonly mediaType: string;
+    readonly bytes: Buffer;
+}
+interface MultipartBody {
+    readonly fields: ReadonlyMap<string, string>;
+    readonly files: readonly MultipartFile[];
+}
+/**
+ * Split a multipart body into its text fields and files.
+ *
+ * Hand-written and deliberately minimal: one request shape (a flat form of
+ * scalar fields and `files` parts), one boundary, no nested multiparts. The
+ * body is already bounded by the caller, so no part can grow without limit.
+ *
+ * @param body - the raw request body.
+ * @param boundary - the boundary parameter of the content type.
+ * @returns text fields and file parts, in the order they appeared.
+ */
+export declare function parseMultipart(body: Buffer, boundary: string): MultipartBody;
+/**
+ * Read the whole request body under a byte ceiling.
+ * @param request - the incoming request.
+ * @param limit - accepted body size in bytes.
+ * @returns the body.
+ */
+export declare function readBody(request: IncomingMessage, limit: number): Promise<Buffer>;
+/**
+ * One refusal, mapped onto its status.
+ *
+ * An unexpected error is answered as `unavailable` rather than leaking a stack
+ * trace: the bridge retries a 5xx, and the deployment's own log holds the
+ * detail.
+ */
+export declare function sendRefusal(response: ServerResponse, error: unknown): void;
+export {};
+//# sourceMappingURL=http.d.ts.map