@stringsync/splates 0.0.0-stage → 0.0.45

package/conversation-state.d.ts

@@ -0,0 +1,472 @@
+import { Duration } from "webappwiz/time";
+import type { Artifact } from "./artifacts.js";
+import type { Event } from "./events.js";
+import type { OpenCodeUsage } from "./opencode-usage.js";
+import type { Flag } from "./watch.js";
+/** Everything the page shows of one conversation. */
+export interface ConversationState {
+    id: string;
+    agent: string;
+    /** The task whose worktree it runs in; null for the main tree. */
+    task: string | null;
+    /**
+     * The task it runs in, or last ran in once that task merged or went; null
+     * until it runs in one.
+     */
+    lastTask: string | null;
+    /**
+     * The branch `lastTask` was cut from, `task/<caller>` for a part, kept once
+     * it merges so the page still nests it under its caller; null for none.
+     */
+    lastBase: string | null;
+    /**
+     * The conversation whose agent added `lastTask`, kept once it merges so
+     * the page still nests it under that one; null for none.
+     */
+    lastCaller: string | null;
+    /** What the agent calls it, once it says. */
+    title: string | null;
+    /** What the person renamed it to, over the agent's title. */
+    name: string | null;
+    status: Status;
+    /** Why it failed, for `failed`. */
+    error: string | null;
+    /**
+     * When splates stopped its agent for sitting idle `IDLE_STOP`; null otherwise,
+     * and again once it starts.
+     */
+    stoppedIdle: string | null;
+    /**
+     * When splates next asks it, idle with an agent it handed a task to at
+     * work, to check on its agents; null while none is due.
+     */
+    heartbeat: string | null;
+    messages: Message[];
+    /**
+     * What splates did at its agent's word, oldest first, read from the journal
+     * rather than its log, so the page can show each among its messages.
+     */
+    events: Event[];
+    ask: Ask | null;
+    /** What the session lets the person pick: its mode, model, effort. */
+    settings: Setting[];
+    /** The skills and commands a message can start with, as the agent last said. */
+    commands: Command[];
+    createdAt: string;
+    /** Put away: stopped, kept off the list, shown with the archived ones. */
+    archived: boolean;
+    /** When it was archived; null when not archived, or for a log too old to say. */
+    archivedAt: string | null;
+    /**
+     * The conversation whose archiving put this one away with it, which
+     * unarchiving that one brings back; null when it was archived alone, or
+     * is not archived.
+     */
+    archivedWith: string | null;
+    /** Kept atop the list, archived or not, until unpinned. */
+    pinned: boolean;
+    /**
+     * Where the person nested it in the list, over where its task would:
+     * under the conversation `id`, or at the top for a null `id`. Null until
+     * they do, while it nests by its task.
+     */
+    parent: {
+        id: string | null;
+    } | null;
+    /**
+     * The conversation that handed it its task with `splates add --agent`, which
+     * it answers to in place of the person: the page writes nothing to it but
+     * an answer to what its agent asks permission for, and its terminating.
+     * Set when it starts, and kept once the task is gone.
+     */
+    handedBy: string | null;
+    /**
+     * The lane orchestrator that handed it its task with `splates add --agent`:
+     * it answers to the person, as any conversation does, and that one only
+     * hears when it stops, and may wake, stop or remove it. Set when it
+     * starts, and kept once the task is gone.
+     */
+    startedBy: string | null;
+    /**
+     * The `version:` of the project's splates skill as it started, which the
+     * Stats page tells adherence apart by; null when it had none, or for a log
+     * written before it was kept.
+     */
+    skill: string | null;
+    /**
+     * Started on the agent and model a todo or `splates add --agent` assigned,
+     * rather than ones the person picked, so a new conversation does not start
+     * where this one left its settings.
+     */
+    assigned: boolean;
+    /**
+     * The agent ended a turn the person has not seen yet: set as each turn
+     * ends, and cleared once the page shows it.
+     */
+    unread: boolean;
+    /**
+     * How many of its messages, those not queued, the person had seen when it
+     * was last marked read: an unread one opens at the one after.
+     */
+    seen: number;
+    /**
+     * Where the last checkpoint asked stands, kept in the log so a restart
+     * still shows it; null when none was, or once the work went on past it.
+     */
+    checkpoint: Checkpoint | null;
+    /**
+     * Whether the checkpoint asked is the person's pause, which Power leaves
+     * alone and nothing resumes: forgotten once it ends.
+     */
+    pausing: boolean;
+    /** What a message said now would do, so the page places it as the server will. */
+    taking: Taking;
+    usage: Usage;
+    /** The commands the agent left in the background, oldest first. */
+    background: Background[];
+    /** The files its agent kept as its outputs, in the order first added, removed ones too. */
+    artifacts: Artifact[];
+}
+/**
+ * Where the agent is: `stopped` and `failed` have no process, and the next
+ * prompt resumes the session in a new one.
+ */
+export type Status = "starting" | "idle" | "running" | "stopped" | "failed";
+/**
+ * What a message said to a conversation would do: `start` a turn of its own,
+ * `steer` into the running turn, or `queue` for the turn's end.
+ */
+export type Taking = "start" | "steer" | "queue";
+/** How long an agent sits idle before splates stops its process. */
+export declare const IDLE_STOP: Duration;
+/**
+ * How long the conversation that handed tasks out sits idle, with an agent it
+ * handed one to at work, before splates asks it to check on them.
+ */
+export declare const HEARTBEAT_IDLE: Duration;
+/**
+ * Where a checkpoint stands: asked of the agent, done once its turn ends,
+ * failed with the turn, or unanswered after `CHECKPOINT_WAIT`.
+ */
+export type Checkpoint = "asked" | "done" | "failed" | "unanswered";
+/**
+ * What follows a checkpoint once every agent is done: `splates server` restarts
+ * and tells each to carry on, or shuts down, and its next start does.
+ */
+export type After = "resume" | "shutdown";
+/** One turn's worth of words, the person's or the agent's. */
+export interface Message {
+    role: "user" | "agent";
+    parts: Part[];
+    /** The agent's plan, as last sent; null when it sent none. */
+    plan: Step[] | null;
+    /** When it began and last moved; null in a log too old to say. */
+    at: string | null;
+    until: string | null;
+    /**
+     * Said while the agent worked, to an agent that cannot take it mid-turn:
+     * it goes out when the turn ends.
+     */
+    queued?: true;
+    /** When a queued prompt reached the agent; absent for prompts sent immediately or old logs. */
+    sentAt?: string;
+    /** When the person stopped the agent's turn, for one they stopped. */
+    stopped?: string;
+    /** When the connection to the agent was lost mid-turn, for one it cut short. */
+    interrupted?: string;
+    /** Said while the agent worked, and taken into the turn it was running. */
+    steered?: true;
+    /** The conversation that said it with `splates tell`, for one the person did not say. */
+    told?: string;
+    /** Said into the mic rather than typed. */
+    dictated?: true;
+    /** The id the page gave it as it sent it, so it knows its own copy when it comes back. */
+    id?: string;
+    /**
+     * Still on its way to the server, unanswered for a while: set only by the
+     * page, on its own copy, never by the server.
+     */
+    sending?: true;
+}
+/** One piece of what someone in a conversation said or did. */
+export type Part = 
+/**
+ * `at` is when the agent began saying it, where the server knows;
+ * `message` is the agent's id for its latest message here, if it gave one.
+ */
+{
+    type: "text";
+    text: string;
+    at?: string | null;
+    message?: string | null;
+}
+/** `at` is when the agent began it; null in a log too old to say. */
+ | {
+    type: "thought";
+    text: string;
+    at: string | null;
+    message?: string | null;
+} | ({
+    type: "image";
+} & Image) | ({
+    type: "file";
+} & Attached) | Tool | Compaction;
+/** An image the person sent, kept beside the conversation's log as `name`. */
+export interface Image {
+    name: string;
+    mimeType: string;
+    /**
+     * Preview URL to display while the image uploads.
+     */
+    url?: string;
+}
+/**
+ * A file the person sent, other than an image the agent sees, kept beside
+ * the conversation's log as `name`; the agent is sent a link to it.
+ */
+export interface Attached extends Image {
+    /** What the person called it. */
+    title: string;
+}
+/** A file the person sent, as the page sends it, before it is kept. */
+/** Where the person said something on the page: its phone layout or its wide one. */
+export type Device = "phone" | "desktop";
+export declare const DEVICES: readonly Device[];
+/** The header a prompt from the page names its `Device` in. */
+export declare const FROM_HEADER = "splates-from";
+export interface Upload {
+    /** What the person called it. */
+    title: string;
+    mimeType: string;
+    bytes: Uint8Array;
+}
+/** What the person sent with their words, as their message holds it. */
+export type Sent = Extract<Part, {
+    type: "image" | "file";
+}>;
+/** A tool call the agent made, as much of it as the page shows. */
+export interface Tool {
+    type: "tool";
+    id: string;
+    title: string;
+    status: "pending" | "in_progress" | "completed" | "failed";
+    /** What ACP says it does: read, edit, execute, search, think, and so on. */
+    kind: string | null;
+    /** The command it runs, for one that runs one. */
+    command: string | null;
+    /** What it searches for or fetches, as its input names it: a pattern, a query or a URL. */
+    target: string | null;
+    /** The end of what it printed, at most `TOOL_CHARS`. */
+    output: string;
+    /** The reported process exit code; absent until reported, or in older state. */
+    exitCode?: number;
+    /** The changes it made to files. */
+    edits: Edit[];
+    /** The files it touched. */
+    paths: string[];
+    /** The subagent's tool call it was made under, if one made it. */
+    parent: string | null;
+    /**
+     * For a call that starts a subagent, as Claude's Agent tool: its type and
+     * the model it was asked to run on, each null when the call names none.
+     */
+    subagent?: {
+        type: string | null;
+        model: string | null;
+    };
+    /** When it began and finished; null in a log too old to say, or until it has. */
+    at: string | null;
+    until: string | null;
+    /** What a command did to git that it should not have. */
+    flags: Flag[];
+    /** How the person answered the agent asking to make it; null when it never asked. */
+    decision: Decision | null;
+}
+/**
+ * The agent folding its context into a summary, as Claude does at its
+ * window's limit or on `/compact`: what came before it is only remembered as
+ * that summary from then on.
+ */
+export interface Compaction {
+    type: "compaction";
+    id: string;
+    status: "in_progress" | "completed" | "failed";
+    /** Whether the agent compacted on its own, at its limit, or was told to; null until it says. */
+    trigger: "automatic" | "manual" | null;
+    /** Tokens in context before and after; null until the agent says. */
+    before: number | null;
+    after: number | null;
+    /** What the agent kept of the thread above the line; null until it says, or when it does not. */
+    summary: string | null;
+    /** When it began and finished; null in a log too old to say, or until it has. */
+    at: string | null;
+    until: string | null;
+}
+/**
+ * A command the agent left running in the background, as Claude's Bash with
+ * `run_in_background`, kept once it ends until the agent's process does.
+ */
+export interface Background {
+    /** The agent's id for it, which stopping it names. */
+    id: string;
+    /** What the agent said it is for. */
+    name: string;
+    /** The command it runs, from the tool call that started it; null when unknown. */
+    command: string | null;
+    /**
+     * The subagent whose call started it, by that subagent's tool call; null
+     * for one the agent started itself, or when the call is unknown.
+     */
+    subagent: {
+        id: string;
+        title: string;
+    } | null;
+    state: BackgroundState;
+    /** The file the agent writes what it prints to; null until it says. */
+    output: string | null;
+}
+export type BackgroundState = "running" | "completed" | "failed" | "stopped";
+/** How the person answered an agent asking permission for a tool call. */
+export interface Decision {
+    /** When permission was requested; absent in older logs. */
+    askedAt?: string;
+    /** The option they picked; null for an ask dismissed, as by stopping the turn. */
+    option: {
+        name: string;
+        kind: string;
+    } | null;
+    at: string;
+}
+/** A change to one file: `old` is null for a file the edit created. */
+export interface Edit {
+    path: string;
+    old: string | null;
+    new: string;
+}
+/** A step of the agent's plan for the turn. */
+export interface Step {
+    text: string;
+    status: "pending" | "in_progress" | "completed";
+}
+/** A field of a question an agent asks, answered with one of `choices` or in words. */
+export interface Field {
+    key: string;
+    title: string;
+    description: string | null;
+    /** Absent for a field answered in words. */
+    choices: {
+        value: string;
+        title: string;
+        description: string | null;
+    }[] | null;
+}
+/** What the agent is waiting on the person for, since `at`. */
+export type Ask = Asked & {
+    at: string;
+};
+/** What the agent asks, before it is stamped with when. */
+export type Asked = {
+    type: "permission";
+    id: string;
+    title: string;
+    options: {
+        id: string;
+        name: string;
+        kind: string;
+    }[];
+} | {
+    type: "question";
+    id: string;
+    message: string;
+    fields: Field[];
+};
+/** How an `Ask` was answered. */
+export type Answer = {
+    type: "permission";
+    option: string;
+} | {
+    type: "question";
+    values: Record<string, string>;
+} | {
+    type: "dismiss";
+};
+/** A choice the agent offers for the session, like its model. */
+export interface Setting {
+    id: string;
+    name: string;
+    /**
+     * A pick among its options, or an on/off toggle, like fast mode, whose
+     * options are `on` and `off`.
+     */
+    type: "select" | "boolean";
+    /** What it sets, as ACP names it: mode, model, thought_level, or its own. */
+    category: string | null;
+    current: string;
+    options: {
+        value: string;
+        name: string;
+        description: string | null;
+    }[];
+}
+/** A command the agent runs when a message starts with `/` and its name. */
+export interface Command {
+    name: string;
+    description: string;
+    /** What to write after its name, for one that takes input. */
+    hint: string | null;
+}
+/** What a session has used, as far as its agent says. */
+export interface Usage {
+    /** OpenCode draft ACP observations, separate from legacy accounting. */
+    opencode?: OpenCodeUsage;
+    /** Tokens in the context window, of the most it holds; null until said. */
+    context: {
+        used: number;
+        size: number;
+    } | null;
+    /** Tokens read over every turn the agent counted, those from cache among them. */
+    input: number;
+    /** Of `input`, those read from cache. */
+    cached: number;
+    /** Tokens written over every turn the agent counted. */
+    output: number;
+    /**
+     * What the session cost, over every process it ran in; null for an agent
+     * that never says, as Codex does not.
+     */
+    cost: {
+        amount: number;
+        currency: string;
+        /**
+         * What the agent last said it had cost: Claude counts from naught in
+         * each new process, so a figure below it starts a new count.
+         */
+        said: number;
+    } | null;
+    /** The plan's windows of use, as the agent last said; none from Codex. */
+    limits: Limit[];
+}
+/**
+ * One window of the plan's use, as Claude says with each reply: the account's,
+ * not the session's, so every conversation with the agent shares it.
+ */
+export interface Limit {
+    /** As Claude names it: `five_hour`, `seven_day`, `seven_day_opus`. */
+    window: string;
+    /** How much of it is used, from 0 to 1. */
+    used: number;
+    /** When it starts over, as an ISO timestamp. */
+    resets: string;
+    /** When the agent said so; null in logs written before it was kept. */
+    at: string | null;
+}
+/** What a session has used before its agent says anything of it. */
+export declare function unused(): Usage;
+/** A conversation as it starts, before its agent has said anything. */
+export declare function blank(id: string, agent: string, task: string | null, createdAt: string, base?: string | null, caller?: string | null, assigned?: boolean, handedBy?: string | null, startedBy?: string | null): ConversationState;
+/**
+ * Who added the task a conversation moves to, as it keeps it: kept from
+ * before for none, and none for the task it was moved away from in the list,
+ * whose caller it was cut loose from.
+ */
+export declare function callerAfter(state: Pick<ConversationState, "lastCaller" | "lastTask" | "parent">, task: string | null, caller: string | null): string | null;

package/conversation-turns.d.ts

@@ -0,0 +1,115 @@
+import type { AgentConnection } from "./agent-connection.js";
+import type { ConversationFiles } from "./conversation-files.js";
+import type { ConversationDeps, ConversationHost } from "./conversation-host.js";
+import type { Attached, Checkpoint, Device, Taking, Upload } from "./conversation-state.js";
+/** What else a prompt says about who said it. */
+export interface PromptOptions {
+    /** The conversation that said it with `splates tell`, when the person did not. */
+    told?: string;
+    /** Whether the person said it into the mic rather than typed it. */
+    dictated?: boolean;
+    /** The id the page gave it, so the page knows its own copy when it comes back. */
+    id?: string;
+    /**
+     * Whether it stops the running turn and follows it, rather than joining
+     * it, for a change of plans.
+     */
+    stop?: boolean;
+}
+/**
+ * The turns of a conversation: what the person says goes to the agent as a
+ * prompt, steered into the turn it is running or queued for when that ends,
+ * and a checkpoint asks it to stop where it is.
+ */
+export declare class ConversationTurns {
+    private readonly host;
+    private readonly deps;
+    private readonly connection;
+    private readonly files;
+    /** Whether the person cancelled the last turn, which holds the queue. */
+    private held;
+    /** Gives up on an asked checkpoint once `CHECKPOINT_WAIT` is out. */
+    private waiting;
+    /** Whether a checkpoint is cancelling the turn, whose end is not its own. */
+    private interrupting;
+    constructor(host: ConversationHost, deps: ConversationDeps, connection: AgentConnection, files: ConversationFiles);
+    /**
+     * Says `text` to the agent, with `files`, once it has started, resuming
+     * the session first when it stopped and unarchiving it when archived.
+     * While the agent works, it joins the
+     * running turn when the agent can take it there, and otherwise waits for
+     * the turn to end.
+     */
+    prompt(text: string, files?: Upload[], from?: Device, { told, dictated, stop, id }?: PromptOptions): Promise<void>;
+    /**
+     * What `prompt` would do with a message said now, which the page shows it
+     * as: it follows the same rules as `prompt` does.
+     */
+    taking(): Taking;
+    /**
+     * Back to idle once a turn ends, then on to what was queued meanwhile,
+     * unless the person cancelled the turn: that holds the queue until they
+     * say something.
+     */
+    ended(error: string | null): void;
+    /**
+     * Marks a running turn as cut short, as when the connection is lost or the
+     * process exits, unless the person stopped it, which says so already.
+     */
+    interrupt(): void;
+    /** Whether a checkpoint has ended and nothing has been said since. */
+    get stoppedByCheckpoint(): boolean;
+    /**
+     * Asks the agent to bring its `SPLATES.md` up to date and stop, cancelling
+     * the turn it is on first, unless that turn is `merging`, which it says
+     * the checkpoint into, or queues it after. An idle agent is not asked,
+     * having ended its turn already. What the person queued stays queued, for
+     * the next prompt to send. A `pause` is forgotten once it ends, so
+     * nothing resumes it.
+     */
+    checkpoint(merging: boolean, pause?: boolean): Promise<void>;
+    /**
+     * Forgets the checkpoint, done or not, so the next starts afresh; an agent
+     * still on it carries on with its turn.
+     */
+    dismissCheckpoint(): void;
+    /**
+     * Keeps where the checkpoint stands, giving up the wait once it is past
+     * asked; a pause past asked is forgotten.
+     */
+    mark(checkpoint: Checkpoint | null): void;
+    /** Settles once the checkpoint asked is no longer under way. */
+    answered(): Promise<void>;
+    /**
+     * Takes back the `index`th queued message before the agent hears it,
+     * answering with its words and files, for the person to edit and send
+     * again.
+     */
+    unqueue(index: number): {
+        text: string;
+        files: Attached[];
+    };
+    /**
+     * Sends what is queued now: stops the running turn, whose end sends it,
+     * or, with no turn running, sends it as one.
+     */
+    sendNow(): Promise<void>;
+    /**
+     * Stops the agent's turn for the person, marking the turn as one they
+     * stopped, and leaves the conversation open for the next.
+     */
+    cancel(): Promise<void>;
+    /** Holds `words` and `sent` for when the turn ends, shown as said. */
+    private queue;
+    /**
+     * Starts a turn on `fresh`, with every message still queued ahead of it,
+     * as one prompt, or on `fresh` alone, leaving the queue as it is.
+     */
+    private send;
+    /** What `messages` say, as one prompt, for the tree the agent runs in. */
+    private content;
+    /** Settles once no turn is running, or the checkpoint has given up. */
+    private idle;
+    /** Stops the agent's turn, holding what is queued for the next prompt. */
+    private halt;
+}