@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/server/assist-view-context.d.ts

@@ -0,0 +1,343 @@
+/**
+ * @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 AssistEditDocumentKind } from '../model/assist-edit';
+/**
+ * Aglyn Assist level 2 — the GUIDE capability (AGL-1988, under AGL-1860).
+ *
+ * Level 1 answers from the docs. Level 2 answers about **the thing in front
+ * of the user**: the console screen they are standing on. This module is the
+ * whole of that knowledge, and three decisions shape it.
+ *
+ * ## 1. A curated descriptor, not a state dump
+ *
+ * The tempting design is to serialise the page — props, records, the loaded
+ * list — into the prompt. That buys worse answers at higher cost: the model
+ * gets rows when what it needs is *what this screen is for*, and every extra
+ * token is billed per turn against a hard margin constraint.
+ *
+ * So the view block is assembled from a STATIC, in-repo table keyed by route
+ * pattern, plus a fixed handful of scalars about the current org. Nothing is
+ * read out of the customer's data to build it. That is also why the privacy
+ * guard is cheap to state and cheap to prove: there is no path from a
+ * Firestore document to this prompt except the two fields `safeOrgFacts`
+ * names, and no path from client input except three sanitised strings.
+ *
+ * ## 2. One answer for both ends of the ICP range
+ *
+ * the requirement is a single feature that is "easy for someone who
+ * doesn't know code and even easier for someone who does". Two modes would
+ * be the obvious build and the wrong one — it makes the beginner choose a
+ * label for themselves before they have a question, and it makes the
+ * developer opt in to being taken seriously.
+ *
+ * Progressive disclosure instead: every view carries a `plain` layer (what
+ * you can do here, in words a first-business owner reads) and a `technical`
+ * layer (the route template, the ids in the path, the API or field names
+ * behind it). The model leads with plain and appends the technical layer
+ * under a fixed `Under the hood:` marker, which the panel renders collapsed.
+ * Same answer, two depths, one message.
+ *
+ * ## 3. Actions are PROPOSALS, and a proposal cannot write
+ *
+ * "Automate current view" is level 2's edge and needs a hard boundary — the
+ * AGL-1860 ladder puts acting in the besigner at level 3, after launch. The
+ * boundary here is structural rather than behavioural, because a rule the
+ * model is asked to follow is not a boundary:
+ *
+ *   - An action descriptor has no field that could carry a write. There is no
+ *     method, no body, no endpoint — only a `route` template and the NAMES of
+ *     params. `assertInertActions()` proves that over the live table.
+ *   - The model never supplies a destination. It may name an `id` from the
+ *     closed set attached to the view it is already on, and supply values for
+ *     params that view declared. `resolveAssistProposal` builds the href from
+ *     the registry; an unknown id, a foreign id, or an undeclared param is
+ *     dropped rather than honoured.
+ *   - Confirming NAVIGATES. The destination form's own submit button, with
+ *     its own permission checks, stays the only thing that writes.
+ *
+ * `prefill` is deliberately `false` across the table today: no console page
+ * reads `assist_*` search params yet, and a card that claims "I filled that
+ * in for you" over a form that came up empty is worse than one that names the
+ * values to type. The plumbing is here so switching a page on is a one-line
+ * change, and `PREFILL_READY_ROUTES` is the allowlist that has to grow first.
+ *
+ * ## 4. The one action that edits, and where it opens (AGL-2906)
+ *
+ * Level 3 makes a single exception, on the besigner only: the `edit` action.
+ * The server still writes nothing. The model proposes typed canvas operations
+ * through a strict tool, the server validates them against the canvas the
+ * request described, and the panel shows the change and applies it in the
+ * author's own editor when they press Apply — an unsaved change, undone by
+ * the editor's own undo. The rung is closed unless the org carries
+ * `aiGenerative`, `release_ai_generative` is on for it and the caller holds
+ * `ai.generate`. `offeredActions` hands an edit action only to a request that
+ * cleared the rung, and `assertInertActions` fails any edit action offered
+ * without it, or one that carries a destination the way a navigation does.
+ */
+/**
+ * One thing the assistant may PROPOSE from a given view, by navigating.
+ *
+ * Note what this interface cannot express. There is no `method`, no `body`,
+ * no `endpoint`, no `submit` — a descriptor is a signpost, and the type is
+ * the first line of the write boundary. Adding any of those fields would
+ * break `assertInertActions()`, which is the point of writing it down.
+ */
+export interface AssistNavigateAction {
+    /** `navigate`, or absent. */
+    kind?: 'navigate';
+    /** Stable id; the ONLY thing the model gets to choose from. */
+    id: string;
+    /** Beginner-facing label on the confirm card. */
+    label: string;
+    /** What the user will be looking at once they confirm. */
+    outcome: string;
+    /**
+     * Server-owned destination template (`/[orgSlug]/…`). Built here, never
+     * supplied by the model — so the worst a bad completion can do is send the
+     * user to a different page in their own console.
+     */
+    route: string;
+    /** Param names the model may supply values for. Anything else is dropped. */
+    params: readonly string[];
+    /**
+     * Whether the destination actually reads `assist_*` search params. False
+     * everywhere today — see the module header. When false the values are
+     * shown on the card as "use these" rather than pushed into the URL.
+     */
+    prefill: boolean;
+}
+/**
+ * The besigner's edit action (AGL-2906). Its proposal is typed canvas
+ * operations the panel applies on confirm — never a destination and never a
+ * server write — so it carries none of a navigation's `route`, `params` or
+ * `prefill`, and `assertInertActions` fails one that does.
+ */
+export interface AssistEditAction {
+    kind: 'edit';
+    /** Stable id; the ONLY thing the model gets to choose from. */
+    id: string;
+    /** Beginner-facing label on the confirm button. */
+    label: string;
+    /** What changes once the author confirms. */
+    outcome: string;
+    /** The besigner documents the action opens on. */
+    documents: readonly AssistEditDocumentKind[];
+}
+export type AssistViewAction = AssistNavigateAction | AssistEditAction;
+/** What a request cleared, which decides the actions a view offers it. */
+export interface AssistActionRung {
+    /**
+     * The edit rung: `aiGenerative`, `release_ai_generative` and `ai.generate`,
+     * on a versioned besigner route, with the canvas described.
+     */
+    edit: boolean;
+}
+/** A console screen, described for the assistant rather than for a router. */
+export interface AssistView {
+    /** Registry key; also the analytics/debug handle. */
+    key: string;
+    /** Route matcher. First match wins, so the table is ordered specific-first. */
+    match: RegExp;
+    /** One line: what this screen is. */
+    screen: string;
+    /** The beginner layer — what a person can do here, in plain words. */
+    plain: readonly string[];
+    /** The developer layer — route template, path ids, API surface. */
+    technical: readonly string[];
+    /** Proposals available from this view: navigations, and on the besigner the edit action. */
+    actions: readonly AssistViewAction[];
+}
+/**
+ * Destinations verified to read `assist_*` search params. EMPTY on purpose:
+ * `assertInertActions()` fails any action with `prefill: true` whose route is
+ * not listed, so turning prefill on requires wiring the page first rather
+ * than remembering to.
+ */
+export declare const PREFILL_READY_ROUTES: readonly string[];
+/** Query-param prefix for proposed values. Namespaced so a page opting in
+ * can never confuse an assistant suggestion with its own state. */
+export declare const ASSIST_PREFILL_PREFIX = "assist_";
+/**
+ * The registry. Ordered specific-first — `describeView` takes the first
+ * match, so a host sub-page must precede the host dashboard, and every
+ * host route must precede the bare `/[orgSlug]` home.
+ *
+ * Content rule: every line here has to be TRUE of the shipped console. These
+ * strings are asserted to the model as fact and it will repeat them, so a
+ * guessed button label becomes a confidently wrong instruction. Where the
+ * exact affordance is uncertain the line names the SCREEN and its purpose
+ * and lets docs retrieval supply the steps — a vaguer sentence that is right
+ * beats a specific one that is invented.
+ */
+export declare const ASSIST_VIEWS: readonly AssistView[];
+/** The view the user is standing on, or null where the route is unknown. */
+export declare function describeView(route: string): AssistView | null;
+/**
+ * The actions a view offers a request: every navigation, and the edit action
+ * only to a request that cleared the edit rung.
+ */
+export declare function offeredActions(view: AssistView | null, rung: AssistActionRung): readonly AssistViewAction[];
+/**
+ * Client-supplied strings that end up inside a SYSTEM block have to be
+ * treated as hostile, not merely untidy. `route` is whatever the panel says
+ * the pathname is, and an attacker who can shape it can otherwise write
+ * newlines, backticks and prose into the model's instructions — including a
+ * forged action fence, which is the one construct in this feature the model
+ * is told to treat as meaningful.
+ *
+ * So the allowed alphabet is exactly what a console path is made of. Anything
+ * else is dropped rather than escaped: there is no legitimate route that
+ * needs a backtick, and a sanitiser that tries to preserve intent is a
+ * sanitiser with a bypass in it.
+ */
+export declare function sanitiseRoute(route: string): string;
+/**
+ * Same reasoning as `sanitiseRoute`, for a Firestore-shaped document id.
+ *
+ * Rejects rather than truncates, which is the difference between refusing an
+ * id and quietly pointing at a different one: `slice(0, 64)` on an over-long
+ * value yields a well-formed id for some OTHER document, and this function's
+ * output is substituted straight into a destination path.
+ */
+export declare function sanitiseId(value: string): string;
+/**
+ * The ONLY fields of the org document that may enter a prompt.
+ *
+ * An allowlist rather than a denylist, and stated as a literal rather than
+ * derived, because the failure mode is silent: the org doc grows a field one
+ * day — a Stripe customer id, an owner's email, a support note — and a
+ * spread would carry it into a third party's API without anything failing.
+ * Both fields named here are already on screen for any member who can open
+ * the panel, so nothing is disclosed that the asker could not read anyway.
+ *
+ * The plan is the one the workspace resolves to, as the console's badges name
+ * it (AGL-3034): a canceled subscription's stored plan grants nothing, and a
+ * staff comp grants a plan the stored field may not name.
+ */
+export declare function safeOrgFacts(org: Record<string, unknown>): {
+    name: string;
+    plan: string;
+};
+/**
+ * The per-VIEW system block — the screen description, and nothing about who
+ * is looking at it.
+ *
+ * The split from `viewFactsBlock` is the whole caching design, and it was
+ * not the first shape this took. Folding the workspace name, plan, slug and
+ * host id in here reads more natural and quietly destroys the cache: a
+ * prefix carrying the tenant's name is unique to that tenant, so on a
+ * multi-tenant console every org warms its own copy and the entry is usually
+ * cold when it matters. Derived purely from the route, the same block serves
+ * every workspace asking anything on that screen — which on a shared console
+ * is the difference between a cache that pays and one that mostly writes.
+ *
+ * So this block is a pure function of the registry and the rung — two
+ * variants a route at most, neither carrying a tenant byte — and everything
+ * that varies per request lives after the breakpoint.
+ */
+export declare function viewScreenBlock(view: AssistView | null, rung?: AssistActionRung): string;
+/**
+ * The per-REQUEST facts. Everything here varies by workspace or by page, so
+ * it sits after the last cache breakpoint where it invalidates nothing.
+ *
+ * Only `safeOrgFacts`' two allowlisted fields and the three sanitised client
+ * strings ever reach this — see the module header.
+ */
+export declare function viewFactsBlock(facts: {
+    route: string;
+    hostId: string;
+    orgSlug: string;
+    name: string;
+    plan: string;
+}): string;
+/** Fence the model wraps a proposal in. Kept out of the visible answer. */
+export declare const ASSIST_ACTION_FENCE = "```aglyn:action";
+/**
+ * How much of `raw` is safe to stream to the user.
+ *
+ * The proposal fence must never reach the panel as text — a user watching
+ * raw JSON appear mid-answer reads it as the assistant breaking. Trimming
+ * only at the end is not enough either, because by then the tokens have
+ * already been emitted as deltas.
+ *
+ * So the visible prefix is recomputed on every delta, and the tail is held
+ * back only while it could still turn out to be the start of a fence. That
+ * matters for latency: holding a fixed window would delay every answer by
+ * the fence's length, whereas this holds nothing back unless the text
+ * genuinely ends in a backtick run.
+ */
+export declare function visibleAssistText(raw: string): string;
+/**
+ * The visible answer once the stream has ENDED — no holdback.
+ *
+ * `visibleAssistText` withholds a tail that might still become a fence,
+ * which is right mid-stream and wrong at the end: an answer that genuinely
+ * closes on a code fence would otherwise lose its last three characters
+ * permanently, both on screen and in the stored exchange. Once there are no
+ * more deltas the ambiguity is resolved, so the only cut left is a real one.
+ */
+export declare function finalAssistText(raw: string): string;
+/** The raw JSON body between the fences, if the model emitted one. */
+export declare function extractAssistAction(raw: string): string | null;
+/** A proposal that survived validation — inert, and safe to show. */
+export interface AssistProposal {
+    id: string;
+    label: string;
+    outcome: string;
+    /** Fully-resolved console path. Server-built; the model never sees it. */
+    href: string;
+    /** Values the model suggested, in the order the action declared them. */
+    values: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+    /** Whether `href` carries the values, or the card must ask the user to type them. */
+    prefill: boolean;
+}
+/**
+ * Turn a model-emitted action block into a proposal, or nothing.
+ *
+ * Everything here is a narrowing. The id must be one the CURRENT view
+ * offers as a navigation — not merely a real id somewhere in the registry,
+ * because "propose the billing page from the besigner" is exactly the kind
+ * of plausible wandering that makes an assistant feel unsafe, and not the
+ * edit action either, which is never a destination. Param names must be ones
+ * that action declared. The href is composed from the registry template and
+ * the caller's own server-resolved slug and host, so a completion cannot
+ * steer the user anywhere the registry does not already point.
+ *
+ * Anything unexpected returns null. A dropped proposal costs the user a
+ * button; an honoured bad one costs them trust.
+ */
+export declare function resolveAssistProposal(rawBlock: string | null, view: AssistView | null, scope: {
+    orgSlug: string;
+    hostId: string;
+}): AssistProposal | null;
+/**
+ * The write boundary, asserted over the live table rather than described in
+ * a comment. Called by the spec; exported so the check travels with the data
+ * it checks rather than living in a test file someone can delete.
+ *
+ * Every action is inert UNLESS it is an edit action and the request cleared
+ * the edit rung: a navigation carries no write-capable field and no ops, an
+ * edit action carries no destination, and an edit action offered to a
+ * request below the rung is a violation. `offer` is the function the doors
+ * decide with; a spec passes a broken one to show this check can fail.
+ *
+ * Returns the list of violations so a failure names the offending action.
+ */
+export declare function assertInertActions(views?: readonly AssistView[], rung?: AssistActionRung, offer?: typeof offeredActions): string[];