@stringsync/splates 0.0.0-stage → 0.0.45

package/conversation.d.ts

@@ -0,0 +1,209 @@
+import type { Resource } from "webappwiz/disposable";
+import { type Eventful } from "webappwiz/events";
+import type { Agent, ProcessHandle } from "./agent-process.js";
+import { Artifacts } from "./artifacts.js";
+import type { ConversationDeps, ConversationEvents, ConversationHost } from "./conversation-host.js";
+import { ConversationLog } from "./conversation-log.js";
+import { type Answer, type Attached, type ConversationState, type Device, type Limit, type Upload } from "./conversation-state.js";
+import { type PromptOptions } from "./conversation-turns.js";
+/**
+ * One conversation with one agent. Live, it holds the agent's process; read
+ * back from its log, it is what was said, and resumes on the next prompt.
+ */
+export declare class Conversation implements Eventful<ConversationEvents>, Resource, ConversationHost {
+    readonly state: ConversationState;
+    readonly log: ConversationLog;
+    private readonly deps;
+    /** What to run to resume it; null when its agent is no longer known. */
+    readonly agent: Agent | null;
+    /** Where it runs; null for a log too old to say. */
+    private dir;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<ConversationEvents>;
+    private readonly files;
+    /** The files its agent kept as its outputs, read and changed here. */
+    readonly artifacts: Artifacts;
+    private readonly connection;
+    private readonly turns;
+    private readonly background;
+    /** Under way while the agent starts or comes back, for a prompt to wait on. */
+    opening: Promise<void> | null;
+    /** Stops the agent once it has sat idle `IDLE_STOP`; null while it works. */
+    private resting;
+    /** Let go of its process for a restart: nothing here ends it now. */
+    private detached;
+    private constructor();
+    /**
+     * A conversation as its log at `path` left it: stopped, whatever it was
+     * doing, unless its agent still runs on a worker, which the launcher
+     * takes back, and the conversation carries on where the log leaves off.
+     */
+    static read(path: string, agents: Agent[], deps: ConversationDeps): Promise<Conversation | null>;
+    /** Starts `agent` in `cwd` and opens a session with it. */
+    static start({ settings, model, ...opening }: Opening & {
+        /** Values to set, by setting id, once the session offers them. */
+        settings?: Record<string, string>;
+        /**
+         * The model to pick, by its value or name in the session's model
+         * setting, over what `settings` says. An unavailable choice fails.
+         */
+        model?: string;
+    }, deps: ConversationDeps): Promise<Conversation>;
+    /**
+     * Brings in `session`, one `agent` holds outside splates, such as from its
+     * CLI: loads it in `cwd`, writing what the agent replays of it to a new
+     * log, from which it resumes like any other.
+     */
+    static bring({ session, title, ...opening }: Opening & {
+        session: string;
+        /** What the agent listed it as, until the replay says otherwise. */
+        title: string | null;
+    }, deps: ConversationDeps): Promise<Conversation>;
+    /** A new conversation with `agent` in `cwd`, its log begun, not yet opened. */
+    private static begin;
+    get id(): string;
+    /** The agent's pid while it runs, for the commands it left running. */
+    get pid(): number | null;
+    /**
+     * The handle for reattaching after a coordinator restart, or null when
+     * this process cannot survive a restart.
+     */
+    get handle(): ProcessHandle | null;
+    /** The agent's session, once it has opened one. */
+    get sessionId(): string | null;
+    /** Where it runs; null for a log too old to say. */
+    get cwd(): string | null;
+    /**
+     * When it was archived, or when it started for a log too old to say; null
+     * while it is not archived.
+     */
+    get archivedSince(): string | null;
+    /** Whether a checkpoint has ended and nothing has been said since. */
+    get stoppedByCheckpoint(): boolean;
+    now(): string;
+    /** Says `text` to the agent, with `files` (see `ConversationTurns`). */
+    prompt(text: string, files?: Upload[], from?: Device, opts?: PromptOptions): Promise<void>;
+    /** Takes back the `index`th queued message, answering with its words and files. */
+    unqueue(index: number): {
+        text: string;
+        files: Attached[];
+    };
+    /** Sends what is queued now, stopping the running turn first. */
+    sendNow(): Promise<void>;
+    /** Stops the agent's turn for the person, and stays open for the next. */
+    cancel(): Promise<void>;
+    /** Asks the agent to bring its `SPLATES.md` up to date and stop (see `ConversationTurns`). */
+    checkpoint(merging: boolean): Promise<void>;
+    /**
+     * Checkpoints the agent for the person, as `checkpoint` does, and leaves
+     * it stopped there: nothing resumes a pause, and Power leaves it alone.
+     */
+    pause(merging: boolean): Promise<void>;
+    /** Forgets the checkpoint, done or not, so the next starts afresh. */
+    dismissCheckpoint(): void;
+    /** Settles once the checkpoint asked is no longer under way. */
+    answered(): Promise<void>;
+    /** Settles the agent's pending ask, if `id` is still the one it is on. */
+    answer(id: string, answer: Answer): void;
+    /** The file `name` the person sent, or null when they sent none by that name. */
+    attachment(name: string): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+    /** Keeps the plan's windows in `limits`, asked of the agent's maker. */
+    hear(limits: Limit[]): void;
+    /** Stops background command `id`, leaving the agent's turn as it is. */
+    stopBackground(id: string): Promise<void>;
+    /** What background command `id` has printed, then more as it prints it. */
+    backgroundOutput(id: string): ReadableStream<Uint8Array>;
+    /**
+     * Sets the session's setting `id` to `value`, one the agent offers: at once
+     * while the agent runs, or, while it is stopped, when it next resumes.
+     */
+    choose(id: string, value: string): Promise<void>;
+    /**
+     * Brings a stopped conversation back: a new process, the same session, or
+     * a new one when its agent died before opening one.
+     */
+    resume(): Promise<void>;
+    /**
+     * Follows the agent into a task's worktree, or back to the main tree: a
+     * running session keeps the directory it opened in, and the agent works by
+     * absolute path; a resumed one opens in the new.
+     */
+    move(task: string | null, cwd: string, base?: string | null, caller?: string | null): void;
+    /** Stops the agent; the next prompt resumes where it left off. */
+    stop(): Promise<void>;
+    /**
+     * Lets go of the agent's process without ending it, for a coordinator
+     * started again to take back from the worker: its log, flushed, says
+     * where it stopped. Answers whether there was one to let go of; a
+     * conversation with none, or one nothing could take back, stops as ever.
+     */
+    detach(): Promise<boolean>;
+    /**
+     * Stops it and puts it away, off the list of conversations; `with`, the
+     * conversation whose archiving takes it along, which brings it back.
+     * Its artifacts keep only what their panel shows.
+     */
+    archive(withConversation?: string): Promise<void>;
+    /** Names it `name` over the agent's title; blank goes back to the title. */
+    rename(name: string): Promise<void>;
+    /** Back on the list, stopped until the next prompt. */
+    unarchive(): Promise<void>;
+    /** Keeps it atop the list, or lets it go back among the rest. */
+    pin(pinned: boolean): Promise<void>;
+    /**
+     * Nests it in the list under the conversation `id`, or at the top for
+     * null, over where its task would, cutting it loose from the conversation
+     * that started it or added its task: that one no longer tells it, hears
+     * from it, or archives it along. Never for a subagent, which stays with
+     * the one it answers to.
+     */
+    reparent(id: string | null): Promise<void>;
+    /** Settles once everything said so far is in its log, for a reader of the file. */
+    saved(): Promise<void>;
+    /** Marks it seen, or unseen again for the person to come back to. */
+    markUnread(unread: boolean): Promise<void>;
+    /** Stops it and deletes its log and files, for good. */
+    delete(): Promise<void>;
+    dispose(): void;
+    /** Marks it `unread` or not, keeping how much was seen when it was read. */
+    flag(unread: boolean): void;
+    /** Back to idle once a turn ends, then on to what was queued meanwhile. */
+    ended(error: string | null): void;
+    /** Ends the agent's process, with `error` for one that failed, and keeps that it stopped. */
+    close(error: string | null): Promise<void>;
+    set(next: Partial<ConversationState>): void;
+    changed(): void;
+    /**
+     * Stops an agent left idle `IDLE_STOP`, with no command running in the background,
+     * no question open and no checkpoint, so its process exits and takes what
+     * it started along, MCP servers and browsers included. The next prompt
+     * resumes the same session.
+     */
+    private rest;
+    /** Opens the agent in `cwd`, clearing `opening` once it has or failed to. */
+    private wake;
+}
+/** What a conversation is opened with, started afresh or brought in. */
+interface Opening {
+    id: string;
+    agent: Agent;
+    task: string | null;
+    /** The branch `task` was cut from. */
+    base?: string | null;
+    /** The conversation whose agent added `task`. */
+    caller?: string | null;
+    cwd: string;
+    log: string;
+    /** Started on what a todo or `splates add --agent` assigned. */
+    assigned?: boolean;
+    /** The conversation that handed it its task, which it answers to. */
+    handedBy?: string | null;
+    /** The lane orchestrator that handed it its task, which hears when it stops. */
+    startedBy?: string | null;
+    /** The project's splates skill version as it starts; null when it has none. */
+    skill?: string | null;
+}
+export {};

package/conversations.d.ts

@@ -0,0 +1,140 @@
+import type { ConversationsOptions } from "./conversation-options.js";
+export type { ConversationsOptions } from "./conversation-options.js";
+import type { Resource } from "webappwiz/disposable";
+import { type Eventful } from "webappwiz/events";
+import { type Agent, type Session } from "./agent-process.js";
+import { Conversation } from "./conversation.js";
+import type { ConversationsEvents } from "./conversation-host.js";
+import type { Limit, Setting } from "./conversation-state.js";
+/** How many archived conversations are kept; older archived ones are deleted. */
+export declare const ARCHIVED_KEPT = 200;
+/**
+ * Every conversation in the repo: the live ones this process started, and
+ * the stopped ones read back from their logs, one JSON-lines file each under
+ * `.git/splates/conversations`.
+ */
+export declare class Conversations implements Eventful<ConversationsEvents>, Resource {
+    readonly dir: string;
+    readonly agents: Agent[];
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<ConversationsEvents>;
+    private readonly known;
+    private readonly fs;
+    private readonly ids;
+    private readonly launcher;
+    private readonly machine;
+    private readonly starting;
+    private readonly timer;
+    private readonly clock;
+    private readonly watch;
+    private readonly offered;
+    private readonly limited;
+    private readonly adherence;
+    private readonly outcomes;
+    private readonly readLimits;
+    private readonly root;
+    private readonly projects;
+    private readonly servers;
+    private readonly artifacts;
+    /** What every conversation's artifacts make room through, across the project. */
+    private readonly room;
+    /** The read of the records on disk, shared by every caller until it settles. */
+    private loaded;
+    /** The last deletion of archived conversations past `ARCHIVED_KEPT`, so they run one at a time. */
+    private pruning;
+    /** When each agent's limits were last asked for, by its id, in epoch ms. */
+    private readonly asked;
+    /** Where `splates server` answers, once it does, for the agents' CLI. */
+    url: string | null;
+    /** New starts use the refreshed roster; existing conversations retain their snapshot. */
+    refreshRoster(agents: Agent[]): void;
+    constructor(dir: string, agents: Agent[], opts?: ConversationsOptions);
+    /** What each conversation is made with. */
+    private get deps();
+    /**
+     * What each agent's sessions last offered, from any project, by its id:
+     * what a first conversation with one shows before it starts.
+     */
+    settings(): Promise<Record<string, Setting[]>>;
+    /**
+     * Each agent's plan limits as it last said, from any project, by its id:
+     * what a new conversation shows before one here says.
+     */
+    limits(): Promise<Record<string, Limit[]>>;
+    /**
+     * Asks each agent that does not send its limits for them, unless it was
+     * asked within `LIMITS_FRESH`, and keeps what it says for every project.
+     */
+    refreshLimits(): Promise<void>;
+    /** Every conversation, newest first. */
+    list(): Promise<Conversation[]>;
+    find(id: string): Promise<Conversation>;
+    /**
+     * Starts a conversation with `agent` in `cwd`, for `task` if it is one's,
+     * with `settings` set once the session offers them.
+     */
+    start(agent: string, { task, base, caller, cwd, settings, model, assigned, handedBy, startedBy, }: {
+        task: string | null;
+        /** The branch `task` was cut from. */
+        base?: string | null;
+        /** The conversation whose agent added `task`. */
+        caller?: string | null;
+        cwd: string;
+        settings?: Record<string, string>;
+        /** The model to start on, by its value or name in the model setting. */
+        model?: string;
+        /** Whether a todo or `splates add --agent` assigned the agent and model. */
+        assigned?: boolean;
+        /** The conversation that handed it its task, which it answers to. */
+        handedBy?: string | null;
+        /** The lane orchestrator that handed it its task, which hears when it stops. */
+        startedBy?: string | null;
+    }): Promise<Conversation>;
+    /**
+     * The sessions each agent holds in `cwd` that splates does not, such as ones
+     * started in its CLI, to bring in: newest first, from every agent that
+     * lists and loads sessions.
+     */
+    sessions(cwd: string): Promise<Session[]>;
+    /**
+     * Brings in `session`, one `agent` holds outside splates, as a conversation
+     * in `cwd`, for `task` if it is one's.
+     */
+    bring(agent: string, session: string, { task, base, caller, cwd, title, }: {
+        task: string | null;
+        /** The branch `task` was cut from. */
+        base?: string | null;
+        /** The conversation whose agent added `task`. */
+        caller?: string | null;
+        cwd: string;
+        title?: string | null;
+    }): Promise<Conversation>;
+    /**
+     * Deletes the archived conversations past the `ARCHIVED_KEPT` archived
+     * most recently, so their logs do not pile up, their artifacts and
+     * attached files going with them.
+     */
+    prune(): Promise<void>;
+    /** Stops every live conversation, so no agent outlives the server. */
+    disposeAsync(): Promise<void>;
+    /**
+     * Lets go of every agent a worker runs, for a coordinator started again
+     * to take back, and says whether there was any: the rest stop as ever.
+     */
+    detachAsync(): Promise<boolean>;
+    dispose(): void;
+    private track;
+    /** Asks for `conversation`'s agent's limits, when it does not send them. */
+    private askLimits;
+    private load;
+    private trim;
+    private read;
+}
+export type { Agent, AgentProcess, Launch, Launcher, Session, } from "./agent-process.js";
+export { launch } from "./agent-process.js";
+export type { Artifact, ArtifactGone, ArtifactVersion, } from "./artifacts.js";
+export { Conversation } from "./conversation.js";
+export type { ConversationEvents, ConversationsEvents, } from "./conversation-host.js";
+export type { After, Answer, Ask, Attached, Background, BackgroundState, Checkpoint, Command, Compaction, ConversationState, Decision, Device, Edit, Field, Image, Limit, Message, Part, Setting, Status, Step, Taking, Tool, Upload, Usage, } from "./conversation-state.js";
+export { DEVICES, FROM_HEADER, unused } from "./conversation-state.js";
+export { fold, heard } from "./fold.js";

package/coordinator-state.d.ts

@@ -0,0 +1,28 @@
+import type { Fs } from "webappwiz/system";
+import type { KeptShell } from "./dev-shell.js";
+/**
+ * What one `splates server` keeps across its own restarts, in
+ * `~/.splates/coordinator.json`: the session id its workers know it by, so a
+ * worker finds the next run unchanged and keeps every agent it runs for it,
+ * and the roots of the projects whose agents it let go of at its last
+ * restart, for the next run to serve before the worker joins and take them
+ * back, and the shells it let go of, for the next run to take back too.
+ */
+export declare class CoordinatorState {
+    readonly path: string;
+    private readonly fs;
+    /** What this coordinator's worker sessions answer as, the same across restarts. */
+    readonly session: string;
+    /** The projects with agents on the worker at the last restart; none after a fresh start. */
+    readonly roots: string[];
+    /** The pages' shells on the worker at the last restart, by key. */
+    readonly terminals: KeptShell[];
+    private constructor();
+    /**
+     * Reads what the last run kept at `path`, or starts afresh with a session
+     * of its own, written there so the next run answers as the same.
+     */
+    static open(path: string, fs: Fs): Promise<CoordinatorState>;
+    /** Keeps `roots` as the projects whose agents, and `terminals` as the shells, the next run takes back. */
+    write(roots: string[], terminals: KeptShell[]): Promise<void>;
+}

package/creds.d.ts

@@ -0,0 +1,123 @@
+import { Credentials, type SecretStore } from "webappwiz/creds";
+import { type Fs, type Lock } from "webappwiz/system";
+import { Duration } from "webappwiz/time";
+import { z } from "zod";
+/** Where a cred is kept: for this project alone, or every project on this device. */
+export declare const SCOPES: readonly ["project", "device"];
+export type Scope = (typeof SCOPES)[number];
+/** How long `wait` gives a request before handing the wait back to its caller. */
+export declare const DEFAULT_TIMEOUT: Duration;
+/** The two stores a cred can be kept in, the system's unless a test says otherwise. */
+export interface SecretStores {
+    /** The store of the project whose main tree is at `root`. */
+    project(root: string): Promise<SecretStore>;
+    device: SecretStore;
+}
+/** The operating system's own stores, shared with `wiz creds`. */
+export declare const SYSTEM_STORES: SecretStores;
+declare const REQUEST: z.ZodObject<{
+    name: z.ZodString;
+    scope: z.ZodEnum<{
+        device: "device";
+        project: "project";
+    }>;
+    purpose: z.ZodDefault<z.ZodString>;
+    instructions: z.ZodString;
+    task: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        dismissed: "dismissed";
+        open: "open";
+        saved: "saved";
+    }>;
+    requestedAt: z.ZodString;
+}, z.core.$strip>;
+/** A cred an agent asked a person for, with what for and how to get it. */
+export type CredRequest = z.infer<typeof REQUEST>;
+/** A cred a store keeps, by name; never its value. */
+export interface KeptCred {
+    name: string;
+    scope: Scope;
+    /** The tool that saved it, when one said so; null when a person did. */
+    savedBy: string | null;
+}
+/**
+ * A project's creds: the requests agents make for them, which `splates server`
+ * shows on its Creds page for a person to fill, and the two stores they are
+ * kept in, the project's and the device's, as `wiz creds` keeps them. A value
+ * goes into a store and never comes out through here but to code reading it
+ * through `credentials`, so no agent, page or log ever holds it.
+ */
+export declare class Creds {
+    #private;
+    /** The record of requests, `.git/splates/creds.json`. */
+    readonly file: string;
+    /** Held while the record is read and written back. */
+    private readonly lock;
+    private readonly stores;
+    constructor(
+    /** The record of requests, `.git/splates/creds.json`. */
+    file: string, 
+    /** Held while the record is read and written back. */
+    lock: Lock, stores: Record<Scope, SecretStore>, opts?: {
+        fs?: Fs;
+    });
+    /** The project's creds, kept in `stores`. */
+    static open(splatesDir: string, root: string, lock: Lock, stores: SecretStores, opts?: {
+        fs?: Fs;
+    }): Promise<Creds>;
+    /**
+     * Where code reads a cred's value: the project's store, then the device's.
+     * Never the environment, so a stray export is not what splates reads.
+     */
+    get credentials(): Credentials;
+    /** Every request, open or not, the latest first. */
+    requests(): Promise<CredRequest[]>;
+    /**
+     * Asks a person for `name`, saying what for, kept in `scope`'s store once they save it.
+     * Asks nothing, returning null, when that store already keeps it, unless
+     * `replace` says the value kept there does not work, and then a purpose or
+     * instructions left off are those of the last request for `name`.
+     */
+    request(name: string, { scope, purpose, instructions, task, replace, }: {
+        scope: Scope;
+        purpose: string;
+        instructions: string;
+        task: string | null;
+        replace?: boolean;
+    }): Promise<CredRequest | null>;
+    /**
+     * Blocks until a person fills or dismisses the request for `name`,
+     * returning what became of it; gives up with `timeout`.
+     */
+    wait(name: string, { timeout, poll, }?: {
+        timeout?: Duration;
+        poll?: Duration;
+    }): Promise<"saved" | "dismissed">;
+    /**
+     * Keeps `value` as `name`, filling its request if one is open, in the
+     * request's scope, else in `scope`. `by` names the tool saving it, for
+     * the page to say; a person's own save says nothing.
+     */
+    save(name: string, value: string, { scope, by }?: {
+        scope?: Scope;
+        by?: string | null;
+    }): Promise<Scope>;
+    /** Turns down the open request for `name`, so its agent stops waiting. */
+    dismiss(name: string): Promise<void>;
+    /** Deletes `name` from `scope`'s store; whether there was one. */
+    remove(name: string, scope: Scope): Promise<boolean>;
+    /**
+     * Copies each cred kept under arbor's `ARBOR_*` name to its `SPLATES_*`
+     * one in the same store, unless that is kept already. The old one stays,
+     * for an arbor still running, and any record naming it, to read.
+     */
+    copyLegacy(): Promise<void>;
+    /** Every cred either store keeps, the project's first, by name. */
+    kept(): Promise<KeptCred[]>;
+    /** What a person calls `scope`'s store, as in "the macOS Keychain". */
+    label(scope: Scope): string;
+    private has;
+    private read;
+    private change;
+}
+export {};

package/darwin-temperature.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The hottest CPU die sensor on an Apple Silicon Mac, in °C, or null when
+ * none answers. macOS has no public API for these, and `powermetrics` needs
+ * sudo, so this asks IOKit's private HID event system the way macmon and
+ * Stats do, which any user may.
+ */
+export declare function darwinTemperature(): number | null;

package/decided.d.ts

@@ -0,0 +1,18 @@
+import type { Outcome } from "./outcomes.js";
+import type { Decision } from "./plan.js";
+/**
+ * Who made `decision`: the person, for one put to them or an assumption
+ * they challenged, which took their attention either way; otherwise the
+ * agent, whose assumption stood without them.
+ */
+export declare function whose(decision: Pick<Decision, "how" | "ended">): "decidedByYou" | "decidedByAgents";
+/** How many calls in `outcome` `who` made. */
+export declare function madeBy(outcome: Outcome, who: ReturnType<typeof whose>): number;
+/**
+ * The calls `outcome` made, each with how many it stands for: its own
+ * decisions one each, or for a line from before they were kept, its counts
+ * read back as unsized calls.
+ */
+export declare function decided(outcome: Outcome): [Pick<Decision, "size" | "how" | "ended">, number][];
+/** Whether `outcome` kept its calls at all: lines from before any were kept say nothing of them. */
+export declare function keptDecisions(outcome: Outcome): boolean;

package/demo.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Something to try, as the skill writes it under `### 🎬 Demo: <title>`:
+ * where, then numbered steps.
+ */
+export interface Demo {
+    /** What it shows, from its heading; null when the heading says none. */
+    title: string | null;
+    /** Where to try it and anything said before the steps, as markdown. */
+    intro: string;
+    steps: Step[];
+}
+/** A step of a demo: what to do, on its line, and what to see, under it. */
+export interface Step {
+    number: string;
+    action: string;
+    /** What should happen, screenshots included, as markdown. */
+    expect: string;
+}
+/**
+ * The demo titled at `start`: what it says up to its steps, or to `until`,
+ * where something else begins, then its steps, and the line after them; null
+ * for any other line.
+ */
+export declare function demoAt(lines: string[], start: number, until: number): {
+    demo: Demo;
+    end: number;
+} | null;
+/** Whether `line` titles a demo. */
+export declare function isDemoTitle(line: string): boolean;