@stringsync/splates 0.0.0-stage → 0.0.45

package/remove.d.ts

@@ -0,0 +1,31 @@
+import { type Logger } from "webappwiz/log";
+import { type Slots } from "./slots.js";
+import type { Todos } from "./todos.js";
+import type { RemoveReason } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface RemoveOptions {
+    /** Discard the tree even when another agent holds its lease. */
+    force?: boolean;
+    /** The `splates server` conversation working on it, when removed from the page. */
+    conversation?: string;
+    /** Why, kept in its outcome for the Stats page. */
+    reason?: RemoveReason;
+}
+/**
+ * Discards a whole task: `git worktree remove` plus the branch and the
+ * record.
+ *
+ * Throwing a task away and redoing it against current trunk is usually cheaper
+ * than a hard rebase, so this is meant to be used freely.
+ */
+export declare function remove({ service, log, todos, slots, }: {
+    service: WorktreeService;
+    log: Logger;
+    todos: Todos;
+    slots: Slots;
+}, task: string, { force, conversation, reason }?: RemoveOptions): Promise<{
+    released: {
+        id: number;
+        subject: string;
+    }[];
+}>;

package/repository.d.ts

@@ -0,0 +1,91 @@
+import type { Deps, Middleware } from "webappwiz/cmd";
+import type { HeavyCap } from "webappwiz/system";
+import { type Fs, type Lock } from "webappwiz/system";
+import type { Config } from "./config.js";
+import { Creds, type SecretStores } from "./creds.js";
+import { Format } from "./format.js";
+import { Git } from "./git.js";
+import { Journal } from "./journal.js";
+import { Outcomes } from "./outcomes.js";
+import { Projects, type Reach } from "./projects.js";
+import { Shell } from "./shell.js";
+import { Slots } from "./slots.js";
+import { Todos } from "./todos.js";
+import { WorktreeService } from "./worktree-service.js";
+/** What a command gets to work with, once there is a repository to work in. */
+export interface Repository {
+    /** Where splates keeps its records: `.git/splates`, shared by every worktree. */
+    splatesDir: string;
+    config: Config;
+    /** Checked before the command runs, so its records are in this splates's format. */
+    format: Format;
+    git: Git;
+    service: WorktreeService;
+    lock: Lock;
+    shell: Shell;
+    journal: Journal;
+    todos: Todos;
+    /** How each task on this machine ended, which a merge reads its findings from. */
+    outcomes: Outcomes;
+    /** Every splates project on this machine, which `splates init` joins this one to. */
+    projects: Projects;
+    /** The creds agents ask for, and the stores they are kept in. */
+    creds: Creds;
+    /** The machine's dev slots, which a task gives back as it ends. */
+    slots: Slots;
+    /** The machine's slots for test runs and installs, which hooks wait for. */
+    heavy: HeavyCap;
+}
+/** How `repository` treats records in an older format than this splates's. */
+export interface RepositoryOptions {
+    /**
+     * Brings them forward before the action runs. Only `splates server` does: a
+     * migration is the server's to run, with its sessions settled, so every
+     * other command refuses them until it has.
+     */
+    migrates?: boolean;
+    /**
+     * Sets up the records of a repository that has none first, as only
+     * `splates init` does: every other command refuses one.
+     */
+    creates?: boolean;
+    /** Where to look for the repository; the working directory by default. */
+    at?: string;
+}
+/**
+ * Runs the action against the repository `cwd` sits in, or the registered
+ * project `--project` names, and refuses to run it at all when that is not
+ * a repository, its records are in a format this splates does not read, or
+ * the command is run from another project that has not been granted what
+ * it `needs` there.
+ */
+export declare function repository<C extends Deps & {
+    fs: Fs;
+    secrets?: SecretStores;
+    project?: string;
+}>(opts: Omit<RepositoryOptions, "at"> & {
+    needs: Needs;
+}): Middleware<C, C & Repository & Reached>;
+/**
+ * What a command needs of the project it runs on, when an agent of another
+ * project runs it: a reach that project must have granted, or `own` for a
+ * command no other project may run there at all.
+ */
+export type Needs = Reach | "own";
+/** What `repository` adds beyond the repository itself. */
+export interface Reached {
+    /**
+     * The main tree of the other project the command is run from, as checked
+     * against what it `needs`; null when run from this one, or from none.
+     */
+    elsewhere: string | null;
+}
+/**
+ * What a command works with in the repository `at` sits in, the working
+ * directory by default: what `repository` hands an action, and what `splates
+ * dev` opens each project it serves with. Refuses what `repository` does.
+ */
+export declare function openRepository({ fs, ps, log, secrets, }: Deps & {
+    fs: Fs;
+    secrets?: SecretStores;
+}, { migrates, creates, at }?: RepositoryOptions): Promise<Repository>;

package/retry.d.ts

@@ -0,0 +1,34 @@
+import { type Logger } from "webappwiz/log";
+import type { Config } from "./config.js";
+import type { Journal } from "./journal.js";
+import type { Worktree } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * The way back from `budget_exhausted`. A task that has spent its merge
+ * attempts gets another `mergeRetryCount` of them, instead of `remove` and redo.
+ *
+ * Only from `escalated`, and deliberately: the budget's whole job is to make an
+ * agent stop and hand the task over. An agent that could grant itself more
+ * would be back to grinding against a moving trunk forever, so the price of a
+ * fresh budget is that a human has looked at the tree first.
+ */
+export declare function retry({ service, config, log, }: {
+    service: WorktreeService;
+    config: Config;
+    log: Logger;
+}, task: string): Promise<Granted>;
+/** `retry`, recorded in the journal with the attempts the task had spent. */
+export declare function recordRetry(ctx: {
+    journal: Journal;
+    service: WorktreeService;
+    config: Config;
+    log: Logger;
+}, task: string): Promise<Granted>;
+/** A retry that was granted: the task back to working, and the attempts it had spent. */
+export interface Granted {
+    worktree: Worktree;
+    /** The merge attempts it had spent before the grant. */
+    attempts: number;
+}
+/** What `retry` does, without the printing, for `splates server`'s page too. */
+export declare function grantRetry(service: WorktreeService, task: string): Promise<Granted>;

package/roster.d.ts

@@ -0,0 +1,63 @@
+import type { Fs, Ps } from "webappwiz/system";
+import type { Agent } from "./conversations.js";
+/**
+ * The agents splates can start, and the models each runs, kept in one file
+ * under the user's home rather than per project: an orchestrator in any
+ * project, of any model family, can read it to delegate to any other.
+ */
+export declare class Roster {
+    /** `~/.splates/agents.json`, or a test's own. */
+    readonly path: string;
+    private readonly deps;
+    constructor(
+    /** `~/.splates/agents.json`, or a test's own. */
+    path: string, deps: {
+        fs: Fs;
+    });
+    /**
+     * Writes the defaults when there is no roster yet, saying whether it did,
+     * so the user has a file to edit rather than a list they cannot see.
+     */
+    seed(): Promise<boolean>;
+    /** Every agent on the roster, in its order; the defaults when there is none. */
+    agents(): Promise<RosterAgent[]>;
+}
+/** A model an agent can run, and what picking it buys. */
+export interface RosterModel {
+    /** What the agent's Model setting takes: `opus`, `gpt-6-luna`. */
+    id: string;
+    name: string;
+    /** What it is good at, so an orchestrator can choose it for a job. */
+    strengths: string;
+    /** What it costs, relative to the others or as a price. */
+    cost: string;
+}
+/** An agent on the roster: how to start it, and the models it runs. */
+export interface RosterAgent extends Agent {
+    models: RosterModel[];
+}
+/**
+ * The roster a machine starts with: each agent is the ACP adapter its maker
+ * publishes, fetched by `bunx` on first use, and its models are those the
+ * adapter offers, by the ids its Model setting takes.
+ */
+export declare const DEFAULT_AGENTS: RosterAgent[];
+/** An agent off the roster, on one of its models, or on its own without one. */
+export interface AgentPick {
+    agent: string;
+    /** The roster's id for the model, which the agent's Model setting takes. */
+    model?: string;
+}
+/** The models `agent` runs, as the roster lists them; none for an agent off it. */
+export declare function modelsOf(agent: Agent): RosterModel[];
+/** `pick` in a word: `claude`, or `claude (opus)` on a model. */
+export declare function pickLabel(pick: AgentPick): string;
+/**
+ * `agent` on `model`, named by its id or name in any case, as the roster's
+ * ids; OpenCode and provider-qualified models require an exact ID. Refuses an agent or a model the roster does not list, saying so with
+ * `data`. An agent whose models the roster leaves out takes the model as
+ * given.
+ */
+export declare function pickAgent(agents: RosterAgent[], agent: string, model: string | undefined, data?: Record<string, unknown>): AgentPick;
+/** Where the user's splates files live: `~/.splates`, or `SPLATES_HOME`, as the tests set. */
+export declare function splatesHome(ps: Ps): string;

package/saved-ports-host.d.ts

@@ -0,0 +1,25 @@
+import type { Fs } from "webappwiz/system";
+/** What `--ports-host` takes to forget the saved base host. */
+export declare const NO_PORTS_HOST = "none";
+/**
+ * The wildcard base host this machine serves task ports under, as
+ * `<task>-<port>.<base>`: saved by `splates server --ports-host`, per machine as
+ * the tunnel is, in `~/.splates/ports.json`, so a bare `splates server` serves it.
+ */
+export declare class SavedPortsHost {
+    /** `~/.splates/ports.json`, or a test's own. */
+    readonly path: string;
+    private readonly fs;
+    constructor(
+    /** `~/.splates/ports.json`, or a test's own. */
+    path: string, fs: Fs);
+    /** The saved base, or null when none is, or its format is newer. */
+    read(): Promise<string | null>;
+    /** Keeps `base`, over what was there, or forgets it for null. */
+    save(base: string | null): Promise<void>;
+}
+/**
+ * What `--ports-host` asks for: a base host to save, null to forget the
+ * saved one, or undefined to serve whatever was saved.
+ */
+export declare function portsHostFlag(flag: string): string | null | undefined;

package/saved-tunnel.d.ts

@@ -0,0 +1,44 @@
+import type { SecretStore } from "webappwiz/creds";
+import type { Fs } from "webappwiz/system";
+/** The name the tunnel's token is kept under in the system's secret store. */
+export declare const TUNNEL_TOKEN = "SPLATES_TUNNEL_TOKEN";
+/** What `splates tunnel setup` made, which a bare `splates server` runs. */
+export interface TunnelRecord {
+    /** The public host name the tunnel carries to the page. */
+    host: string;
+    /** The Zero Trust team, as in `<team>.cloudflareaccess.com`. */
+    team: string;
+    /** The AUD tag of the Access application in front of `host`. */
+    aud: string;
+    /** The Cloudflare tunnel's id. */
+    tunnel: string;
+    /**
+     * The cred its token is kept as, when not `TUNNEL_TOKEN`: a slot's own,
+     * since every slot runs a tunnel of its own.
+     */
+    token?: string;
+}
+/**
+ * The tunnel this machine set up, kept per machine rather than per project,
+ * since one `splates server` serves every project: what it is in
+ * `~/.splates/tunnel.json`, and the token that runs it, a secret of this
+ * machine, in the device's secret store, as the cred `TUNNEL_TOKEN`.
+ */
+export declare class SavedTunnel {
+    /** `~/.splates/tunnel.json`, or a test's own. */
+    readonly path: string;
+    private readonly deps;
+    constructor(
+    /** `~/.splates/tunnel.json`, or a test's own. */
+    path: string, deps: {
+        fs: Fs;
+        /** The device's store, which `splates tunnel setup` saves the token in. */
+        store: SecretStore;
+    });
+    /** What was saved, or null when nothing was, or its format is newer. */
+    read(): Promise<TunnelRecord | null>;
+    /** The token that runs the saved tunnel, or undefined when the store lost it. */
+    token(): Promise<string | undefined>;
+    /** Keeps `record` in the file, over what was there; its token is a cred. */
+    save(record: TunnelRecord): Promise<void>;
+}

package/server-worker-socket.d.ts

@@ -0,0 +1,21 @@
+import type { Connection } from "./dev-sockets.js";
+import type { WorkerRegistry } from "./worker-registry.js";
+import type { WorkerSocket, WorkerSocketEvents } from "./worker-socket.js";
+/**
+ * A worker's WebSocket as `splates server` upgraded it on `/api/workers`, seen as
+ * a `WorkerSocket`: the server hands it each socket event, and it hands
+ * itself to the registry once open.
+ */
+export declare class ServerWorkerSocket implements WorkerSocket, Connection {
+    private readonly registry;
+    private readonly dispatcher;
+    readonly events: import("webappwiz/events").Events<WorkerSocketEvents>;
+    private socket;
+    private live;
+    constructor(registry: WorkerRegistry);
+    send(frame: string | Uint8Array): void;
+    dispose(): void;
+    open(socket: Bun.ServerWebSocket<Connection>): void;
+    message(_socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    closed(): void;
+}

package/setup-areas.d.ts

@@ -0,0 +1,7 @@
+import type { SetupArea } from "./setup.js";
+/**
+ * Everything that makes up setting splates up on a machine, in the order it is
+ * best done. Each area is a short list of steps the page and an agent walk
+ * the user through one at a time.
+ */
+export declare const SETUP_AREAS: readonly SetupArea[];

package/setup-opencode-model-error.d.ts

@@ -0,0 +1,3 @@
+/** A safe setup diagnostic; native output must never become one. */
+export declare class OpenCodeModelError extends Error {
+}

package/setup-opencode-models.d.ts

@@ -0,0 +1,54 @@
+import { type Fs, type Ps } from "webappwiz/system";
+import { z } from "zod";
+import { type OpenCodeRecipe, OpenCodeRecipes } from "./setup-opencode-recipe.js";
+/** Only metadata commands. The configuration is embedded in the roster argv so
+ * a single atomic rename activates both the models and their experiment policy. */
+export declare class OpenCodeModels {
+    private readonly deps;
+    private readonly metadata;
+    private catalog;
+    private previewed;
+    private saved;
+    readonly recipes: OpenCodeRecipes;
+    constructor(deps: {
+        fs: Fs;
+        ps: Ps;
+        home: string;
+    }, metadata: OpenCodeMetadata);
+    read(): OpenCodeModelState;
+    invalidate(): void;
+    cancel(): void;
+    refresh(signal: AbortSignal): Promise<OpenCodeModelState>;
+    preview(selection: OpenCodeSelection, signal: AbortSignal): Promise<OpenCodeModelState>;
+    apply(token: string, balanceOff: boolean, signal: AbortSignal): Promise<OpenCodeModelState>;
+    verifyStored(recipe: OpenCodeRecipe, cwd: string, signal: AbortSignal): Promise<void>;
+    private requireModels;
+    private discover;
+    private agents;
+    private verify;
+    private roster;
+}
+export declare const openCodeSelection: z.ZodObject<{
+    model: z.ZodString;
+    auxiliary: z.ZodString;
+}, z.core.$strip>;
+export type OpenCodeSelection = z.infer<typeof openCodeSelection>;
+export interface OpenCodeCatalog {
+    models: string[];
+    checkedAt: string | null;
+    problem: string | null;
+}
+export interface OpenCodePreview extends OpenCodeSelection {
+    token: string;
+    path: string;
+    config: Record<string, unknown>;
+    agents: string[];
+}
+export interface OpenCodeModelState {
+    catalog: OpenCodeCatalog;
+    preview: OpenCodePreview | null;
+    saved: OpenCodeSelection | null;
+}
+export interface OpenCodeMetadata {
+    run(args: string[], signal: AbortSignal, env?: Record<string, string>, cwd?: string): Promise<string>;
+}

package/setup-opencode-recipe.d.ts

@@ -0,0 +1,26 @@
+import { type Fs, type Ps } from "webappwiz/system";
+import { z } from "zod";
+import type { OpenCodeSelection } from "./setup-opencode-models.js";
+export declare class OpenCodeRecipes {
+    private readonly deps;
+    constructor(deps: {
+        fs: Fs;
+        ps: Ps;
+        home: string;
+    });
+    /** Read disk on every revisit; this never asserts readiness or runs a process. */
+    stored(): Promise<OpenCodeRecipe | null>;
+    unchanged(recipe: OpenCodeRecipe, signal: AbortSignal): Promise<void>;
+    /** Only removes the wizard-owned entry; native authentication is untouched. */
+    disable(signal: AbortSignal): Promise<void>;
+    rawRoster(): Promise<string | null>;
+}
+export declare function managedArgv(value: unknown): boolean;
+export declare const projectOff = "OPENCODE_CONFIG_PROJECT_DISABLE=1";
+export declare const contentPrefix = "OPENCODE_CONFIG_CONTENT=";
+export interface OpenCodeRecipe extends OpenCodeSelection {
+    config: Record<string, unknown>;
+    env: Record<string, string>;
+    raw: string;
+}
+export declare const id: z.ZodString;

package/setup-opencode.d.ts

@@ -0,0 +1,46 @@
+import type { Fs, Ps } from "webappwiz/system";
+import { OpenCodeModels, type OpenCodeSelection } from "./setup-opencode-models.js";
+/** Observations only: a stored credential is not proof of entitlement or inference. */
+export interface OpenCodeStatus {
+    version: string | null;
+    auth: "unchecked" | "missing" | "stored" | "unsupported";
+    protocol: "unchecked" | "compatible" | "failed";
+    checking: boolean;
+    problem: string | null;
+    checkedAt: string | null;
+}
+/** Fixed native actions; no arguments, credentials or commands come from the page. */
+export declare const OPENCODE_INSTALL: string[];
+export declare const OPENCODE_LOGIN: string[];
+/** Non-billed installation, native-auth metadata and initialize-only ACP checks. */
+export declare class OpenCodeSetup {
+    private readonly deps;
+    private status;
+    private pending;
+    private controller;
+    readonly models: OpenCodeModels;
+    constructor(deps: {
+        fs: Fs;
+        ps: Ps;
+        home: string;
+    });
+    configure<T>(operation: (signal: AbortSignal) => Promise<T>, requireConnection?: boolean): Promise<T>;
+    readiness(cwd: string, verify?: boolean): Promise<OpenCodeReadiness>;
+    get cwd(): string;
+    read(): OpenCodeStatus;
+    prepare(): Promise<void>;
+    check(): Promise<OpenCodeStatus>;
+    /** Native actions can change credentials; require new observations afterwards. */
+    invalidate(): void;
+    cancel(): void;
+    private command;
+    private probe;
+    private handshake;
+}
+export interface OpenCodeReadiness {
+    cwd: string;
+    selection: OpenCodeSelection | null;
+    ready: boolean;
+    checkedAt: string | null;
+    problem: string | null;
+}

package/setup.d.ts

@@ -0,0 +1,102 @@
+import type { SecretStore } from "webappwiz/creds";
+import type { Fs } from "webappwiz/system";
+import type { OpenCodeSetup } from "./setup-opencode.js";
+/**
+ * Setting splates up on this machine: the roster's steps, which the user has
+ * skipped, kept in `~/.splates/setup.json` so a skipped step stops asking, and
+ * where each stands.
+ */
+export declare class Setup {
+    #private;
+    constructor(machine: SetupMachine, areas: readonly SetupArea[]);
+    /** The step `id` names, refusing one not on the roster. */
+    step(id: string): SetupStep;
+    /** Every step checked, by area, and the one to do next. */
+    read(): Promise<SetupProgress>;
+    /** Stops `id` asking, until `unskip`. */
+    skip(id: string): Promise<void>;
+    /** Asks for `id` again. */
+    unskip(id: string): Promise<void>;
+    /**
+     * Marks setup as seen on this machine, so the page stops nudging a fresh
+     * one towards it.
+     */
+    see(): Promise<void>;
+}
+/** What a step's check reads: this machine's splates home and its device store. */
+export interface SetupMachine {
+    /** Explicit checks from the optional native setup panel; never launch on page load. */
+    opencode?: OpenCodeSetup;
+    fs: Fs;
+    /** `~/.splates`, or a test's own. */
+    home: string;
+    /** The device's secret store, where creds kept for every project live. */
+    device: SecretStore;
+    /** How a check reaches the network, as for Access; the global one by default. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * One thing to set up, small enough that the user does at most one thing for
+ * it. Whether it is done comes from its check against real state, never a
+ * stored flag, so a step undone by hand shows as left again.
+ */
+export interface SetupStep {
+    /** How `splates setup <step>` and the page name it, lowercase-with-dashes. */
+    readonly id: string;
+    readonly title: string;
+    /** Why it matters, in a sentence. */
+    readonly why: string;
+    /** The one thing the user does, in markdown. */
+    readonly user: string;
+    /** What the agent walking the user through it does, in markdown. */
+    readonly agent: string;
+    /** An optional step can be left undone for good; a required one cannot. */
+    readonly optional: boolean;
+    /** The steps that must be done first, on the roster before this one. */
+    readonly after: readonly SetupStep[];
+    /** The cred the user pastes for it, when that is the one thing they do. */
+    readonly cred?: string;
+    /** Whether it is done, from real state. */
+    check(machine: SetupMachine): Promise<boolean>;
+}
+/** A part of setup, such as remote access, and its steps in order. */
+export interface SetupArea {
+    readonly id: string;
+    readonly title: string;
+    readonly steps: readonly SetupStep[];
+}
+/** A step's state: done and skipped are settled, ready can go now, waiting cannot yet. */
+export type StepStatus = "done" | "skipped" | "ready" | "waiting";
+/** A step as `splates setup --json` and `GET /api/setup` give it. */
+export interface StepProgress {
+    id: string;
+    title: string;
+    why: string;
+    user: string;
+    agent: string;
+    optional: boolean;
+    after: string[];
+    status: StepStatus;
+    /** What went wrong checking it, or null when the check ran. */
+    problem: string | null;
+    /** The cred the user pastes for it, or null. */
+    cred: string | null;
+}
+export interface AreaProgress {
+    id: string;
+    title: string;
+    done: number;
+    skipped: number;
+    /** Steps neither done nor skipped. */
+    left: number;
+    steps: StepProgress[];
+}
+export interface SetupProgress {
+    areas: AreaProgress[];
+    /** The one step to do next, or null when nothing is ready. */
+    next: string | null;
+    /** Whether no one has opened setup on this machine yet. */
+    fresh: boolean;
+    /** Whether any required step is neither done nor skipped. */
+    required: boolean;
+}

package/shared-browser.d.ts

@@ -0,0 +1,50 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type { AsyncResource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Fs, HeavyCap, Ps } from "webappwiz/system";
+import { Duration, type Timer } from "webappwiz/time";
+/** Pinned, so the browser it installs is the one it launches. */
+export declare const PLAYWRIGHT_MCP = "@playwright/mcp@0.0.83";
+/**
+ * The name sessions are offered it by, which an agent's own server of that
+ * name gives way to, so its tools keep the names they had.
+ */
+export declare const BROWSER_SERVER = "playwright";
+/** How long the browser stays up with no tool call from any session. */
+export declare const IDLE: Duration;
+/**
+ * The MCP servers each agent session is offered, beyond its own.
+ */
+export interface SessionServers {
+    servers(): Promise<acp.McpServer[]>;
+}
+/**
+ * One headless browser for every agent session on the machine: a Playwright
+ * MCP over HTTP, started on the first session that asks, giving each session
+ * a browser context of its own in one chrome-headless-shell, in place of a
+ * full Chrome and an MCP per session. One that cannot start, or dies, is
+ * logged and offered to no session, which then runs its agent's own.
+ */
+export declare class SharedBrowser implements SessionServers, AsyncResource {
+    private readonly deps;
+    /** Where its config is written. */
+    private readonly dir;
+    /** The MCP while it starts or runs; null before the first ask, or once it died. */
+    private running;
+    constructor(deps: {
+        ps: Ps;
+        fs: Fs;
+        timer: Timer;
+        log: Logger;
+        /** Held while the browser installs and its MCP starts. */
+        heavy: HeavyCap;
+    }, 
+    /** Where its config is written. */
+    dir: string);
+    servers(): Promise<acp.McpServer[]>;
+    disposeAsync(): Promise<void>;
+    private start;
+    private started;
+    /** Where `child` listens, once it says, or null once it dies or `START_WAIT` passes. */
+    private listening;
+}

package/shell.d.ts

@@ -0,0 +1,17 @@
+import { type Ps, type SpawnCaptureResult, type SpawnOptions, type SpawnResult } from "webappwiz/system";
+/** What a `Shell` spawns through; the real process by default. */
+export interface ShellOptions {
+    ps?: Ps;
+}
+/**
+ * Runs the commands a repo configures (the lifecycle hooks) as shell strings
+ * rather than argv, since that is how a repo writes them.
+ */
+export declare class Shell {
+    private readonly ps;
+    constructor(opts?: ShellOptions);
+    /** Captures output, for commands whose failure has to be reported back. */
+    run(command: string, cwd: string, opts?: SpawnOptions): Promise<SpawnCaptureResult>;
+    /** Inherits stdio, for commands the agent should watch as they run. */
+    stream(command: string, cwd: string, opts?: SpawnOptions): Promise<SpawnResult>;
+}