@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/docs-deflection.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AssistDocsSection } from './docs-index.generated';
+import { type ScoredSection } from './docs-retrieval';
+/** Why a question was not answered from the docs. `null` reason = answered. */
+export type DeflectionRefusal = 'follow-up' | 'too-short' | 'generative' | 'diagnostic' | 'low-score' | 'ambiguous' | 'low-coverage' | 'thin-section';
+export interface DeflectionVerdict {
+    /** True when the docs answer this without a model call. */
+    answered: boolean;
+    /** Set when `answered` is false — which gate refused. */
+    refusal: DeflectionRefusal | null;
+    /** The composed answer; `''` unless `answered`. */
+    answer: string;
+    /** Sections quoted in the answer; `[]` unless `answered`. */
+    quoted: readonly AssistDocsSection[];
+    /** The winning page's path; `''` when nothing won. */
+    page: string;
+    /** Top section's retrieval score. 0 when nothing was retrieved. */
+    topScore: number;
+    /** Winning page's score over the best rival page's. 0 when unscored. */
+    pageMargin: number;
+    /** IDF-weighted share of the question the winning page carries. */
+    coverage: number;
+}
+/** The docs-site URL for one section. */
+export declare function sectionUrl(section: AssistDocsSection): string;
+/** `Title — Heading`, or just the title on a page intro. */
+export declare function sectionLabel(section: AssistDocsSection): string;
+/**
+ * Trim verbatim text to `limit` characters on a sentence boundary, so a quote
+ * never ends mid-clause. Returns the text unchanged when it already fits.
+ *
+ * A truncated quote is still verbatim — it is a PREFIX of the section, which
+ * is what the spec's substring check asserts. Cutting on a boundary matters
+ * for a different reason: a sentence stopped halfway reads as a broken
+ * feature, and the user cannot tell whether the missing half contradicted the
+ * visible one.
+ */
+export declare function trimToSentence(text: string, limit: number): string;
+/** Question intent, ahead of any retrieval work. */
+export declare function questionIsAnswerableFromDocs(question: string): DeflectionRefusal | null;
+/**
+ * Whether a question can be read WITHOUT the conversation it was asked in.
+ *
+ * Only consulted for a turn that has history — see
+ * {@link CONTEXT_DEPENDENT_PATTERNS} for why the test errs towards "no", and
+ * the class docstring for why the gate is no longer simply "did anything
+ * precede this".
+ *
+ * Purely lexical, and that is a real limit worth naming: "how do I do the
+ * same for a blog post" is caught by `the same`, while "how do I change the
+ * colour" after a paragraph about buttons is not — nothing in those words
+ * says which colour. What saves that case is not this function but the raised
+ * evidence bar behind it, which such a question does not clear. The two gates
+ * are one argument in two halves: this one reads the question, that one reads
+ * the retrieval, and a follow-up must pass both.
+ */
+export declare function questionStandsAlone(question: string): boolean;
+/**
+ * Decide whether the retrieved sections answer the question on their own, and
+ * compose the answer when they do.
+ *
+ * `hasHistory` is passed rather than derived because the caller holds the
+ * clamped history and this module must not grow an opinion about how history
+ * is budgeted. It is not a hard gate any more (AGL-2486): a turn with history
+ * must additionally stand on its own words and clear the raised `FOLLOW_UP_*`
+ * bar, and escalates when it does not.
+ */
+export declare function deflectToDocs(question: string, scored: readonly ScoredSection[], hasHistory: boolean): DeflectionVerdict;
+/**
+ * The deflected answer: template + verbatim docs + real links, and nothing
+ * else. Kept exported so the spec can assert the reconstruction property
+ * against it directly rather than through the route.
+ *
+ * ⚠️ COMPOSED FOR A SURFACE THAT DOES NOT RENDER MARKDOWN. The Assist panel
+ * says so in its own docstring — `renderAssistText` turns `[label](url)` and
+ * bare URLs into links and renders everything else literally, under
+ * `whiteSpace: 'pre-wrap'`. That is a deliberate phase-1 decision, not a gap.
+ *
+ * This template shipped once with the heading wrapped in `**…**`, and the * besigner drawer duly showed `**Drag-and-drop hierarchy — Moving an element
+ * without dragging**`, asterisks and all. The lesson is not "escape the
+ * asterisks" — it is that the composer has to know what renders it.
+ *
+ * So the heading is a bare `[label](url)` on its own line — a LINK, which is
+ * the one markup the panel speaks, and which is why the title in the * screenshot was correctly clickable even while the asterisks around it were
+ * not. Everything else is carried by NEWLINES, which `pre-wrap` renders,
+ * rather than by markup, which it does not.
+ *
+ * The link has to live in the TEXT, and that is still true now that the
+ * `docs` array on the `done` event IS rendered (AGL-2486, `AssistSources`).
+ * It was tempting to treat that array as the structural home for the citation
+ * even when nothing rendered it; it is still the wrong home, for a different
+ * reason. `docs` carries every section RETRIEVED, whereas this template
+ * quotes only the sections it actually used — so the array is a superset, and
+ * a citation moved there would credit pages this answer never drew a word
+ * from. `AssistSources` drops any url already linked in the text, which means
+ * a deflected answer renders exactly as it does below and gains no duplicate
+ * list underneath.
+ *
+ * Three specs in `docs-deflection.spec.ts` hold the line — no emphasis
+ * markers, no heading markers, and a link still present.
+ *
+ * The closing line is not decoration. A user who reads this and finds it did
+ * not answer them needs to know that asking again in different words reaches
+ * something else — otherwise the cheap path looks like the assistant simply
+ * being worse, and the next thing they do is stop using it.
+ */
+export declare function composeDocsAnswer(sections: readonly AssistDocsSection[]): string;
+/**
+ * The graceful degrade: the closest pages we found, and an honest sentence
+ * saying why that is all there is (AGL-2486).
+ *
+ * ## Why this exists
+ *
+ * A deployment with no AI provider key — which includes every self-hosted
+ * one on the day it comes up, and Aglyn's own production today — can answer
+ * only what retrieval is confident about. A bare 501 for everything else
+ * reaches the panel as "Assist is not configured on this deployment" — and it
+ * can arrive on the SECOND question of a thread whose first question was just
+ * answered in full. A capability refusal that lands after a working answer
+ * reads as a fault, not a limit.
+ *
+ * The self-host charter says every Aglyn-operated dependency must be
+ * configurable AND degrade cleanly. "Degrades cleanly" cannot mean "answers
+ * one question per thread and then refuses" — a keyless deployment still has
+ * the entire documentation corpus and a retrieval index over it, so the floor
+ * is the best pages we found, not nothing.
+ *
+ * ## What it may and may not say
+ *
+ * The no-fabrication rule applies here exactly as it does to a deflected
+ * answer, and is tighter in one respect: these pages did NOT clear the
+ * confidence bar, so this text must not claim they answer the question. It
+ * says they are the closest, which is true by construction — they are the
+ * top of the retrieval ranking — and every word around them is a fixed
+ * template plus a real section label and URL.
+ *
+ * It also must not name an env var. A user who wanted to read `501` would
+ * have opened the network tab; the operator-facing detail stays in the API
+ * error body, where an operator looks. This is the plain-English half.
+ */
+export declare function composeDocsLinksAnswer(sections: readonly AssistDocsSection[]): string;