@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/server/assist-chat.d.ts

@@ -0,0 +1,234 @@
+/**
+ * @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.
+ */
+/**
+ * Aglyn Assist chat proxy (AGL-1860, phase 1 — capability levels 1–2).
+ *
+ * The gate ladder, in order (every step can go red and each has a spec that
+ * forces it): 405 → 401 no token → 403 email-unverified → 400 bad body → 403
+ * not a member → 403 the member's role lacks `ai.use` (AGL-2927; staff pass)
+ * → 404 release flag off (a released-off feature does not exist;
+ * staff bypass) → 403 unscoped/wrong org (AGL-1934 — the request must NAME
+ * the org it meters) → 423 lockdown (platform/org/user + the `ai-assist`
+ * feature kill switch) → 429 rate limit (per uid, then per trusted-hop client
+ * address — AGL-2925) → **the docs answer, if retrieval is
+ * confident** → with no ready provider: **the closest docs pages**, or 501
+ * when retrieval found nothing at all → 403 account age, on a Free workspace
+ * only (AGL-2925) → 429 quota (free: N messages/UTC-day, plus the Free
+ * taste's account, daily-request, refusal and platform rungs — see
+ * `assist-free-taste.ts`; entitled: monthly runaway guard; plus a monthly SPEND ceiling on both
+ * — the plan's own assist band in credits where it has one, otherwise the
+ * operator backstop armed by default at $40/org, removed only by the literal
+ * word `off`; see `assistMonthlyCeilingUsd`) → the model call.
+ *
+ * The spend ceiling is the gate that decides what a paying workspace gets,
+ * because assist actions differ in cost by up to two orders of magnitude —
+ * a question against generating a screen. Quota returned to the client is
+ * `publicAssistQuota`, which reports CREDITS: the reservation's own figures
+ * are our provider bill and do not leave the server.
+ *
+ * ── Retrieval-first (AGL-2486) ─────────────────────────────────────────────
+ *
+ * Two rungs moved when deflection landed, and both moves are load-bearing.
+ *
+ * **The docs answer sits ABOVE the quota**, because it spends nothing. A
+ * question answered out of `apps/docs` takes no reservation and no message
+ * from a free workspace's daily ten — the per-uid rate limiter is its only
+ * bound, and for a map lookup and a string join that is the right one.
+ *
+ * **The key check sits BELOW it**, where it used to be the first thing this
+ * handler did. That is what lets a deployment with no provider key still
+ * answer every question the documentation answers, and say it is
+ * unconfigured only for the ones that genuinely need a model. The cost of the
+ * move is that an unauthenticated caller now gets 401 rather than 501, which
+ * is the better answer to that request anyway.
+ *
+ * What "confident" means, and why a weak match escalates rather than hedges,
+ * is in `docs-deflection.ts`; the measured share of realistic questions it
+ * answers is asserted in `docs-deflection.spec.ts` rather than claimed here.
+ *
+ * ── The edit rung (AGL-2906) ──────────────────────────────────────────────
+ *
+ * On a versioned besigner route, a request that carries the canvas outline
+ * may also PROPOSE edits to it. `assistEditRung` opens the rung only for an
+ * org with `aiGenerative`, `release_ai_generative` on, a caller holding
+ * `ai.generate` and the `ai-generate` switch unlocked. On the rung the model
+ * is offered one strict tool, the edit protocol and the element catalog ride
+ * a third cached block, and the outline rides a volatile one; the tool call
+ * is validated into ops and sent on `done` as `edit`. An instruction there
+ * is not answered from the docs, and no answer is cached. The route still
+ * writes nothing but the exchange and the meters — the panel applies the ops
+ * in the author's editor, on confirm. Below the rung the request is answered
+ * exactly as it would be without a canvas, and the outline is never parsed.
+ *
+ * Capability tiers: entitled orgs (`aiAssist`, Pro+) get docs-grounded
+ * answers PLUS page-context awareness (level 2 — the current route/host is
+ * injected so the assistant can walk the user through the view they are
+ * on). Free orgs get level 1 only: docs-grounded answers and deep links;
+ * any client-sent page context is deliberately dropped.
+ *
+ * Streaming: the route re-emits the provider's stream as simplified
+ * `data: {type:'delta',text}` events, then one `{type:'done', exchangeId,
+ * usage, quota, docs, meter}` after the exchange + meters are recorded —
+ * `meter` being the usage strip's envelope (AGL-2942). The
+ * provider call itself — request shape, SSE parsing, usage and cost, the
+ * error boundary — is `runAiRequest`, the runtime every AI door shares
+ * (AGL-2903); this route owns the prompt, the fence handling, the ladder
+ * and the wire format, and nothing about the wire format changed when the
+ * call moved.
+ *
+ * Thinking is DISABLED explicitly. On a model whose default is adaptive
+ * thinking, an omitted `thinking` runs ADAPTIVE, and `max_tokens` caps
+ * thinking plus answer together, so leaving it off the request would spend
+ * output-priced thinking tokens on "how do I publish a screen", stall the
+ * stream behind a silent think (display defaults to `omitted`, i.e. empty
+ * thinking blocks), and truncate the answer inside the same 1024-token
+ * ceiling. `effort: low` is the documented posture for a scoped chat
+ * workload; both are asserted in the spec so a silent default change fails.
+ *
+ * Prompt caching: the system array is ordered stable → volatile across FIVE
+ * blocks, with breakpoints after the first two.
+ *
+ *   1. static prompt        [breakpoint]  identical everywhere
+ *   2. screen description   [breakpoint]  identical per ROUTE, any tenant
+ *   3. product brand                      the org's name for the product
+ *   4. request facts                      workspace, plan, host, path
+ *   5. docs retrieval                     follows the question
+ *
+ * Caching is a prefix match, so breakpoint 2 covers blocks 1+2 together. The
+ * split between 2 and 3 is the whole design and it is easy to get wrong:
+ * folding the workspace name and plan into block 2 reads more natural and
+ * makes the prefix unique per tenant, so on a shared console every org warms
+ * its own copy and the entry is usually cold when it matters. Derived purely
+ * from the route, block 2 serves every workspace on that screen.
+ *
+ * Block 3 is the same argument applied to the BRAND (AGL-2352). Block 1 no
+ * longer names the product at all — it says a later block will — so a
+ * white-label org's assistant calls itself by that org's name without any
+ * org's bytes reaching a cached prefix. See `assistBrandBlock`.
+ *
+ * Two breakpoints rather than one because a request with no screen block
+ * (free tier, unrecognised route) would otherwise get no cache at all.
+ *
+ * Measured before AGL-2352, which lengthened block 1 by ~130 characters
+ * (the brand interpolations became longer generic nouns, and one sentence
+ * was added) — so the headroom below moved the safe way, not the wrong one:
+ * block 1 was ~933 tokens and blocks 1+2 came to ~1,030–1,190
+ * depending on the screen, against the default model's 1,024-token minimum.
+ * So it caches, with little headroom — and on a shorter screen description
+ * it may not. `usage.cacheReadTokens` on the exchange doc is the only thing
+ * that settles it in production; a prefix under the minimum caches silently
+ * not at all. The minimum moves with the model, so routing `assist.chat` to
+ * another catalog model changes the arithmetic: since AGL-2937 it is written
+ * beside each model as `cacheMinTokens`, and `runtime/ai-prompt-cache.spec.ts`
+ * measures every door's span against it rather than leaving the question to
+ * a comment.
+ *
+ * The history is where this route's uncached money goes — `messages` never
+ * caches, and a client posts its own thread. Since AGL-2937 only the last
+ * `HISTORY_VERBATIM_TURNS` ride word for word; the turns behind them are
+ * folded into one labelled digest with no second model call, which bounds a
+ * scripted caller's history at about 5,200 characters rather than 8,000 and
+ * keeps the gist of the turns that used to be dropped.
+ */
+/**
+ * The balanced tier by default: the margin constraint on this feature is
+ * hard, and a docs-grounded how-to is exactly the shape that tier serves
+ * well. The routing table takes an env override for incident response — the
+ * cost telemetry follows the model id through the catalog's rates, so an
+ * override cannot silently make the per-org cost numbers lie.
+ */
+export declare function assistModel(): string;
+interface AssistHistoryTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+interface AssistRequestBody {
+    orgId: string;
+    question: string;
+    history: AssistHistoryTurn[];
+    context: {
+        route: string;
+        hostId: string;
+        orgSlug: string;
+    } | null;
+    /** A catalog model the asker picked (AGL-2942), or `null` for Auto. */
+    model: string | null;
+    /**
+     * The canvas outline the panel sends from a besigner route (AGL-2906),
+     * unread until the edit rung is decided: `parseAssistEditContext` holds it
+     * to what may enter a prompt, and below the rung it is never parsed at all.
+     */
+    canvas: unknown;
+}
+/**
+ * The turns past the verbatim window, as one labelled digest (AGL-2937).
+ *
+ * Each older turn contributes its opening, which is where a turn says what
+ * it is about, under a per-turn cap and a budget for the whole digest that
+ * is spent newest-first like the verbatim one. An empty string when there
+ * are no older turns, and the caller sends no digest turn at all.
+ *
+ * Written as the USER recounting the thread, because that is what it is: the
+ * client's own record of the conversation, compressed. Reading it as the
+ * assistant's words would invite the model to treat a summary of its earlier
+ * answers as something it had actually said in those words.
+ */
+export declare function assistHistoryDigest(older: readonly AssistHistoryTurn[]): string;
+/** Validate + clamp the request body; null when structurally unusable. */
+export declare function parseAssistBody(payload: unknown): AssistRequestBody | null;
+export type AssistScopeRefusal = 'no-org' | 'wrong-org';
+/**
+ * Whether this request may be METERED against `body.orgId` (AGL-1934).
+ *
+ * Membership is checked above this and answers a different question: *may
+ * this caller reach that org at all*. It cannot catch the reported bug,
+ * because in that bug the caller **is** a member — `useCurrentOrg()` falls
+ * back to a remembered selection and then to the user's FIRST org, so the
+ * workspace picker posted questions attributed and billed to a workspace
+ * nobody opened. A membership check waves that through: every one of the
+ * four cards on the picker passes it.
+ *
+ * So the server asks the second question too: **did the request NAME the org
+ * it wants billed?** The only evidence available is the page the question was
+ * asked from, which the client already sends as `context` — the route path
+ * and, when the page was opened on a workspace subdomain, that subdomain's
+ * slug. This mirrors `urlNamesOrg()` (AGL-1130) on the server side, so the
+ * client gate and the billing boundary agree by construction rather than by
+ * the client being trusted to have one.
+ *
+ * Two refusals, and they are deliberately asymmetric:
+ *
+ *   - `no-org` — the page named no workspace at all (`/`, `/manage/*` off a
+ *     subdomain, `/admin/*` anywhere). There is no correct attribution for a
+ *     question asked from a page with no workspace in scope, so the answer is
+ *     a refusal, not a guess. This is the reported bug, and refusing it here
+ *     is what makes a future client-side regression a VISIBLE failure instead
+ *     of quiet mis-billing.
+ *   - `wrong-org` — the page named a workspace and it is not this one. A
+ *     POSITIVE contradiction only, exactly as AGL-1916 settled it: `slug` is
+ *     absent on plenty of org docs, and an org that cannot state its own slug
+ *     must not have every message refused. Only a slug that actively
+ *     disagrees suppresses.
+ *
+ * `/admin/*` is the platform's own view and names no workspace on ANY
+ * hostname — a staff subdomain session does not rescue it, same as
+ * `urlNamesOrg`'s `section.kind === 'admin'` short-circuit.
+ */
+export declare function assistScopeRefusal(context: AssistRequestBody['context'], orgSlug: string): AssistScopeRefusal | null;
+declare function handler(request: Request): Promise<Response>;
+export declare const dynamic = "force-dynamic";
+export { handler as POST };