@stringsync/splates 0.0.0-stage → 0.0.45

package/asked.d.ts

@@ -0,0 +1,146 @@
+import { type Assumed } from "./assumed.js";
+import { type Demo } from "./demo.js";
+import { type Question } from "./plan.js";
+/**
+ * `text` cut where it asks questions: a list numbered from 1 at the margin,
+ * outside code blocks, every item a question, the lines indented under each
+ * its body and its `- (a)` or `- [a]` choices, read as `## Blocked` reads
+ * them. An item is a question when its line ends in `?`, or in `?` and an
+ * aside in parentheses: `(all that apply)`; when it goes on past a `?`, which
+ * leaves the rest to its body; or when it offers choices. Any other list is
+ * only text.
+ */
+export declare function stretches(text: string): Stretch[];
+/**
+ * A stretch of an agent's message: markdown as it was written, the questions
+ * it asks the person in the splates skill's format, its report asking them to
+ * review a task before it merges, a design it proposes, its report of how a task ended or what it
+ * waits on or that the lanes it orchestrated are done, its word that it
+ * started lanes, a todo it proposes, a demo for the person to try, the calls
+ * it made without asking, or its word that it requested a cred.
+ */
+export type Stretch = {
+    type: "text";
+    text: string;
+} | {
+    type: "questions";
+    questions: Question[];
+} | {
+    type: "review";
+    review: Review;
+} | {
+    type: "proposal";
+    proposal: Proposal;
+} | {
+    type: "report";
+    report: Report;
+} | {
+    type: "start";
+    start: LanesStart;
+} | {
+    type: "todo";
+    todo: TodoProposal;
+} | {
+    type: "demo";
+    demo: Demo;
+} | {
+    type: "assumed";
+    assumed: Assumed[];
+};
+/** A review the skill's `## 🔍 Ready to merge` report asks for. */
+export interface Review {
+    task: string;
+    base: string;
+    /** Its first paragraph: what changed, in a sentence, as markdown. */
+    summary: string;
+    /** The demo it holds, to try before merging. */
+    demo: Demo | null;
+    /** The commands its `Checks:` line says passed, in order. */
+    checks: string[];
+    /** The commands its `Failed:` line says failed, in order. */
+    failed: string[];
+    /** Whatever else it says, past the summary, as markdown. */
+    details: string;
+}
+/**
+ * What the agent proposes to do, as the skill's `## 💡 Proposed` report puts
+ * it, for the person to approve before it starts. The questions after it are
+ * the calls it rests on, those with a `(chosen)` choice already answered.
+ */
+export interface Proposal {
+    /** What it proposes, as its title says. */
+    subject: string;
+    /** What it recommends, and the `####` sections saying why, as markdown. */
+    body: string;
+}
+/**
+ * How a task ended, or what it waits on, or that a lane orchestrator is done
+ * with its lanes or waits on the person, as the skill's reports title them.
+ */
+export type Ending = "merged" | "removed" | "escalated" | "handed" | "finished" | "waiting" | "working";
+/** A report on a task, or a lane orchestrator's last word on its lanes. */
+export type Report = TaskReport | LanesReport;
+/**
+ * A report the skill titles `## ✅ Merged <task> onto <base>`, `## 🛑 Removed
+ * <task>: <why>`, `## ⚠️ Escalated <task>: <what it needs>`, `## 🤝 Handed
+ * off <task> to <agent>: <why>`, or `## ⏳ Working <task>: on <agent>`, for a
+ * task its agent handed on and relays for, as a lane's orchestrator does.
+ */
+export interface TaskReport {
+    ending: Exclude<Ending, "finished" | "waiting">;
+    task: string;
+    /** Where it merged; null for the others. */
+    base: string | null;
+    /** The agent it was handed off to; null for the others. */
+    to: string | null;
+    /** What the title says after its colon, if anything. */
+    reason: string | null;
+    /** What changed, and anything else said before what follows, as markdown. */
+    body: string;
+    /** The markdown the agent wrote for it, from its title to its end. */
+    source: string;
+}
+/**
+ * The report a lane orchestrator ends on: once every lane it works is done,
+ * titled `## 🏁 Finished lanes <name>, <name>`, as there is nothing left for
+ * it to hand out; or once each lane not done waits on a task that escalated,
+ * titled `## ⏸️ Waiting lanes <name>, <name>: <on what>`, as the person must
+ * answer that task before it can go on.
+ */
+export interface LanesReport {
+    ending: "finished" | "waiting" | "working";
+    /** The lanes' names, as the title lists them. */
+    lanes: string[];
+    /** What the title says after its colon, if anything. */
+    reason: string | null;
+    /** How each lane stands, and anything else said, as markdown. */
+    body: string;
+    /** The markdown the agent wrote for it, from its title to its end. */
+    source: string;
+}
+/** What an agent says it is starting on: a task, or a lane orchestrator's lanes. */
+export type Start = TaskStart | LanesStart;
+/** A task the agent added for itself or claimed, its Goal from that event. */
+export interface TaskStart {
+    task: string;
+    /** What done means, as the task's Goal says, as markdown. */
+    goal: string;
+}
+/**
+ * The lanes an orchestrator says it is starting to work, as `## 🌱 Started
+ * lanes <name>, <name>`, what they add up to under it.
+ */
+export interface LanesStart {
+    /** The lanes' names, as the title lists them. */
+    lanes: string[];
+    /** What the lanes add up to, as markdown. */
+    goal: string;
+}
+/** A todo the skill proposes as `### 📝 <subject> [#<id>]`. */
+export interface TodoProposal {
+    id: number;
+    /** The subject as the agent wrote it, which may since have changed. */
+    subject: string;
+    /** What the todo is and why it matters now, as markdown. */
+    body: string;
+}

package/asked.js

@@ -0,0 +1,7 @@
+import {
+  stretches2
+} from "./index-gcfq7awr.js";
+import"./index-k73tsw5g.js";
+export {
+  stretches2 as stretches
+};

package/assumed.d.ts

@@ -0,0 +1,34 @@
+import { type Exhibit } from "./exhibit.js";
+import { type Question } from "./plan.js";
+/**
+ * A call the agent made without asking, as the skill's `- Assumed <number>:
+ * <what>` line says it in a reply: numbered as in its task's `## Assumptions`.
+ */
+export interface Assumed {
+    number: string;
+    /** What it chose, as the line says it. */
+    text: string;
+    /** What the reply shows it in, when the line captions an exhibit. */
+    exhibit?: Exhibit;
+}
+/**
+ * Each of `assumed` as its task's `plan` writes it, matched by number: under
+ * `## Assumptions`, or under `## Blocked` once challenged, so a reply that
+ * challenged it still reads as it did. One the plan has no item for, as
+ * outside a task or once it is gone, is its line alone, with no choices.
+ * Either way, one the reply captions an exhibit with shows it, unless the
+ * plan already shows it something.
+ */
+export declare function assumedIn(plan: string, assumed: Assumed[]): Question[];
+/** Whether `line` is a reply's `- Assumed <number>:` line. */
+export declare function isAssumed(line: string): boolean;
+/**
+ * The run of `- Assumed <number>:` lines from `start`, blank lines between
+ * them, and the line after it; null for any other line. An exhibit in the
+ * run, `### 🖼️ <title>` and what it shows, is what the lines right after it
+ * caption, up to a blank line; one that captions none ends the run.
+ */
+export declare function assumedAt(lines: string[], start: number): {
+    assumed: Assumed[];
+    end: number;
+} | null;

package/attach.d.ts

@@ -0,0 +1,30 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+import type { Git } from "./git.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface AttachOptions {
+    /** Task whose files these are. Defaults to the one `cwd` is a worktree for. */
+    task?: string;
+    /** Files it holds to drop first, by path or by the name they were stored under. */
+    remove?: string[];
+    /**
+     * Conversation to keep the files with. Defaults to the one whose agent runs
+     * the command; with neither, they stay with the task and go when it does.
+     */
+    conversation?: string;
+}
+/**
+ * Stores files for a task's questions to show, in a folder splates owns, so
+ * the screenshots and recordings an agent takes never land in a commit.
+ * An agent in a conversation has them kept with it, so a merged task's
+ * report card still shows them; any other agent's go when the task merges or
+ * is removed. Prints where each was stored, which is the path a question
+ * names.
+ */
+export declare function attach(deps: {
+    service: WorktreeService;
+    git: Git;
+    log: Logger;
+    fs: Fs;
+    ps: Ps;
+}, paths: string[], cwd: string, { task, remove, conversation: given }?: AttachOptions): Promise<string[]>;

package/attachments.d.ts

@@ -0,0 +1,43 @@
+import { type IdProvider } from "webappwiz/id";
+import type { Fs, Ps } from "webappwiz/system";
+/** A file handed over, as bytes so a pasted image needs no temp file. */
+export interface Attachment {
+    /** What it was called, kept in the stored name so the files stay apart. */
+    name: string;
+    bytes: Uint8Array;
+}
+/**
+ * The folder of files that belong to a todo or a task: todo 7's beside its
+ * record, in `todos/7/`, and task `login`'s in `tasks/login/`.
+ * Under `.git/splates`, so nothing here is ever committed and every tree can
+ * open what it holds.
+ */
+export declare class Attachments {
+    readonly dir: string;
+    private readonly fs;
+    private readonly ids;
+    constructor(dir: string, fs: Fs, ids?: IdProvider);
+    /** Copies each file in, returning the absolute path each was stored at. */
+    store(files: Attachment[]): Promise<string[]>;
+    /** Each file stored here, by absolute path, with its size in bytes. */
+    held(): Promise<{
+        path: string;
+        bytes: number;
+    }[]>;
+    /** Whether `path` is one of this folder's files, and not a way out of it. */
+    owns(path: string): boolean;
+    /** Deletes the files given that are this folder's; others are left alone. */
+    remove(paths: string[]): Promise<void>;
+    /** Deletes the folder and everything in it. */
+    clear(): Promise<void>;
+}
+/**
+ * Reads files named on the command line, relative to the current directory or
+ * absolute, refusing the whole command over one that cannot be read.
+ */
+export declare function readFiles({ fs, ps }: {
+    fs: Fs;
+    ps: Ps;
+}, paths: string[]): Promise<Attachment[]>;
+/** The bytes of every file under `dir`, folders included, 0 when it is not there. */
+export declare function folderBytes(fs: Fs, dir: string): Promise<number>;

package/baselines.d.ts

@@ -0,0 +1,55 @@
+import type { Finding } from "./findings.js";
+import type { Outcome } from "./outcomes.js";
+/** Each project's baseline, over the merged tasks that ended in the window before `now`. */
+export declare function baselines(outcomes: Outcome[], now: Date): Baseline[];
+/**
+ * What a project's recent merged tasks were like, so one task can be held
+ * against them: each measure's median and 90th percentile, and how often each
+ * kind of finding came up.
+ */
+export interface Baseline {
+    /** The main tree of the repository. */
+    project: string;
+    /** Its merged tasks in the window. */
+    tasks: number;
+    /** Each measure over the tasks that kept it; null with too few to compare against. */
+    measures: Record<Measure, Spread | null>;
+    /** How many of its tasks had each finding, by `findingKeys`. */
+    findings: Record<string, number>;
+}
+/** Where a measure's values fall among a project's tasks. */
+export interface Spread {
+    /** The tasks that kept it. */
+    tasks: number;
+    median: number;
+    p90: number;
+}
+/** What a task is held against its project's on. */
+export type Measure = 
+/** From add to merge, in milliseconds. */
+"spentMs"
+/** What its own turns cost; Codex says none. */
+ | "cost"
+/** Lines added and removed. */
+ | "lines"
+/** Calls the person made, asked or challenged. */
+ | "decidedByYou" | "failedMerges";
+export declare const MEASURES: readonly Measure[];
+/** Each tuned here, so a comparison that cries wolf is one number to change. */
+export declare const BASELINE: {
+    /** How far back the tasks compared against ended. */
+    readonly windowMs: number;
+    /** Fewer tasks than this keeping a measure, and it gives no comparison. */
+    readonly minTasks: 10;
+    /** A value is an outlier past the 90th percentile, or this many medians. */
+    readonly timesMedian: 2;
+};
+/** What `outcome` shows of each measure; null for one it did not keep. */
+export declare function measured(outcome: Outcome): Record<Measure, number | null>;
+/** Whether `value` stands out from `spread`: never against no spread. */
+export declare function outlier(value: number, spread: Spread | null): boolean;
+/**
+ * What a finding counts toward: its kind, and, for one that names what
+ * failed, that too, so the same failing test is counted apart from others.
+ */
+export declare function findingKeys(finding: Finding): string[];

package/claim.d.ts

@@ -0,0 +1,17 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs } from "webappwiz/system";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * The resume entry point: a fresh agent thread picking up existing work. An
+ * escalated task goes back to `working`, since someone is on it again; its
+ * merge budget stays as it was, which only `retry` refills.
+ */
+export declare function claim({ service, log, fs }: {
+    service: WorktreeService;
+    log: Logger;
+    fs: Fs;
+}, task: string): Promise<{
+    escalated: boolean;
+    tookOver: boolean;
+    goal: string;
+}>;

package/cloudflare-api.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/** Where Cloudflare's v4 API answers. */
+export declare const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
+/**
+ * The few calls `splates tunnel setup` makes of Cloudflare's v4 API, over plain
+ * `fetch` rather than the `cloudflare` SDK, which every `bunx` of splates would
+ * download for some ten endpoints. Each answer's result is checked against
+ * the shape the caller names, so a field that moved fails here, saying where.
+ */
+export declare class CloudflareApi {
+    private readonly token;
+    private readonly fetch;
+    constructor(token: string, opts?: {
+        fetch?: typeof fetch;
+    });
+    get<T>(path: string, shape: z.ZodType<T>): Promise<T>;
+    /** Every item of the list at `path`, page after page. */
+    list<T>(path: string, item: z.ZodType<T>): Promise<T[]>;
+    post<T>(path: string, body: unknown, shape: z.ZodType<T>): Promise<T>;
+    put<T>(path: string, body: unknown, shape: z.ZodType<T>): Promise<T>;
+    patch<T>(path: string, body: unknown, shape: z.ZodType<T>): Promise<T>;
+    /** Deletes what is at `path`, whatever Cloudflare answers with. */
+    delete(path: string): Promise<void>;
+    private call;
+}

package/cloudflare-error.d.ts

@@ -0,0 +1,5 @@
+/** A call Cloudflare refused, with the HTTP status it answered. */
+export declare class CloudflareError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/cloudflared-tunnel-provider.d.ts

@@ -0,0 +1,27 @@
+import type { AsyncResource } from "webappwiz/disposable";
+import type { Ps } from "webappwiz/system";
+import type { TunnelProvider, TunnelRoute } from "./tunnel-provider.js";
+/**
+ * An `sh -c` script that runs the command after it, `sh -c GUARD sh <argv>`,
+ * until the guard's stdin closes or a SIGTERM reaches it, and exits with the
+ * command's status. Start it with stdin a pipe, so it dies with its parent.
+ */
+export declare const GUARD: string;
+/**
+ * A TunnelProvider over the `cloudflared` binary, running the named tunnel
+ * the account already has, or the one its own config names, or, given a
+ * token, the tunnel `splates tunnel setup` made, with no login or credentials
+ * file. One that dies while running is logged, never fatal: the page still
+ * answers on this machine.
+ */
+export declare class CloudflaredTunnelProvider implements TunnelProvider {
+    private readonly ps;
+    private readonly name;
+    /** The tunnel's token, handed over in the environment, never the argv `ps` lists. */
+    private readonly token;
+    constructor(ps: Ps, name?: string | null, 
+    /** The tunnel's token, handed over in the environment, never the argv `ps` lists. */
+    token?: string | null);
+    ready(): Promise<void>;
+    run({ host, url, log }: TunnelRoute): AsyncResource;
+}

package/codex-limits.d.ts

@@ -0,0 +1,19 @@
+import { type Timer } from "webappwiz/time";
+import type { Agent, Launch, Limit } from "./conversations.js";
+/** Whether `agent` is Codex's ACP adapter, which says its limits only in `/status`. */
+export declare function isCodex(agent: Agent): boolean;
+/**
+ * Asks Codex's app server, the one its ACP adapter runs, for the plan's
+ * windows, since the adapter never sends them: a window Claude also has goes
+ * by Claude's name, any other by its length, as `43200_minutes`. None when
+ * Codex will not say.
+ */
+export declare function codexLimits(deps: {
+    launch: Launch;
+    timer: Timer;
+    now: () => number;
+    /** Where it runs: anywhere does, since the plan is the account's. */
+    cwd: string;
+    /** Where `codex` is, as the adapter reads it; `codex` on the path otherwise. */
+    codex?: string;
+}): Promise<Limit[]>;

package/compaction.d.ts

@@ -0,0 +1,17 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type { Compaction, ConversationState } from "./conversation-state.js";
+/** Whether `update` reports a compaction rather than a tool call of the agent's. */
+export declare function isCompaction(update: acp.ToolCall | acp.ToolCallUpdate): boolean;
+/** Takes what an update says of the compaction into it. */
+export declare function fillCompaction(part: Compaction, update: acp.ToolCall | acp.ToolCallUpdate, at: string | null): void;
+/** The compaction `id`, wherever in the conversation it was; null for none. */
+export declare function compactionIn(state: ConversationState, id: string): Compaction | null;
+/** A compaction `id` just begun at `at`, with nothing said of it yet. */
+export declare function newCompaction(id: string, at: string | null): Compaction;
+/**
+ * Takes ACP's `compaction_update` into `part`: its status, and its summary,
+ * which replaces the one kept, or clears it when null or empty.
+ */
+export declare function updateCompaction(part: Compaction, update: acp.CompactionUpdate, at: string | null): void;
+/** Appends a `compaction_summary_chunk`'s text to the summary `part` keeps. */
+export declare function appendSummary(part: Compaction, chunk: acp.CompactionSummaryChunk): void;

package/config-source.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `source` typed by a type-only import of `ConfigFile` and `satisfies` rather
+ * than by calling `defineConfig`, so a reader can import it without splates
+ * installed; or null unless it imports `defineConfig` alone and calls it
+ * once.
+ */
+export declare function typedConfig(source: string): string | null;
+/**
+ * `source` with the `systems` property of its outermost object taken out,
+ * with its line when it has one to itself, or null unless there is exactly
+ * one such property.
+ */
+export declare function withoutSystems(source: string): string | null;

package/config.d.ts

@@ -0,0 +1,98 @@
+import type { TunnelProvider } from "./tunnel-provider.js";
+export interface Config {
+    /**
+     * The integration branch name. `merge` rebases a task onto this branch and
+     * then fast-forwards it to the result; new worktrees start from it.
+     */
+    trunk: string;
+    /** Directory holding one worktree per task, a sibling of the repo. */
+    worktreeRoot: string;
+    /** Command run by `add` in the new worktree, via `sh -c`. */
+    postCheckout: string | null;
+    /**
+     * Command run by `merge` after the rebase, before `preMerge`, via `sh -c`.
+     * A rebase can bring in a dependency the worktree has never installed, and
+     * whatever `preMerge` runs needs it.
+     */
+    postRewrite: string | null;
+    /**
+     * Command run by `merge` after the rebase, via `sh -c`. The last gate before
+     * the branch lands: a nonzero exit rolls the branch back and leaves the base
+     * untouched. Tests are the obvious thing to put here, but splates has no
+     * opinion; a repo with nothing to run leaves it null and merges on a green
+     * rebase alone.
+     */
+    preMerge: string | null;
+    /** How long since its last heartbeat before a task's lease is up for grabs. */
+    leaseStalenessMs: number;
+    /**
+     * How many agents one agent may have started at once: the tasks it
+     * handed out with `splates add --agent` and that are still out. A lane
+     * orchestrator hands out every todo that can go, each to an agent of
+     * its own. Past it, `add --agent` refuses, unless the person asked for
+     * more and it passes `--over-capacity`.
+     */
+    agentsPerAgent: number;
+    /** Failed `merge` attempts a task gets before it must escalate or be removed. */
+    mergeRetryCount: number;
+    /**
+     * How many removed task names to keep, so `remove` can say "already removed"
+     * rather than "never existed". A flat cap with no age policy: losing the
+     * oldest costs a nicer message and nothing else.
+     */
+    removedCapacity: number;
+    /**
+     * How many events the log holds before it is moved aside and a fresh one
+     * starts; moved files are kept for `LOG_KEPT_MS` (`journal.ts`).
+     */
+    logCapacity: number;
+    /**
+     * How long a todo can wait before `merge` stops recommending it and offers
+     * it for removal instead: work deferred that long has usually been done
+     * some other way, or stopped mattering.
+     */
+    todoStalenessMs: number;
+    /**
+     * How many bytes of files `splates attach` lets one task hold, all of them
+     * together: a screen recording is the one thing here that grows fast.
+     */
+    attachmentCapacity: number;
+    /** How many bytes one artifact a conversation keeps may be (`artifacts.ts`). */
+    artifactFileCapacity: number;
+    /**
+     * How many bytes of artifacts one conversation may keep, every version
+     * whose bytes have not been deleted.
+     */
+    artifactConversationCapacity: number;
+    /** How many bytes of artifacts every conversation in the project may keep together. */
+    artifactProjectCapacity: number;
+    /**
+     * The command the `splates server` Budget page runs `scry budgets` with, from
+     * the repo's root. Leave it unset when the repo installs `@webappwiz/cli`;
+     * name a wrapper of the repo's own otherwise, like `"./bin/splates dev"`.
+     */
+    wiz: string;
+    /**
+     * What carries `splates server --tunnel` to its public host, a TunnelProvider
+     * of your own for any tunnel; null runs `cloudflared`.
+     */
+    tunnel: TunnelProvider | null;
+}
+/**
+ * What `splates.config.ts` exports as its default, typed by a type-only import
+ * so a reader can import the file without splates installed:
+ *
+ * ```ts
+ * import type { ConfigFile } from "@stringsync/splates/config";
+ *
+ * export default { preMerge: "bun test" } satisfies ConfigFile;
+ * ```
+ */
+export type ConfigFile = Partial<Config>;
+/**
+ * Types a config written before `ConfigFile`, which wraps its default in
+ * `defineConfig(...)`, so it still loads until `splates update` rewrites it.
+ *
+ * @deprecated `satisfies ConfigFile` instead.
+ */
+export declare function defineConfig(config: Partial<Config>): Partial<Config>;

package/config.js

@@ -0,0 +1,7 @@
+// config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};

package/conversation-archive.d.ts

@@ -0,0 +1,6 @@
+import type { ConversationHost } from "./conversation-host.js";
+/** Records archive membership and its timestamp together. */
+export declare function put(host: ConversationHost, { archived, with: withConversation, }: {
+    archived: boolean;
+    with?: string | undefined;
+}): Promise<void>;

package/conversation-background.d.ts

@@ -0,0 +1,21 @@
+import type { AgentConnection } from "./agent-connection.js";
+import type { ConversationDeps, ConversationHost } from "./conversation-host.js";
+/**
+ * The commands the agent left running in the background, as the
+ * conversation's state lists them: what each has printed, and stopping one.
+ */
+export declare class ConversationBackground {
+    private readonly host;
+    private readonly deps;
+    private readonly connection;
+    constructor(host: ConversationHost, deps: ConversationDeps, connection: AgentConnection);
+    /** Stops background command `id`, leaving the agent's turn as it is. */
+    stop(id: string): Promise<void>;
+    /**
+     * What background command `id` has printed, then more as it prints it,
+     * ending once the command has and all of it is read.
+     */
+    output(id: string): ReadableStream<Uint8Array>;
+    /** Background command `id`, refusing one the agent never left. */
+    private command;
+}

package/conversation-choice.d.ts

@@ -0,0 +1,4 @@
+import type { AgentConnection } from "./agent-connection.js";
+import type { ConversationHost } from "./conversation-host.js";
+/** Applies a validated user choice to the session and its log. */
+export declare function choose(host: ConversationHost, connection: AgentConnection, id: string, value: string): Promise<void>;

package/conversation-files.d.ts

@@ -0,0 +1,51 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type { Fs } from "webappwiz/system";
+import type { ProjectRoster } from "./conversation-host.js";
+import type { Message, Sent, Upload } from "./conversation-state.js";
+/**
+ * The files the person sent in a conversation, kept beside its log in a
+ * directory named for it, and how what they said goes to the agent.
+ */
+export declare class ConversationFiles {
+    private readonly fs;
+    /** Where the files are kept. */
+    private readonly dir;
+    private readonly projects;
+    private readonly home;
+    constructor(log: string, fs: Fs, { projects, home, }?: {
+        /** The splates projects on this machine, for `#slug`; null for none. */
+        projects?: ProjectRoster | null;
+        /** The main tree of the project the conversation is in; null for none. */
+        home?: string | null;
+    });
+    /**
+     * Saves each file beside the log, named for what is in it, so the page
+     * reads it by name rather than with every change to the conversation.
+     * An image goes to the agent as itself when it `sees` images; anything
+     * else, as a link to where it is kept, which every agent takes.
+     */
+    keep(files: Upload[], sees: boolean): Promise<Sent[]>;
+    /** The file `name` the person sent in `messages`, or null when they sent none by that name. */
+    attachment(name: string, messages: Message[]): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+    /**
+     * What `messages` say, as one prompt: their images, links to their other
+     * files, then their words, with a line on each system they name in
+     * `tree`, the one the agent runs in (none for a log too old to say), one
+     * on where each project they name sits, and one on reading them as speech
+     * when any was dictated.
+     */
+    content(messages: Message[], tree: string | null, sees?: boolean): Promise<acp.ContentBlock[]>;
+    /** Deletes every file kept, for good. */
+    remove(): Promise<void>;
+    /**
+     * A line on each system, conversation UUID and project `text` mentions with `#`,
+     * then one on each `#word` that names neither, for the agent alone: the
+     * thread keeps the words as typed. Read from `tree` and the projects as
+     * it goes, so a system named there a moment ago counts. A system wins
+     * over a project of the same name.
+     */
+    private namedIn;
+}

package/conversation-given.d.ts

@@ -0,0 +1,8 @@
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * The conversation a command is about: `given` from `--conversation`, for an
+ * agent outside `splates server`, else the one `splates server` started this agent in
+ * ($SPLATES_CONVERSATION). Refuses `usage` when neither names one of this
+ * repository's.
+ */
+export declare function conversationOf(service: WorktreeService, given: string): Promise<string>;