@stringsync/splates 0.0.45 → 0.0.47

package/worker-channel.d.ts

@@ -1,83 +0,0 @@
-import type { Resource } from "webappwiz/disposable";
-import { type Eventful } from "webappwiz/events";
-import type { Json } from "./worker-protocol.js";
-/** What a `WorkerChannel` hears from the other end, each with its seq. */
-export interface WorkerChannelEvents extends Record<string, unknown> {
-    data: {
-        bytes: Uint8Array;
-        seq: number;
-    };
-    message: {
-        body: Json;
-        seq: number;
-    };
-    /** Both ends have closed it, whichever closed first. */
-    close: undefined;
-}
-/** What a channel needs of the session it runs over. */
-export interface WorkerChannelLink {
-    /** Sends a frame in the channel's next seq, and says whether there is room for more. */
-    send(channel: number, frame: {
-        type: "message";
-        body: Json;
-    } | {
-        type: "data";
-        bytes: Uint8Array;
-    } | {
-        type: "close";
-    }): boolean;
-    ack(channel: number, seq: number): void;
-    /** Both ends have said close, so the session can forget the channel. */
-    done(channel: number): void;
-}
-/**
- * One stream between a coordinator and a worker, such as an agent's stdio or
- * a PTY: bytes as `data`, and JSON as `message` for what is not bytes (a
- * resize, an exit code). Its frames survive a reconnect. Disposing it closes
- * it at both ends, and each hears `close` once both have.
- */
-export declare class WorkerChannel implements Eventful<WorkerChannelEvents>, Resource {
-    readonly id: number;
-    readonly kind: string;
-    readonly params: Json;
-    private readonly link;
-    private readonly dispatcher;
-    readonly events: import("webappwiz/events").Events<WorkerChannelEvents>;
-    private sentClose;
-    private heardClose;
-    constructor(id: number, kind: string, params: Json, link: WorkerChannelLink);
-    get closed(): boolean;
-    /**
-     * Returns `false` once the session holds as many unacked bytes as it is
-     * allowed: stop reading whatever feeds this until the session's `drain`.
-     */
-    write(bytes: Uint8Array): boolean;
-    /** As `write`, for JSON. */
-    send(body: Json): boolean;
-    /** Says this end holds everything up to `seq`, for a session that acks by hand. */
-    ack(seq: number): void;
-    dispose(): void;
-    /**
-     * Ends it here without a word to the other end, which no longer knows it,
-     * as a coordinator started again does not; this end hears `close`.
-     */
-    drop(): void;
-    /**
-     * Hands the channel what the other end sent; the session calls it. Says
-     * whether anyone heard it, since a frame nobody heard is the session's to ack.
-     */
-    receive(frame: {
-        type: "message";
-        body: Json;
-        seq: number;
-    } | {
-        type: "data";
-        bytes: Uint8Array;
-        seq: number;
-    } | {
-        type: "close";
-        seq: number;
-    }): boolean;
-    private finishIfDone;
-    private assertOpen;
-}

package/worker-connection.d.ts

@@ -1,24 +0,0 @@
-import { Disposer, type Resource } from "webappwiz/disposable";
-import type { Duration } from "webappwiz/time";
-import type { Negotiated } from "./worker-protocol.js";
-import type { WorkerSocket } from "./worker-socket.js";
-/**
- * One socket's worth of a `WorkerSession`: what goes when the socket does,
- * while the session's channels and unacked frames stay for the next one.
- */
-export declare class WorkerConnection implements Resource {
-    readonly socket: WorkerSocket;
-    heard: Duration;
-    readonly resources: Disposer;
-    /** Settles with the handshake, or with why the socket went first. */
-    readonly settled: {
-        promise: Promise<Negotiated>;
-        resolve: (value?: PromiseLike<Negotiated> | Negotiated | undefined) => void;
-        reject: (reason?: any) => void;
-    };
-    /** Past the handshake, so channel frames flow. */
-    live: boolean;
-    ackFlush: Resource | undefined;
-    constructor(socket: WorkerSocket, heard: Duration);
-    dispose(): void;
-}

package/worker-daemon.d.ts

@@ -1,64 +0,0 @@
-import type { AsyncResource } from "webappwiz/disposable";
-import type { Logger } from "webappwiz/log";
-import type { Fs, Ps } from "webappwiz/system";
-import { type Clock, Duration, type Timer } from "webappwiz/time";
-import { WorkerSession, type WorkerSessionOptions } from "./worker-session.js";
-import type { WorkerSocket } from "./worker-socket.js";
-/** How a worker reaches its coordinator, dialed afresh after each drop. */
-export interface WorkerDialer {
-    /** Where it dials, for the log. */
-    readonly where: string;
-    dial(): Promise<WorkerSocket>;
-}
-/** The channels a worker serves, which it says it can in its hello. */
-export declare const WORKER_CAPABILITIES: string[];
-/** Who a `WorkerDaemon` is and what it runs on. */
-export interface WorkerDaemonOptions {
-    /** Stays the same across restarts, so the coordinator resumes its session. */
-    id: string;
-    slots: number;
-    ps: Ps;
-    fs: Fs;
-    log: Logger;
-    /** The shortest and longest wait between dials. */
-    backoff?: {
-        min: Duration;
-        max: Duration;
-    };
-    /** Paces the session, as `WorkerSession` takes it. */
-    session?: Omit<WorkerSessionOptions, "timer" | "clock" | "capabilities">;
-    timer?: Timer;
-    clock?: Clock;
-}
-/**
- * `splates worker run`: a worker that dials out to its coordinator and keeps
- * dialing, waiting longer after each failure, and runs what it is asked to
- * on this machine: processes, PTYs, calls, and connections to the ports its
- * tasks serve. What it runs outlives a
- * dropped link, since the session replays what the coordinator missed.
- */
-export declare class WorkerDaemon implements AsyncResource {
-    private readonly dialer;
-    private readonly opts;
-    readonly session: WorkerSession;
-    private readonly hosts;
-    private readonly timer;
-    private readonly backoff;
-    private readonly machine;
-    private waiting;
-    private stopped;
-    constructor(dialer: WorkerDialer, opts: WorkerDaemonOptions);
-    /**
-     * Dials and serves until disposed, or until the coordinator refuses this
-     * worker, resolving with why it stopped.
-     */
-    run(): Promise<{
-        refused: string;
-    } | {
-        stopped: true;
-    }>;
-    /** Stops dialing and everything this worker runs, and hangs up. */
-    disposeAsync(): Promise<void>;
-    private serve;
-    private sleep;
-}

package/worker-git.d.ts

@@ -1,18 +0,0 @@
-import type { GitResult } from "./git.js";
-import type { WatchGit } from "./watch.js";
-import type { WorkerMachine } from "./worker-machine.js";
-/**
- * The git `Watch` runs around an agent's commands, run on the worker the
- * agent works on, since its worktree is there.
- */
-export declare class WorkerGit implements WatchGit {
-    /** The main worktree, where trunk lives. */
-    readonly root: string;
-    private readonly machine;
-    constructor(
-    /** The main worktree, where trunk lives. */
-    root: string, machine: WorkerMachine);
-    run(cwd: string, ...args: string[]): Promise<GitResult>;
-    /** As `Git.interruptedOps`, read on the worker: a worktree's half-finished merges and rebases. */
-    interruptedOps(worktree: string): Promise<string[]>;
-}

package/worker-list.d.ts

@@ -1,49 +0,0 @@
-import type { Logger } from "webappwiz/log";
-import type { Ps } from "webappwiz/system";
-import { type WallClock } from "webappwiz/time";
-import type { WorkerKind } from "./remote-worker.js";
-import type { WorkerRegistry } from "./worker-registry.js";
-/** One worker as `GET /api/workers` and `splates worker list` give it. */
-export interface WorkerListing {
-    id: string;
-    /** `provisioned` is for workers splates makes itself, which do not exist yet. */
-    kind: WorkerKind | "provisioned";
-    platform: string | null;
-    build: string | null;
-    /** What its link settled on; null before any handshake. */
-    protocol: string | null;
-    slots: {
-        used: number;
-        total: number | null;
-    };
-    /** `connected` while the link is up, else `away`. */
-    health: "connected" | "away";
-    /** When anything last came from it, epoch milliseconds; null before the first. */
-    lastHeard: number | null;
-    /** The tasks placed on it; none until tasks are placed on workers. */
-    tasks: string[];
-    dollarsPerHour: number;
-}
-/** What `GET /api/workers` answers. */
-export interface WorkerListings {
-    workers: WorkerListing[];
-    refused: {
-        id: string;
-        protocol: string;
-        reason: string;
-    }[];
-}
-/** The workers a registry keeps and the ones it turned away. */
-export declare function workerList(registry: WorkerRegistry): WorkerListings;
-/** What `splates worker list` is run with. */
-export interface ListWorkersOptions {
-    /** The `splates server` to ask; empty for the one this agent runs under. */
-    dev: string;
-    json: boolean;
-    log: Logger;
-    ps: Ps;
-    send?: typeof fetch;
-    wall?: WallClock;
-}
-/** `splates worker list`: asks the running `splates server` which workers it has. */
-export declare function listWorkers(opts: ListWorkersOptions): Promise<void>;

package/worker-machine.d.ts

@@ -1,34 +0,0 @@
-import type { Fs, ListeningEntry, ProcessEntry, Ps } from "webappwiz/system";
-import { type GitResult } from "./git.js";
-/** A file's size, and its bytes from where the caller last read up to. */
-export interface WorkerRead {
-    size: number;
-    bytes: Uint8Array;
-}
-/**
- * What the coordinator asks of the machine a task runs on: git in its
- * worktree around each tool call (`Watch`), a background command's output
- * (`ConversationBackground`), the process table (`heldBy`), and the ports
- * its processes listen on (`TaskPorts`).
- */
-export interface WorkerMachine {
-    git(cwd: string, args: string[]): Promise<GitResult>;
-    processes(): Promise<ProcessEntry[]>;
-    listening(): Promise<ListeningEntry[]>;
-    /** `path` from byte `from` on; a missing file reads as empty. */
-    read(path: string, from: number): Promise<WorkerRead>;
-    /** Whether anything is at `path`, a file or a directory. */
-    exists(path: string): Promise<boolean>;
-}
-/** The machine this process runs on, as a worker answers for it. */
-export declare class LocalWorkerMachine implements WorkerMachine {
-    private readonly ps;
-    private readonly fs;
-    private readonly runner;
-    constructor(ps: Ps, fs: Fs);
-    git(cwd: string, args: string[]): Promise<GitResult>;
-    processes(): Promise<ProcessEntry[]>;
-    listening(): Promise<ListeningEntry[]>;
-    exists(path: string): Promise<boolean>;
-    read(path: string, from: number): Promise<WorkerRead>;
-}

package/worker-port-host.d.ts

@@ -1,21 +0,0 @@
-import type { Resource } from "webappwiz/disposable";
-import { z } from "zod";
-import type { WorkerChannel } from "./worker-channel.js";
-import type { WorkerSession } from "./worker-session.js";
-/** What a coordinator opens a `port` channel with. */
-export declare const PortParams: z.ZodObject<{
-    port: z.ZodNumber;
-}, z.core.$strip>;
-/**
- * One TCP connection a `port` channel opened to a port on the worker's
- * loopback, such as a task's dev server: its bytes both ways as the
- * channel's, `connected` once it is open, or `failed` with why before the
- * channel closes. Closing the channel ends the connection.
- */
-export declare class WorkerPortHost implements Resource {
-    private readonly channel;
-    private readonly pipe;
-    constructor(channel: WorkerChannel, session: WorkerSession);
-    dispose(): void;
-    private connect;
-}

package/worker-process-host.d.ts

@@ -1,29 +0,0 @@
-import type { Resource } from "webappwiz/disposable";
-import type { Ps } from "webappwiz/system";
-import { z } from "zod";
-import type { WorkerChannel } from "./worker-channel.js";
-import type { WorkerSession } from "./worker-session.js";
-/** What a coordinator opens a `process` channel with. */
-export declare const ProcessParams: z.ZodObject<{
-    argv: z.ZodArray<z.ZodString>;
-    cwd: z.ZodString;
-    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, z.core.$strip>;
-/**
- * One process a `process` channel started on the worker, such as an agent:
- * its stdout as the channel's bytes, its stdin from them, and its pid,
- * stderr and exit code as messages. Its stdout is read only while the
- * session has room, so a coordinator away for long stalls the process
- * rather than losing what it says. Closing the channel kills it.
- */
-export declare class WorkerProcessHost implements Resource {
-    private readonly channel;
-    private readonly session;
-    private readonly child;
-    private readonly stdin;
-    constructor(channel: WorkerChannel, session: WorkerSession, ps: Ps);
-    dispose(): void;
-    private told;
-    private run;
-    private pump;
-}

package/worker-protocol.d.ts

@@ -1,104 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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>;