@stringsync/splates 0.0.60 → 1.13.3

package/vendor/@stringsync/splates-server/conversations/state.d.ts

@@ -0,0 +1,606 @@
+import { Duration } from "../../../core/time/index.js";
+import type { Flag } from "../agents";
+import type { Artifact } from "../artifacts";
+import type { OpenCodeUsage } from "../models";
+import type { Event } from "../records";
+/** What a session has used before its agent says anything of it. */
+export declare function unused(): Usage;
+/** Where an agent waits for a place, as the page shows it. */
+export interface QueueSpot {
+    /** From 1, the next to be placed. */
+    position: number;
+    /** How many wait in all, on every project. */
+    of: number;
+    /** When it joined the queue. */
+    since: string;
+    /** Why it waits: "no free place", or "needs macOS" for a platform no worker runs. */
+    reason: string;
+}
+/** 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 or a scratch conversation. */
+    task: string | null;
+    /** Runs projectless in its own scratch workspace; absent for a project's conversation. */
+    scratch?: true;
+    /**
+     * 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;
+    /** Where its agent waits for a place on a worker; null once it has one, or wants none. */
+    queue: QueueSpot | null;
+    messages: Message[];
+    /** What splates did at its agent's word, oldest first, shown 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;
+    /**
+     * Archived resting: a persistent agent's run that ended with its role
+     * still on, the next run to start afresh in a new conversation. The
+     * newest of its role holds the role's row while no run is on, as a
+     * placeholder. Absent or false otherwise.
+     */
+    resting?: boolean;
+    /** 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 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 queued task 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;
+    /**
+     * Auto pick is still deciding its agent: it shows the agent the rules
+     * fall back on with no judge until the pick lands, and opens none before.
+     */
+    picking: boolean;
+    /**
+     * What Auto pick set it to, and on what rule, once it has; null for one
+     * it did not start, or before it decided.
+     */
+    autoPick: AutoPickMark | null;
+    /**
+     * Started by the server's queue or a hook, so its agent waits while
+     * starts are paused; the person's own conversations never do.
+     */
+    automatic: boolean;
+    /**
+     * The queued task it is held for, out of the line for a place until the
+     * queue starts that task and gives it its worktree; null otherwise.
+     */
+    heldForTask: number | null;
+    /**
+     * 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;
+    /**
+     * How many of its messages, those not queued, the person has read, by
+     * their reaching the foot of the page's view: it opens at the one after.
+     * Null for one the page has yet to report on, which opens at the foot, or
+     * at `seen` when unread.
+     */
+    read: number | null;
+    /**
+     * 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;
+    /**
+     * Why a worker budget hard stop asked the checkpoint, like `daily limit
+     * $5.00 reached`, kept in the log so a restart leaves it for the budget
+     * to carry on once it allows again; null for any other checkpoint, and
+     * once the work went on past it.
+     */
+    budgetStop: string | null;
+    /** 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[];
+    /**
+     * A run its `run evals` card started is going, which the agent hears of
+     * once it is done: set by the server while it runs, kept in no log.
+     */
+    evaluating?: true;
+    /**
+     * Set when this is only a summary, as a listing sends every conversation:
+     * read `GET /api/conversations/<id>` for its tool calls, thoughts and
+     * commands.
+     */
+    summary?: true;
+    /**
+     * The role of a persistent agent, as `"groomer"`: splates starts one
+     * conversation for the role per run, each with a fresh context, and
+     * keeps the role's row atop the list, archiving each run as it ends.
+     * Absent for an ordinary conversation.
+     */
+    persistent?: string;
+    /**
+     * The person's automation that started it, by its id, as an agent hook
+     * on a task event or a schedule, run by hand or not, so the page lists it
+     * with the persistent agents. Absent for any other.
+     */
+    automation?: string;
+    /**
+     * The ship, by its id, whose adoption task it runs, so the page marks it
+     * with a ship. Absent for any other.
+     */
+    ship?: string;
+}
+/**
+ * Where the agent is: `stopped` and `failed` have no process, and the next
+ * prompt resumes the session in a new one.
+ */
+/** What Auto pick set a conversation to, and why, as its log keeps it. */
+export interface AutoPickSet {
+    /** The index in the rules of the rule it took; null before it took one, as for a conversation switched on that it has yet to look at. */
+    rule: number | null;
+    /** The kind and depth it was taken for; null when the judge was unsure. */
+    kind: string | null;
+    depth: string | null;
+    /** How settled the behavior was; absent on older picks. */
+    clarity?: string | null;
+    agent: string;
+    /** By the roster's id; null for the agent's own. */
+    model: string | null;
+    effort: string | null;
+}
+/** A conversation's Auto pick, and whether the person has moved off it since. */
+export interface AutoPickMark extends AutoPickSet {
+    /** The person set the model or effort since, or switched it off, which then stands. */
+    overridden: boolean;
+    /**
+     * The person switched it on: the next message they say is judged with
+     * all they said before, and the conversation moves to the rules' pick
+     * for it, down as well as up, on the agent it runs.
+     */
+    rejudge?: true;
+}
+/**
+ * What Auto pick holds for `state` once the person switches it `on` or off:
+ * on, to judge their next message afresh, keeping what it picked before, if
+ * anything; off, what it picked, overridden, or nothing for a conversation it
+ * never picked for.
+ */
+export declare function switched(state: Pick<ConversationState, "autoPick" | "agent">, on: boolean): AutoPickMark | null;
+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;
+/**
+ * The `told` of a message `splates server` said itself, as to the agent of a
+ * running lane's task: compare a message's `told` to it to name the server
+ * rather than another conversation.
+ */
+export declare const SERVER_TOLD = "splates";
+/**
+ * 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`, or `SERVER_TOLD`
+     * for `splates server`, 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;
+    /**
+     * Set while it is on its way: when the page sent it, as epoch ms, which
+     * the line under it counts its timeout from.
+     */
+    sending?: number;
+}
+/** 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;
+    /**
+     * For a call that left its command running in the background, as Claude's
+     * Bash with `run_in_background`, how that command went: kept once it ends,
+     * as the thread's line for it says.
+     */
+    background?: Backgrounded;
+}
+/** How a command a tool call left in the background went. */
+export interface Backgrounded {
+    /** The agent's id for it, as the conversation's `Background` names it. */
+    id: string;
+    state: BackgroundState;
+    /** What it exited with, once the agent says; null until then, or when it never does. */
+    exitCode: number | null;
+    /** When it ended; null until it has, or in a log too old to say. */
+    until: string | 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;
+}
+/** 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, startedBy?: string | null, scratch?: boolean): ConversationState;
+/**
+ * `state` as a listing sends it: a summary, since the
+ * page shows little of one until it is opened, and its events and messages
+ * are most of what every conversation weighs. ⌘K searches the rest on the
+ * server (see `saidIn`).
+ */
+export declare function listed(state: ConversationState): ConversationState;
+/**
+ * Moves `state` onto `agent`, as Auto's pick does before any session opens,
+ * keeping the usage only OpenCode tracks for OpenCode.
+ */
+export declare function runOn(state: ConversationState, agent: string): void;
+/**
+ * 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/vendor/@stringsync/splates-server/conversations/stream.d.ts

@@ -0,0 +1,34 @@
+import { type Resource } from "../../../core/disposable/index.js";
+import type { Conversations } from "./conversations";
+import { type ConversationState } from "./state";
+/** What a listener hears of a project's conversations. */
+export interface ConversationsHeard {
+    /** A conversation, whole, as it is now. */
+    changed(state: ConversationState): void;
+    /** An older archived conversation, deleted. */
+    removed(id: string): void;
+    /** The agents' saved settings or limits moved. */
+    settings(): void;
+}
+/**
+ * Streams each project's conversations at most once per beat. Pages receive
+ * summaries when they connect, then deltas; other listeners receive states.
+ */
+export declare class ConversationStream implements Resource {
+    private readonly conversations;
+    private readonly pages;
+    private readonly copies;
+    private readonly heard;
+    /** Each conversation's beat, by id, while it lives. */
+    private readonly beats;
+    private readonly disposer;
+    constructor(conversations: Conversations);
+    /** The stream a page listens to. */
+    events(): Response;
+    /** Tells `heard` of each change a page hears, until the returned function is called. */
+    listen(heard: ConversationsHeard): () => void;
+    dispose(): void;
+    private changed;
+    private write;
+    private send;
+}

package/vendor/@stringsync/splates-server/conversations/transcript.d.ts

@@ -0,0 +1,9 @@
+import type { Message } from "./state";
+/** How much of the end of a conversation a transcript keeps, in characters. */
+export declare const TRANSCRIPT_CHARS = 40000;
+/**
+ * The end of what was said and done in `messages`, as markdown for the next
+ * agent on its task to read: each turn's words, and a line for each command
+ * or other tool its agent ran, with how it ended. Thoughts and files stay out.
+ */
+export declare function transcriptOf(messages: readonly Message[]): string;

package/vendor/@stringsync/splates-server/conversations/tree.d.ts

@@ -0,0 +1,11 @@
+import type { WorktreeService } from "../tasks";
+/**
+ * Where a conversation runs: its task's name, the tree, the branch the task
+ * was cut from, and the conversation whose agent added it.
+ */
+export type Tree = [string | null, string, string | null, string | null];
+/**
+ * Where a conversation for `task` runs: its worktree, or the main tree for
+ * none, refusing a task whose worktree is gone.
+ */
+export declare function treeOf(service: WorktreeService, task: unknown): Promise<Tree>;

package/vendor/@stringsync/splates-server/conversations/turn-end.d.ts

@@ -0,0 +1,30 @@
+import type { Used } from "../spend";
+import type { Adherence, Outcomes } from "../stats";
+import type { Storage } from "../storage";
+import type { Conversation } from "./conversation";
+import type { ProjectRoster } from "./host";
+import type { ConversationsOptions } from "./options";
+/** What looks back at a turn once it ends, each null for nothing. */
+export interface LookingBack {
+    adherence: Adherence | null;
+    outcomes: Outcomes | null;
+    spend: NonNullable<ConversationsOptions["spend"]> | null;
+    storage: Storage;
+    root: string | null;
+    projects: ProjectRoster | null;
+}
+/** A turn as it began, as far as this server saw it begin. */
+export interface Began {
+    /** When; null when it began before this server. */
+    at: string | null;
+    /** What it had used by then, for the ledger; null when unseen. */
+    used: Used | null;
+    /** How many turns OpenCode had said it ran by then. */
+    turnsBefore: number;
+}
+/**
+ * Looks back, without waiting, at the turn of `conversation` that began as
+ * `began` says and has just ended, however it did: how it followed the
+ * skill, an outcome it saved, what it cost.
+ */
+export declare function lookBack(conversation: Conversation, { adherence, outcomes, spend, storage, root, projects }: LookingBack, began: Began): void;