@stringsync/splates 0.0.0-stage → 0.0.45

package/agent-connection.d.ts

@@ -0,0 +1,171 @@
+import * as acp from "@agentclientprotocol/sdk";
+import type { Agent, AgentProcess, ProcessHandle } from "./agent-process.js";
+import type { ConversationDeps, ConversationHost } from "./conversation-host.js";
+import type { Live } from "./conversation-log.js";
+import type { Answer, Setting } from "./conversation-state.js";
+/**
+ * A conversation's side of ACP: the agent's process and the connection to
+ * it, what the agent asks of this side, routed to the person, and the calls
+ * the conversation makes on it. Opened anew each time the agent starts or
+ * comes back, with the same session, or reattached to a process a worker
+ * kept running while the coordinator restarted.
+ */
+export declare class AgentConnection {
+    private readonly host;
+    private readonly deps;
+    private connection;
+    private process;
+    private stream;
+    /** What listens on the stream and the log while they are up. */
+    private listening;
+    /** How many times `open` has run, so a start that fails late knows it is still the latest. */
+    private opens;
+    /** The agent's session, once it has opened one. */
+    private session;
+    /** Settles the agent's pending ask with the person's answer. */
+    private settle;
+    /** Whether the agent takes a prompt into its running turn. */
+    private steering;
+    /**
+     * Whether the running turn is on its final answer: a prompt steered in
+     * now may find it ended, and the agent start a turn of its own for it.
+     */
+    private finishing;
+    /** Whether the agent takes images in a prompt. */
+    private seeing;
+    /** Whether the turn running is one the agent started, with no prompt to end it. */
+    private unprompted;
+    /** Whether the agent has said a turn ended, as Claude does, so one it starts can end. */
+    private tells;
+    /** Whether the agent says on its session list when a turn ends, as Codex does. */
+    private follows;
+    /**
+     * The turn the agent started for a steer, as Codex does when its turn
+     * ended on the way: when splates heard of it, in ms, and whether the
+     * session list has said since that it runs.
+     */
+    private following;
+    /** Settles once the agent has answered the last steer, which may have started a turn of its own. */
+    private steered;
+    /** The commands running, by tool call, each watched since it started. */
+    private readonly watching;
+    /** Whether the next open loads the session, replaying it, rather than resuming it. */
+    private loading;
+    /** The person's words the replay has said so far, not yet logged as a prompt. */
+    private heard;
+    /** Recovery loads replay history already in the log. */
+    private suppressReplay;
+    /** Settings picked before the session opened, set once it has. */
+    private picks;
+    /** The model asked for before the session opened, picked once it has. */
+    private model;
+    private sessionCwd;
+    constructor(host: ConversationHost, deps: ConversationDeps, { session, loading, picks, model, sessionCwd, }?: {
+        session?: string | null;
+        /** Whether the first open loads `session`, replaying it, rather than resuming it. */
+        loading?: boolean;
+        picks?: Record<string, string>;
+        model?: string | null;
+        sessionCwd?: string | null;
+    });
+    /** The agent's pid while it runs, for the commands it left running. */
+    get pid(): number | null;
+    /** What takes the agent's process back after a restart; null while none could. */
+    get handle(): ProcessHandle | null;
+    get sessionId(): string | null;
+    /** Whether the agent's process is up and speaking ACP. */
+    get connected(): boolean;
+    /** Whether the agent takes a prompt into its running turn, as it stands. */
+    get canSteer(): boolean;
+    /** Whether the agent takes images in a prompt. */
+    get sees(): boolean;
+    /** Whether the agent is waiting on the person for an answer. */
+    get asking(): boolean;
+    /**
+     * Runs the agent and opens a session with it: the one this conversation
+     * had, when there was one, else a new one.
+     */
+    open(agent: Agent, cwd: string): Promise<void>;
+    /**
+     * Speaks ACP again to `process`, which a worker kept running while the
+     * coordinator restarted, where the log left off: `live` says what was in
+     * flight. A late answer to the prompt it was on ends the turn, and the
+     * question it was asking is answered on the request it came in.
+     */
+    reattach(agent: Agent, process: AgentProcess, live: Live): void;
+    /**
+     * Releases the running agent for the next coordinator to reconnect.
+     * Flush the conversation log after awaiting this before shutting down.
+     */
+    detach(): Promise<void>;
+    /**
+     * Opens ACP over `process`, which from here is the one this conversation
+     * runs: its frames stamp the log, its exit closes the conversation, and
+     * the worker is acked for each frame once the log holds it.
+     */
+    private attach;
+    /** What `process` said on stderr if it exits within `DEATH_WAIT`, else null. */
+    private diedSaying;
+    /**
+     * Waits for no other agent to be starting, answering with what lets the
+     * next one start: once this one's process is up, has died, or has had
+     * `START_WAIT` to answer, so one that hangs holds up no other for long.
+     */
+    private startAlone;
+    /** Says `prompt` to the agent as a turn, settling with what it answered once the turn ends. */
+    prompt(prompt: acp.ContentBlock[]): Promise<acp.PromptResponse | undefined>;
+    /** Whether the agent runs a turn it started for a steer, which no prompt's answer ends. */
+    get detached(): boolean;
+    /** A stale or substituted choice must never reach a prompt or steering call. */
+    private validateModel;
+    /**
+     * Says `prompt` into the turn the agent is running, answering with what
+     * came of it: `injected`, `startedNewTurn`, or `promptRequired` when the
+     * turn ended on the way.
+     */
+    steer(prompt: acp.ContentBlock[]): Promise<string | undefined>;
+    private steerInto;
+    /** Shows the turn the agent started for a steer as running, until it ends. */
+    private follow;
+    /**
+     * Ends the turn being followed once the session list says it no longer
+     * runs. A row read before it started can come after `startedNewTurn`,
+     * saying the turn before it ended: it counts only once a row has said the
+     * turn runs, or when it ended past the second splates heard it start in,
+     * since the agent says when in whole seconds.
+     */
+    private listed;
+    /** Stops the agent's turn, if it is connected. */
+    cancel(): Promise<void>;
+    /** Stops background command `id`; the agent says it ended as it does. */
+    stopTask(id: string): Promise<void>;
+    /**
+     * Sets `setting` to `value`, answering with the session's settings as the
+     * agent then offers them: at once while it is connected, or, while it is
+     * not, as picked for when it next opens.
+     */
+    choose(setting: Setting, value: string): Promise<Setting[]>;
+    /** Settles the agent's pending ask, if `id` is still the one it is on. */
+    answer(id: string, answer: Answer): void;
+    /** Ends the process, dismissing whatever the agent was asking. */
+    close(): void;
+    /** What the agent may ask of this side, all of it routed to the person. */
+    private client;
+    /**
+     * Watches each command the agent runs from when it starts, and keeps what
+     * it did to git that it should not have once it ends.
+     */
+    private watchCommand;
+    /** Logs the person's words the replay has said, as one prompt. */
+    private logHeard;
+    /** Keeps how the person answered the permission asked for tool call `id`. */
+    private decided;
+    /**
+     * Holds `asked` until the person answers it, or the turn is cancelled,
+     * logged with the request it came in, so a coordinator started again can
+     * answer it there.
+     */
+    private ask;
+    /** Settles the pending ask, if any, with `answer`, and logs that it is answered. */
+    private settled;
+}

package/agent-errors.d.ts

@@ -0,0 +1,2 @@
+/** Redacts common credential-bearing diagnostics before persistence or display. */
+export declare function agentError(message: string): string;

package/agent-process.d.ts

@@ -0,0 +1,65 @@
+import { type Timer } from "webappwiz/time";
+/** An agent splates can hold a conversation with over ACP, and how to start it. */
+export interface Agent {
+    id: string;
+    name: string;
+    argv: string[];
+}
+/** What a process wrote to stdout, numbered from 1 so a restart can say what it holds. */
+export interface AgentFrame {
+    bytes: Uint8Array;
+    seq: number;
+}
+/** What finds a process again after a restart: the worker it runs on and its channel there. */
+export interface ProcessHandle {
+    worker: string;
+    channel: number;
+}
+/** A running agent: bytes in, frames out, and a way to stop it. */
+export interface AgentProcess {
+    /** Its pid, for what runs under it; null for one that never started. */
+    pid: number | null;
+    input: WritableStream<Uint8Array>;
+    output: ReadableStream<AgentFrame>;
+    /**
+     * Says everything up to frame `seq` is written down, so a restart replays
+     * from past it; nothing to do for a process that ends with this one.
+     */
+    ack(seq: number): void;
+    /** What takes it back after a restart; null for one that ends with this process. */
+    handle: ProcessHandle | null;
+    /** What it last wrote to stderr, for when it dies before saying why. */
+    stderr(): string;
+    exited: Promise<number>;
+    kill(): void;
+}
+/** `bytes` as frames, numbered from 1 as they come. */
+export declare function framed(bytes: ReadableStream<Uint8Array>): ReadableStream<AgentFrame>;
+/** Starts `argv` in `cwd`, with `env` added to its own, its stdio piped. */
+export type Launch = (argv: string[], cwd: string, env: Record<string, string>) => AgentProcess;
+/** What starts a conversation's agent, and takes one back after a restart. */
+export interface Launcher {
+    launch: Launch;
+    /**
+     * The process `handle` names, kept running while this coordinator was
+     * away, its output carrying on from past frame `held`, the last one the
+     * log holds. Throws when nothing here can take it back.
+     */
+    resume(handle: ProcessHandle, held: number): AgentProcess;
+}
+/** `launch` alone, for a process that ends with this one: nothing takes one back. */
+export declare function launcherOf(launch: Launch): Launcher;
+export declare const launch: Launch;
+/** A session an agent holds that splates could bring in. */
+export interface Session {
+    agent: string;
+    session: string;
+    title: string | null;
+    /** When it was last active, as the agent says; null when it does not. */
+    updatedAt: string | null;
+}
+/**
+ * The sessions `agent` holds in `cwd`, asked of a process of its own that
+ * stops once it answers; none when it cannot both list and load them.
+ */
+export declare function listSessions(agent: Agent, cwd: string, run: Launch, timer: Timer): Promise<Session[]>;

package/agent-stream.d.ts

@@ -0,0 +1,91 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import { type Eventful } from "webappwiz/events";
+import type { AgentProcess } from "./agent-process.js";
+/** What an `AgentStream` says beyond the messages it carries. */
+export interface AgentStreamEvents extends Record<string, unknown> {
+    /** A message of the frame with this seq is being handed over. */
+    handling: number;
+    /** Every message of the frame with this seq has been dispatched. */
+    dispatched: number;
+    /** A response to a request sent before this stream, by an id under its base. */
+    stale: acp.AnyResponse;
+    /** A request this side sent, by the id it went out with. */
+    request: {
+        id: number;
+        method: string;
+    };
+}
+export interface AgentStreamOptions {
+    /**
+     * Where this side's request ids start: after a restart, give one past the
+     * highest id the log holds, so a late answer to an old request comes
+     * back as `stale` rather than as an answer to a new one.
+     */
+    base?: number;
+}
+/**
+ * ACP over an agent's frames, for the SDK's connection to read and write. It
+ * hands over one message at a time and waits for the connection to have
+ * handled it before the next, so `seq` names the frame of the message being
+ * handled while its handler runs. Lines are held until a frame ends on a
+ * newline, so a replay from past `dispatched` starts at a line and repeats
+ * none.
+ */
+export declare class AgentStream implements acp.Stream, Eventful<AgentStreamEvents> {
+    private readonly process;
+    readonly readable: ReadableStream<acp.AnyMessage>;
+    readonly writable: WritableStream<acp.AnyMessage>;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<AgentStreamEvents>;
+    /** Added to every request id sent. */
+    readonly base: number;
+    private readonly frames;
+    private more;
+    private ended;
+    /** Text since the last frame that ended on a newline. */
+    private partial;
+    private _seq;
+    private _dispatched;
+    private _lastId;
+    private _asking;
+    /** Whether a frame has been handed over in part, which `detach` lets finish. */
+    private midFrame;
+    private detaching;
+    private writer;
+    private writing;
+    constructor(process: AgentProcess, { base }?: AgentStreamOptions);
+    /** The seq of the frame the message being handled came in, 0 before the first. */
+    get seq(): number;
+    /** The highest seq every message of whose frame has been handled. */
+    get dispatched(): number;
+    /** The id the last request this side sent went out with; null before the first. */
+    get lastId(): number | null;
+    /**
+     * The id of the agent's request being handled, for a handler to log
+     * what it is answering; null while the message being handled is not one.
+     */
+    get asking(): acp.JsonRpcId | null;
+    /**
+     * Stops handing messages over at the end of the frame being handled, so
+     * a log flushed after this holds whole frames only, and settles once it
+     * has: the frames after it stay with the process for the next stream.
+     */
+    detach(): Promise<void>;
+    /**
+     * Answers request `id` of the agent's as it was on the wire, for one a
+     * log holds from before this stream, which the connection never heard.
+     */
+    respond(id: acp.JsonRpcId, answer: {
+        result: unknown;
+    } | {
+        error: acp.ErrorResponse;
+    }): Promise<void>;
+    private read;
+    private pull;
+    private finish;
+    /** A response to this side's request, with the id it asked by; or null for one handed back as stale. */
+    private incoming;
+    private outgoing;
+    private send;
+    private input;
+}

package/agents.d.ts

@@ -0,0 +1,15 @@
+import { type Logger } from "webappwiz/log";
+import type { Roster } from "./roster.js";
+export interface AgentsOptions {
+    /** Print the roster as JSON instead of tables. */
+    json?: boolean;
+}
+/**
+ * The roster: each agent, how it starts, and its models with what each is
+ * good at and costs, for an orchestrator choosing whom to delegate to. Writes
+ * the defaults first when there is none, and says where, so they can be edited.
+ */
+export declare function agents({ roster, log }: {
+    roster: Roster;
+    log: Logger;
+}, { json }?: AgentsOptions): Promise<void>;

package/artifact-room.d.ts

@@ -0,0 +1,47 @@
+import type { Fs } from "webappwiz/system";
+import { type Artifacts, type ArtifactVersion } from "./artifacts.js";
+/**
+ * Room for artifacts across a project, which every conversation's store
+ * makes its adds through, one at a time. An add past the project's capacity
+ * first evicts the bytes of other versions, in `evictionOrder`, keeping
+ * their records as placeholders; when even all of them would not make room,
+ * it is refused and nothing goes. Files attached to conversations count
+ * toward the capacity but are never evicted: they serve the questions that
+ * show them.
+ */
+export declare class ArtifactRoom {
+    private readonly deps;
+    private queue;
+    constructor(deps: {
+        fs: Fs;
+        /** Where every conversation of the project keeps its files. */
+        dir: string;
+        /** How many bytes every conversation may keep together. */
+        capacity: number;
+        /** Every conversation's store, and whether it is archived. */
+        shelves: () => ArtifactShelf[];
+    });
+    /** Runs `work` once every add before it has finished. */
+    hold<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Evicts what it must for `bytes` more of the artifact `name` to fit, or
+     * refuses `too_large`, evicting nothing, when it cannot.
+     */
+    make(bytes: number, name: string): Promise<void>;
+}
+/** One conversation's store, as the room sees it. */
+export interface ArtifactShelf {
+    store: Artifacts;
+    archived: boolean;
+}
+/**
+ * Every version whose bytes are kept, in the order eviction takes them:
+ * removed and superseded ones of any conversation first, then the shown ones
+ * of archived conversations, then those of live ones; oldest first within
+ * each.
+ */
+export declare function evictionOrder(shelves: ArtifactShelf[]): {
+    store: Artifacts;
+    name: string;
+    version: ArtifactVersion;
+}[];

package/artifact-viewers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How the page shows an artifact of `mimeType`: an image or a recording in
+ * the lightbox, a page in a sandboxed frame, or null for one it only offers
+ * as a download, which the server sends as an attachment to match.
+ */
+export declare function viewerOf(mimeType: string): "image" | "video" | "page" | null;

package/artifact.d.ts

@@ -0,0 +1,30 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+import { type ArtifactVersion } from "./artifacts.js";
+import type { WorktreeService } from "./worktree-service.js";
+/** What `fetch` is used for here, so a test can stand in for it. */
+type Send = (url: string, init: RequestInit) => Promise<Response>;
+export interface ArtifactDeps {
+    service: WorktreeService;
+    log: Logger;
+    fs: Fs;
+    ps: Ps;
+    send?: Send;
+}
+/**
+ * Keeps `file` as the next version of the artifact of that name in the
+ * conversation `id`, through the `splates server` serving this repository when
+ * the agent has one in its env, so the page hears of it, else straight into
+ * the conversation's log.
+ */
+export declare function addArtifact(deps: ArtifactDeps, id: string, file: {
+    name: string;
+    bytes: Uint8Array;
+}): Promise<ArtifactVersion>;
+/** Marks the artifact `name` of conversation `id` removed; answers the version that was current. */
+export declare function removeArtifact(deps: ArtifactDeps, id: string, name: string): Promise<number>;
+/** Prints what the conversation `id` holds, or, given a `name`, that artifact's versions. */
+export declare function listArtifacts(deps: ArtifactDeps, id: string, name?: string): Promise<void>;
+/** The media type `name`'s extension says, else plain bytes. */
+export declare function mimeTypeOf(name: string): string;
+export {};

package/artifacts.d.ts

@@ -0,0 +1,161 @@
+import { type IdProvider } from "webappwiz/id";
+import type { Fs } from "webappwiz/system";
+import type { ArtifactRoom } from "./artifact-room.js";
+import type { Config } from "./config.js";
+/**
+ * A conversation's artifacts: their bytes, in `artifacts/` beside its log's
+ * other files, and their record, `held`, which each change goes to through
+ * `record` (the log, then the state) once its bytes are in place. One change
+ * at a time, so two adds of one name never take the same version.
+ */
+export declare class Artifacts {
+    private readonly deps;
+    /** Where the bytes are kept. */
+    readonly dir: string;
+    /** Where every conversation of the project keeps its files. */
+    private readonly conversations;
+    private readonly ids;
+    private queue;
+    constructor(
+    /** The conversation's log, whose files directory holds the artifacts. */
+    log: string, deps: {
+        fs: Fs;
+        now: () => string;
+        limits: ArtifactLimits;
+        ids?: IdProvider;
+        /** The record as it stands. */
+        held: () => Artifact[];
+        /** Keeps `change`, folding it into `held`. */
+        record: (change: ArtifactChange) => Promise<void>;
+        /**
+         * The project's room, which evicts what other versions it must
+         * for an add past the project's capacity; without it, as for a
+         * CLI that reaches no `splates server`, such an add is refused.
+         */
+        room?: ArtifactRoom;
+    });
+    /** The record as it stands. */
+    get held(): Artifact[];
+    /**
+     * Keeps `file` as the next version of the artifact named for it, listing
+     * it again if it was removed. Past the project's capacity, its room evicts
+     * what it can first; refuses one past any limit still `too_large`,
+     * changing nothing.
+     */
+    add(file: ArtifactFile): Promise<ArtifactVersion>;
+    /** Marks the artifact `name` removed, keeping every version's bytes for cleanup. */
+    remove(name: string): Promise<void>;
+    /**
+     * Deletes the bytes of `version` of the artifact `name`, saying `why`,
+     * and keeps its record, so it shows as a placeholder.
+     */
+    delete(name: string, version: number, why: ArtifactGone): Promise<void>;
+    /**
+     * Deletes the bytes of every version no longer shown, those of removed
+     * artifacts and those a later one superseded, as its conversation is
+     * archived: what stays is what its panel still lists.
+     */
+    archive(): Promise<void>;
+    /**
+     * The bytes and media type of `version` of the artifact `name`, its
+     * current one by default; null when there is no such version or its
+     * bytes are gone.
+     */
+    read(name: string, version?: number): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+    /**
+     * Refuses `file` when it has no name, or when it or this conversation
+     * would pass its limit; its size when it fits.
+     */
+    private admit;
+    /** Writes `file`'s bytes and records them as its name's next version. */
+    private keep;
+    /** Deletes `version`'s bytes and records that they went, and why. */
+    private drop;
+    /** The artifact `name`, refusing `not_found` when there is none. */
+    private find;
+    private serially;
+}
+/**
+ * A file an agent made as an output of its conversation, such as a
+ * screenshot, a recording or an HTML page, kept by name for the life of the
+ * conversation, whatever task it was made in. Adding the name again makes its
+ * next version. Its record stays for good, so one whose bytes went still
+ * shows as a placeholder.
+ */
+export interface Artifact {
+    name: string;
+    /** The `version` of the one shown; the newest, as added. */
+    current: number;
+    /** Every version, oldest first, numbered from 1. */
+    versions: ArtifactVersion[];
+    /** When it was removed, its versions kept until cleanup takes them; null while listed. */
+    removedAt: string | null;
+}
+/** One version of an artifact: what was added under its name at once. */
+export interface ArtifactVersion {
+    version: number;
+    /** Its file in the conversation's artifacts directory, named so none collide. */
+    file: string;
+    mimeType: string;
+    /** Its size. */
+    bytes: number;
+    addedAt: string;
+    /** When and why its bytes were deleted, its record kept; null while they are kept. */
+    gone: {
+        at: string;
+        why: ArtifactGone;
+    } | null;
+}
+/**
+ * Why a version's bytes went: its conversation was archived, the project ran
+ * past its cap, or the person deleted it.
+ */
+export type ArtifactGone = "archived" | "evicted" | "deleted";
+/** A change to a conversation's artifacts, as its log keeps it. */
+export type ArtifactChange = ({
+    type: "add";
+    name: string;
+} & Omit<ArtifactVersion, "version" | "gone">) | {
+    type: "remove";
+    name: string;
+    at: string;
+} | {
+    type: "gone";
+    name: string;
+    version: number;
+    at: string;
+    why: ArtifactGone;
+};
+/** A file to keep as an artifact, as the agent hands it over. */
+export interface ArtifactFile {
+    name: string;
+    mimeType: string;
+    bytes: Uint8Array;
+}
+/** How many bytes artifacts may take, each past which an add is refused. */
+export interface ArtifactLimits {
+    /** One file. */
+    file: number;
+    /** Every version one conversation keeps the bytes of. */
+    conversation: number;
+    /** Every version every conversation in the project keeps the bytes of. */
+    project: number;
+}
+/** What `splates.config.ts` leaves the limits at unless it says otherwise. */
+export declare const ARTIFACT_LIMITS: ArtifactLimits;
+/** The limits `config` sets. */
+export declare function artifactLimits(config: Pick<Config, "artifactFileCapacity" | "artifactConversationCapacity" | "artifactProjectCapacity">): ArtifactLimits;
+/** Folds `change` into `artifacts`, as live and as a log is read back. */
+export declare function applyArtifact(artifacts: Artifact[], change: ArtifactChange): void;
+/** Whether `version` is the one its artifact's panel shows: its current, while listed. */
+export declare function shown(artifact: Artifact, version: ArtifactVersion): boolean;
+/**
+ * How many bytes every conversation under `dir` keeps, read from disk: its
+ * artifacts' and the files attached to it.
+ */
+export declare function projectBytes(fs: Fs, dir: string): Promise<number>;
+/** Refuses an add that would have `what` hold `bytes`, past its `capacity`. */
+export declare function tooLarge(what: string, name: string, bytes: number, capacity: number): never;