@yadsh/dsh-qa-surface 0.9.0 → 0.11.0

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

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

@@ -0,0 +1,120 @@
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaAccounts } from "../accounts/store.js";
+import { type QaServiceTokenScope } from "../accounts/service-token.js";
+import type { QaSourceReference } from "../provenance/types.js";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+import { type QaAskAnswer, type QaAskRequest, type QaHealth, type QaIntegrationRunner, type QaIntegrationTranscript } from "./contract.js";
+/**
+ * The integration API's brain: credential, budget, and one answered turn.
+ *
+ * The service owns everything that must be identical for every transport —
+ * who is allowed to ask, how often, how many at once, what a refusal means and
+ * how an answered turn is shaped into the contract. The HTTP layer owns bytes
+ * and status codes, the runner owns sessions and agents. That split is what
+ * lets the mechanics be tested without a web server, a model or a database.
+ *
+ * Two limits, deliberately different in kind. Concurrency (`maxConcurrent`)
+ * protects the deployment: a bridge that fires a hundred questions must not
+ * open a hundred agent turns. Rate (`requestsPerMinute`) protects the account:
+ * one token cannot spend the deployment's whole budget. Both refuse with 429,
+ * which the bridge already retries.
+ */
+/** The bridge publishes a handful of citations; more is noise in a Jira note. */
+export declare const QA_INTEGRATION_MAX_CITATIONS = 5;
+/**
+ * One citation string per source, in the bridge's own style: the document plus
+ * where in it the evidence sits, so a reader can open the right page.
+ *
+ * @param sources - the turn's evidence, best first.
+ * @returns bounded citation strings.
+ */
+export declare function sourceCitations(sources: readonly QaSourceReference[]): readonly string[];
+/** Who a presented credential turned out to be. */
+export interface QaIntegrationIdentity {
+    readonly tokenId: string;
+    readonly userId: string;
+    readonly scopes: readonly QaServiceTokenScope[];
+}
+export interface QaIntegrationServiceOptions {
+    getConfig(): ResolvedQaSurfaceConfig;
+    /** The accounts store, or undefined while accounts are disabled. */
+    accounts(): QaAccounts | undefined;
+    runner: QaIntegrationRunner;
+    logger: PluginLogger;
+    /** Package version the health payload reports. */
+    version: string;
+    now?(): number;
+}
+export declare class QaIntegrationService {
+    private readonly deps;
+    private readonly now;
+    private readonly startedAt;
+    /** Recent request timestamps per token id, pruned to the rolling minute. */
+    private readonly recent;
+    private inFlight;
+    constructor(deps: QaIntegrationServiceOptions);
+    /** Requests currently inside `ask`; the console shows this as load. */
+    get busy(): number;
+    /**
+     * Resolve a bearer credential to its token, or refuse.
+     *
+     * A malformed, unknown, expired, revoked or disabled-account token is one
+     * answer — 401 — because telling them apart would let an unauthenticated
+     * caller enumerate token ids. A valid token missing the scope is 403: the
+     * caller proved who it is, and the refusal is about rights, not identity.
+     */
+    authenticate(authorization: string | undefined, required: QaServiceTokenScope | null): QaIntegrationIdentity;
+    /**
+     * Answer one question, or refuse before a turn is ever opened.
+     *
+     * @param authorization - the raw `Authorization` header value.
+     * @param request - the parsed body.
+     * @param signal - the request's own lifetime; a dropped connection stops the wait.
+     * @returns the answer the bridge publishes.
+     */
+    ask(authorization: string | undefined, request: QaAskRequest, signal: AbortSignal): Promise<QaAskAnswer>;
+    /**
+     * Read one conversation back for the application that started it.
+     *
+     * This is what `sessions:read` is for. A bridge that escalated a question,
+     * or that has to show a specialist what was already said, reads the chat it
+     * owns instead of asking the same question again — which would spend a turn
+     * and produce a second answer to a question that already has one.
+     *
+     * The ownership rule is the same one `ask` applies when it continues a chat:
+     * the account the token belongs to has to own the conversation. A chat that
+     * does not exist and a chat that belongs to somebody else get one answer, so
+     * an id alone never confirms that another account's conversation exists.
+     *
+     * @param authorization - the raw `Authorization` header value.
+     * @param query - the chat, the caller's cursor and the page size.
+     * @returns the window of messages, with the caller's new cursor.
+     */
+    session(authorization: string | undefined, query: {
+        readonly chatId: string;
+        readonly after: number;
+        readonly limit: number;
+    }): Promise<QaIntegrationTranscript>;
+    /**
+     * Liveness and routing facts for the bridge's own UI.
+     * @param authorization - the raw `Authorization` header value.
+     * @returns the health payload; `ok` is true whenever it is answered at all.
+     */
+    health(authorization: string | undefined): Promise<QaHealth>;
+    /** One refusal shaped as an answer: empty text, escalated, no citations. */
+    private escalated;
+    /** Refuse with `rate-limited` once a token spends its minute's budget. */
+    private assertRate;
+}
+/**
+ * The credential in one `Authorization` value, or null.
+ *
+ * `Bearer` is matched case-insensitively, as HTTP authentication schemes are,
+ * and the token itself is never trimmed: whitespace inside a credential is
+ * part of it, and accepting a padded variant would accept a token the store
+ * never minted.
+ * @param authorization - the raw header, when the caller sent one.
+ * @returns the token, or null.
+ */
+export declare function bearerToken(authorization: string | undefined): string | null;
+//# sourceMappingURL=service.d.ts.map