@stringsync/splates 0.0.60 → 1.13.3

package/vendor/@stringsync/splates-server/workers/process.d.ts

@@ -0,0 +1,33 @@
+import { Duration } from "../../../core/time/index.js";
+import type { AgentFrame, AgentProcess, ProcessHandle } from "../agents";
+import type { WorkerChannel } from "./channel";
+import type { WorkerSession } from "./session";
+/** How long a worker has to say anything of a process taken back, once it rejoins. */
+export declare const ANSWER_WITHIN: Duration;
+/**
+ * A process running on a worker, seen from the server as any
+ * `AgentProcess` is: writing `input` is its stdin, `output` its stdout, each
+ * frame in the seq its channel gave it, acked back to the worker once written
+ * down. Its pid is null until the worker says it started; one taken back
+ * after a restart asks again, since the word came before.
+ */
+export declare class WorkerProcess implements AgentProcess {
+    private readonly channel;
+    private readonly worker;
+    readonly input: WritableStream<Uint8Array>;
+    readonly output: ReadableStream<AgentFrame>;
+    readonly exited: Promise<number>;
+    private _pid;
+    private tail;
+    /** What takes it back after a server restart. */
+    get handle(): ProcessHandle;
+    constructor(channel: WorkerChannel, session: WorkerSession, worker: string, { resumed, answerWithin, }?: {
+        resumed?: boolean;
+        /** How long a worker has to answer for a process taken back, once it rejoins. */
+        answerWithin?: Duration;
+    });
+    get pid(): number | null;
+    stderr(): string;
+    ack(seq: number): void;
+    kill(): void;
+}

package/vendor/@stringsync/splates-server/workers/protocol.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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.5";
+    static readonly headerBytes = 8;
+    /**
+     * The most one frame may hold, encoded. Each frame is one WebSocket
+     * message and a message past the receiver's limit closes the socket, so
+     * a larger one is split by whoever makes it, or refused at send.
+     */
+    static readonly maxFrameBytes: number;
+    /** The most a data frame carries; `write` splits what is longer. */
+    static readonly maxDataBytes: number;
+    /** What a server's WebSocket takes in a message, well above `maxFrameBytes`. */
+    static readonly maxPayloadBytes: number;
+    /** How many bytes `frame` takes encoded. */
+    static size(frame: Frame): number;
+    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 server
+     * shows when it drains that worker.
+     */
+    static negotiate(ours: {
+        protocol: string;
+        capabilities: string[];
+    }, theirs: {
+        protocol: string;
+        capabilities: string[];
+    }): Negotiated;
+}
+/** The capability of a worker that restarts on another build when its server sends `update`. */
+export declare const UPDATE = "update";
+/** The capability of a server that frees what a worker runs when the worker sends `leaving`, as a spot reclaim's notice does. */
+export declare const LEAVING = "leaving";
+/** 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 server 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;
+    /**
+     * The key it joined with, sent only after the server proved
+     * itself, for a worker that kept the server's public key.
+     */
+    key?: string;
+} | {
+    type: "welcome";
+    protocol: string;
+    capabilities: string[];
+    /** The server session's id, new each time a server starts. */
+    session: string;
+    held: Held;
+}
+/** A worker's first frame when it keeps the server's public key: asks it to sign `nonce`. */
+ | {
+    type: "challenge";
+    nonce: string;
+}
+/** The server's answer: its signature over the nonce and its `session`. */
+ | {
+    type: "proof";
+    session: string;
+    signature: string;
+} | {
+    type: "refuse";
+    reason: string;
+    /** The build the server runs, for a worker turned away for its major to restart on; absent from one before 1.3. */
+    update?: string;
+}
+/** Asks a worker that offers `update` to restart on the server's `build`, once nothing of its own runs on it. */
+ | {
+    type: "update";
+    build: string;
+}
+/** Tells the server the worker is about to be taken from under it, for it to carry its agents elsewhere at once. */
+ | {
+    type: "leaving";
+    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; `update`, the build a server that refused a worker
+ * runs, for the worker to restart on.
+ */
+ | {
+    ok: false;
+    reason: string;
+    refused: boolean;
+    update?: string;
+};

package/vendor/@stringsync/splates-server/workers/pty-host.d.ts

@@ -0,0 +1,35 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import type { Ps } from "../../../core/system/index.js";
+import { z } from "zod";
+import type { WorkerChannel } from "./channel";
+import type { WorkerSession } from "./session";
+/** What a server 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 server 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, session: Pick<WorkerSession, "drained">, 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/vendor/@stringsync/splates-server/workers/queue.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from "../../../core/log/index.js";
+import type { Fs, Ps } from "../../../core/system/index.js";
+import { type WallClock } from "../../../core/time/index.js";
+import type { QueueEntry } from "./scheduler";
+/** One agent waiting to start, as `GET /api/queue` and `splates worker queue list` give it. */
+export interface QueueListing {
+    /** Its conversation's id. */
+    id: string;
+    /** The main tree of its project. */
+    project: string;
+    task: string | null;
+    position: number;
+    /** When it joined the queue. */
+    since: string;
+    reason: string;
+}
+/** `entries` as `GET /api/queue` answers them. */
+export declare function queueListing(entries: QueueEntry[]): QueueListing[];
+/** What `splates worker queue` is run with. */
+export interface QueueOptions {
+    /** The `splates server` to ask; empty for the one this agent runs under. */
+    dev: string;
+    json: boolean;
+    log: Logger;
+    fs?: Fs;
+    ps: Ps;
+    send?: typeof fetch;
+    wall?: WallClock;
+}
+/** `splates worker queue list`: the agents waiting for a slot on the running `splates server`. */
+export declare function listQueue(opts: QueueOptions): Promise<void>;
+/**
+ * `splates worker queue move`: puts the agent waiting for `which`, a task or a
+ * conversation's id, at `position` in the queue, from 1.
+ */
+export declare function moveQueued(opts: QueueOptions & {
+    which: string;
+    position: number;
+}): Promise<void>;

package/vendor/@stringsync/splates-server/workers/records.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { Document } from "../storage";
+/** Settings for this machine's worker, kept across server restarts. */
+declare const Record: z.ZodObject<{
+    id: z.ZodString;
+    draining: z.ZodDefault<z.ZodBoolean>;
+    removing: z.ZodDefault<z.ZodBoolean>;
+    updating: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const Kept: z.ZodObject<{
+    workers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        draining: z.ZodDefault<z.ZodBoolean>;
+        removing: z.ZodDefault<z.ZodBoolean>;
+        updating: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    local: z.ZodDefault<z.ZodBoolean>;
+    paused: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+type KeptFile = z.output<typeof Kept>;
+export type WorkerRecord = z.output<typeof Record>;
+export type WorkerSettings = Partial<Omit<WorkerRecord, "id">>;
+/** Persists local worker settings, ignoring workers registered by older builds. */
+export declare class WorkerRecords {
+    private readonly document;
+    private kept;
+    private writing;
+    private constructor();
+    static open(document: Document<KeptFile>): Promise<WorkerRecords>;
+    static memory(): WorkerRecords;
+    get all(): WorkerRecord[];
+    of(id: string): WorkerRecord | undefined;
+    get localOn(): boolean;
+    turnLocal(on: boolean): Promise<void>;
+    /** Whether everything splates starts on its own waits, as `pause` set. */
+    get paused(): boolean;
+    pause(on: boolean): Promise<void>;
+    set(id: string, settings: WorkerSettings): Promise<WorkerRecord>;
+    /** Forgets worker `id`'s settings, as for a handoff worker once it has stopped. */
+    drop(id: string): Promise<void>;
+    private change;
+}
+export {};

package/vendor/@stringsync/splates-server/workers/registry.d.ts

@@ -0,0 +1,101 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import { type Eventful } from "../../../core/events/index.js";
+import type { Logger } from "../../../core/log/index.js";
+import { type Clock, Duration, type Timer, type WallClock } from "../../../core/time/index.js";
+import type { CoordinatorIdentity } from "./identity";
+import { type WorkerSessionOptions } from "./session";
+import type { WorkerSocket } from "./socket";
+import { type CallBounds, ConnectedWorker, type WorkerKind } from "./worker";
+/** A worker turned away, and why, so the server 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: ConnectedWorker;
+    refused: RefusedWorker;
+    /** A worker said its machine is about to be taken away. */
+    leaving: {
+        id: string;
+        reason: string;
+    };
+}
+/** How a `WorkerRegistry` paces the sessions it keeps. */
+export interface WorkerRegistryOptions {
+    /** How long a new connection has to say hello. */
+    helloWithin?: Duration;
+    /** How long each kind of call to a worker may go unanswered. */
+    calls?: Partial<CallBounds>;
+    session?: Omit<WorkerSessionOptions, "timer" | "clock" | "wall" | "capabilities">;
+    timer?: Timer;
+    clock?: Clock;
+    wall?: WallClock;
+    /** What proves this server to a worker that keeps its public key; none answers no challenge. */
+    identity?: CoordinatorIdentity;
+    /** Whether `key` is the one worker `id` joined with, for a worker that sends it in its hello. */
+    verify?: (id: string, key: string) => boolean;
+}
+/**
+ * The server'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("../../../core/events/index.js").Events<WorkerRegistryEvents>;
+    private readonly byId;
+    private readonly refusals;
+    private readonly timer;
+    private readonly clock;
+    private readonly wall;
+    /**
+     * Detached for a restart, or disposed: a worker that redials now is hung
+     * up on, since a fresh session's welcome would have it end everything it
+     * kept for the next run.
+     */
+    private closed;
+    /** What the server signs a worker's nonce with, new for each run unless its session is given. */
+    private readonly proofSession;
+    constructor(log: Logger, opts?: WorkerRegistryOptions);
+    get workers(): ConnectedWorker[];
+    /** Workers turned away for another major, by id, last word first. */
+    get refused(): RefusedWorker[];
+    worker(id: string): ConnectedWorker | 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): ConnectedWorker;
+    /**
+     * 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.
+     * `identity`, when a string, is the worker its key proved it to be, and a
+     * hello saying it is another is hung up on; when a function, it says
+     * which ids a hello may name, as this machine's socket takes its own
+     * workers alone; null, the worker proves
+     * itself in its hello, with the key it joined with, once it has had this
+     * server sign its nonce.
+     */
+    accept(socket: WorkerSocket, kind?: WorkerKind, identity?: string | null | ((id: string) => boolean)): Promise<void>;
+    /**
+     * Hangs up on worker `id` for good, ending what it runs, and forgets it;
+     * answers whether it was known.
+     */
+    forget(id: string): boolean;
+    /**
+     * 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 bounds;
+    private session;
+    private serve;
+    dispose(): void;
+}

package/vendor/@stringsync/splates-server/workers/replay.d.ts

@@ -0,0 +1,25 @@
+import type { ChannelFrame, Held } from "./protocol";
+/**
+ * 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/vendor/@stringsync/splates-server/workers/routes.d.ts

@@ -0,0 +1,119 @@
+import type { AsyncResource } from "../../../core/disposable/index.js";
+import type { Logger } from "../../../core/log/index.js";
+import type { Fs } from "../../../core/system/index.js";
+import { CoordinatorIdentity } from "./identity";
+import { LocalWorkerUpdate } from "./local-update";
+import { AgentPlacement } from "./placement";
+import { WorkerRecords } from "./records";
+import { WorkerRegistry } from "./registry";
+import type { ConnectedWorker } from "./worker";
+/** Accepts this machine's worker over its private Unix socket and places agents on it. */
+export declare class DevWorkers implements AsyncResource {
+    private readonly log;
+    readonly registry: WorkerRegistry;
+    readonly records: WorkerRecords;
+    /** What proves this server to its workers. */
+    readonly identity: CoordinatorIdentity;
+    /** Where agents are placed on a worker, and where they wait while paused. */
+    readonly placement: AgentPlacement;
+    /**
+     * This machine's worker, which the page's shells and task ports run on,
+     * and agents too while it is on; work waits for it to join.
+     */
+    readonly local: ConnectedWorker;
+    /** What brings this machine's worker to the server's build. */
+    readonly updater: LocalWorkerUpdate;
+    private listener;
+    /** Whether a worker may join: not while what the last run let go of is being taken back. */
+    private ready;
+    constructor(log: Logger, { session, protocol, records, identity, startWorker, }?: DevWorkersOptions);
+    /** What runs on each worker: the tasks its agents run, a conversation's id for one in no task. */
+    private used;
+    /** Whether this machine's worker takes agents, or one taking over while it updates. */
+    private pooled;
+    /** Hangs up on handoff worker `id`, once it is empty and told to stop, and forgets its record. */
+    private forgetHandoff;
+    /**
+     * Turns workers away until `serving`, while the conversations the last
+     * run let go of take their processes back, since a worker's hello
+     * settles which channels live on.
+     */
+    takingBack(): void;
+    /** Lets workers join again. */
+    serving(): void;
+    /** Hangs up on every worker for a restart, keeping what each runs (see `WorkerRegistry.detach`). */
+    detach(): Promise<void>;
+    /**
+     * Listens at `path`, logging rather than failing when it cannot, as when
+     * another `splates server` with the same home already does: the page works
+     * without workers.
+     */
+    listen(path: string, fs: Fs): Promise<void>;
+    /**
+     * `GET /api/workers`: each worker and each refusal, as `splates worker
+     * list` shows them, the build this server runs, whether it is paused,
+     * and every agent placed.
+     */
+    readonly list: () => Promise<Response>;
+    /**
+     * `PUT /api/workers/:id`: sets whether worker `id` drains, taking no new
+     * agents.
+     * Taking new agents again turns this machine's own back on, removed or
+     * being removed. `paused`, on this machine's own alone, holds back
+     * everything splates starts on its own, the person's agents still
+     * starting; it is set whether or not the worker is in the pool, since it
+     * stands for the server rather than the worker.
+     */
+    readonly update: (request: Request) => Promise<Response>;
+    /**
+     * `DELETE /api/workers/:id`: removes worker `id`, revoking its key. One
+     * with agents on it drains and is removed once they end, unless
+     * `?force`, which ends them now and frees their places. This machine's
+     * own is only taken out of the pool, its process kept for the page's
+     * shells and task ports, until `PUT` turns it on again.
+     */
+    readonly remove: (request: Request) => Promise<Response>;
+    /** Removes each worker waiting to be once its last agent has ended. */
+    private removeIdle;
+    /**
+     * Revokes worker `id`'s key and service token, hangs up on it, and frees
+     * what its agents held.
+     * This machine's own is turned off instead, keeping its settings for
+     * when it is back.
+     */
+    private forget;
+    /**
+     * `GET /api/queue`: every agent waiting for a worker, first in line first,
+     * from every project, as `splates worker queue list` shows them.
+     */
+    readonly queue: () => Promise<Response>;
+    /**
+     * `PUT /api/queue/:id/position`: moves the agent of conversation `id` to
+     * `position` in the queue, from 1, answering the queue as it stands.
+     */
+    readonly moveQueued: (request: Request) => Promise<Response>;
+    /** Local worker settings, guarded like the page's other writes. */
+    readonly manage: (request: Request, guard: (handle: (request: Request) => Promise<Response>) => (request: Request) => Promise<Response>) => Promise<Response>;
+    disposeAsync(): Promise<void>;
+}
+/** Keep the local worker’s session and settings across server restarts. */
+export interface DevWorkersOptions {
+    /**
+     * The session id every worker hears in its welcome: the same across
+     * restarts, so a worker keeps what it runs for the next run to take
+     * back; new by default, which ends what the worker held.
+     */
+    session?: string;
+    /** The protocol the last run spoke, which a worker's channels are taken back by only when its major is this one's. */
+    protocol?: string;
+    /** The local worker’s settings; kept in memory alone by default. */
+    records?: WorkerRecords;
+    /** What signs a worker's challenge, so it knows this server from one answering for its host; new, and kept nowhere, by default. */
+    identity?: CoordinatorIdentity;
+    /**
+     * Starts a worker known by `id` beside this machine's own, to take new
+     * agents while its own updates, answering whether it could; with none,
+     * this machine's own takes none while it updates.
+     */
+    startWorker?: (id: string) => boolean;
+}

package/vendor/@stringsync/splates-server/workers/run-options.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from "../../../core/log/index.js";
+import type { Fs, Ps } from "../../../core/system/index.js";
+/** What `splates worker run` is run with. */
+export interface WorkerRunOptions {
+    /** Empty for this machine's server, or `unix:<path>`. */
+    coordinator: string;
+    id: string;
+    log: Logger;
+    ps: Ps;
+    fs: Fs;
+}

package/vendor/@stringsync/splates-server/workers/run.d.ts

@@ -0,0 +1,10 @@
+import type { Ps } from "../../../core/system/index.js";
+import type { WorkerRunOptions } from "./run-options";
+/** Where the local worker finds the server on this machine. */
+export declare function workerSocketPath(ps: Ps): string;
+/**
+ * `splates worker run`: serves the server until a SIGINT or SIGTERM,
+ * restarting on the server's build when told it, and exiting
+ * `outdated` when refused without one.
+ */
+export declare function workerRun(opts: WorkerRunOptions): Promise<void>;