@stringsync/splates 0.0.60 → 1.13.3

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

@@ -0,0 +1,420 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import { type Eventful } from "../../../core/events/index.js";
+import type { Agent, ProcessHandle } from "../agents";
+import { Artifacts } from "../artifacts";
+import type { ConversationDeps, ConversationEvents, ConversationHost } from "./host";
+import { ConversationLog } from "./log";
+import { type Answer, type Attached, type AutoPickSet, type ConversationState, type Device, type Limit, type QueueSpot, type Upload } from "./state";
+import { type PromptOptions } from "./turns";
+/**
+ * One conversation with one agent. Live, it holds the agent's process; read
+ * back from its log, it is what was said, and resumes on the next prompt.
+ */
+export declare class Conversation implements Eventful<ConversationEvents>, Resource, ConversationHost {
+    readonly state: ConversationState;
+    readonly log: ConversationLog;
+    private readonly deps;
+    /** What to run to resume it; null when its agent is no longer known. */
+    private ran;
+    /** Where it runs; null for a log too old to say. */
+    private dir;
+    private readonly dispatcher;
+    readonly events: import("../../../core/events/index.js").Events<ConversationEvents>;
+    private readonly files;
+    /** The files its agent kept as its outputs, read and changed here. */
+    readonly artifacts: Artifacts;
+    private readonly connection;
+    private readonly turns;
+    private readonly background;
+    /** Under way while the agent starts or comes back, for a prompt to wait on. */
+    opening: Promise<void> | null;
+    /** Stops the agent once it has sat idle `IDLE_STOP`; null while it works. */
+    private resting;
+    /** Set when it left its task's worktree mid-turn: stop once the turn ends. */
+    private leftWorktree;
+    /** Says `[SPLATES RECONNECT]` once its wait is up; null while none is due. */
+    private reconnecting;
+    /** How many times in a row it has reconnected by itself. */
+    private reconnects;
+    /** Let go of its process for a restart: nothing here ends it now. */
+    private detached;
+    /**
+     * Read back with what was said while it started still unheard, the
+     * server having gone down first: `sayUnsaid` starts it again to say it.
+     */
+    private unsaid;
+    /** The place its agent holds on a worker; null while it has none. */
+    private grant;
+    /** Takes its agent out of the queue for a place; null while it waits in none. */
+    private placing;
+    /**
+     * Lets a held one go, to open its agent, or not, once stopped; null
+     * while it is not held.
+     */
+    private latch;
+    /**
+     * What its next prompt is to follow, for an agent taken off a worker
+     * while idle: its new session knows nothing of the task. Null for none.
+     */
+    private carry;
+    /**
+     * The question its agent was asking when a drain freed its place, kept
+     * on the page for the person to answer (`free`); null for none.
+     */
+    private kept;
+    /** Stops hearing of workers that start draining; null with no placer. */
+    private readonly unlistenDrain;
+    private constructor();
+    /**
+     * A conversation as its log at `key` left it: stopped, whatever it was
+     * doing, unless its agent still runs on a worker, which the launcher
+     * takes back, and the conversation carries on where the log leaves off.
+     */
+    static read(key: string, agents: Agent[], deps: ConversationDeps): Promise<Conversation | null>;
+    /**
+     * The agent `live` names, taken back on the worker it runs on, holding
+     * its place there; null when nothing here runs it any more, stopped as
+     * any dead process is.
+     */
+    private static takeBack;
+    /** Starts `agent` in `cwd` and opens a session with it. */
+    static start({ settings, model, picking, ...opening }: Opening & {
+        /** Values to set, by setting id, once the session offers them. */
+        settings?: Record<string, string>;
+        /**
+         * The model to pick, by its value or name in the session's model
+         * setting, over what `settings` says. An unavailable choice fails.
+         */
+        model?: string;
+        /**
+         * What Auto pick decides, once it has, to open on in place of
+         * `agent`, `settings` and `model`, which it shows meanwhile.
+         */
+        picking?: Promise<Picked>;
+    }, deps: ConversationDeps): Promise<Conversation>;
+    /**
+     * Brings in `session`, one `agent` holds outside splates, such as from its
+     * CLI: loads it in `cwd`, writing what the agent replays of it to a new
+     * log, from which it resumes like any other.
+     */
+    static bring({ session, title, ...opening }: Opening & {
+        session: string;
+        /** What the agent listed it as, until the replay says otherwise. */
+        title: string | null;
+    }, deps: ConversationDeps): Promise<Conversation>;
+    /** A new conversation with `agent` in `cwd`, its log begun, not yet opened. */
+    private static begin;
+    get id(): string;
+    /** What runs it; null when its agent is no longer known. */
+    get agent(): Agent | null;
+    /** Whether the agent takes images, as it said connecting; null while not connected. */
+    get sees(): boolean | null;
+    /** The agent's pid while it runs, for the commands it left running. */
+    get pid(): number | null;
+    /**
+     * The handle for reattaching after a server restart, or null when
+     * this process cannot survive a restart.
+     */
+    get handle(): ProcessHandle | null;
+    /** The agent's session, once it has opened one. */
+    get sessionId(): string | null;
+    /** Where it runs; null for a log too old to say. */
+    get cwd(): string | null;
+    /**
+     * When it was archived, or when it started for a log too old to say; null
+     * while it is not archived.
+     */
+    get archivedSince(): string | null;
+    /** Whether a checkpoint has ended and nothing has been said since. */
+    get stoppedByCheckpoint(): boolean;
+    now(): string;
+    /** Says `text` to the agent, with `files` (see `ConversationTurns`). */
+    prompt(text: string, files?: Upload[], from?: Device, opts?: PromptOptions): Promise<void>;
+    /** Takes back the `index`th queued message, answering with its words and files. */
+    unqueue(index: number): {
+        text: string;
+        files: Attached[];
+    };
+    /** Sends what is queued now, stopping the running turn first. */
+    sendNow(): Promise<void>;
+    /** Stops the agent's turn for the person, and stays open for the next. */
+    cancel(): Promise<void>;
+    /**
+     * Asks the agent to bring its `SPLATES.md` up to date and stop (see
+     * `ConversationTurns`), for `budget`, a worker budget hard stop's reason,
+     * when that is what asks.
+     */
+    checkpoint(merging: boolean, budget?: string | null): Promise<void>;
+    /**
+     * Checkpoints the agent for the person, as `checkpoint` does, and leaves
+     * it stopped there: nothing resumes a pause, and Power leaves it alone.
+     */
+    pause(merging: boolean): Promise<void>;
+    /** Forgets the checkpoint, done or not, so the next starts afresh. */
+    dismissCheckpoint(): void;
+    /** Settles once the checkpoint asked is no longer under way. */
+    answered(): Promise<void>;
+    /**
+     * Settles the agent's pending ask, if `id` is still the one it is on.
+     * One kept from an agent a drain freed carries it on instead, the
+     * answer said as the person's words after its task (`free`).
+     */
+    answer(id: string, answer: Answer): void;
+    /** The file `name` the person sent, or null when they sent none by that name. */
+    attachment(name: string): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+    /** Keeps the plan's windows in `limits`, asked of the agent's maker. */
+    hear(limits: Limit[]): void;
+    /** Stops background command `id`, leaving the agent's turn as it is. */
+    stopBackground(id: string): Promise<void>;
+    /** What background command `id` has printed, then more as it prints it. */
+    backgroundOutput(id: string): ReadableStream<Uint8Array>;
+    /**
+     * Sets the session's setting `id` to `value`, one the agent offers: at once
+     * while the agent runs, or, while it is stopped, when it next resumes.
+     */
+    choose(id: string, value: string): Promise<void>;
+    /** Keeps what Auto pick set it to, as it started. */
+    autoPicked(pick: AutoPickSet): void;
+    /**
+     * Switches Auto pick `on` for its model and effort, to judge what the
+     * person says next, or off, leaving them as they are.
+     */
+    switchAutoPick(on: boolean): void;
+    lift(settings: Record<string, string>, pick: AutoPickSet): Promise<void>;
+    /**
+     * Brings a stopped conversation back: a new process, the same session, or
+     * a new one when its agent died before opening one.
+     */
+    resume(): Promise<void>;
+    /**
+     * Follows the agent into a task's worktree, or back to the main tree.
+     * A running session stays where it opened; a resumed one opens in the new.
+     */
+    move(task: string | null, cwd: string, base?: string | null, caller?: string | null): void;
+    /**
+     * Holds it for its queued task, out of the line for a place, until
+     * `release` gives it the task: what is said to it meanwhile waits for
+     * its agent, as while any agent starts. A stopped one, as a held one
+     * reads back after a restart, is held again; one held already, or under
+     * way, is left as it is.
+     */
+    hold(): void;
+    /** Whether it is held for its queued task now (`hold`). */
+    get held(): boolean;
+    /**
+     * Gives a held one its task, the queue having started it in `cwd`: it
+     * follows the task there and takes its place in the line for a place.
+     */
+    release(task: string, cwd: string, base?: string | null, caller?: string | null): void;
+    /** Keeps where a held one stands in the queue of tasks, as the queue says it. */
+    waitsAt(spot: QueueSpot): void;
+    /** Lets a held one go, to open its agent or to stop. */
+    private letGo;
+    /** Stops the agent; the next prompt resumes where it left off. */
+    stop({ idle }?: {
+        idle?: boolean;
+    }): Promise<void>;
+    /**
+     * Stops it as the server goes down. One still starting, as while it
+     * waits for a place, keeps that unsaid, with whatever was said to it yet
+     * to reach its agent, so the next run starts it again and says it, as
+     * though the server had stayed up.
+     */
+    shutDown(): Promise<void>;
+    /**
+     * Starts it again when it was read back with what was said while it
+     * started still unheard (`shutDown`), saying it once the session opens;
+     * one read back any other way waits for the person.
+     */
+    sayUnsaid(): void;
+    /** Stops the agent, leaving what it was told `unsaid` for the next run or not. */
+    private halt;
+    /** Keeps `picks`, to set once the session opens, through a restart before it does. */
+    private request;
+    /**
+     * Moves its agent to a new worker once the one it ran on is gone, as a
+     * forced remove or a drain does, so the task carries on from its last
+     * checkpoint. One in no task stays stopped.
+     */
+    requeue(): Promise<void>;
+    /**
+     * Starts its agent again in a new session on its task, for one stuck or
+     * dead there: the old session ends, and the new one is told to claim the
+     * task, with what the old one said last kept for it to read.
+     */
+    restart(): Promise<void>;
+    /** Keeps what was said so far for another agent to read, answering where it opens. */
+    keepTranscript(): Promise<string>;
+    /**
+     * Lets go of its task for another agent to take on: stops its agent and
+     * moves it to the main tree, where it resumes if prompted again, and
+     * answers the prompt that has the next agent claim the task, with what
+     * this one said last kept for it to read.
+     */
+    handOff(): Promise<string>;
+    /** Its task, for `doing` that needs one; refused when it is in none. */
+    private onTask;
+    /**
+     * Lets go of the place of an agent asking the person something on a
+     * worker that drains, rather than keep the worker up until they answer,
+     * which may be hours: ends it, its worktree left as it stands, and keeps
+     * its question on the page. The answer, or whatever the person says
+     * instead, places it again in a new session, told `[SPLATES TASK <task>]`
+     * first, as `requeue` does for an idle one. One in no task has nothing
+     * to carry on from, so it keeps its place until answered.
+     */
+    private free;
+    /**
+     * Moves its agent off a worker being replaced, at its next pause, so the
+     * worker can update without waiting on the person: one asking does as
+     * `free` says; one idle, nothing running in the background, ends and
+     * frees its place, and the person's next words place it again in a new
+     * session told `[SPLATES TASK <task>]` first, as `requeue` does for an
+     * idle one. One at work moves once its turn ends. One in no task has
+     * nothing to carry on from, so it keeps its place until it ends.
+     */
+    private moveOff;
+    /** Lets go of the question kept by `free`, its session gone. */
+    private unkeep;
+    /**
+     * Lets go of the agent's process without ending it, for a server
+     * started again to take back from the worker: its log, flushed, says
+     * where it stopped. Answers whether there was one to let go of; a
+     * conversation with none, or one nothing could take back, stops as ever.
+     */
+    detach(): Promise<boolean>;
+    /**
+     * Stops it and puts it away, off the list of conversations; `with`, the
+     * conversation whose archiving takes it along, which brings it back;
+     * `rest`, a persistent agent's run ended with its role still on.
+     * Its artifacts keep only what their panel shows.
+     */
+    archive(withConversation?: string, { rest }?: {
+        rest?: boolean;
+    }): Promise<void>;
+    /** Names it `name` over the agent's title; blank goes back to the title. */
+    rename(name: string): Promise<void>;
+    /** Back on the list, stopped until the next prompt. */
+    unarchive(): Promise<void>;
+    /** Keeps it atop the list, or lets it go back among the rest. */
+    pin(pinned: boolean): Promise<void>;
+    /**
+     * Nests it in the list under the conversation `id`, or at the top for
+     * null, over where its task would, cutting it loose from the conversation
+     * that started it or added its task: that one no longer tells it, hears
+     * from it, or archives it along. Never for a subagent, which stays with
+     * the one it answers to.
+     */
+    reparent(id: string | null): Promise<void>;
+    /** Settles once everything said so far is in its log, for a reader of the file. */
+    saved(): Promise<void>;
+    /** Marks it seen, or unseen again for the person to come back to. */
+    markUnread(unread: boolean): Promise<void>;
+    /**
+     * Keeps that the person has read `read` of its messages, never fewer than
+     * before nor more than went out.
+     */
+    markRead(read: number): Promise<void>;
+    /** Stops it and deletes its log and files, for good. */
+    delete(): Promise<void>;
+    dispose(): void;
+    /** Marks it `unread` or not, keeping how much was seen when it was read. */
+    flag(unread: boolean): void;
+    /** Marks whether a run its eval card started is going. */
+    evaluate(running: boolean): void;
+    /** Back to idle once a turn ends, then on to what was queued meanwhile. */
+    ended(error: string | null): void;
+    /**
+     * Ends the agent's process, with `error` for one that failed, and keeps
+     * that it stopped, and whether what it was told is left `unsaid`, for the
+     * next run to say.
+     */
+    close(error: string | null, { unsaid, idle }?: {
+        unsaid?: boolean;
+        idle?: boolean;
+    }): Promise<void>;
+    /**
+     * Carries on with the turn a lost connection cut short, as the page's
+     * Reconnect button would, once `RECONNECT_WAIT` is up: a worker that comes
+     * back without the agent's process loses it just as it reconnects. After
+     * `RECONNECTS` tries in a row with no turn ending between them, the
+     * button is left to the person.
+     */
+    private reconnect;
+    set(next: Partial<ConversationState>): void;
+    changed(): void;
+    /**
+     * Stops an agent left idle `IDLE_STOP`, with no command running in the background,
+     * no question open and no checkpoint, so its process exits and takes what
+     * it started along, MCP servers and browsers included. The next prompt
+     * resumes the same session.
+     */
+    private rest;
+    /** Whether `dir` is still there. */
+    private there;
+    /**
+     * Opens on what Auto pick decides once it has, or, when the pick fails,
+     * on what the conversation started on; opens nothing when it was stopped
+     * meanwhile. The model is asked for only now, so a log read back mid-pick
+     * asks for none the pick may not keep.
+     */
+    private pick;
+    /**
+     * Opens the agent in `cwd` once it has a place, clearing `opening` once it
+     * has, failed to, or was stopped while it waited for one.
+     */
+    private wake;
+    /**
+     * Waits in the queue for a worker for its agent, keeping where it waits
+     * in its state: its placement on the worker it was placed on, undefined
+     * with no queue, or null once a stop takes it out of line. An automatic
+     * one also waits while starts are paused; the person's own wait only
+     * while no worker they can run on is up.
+     */
+    private place;
+    /** Keeps where its agent waits for a place, saying so only when that changed. */
+    private queued;
+}
+/** What a conversation is opened with, started afresh or brought in. */
+interface Opening {
+    id: string;
+    agent: Agent;
+    task: string | null;
+    /** The branch `task` was cut from. */
+    base?: string | null;
+    /** The conversation whose agent added `task`. */
+    caller?: string | null;
+    cwd: string;
+    /** Runs projectless in its own scratch workspace. */
+    scratch?: boolean;
+    /** Started on what a queued task or `splates add --agent` assigned. */
+    assigned?: boolean;
+    /** The lane orchestrator that handed it its task, which hears when it stops. */
+    startedBy?: string | null;
+    /** Whether the server's queue or a hook starts it, so it waits while starts are paused. */
+    automatic?: boolean;
+    /** The project's splates skill version as it starts; null when it has none. */
+    skill?: string | null;
+    /** The queued task it is held for until the queue starts it (`hold`). */
+    heldForTask?: number;
+    /** What to call it until its agent names it. */
+    title?: string | null;
+    /** The persistent agent's role it is started for, as `"groomer"`. */
+    persistent?: string;
+    /** The automation that starts it, by its id. */
+    automation?: string;
+    /** The ship whose adoption task it runs, by its id. */
+    ship?: string;
+}
+/** What Auto pick decided for a conversation to open on, its agent as `A` names it. */
+export interface Picked<A = Agent> {
+    agent: A;
+    /** The model to pick, as `Conversation.start` takes it; none for the agent's default. */
+    model?: string;
+    /** Values to set, by setting id, once the session offers them. */
+    settings: Record<string, string>;
+}
+export {};

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

@@ -0,0 +1,181 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import { type Eventful } from "../../../core/events/index.js";
+import { type Agent, type Session } from "../agents";
+import { Conversation, type Picked } from "./conversation";
+import type { ConversationsEvents, Lift } from "./host";
+import type { ConversationsOptions } from "./options";
+import type { Limit, Setting } from "./state";
+/** How many archived conversations are kept; older archived ones are deleted. */
+export declare const ARCHIVED_KEPT = 200;
+/**
+ * Every conversation in the repo: the live ones this process started, and
+ * the stopped ones read back from their logs.
+ */
+export declare class Conversations implements Eventful<ConversationsEvents>, Resource {
+    readonly dir: string;
+    readonly agents: Agent[];
+    private readonly dispatcher;
+    readonly events: import("../../../core/events/index.js").Events<ConversationsEvents>;
+    private readonly known;
+    private readonly fs;
+    private readonly kimiHome;
+    /** Where the conversations are kept, each log `<id>.jsonl` in it. */
+    private readonly storage;
+    private readonly ids;
+    private readonly launcher;
+    private readonly placer;
+    private readonly machine;
+    private readonly starting;
+    private readonly timer;
+    private readonly clock;
+    private readonly watch;
+    private readonly offered;
+    private readonly limited;
+    private readonly adherence;
+    private readonly outcomes;
+    private readonly spend;
+    private readonly readLimits;
+    private readonly root;
+    private readonly projects;
+    private readonly servers;
+    private readonly artifacts;
+    /** What every conversation's artifacts make room through, across the project. */
+    private readonly room;
+    /** The read of the records on disk, shared by every caller until it settles. */
+    private loaded;
+    /** The last deletion of archived conversations past `ARCHIVED_KEPT`, so they run one at a time. */
+    private pruning;
+    /** When each agent's limits were last asked for, by its id, in epoch ms. */
+    private readonly asked;
+    /** Where `splates server` answers, once it does, for the agents' CLI. */
+    url: string | null;
+    /** What looks again at what the person says in a conversation Auto pick started; null for nothing. */
+    lift: Lift | null;
+    /** Replaces the agents new conversations can start with; running ones keep theirs. */
+    refreshRoster(agents: Agent[]): void;
+    constructor(dir: string, agents: Agent[], opts?: ConversationsOptions);
+    /** What each conversation is made with. */
+    private get deps();
+    /**
+     * What each agent's sessions last offered, from any project, by its id:
+     * what a first conversation with one shows before it starts.
+     */
+    settings(): Promise<Record<string, Setting[]>>;
+    /** Whether each agent that connected here last said it takes images. */
+    sights(): Promise<Record<string, boolean>>;
+    /**
+     * Saves `value` as what `agent`'s new conversations start with for its
+     * setting `id`, one the agent offers, as picked before any is started.
+     */
+    chooseDefault(agent: string, id: string, value: string): Promise<void>;
+    /**
+     * Each agent's plan limits as it last said, from any project, by its id:
+     * what a new conversation shows before one here says.
+     */
+    limits(): Promise<Record<string, Limit[]>>;
+    /**
+     * Asks each agent that does not send its limits for them, unless it was
+     * asked within `LIMITS_FRESH`, and keeps what it says for every project.
+     */
+    refreshLimits(): Promise<void>;
+    /** Every conversation, newest first. */
+    list(): Promise<Conversation[]>;
+    /**
+     * The newest conversation started for persistent agent `role`, archived
+     * or not, or null before one started.
+     */
+    persistent(role: string): Promise<Conversation | null>;
+    /** `id`, as a page picked it for a new conversation: a UUID none has. */
+    private unused;
+    find(id: string): Promise<Conversation>;
+    /**
+     * Starts a conversation with `agent` in `cwd`, for `task` if it is one's,
+     * with `settings` set once the session offers them; for `queued`, held
+     * for that queued task until the queue starts it.
+     */
+    start(agent: string, { id: given, task, base, caller, cwd, scratch, settings, model, assigned, startedBy, automatic, heldForTask, title, persistent, automation, ship, picking, }: {
+        /**
+         * The id the page picked, so it opens the conversation before the
+         * server answers; a new one when not given.
+         */
+        id?: string;
+        task: string | null;
+        /** The branch `task` was cut from. */
+        base?: string | null;
+        /** The conversation whose agent added `task`. */
+        caller?: string | null;
+        cwd: string | ((id: string) => string | Promise<string>);
+        /** Runs projectless in its own scratch workspace. */
+        scratch?: boolean;
+        settings?: Record<string, string>;
+        /** The model to start on, by its value or name in the model setting. */
+        model?: string;
+        /** Whether a queued task or `splates add --agent` assigned the agent and model. */
+        assigned?: boolean;
+        /** The lane orchestrator that handed it its task, which hears when it stops. */
+        startedBy?: string | null;
+        /** Whether the server's queue or a hook starts it, to hold a place on a worker. */
+        automatic?: boolean;
+        /** The queued task it is held for, its agent unopened until `release`. */
+        heldForTask?: number;
+        /** What to call it until its agent names it. */
+        title?: string;
+        /** The persistent agent's role it is started for, as `"groomer"`. */
+        persistent?: string;
+        /** The automation that starts it, by its id. */
+        automation?: string;
+        /** The ship whose adoption task it runs, by its id. */
+        ship?: string;
+        /**
+         * What Auto pick decides, once it has, to open on in place of
+         * `agent`, `model` and `settings`, which it shows meanwhile.
+         */
+        picking?: Promise<Picked<string>>;
+    }): Promise<Conversation>;
+    /** The agent `id` names, failing for one splates does not run. */
+    private agentOf;
+    /**
+     * The sessions each agent holds in `cwd` that splates does not, such as ones
+     * started in its CLI, to bring in: newest first, from every agent that
+     * lists and loads sessions.
+     */
+    sessions(cwd: string): Promise<Session[]>;
+    /**
+     * Brings in `session`, one `agent` holds outside splates, as a conversation
+     * in `cwd`, for `task` if it is one's.
+     */
+    bring(agent: string, session: string, { task, base, caller, cwd, title, }: {
+        task: string | null;
+        /** The branch `task` was cut from. */
+        base?: string | null;
+        /** The conversation whose agent added `task`. */
+        caller?: string | null;
+        cwd: string;
+        title?: string | null;
+    }): Promise<Conversation>;
+    /**
+     * Deletes the archived conversations past the `ARCHIVED_KEPT` archived
+     * most recently, so their logs do not pile up, their artifacts and
+     * attached files going with them.
+     */
+    prune(): Promise<void>;
+    /**
+     * Stops every live conversation, so no agent outlives the server; one
+     * still starting says what it was told once the next run reads it back.
+     */
+    disposeAsync(): Promise<void>;
+    /**
+     * Lets go of every agent a worker runs, for a server started again
+     * to take back, and says whether there was any: the rest stop as ever.
+     */
+    detachAsync(): Promise<boolean>;
+    dispose(): void;
+    private track;
+    /** Asks for `conversation`'s agent's limits, when it does not send them. */
+    private askLimits;
+    /** Takes in the logs written since it read them, as an import adds, leaving each it holds as it is. */
+    reread(): Promise<void>;
+    private load;
+    private trim;
+    private read;
+}