@stringsync/splates 0.0.0-stage → 0.0.45

package/conversation-host.d.ts

@@ -0,0 +1,102 @@
+import type { Events } from "webappwiz/events";
+import type { IdProvider } from "webappwiz/id";
+import type { Fs, Lock } from "webappwiz/system";
+import type { Timer, WallClock } from "webappwiz/time";
+import type { Agent, Launcher } from "./agent-process.js";
+import type { ArtifactRoom } from "./artifact-room.js";
+import type { ArtifactLimits } from "./artifacts.js";
+import type { ConversationLog } from "./conversation-log.js";
+import type { ConversationState } from "./conversation-state.js";
+import type { Reach } from "./projects.js";
+import type { SessionServers } from "./shared-browser.js";
+import type { Watch } from "./watch.js";
+import type { WorkerMachine } from "./worker-machine.js";
+/**
+ * What a conversation's parts, its connection, its turns and its background
+ * commands, share of it: its state and log, and the few things they do to
+ * the whole. `Conversation` implements it.
+ */
+export interface ConversationHost {
+    readonly state: ConversationState;
+    readonly log: ConversationLog;
+    readonly events: Events<ConversationEvents>;
+    /** What runs it; null when its agent is no longer known. */
+    readonly agent: Agent | null;
+    /** Where it runs; null for a log too old to say. */
+    readonly cwd: string | null;
+    /** Under way while the agent starts or comes back, for a prompt to wait on. */
+    readonly opening: Promise<void> | null;
+    now(): string;
+    set(next: Partial<ConversationState>): void;
+    changed(): void;
+    /** A turn ended, with `error` for one that failed. */
+    ended(error: string | null): void;
+    /** Ends the agent's process, with `error` for one that failed. */
+    close(error: string | null): Promise<void>;
+    /** Brings a stopped conversation back: a new process, the same session or a new one. */
+    resume(): Promise<void>;
+    /** Back on the list, stopped until the next prompt. */
+    unarchive(): Promise<void>;
+    /** Marks it `unread` or not. */
+    flag(unread: boolean): void;
+}
+export type ConversationEvents = {
+    changed: undefined;
+    chosen: string;
+};
+/** What every conversation in a repo is made with. */
+export interface ConversationDeps {
+    fs: Fs;
+    /** What names the files artifacts are kept in. */
+    ids: IdProvider;
+    /** How many bytes of artifacts it may keep (`artifacts.ts`). */
+    artifacts: ArtifactLimits;
+    /** What makes room for an add across the project; none refuses one past it. */
+    room?: ArtifactRoom;
+    timer: Timer;
+    clock: WallClock;
+    /** What starts each agent, and takes one back after a restart. */
+    launcher: Launcher;
+    /** Where the agent runs, which its background commands' output is read from. */
+    machine: WorkerMachine;
+    /**
+     * Hold it while an agent's process starts, until it answers
+     * `initialize`, so agents start one at a time.
+     */
+    starting: Lock;
+    /** Where `splates server` answers, for the agent's CLI to tell it things. */
+    url: string | null;
+    /** What watches the agent's commands; null to leave them be. */
+    watch: Watch | null;
+    /** The main tree, where a conversation carries on once its worktree is gone. */
+    root: string | null;
+    /** The splates projects on this machine, for `#slug`; null for none. */
+    projects: ProjectRoster | null;
+    /** The MCP servers each session is offered, beyond the agent's own; null for none. */
+    servers: SessionServers | null;
+}
+/** The splates projects on this machine, as `Projects` lists them. */
+export interface ProjectRoster {
+    /** Each project, flagged `gone` when its repository is no longer there. */
+    list(): Promise<(ProjectRef & {
+        gone: boolean;
+    })[]>;
+    /** What the project at `from` may do in the one at `to`. */
+    reach(from: string, to: string): Promise<Reach>;
+}
+/** A splates project a prompt can name as `#slug`. */
+export interface ProjectRef {
+    slug: string;
+    /** Its main tree's root. */
+    root: string;
+}
+/**
+ * `changed`, `ended` (a turn ended, however it did, or the agent failed to
+ * start) and `removed` each carry a conversation's id.
+ */
+export type ConversationsEvents = {
+    settings: undefined;
+    changed: string;
+    ended: string;
+    removed: string;
+};

package/conversation-listing.d.ts

@@ -0,0 +1,15 @@
+import type { Conversations } from "./conversations.js";
+/** The conversations and saved agent defaults offered to the page. */
+export declare function listing(all: Conversations): Promise<{
+    agents: {
+        id: string;
+        name: string;
+        models: {
+            id: string;
+            name: string;
+        }[];
+        settings: import("./conversation-state.js").Setting[];
+        limits: import("./conversation-state.js").Limit[];
+    }[];
+    conversations: import("./conversation-state.js").ConversationState[];
+}>;

package/conversation-log.d.ts

@@ -0,0 +1,301 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import { type Eventful } from "webappwiz/events";
+import type { Fs } from "webappwiz/system";
+import { type Timer } from "webappwiz/time";
+import { type AsyncTaskUpdate } from "./acp-extensions.js";
+import type { ProcessHandle } from "./agent-process.js";
+import { type ArtifactChange } from "./artifacts.js";
+import { type Ask, type Attached, type Checkpoint, type ConversationState, type Decision, type Device, type Image, type Limit, type Setting } from "./conversation-state.js";
+import { type ObservedTurn } from "./opencode-usage.js";
+import type { Flag } from "./watch.js";
+/** What a `ConversationLog` says of its saves. */
+export interface ConversationLogEvents extends Record<string, unknown> {
+    /** A save reached the file: `savedThrough` may have moved. */
+    saved: undefined;
+}
+/**
+ * A conversation's log, one JSON line per entry: `write` each entry as it
+ * happens, and `replay` the file to read the conversation back.
+ */
+export declare class ConversationLog implements Eventful<ConversationLogEvents> {
+    readonly path: string;
+    private readonly fs;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<ConversationLogEvents>;
+    /** The lines not yet appended to the file, each with its seq. */
+    private readonly unsaved;
+    private saving;
+    private readonly saves;
+    /** The seq of the agent's frame being handled; 0 before the first. */
+    private seq;
+    /** The seq of the last entry the file holds. */
+    private lastSaved;
+    constructor(path: string, fs: Fs, timer: Timer);
+    /**
+     * The highest seq every entry at or under which the file holds: the seq
+     * before the first unsaved entry, or the last saved one with none unsaved.
+     */
+    get savedThrough(): number;
+    /** Stamps what is written from now on with frame `seq`. */
+    heard(seq: number): void;
+    /**
+     * What the log adds up to, read back: the conversation as its entries
+     * left it, stopped, whatever it was doing, unless its process is still
+     * out there (`live`), in which case it is left as it stands for whoever
+     * takes the process back, or `stopped` once nobody can. Null for a log
+     * that does not start one.
+     */
+    replay(): Promise<Replayed | null>;
+    /**
+     * Leaves `replayed` as a conversation whose process is gone: its turn cut
+     * short, its commands ended, its question unanswered, and, for one read
+     * back live, an `end` so the next read finds it stopped too.
+     */
+    stopped(replayed: Replayed): Promise<void>;
+    /** Appends `entry`, with whatever else is written before the next save. */
+    write(entry: Entry): void;
+    /** Settles once everything written so far is in the file. */
+    flush(): Promise<void>;
+    /** Deletes the file, once the last save has reached it. */
+    remove(): Promise<void>;
+}
+/** What a log read back says of its conversation, beyond its state. */
+export interface Replayed {
+    state: ConversationState;
+    /** The agent's session, once it opened one. */
+    session: string | null;
+    /** Explicit requested model, including failed selections. */
+    model: string | null;
+    /** Original session directory, independent of task moves. */
+    sessionCwd: string | null;
+    /** Where it runs; null for a log too old to say. */
+    cwd: string | null;
+    /** Its settings as last set, by id, for the resumed session to match. */
+    picks: Record<string, string>;
+    /** Its process, still running on a worker; null once it is gone. */
+    live: Live | null;
+    /** Whether the log says a turn is running. */
+    running: boolean;
+    /** When the log last said anything happened; null for one that never did. */
+    last: string | null;
+}
+/** What a log read back live says of the process to take back. */
+export interface Live {
+    handle: ProcessHandle;
+    /** The last frame the log holds, past which the worker's replay carries on. */
+    held: number;
+    /** The highest request id this side sent, past which the next stream numbers its own. */
+    lastId: number;
+    /** The prompt request still open, by its id; null when no turn waits on one. */
+    prompt: number | null;
+    /** What the agent is asking, and the request id to answer it on, when known; null for nothing. */
+    ask: {
+        rpc: acp.JsonRpcId | null;
+        ask: Ask;
+    } | null;
+    /** Whether the agent takes a prompt into its running turn. */
+    steers: boolean;
+    /** Whether the agent takes images in a prompt. */
+    sees: boolean;
+    /** Whether the agent has said a turn ended, so one it starts can end. */
+    tells: boolean;
+    /** Whether the agent says on its session list when a turn ends. */
+    follows: boolean;
+}
+/**
+ * A line of a conversation's log: what was said, in the order it was. Each
+ * carries the `seq` of the agent's frame being handled when it was written;
+ * missing before the first frame, and from older logs.
+ */
+export type Entry = Said & {
+    seq?: number;
+};
+type Said = {
+    kind: "start";
+    id: string;
+    agent: string;
+    task: string | null;
+    /** Where it runs; missing from logs written before resuming. */
+    cwd?: string;
+    /** The task's base; missing from logs written before parts nested. */
+    base?: string | null;
+    /** Who added the task; missing from logs written before tasks remembered it. */
+    caller?: string | null;
+    createdAt: string;
+    /** Missing from logs written before assignments were kept apart. */
+    assigned?: boolean;
+    /** Who handed it its task; missing for one nobody did. */
+    handedBy?: string;
+    /** The lane orchestrator that handed it its task; missing for one nobody did. */
+    startedBy?: string;
+    /** The project's splates skill version; missing when it had none, or before it was kept. */
+    skill?: string;
+} | {
+    kind: "session";
+    session: string;
+    cwd?: string;
+} | {
+    kind: "model-request";
+    model: string;
+}
+/** Moved into a task's worktree, or back to the main tree. */
+ | {
+    kind: "task";
+    task: string | null;
+    cwd: string;
+    /** The task's base; missing from logs written before parts nested. */
+    base?: string | null;
+    /** Who added the task; missing from logs written before tasks remembered it. */
+    caller?: string | null;
+}
+/** What the session offered and had set, kept so the next one can start alike. */
+ | {
+    kind: "settings";
+    settings: Setting[];
+}
+/** `at` is missing from logs written before older archived ones were deleted. */
+ | {
+    kind: "archive";
+    archived: boolean;
+    at?: string;
+    /** The conversation whose archiving took this one with it. */
+    with?: string;
+} | {
+    kind: "rename";
+    name: string | null;
+} | {
+    kind: "unread";
+    unread: boolean;
+} | {
+    kind: "pin";
+    pinned: boolean;
+} | {
+    kind: "parent";
+    parent: {
+        id: string | null;
+    };
+}
+/** `at` is missing from logs written before the page showed how long things took. */
+ | {
+    kind: "prompt";
+    text: string;
+    at?: string;
+    queued?: true;
+    steered?: true;
+    /** The conversation that said it with `splates tell`. */
+    told?: string;
+    /** Said into the mic; missing from logs written before the page said. */
+    dictated?: true;
+    /** The page's id for it; missing for an agent's word, or from older logs. */
+    id?: string;
+    /** Where the person said it on the page; missing for an agent's word, or from older logs. */
+    from?: Device;
+    /** Missing from logs written before the page sent images. */
+    images?: Image[];
+    /** Missing from logs written before the page sent other files. */
+    files?: Attached[];
+}
+/** Every queued prompt went out. */
+ | {
+    kind: "sent";
+    count?: number;
+    at?: string;
+}
+/** The person stopped the agent's turn. */
+ | {
+    kind: "stopped";
+    at: string;
+}
+/** The agent's turn ended early, its connection lost or its process gone. */
+ | {
+    kind: "interrupted";
+    at: string;
+}
+/** A turn started or ended, so one a dead process left running shows as cut short. */
+ | {
+    kind: "turn";
+    running: boolean;
+    at?: string;
+} | {
+    kind: "observed-turn";
+    turn: ObservedTurn;
+}
+/** The `index`th queued prompt was taken back. */
+ | {
+    kind: "unqueue";
+    index: number;
+}
+/** Where a checkpoint stands, and what comes after it. */
+ | {
+    kind: "checkpoint";
+    checkpoint: Checkpoint | null;
+} | {
+    kind: "update";
+    update: acp.SessionUpdate;
+    at?: string;
+}
+/** The tokens a turn used, as the agent said when it ended. */
+ | {
+    kind: "usage";
+    usage: acp.Usage;
+}
+/** The plan's windows, as asked of an agent that does not send them. */
+ | {
+    kind: "limits";
+    limits: Limit[];
+}
+/** What a finished command did to git that it should not have. */
+ | {
+    kind: "flags";
+    tool: string;
+    flags: Flag[];
+}
+/** How the person answered the agent asking permission for a tool call. */
+ | {
+    kind: "decision";
+    tool: string;
+    decision: Decision;
+}
+/** An artifact added, removed, or its bytes deleted. */
+ | {
+    kind: "artifact";
+    change: ArtifactChange;
+}
+/**
+ * The agent's session is open on a process a worker runs, which a
+ * coordinator started again takes back by `handle`, until `end`.
+ */
+ | {
+    kind: "launched";
+    handle: ProcessHandle;
+    /** Whether the agent takes a prompt into its running turn. */
+    steers: boolean;
+    /** Whether the agent takes images in a prompt. */
+    sees: boolean;
+    /** Whether the agent says on its session list when a turn ends; missing from older logs. */
+    follows?: boolean;
+}
+/** A request this side sent the agent, by the id it went out with. */
+ | {
+    kind: "request";
+    id: number;
+    method: string;
+}
+/** What the agent asks the person, by the request id `rpc` to answer on, when known; null once answered. */
+ | {
+    kind: "ask";
+    rpc: acp.JsonRpcId | null;
+    ask: Ask;
+} | {
+    kind: "ask";
+    ask: null;
+}
+/** Word of a command the agent left running in the background. */
+ | {
+    kind: "background";
+    update: AsyncTaskUpdate;
+} | {
+    kind: "end";
+    error: string | null;
+};
+export {};

package/conversation-messages.d.ts

@@ -0,0 +1,18 @@
+import type { Attached, Image, Message, Sent } from "./conversation-state.js";
+/** What the person said, `at`: what they sent with it, then their words. */
+export declare function said(text: string, at: string | null, sent?: Sent[]): Message;
+/** How many of `messages` went out, as the thread shows them. */
+export declare function sent(messages: Message[]): number;
+/** A prompt entry's images and files, each left out of the log when there are none. */
+export declare function shown(sent: Sent[]): {
+    images?: Image[];
+    files?: Attached[];
+};
+/** The words of `message`, without what was sent with them. */
+export declare function textOf(message: Message): string;
+/** Marks up to `count` queued messages as gone out, all by default. */
+export declare function delivered(messages: Message[], count?: number, at?: string): void;
+/** Removes the `index`th queued message, returning it if there was one. */
+export declare function takeBack(messages: Message[], index: number): Message | null;
+/** What an error says, whether it is an `Error` or only shaped like one. */
+export declare function messageOf(error: unknown): string;

package/conversation-name.d.ts

@@ -0,0 +1,28 @@
+import type { ConversationState } from "./conversations.js";
+import type { LaneRecord } from "./lanes.js";
+/**
+ * What a conversation goes by: its real name (see `realName`), else a
+ * stand-in until it has one: the first line of what the person first said,
+ * else "Not started".
+ */
+export declare function nameOf(conversation: ConversationState, lanes: readonly LaneRecord[]): string;
+/**
+ * The name a conversation has earned, or null: the name the person gave it,
+ * else the lanes it was started on, so an orchestrator's follows a lane's
+ * renames and keeps them through a todo it does itself, else the task its
+ * agent holds, so it follows the agent from task to task, or held last, so a
+ * finished task keeps its name until the agent takes another, else the
+ * agent's title.
+ */
+export declare function realName(conversation: ConversationState, lanes: readonly LaneRecord[]): string | null;
+/**
+ * Whether a conversation goes by the task its agent holds or held last, as
+ * `nameOf` names it.
+ */
+export declare function namedForTask(conversation: ConversationState): boolean;
+/** What each `[SPLATES LANE ...]` the person's first words start with names. */
+export declare function lanesOf(conversation: ConversationState): string[];
+/** The lanes each Started card `conversation`'s agent said names. */
+export declare function startedLanes(conversation: ConversationState): string[];
+/** The first line the person said in a conversation, or null before they say any. */
+export declare function openingOf(conversation: ConversationState): string | null;

package/conversation-options.d.ts

@@ -0,0 +1,73 @@
+import type { IdProvider } from "webappwiz/id";
+import type { Fs, Lock } from "webappwiz/system";
+import type { Timer, WallClock } from "webappwiz/time";
+import type { Adherence } from "./adherence.js";
+import type { Agent, Launch, Launcher } from "./agent-process.js";
+import type { ArtifactLimits } from "./artifacts.js";
+import type { ProjectRoster } from "./conversation-host.js";
+import type { Limit } from "./conversation-state.js";
+import type { Limits } from "./limits.js";
+import type { Offered } from "./offered.js";
+import type { Outcomes } from "./outcomes.js";
+import type { SessionServers } from "./shared-browser.js";
+import type { Watch } from "./watch.js";
+import type { WorkerMachine } from "./worker-machine.js";
+export interface ConversationsOptions {
+    fs?: Fs;
+    /** How many bytes of artifacts each may keep; `ARTIFACT_LIMITS` by default. */
+    artifacts?: ArtifactLimits;
+    ids?: IdProvider;
+    /** What starts agents, when nothing takes one back after a restart; this process by default. */
+    launch?: Launch;
+    /** What starts agents and takes them back after a restart, over `launch`: a worker. */
+    launcher?: Launcher;
+    /**
+     * Where agents run, which their background output is read from; this
+     * machine by default.
+     */
+    machine?: WorkerMachine;
+    /**
+     * Held while each agent starts, shared by every project's conversations
+     * so no two start at once; one of their own by default.
+     */
+    starting?: Lock;
+    timer?: Timer;
+    clock?: WallClock;
+    /** What watches the agents' commands for what they do to git; none by default. */
+    watch?: Watch | null;
+    /** Where what each agent's sessions offer is kept across projects; nowhere by default. */
+    offered?: Offered | null;
+    /** Where each agent's plan limits are kept across projects; nowhere by default. */
+    limits?: Limits | null;
+    /**
+     * Where how each conversation followed the splates skill is kept across
+     * projects, judged as each turn ends; nowhere by default.
+     */
+    adherence?: Adherence | null;
+    /**
+     * Where how each task ended is kept across projects, credited with the
+     * turn it ended in once that turn ends; nowhere by default.
+     */
+    outcomes?: Outcomes | null;
+    /**
+     * Asks an agent that does not send its plan's windows for them, after
+     * each of its turns; none by default.
+     */
+    readLimits?: ((agent: Agent) => Promise<Limit[]>) | null;
+    /**
+     * The main tree, where a conversation carries on once its task's worktree
+     * is gone, as when the task landed while `splates server` was not there to hear
+     * of it; without it, such a conversation cannot resume.
+     */
+    root?: string | null;
+    /**
+     * The splates projects on this machine, for a prompt's `#slug` to name one
+     * by; none by default.
+     */
+    projects?: ProjectRoster | null;
+    /**
+     * The MCP servers each session is offered, beyond the agent's own, shared
+     * across projects like the browser they serve; none by default.
+     */
+    servers?: SessionServers | null;
+}

package/conversation-reference.d.ts

@@ -0,0 +1,2 @@
+/** Whether a # reference names a conversation by its stable UUID. */
+export declare function conversationReference(called: string): boolean;