@stringsync/splates 0.0.45 → 0.0.46

package/worker-session.d.ts

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

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

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

package/worktree.d.ts

@@ -1,232 +0,0 @@
-import { type FileDiff } from "./diff.js";
-import type { GitResult } from "./git.js";
-import type { WorktreeService } from "./worktree-service.js";
-/**
- * One task, whether or not it is still there. Commands ask the service for
- * one of these and read its status rather than assembling the same handful of
- * existence checks themselves.
- */
-export declare class Worktree {
-    private readonly service;
-    private readonly snapshot;
-    constructor(service: WorktreeService, snapshot: WorktreeSnapshot);
-    get task(): string;
-    get branch(): string;
-    /** Where this task's work lands: its recorded base branch, else trunk. */
-    get base(): string;
-    /** The conversation whose agent added the task, or null. */
-    get caller(): string | null;
-    get path(): string;
-    get state(): TaskState | null;
-    get lease(): LeaseState | null;
-    /** The `splates server` conversation whose agent last took the task, or null. */
-    get takenBy(): string | null;
-    get leaseHeld(): boolean;
-    get leaseStatus(): "held" | "stale" | "none";
-    get leaseOurs(): boolean;
-    get leaseHeldByOther(): boolean;
-    get mergeAttempts(): number;
-    /** How many merge attempts a task gets before `merge` stops on `budget_exhausted`. */
-    get mergeAttemptLimit(): number;
-    get exists(): boolean;
-    get hasBranch(): boolean;
-    get removedAt(): string | null;
-    get status(): WorktreeStatus;
-    get gone(): boolean;
-    /**
-     * Merges changes into the record and writes it. Works on a name that has no
-     * record yet, which is how `add` writes the first one and how `claim`
-     * rebuilds one from a worktree found on disk.
-     */
-    save(changes?: Partial<TaskState>): Promise<Worktree>;
-    take(changes?: Partial<TaskState>): Promise<Worktree>;
-    /** Re-reads from disk. `merge` needs this: the record is the truth. */
-    reload(): Promise<Worktree>;
-    /**
-     * Removes the directory, the branch, and the record; remembers the name,
-     * and how the task ended.
-     */
-    discard(ended: "merged" | "removed", opts?: DiscardOptions): Promise<GitResult>;
-    /** The message of each commit it has that its base does not, oldest first. */
-    commitMessages(): Promise<string[] | null>;
-    commitsAhead(): Promise<number | null>;
-    /** Files and lines across all its pending work, as `diff` shows it; null without a branch. */
-    size(): Promise<DiffSize | null>;
-    /**
-     * Its committed and uncommitted changes, new files among them, parsed;
-     * null without a branch.
-     */
-    diff(): Promise<FileDiff[] | null>;
-    /** Committed and uncommitted paths this task touches; null without a branch. */
-    changedFiles(): Promise<string[] | null>;
-    uncommitted(): Promise<string[]>;
-    /** When its branch's latest commit was made, or null without a branch. */
-    committedAt(): Promise<string | null>;
-    interruptedOps(): Promise<string[]>;
-}
-export interface DiscardOptions {
-    /**
-     * The `splates server` conversation working on it, when ended from the page
-     * rather than by the agent, whose env names it.
-     */
-    conversation?: string;
-    /**
-     * The repo-relative paths the task changed, for a merge, which reads them
-     * before landing leaves nothing between the branch and its base. Read
-     * from the branch when not given.
-     */
-    changed?: string[];
-    /**
-     * The message of each commit a merge lands, read before landing as
-     * `changed` is.
-     */
-    commits?: string[];
-    /** Why it was removed, as `splates remove --reason` gives it. */
-    reason?: RemoveReason;
-    /** What a merge lands, read before landing as `changed` is. */
-    size?: DiffSize;
-}
-/** How big a change is, as its diff counts it. */
-export interface DiffSize {
-    files: number;
-    added: number;
-    removed: number;
-}
-/** Why a task can be removed rather than merged, as `--reason` names it. */
-export declare const REMOVE_REASONS: readonly ["nothing", "moot", "superseded", "redo"];
-/** Why a task was removed rather than merged. */
-export type RemoveReason = (typeof REMOVE_REASONS)[number];
-/** The status a task's own record carries. */
-export type RecordStatus = "working" | "merging" | "escalated";
-/** What a task's record stores about who is driving it. */
-export interface LeaseState {
-    pid: number;
-    hostname: string;
-    heartbeatAt: string;
-    /**
-     * The `splates server` conversation whose agent took it, or its caller's for a
-     * subagent; absent for an agent outside the page, and in older records.
-     */
-    conversation?: string;
-}
-export interface Escalation {
-    reason: string;
-    at: string;
-    /**
-     * Set for a task handed over to be approved rather than to answer
-     * questions, the reason saying what to look at.
-     */
-    review?: true | string;
-    /**
-     * When `claim` took the task back up, ending the wait on a person; absent
-     * while it waits, and in records from before it was kept.
-     */
-    resumedAt?: string;
-}
-/** Why a merge failed, as `merge` refuses it. */
-export type MergeFailure = "conflict" | "tests_failed" | "merge_failed";
-/** A test the gate named as failing, and what it said, as far as the runner printed. */
-export interface FailedTest {
-    name: string;
-    message: string;
-}
-/** One time `merge` turned a task away, and what it said of why. */
-export interface GateFailure {
-    reason: MergeFailure | "budget_exhausted";
-    at: string;
-    /** The files the rebase conflicted in, for a conflict. */
-    files?: string[];
-    /** What git said, for a conflict that named no file: why the rebase failed. */
-    output?: string;
-    /** The tests the gate named as failing, for `tests_failed`. */
-    tests?: string[];
-    /** Those tests with what each said, for `tests_failed`. Absent in old records. */
-    failures?: FailedTest[];
-    /** What git said, for `merge_failed`. */
-    error?: string;
-}
-export interface TaskState {
-    task: string;
-    branch: string;
-    worktree: string;
-    /** The branch this task lands on. Absent in old records: trunk. */
-    base?: string;
-    status: RecordStatus;
-    lease: LeaseState | null;
-    mergeAttempts: number;
-    /**
-     * Every merge that failed, which `retry` leaves alone while it hands back
-     * the attempts. Absent in old records: none counted yet.
-     */
-    mergeFailures?: number;
-    /** `mergeFailures` by why each failed. Absent in old records. */
-    mergeFailuresBy?: Partial<Record<MergeFailure, number>>;
-    /**
-     * Each time the gate turned it away, oldest first, with what it named:
-     * every failed merge, and each refusal once its attempts ran out. Absent in
-     * old records.
-     */
-    gateFailures?: GateFailure[];
-    /** How many times `splates retry` granted it more attempts. Absent in old records. */
-    retries?: number;
-    createdAt: string;
-    updatedAt: string;
-    escalations?: Escalation[];
-    /**
-     * The agent `splates add --agent` or `splates handoff` handed the task to, for
-     * `splates server` to start.
-     */
-    dispatch?: Dispatched;
-    /**
-     * The `splates server` conversation whose agent added the task, which the page
-     * nests it under. Absent for one added outside a conversation, or before
-     * tasks remembered it.
-     */
-    caller?: string;
-}
-/**
- * Who `splates add --agent` or `splates handoff` handed a task to. `splates server` starts the agent in
- * the task's tree and writes down the conversation it started, so it starts
- * once.
- */
-export interface Dispatched {
-    agent: string;
-    /** The model to pick, by the session's model setting; absent, the agent's own. */
-    model?: string;
-    /** What the agent is told beyond claiming the task. */
-    prompt?: string;
-    /** The conversation `splates server` started, once it has. */
-    conversation?: string;
-    /**
-     * Set while the postCheckout hook readies the tree; `splates server` starts the
-     * agent once it clears.
-     */
-    pending?: true;
-    /**
-     * Set when the agent at work on the task handed it on with `splates
-     * handoff`, so the one started is told `[SPLATES HANDOFF <task>]`.
-     */
-    handoff?: true;
-    /**
-     * Whether the agent started answers to the task's caller rather than the
-     * person, as for `splates handoff --relay`. Absent in records written
-     * before it was kept, when a handoff with a caller always relayed.
-     */
-    relay?: boolean;
-}
-/**
- * Everything a name can turn out to be. The record's own status when the
- * task is intact, and otherwise the way in which it is not.
- */
-export type WorktreeStatus = RecordStatus | "absent" | "removed" | "orphaned" | "stray" | "unrecorded" | "unknown";
-/** What the service found on disk. */
-export interface WorktreeSnapshot {
-    task: string;
-    branch: string;
-    path: string;
-    state: TaskState | null;
-    exists: boolean;
-    hasBranch: boolean;
-    removedAt: string | null;
-    corrupt: boolean;
-}