@hachej/boring-ui-kit 0.4.22 → 0.4.24

package/README.md

@@ -142,6 +142,10 @@ A submit the host refused before admission (status 402 `submission-refused`, for
 
 `test/packages/ui-native-chat.test.mjs` uses a real native Harness and a fictional local streaming provider.
 
+### Chat view rules
+
+`@hachej/boring-ui-kit/chat-view` holds the chat's presentation rules once, so the registry items (`pi-chat`, `pi-ambient`) keep only their markup. It imports Pi types only: no React, no files or agent code. `derive(view, options)` turns a native `ConversationView` into display rows (cards, activity steps, questions, approvals, artifacts) and the run state; its card content type is generic, and the items fix it to React nodes. `waits(part)`, `waitingPart(rows)` and `waitingForAnswer(rows)` are the one rule for "waiting for the person": a committed question with no result, or an approval with no result and no decision (a decided approval is not waiting). `preparing(...)` is when the natural presentation's single status shows. `pendingNotice` and `finishNotice` give the words of the run toasts and system notifications from one table, `defaultNoticeText`, which a surface can replace to localize them. Evidence: `test/packages/ui-chat-view.test.mjs`.
+
 ### Native conversation history
 
 `loadEarlier()` reads one native page through `Conversation.entries`. `snapshot.history` distinguishes disabled, idle, loading, ready and error states. Each request contains at most 40 native entries. The controller accumulates pages in display order for the person's current browsing session and retains an opaque native continuation cursor. It clears that cache on history invalidation or `clearHistory()`; loading never restores records to model context. The first request captures the greatest observed active entry ID as an inclusive upper bound; later writes do not move that bound. Parent-owned fork entries remain valid native history.

package/dist/chat-view.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Optional chat view rules: what a native Pi conversation view means for a chat surface. Pure functions over Pi types; no React,
+ * files, agent or controller runtime. Registry items (pi-chat, pi-ambient, ...) draw these rows and words, they do not re-derive them.
+ *
+ * `Content` is whatever the surface renders (React nodes in the registry); this module never reads it.
+ */
+import type { ConversationView, EntryRecord, InboxItem, JsonObject } from '@earendil-works/pi-durable';
+import type { JsonValue } from '@earendil-works/chord';
+import type { AssistantMessage, ImageContent, ToolCall, ToolResultMessage, UserMessage } from '@earendil-works/pi-ai';
+import type { ChatSnapshot } from './native-chat.js';
+/** The tool that asks the person a question (`ask_user` of `@hachej/boring-agent/ask-user`). Its calls are question parts. */
+export declare const ASK_USER_TOOL = "ask_user";
+/** Key of `{ summary, decision? }` in a gated call's details: `APPROVAL_DETAILS` of `@hachej/boring-agent/approval` (a contract test keeps them equal). */
+export declare const APPROVAL_DETAILS = "boring.approval";
+/** The decision `requireApproval` records for a gated call. */
+export type ApprovalDecision = 'approved' | 'denied' | 'cancelled';
+/** The host adds file content for `@path` mentions as parts that start like this; the message already shows the mention itself. */
+export declare const isFileBlock: (text: string) => boolean;
+/** A marked app context stays in the native message; presentation collapses only a valid leading target block to a chip. */
+export declare function targetContent(text: string): {
+    readonly target: JsonObject;
+    readonly speech: string;
+    readonly label: string;
+} | undefined;
+/** A submission waiting in the native inbox (steer or follow-up); `queuedMessages` reads them from the view, the queue renders them. */
+export type QueuedMessage = Extract<InboxItem, {
+    readonly mode: 'steer' | 'followUp';
+}>;
+export type ToolStatus = 'running' | 'completed' | 'failed' | 'unfinished';
+export interface ToolEntry<Content = unknown> {
+    readonly key: string;
+    readonly call: ToolCall;
+    readonly result: ToolResultMessage | undefined;
+    readonly status: ToolStatus;
+    readonly custom?: Content;
+}
+/**
+ * An artifact a tool call made (or a running `present` call is making), as the chat places it. `descriptor` is the artifacts item's own
+ * value: the chat hands it back to the host's `open` and `isOpen` and never reads it.
+ */
+export interface ChatArtifact {
+    readonly state: 'presenting' | 'ready';
+    /** One card per id in a reply: the last version, at the place of its last step. */
+    readonly id: string | undefined;
+    readonly title: string | undefined;
+    /** The workspace path, for the conversation's file list. */
+    readonly path: string | undefined;
+    /** The tool's own result carries it, so its card replaces the step; a host-detected one is shown in addition to the step. */
+    readonly own: boolean;
+    readonly descriptor: unknown;
+}
+/** Finds an artifact descriptor a finished call's result does not carry itself (the host's `detect`). */
+export type ArtifactDetect = (call: ToolCall, result: ToolResultMessage) => unknown;
+/** The artifact a call made, or that a running call (`running`) is making; undefined for any other call. */
+export type ArtifactRecognise = (call: ToolCall, result: ToolResultMessage | undefined, running: boolean, detect: ArtifactDetect | undefined) => ChatArtifact | undefined;
+/**
+ * Draws a tool call that ran a sub-agent, from the details its running slot published (`details`) or that it finished with.
+ * Undefined: the call is not a sub-agent call and stays an ordinary tool step.
+ */
+export type SubagentRenderer<Content = unknown> = (call: ToolCall, details: unknown, result: ToolResultMessage | undefined) => Content | undefined;
+/** `required` pins the card above the transcript. `inline` keeps an entry/tool card in place in expert mode too;
+ * inline entries remain part of the answer. Other custom tool cards show only in developer mode or on failure. */
+export interface ChatCard<Content = unknown> {
+    readonly content: Content;
+    readonly required?: boolean;
+    readonly inline?: boolean; /** Host stage wording for the single natural status; null clears it. */
+    readonly status?: Content;
+}
+export type Mode = 'expert' | 'developer';
+export type StreamPart = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'thinking';
+    readonly thinking: string;
+} | ToolCall;
+export type QuestionPart = {
+    readonly kind: 'question';
+    readonly key: string;
+    readonly call: ToolCall;
+    readonly result: ToolResultMessage | undefined;
+    readonly live: boolean;
+    readonly questionId: string | undefined;
+};
+export type ApprovalPart<Content = unknown> = {
+    readonly kind: 'approval';
+    readonly key: string;
+    readonly call: ToolCall;
+    readonly result: ToolResultMessage | undefined;
+    readonly live: boolean; /** The bound question ID the answer must use (as for `question`). */
+    readonly questionId: string | undefined; /** The one-line summary `requireApproval` published for this call. */
+    readonly summary: string; /** The decision it recorded, once made. */
+    readonly decision?: ApprovalDecision; /** The call's own step, shown in the activity block once it has a result. */
+    readonly entry?: ToolEntry<Content>;
+};
+export type Part<Content = unknown> = {
+    readonly kind: 'card';
+    readonly key: string;
+    readonly content: Content;
+} | {
+    readonly kind: 'text';
+    readonly key: string;
+    readonly text: string;
+} | {
+    readonly kind: 'thinking';
+    readonly key: string;
+    readonly text: string;
+    readonly streaming: boolean;
+} | QuestionPart | ApprovalPart<Content> | {
+    readonly kind: 'subagent';
+    readonly key: string;
+    readonly call: ToolCall;
+    readonly result: ToolResultMessage | undefined; /** The sub-agent card, from the details the call published (live) or finished with. */
+    readonly content: Content; /** The call's own step, shown in the activity block once it has a result. */
+    readonly entry?: ToolEntry<Content>;
+} | {
+    readonly kind: 'artifact';
+    readonly key: string;
+    readonly call: ToolCall;
+    readonly artifact: ChatArtifact; /** Set when the host's `detect` found the descriptor: the call stays a step of the activity block too. */
+    readonly entry?: ToolEntry<Content>;
+} | {
+    readonly kind: 'tool';
+    readonly key: string;
+    readonly entry: ToolEntry<Content>;
+};
+export type Row<Content = unknown> = ({
+    readonly key: string;
+    readonly type: 'user';
+    readonly message: UserMessage; /** `messageStyle="messaging"`: first of a run (see `markLeads`). */
+    readonly lead?: boolean;
+} | {
+    readonly key: string;
+    readonly type: 'assistant';
+    readonly lead?: boolean;
+    readonly parts: readonly Part<Content>[]; /** Native result images remain visible when their tool chrome is omitted. */
+    readonly images?: readonly ImageContent[];
+    readonly streaming: boolean; /** The turn is still running (the last row while a run is active). */
+    readonly active?: boolean;
+    readonly stopReason?: AssistantMessage['stopReason'];
+    readonly errorMessage?: string;
+    readonly text: string; /** When the reply was written (the last round of a merged turn), in ms. Absent while it streams. */
+    readonly timestamp?: number; /** The model that wrote the last round of the reply. */
+    readonly model?: {
+        readonly provider: string;
+        readonly modelId: string;
+    }; /** Sum of the merged rounds' native `durationMs`, when recorded. */
+    readonly durationMs?: number; /** The native entry of its last committed round: where a fork of the conversation after this reply starts. */
+    readonly entryId?: string;
+} | {
+    readonly key: string;
+    readonly type: 'orphan-result';
+    readonly message: ToolResultMessage;
+} | {
+    readonly key: string;
+    readonly type: 'system';
+    readonly text: string;
+} | {
+    readonly key: string;
+    readonly type: 'event';
+    readonly label: string;
+} | {
+    readonly key: string;
+    readonly type: 'card';
+    readonly card: ChatCard<Content>;
+}) & {
+    readonly historical?: boolean;
+};
+export declare function object(value: JsonValue | undefined): JsonObject | undefined;
+export declare function streamParts(value: JsonValue | undefined): StreamPart[];
+export declare function queuedMessages(view: ConversationView | undefined): QueuedMessage[];
+export interface Derived<Content = unknown> {
+    readonly rows: readonly Row<Content>[];
+    /** Required entry and tool cards: pinned above the transcript. */
+    readonly pinned: readonly {
+        readonly key: string;
+        readonly content: Content;
+    }[];
+    readonly run: JsonObject | undefined;
+    readonly retry: JsonObject | undefined;
+    readonly compacting: boolean;
+    readonly stageStatus?: Content;
+}
+export interface DeriveOptions<Content = unknown> {
+    readonly mode: Mode;
+    /** Complete assistant lines to omit. With live text, the unfinished last line waits for its newline or settlement. */
+    readonly hideLine?: ((line: string) => boolean) | undefined;
+    readonly renderEntry: ((entry: EntryRecord) => ChatCard<Content> | undefined) | undefined;
+    readonly renderTool: ((call: ToolCall, result: ToolResultMessage | undefined) => ChatCard<Content> | undefined) | undefined;
+    readonly groupTool: ((call: ToolCall, result: ToolResultMessage) => boolean) | undefined;
+    /** Turn artifact tool results into cards (`recognise`; `detect` finds descriptors the tool result does not carry itself). */
+    readonly artifacts?: {
+        readonly recognise: ArtifactRecognise;
+        readonly detect?: ArtifactDetect | undefined;
+    } | undefined;
+    /** Draws sub-agent calls. Without it they are ordinary tool steps. */
+    readonly subagent?: SubagentRenderer<Content> | undefined;
+    /** `natural` shows only what a non-developer reads: their messages, the assistant's prose and the question, approval and artifact cards. Tool steps, reasoning, system rows and raw error text are left out of the rows (the entries stay as they are). */
+    readonly presentation?: 'natural' | undefined;
+}
+/** The display rows of a native conversation view, plus its run, retry, compaction and pinned cards. */
+export declare function derive<Content = unknown>(view: ConversationView | undefined, options: DeriveOptions<Content>): Derived<Content>;
+/** What a reply reports about the model round that wrote it, read from Pi's own message (each field only when it is there). */
+export declare function replyMeta(message: AssistantMessage): {
+    readonly timestamp?: number;
+    readonly model?: {
+        readonly provider: string;
+        readonly modelId: string;
+    };
+    readonly durationMs?: number;
+};
+/** One step of an activity block: a default tool call or a stretch of reasoning. */
+export type Step<Content = unknown> = {
+    readonly kind: 'tool';
+    readonly key: string;
+    readonly entry: ToolEntry<Content>;
+} | {
+    readonly kind: 'thinking';
+    readonly key: string;
+    readonly text: string;
+    readonly streaming: boolean;
+};
+/** An assistant turn is text parts and activity blocks: one block per uninterrupted run of steps. */
+export type Segment<Content = unknown> = {
+    readonly kind: 'part';
+    readonly part: Part<Content>;
+} | {
+    readonly kind: 'activity';
+    readonly key: string;
+    readonly steps: readonly Step<Content>[];
+};
+export declare function segments<Content>(parts: readonly Part<Content>[], groupTool: DeriveOptions['groupTool']): Segment<Content>[];
+/**
+ * `messageStyle="messaging"`: flags the first user or assistant row of each run (a change of side, or more than 15 minutes since the
+ * last message) so only it gets a tail. A row keeps its identity while its flag does not change, so memoized rows stay still.
+ */
+export declare function markLeads<Content>(rows: readonly Row<Content>[]): readonly Row<Content>[];
+/**
+ * The newest question or approval that waits for the person: committed (not still being generated), with no result yet and, for an
+ * approval, no decision recorded. An approval whose decision is made is not waiting: the run carries on (or stops) by itself.
+ */
+export declare function waitingPart<Content>(rows: readonly Row<Content>[]): QuestionPart | ApprovalPart<Content> | undefined;
+/** Whether this one part waits for the person (the rule of `waitingPart`). */
+export declare function waits<Content>(part: Part<Content>): part is QuestionPart | ApprovalPart<Content>;
+/** Whether the conversation waits for the person to answer a question or decide an approval (`waitingPart`). */
+export declare const waitingForAnswer: (rows: readonly Row<unknown>[]) => boolean;
+/** `presentation="natural"`: whether the one "preparing" status shows. Any work (a run, a retry, a compaction) counts, except a confirmed stop with no run left; a question waiting for the person does not. */
+export declare function preparing(input: {
+    readonly natural: boolean;
+    readonly waitingForAnswer: boolean;
+    readonly run: unknown;
+    readonly retry: unknown;
+    readonly compacting: boolean;
+    readonly stop: ChatSnapshot['stop'];
+}): boolean;
+/** The words of run notices (toasts and system notifications). One table, so a surface localizes them in one place. */
+export declare const defaultNoticeText: {
+    /** What a waiting approval asks. */
+    approve: (summary: string) => string;
+    /** A failed run that reported no error message. */
+    runFailed: string;
+    /** A finished run whose reply has no text. */
+    finished: string;
+};
+export type NoticeText = typeof defaultNoticeText;
+/** One line from a Markdown reply: its first non-empty line without Markdown marks, cut with an ellipsis. */
+export declare function summaryOf(text: string, limit?: number): string;
+/**
+ * What a notice says about the question or approval waiting for the person (`waitingPart`), if one waits. `question` reads the
+ * question text from an `ask_user` call (the question item owns that grammar).
+ */
+export declare function pendingNotice(rows: readonly Row<unknown>[], question: (call: ToolCall) => string, text?: NoticeText): string | undefined;
+/** What a notice says about a run that just ended, from the conversation's rows; `undefined` when the person stopped it. */
+export declare function finishNotice(rows: readonly Row<unknown>[], text?: NoticeText): {
+    readonly kind: 'done' | 'error';
+    readonly summary: string;
+} | undefined;
+//# sourceMappingURL=chat-view.d.ts.map