@stringsync/splates 0.0.0-stage → 0.0.45

package/events.d.ts

@@ -0,0 +1,311 @@
+import type { Question } from "./plan.js";
+import type { FailedTest, RemoveReason } from "./worktree.js";
+/** An escalation that went through, which asks the person to act. */
+export type Escalated = Extract<Event, {
+    action: "escalate";
+    reason: null;
+}>;
+/** Whether `event` is an escalation that went through. */
+export declare function isEscalation(event: Event): event is Escalated;
+/**
+ * What each action's event says beyond what every event does, keyed by the
+ * action as `splates log` names it. An action with nothing of its own yet maps
+ * to `None`: each slice of the Splates events lane fills in its command's.
+ */
+export interface Facts {
+    add: {
+        /** The branch the task starts from and merges onto. */
+        base: string;
+        /** The todos it took, by id. */
+        todos: number[];
+        /** What `--goal` said done means, or null when the todos seed the Goal. */
+        goal: string | null;
+        /** The subjects of the todos it took, in order, which seed its Goal. */
+        subjects: string[];
+        /** The agent it was handed to, or null when this conversation keeps it. */
+        agent: string | null;
+        /** That agent's model, or null for its own default or no agent. */
+        model: string | null;
+    };
+    claim: {
+        /** Whether the task was escalated, so the claim ends a wait on the user. */
+        escalated: boolean;
+        /**
+         * Whether the agent claiming is the one the task was handed to with
+         * `splates handoff`, taking it over.
+         */
+        tookOver: boolean;
+        /** What its `SPLATES.md` says done means, as markdown, or "" for nothing yet. */
+        goal: string;
+    };
+    tell: {
+        /**
+         * The conversation it was said in, the agent the task was handed to. The
+         * sender is the event's own `conversation`. The page shows it as no line
+         * of its own: the receiving message says where it came from.
+         */
+        to: string;
+    };
+    /** A wait on a task, the event's own: see `Waiting`. */
+    wait: Waiting;
+    merge: {
+        /** The branch it landed on, or was refused landing on. */
+        base: string;
+        /** The commit the base reached, short. */
+        commit: string;
+        /**
+         * What it touched when it landed, or the files the rebase conflicted in
+         * when refused for a conflict. Empty when a refusal names none.
+         */
+        files: string[];
+        /** The merge attempts it has left. */
+        attemptsLeft: number;
+        /**
+         * The tests the gate named as failing when refused for `tests_failed`,
+         * with what each said, so the log shows which ones fail most and why.
+         * Empty when the runner named none.
+         */
+        failedTests: FailedTest[];
+    };
+    remove: {
+        /** The `--reason` it gave, or null when it gave none. */
+        why: RemoveReason | null;
+        /** The todos it put back on the list, by id and subject. */
+        released: {
+            id: number;
+            subject: string;
+        }[];
+    };
+    escalate: {
+        /** Why it needs the person, or for a review, what to look at. */
+        about: string;
+        /** Whether it asks the person to approve merging, not to answer. */
+        review: boolean;
+        /** Where it merges once done. */
+        base: string;
+        /**
+         * Its open questions under `## Blocked` as they stood, which the card
+         * asks: a report never follows the task afterwards.
+         */
+        questions: Question[];
+    };
+    handoff: {
+        /** The roster agent it went to, by its id. */
+        agent: string;
+        /** Its model, by the id the roster gives it, or null for the agent's own. */
+        model: string | null;
+        /** Whether the agent answers to the conversation that handed it on. */
+        relay: boolean;
+    };
+    attach: {
+        /** The paths it stored, in the order given. */
+        stored: string[];
+        /** What `--remove` named to drop, each by path or stored name. */
+        removed: string[];
+    };
+    "artifact add": {
+        /** The artifact, by name. */
+        name: string;
+        /** The version it made. */
+        version: number;
+        /** That version's size. */
+        bytes: number;
+    };
+    "artifact remove": {
+        /** The artifact, by name. */
+        name: string;
+        /** The version that was current. */
+        version: number;
+    };
+    retry: {
+        /** The merge attempts the task had spent, which the grant gives it more of. */
+        attempts: number;
+    };
+    "todo add": {
+        /** The todo it added, by id. */
+        todo: number;
+        /** Its line, as the page names it. */
+        subject: string;
+        /** The lane it went in, or null when it went in none. */
+        lane: number | null;
+        /** Where it went in the list, 1 at the top. */
+        position: number;
+    };
+    "todo update": {
+        /** The todo, by id. */
+        todo: number;
+        /** Its subject once updated, so a line names it though it was reworded. */
+        subject: string;
+        /** Only what moved: a key is absent when its part stayed as it was. */
+        changed: {
+            /** The new subject. */
+            subject?: string;
+            /** Whether its detail was rewritten. */
+            text?: true;
+            /** Where it moved to in the list, 1 at the top. */
+            position?: number;
+            /** The lane it moved to, null for none. */
+            lane?: number | null;
+            /** Todos it is now blocked by. */
+            blocked?: number[];
+            /** Todos that no longer block it. */
+            unblocked?: number[];
+            /** Names of the files attached. */
+            attached?: string[];
+            /** Names of the files dropped. */
+            detached?: string[];
+            /** The agent and model it now names, null once it names none. */
+            assignee?: {
+                agent: string;
+                model?: string;
+            } | null;
+        };
+    };
+    "todo take": TodosFacts;
+    "todo wait": Waiting & {
+        /** The todo, by id. */
+        todo: number;
+        /** Its subject as the wait began, or null for a todo there is no such thing as. */
+        subject: string | null;
+    };
+    "todo release": TodosFacts;
+    "todo remove": TodosFacts;
+    "lane add": {
+        /** The lane it started, by number. */
+        lane: number;
+        /** Its name. */
+        name: string;
+    };
+    "lane update": {
+        /** The lane, by number. */
+        lane: number;
+        /** Its name once updated, so a line names it though it was renamed. */
+        name: string;
+        /** Only what changed: a key is absent when it stayed as it was. */
+        changed: {
+            /** The new name. */
+            name?: string;
+            /** Where it moved to among the lanes, 1 the first column. */
+            position?: number;
+        };
+    };
+    "lane remove": {
+        /** The lane, by the number it had. */
+        lane: number;
+        /** Its name. */
+        name: string;
+        /** The todos it held, now in no lane. */
+        todos: number[];
+    };
+    "lane join": None;
+    "creds request": {
+        /** The cred asked for, as its environment variable. */
+        name: string;
+        /** Whether it asked, rather than finding the cred already kept. */
+        asked: boolean;
+    };
+    "creds save": None;
+    "creds remove": None;
+    "creds dismiss": None;
+    "creds wait": Waiting & {
+        /** The cred waited for, by name. */
+        name: string;
+    };
+    "tunnel setup": None;
+    "tunnel remove": None;
+}
+type None = Record<never, never>;
+/**
+ * A wait the page counts down: its start shows a line that runs until `until`,
+ * and its end says how the wait went, pointing back at its start with `began`.
+ */
+export interface Waiting {
+    /** When it gives up, as an ISO time. */
+    until: string;
+    /** The id of the event it began with, on the one it ends with; null on that first. */
+    began: string | null;
+}
+/** The todos a command took, released or removed, as they were named then. */
+interface TodosFacts {
+    todos: {
+        id: number;
+        subject: string;
+    }[];
+}
+export type Action = keyof Facts;
+/**
+ * Each action's facts by name, as its event records them now: the journal
+ * reads an event only when it carries all of them, and none of an action
+ * missing here.
+ */
+export declare const FACTS: {
+    readonly add: readonly ["base", "todos", "goal", "subjects", "agent", "model"];
+    readonly claim: readonly ["escalated", "tookOver", "goal"];
+    readonly tell: readonly ["to"];
+    readonly wait: readonly ["until", "began"];
+    readonly merge: readonly ["base", "commit", "files", "attemptsLeft", "failedTests"];
+    readonly remove: readonly ["why", "released"];
+    readonly escalate: readonly ["about", "review", "base", "questions"];
+    readonly handoff: readonly ["agent", "model", "relay"];
+    readonly attach: readonly ["stored", "removed"];
+    readonly "artifact add": readonly ["name", "version", "bytes"];
+    readonly "artifact remove": readonly ["name", "version"];
+    readonly retry: readonly ["attempts"];
+    readonly "todo add": readonly ["todo", "subject", "lane", "position"];
+    readonly "todo update": readonly ["todo", "subject", "changed"];
+    readonly "todo take": readonly ["todos"];
+    readonly "todo wait": readonly ["until", "began", "todo", "subject"];
+    readonly "todo release": readonly ["todos"];
+    readonly "todo remove": readonly ["todos"];
+    readonly "lane add": readonly ["lane", "name"];
+    readonly "lane update": readonly ["lane", "name", "changed"];
+    readonly "lane remove": readonly ["lane", "name", "todos"];
+    readonly "lane join": readonly [];
+    readonly "creds request": readonly ["name", "asked"];
+    readonly "creds save": readonly [];
+    readonly "creds remove": readonly [];
+    readonly "creds dismiss": readonly [];
+    readonly "creds wait": readonly ["until", "began", "name"];
+    readonly "tunnel setup": readonly [];
+    readonly "tunnel remove": readonly [];
+};
+/**
+ * Whether `event` carries every fact its action records now. One that went
+ * through before its action recorded them all does not, and nor does one
+ * logged by a newer splates for an action this one does not know.
+ */
+export declare function isCurrent(event: Event): boolean;
+/** What every event carries, whatever its action. */
+interface Common<A extends Action> {
+    /** Its own, so a reader following the log takes each event once. */
+    id: string;
+    at: string;
+    action: A;
+    /** The task it was about, or null when the command names none. */
+    task: string | null;
+    /** The refusal reason, or null when the command succeeded. */
+    reason: string | null;
+    /**
+     * The `splates server` conversation that ran it, so the page can show it there,
+     * or null for an external agent or the page itself.
+     */
+    conversation: string | null;
+}
+/**
+ * One thing that was done, and how it went. A refused command carries only
+ * the facts it was asked with, since it never got to learn the rest.
+ */
+export type Event = {
+    [A in Action]: (Common<A> & {
+        reason: null;
+    } & Facts[A]) | (Common<A> & {
+        reason: string;
+    } & Partial<Facts[A]>);
+}[Action];
+/**
+ * What `ctx.journal.record` takes for an action's facts: a value, for what the
+ * command was asked with, kept even when it is refused, or a function of what
+ * it returned, kept only on success. An action with no facts takes none.
+ */
+export type FactsOf<A extends Action, T> = keyof Facts[A] extends never ? [] : [facts: Facts[A] | ((out: T) => Facts[A])];
+export {};

package/everywhere.d.ts

@@ -0,0 +1,41 @@
+import type { Conversation, Conversations } from "./conversations.js";
+import type { Served } from "./dev-project.js";
+import type { Projects } from "./projects.js";
+/**
+ * The conversations of every project `splates server` serves, so a conversation
+ * that handed out a task in another project than its own hears of, and
+ * answers for, the agent it handed it to, as it would one in its own.
+ */
+export declare class Everywhere {
+    private readonly placing;
+    /** Only the conversations of the project at `root`, as a server of one has them. */
+    static onlyHere(root: string, conversations: Conversations): Everywhere;
+    /**
+     * The conversations of each project in `served`, by its root, those that
+     * failed to open left out, each named as `projects` names it.
+     */
+    static served(served: Map<string, Promise<Served>>, projects: Projects): Everywhere;
+    constructor(placing: Placing);
+    /** Every conversation of every project served so far, with its project's main tree. */
+    list(): Promise<Placed[]>;
+    /** The conversation `id`, of whichever project holds it, or undefined for none. */
+    find(id: string): Promise<Placed | undefined>;
+    /**
+     * How a directive names `task`, of the project at `root`, to a
+     * conversation of the project at `to`: bare in its own, else
+     * `<slug>/<task>`, which `splates --project <slug>` reaches.
+     */
+    taskNamed(task: string, root: string, to: string): Promise<string>;
+}
+/** A conversation, and the main tree of the project it is in. */
+export interface Placed {
+    conversation: Conversation;
+    root: string;
+}
+/** Where `Everywhere` finds the conversations, and the projects' names. */
+export interface Placing {
+    /** Every conversation of every project served so far. */
+    list(): Promise<Placed[]>;
+    /** What the registry names the project at `root` by. */
+    slug(root: string): Promise<string>;
+}

package/exhibit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Something to look at that the skill captions with the one or two calls it
+ * shows, as a reply writes it under `### 🖼️ <title>`: a screenshot, a
+ * diagram or a snippet.
+ */
+export interface Exhibit {
+    /** What it shows, from its heading. */
+    title: string;
+    /** The screenshot, diagram or snippet, as markdown. */
+    body: string;
+}
+/** What the exhibit titled by `line` shows; null for any other line. */
+export declare function exhibitTitle(line: string): string | null;
+/**
+ * An assumption's `body` parted into what is to look at, its images and code
+ * blocks, as markdown, null when it holds neither, and the words around them.
+ */
+export declare function shownIn(body: string): {
+    shown: string | null;
+    said: string;
+};

package/exit.d.ts

@@ -0,0 +1,54 @@
+import type { Deps, Middleware } from "webappwiz/cmd";
+/** Exit codes are the API: an agent branches on these, not on prose. */
+export declare const EXIT: {
+    readonly usage: 1;
+    readonly conflict: 2;
+    readonly tests_failed: 3;
+    readonly lease_lost: 4;
+    readonly budget_exhausted: 5;
+    readonly lease_held: 6;
+    readonly dirty: 7;
+    readonly not_found: 8;
+    readonly hook_failed: 9;
+    readonly exists: 10;
+    readonly orphaned: 11;
+    readonly merge_failed: 12;
+    readonly already_removed: 13;
+    readonly timeout: 14;
+    readonly blocked: 16;
+    readonly cycle: 18;
+    readonly outdated: 19;
+    readonly uninitialized: 20;
+    readonly too_large: 21;
+    readonly dismissed: 22;
+    readonly no_secret_store: 23;
+    readonly cloudflare: 24;
+    readonly requested: 25;
+    readonly slots_full: 26;
+    readonly slot_running: 27;
+    readonly not_granted: 28;
+    readonly agents_full: 29;
+};
+export type Reason = keyof typeof EXIT;
+/**
+ * A refusal, carrying the reason to branch on, a message to show, and any
+ * data worth reporting with it. `exits` turns one into output and a status
+ * code.
+ */
+export declare class Exit extends Error {
+    readonly reason: Reason;
+    readonly data: Record<string, unknown>;
+    constructor(reason: Reason, message: string, data?: Record<string, unknown>);
+}
+/**
+ * How a command refuses. Every call site means "and go no further", which is
+ * what the `never` return buys: the code below a `fail` is unreachable, and
+ * TypeScript narrows accordingly.
+ */
+export declare function fail(reason: Reason, message: string, data?: Record<string, unknown>): never;
+/**
+ * Decides what a refusal looks like (a machine-readable reason on stdout, a
+ * human explanation on stderr) and is the only place that ends the process.
+ * An agent branches on the first and reads the second.
+ */
+export declare function exits<C extends Deps>(): Middleware<C>;

package/fact-todos.d.ts

@@ -0,0 +1,18 @@
+import { type Logger } from "webappwiz/log";
+import type { Git } from "./git.js";
+import type { Journal } from "./journal.js";
+import type { Outcomes } from "./outcomes.js";
+import type { Todos } from "./todos.js";
+/**
+ * Adds a todo, untriaged, for each thing that went worse in `task`'s merge,
+ * as its merged card lists them, journaled so the conversation that merged
+ * it shows each as an "Added" line the person can remove it from. One whose
+ * line is on the list already is not added again.
+ */
+export declare function addFactTodos({ git, outcomes, todos, journal, log, }: {
+    git: Git;
+    outcomes: Outcomes;
+    todos: Todos;
+    journal: Journal;
+    log: Logger;
+}, task: string): Promise<void>;

package/fake-agent.d.ts

@@ -0,0 +1,107 @@
+import * as acp from "@agentclientprotocol/sdk";
+import type { Agent, AgentProcess } from "./conversations.js";
+import type { RosterAgent } from "./roster.js";
+/** What the agent does with each prompt, given the connection back to splates. */
+export type Turn = (client: acp.AgentSideConnection, session: string, text: string) => Promise<acp.StopReason>;
+export declare const AGENT: Agent;
+/** `AGENT` as the roster lists it, with the models its Model setting offers. */
+export declare const ROSTERED: RosterAgent;
+/**
+ * An ACP agent in this process, joined to the conversation by two pipes in
+ * place of a child's stdio, and played by `turn`.
+ */
+export declare class FakeAgent {
+    turn: Turn;
+    cancelled: number;
+    /** The sessions resumed, by id, in order. */
+    resumed: string[];
+    /**
+     * What `_session/steering` answers, or null for an agent that does not
+     * offer it, the default: `startedNewTurn` as Codex does when it finds no
+     * turn, whatever splates asked, and `failed` as it does on an error.
+     */
+    steering: "injected" | "promptRequired" | "startedNewTurn" | "failed" | null;
+    /** What was steered into a turn, in order. */
+    steered: string[];
+    /** What it does before it answers a steer, as ending the turn it would steer into. */
+    beforeSteer: () => Promise<void>;
+    /** Whether it offers its session list to subscribe to, as Codex does. */
+    lists: boolean;
+    /** The working directories its session list was subscribed for, in order. */
+    subscribed: string[];
+    /** What splates said it can take, as it started the last process. */
+    capabilities: acp.ClientCapabilities | null;
+    /** The background commands stopped, by id, in order. */
+    stoppedBackground: string[];
+    /** Whether it says it takes images in a prompt. */
+    sees: boolean;
+    /** The tokens it says each turn used; none, the default, says nothing. */
+    usage: acp.Usage | null;
+    /**
+     * The sessions it holds from before, as its CLI would, to list and load;
+     * none, the default, for an agent that does not offer either.
+     */
+    held: (acp.SessionInfo & {
+        replay: acp.SessionUpdate[];
+    })[] | null;
+    /** The sessions loaded, by id, in order. */
+    loaded: string[];
+    /** The `_meta` each session was opened, loaded or resumed with, in order. */
+    opened: unknown[];
+    /** Whether it takes MCP servers over HTTP, as Claude's adapter does. */
+    http: boolean;
+    /** The MCP servers each session was opened, loaded or resumed with, in order. */
+    mcp: acp.McpServer[][];
+    /** Every prompt it was sent, block by block, in order. */
+    prompts: acp.ContentBlock[][];
+    /** The settings set, in order. */
+    chosen: {
+        configId: string;
+        value: unknown;
+    }[];
+    options: acp.SessionConfigOption[];
+    /** Negotiated resume support; absent capabilities must never imply it. */
+    resumes: boolean;
+    protocolVersion: number;
+    disconnect: () => void;
+    /** Simulate an agent refusing to apply a model choice. */
+    ignoreChoices: boolean;
+    /** What each start's `initialize` waits on; null, the default, answers at once. */
+    hold: Promise<void> | null;
+    /** How many starts to come die before answering `initialize`. */
+    dying: number;
+    stderr: string;
+    launched: {
+        argv: string[];
+        cwd: string;
+        env: Record<string, string>;
+    }[];
+    killed: number;
+    /** The pid each process it launches says it has. */
+    pid: number | null;
+    private exit;
+    launch: (argv: string[], cwd: string, env: Record<string, string>) => AgentProcess;
+    /** Dies as a crashed agent would, on its own. */
+    crash(): void;
+    /** Says `update` outside any turn, as Claude does of a background command. */
+    say(update: acp.SessionUpdate): Promise<void>;
+    /**
+     * Says on its session list that session `s1` is in `state`, its last turn
+     * ended at `endedAt`, as Codex does as a turn starts and ends.
+     */
+    list(state: "running" | "idle" | "error", endedAt?: string): Promise<void>;
+    private client;
+    private agent;
+}
+/** What the person said, as an agent replays it. */
+export declare function heard(text: string): acp.SessionUpdate;
+export declare function say(text: string): acp.SessionUpdate;
+/**
+ * Claude's adapter saying it left a command running in the background as
+ * `id`, started by tool call `tool`: a draft the SDK's types leave out.
+ */
+export declare function backgroundStarted(id: string, description: string, tool: string, taskType?: string, output?: string): acp.SessionUpdate;
+/** Claude's adapter saying background command `id` ended as `state`. */
+export declare function backgroundEnded(id: string, state: "completed" | "failed" | "stopped"): acp.SessionUpdate;
+/** Claude's adapter saying where background command `id` writes its output. */
+export declare function backgroundWrites(id: string, output: string): acp.SessionUpdate;