@stringsync/splates 0.0.0-stage → 0.0.45

package/unix-worker-socket.d.ts

@@ -0,0 +1,30 @@
+import type { WorkerSocket, WorkerSocketEvents } from "./worker-socket.js";
+/** Bun's socket, whose handlers hand each event to the `UnixWorkerSocket` it carries. */
+export type UnixSocket = Bun.Socket<UnixWorkerSocket>;
+/** The handlers `Bun.listen` and `Bun.connect` take, the same at both ends. */
+export declare const UNIX_HANDLERS: Bun.SocketHandler<UnixWorkerSocket>;
+/**
+ * A `WorkerSocket` over a Unix socket, how the local worker speaks to the
+ * coordinator on its machine. Dial one with `connect`; a `UnixWorkerListener`
+ * hands over the other end.
+ */
+export declare class UnixWorkerSocket implements WorkerSocket {
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<WorkerSocketEvents>;
+    private socket;
+    private pending;
+    /** What the kernel would not take yet, sent on the next drain. */
+    private unsent;
+    private open;
+    /** Dials the coordinator listening at `path`. */
+    static connect(path: string): Promise<UnixWorkerSocket>;
+    /** Takes the Bun socket it speaks over, as a listener or `connect` hands it. */
+    attach(socket: UnixSocket): void;
+    send(frame: string | Uint8Array): void;
+    dispose(): void;
+    /** Bun's `data` handler calls this with each chunk it read. */
+    received(chunk: Uint8Array): void;
+    /** Sends what the kernel has room for now. */
+    flush(): void;
+    closed(): void;
+}

package/update.d.ts

@@ -0,0 +1,29 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+/**
+ * Set in the environment of the splates `update` hands itself to, so that one
+ * refreshes rather than looking for a newer one again: npm can name a version
+ * a moment before `bunx` can fetch it.
+ */
+export declare const UPDATING = "SPLATES_UPDATING";
+/**
+ * Brings this repository up to the newest splates: when npm has a newer release
+ * than the one running, runs `update` again on that one, which does the rest
+ * itself; otherwise moves todos saved with tags into lanes, installs this
+ * one's skill over whatever copy is there, through `bunx skills add` from
+ * this release's tag, and moves what an older config holds to where this
+ * one reads it. Offline, the running release is the newest there is to
+ * have. `wiz update` names the release instead, as it pins every webappwiz
+ * package to one. Answers with the exit code to end on.
+ */
+export declare function update({ root, fs, ps, log, newest, release, }: {
+    /** The repository's main tree. */
+    root: string;
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+    /** The latest splates on npm, or null when it cannot say; unasked given `release`. */
+    newest?: () => Promise<string | null>;
+    /** The release whose skill to install, rather than the newest. */
+    release?: string;
+}): Promise<number>;

package/update.js

@@ -0,0 +1,10 @@
+import {
+  UPDATING2,
+  update2
+} from "./index-vcv9m93e.js";
+import"./index-4776671w.js";
+import"./index-k73tsw5g.js";
+export {
+  UPDATING2 as UPDATING,
+  update2 as update
+};

package/vocabulary.d.ts

@@ -0,0 +1,9 @@
+import type { System } from "./systems.js";
+/**
+ * Every word a prompt to an agent in `project` may use that a speech model
+ * would spell its own way: splates, the project's name, and each system's name
+ * and aliases.
+ */
+export declare function words(project: string, systems: Record<string, System>): string[];
+/** The prompt that gets the project's own words spelled its way. */
+export declare function vocabulary(project: string, systems: Record<string, System>): string;

package/wait.d.ts

@@ -0,0 +1,36 @@
+import { type Logger } from "webappwiz/log";
+import { Duration } from "webappwiz/time";
+import type { Todos } from "./todos.js";
+import type { WorktreeService } from "./worktree-service.js";
+/** How long `wait` gives a task before handing the wait back to its caller. */
+export declare const DEFAULT_TIMEOUT: Duration;
+/** When a wait begun now gives up after `timeout`, as an ISO time. */
+export declare function untilAfter(timeout: Duration): string;
+export interface WaitOptions {
+    /** How long to wait before giving up. */
+    timeout?: Duration;
+    /** How long between reads of the record; the default suits a human's patience. */
+    poll?: Duration;
+}
+/**
+ * Blocks until a task stops moving: merged or removed (both leave the name
+ * `removed`), escalated to a human, or broken. Waiting is for the agent whose
+ * own work overlaps this one's and would rather rebase onto the result than
+ * against it, which is why the timeout is short enough to come back and think
+ * again rather than block a session for an afternoon.
+ */
+export declare function wait({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task: string, { timeout, poll }?: WaitOptions): Promise<void>;
+/**
+ * Blocks until todo `id` leaves the list, which it does when the task that
+ * took it merges (or it is removed): what an agent whose next todo comes
+ * after it waits for, not knowing which task will take it. Ends early when
+ * the task that has it is escalated, since that wait is on a person.
+ */
+export declare function todoWait({ service, todos, log, }: {
+    service: WorktreeService;
+    todos: Todos;
+    log: Logger;
+}, id: number, { timeout, poll }?: WaitOptions): Promise<void>;

package/watch.d.ts

@@ -0,0 +1,46 @@
+import type { Git } from "./git.js";
+import { Watched } from "./watched.js";
+/** The git `Watch` runs, on whichever machine the agent works: `Git` here, or a worker's. */
+export type WatchGit = Pick<Git, "root" | "run" | "interruptedOps">;
+/**
+ * Something a command did to git that an agent should not have, judged by
+ * what it did rather than what it said: one that stashes and pops again, or
+ * commits and squashes, did nothing worth a flag.
+ */
+export type Flag = 
+/** Stashed `count` changes and left them there. */
+{
+    type: "stashed";
+    count: number;
+}
+/** Took commits off `branch` that its tree no longer holds. */
+ | {
+    type: "dropped";
+    branch: string;
+}
+/** Checked out `now`, a branch or null for a detached HEAD, off `branch`. */
+ | {
+    type: "left";
+    branch: string;
+    now: string | null;
+}
+/** Pushed, updating these remote branches, in a command that says `push`. */
+ | {
+    type: "pushed";
+    refs: string[];
+}
+/** Changed these files in the main tree, from a task's worktree. */
+ | {
+    type: "outside";
+    paths: string[];
+};
+/**
+ * Watches the commands agents run in one repository, `git.root` its main
+ * tree, for what they did to git.
+ */
+export declare class Watch {
+    private readonly git;
+    constructor(git: WatchGit);
+    /** Starts watching a command run in `cwd`, looking at git as it stands. */
+    command(cwd: string): Watched;
+}

package/watched.d.ts

@@ -0,0 +1,43 @@
+import type { Flag, WatchGit } from "./watch.js";
+/** A command being watched, from the look before it ran. */
+export declare class Watched {
+    private readonly git;
+    private readonly cwd;
+    private readonly before;
+    constructor(git: WatchGit, cwd: string, before: Promise<Look>);
+    /** Starts watching a command run in `cwd`, looking at git as it stands. */
+    static start(git: WatchGit, cwd: string): Watched;
+    /** Settles once the look before the command is taken. */
+    looked(): Promise<void>;
+    /**
+     * Looks at git again, now that `command` is over, and says what it did.
+     * A push counts only in a command that says `push`.
+     */
+    done(command: string | null): Promise<Flag[]>;
+    /**
+     * Whether `branch` lost what it held at `tip`: merging that commit into
+     * what the branch is now changes nothing in its commit or its tree, as it
+     * would not after a squash or a rebase onto trunk.
+     */
+    private dropped;
+    /** A rebase detaches HEAD until it is done, as `splates merge` leaves one. */
+    private rebasing;
+    /** The remote branches a push moved, as their reflogs say. */
+    private pushed;
+}
+/** What git looked like around a command. */
+interface Look {
+    /** The stash's entries, by commit. */
+    stash: string[];
+    /** The branch HEAD is on in the command's tree, null when detached. */
+    branch: string | null;
+    /** That branch's commit; null when detached or the tree is gone. */
+    tip: string | null;
+    /** Whether the tree is gone, as a merged task's is. */
+    gone: boolean;
+    /** Every remote branch but a symbolic one like `origin/HEAD`, with its commit. */
+    remotes: Map<string, string>;
+    /** The main tree's uncommitted paths; null for a command run in it. */
+    dirty: Set<string> | null;
+}
+export {};

package/websocket-worker-socket.d.ts

@@ -0,0 +1,18 @@
+import type { WorkerSocket, WorkerSocketEvents } from "./worker-socket.js";
+/**
+ * A `WorkerSocket` over a WebSocket the worker dials, as a remote worker
+ * reaches its coordinator's `/api/workers`: each frame is one message, text
+ * or binary as the protocol has it.
+ */
+export declare class WebSocketWorkerSocket implements WorkerSocket {
+    private readonly socket;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<WorkerSocketEvents>;
+    private open;
+    private constructor();
+    /** Dials `url`, settling once the socket is open. */
+    static connect(url: string): Promise<WebSocketWorkerSocket>;
+    send(frame: string | Uint8Array): void;
+    dispose(): void;
+    private closed;
+}

package/worker-call-host.d.ts

@@ -0,0 +1,51 @@
+import type { Resource } from "webappwiz/disposable";
+import { z } from "zod";
+import type { WorkerChannel } from "./worker-channel.js";
+import type { WorkerMachine } from "./worker-machine.js";
+/** A question a coordinator asks on a `calls` channel, answered by its id. */
+export declare const CallRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"git">;
+    cwd: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"processes">;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"listening">;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"exists">;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNumber;
+    method: z.ZodLiteral<"read">;
+    path: z.ZodString;
+    from: z.ZodNumber;
+}, z.core.$strip>], "method">;
+export type CallRequest = z.infer<typeof CallRequest>;
+/** How a worker answers: `{ id, result }`, or `{ id, error }` saying what went wrong. */
+export declare const CallAnswer: z.ZodUnion<readonly [z.ZodObject<{
+    id: z.ZodNumber;
+    result: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodNumber;
+    error: z.ZodString;
+}, z.core.$strip>]>;
+/**
+ * Answers a coordinator's calls on the machine a task runs on, each request
+ * a message on a `calls` channel and each answer one back, in whatever order
+ * they finish. A read's bytes go as base64.
+ */
+export declare class WorkerCallHost implements Resource {
+    private readonly channel;
+    private readonly machine;
+    private readonly unlisten;
+    constructor(channel: WorkerChannel, machine: WorkerMachine);
+    /** Stops answering, leaving the channel to whoever closes it. */
+    dispose(): void;
+    private answer;
+    private call;
+    private reply;
+}

package/worker-channel.d.ts

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

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

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

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

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

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

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

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