@stringsync/splates 0.0.0-stage → 0.0.45

package/worker-protocol.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Turns frames into what a `WorkerSocket` carries and back, and settles which
+ * version two ends speak. A `WorkerSession` uses it for every frame; reach for
+ * it directly only to speak the protocol without one.
+ */
+export declare class WorkerProtocol {
+    private constructor();
+    /** The version this end speaks, sent in every hello and welcome. */
+    static readonly version = "1.0";
+    static readonly headerBytes = 8;
+    static encode(frame: Frame): string | Uint8Array;
+    /** Throws on anything that is not a frame, which ends the connection. */
+    static decode(encoded: string | Uint8Array): Frame;
+    /**
+     * Settles on the lower minor and the capabilities both ends have; another
+     * major cannot be read, so it is refused with a reason the coordinator
+     * shows when it drains that worker.
+     */
+    static negotiate(ours: {
+        protocol: string;
+        capabilities: string[];
+    }, theirs: {
+        protocol: string;
+        capabilities: string[];
+    }): Negotiated;
+}
+/** A JSON value, as control frames carry them. */
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+/** Each channel's last seq one end holds, as `[channel, seq]` pairs. */
+export type Held = [channel: number, seq: number][];
+/**
+ * Every frame on the link between a coordinator and a worker. Those naming a
+ * `channel` carry its seq and are kept until acked, so they survive a
+ * reconnect; the rest belong to one connection and are never replayed.
+ */
+export type Frame = {
+    type: "hello";
+    protocol: string;
+    capabilities: string[];
+    id: string;
+    info: {
+        [key: string]: Json;
+    };
+    /** The worker session's id, new each time a worker starts. */
+    session: string;
+    held: Held;
+} | {
+    type: "welcome";
+    protocol: string;
+    capabilities: string[];
+    /** The coordinator session's id, new each time a coordinator starts. */
+    session: string;
+    held: Held;
+} | {
+    type: "refuse";
+    reason: string;
+} | {
+    type: "open";
+    channel: number;
+    seq: number;
+    kind: string;
+    params: Json;
+} | {
+    type: "message";
+    channel: number;
+    seq: number;
+    body: Json;
+} | {
+    type: "data";
+    channel: number;
+    seq: number;
+    bytes: Uint8Array;
+} | {
+    type: "close";
+    channel: number;
+    seq: number;
+} | {
+    type: "ack";
+    acks: Held;
+} | {
+    type: "ping";
+    n: number;
+} | {
+    type: "pong";
+    n: number;
+};
+/** A frame that belongs to a channel, so it has a seq and is replayed. */
+export type ChannelFrame = Extract<Frame, {
+    channel: number;
+}>;
+/** What one end makes of the other's version, from its hello or welcome. */
+export type Negotiated = {
+    ok: true;
+    protocol: string;
+    capabilities: string[];
+}
+/** `refused` when the other end turned this one away, rather than the link going. */
+ | {
+    ok: false;
+    reason: string;
+    refused: boolean;
+};

package/worker-pty-host.d.ts

@@ -0,0 +1,34 @@
+import type { Resource } from "webappwiz/disposable";
+import type { Ps } from "webappwiz/system";
+import { z } from "zod";
+import type { WorkerChannel } from "./worker-channel.js";
+/** What a coordinator opens a `pty` channel with. */
+export declare const PtyParams: z.ZodObject<{
+    argv: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+/** How much of what the shell last wrote is kept, to redraw a terminal that comes back. */
+export declare const SCREEN_BYTES: number;
+/**
+ * One shell a `pty` channel started on the worker, for a page's terminal:
+ * the terminal's bytes both ways, a resize as a message, and its pid and
+ * exit code as messages back. It keeps the last `SCREEN_BYTES` the shell
+ * wrote, and says its pid and writes them again when asked to `describe`
+ * itself, for a terminal taken back after a coordinator restart, or a page
+ * come back to it. Closing the channel hangs it up.
+ */
+export declare class WorkerPtyHost implements Resource {
+    readonly channel: WorkerChannel;
+    private readonly pty;
+    /** What the shell last wrote, oldest first, `SCREEN_BYTES` at most in all. */
+    private readonly screen;
+    private screenBytes;
+    constructor(channel: WorkerChannel, ps: Ps);
+    /** Says the pid again, then writes the screen kept, to redraw a terminal that came back. */
+    private describe;
+    private keep;
+    dispose(): void;
+}

package/worker-registry.d.ts

@@ -0,0 +1,68 @@
+import type { Resource } from "webappwiz/disposable";
+import { type Eventful } from "webappwiz/events";
+import type { Logger } from "webappwiz/log";
+import { type Clock, Duration, type Timer, type WallClock } from "webappwiz/time";
+import { RemoteWorker, type WorkerKind } from "./remote-worker.js";
+import { type WorkerSessionOptions } from "./worker-session.js";
+import type { WorkerSocket } from "./worker-socket.js";
+/** A worker turned away, and why, so the coordinator can drain it. */
+export interface RefusedWorker {
+    id: string;
+    protocol: string;
+    reason: string;
+}
+/** What a `WorkerRegistry` hears. */
+export interface WorkerRegistryEvents extends Record<string, unknown> {
+    /** A worker connected, for the first time or again. */
+    joined: RemoteWorker;
+    refused: RefusedWorker;
+}
+/** How a `WorkerRegistry` paces the sessions it keeps. */
+export interface WorkerRegistryOptions {
+    /** How long a new connection has to say hello. */
+    helloWithin?: Duration;
+    session?: Omit<WorkerSessionOptions, "timer" | "clock" | "wall" | "capabilities">;
+    timer?: Timer;
+    clock?: Clock;
+    wall?: WallClock;
+}
+/**
+ * The coordinator's roster of workers, in memory for now: it takes each
+ * connection, on whatever transport, reads its hello, and resumes the session
+ * of a worker it knows by its id, so what it was running carries on.
+ */
+export declare class WorkerRegistry implements Eventful<WorkerRegistryEvents>, Resource {
+    private readonly log;
+    private readonly opts;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<WorkerRegistryEvents>;
+    private readonly byId;
+    private readonly refusals;
+    private readonly timer;
+    private readonly clock;
+    private readonly wall;
+    constructor(log: Logger, opts?: WorkerRegistryOptions);
+    get workers(): RemoteWorker[];
+    /** Workers turned away for another major, by id, last word first. */
+    get refused(): RefusedWorker[];
+    worker(id: string): RemoteWorker | undefined;
+    /**
+     * The worker known by `id`, made now if it has yet to join, so work can be
+     * given it before it does: its session keeps what it is sent until then.
+     * `kind` is how it will connect.
+     */
+    expect(id: string, kind?: WorkerKind): RemoteWorker;
+    /**
+     * Takes a worker's new connection, hanging up on one that says nothing in
+     * time. `kind` is how it reached us: `local` over this machine's socket.
+     */
+    accept(socket: WorkerSocket, kind?: WorkerKind): Promise<void>;
+    /**
+     * Hangs up on every worker for a restart, keeping what each runs for
+     * the next run to take back, once each holds everything it was sent, or
+     * `ACK_WAIT` is up.
+     */
+    detach(): Promise<void>;
+    private session;
+    dispose(): void;
+}

package/worker-replay.d.ts

@@ -0,0 +1,25 @@
+import type { ChannelFrame, Held } from "./worker-protocol.js";
+/**
+ * The channel frames one end has sent and the other has yet to ack, kept to
+ * send again on a reconnect. Its bound is in bytes: past it, `keep` still
+ * keeps the frame, so nothing is lost, but says the writer should stop.
+ */
+export declare class WorkerReplay {
+    readonly limit: number;
+    private readonly channels;
+    private nextOrder;
+    private _bytes;
+    constructor(limit: number);
+    get bytes(): number;
+    get full(): boolean;
+    /** Keeps a frame until acked, and says whether there is room for more. */
+    keep(frame: ChannelFrame, encoded: string | Uint8Array): boolean;
+    /** Lets go of every frame, for an other end that will never ack them. */
+    clear(): void;
+    /** Lets go of `channel`'s frames, once both ends have closed it: nothing will ask for them. */
+    drop(channel: number): void;
+    /** Drops every frame of each channel up to the seq the other end holds. */
+    ack(acks: Held): void;
+    /** Every frame still kept, in the order it was first sent. */
+    unacked(): (string | Uint8Array)[];
+}

package/worker-run.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+/** Where the local worker finds the coordinator on this machine. */
+export declare function workerSocketPath(ps: Ps): string;
+/** What `splates worker run` is run with. */
+export interface WorkerRunOptions {
+    /** Empty for this machine's coordinator, a URL for another's, or `unix:<path>`. */
+    coordinator: string;
+    slots: number;
+    id: string;
+    log: Logger;
+    ps: Ps;
+    fs: Fs;
+}
+/**
+ * `splates worker run`: a worker that serves its coordinator until a SIGINT
+ * or SIGTERM, or until the coordinator refuses it for speaking another
+ * protocol, which is a refusal to update one or the other.
+ */
+export declare function workerRun(opts: WorkerRunOptions): Promise<void>;

package/worker-session.d.ts

@@ -0,0 +1,189 @@
+import { type Resource } from "webappwiz/disposable";
+import { type Eventful } from "webappwiz/events";
+import { type Clock, Duration, type Timer, type WallClock } from "webappwiz/time";
+import { WorkerChannel } from "./worker-channel.js";
+import { type Frame, type Json, type Negotiated } from "./worker-protocol.js";
+import type { WorkerSocket } from "./worker-socket.js";
+/** A worker's hello, which the coordinator reads to pick its session. */
+export type WorkerHello = Extract<Frame, {
+    type: "hello";
+}>;
+/** What a `WorkerSession` hears. */
+export interface WorkerSessionEvents extends Record<string, unknown> {
+    /** The other end opened a channel. */
+    channel: WorkerChannel;
+    /** A handshake settled, and what the other end missed has been sent again. */
+    connected: undefined;
+    /** The connection went, by hang-up, missed heartbeats or a bad frame; channels stay. */
+    lost: {
+        reason: string;
+    };
+    /** Acks brought unacked bytes back under the bound: writers may go on. */
+    drain: undefined;
+    /** The other end acked something; `acked()` waits on it. */
+    acked: undefined;
+}
+/** How a `WorkerSession` paces and bounds itself. */
+export interface WorkerSessionOptions {
+    /**
+     * What its hello or welcome names it by: the id a coordinator started
+     * again answers as, so its worker finds it unchanged and keeps every
+     * channel; new by default.
+     */
+    id?: string;
+    capabilities?: string[];
+    /** Unacked bytes kept for replay before writes return `false`. */
+    bufferBytes?: number;
+    /** How often each end pings the other. */
+    heartbeat?: Duration;
+    /** How long without a frame before the other end counts as gone. */
+    timeout?: Duration;
+    /** How long acks gather before they go, so a burst costs one ack. */
+    ackDelay?: Duration;
+    /**
+     * `delivery` acks data and messages once listeners have them; `manual`
+     * waits for `WorkerChannel.ack`, for an end that must first write them
+     * down. Opens and closes are acked on arrival either way.
+     */
+    acks?: "delivery" | "manual";
+    timer?: Timer;
+    clock?: Clock;
+    /** Stamps `lastHeard`. */
+    wall?: WallClock;
+}
+/**
+ * One end of the link between a coordinator and a worker, the same code on
+ * both. It outlives any one connection: channels stay open across a
+ * reconnect, every channel frame is kept until the other end acks it, and a
+ * new connection replays what was not acked, in order, once.
+ */
+export declare class WorkerSession implements Eventful<WorkerSessionEvents>, Resource {
+    readonly role: "worker" | "coordinator";
+    /** What its hello or welcome names it by, so the other end can tell one started again. */
+    readonly id: string;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<WorkerSessionEvents>;
+    private readonly channels;
+    private readonly replay;
+    private readonly sent;
+    private readonly received;
+    /** Channels taken back without knowing where the other end's replay starts: its first frame says. */
+    private readonly unplaced;
+    /** Channels taken back from the session this one resumes, until the first handshake says the other end holds them. */
+    private readonly taken;
+    /**
+     * What was sent on a taken channel before that handshake, which says
+     * where its seqs carry on from: numbered and sent then.
+     */
+    private readonly deferred;
+    private readonly held;
+    private readonly pendingAcks;
+    /** Channels both ends closed, kept until a pong proves the other end has their ack. */
+    private readonly forgetting;
+    private readonly capabilities;
+    private readonly heartbeat;
+    private readonly timeout;
+    private readonly ackDelay;
+    private readonly acks;
+    private readonly timer;
+    private readonly clock;
+    private readonly wall;
+    private readonly link;
+    private connection;
+    private nextChannel;
+    private nextPing;
+    private wasFull;
+    private _negotiated;
+    private _lastHeard;
+    private disposed;
+    /** Hung up for a restart: its channels live on at the other end, for the next session to take back. */
+    private detached;
+    /** Made with an id, so the other end may hold channels of the session it resumes. */
+    private readonly resumed;
+    /** The other end's session at the last handshake; null before the first. */
+    private peer;
+    constructor(role: "worker" | "coordinator", opts?: WorkerSessionOptions);
+    /**
+     * Reads the first frame of a new connection, which must be a worker's
+     * hello, so the coordinator can pick the session it resumes.
+     */
+    static hello(socket: WorkerSocket): Promise<WorkerHello>;
+    /** What the last handshake settled on, once there has been one. */
+    get negotiated(): Negotiated | undefined;
+    /** When any frame last came from the other end, in epoch milliseconds; null before the first. */
+    get lastHeard(): number | null;
+    get connected(): boolean;
+    /** False while unacked bytes are at the bound; `drain` says when that ends. */
+    get writable(): boolean;
+    /** Settles once writes may go on: at once, or at the next `drain`. */
+    drained(): Promise<void>;
+    /** Opens a channel to the other end, which hears it as `channel`. */
+    open(kind: string, params?: Json): WorkerChannel;
+    /**
+     * Takes back channel `id`, which the other end still holds from the
+     * session this one resumes, before the handshake: `held` is the last seq
+     * of the other end's this end has, which its replay then follows, or null
+     * to take the replay from wherever it starts. What this end sends on it
+     * carries on from what the other end's hello says it received.
+     */
+    resume(id: number, kind: string, params: Json, held: number | null): WorkerChannel;
+    /**
+     * The worker's side of a handshake: says hello on `socket`, and on welcome
+     * replays what the coordinator does not hold. Resolves with what was
+     * negotiated, or why not: refused for another major, or the link went.
+     */
+    connect(socket: WorkerSocket, hello: {
+        id: string;
+        info?: {
+            [key: string]: Json;
+        };
+    }): Promise<Negotiated>;
+    /**
+     * The coordinator's side of a handshake, given the hello
+     * `WorkerSession.hello` read: welcomes the worker and replays what it
+     * does not hold, or refuses one on another major, hanging up, so the
+     * coordinator can drain it with the reason.
+     */
+    accept(socket: WorkerSocket, hello: WorkerHello): Negotiated;
+    /**
+     * What the worker's hello says it holds of the channels of the session
+     * this one resumes, at its first handshake: this end sends on each from
+     * past that, opens new ones past them all, and closes those nobody took
+     * back, which ends what they ran. One taken back that the worker does
+     * not hold, as after the worker too started again, ends here.
+     */
+    private takeBack;
+    /**
+     * Hangs up for a restart, keeping every channel open at the other end:
+     * a session with this id takes them back once it comes up.
+     */
+    detach(): void;
+    /** Settles once the other end has acked everything sent, or at once with nothing out. */
+    acked(): Promise<void>;
+    /** Hangs up and closes every channel; the other end hears them close. */
+    dispose(): void;
+    private attach;
+    private go;
+    private hear;
+    private handshake;
+    private receive;
+    /** Holds `frame` for the handshake that says what seq it goes out as. */
+    private defer;
+    private sendOnChannel;
+    private nextSeq;
+    private ack;
+    private flushAcks;
+    private acknowledged;
+    /**
+     * Ends every channel at this end, for another end started again, which
+     * knows none of them: what they ran stops, as when the old one hung up.
+     */
+    private forget;
+    private channelDone;
+    private ponged;
+    private beat;
+    private write;
+    private lose;
+    private assertRole;
+    private assertOpen;
+}

package/worker-socket.d.ts

@@ -0,0 +1,15 @@
+import type { Resource } from "webappwiz/disposable";
+import type { Eventful } from "webappwiz/events";
+/** What a `WorkerSocket` hears: one whole frame, or that it is gone. */
+export interface WorkerSocketEvents extends Record<string, unknown> {
+    frame: string | Uint8Array;
+    close: undefined;
+}
+/**
+ * One connection between a coordinator and a worker, carrying whole frames in
+ * order: a WebSocket as it is, or a Unix socket behind length-prefixed
+ * framing. Disposing it hangs up, and both ends then hear `close`.
+ */
+export interface WorkerSocket extends Eventful<WorkerSocketEvents>, Resource {
+    send(frame: string | Uint8Array): void;
+}

package/worktree-service.d.ts

@@ -0,0 +1,113 @@
+import { type Fs, type Ps } from "webappwiz/system";
+import type { Adherence } from "./adherence.js";
+import { Attachments } from "./attachments.js";
+import type { Config } from "./config.js";
+import type { Git, GitResult } from "./git.js";
+import { type Outcomes } from "./outcomes.js";
+import { type DiscardOptions, type TaskState, Worktree } from "./worktree.js";
+export interface AddOptions {
+    /** Branch the new worktree starts from. Defaults to the trunk. */
+    base?: string;
+}
+/**
+ * Where tasks live and everything persistent about them: the worktree
+ * directories, the records under `.git/splates/tasks`, and the names of tasks
+ * already removed. One name, one lookup, whatever state it turns out to be in.
+ */
+/** What a `WorktreeService` works through; the real ones by default. */
+export interface WorktreeServiceOptions {
+    fs?: Fs;
+    ps?: Ps;
+    /** Where each task's ending is written down; none, and nothing is. */
+    outcomes?: Outcomes;
+    /** How closely conversations follow the skill, which an ending's findings read. */
+    adherence?: Adherence;
+}
+export declare class WorktreeService {
+    readonly git: Git;
+    readonly config: Config;
+    private readonly tasksDir;
+    private readonly removedDir;
+    private readonly conversationsDir;
+    private readonly fs;
+    private readonly outcomes;
+    private readonly adherence;
+    readonly ps: Ps;
+    constructor(git: Git, config: Config, splatesDir: string, opts?: WorktreeServiceOptions);
+    /**
+     * The `splates server` conversation whose agent runs this command, when it is
+     * one of this repo's: an agent from another project's page working here
+     * is, to this repo, an agent outside the page.
+     */
+    conversation(): Promise<string | undefined>;
+    /** Where the log of the conversation `id` is kept. */
+    conversationLog(id: string): string;
+    /** Whether the `splates server` conversation `id` is one of this repo's. */
+    holds(id: string): Promise<boolean>;
+    init(): Promise<void>;
+    get trunk(): string;
+    /** Where a task's worktree lives: a sibling of the repo, never inside it. */
+    pathFor(task: string): string;
+    branchFor(task: string): string;
+    taskFor(branch: string | null): string | null;
+    recordPath(task: string): string;
+    /**
+     * Where a task's files live, beside its record: the screenshots and videos
+     * its questions show, in `tasks/<task>/`. They go when the task does.
+     */
+    files(task: string): Attachments;
+    /**
+     * Where a task's files live when it attaches them from `conversation`:
+     * beside that conversation's artifacts, in `attached/<task>/`, so they
+     * outlive the task and a merged card's images still show.
+     */
+    attached(conversation: string, task: string): Attachments;
+    /**
+     * Every folder holding files `task` attached: its own, and one in each
+     * conversation that attached some.
+     */
+    filesOf(task: string): Promise<Attachments[]>;
+    /**
+     * The bytes `conversation` keeps on disk, its artifacts and attached
+     * files, which together are held to `artifactConversationCapacity`.
+     */
+    conversationBytes(conversation: string): Promise<number>;
+    /**
+     * Whether `path` is a file some task or conversation holds for a task:
+     * one level inside a task's folder, or inside a conversation's
+     * `attached/<task>/`, never a record or log, and not a way out of here.
+     */
+    owns(path: string): boolean;
+    /** Always answers; the returned worktree's status says what was found. */
+    find(task: string): Promise<Worktree>;
+    list(): Promise<Worktree[]>;
+    /** Adds the branch and the working directory. The record comes after. */
+    add(task: string, { base }?: AddOptions): Promise<GitResult>;
+    discard(worktree: Worktree, ended: "merged" | "removed", opts?: DiscardOptions): Promise<GitResult>;
+    /** Writes a task's record. A concurrent reader sees the old one or the new. */
+    saveRecord(state: TaskState): Promise<void>;
+    /**
+     * Writes down how a task with a record ended. One with none, a stray
+     * branch or a bare directory, never ran as a task, so says nothing.
+     */
+    /**
+     * What a task leaves to read as it ends: its plan's questions, and the
+     * systems its changes fall in, by the config in its own tree.
+     */
+    private ending;
+    private recordOutcome;
+    private readRecord;
+    /**
+     * Drops the files of every task with no record left: what a process that
+     * died between discarding a task and clearing its folder left behind.
+     */
+    private sweep;
+    private removedPath;
+    private removedAt;
+    /**
+     * Remembers a removed name so a second `remove` can say "already removed"
+     * instead of "never existed", then drops the oldest so the list of
+     * remembered names cannot grow without bound.
+     */
+    private rememberRemoved;
+}