@acornly/ui 0.1.0 → 0.3.0

package/dist/chat-model.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The in-app chat's model calls: building a Messages API request from the app's context, calling
+ * the model proxy (or the app's relay) tagged as chat, streaming the reply through the app's guard,
+ * and the `read_context` and `offer` tools. Part of the chat's lazy chunk.
+ */
+import { type ContextItem, type ContextSnapshot } from "./chat-protocol.js";
+/** The header the model proxy reads to tell chat's calls from the app's own (design doc, section 10). */
+export declare const FEATURE_HEADER = "Acornly-Feature";
+export declare const FEATURE = "chat";
+export type Block = Record<string, unknown> & {
+    type: string;
+};
+export interface Message {
+    role: "user" | "assistant";
+    content: string | Block[];
+}
+export interface MessagesRequest {
+    model: string;
+    max_tokens: number;
+    system: Block[];
+    messages: Message[];
+    tools?: Record<string, unknown>[];
+    tool_choice?: {
+        type: "auto" | "none";
+    };
+    stream: true;
+}
+/** Sends one request; the response is the Messages API's event stream. */
+export type ChatTransport = (body: MessagesRequest, signal: AbortSignal) => Promise<Response>;
+/** Calls the model proxy Worker straight from the browser, with the person's app token. */
+export declare function proxyTransport(options: {
+    /** The Worker's address, without a trailing slash. */
+    url: string;
+    appId: string;
+    /** The person's app token, fresh for each call. */
+    token: () => string | Promise<string>;
+    fetch?: typeof fetch;
+}): ChatTransport;
+/**
+ * Posts each request to the app's own endpoint, which adds what the browser must not hold, checks
+ * the reply, and calls the proxy with its server token. It must forward `Acornly-Feature`.
+ */
+export declare function relayTransport(options: {
+    endpoint: string;
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    fetch?: typeof fetch;
+}): ChatTransport;
+/** One finished exchange, as later turns resend it. */
+export interface Exchange {
+    question: string;
+    reply: string;
+}
+/** A hand-back the model offered, about an item. */
+export interface Offer {
+    handBack: string;
+    item: string;
+}
+export interface TurnInput {
+    snapshot: ContextSnapshot;
+    /** The conversation's focus, kept from its first message. */
+    focus: readonly string[];
+    /** Items read so far in this conversation, by id. */
+    loaded: ReadonlyMap<string, ContextItem>;
+    /**
+     * The conversation's own copy of its focus items and their ancestors, from when they were last
+     * on screen, so a follow-up stays about them after the app moves on.
+     */
+    kept?: ReadonlyMap<string, ContextItem>;
+    history: readonly Exchange[];
+    question: string;
+    model: string;
+}
+/** The chat's instructions, the app's rules (from the latest snapshot) and its hand-backs. */
+export declare function systemPrompt(snapshot: ContextSnapshot): string;
+/** Tracks what one turn may still carry, so it stays inside the protocol's limits. */
+export declare class Budget {
+    chars: 64000;
+    images: 4;
+    dropped: string[];
+}
+/** An item's content as blocks: its sendable text and images, with a note for what is withheld. */
+export declare function itemBlocks(item: ContextItem, budget: Budget): Promise<Block[]>;
+/** The tree and around as an outline of labels, focus marked: what every turn knows for free. */
+export declare function outline(snapshot: ContextSnapshot, focus: readonly string[], offScreen?: ReadonlySet<string>): string;
+/**
+ * The request for a turn's first round. Ordered for prompt caching: instructions and rules, the
+ * outline, the focus and what was read, then the conversation.
+ */
+/**
+ * The app's latest snapshot with the conversation's kept items added where the app no longer lists
+ * them (ancestors first), and the ids so added. An item the snapshot still lists is the snapshot's,
+ * so its latest `use` applies.
+ */
+export declare function conversationView(snapshot: ContextSnapshot, kept: ReadonlyMap<string, ContextItem> | undefined): {
+    view: ContextSnapshot;
+    offScreen: Set<string>;
+};
+/** The request for a turn's first round, and the turn's budget, which its reads share. */
+export declare function buildRequest(input: TurnInput): Promise<{
+    body: MessagesRequest;
+    dropped: string[];
+    budget: Budget;
+}>;
+/**
+ * Input tokens a request will take, roughly: four characters a token, images at 1,600. A thinking
+ * block's signature is not counted; a redacted block's data is, standing in for the thinking it
+ * holds.
+ */
+export declare function estimateTokens(body: MessagesRequest): number;
+/** A failed call, with the proxy's error code when it gave one (`budget_exhausted`, `feature_cap`). */
+export declare class ChatCallError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+interface Streamed {
+    content: Block[];
+    stopReason: string | null;
+    /** The app's relay ended the stream as refused (`{"type":"acornly_refused"}`). */
+    refused: boolean;
+}
+/** The event an app's relay sends to say its guard flagged the reply (design doc, section 10). */
+export declare const REFUSED_EVENT = "acornly_refused";
+/** Reads a Messages API event stream, passing text as it arrives. */
+export declare function readStream(response: Response, onText: (text: string) => void): Promise<Streamed>;
+/** Splits streamed text into finished sentences, keeping the unfinished rest. */
+export declare function takeSentences(buffer: string): {
+    sentences: string[];
+    rest: string;
+};
+/** True when a sentence breaks the app's rules: the reply is then withheld. */
+export type ReplyGuard = (sentence: string, replySoFar: string) => boolean | Promise<boolean>;
+export interface TurnHooks {
+    transport: ChatTransport;
+    /** The app's `load`, for `read_context`. */
+    load: (id: string) => Promise<ContextItem | null>;
+    guard?: ReplyGuard | undefined;
+    /** Each checked piece of the reply, as it may be shown. */
+    onText(text: string): void;
+    /** An item was read, for "Read: …" under the reply. */
+    onRead?(item: ContextItem): void;
+    signal: AbortSignal;
+}
+export interface TurnResult {
+    reply: string;
+    /** The guard, or the app's relay, flagged the reply: it was replaced by a refusal. */
+    refused: boolean;
+    offers: Offer[];
+    read: ContextItem[];
+    dropped: string[];
+}
+/**
+ * Runs one turn: up to three model rounds, reading items the model asks for between them, with
+ * every finished sentence checked by the guard before it is shown; with no guard, the text is shown
+ * as it streams.
+ */
+export declare function runTurn(input: TurnInput, hooks: TurnHooks): Promise<TurnResult>;
+/**
+ * Drafts the one- or two-line takeaway "Keep" offers, from one exchange, under the latest rules:
+ * their `never` in its instructions, and the whole draft through the guard. A draft the guard or the
+ * app's relay flags comes back empty, for the person to write their own.
+ */
+export declare function draftTakeaway(exchange: Exchange, snapshot: ContextSnapshot, model: string, transport: ChatTransport, signal: AbortSignal, guard?: ReplyGuard): Promise<string>;
+export {};
+//# sourceMappingURL=chat-model.d.ts.map

package/dist/chat-model.d.ts.map

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