@stringsync/splates 0.0.0-stage → 0.0.45

package/fake-agent.js

@@ -0,0 +1,284 @@
+import {
+  framed2
+} from "./index-d4hjrzaq.js";
+import"./index-k73tsw5g.js";
+
+// fake-agent.ts
+import * as acp from "@agentclientprotocol/sdk";
+var AGENT = { id: "fake", name: "Fake", argv: ["fake-acp"] };
+var ROSTERED = {
+  ...AGENT,
+  models: [
+    { id: "big", name: "Big", strengths: "hard problems", cost: "high" },
+    { id: "small", name: "Small", strengths: "quick edits", cost: "low" }
+  ]
+};
+
+class FakeAgent {
+  turn = async () => "end_turn";
+  cancelled = 0;
+  resumed = [];
+  steering = null;
+  steered = [];
+  beforeSteer = async () => {};
+  lists = false;
+  subscribed = [];
+  capabilities = null;
+  stoppedBackground = [];
+  sees = false;
+  usage = null;
+  held = null;
+  loaded = [];
+  opened = [];
+  http = false;
+  mcp = [];
+  prompts = [];
+  chosen = [];
+  options = structuredClone(OPTIONS);
+  resumes = true;
+  protocolVersion = acp.PROTOCOL_VERSION;
+  disconnect = () => {};
+  ignoreChoices = false;
+  hold = null;
+  dying = 0;
+  stderr = "fake agent fell over";
+  launched = [];
+  killed = 0;
+  pid = null;
+  exit = () => {};
+  launch = (argv, cwd, env) => {
+    this.launched.push({ argv, cwd, env });
+    const toAgent = new TransformStream;
+    const toClient = new TransformStream({
+      start: (controller) => {
+        this.disconnect = () => controller.terminate();
+      }
+    });
+    new acp.AgentSideConnection((client) => this.agent(client), acp.ndJsonStream(toClient.writable, toAgent.readable));
+    const exited = new Promise((resolve) => {
+      this.exit = resolve;
+    });
+    return {
+      pid: this.pid,
+      input: toAgent.writable,
+      output: framed2(toClient.readable),
+      ack: () => {},
+      handle: null,
+      stderr: () => this.stderr,
+      exited,
+      kill: () => {
+        this.killed++;
+      }
+    };
+  };
+  crash() {
+    this.exit(1);
+  }
+  async say(update) {
+    await this.client?.sessionUpdate({ sessionId: "s1", update });
+  }
+  async list(state, endedAt) {
+    await this.client?.extNotification("_session/list/changes", {
+      subscriptionId: "list-1",
+      sessions: [
+        {
+          sessionId: "s1",
+          cwd: this.subscribed.at(-1) ?? "/",
+          _meta: {
+            jetbrains: {
+              air: {
+                state,
+                ...endedAt === undefined ? {} : { lastTurnEndedAt: endedAt }
+              }
+            }
+          }
+        }
+      ]
+    });
+  }
+  client = null;
+  agent(client) {
+    this.client = client;
+    return {
+      initialize: async ({ clientCapabilities }) => {
+        if (this.dying > 0) {
+          this.dying--;
+          this.exit(1);
+          throw new Error("ACP connection closed");
+        }
+        await this.hold;
+        this.capabilities = clientCapabilities ?? null;
+        return {
+          protocolVersion: this.protocolVersion,
+          agentCapabilities: {
+            ...this.http ? { mcpCapabilities: { http: true } } : {},
+            ...this.sees ? { promptCapabilities: { image: true } } : {},
+            loadSession: this.held !== null,
+            sessionCapabilities: {
+              ...this.resumes ? { resume: {} } : {},
+              ...this.held === null ? {} : { list: {} }
+            }
+          },
+          _meta: {
+            ...this.steering === null ? {} : { steering: { supported: true } },
+            ...this.lists ? {
+              jetbrains: {
+                air: { version: 1, capabilities: ["sessionListSubscribe"] }
+              }
+            } : {}
+          }
+        };
+      },
+      extMethod: async (method, params) => {
+        if (method === "_session/async_task/stop") {
+          const id = String(params.asyncTaskId);
+          this.stoppedBackground.push(id);
+          await client.sessionUpdate({
+            sessionId: String(params.sessionId),
+            update: backgroundEnded(id, "stopped")
+          });
+          return { stopped: true };
+        }
+        if (method === "_session/list/subscribe" && this.lists) {
+          this.subscribed.push(String(params.cwd));
+          return { subscriptionId: "list-1" };
+        }
+        if (method !== "_session/steering" || this.steering === null) {
+          throw acp.RequestError.methodNotFound(method);
+        }
+        const prompt = params.prompt;
+        await this.beforeSteer();
+        if (this.steering === "injected" || this.steering === "startedNewTurn") {
+          this.steered.push(prompt.map((block) => block.type === "text" ? block.text : "").join(""));
+        }
+        return { outcome: this.steering };
+      },
+      newSession: async ({ _meta, mcpServers }) => {
+        this.opened.push(_meta);
+        this.mcp.push(mcpServers);
+        return { sessionId: "s1", configOptions: this.options };
+      },
+      listSessions: async ({ cwd }) => ({
+        sessions: (this.held ?? []).filter((each) => cwd == null || each.cwd === cwd).map(({ replay: _, ...info }) => info)
+      }),
+      loadSession: async ({ sessionId, _meta, mcpServers }) => {
+        this.opened.push(_meta);
+        this.mcp.push(mcpServers);
+        const session = this.held?.find((each) => each.sessionId === sessionId);
+        if (session === undefined) {
+          throw acp.RequestError.resourceNotFound(sessionId);
+        }
+        this.loaded.push(sessionId);
+        for (const update of session.replay) {
+          await client.sessionUpdate({ sessionId, update });
+        }
+        return { configOptions: this.options };
+      },
+      resumeSession: async ({ sessionId, _meta, mcpServers }) => {
+        this.opened.push(_meta);
+        this.mcp.push(mcpServers ?? []);
+        this.resumed.push(sessionId);
+        return { configOptions: this.options };
+      },
+      authenticate: async () => ({}),
+      setSessionConfigOption: async ({ configId, value }) => {
+        this.chosen.push({ configId, value });
+        this.options = this.options.map((option) => option.id === configId && !this.ignoreChoices ? {
+          ...option,
+          currentValue: typeof value === "boolean" ? value : String(value)
+        } : option);
+        return { configOptions: this.options };
+      },
+      prompt: async ({ sessionId, prompt }) => {
+        this.prompts.push(prompt);
+        return {
+          stopReason: await this.turn(client, sessionId, prompt.map((block) => block.type === "text" ? block.text : "").join("")),
+          usage: this.usage
+        };
+      },
+      cancel: async () => {
+        this.cancelled++;
+      }
+    };
+  }
+}
+function heard(text) {
+  return {
+    sessionUpdate: "user_message_chunk",
+    content: { type: "text", text }
+  };
+}
+function say(text) {
+  return {
+    sessionUpdate: "agent_message_chunk",
+    content: { type: "text", text }
+  };
+}
+function backgroundStarted(id, description, tool, taskType = "shell", output) {
+  return {
+    sessionUpdate: "async_task_spawned",
+    asyncTaskId: id,
+    name: description,
+    taskType,
+    description,
+    showInTranscript: true,
+    canStop: true,
+    toolCallId: tool,
+    ...output === undefined ? {} : { outputFilePath: output }
+  };
+}
+function backgroundEnded(id, state) {
+  return {
+    sessionUpdate: "async_task_state_update",
+    asyncTaskId: id,
+    state
+  };
+}
+function backgroundWrites(id, output) {
+  return {
+    sessionUpdate: "async_task_progress",
+    asyncTaskId: id,
+    outputFilePath: output
+  };
+}
+var OPTIONS = [
+  {
+    id: "mode",
+    name: "Mode",
+    category: "mode",
+    type: "select",
+    currentValue: "ask",
+    options: [
+      { value: "ask", name: "Ask" },
+      { value: "auto", name: "Auto" }
+    ]
+  },
+  {
+    id: "model",
+    name: "Model",
+    category: "model",
+    type: "select",
+    currentValue: "big",
+    options: [
+      { value: "big", name: "Big" },
+      { value: "small", name: "Small", description: "Fast" }
+    ]
+  },
+  {
+    id: "fast",
+    name: "Fast mode",
+    category: "model_config",
+    type: "boolean",
+    currentValue: false
+  }
+];
+export {
+  AGENT,
+  FakeAgent,
+  ROSTERED,
+  backgroundEnded,
+  backgroundStarted,
+  backgroundWrites,
+  heard,
+  say
+};

package/finding-facts.d.ts

@@ -0,0 +1,38 @@
+import type { Finding } from "./findings.js";
+import type { Landed } from "./landed.js";
+/** One thing that went worse than it could have, as the merged card says it. */
+export interface Fact {
+    text: string;
+    /** "3rd time this week" when it came up before in its project; null otherwise. */
+    again: string | null;
+    /** What it was found from; null for an older outcome's count of failed merges. */
+    finding: Finding | null;
+}
+/** What went worse in a merged task: the gate's turn-aways, and the rest. */
+export interface FoundFacts {
+    /** Null when the gate passed it the first time. */
+    gate: Fact[] | null;
+    /** Most severe first. */
+    findings: Fact[];
+}
+/** A todo made of a fact: its line, and what more there is to say. */
+export interface FactTodo {
+    subject: string;
+    text: string;
+}
+/** The findings that are not the gate's, the most worth acting on first. */
+export declare const SEVERITY: Finding["kind"][];
+/** What went worse in `landed`, from what its outcome kept. */
+export declare function foundFacts({ outcome, baseline }: Landed): FoundFacts;
+/**
+ * Findings the merged card lists but no todo is made of: the person's own
+ * calls on the agent's picks, which are asking working as meant.
+ */
+export declare const UNTODOED: Finding["kind"][];
+/**
+ * The todos `splates merge` adds for what went worse in `landed`, the gate's
+ * first: one a fact, as the merged card lists them, but for `UNTODOED`.
+ */
+export declare function factTodos(landed: Landed): FactTodo[];
+/** The todo made of `fact`, found in `task` as it merged. */
+export declare function deferred(task: string, fact: Fact): FactTodo;

package/findings.d.ts

@@ -0,0 +1,84 @@
+import type { Judged } from "./adherence.js";
+import type { TaskLog } from "./task-log.js";
+import type { GateFailure } from "./worktree.js";
+/** What went worse than it could have, in the order `Finding` lists the kinds. */
+export declare function findings(evidence: Evidence): Finding[];
+/**
+ * Where a finding starts: each tuned here, so a finding that fires too often
+ * or too rarely is one number to change.
+ */
+export declare const FINDING_THRESHOLDS: {
+    /** A command failing this many times in one task. */
+    readonly repeatedFailures: 3;
+    /** Lines edited this many times over the lines that landed. */
+    readonly churnRatio: 4;
+    /** And at least this many lines edited, so a small task's retouching is not churn. */
+    readonly churnLines: 300;
+    /** A skill check passed less than this share of the times it applied. */
+    readonly adherenceBelow: 0.5;
+};
+/**
+ * Something that went worse than it could have in one task, kept with what it
+ * names, so a later count can tell how often each kind recurs.
+ */
+export type Finding = 
+/** The gate turned it away, even once. */
+({
+    kind: "gate";
+} & GateFailure)
+/** `splates retry` granted it more merge attempts. */
+ | {
+    kind: "retried";
+    times: number;
+}
+/** The person stopped the agent's turn. */
+ | {
+    kind: "stopped";
+    at: string;
+}
+/** A lost connection cut the agent's turn short. */
+ | {
+    kind: "interrupted";
+    at: string;
+}
+/** The person answered picks with another choice than the agent's. */
+ | {
+    kind: "overturned";
+    picks: number;
+}
+/** The person challenged assumptions the agent made. */
+ | {
+    kind: "challenged";
+    assumptions: number;
+}
+/** One command failed again and again. */
+ | {
+    kind: "repeated_failure";
+    command: string;
+    times: number;
+}
+/** Far more lines edited than landed. */
+ | {
+    kind: "churn";
+    edited: number;
+    landed: number;
+}
+/** A skill check its conversation mostly failed. */
+ | {
+    kind: "adherence";
+    check: string;
+    passed: number;
+    failed: number;
+};
+/** What a task leaves to find in, each part absent when it was not kept. */
+export interface Evidence {
+    gateFailures: GateFailure[];
+    retries: number;
+    picksOverturned: number;
+    assumptionsChallenged: number;
+    log: TaskLog | null;
+    /** Lines the landed diff added and removed; null when unknown. */
+    landedLines: number | null;
+    /** Its conversation's skill checks as last judged; null when unjudged. */
+    adherence: Judged | null;
+}

package/fold.d.ts

@@ -0,0 +1,43 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type { ConversationState, Field, Limit, Message, Setting } from "./conversation-state.js";
+/**
+ * Folds one ACP update, sent `at`, into the messages: text runs on in the
+ * message it started, and a tool call is one part that fills in as it runs.
+ */
+export declare function fold(state: ConversationState, update: acp.SessionUpdate, at?: string | null): void;
+/**
+ * The windows Claude's rate limit info in `update` tells of: every one in
+ * `unifiedWindows` when it sends them, else the one it names. Its
+ * `utilization` runs from 0 to 1, and `resetsAt` is in seconds.
+ */
+export declare function limitsIn(update: acp.UsageUpdate, at: string | null): Limit[];
+/** `limits`, each window in `news` replaced by what it says now. */
+export declare function heard(limits: Limit[], news: Limit[]): Limit[];
+/** Adds the tokens a turn used to those of the turns before it. */
+export declare function tally(state: ConversationState, usage: acp.Usage): void;
+/**
+ * The agent's message at the end, started if the person spoke last, marked
+ * as having moved `at`. Queued messages stay below it: the agent has yet to
+ * hear them, so nothing it says meanwhile answers them.
+ */
+export declare function agentTurn(state: ConversationState, at: string | null): Message;
+/** Marks the agent's message at the end, if it is the last, as having moved `at`. */
+export declare function moved(state: ConversationState, at: string | null): void;
+/** Whether `update` is the agent at work, as it is only in a turn. */
+export declare function starts(update: acp.SessionUpdate): boolean;
+/**
+ * Whether `update` ends a turn: Claude says where each turn came from in the
+ * usage it sends at the turn's end, and only then.
+ */
+export declare function result(update: acp.SessionUpdate): boolean;
+/** The session's settings the agent lets the person pick from, in its order. */
+export declare function settingsIn(options: acp.SessionConfigOption[] | null | undefined): Setting[];
+/** `value` for `setting` as ACP sets it: a toggle's as a boolean. */
+export declare function configValue(setting: Setting, value: string): {
+    type: "boolean";
+    value: boolean;
+} | {
+    value: string;
+};
+/** A form an agent asks with, as the fields the page shows. */
+export declare function fieldsIn(schema: unknown): Field[];

package/follow.d.ts

@@ -0,0 +1,41 @@
+import type { Logger } from "webappwiz/log";
+import type { Ps } from "webappwiz/system";
+import type { Git } from "./git.js";
+import type { Projects } from "./projects.js";
+/** What `fetch` is used for here, so a test can stand in for it. */
+type Send = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Tells `splates server` that the agent in a conversation took or left a task, so
+ * the conversation follows it into that worktree, or back to the main tree.
+ * An agent started from the page runs with its conversation and the server
+ * in its env; any other `splates` has neither, and says nothing. A server that
+ * cannot be reached is worth a line, never a failure: the task command has
+ * done its work.
+ */
+export declare function follow({ ps, log, send }: {
+    ps: Ps;
+    log: Logger;
+    send?: Send;
+}, task: string | null, { from, base, }?: {
+    /** The task being left; given, the conversation moves only out of it. */
+    from?: string;
+    /**
+     * The branch `task` lands on, for an add to send before the task's
+     * record names it, so the server can tell a part from a task to follow.
+     */
+    base?: string;
+}): Promise<void>;
+/**
+ * Asks `splates server` to serve the project `git` is in, so the agent a task
+ * there was just handed to from another project starts: the server opens a
+ * project only once something asks for it. Outside `splates server` it says
+ * nothing; a server that cannot be reached is worth a line.
+ */
+export declare function serveProject({ ps, log, git, projects, send, }: {
+    ps: Ps;
+    log: Logger;
+    git: Git;
+    projects: Projects;
+    send?: Send;
+}): Promise<void>;
+export {};

package/format.d.ts

@@ -0,0 +1,68 @@
+import type { Logger } from "webappwiz/log";
+import type { Fs, Lock } from "webappwiz/system";
+/**
+ * One step forward in the format of the records under `.git/splates`: from the
+ * version before it to its own. A step can be interrupted and run again, and
+ * finds no records to change in a repository that has none yet.
+ */
+export interface Migration {
+    /** What the step changes, said as it runs: "moves lanes into their own files". */
+    does: string;
+    run(splatesDir: string, fs: Fs): Promise<void>;
+}
+/**
+ * Every step from version 1, in order: the one at index 0 takes records from
+ * version 1 to 2. Forward only; splates never writes an older format.
+ */
+export declare const MIGRATIONS: readonly Migration[];
+/**
+ * The version of the records under `.git/splates` this splates reads and writes:
+ * tasks, todos, lanes, the journal and conversations, as one. A change an
+ * older splates would misread adds a step to `MIGRATIONS`, which moves it on.
+ */
+export declare const FORMAT: number;
+/** What a `Format` works with. */
+export interface FormatOptions {
+    fs: Fs;
+    /** Held while migrating, so two commands never run the same step at once. */
+    lock: Lock;
+    log: Logger;
+    /** The steps from version 1; a test passes its own. */
+    migrations?: readonly Migration[];
+}
+/** The format of one repository's records, kept in `<splatesDir>/format`. */
+export declare class Format {
+    readonly splatesDir: string;
+    private readonly fs;
+    private readonly lock;
+    private readonly log;
+    private readonly migrations;
+    private readonly path;
+    constructor(splatesDir: string, { fs, lock, log, migrations }: FormatOptions);
+    /** The version this splates reads and writes. */
+    get current(): number;
+    /**
+     * Makes the repository a splates project, as only `splates init` does: stamps
+     * records from before formats were stamped as version 1, and a repository
+     * with none yet as this splates's. Leaves stamped records alone.
+     */
+    create(): Promise<void>;
+    /**
+     * Refuses records in any format but this splates's, which it would misread or
+     * overwrite: a newer one until splates is updated, an older one until
+     * `splates server` has migrated it. Refuses a repository with none stamped
+     * until `splates init` has made it a splates project.
+     */
+    check(): Promise<void>;
+    /**
+     * Moves older records forward to this splates's format, a step at a time,
+     * then checks them as `check` does.
+     */
+    migrate(): Promise<void>;
+    /**
+     * The stored version, or null for records from before formats were
+     * stamped, which are version 1. Refuses one this splates cannot read.
+     */
+    private stored;
+    private write;
+}

package/git.d.ts

@@ -0,0 +1,112 @@
+import { type Fs, type Ps } from "webappwiz/system";
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Every git call splates makes, scoped to one repository. Agents are not allowed
+ * to run these themselves, since going through splates is what makes concurrent
+ * work safe, so this is the only place git is spoken.
+ */
+/** What a `Git` works through; the real ones by default. */
+export interface GitOptions {
+    ps?: Ps;
+    fs?: Fs;
+}
+/** One commit as `Git.log` reads it. */
+export interface Commit {
+    hash: string;
+    /** When it was written, as ISO 8601. */
+    at: string;
+    author: string;
+    /** Its message's first line. */
+    subject: string;
+    /** The paths it changed, repo-relative. */
+    files: string[];
+}
+export declare class Git {
+    /** The main worktree, where trunk lives. */
+    readonly root: string;
+    private readonly ps;
+    private readonly fs;
+    constructor(
+    /** The main worktree, where trunk lives. */
+    root: string, opts?: GitOptions);
+    run(cwd: string, ...args: string[]): Promise<GitResult>;
+    out(cwd: string, ...args: string[]): Promise<string>;
+    branchExists(branch: string): Promise<boolean>;
+    /**
+     * The branch `origin/HEAD` points at, or null when the repo has no such ref:
+     * no remote, or a clone that never fetched it.
+     */
+    defaultBranch(): Promise<string | null>;
+    /**
+     * The branch checked out at `cwd`, or null where there is none: a detached
+     * HEAD, or a directory outside any repository. Any other failure throws, so
+     * it is not mistaken for being off a task's branch.
+     */
+    currentBranch(cwd: string): Promise<string | null>;
+    head(cwd: string): Promise<string>;
+    shortHead(cwd: string): Promise<string>;
+    porcelain(cwd: string): Promise<string[]>;
+    conflictedPaths(cwd: string): Promise<string[]>;
+    commitsAhead(trunk: string, branch: string): Promise<number | null>;
+    /** When `ref`'s latest commit was committed, as ISO 8601; null when git cannot say. */
+    committedAt(ref: string): Promise<string | null>;
+    /**
+     * The message of each commit on `branch` since it left `trunk`, oldest
+     * first; null when git cannot say.
+     */
+    commitMessages(trunk: string, branch: string): Promise<string[] | null>;
+    /**
+     * What `branch` changed since it left `trunk`, as a unified diff, along
+     * with all the work still uncommitted in `worktree` when there is one, new
+     * files git does not track yet among it; `uncommitted` names the paths
+     * that have some. Untrimmed, since a diff's lines keep their leading spaces.
+     */
+    diff(trunk: string, branch: string, worktree: string | null): Promise<{
+        text: string;
+        uncommitted: string[];
+    } | null>;
+    /**
+     * Every path `branch` touches since it left `trunk`, plus what is still
+     * uncommitted in `worktree` when there is one: an agent mid-task has usually
+     * committed nothing yet, and its edits are the overlap that matters most.
+     */
+    changedFiles(trunk: string, branch: string, worktree: string | null): Promise<string[] | null>;
+    /**
+     * Every path a person might point an agent at in the tree at `cwd`: the
+     * files git tracks, the new ones it does not ignore, and each directory
+     * above them, which ends in `/`. Sorted, relative to the tree's root.
+     */
+    paths(cwd: string): Promise<string[]>;
+    /**
+     * The latest `count` commits on `ref`, newest first, each with the paths
+     * it changed. Empty when `ref` names nothing, as in a repo with no commit.
+     */
+    log(ref: string, count: number): Promise<Commit[]>;
+    /** Every path git tracks at `ref`, or none when `ref` names nothing. */
+    files(ref: string): Promise<string[]>;
+    rebase(cwd: string, onto: string): Promise<GitResult>;
+    resetHard(cwd: string, commit: string): Promise<GitResult>;
+    checkout(branch: string): Promise<GitResult>;
+    mergeFfOnly(cwd: string, branch: string): Promise<GitResult>;
+    /**
+     * The worktree with `branch` checked out, or null when no worktree has it.
+     * Git allows one worktree per branch and that is the only place the branch
+     * can be advanced, so this is where a fast-forward has to happen.
+     */
+    worktreeFor(branch: string): Promise<string | null>;
+    addWorktree(branch: string, path: string, from: string): Promise<GitResult>;
+    removeWorktree(path: string): Promise<GitResult>;
+    /** Drops metadata for worktrees whose directories are gone. */
+    pruneWorktrees(): Promise<GitResult>;
+    deleteBranch(branch: string): Promise<GitResult>;
+    /** The one `.git` every worktree of this repo shares. */
+    commonDir(): Promise<string>;
+    /** The git directory belonging to a worktree, or null if it has none. */
+    worktreeGitDir(worktree: string): Promise<string | null>;
+    /** Half-finished merges and rebases a resuming agent is standing in. */
+    interruptedOps(worktree: string): Promise<string[]>;
+}