@burdenoff/fe-libs 2026.924.1 → 2026.924.3

package/dist/shared/assistant/autoRouting.d.ts

@@ -0,0 +1,197 @@
+import { AssistantModeConfig, ConversationRouting } from './conversation';
+import { AssistantMode } from './types';
+/** The read-only mode Auto routes questions, explanations and navigation to. */
+export declare const AUTO_READ_MODE = "assistant";
+/**
+ * The write mode Auto routes requests for a change to — the only id whose
+ * sandbox proposes each change and waits for approval before saving it.
+ *
+ * ★ Deliberately not `vibe-plugins` or any product-declared builder. Those make
+ * artifacts, not records, and are chosen on purpose; Auto does not guess them.
+ */
+export declare const AUTO_WRITE_MODE = "api-calls";
+/** What a message asks for: a change to be made, or anything else. */
+export type AssistantIntent = "act" | "read";
+/**
+ * Auto is offered only where there is something to route between: the product
+ * offers BOTH the read mode and the write mode to this person. `modes` must be
+ * the role-filtered list the selector shows, not the product's full list.
+ */
+export declare function isAutoRoutingOffered(modes: readonly Pick<AssistantModeConfig, "id">[]): boolean;
+/**
+ * Does this message ask for a change to be made?
+ *
+ * Conservative by design: "act" only when a clause asks for a change — opens
+ * with a verb of change ("create a tomato crop in Field 3"), asks the assistant
+ * to ("can you add a chart", "would you mind deleting the parser", "I'd like
+ * the sink renamed"), or confirms ("go ahead"). A question about how to change
+ * something ("how do I create a crop"), a request to see or go somewhere ("open
+ * the crop page"), a statement ("import errors keep showing up"), and anything
+ * the rules do not recognise are "read".
+ *
+ * ★ Any sentence or clause that asks for a change makes the message a request:
+ * "I have a CSV of attendance. Build a dashboard from it." is one, and so is
+ * "show me the widgets and remove the empty one". A question stays one unless
+ * its last clause asks the assistant to act ("why is this failing, can you fix
+ * it?").
+ *
+ * ★★ One message at a time, by design. A follow-up with nothing to go on — a
+ * bare "yes", "same for field 4" — reads as "read", which in an open Auto
+ * conversation means CONTINUE in the mode it is in: it inherits the
+ * conversation's route (`resolveAutoRoute`), which is what it refers to.
+ *
+ * ★★ English only. A request in another language routes to Ask and is answered
+ * read-only — the behaviour before Auto existed, never a wrong write.
+ */
+export declare function classifyAssistantIntent(text: string): AssistantIntent;
+/** The part of a conversation routing reads. */
+export interface AutoRouteConversation {
+    mode: AssistantMode;
+    routedBy?: ConversationRouting;
+    /** Any message, or a live backend session: something a new mode would lose. */
+    hasHistory: boolean;
+}
+/**
+ * What an Auto send does with the conversation it lands in.
+ *
+ * - `new`: start a new conversation in `mode`. There is none, or the one open
+ *   is a conversation whose mode the person chose — never converted.
+ * - `adopt`: the open conversation is empty; give it `mode` and mark it Auto's.
+ * - `continue`: send into the open Auto conversation as it stands.
+ * - `escalate`: move the open Auto conversation from Ask to the write mode, in
+ *   place, with a fresh backend session.
+ */
+export type AutoRoute = {
+    action: "new";
+    mode: AssistantMode;
+} | {
+    action: "adopt";
+    mode: AssistantMode;
+} | {
+    action: "continue";
+    mode: AssistantMode;
+} | {
+    action: "escalate";
+    mode: AssistantMode;
+};
+export interface AutoRouteInput {
+    intent: AssistantIntent;
+    /**
+     * The turn was spoken. A spoken turn is never routed to the write mode:
+     * voice is refused in any mode that can change data
+     * (`writeModeSendRefusal`), so routing it there would turn a question into a
+     * refusal.
+     */
+    dictated: boolean;
+    conversation: AutoRouteConversation | null;
+}
+export declare function resolveAutoRoute({ intent, dictated, conversation, }: AutoRouteInput): AutoRoute;
+/** Where an escalated conversation came from. */
+export interface EscalationOrigin {
+    mode: AssistantMode;
+    backendSessionId: string | null;
+}
+/**
+ * After an escalated turn ends, however it ended: the state to put back, or
+ * null to keep the escalation.
+ *
+ * ★★ The escalation is committed before the write mode's sandbox is reached —
+ * it has to be, since the send it makes is what reaches it. If that turn never
+ * got a session in the write mode (no sandbox, quota, a timeout, the person
+ * stopping it), nothing there knows this conversation, and leaving it moved
+ * would pin a conversation to the write mode for good ("never moves back"). So
+ * it goes back to the mode it came from; the next request escalates again.
+ *
+ * ★★ Its old session comes back only while that mode's sandbox is still ours
+ * (`sandboxAlive`). Provisioning the write mode can STOP it to free the
+ * workspace's slot, and a session id outlives its sandbox: restored, it would
+ * suppress the carry-over (a conversation with a session gets none) while the
+ * next turn discovers the session is gone and starts an empty one. Without it,
+ * that turn starts a session AND hands it the person's earlier messages.
+ *
+ * Once the write mode HAS a session, it holds this turn, and the escalation
+ * stands whatever the turn's outcome. A conversation someone has since moved
+ * (a pick, a different route) is left alone.
+ */
+export declare function escalationToUndo(origin: EscalationOrigin | null, escalatedTo: AssistantMode, after: {
+    mode: AssistantMode;
+    routedBy?: ConversationRouting;
+    backendSessionId?: string | null;
+} | undefined, sandboxAlive: (mode: AssistantMode) => boolean): EscalationOrigin | null;
+/** At most this many of the person's earlier messages are carried over. */
+export declare const AUTO_CARRY_OVER_MAX_MESSAGES = 6;
+/** Each carried message is cut to this many characters. */
+export declare const AUTO_CARRY_OVER_MAX_CHARS_PER_MESSAGE = 500;
+/** The carried messages together stay within this many characters. */
+export declare const AUTO_CARRY_OVER_MAX_CHARS = 3000;
+/**
+ * The preamble that hands a NEW backend session the person's earlier messages,
+ * or "" when there are none.
+ *
+ * ★★ The person's messages only — never the assistant's replies. Those carry
+ * text read out of business data, and handing them to the write mode as
+ * conversation context would let whatever a record says reach the one agent
+ * that can change records, dressed as something the person said. What the
+ * person wrote is what they asked for, which is all the new session needs to
+ * resolve "add it there too".
+ *
+ * ★ Trailing copies of `content` are dropped: Retry sends the same text again,
+ * and the failed attempt is already in the history.
+ */
+export declare function buildAutoCarryOver(priorUserMessages: readonly string[], content: string): string;
+/** The part of a conversation the carry-over reads. */
+export interface AutoCarryOverConversation {
+    routedBy?: ConversationRouting;
+    messages: readonly {
+        role: string;
+        content: string;
+    }[];
+}
+/**
+ * The carry-over for a turn in `conversation`, or "".
+ *
+ * Only for an Auto conversation whose turn is going to a NEW backend session
+ * while it already has history — the escalation, the recovery after its
+ * sandbox was lost, and a session the backend reaped overnight.
+ *
+ * ★★ `sessionIsNew` comes from the runtime, AFTER it validated the session,
+ * never from the stored id: a reaped session's id is still stored when the
+ * send starts, and is only found dead and replaced while the runtime prepares
+ * the turn. Reading the stored id gave that fresh session no history, so "add
+ * it there too" arrived with nothing to refer to.
+ *
+ * The turn's own message may already be in `conversation`; it is dropped as a
+ * trailing copy of `content` (`buildAutoCarryOver`). A conversation the person
+ * routed by hand behaves as it always has.
+ */
+export declare function autoCarryOverFor(conversation: AutoCarryOverConversation | undefined, content: string, sessionIsNew: boolean): string;
+export interface AutoSuggestion {
+    text: string;
+    /**
+     * Which list it came from. Clicking it routes by THIS, not by classifying its
+     * text: a product's suggestions are translated, and the classifier reads only
+     * English, so a translated write suggestion would otherwise land in Ask.
+     */
+    intent: AssistantIntent;
+}
+/**
+ * The chips an empty Auto conversation offers: the read mode's and the write
+ * mode's suggestions, alternating, so the person sees both kinds of thing Auto
+ * can do. Duplicates are shown once, as the read mode's.
+ */
+export declare function autoSuggestions(read: readonly string[], write: readonly string[], limit?: number): AutoSuggestion[];
+/**
+ * Whether Auto is selected, restored from a persisted store.
+ *
+ * A stored answer wins. A store saved before Auto existed has none, so it is
+ * derived from what was on screen:
+ *
+ * - an open conversation with history keeps the mode it was having — the
+ *   person's next message continues it rather than being moved elsewhere;
+ * - otherwise (none open, or an empty one) the selected MODE decides. The
+ *   default Ask, or nothing recorded, is a mode nobody chose, so Auto. Any
+ *   other mode was picked and stays: in a product that does not offer Auto,
+ *   Auto-by-default turned a picked builder into Ask on the next New.
+ */
+export declare function restoreAutoRouting(persisted: unknown): boolean;
+//# sourceMappingURL=autoRouting.d.ts.map

package/dist/shared/assistant/autoRouting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoRouting.d.ts","sourceRoot":"","sources":["../../../src/shared/assistant/autoRouting.ts"],"names":[],"mappings":"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"}