@stringsync/splates 0.0.0-stage → 0.0.45

package/dev-project.d.ts

@@ -0,0 +1,168 @@
+import type { Deps } from "webappwiz/cmd";
+import type { Transcriber } from "webappwiz/dictate";
+import type { AsyncResource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+import type { ConversationState, Conversations } from "./conversations.js";
+import type { SecretStores } from "./creds.js";
+import type { Assets } from "./dev/assets.js";
+import type { TranscriberFor } from "./dev-transcriber.js";
+import type { Everywhere } from "./everywhere.js";
+import type { Format } from "./format.js";
+import type { LaneRecord } from "./lanes.js";
+import { type Needing } from "./needs.js";
+import type { Projects } from "./projects.js";
+import type { Behind, Release } from "./release.js";
+import type { Repository } from "./repository.js";
+import type { Details } from "./show.js";
+import type { Slot } from "./slots.js";
+import type { PortOwners } from "./task-ports.js";
+/**
+ * Everything one project's page talks to: its records, its stream of
+ * changes and its conversations, kept from the first request for it until
+ * the server stops.
+ */
+export declare function serveProject(project: Project, context: DevContext): Promise<Served>;
+/** What `dev` serves a project with: its own records, read and written. */
+export type Project = Pick<Repository, "service" | "journal" | "todos" | "format" | "splatesDir" | "git" | "creds" | "slots"> & {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+};
+/**
+ * What `dev` runs with: the machine's, not any project's, since it serves
+ * every registered project wherever it was started.
+ */
+export type DevMachine = Deps & {
+    fs: Fs;
+    /** Where each project's creds are kept; the system's stores by default. */
+    secrets?: SecretStores;
+    /** How setup's checks reach the network; the global fetch by default. */
+    fetch?: typeof fetch;
+    /** The built page. */
+    assets: Assets;
+    /** Every splates project on this machine. */
+    projects: Projects;
+    /**
+     * Projects opened already, served as they are rather than opened again:
+     * a test's own, with its fakes.
+     */
+    opened?: Project[];
+};
+/** What the server as a whole tells each project it serves. */
+export interface DevContext {
+    /** Where the agents' own `splates` reaches this server, once it listens. */
+    readonly url: string | null;
+    /** A newer splates on npm, once a check has found one; every page says so. */
+    readonly release: Release | null;
+    /** Commits to splates's own source since this run started, once seen. */
+    readonly behind: Behind | null;
+    /** Whether building the page failed, so it serves the one built before. */
+    readonly unbuilt: boolean;
+    /** The slot `splates server --slot` serves under, or null. */
+    readonly slot: Slot | null;
+    /** The conversations `project`'s page may hold, or null when they are off. */
+    conversationsFor(project: Project): Conversations | null;
+    /** Every served project's conversations, where a caller of one may be. */
+    readonly everywhere: Everywhere;
+    /** What `project`'s dictations transcribe with. */
+    readonly transcriberFor: TranscriberFor;
+}
+/** A route's work once its project is known. */
+export type Handler = (request: Request) => Promise<Response>;
+/** One project as the server holds it: what each of its routes does. */
+export interface Served extends AsyncResource {
+    root: string;
+    format: Format;
+    conversations: Conversations | null;
+    /** Reads the repo again soon, telling its pages if anything moved. */
+    refresh: () => void;
+    snapshot: Handler;
+    /** How many of its agents wait on the person. */
+    waiting: () => Promise<number>;
+    /** What each of its agents needs, and the lanes that name an orchestrator. */
+    needing: () => Promise<{
+        rows: Needing[];
+        lanes: LaneRecord[];
+    }>;
+    /** Every lane there has been, to name an orchestrator after. */
+    lanes: () => Promise<LaneRecord[]>;
+    /** Its tasks' worktrees and agents, whose processes' ports are the tasks'. */
+    portOwners: () => Promise<PortOwners>;
+    events: Handler;
+    file: Handler;
+    open: Handler;
+    paths: Handler;
+    systems: Handler;
+    systemChanges: Handler;
+    diff: Handler;
+    retryTask: Handler;
+    removeTask: Handler;
+    addTodo: Handler;
+    updateTodo: Handler;
+    moveTodo: Handler;
+    linkTodo: Handler;
+    arrangeTodo: Handler;
+    assignTodo: Handler;
+    joinLane: Handler;
+    addLane: Handler;
+    updateLane: Handler;
+    dropLane: Handler;
+    removeTodo: Handler;
+    restoreTodo: Handler;
+    listCreds: Handler;
+    saveCred: Handler;
+    removeCred: Handler;
+    dismissCred: Handler;
+    listBudgets: Handler;
+    setBudget: Handler;
+    raiseBudget: Handler;
+    endRaise: Handler;
+    pauseBudget: Handler;
+    resumeBudget: Handler;
+    listConversations: Handler;
+    refreshLimits: Handler;
+    startConversation: Handler;
+    listSessions: Handler;
+    bringSession: Handler;
+    /**
+     * Asks every live conversation here to bring its SPLATES.md up to date,
+     * answering with what settles as each answers.
+     */
+    checkpoint: (only?: string[]) => Promise<Promise<void>[]>;
+    moveConversation: Handler;
+    promptConversation: Handler;
+    tellConversation: Handler;
+    addArtifact: Handler;
+    removeArtifact: Handler;
+    deleteArtifactVersion: Handler;
+    terminateConversation: Handler;
+    conversationAttachment: Handler;
+    conversationArtifact: Handler;
+    answerConversation: Handler;
+    cancelConversation: Handler;
+    pauseConversation: Handler;
+    stopBackground: Handler;
+    backgroundOutput: Handler;
+    unqueueConversation: Handler;
+    sendQueuedNow: Handler;
+    chooseSetting: Handler;
+    renameConversation: Handler;
+    markUnread: Handler;
+    pinConversation: Handler;
+    reparentConversation: Handler;
+    archiveConversation: Handler;
+    conversationEvents: Handler;
+    terminalTree: (request: Request) => Promise<string>;
+    /**
+     * What a dictation transcribes with, read afresh for each take; null,
+     * after asking for the key on the Creds page, without one.
+     */
+    transcriber: () => Promise<Transcriber | null>;
+}
+/**
+ * How many agents wait on the person, as the page's own waiting line counts
+ * them, but for an external agent whose reply the page copied: only the page
+ * knows that.
+ */
+export declare function waitingOn(tasks: Details[], conversations: ConversationState[]): number;

package/dev-push.d.ts

@@ -0,0 +1,59 @@
+import type { Logger } from "webappwiz/log";
+import { type Pusher, type VapidKeys } from "webappwiz/push";
+import type { Fs, Ps } from "webappwiz/system";
+import { Duration } from "webappwiz/time";
+import type { Handler, Served } from "./dev-project.js";
+import type { Projects } from "./projects.js";
+/** How often the server looks for something worth pushing, while a device listens. */
+export declare const PUSH_EVERY: Duration;
+/** What `Pushes` reads each served project through. */
+export interface PushesDeps {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+    projects: Projects;
+    /** By root, every project the server has opened. */
+    served: Map<string, Promise<Served>>;
+    /** What sends a push, signed with the keys kept; the Web Push services by default. */
+    pusher?: (keys: VapidKeys) => Pusher;
+    /** How often to look; `PUSH_EVERY` by default. */
+    every?: Duration;
+}
+/**
+ * Tells each device that subscribed, through its browser's push service,
+ * what the page's own notifications would: an agent that came to wait,
+ * finished its turn or went quiet, in any project the server has open. The
+ * page cannot tell it itself once a phone freezes it, soon after the app
+ * leaves the front. The keys it signs with and the devices it pushes to are
+ * kept in one file for every project on the machine, so a restart keeps them.
+ */
+export declare class Pushes {
+    private readonly deps;
+    private readonly file;
+    private readonly keys;
+    private devices;
+    private readonly pusher;
+    /** By device and project, what the last look saw. */
+    private readonly notices;
+    private readonly tick;
+    private looking;
+    static start(deps: PushesDeps): Promise<Pushes>;
+    private constructor();
+    /** The public key a page subscribes with. */
+    readonly key: Handler;
+    /** Keeps a device's subscription and what it wants, replacing what it said before. */
+    readonly subscribe: Handler;
+    /** Forgets the device whose subscription `endpoint` names. */
+    readonly unsubscribe: Handler;
+    /**
+     * Compares every open project's rows with the last look, for each device,
+     * and pushes each notice it wants. A look still going when the next is due
+     * lets it pass.
+     */
+    look(): Promise<void>;
+    dispose(): void;
+    private lookOnce;
+    private push;
+    private forget;
+    private keep;
+}

package/dev-restart.d.ts

@@ -0,0 +1,141 @@
+import type { AsyncResource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+import { type Project, type Served } from "./dev-project.js";
+import type { ServerChoice } from "./dev-servers.js";
+import type { Terminals } from "./dev-terminal.js";
+import type { Versions } from "./dev-versions.js";
+import type { Projects } from "./projects.js";
+import type { WorkerMachine } from "./worker-machine.js";
+/** The projects `splates server` serves, as its restarts reach them. */
+export interface ServedProjects {
+    /** Each project opened so far, by root. */
+    readonly served: Map<string, Promise<Served>>;
+    /** The project at `root`, opened on first asking. */
+    servedAt(root: string): Promise<Served>;
+    /** The project `slug` names, or the focused one for none. */
+    projectNamed(slug: string): Promise<Served>;
+}
+/** What `Restarts` works with: the machine, and what `splates server` holds. */
+export interface RestartsHome {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+    /** The registry of splates projects. */
+    projects: Projects;
+    served: ServedProjects;
+    terminals: Terminals;
+    /** Where agents and shells run, whose process table says what a restart would kill. */
+    machine: Pick<WorkerMachine, "processes">;
+    /** Stops the whole server, before a restart ends the process. */
+    server: AsyncResource;
+    /** Hands every agent and shell on a worker to the next run, which takes them back; called before the server stops. */
+    handOver(): Promise<void>;
+}
+/** What `Restarts` takes from `dev`'s options. */
+export interface RestartsOptions {
+    exit: ((code: number) => void) | null;
+    open: (root: string) => Promise<Project>;
+    /** Every `splates server` on this machine the page can switch to. */
+    servers: () => Promise<ServerChoice[]>;
+}
+/**
+ * How `splates server` restarts: the checkpoint a restart waits on, the restart
+ * itself, and how this run began. Its handlers are properties, so `dev` hands them to its routes
+ * as they are.
+ */
+export declare class Restarts {
+    private readonly home;
+    private readonly versions;
+    private readonly opts;
+    /**
+     * The restart to follow the checkpoint under way, once every agent has
+     * answered, and whether the next run resumes them, or whether it shuts
+     * down instead, for the next start to resume them; null for none.
+     */
+    private restarting;
+    /**
+     * How this run began, when a checkpoint's restart started it: its agents
+     * `resuming`, told to carry on, until each has.
+     */
+    private restarted;
+    /**
+     * Whether `reopenStopped` has read how this run began, before which a
+     * checkpoint left in the logs may yet be one to resume.
+     */
+    private began;
+    /** This run of `splates server`, so a page can tell it has restarted. */
+    private readonly run;
+    /**
+     * Written by a checkpoint's restart, beside the registry, with the other
+     * projects whose agents it stopped, so the next run opens them at once
+     * and resumes them.
+     */
+    private readonly reopen;
+    private readonly peeked;
+    constructor(home: RestartsHome, versions: Versions, opts: RestartsOptions);
+    /**
+     * Opens the projects a restart stopped agents in, and once they are
+     * served, tells each agent done with the checkpoint to carry on.
+     */
+    reopenStopped(): Promise<void>;
+    readonly listProjects: () => Promise<Response>;
+    /**
+     * Asks every live conversation in each project `projects` names, by slug,
+     * for a checkpoint, then restarts, or shuts down when `after` says to,
+     * once all of them have answered, stopping other projects' agents as they
+     * are; the next run tells each to carry on.
+     */
+    readonly checkpointProjects: (request: Request) => Promise<Response>;
+    /**
+     * Restarts `splates server` now, or with `shutdown` exits for good, without a
+     * checkpoint: an agent at work stops mid-turn, and a command it would
+     * kill dies with it. The next run starts as if started afresh.
+     */
+    readonly powerNow: (request: Request) => Promise<Response>;
+    /**
+     * Restarts `splates server` now, refused while an agent is at work that a
+     * restart would stop (one on a worker carries on through it), or a
+     * command it would kill runs: a job in front in a shell, or one an idle
+     * agent left running.
+     */
+    readonly restartIdle: () => Promise<Response>;
+    readonly forgetProject: (request: Request) => Promise<Response>;
+    /** Each project opened so far, but those that failed to open. */
+    private opened;
+    /**
+     * What a restart would kill: each command an idle agent left running,
+     * unless the agent runs on a worker, which keeps its commands as it keeps
+     * it; the page's shells run there too, and stay. An agent at work that a
+     * restart would stop holds one off on its own.
+     */
+    private holding;
+    private checkpointable;
+    private live;
+    private conversationsIn;
+    private waitingIn;
+    /**
+     * Restarts `splates server` once each checkpoint `asked` has been answered,
+     * unless dismissed meanwhile, or with `shutdown`, exits for good, the
+     * next start reopening and resuming as a restart would. Without
+     * `reopens`, the next run starts as if started afresh, as for a restart
+     * with every agent idle.
+     */
+    private restartAfter;
+    /**
+     * Forgets each checkpoint ended with no run under way to restart or
+     * resume it: left by a run that stopped without saying to resume, as when
+     * killed mid-checkpoint, or in a project opened after the resume. Kept,
+     * it would hold Power on a checkpoint nothing ever ends.
+     */
+    private forgetStale;
+    /** Each conversation a checkpoint has asked, in every project. */
+    private checkpointed;
+    /**
+     * Tells each agent done with the checkpoint to carry on, which ends its
+     * checkpoint once said, and forgets the checkpoint of those it missed.
+     * One whose agent fails to come back has its checkpoint forgotten too,
+     * left failed for the person to open.
+     */
+    private carryOn;
+}

package/dev-servers.d.ts

@@ -0,0 +1,30 @@
+import type { Logger } from "webappwiz/log";
+import type { Fs, Ps } from "webappwiz/system";
+import { type SecretStores } from "./creds.js";
+import { type Slot } from "./slots.js";
+/**
+ * A `splates server` on this machine the page can switch to: the machine's own,
+ * reached at the host `splates tunnel setup` made, or a slot's.
+ */
+export interface ServerChoice {
+    /** The slot it serves under; null for the machine's own. */
+    slot: Slot | null;
+    /** Its page, as in https://fox.example.com. */
+    url: string;
+    /** The checkout that holds the slot; null for the machine's own. */
+    tree: string | null;
+    /** Whether it is the one serving this page. */
+    here: boolean;
+}
+/**
+ * Every `splates server` this machine has a host for: its own, then each slot a
+ * checkout that still exists holds, in the pool's order, whether or not it
+ * runs. Read from the machine's home, which a slot's server is told of, since
+ * its own `SPLATES_HOME` is the slot's.
+ */
+export declare function devServers({ fs, ps, log, secrets, }: {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+    secrets?: SecretStores;
+}): Promise<ServerChoice[]>;

package/dev-setup-native.d.ts

@@ -0,0 +1,23 @@
+import type { Ps } from "webappwiz/system";
+import type { Connection } from "./dev-sockets.js";
+/** Releases the single native setup slot when its command ends. */
+export interface NativeSetupOwner {
+    finished(): void;
+}
+/** A single ephemeral native command. Input/output are never persisted or logged. */
+export declare class NativeSetupConnection implements Connection {
+    private readonly ps;
+    private readonly argv;
+    private readonly cwd;
+    private readonly owner;
+    private child;
+    private socket;
+    private timer;
+    private disposed;
+    constructor(ps: Ps, argv: string[], cwd: string, owner: NativeSetupOwner);
+    open(socket: Bun.ServerWebSocket<Connection>): void;
+    message(_socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    closed(): void;
+    private finish;
+    dispose(): void;
+}

package/dev-setup-opencode.d.ts

@@ -0,0 +1,29 @@
+import type { Ps } from "webappwiz/system";
+import { type HostGate } from "./dev-http.js";
+import type { Connection } from "./dev-sockets.js";
+import { type OpenCodeSetup } from "./setup-opencode.js";
+/** Local/Access-protected setup operations, with no conversation or worker log. */
+export declare class OpenCodeSetupRoutes {
+    readonly setup: OpenCodeSetup;
+    private readonly ps;
+    private readonly gate;
+    private readonly roster;
+    private terminal;
+    constructor(setup: OpenCodeSetup, ps: Ps, gate: HostGate, roster?: SetupRoster);
+    readonly read: () => Promise<Response>;
+    readonly check: () => Promise<Response>;
+    readonly cancel: () => Promise<Response>;
+    readonly models: () => Promise<Response>;
+    readonly refreshModels: () => Promise<Response>;
+    readonly previewModels: (request: Request) => Promise<Response>;
+    readonly applyModels: (request: Request) => Promise<Response>;
+    readiness(cwd: string, verify: boolean): Promise<Response>;
+    readonly disable: () => Promise<Response>;
+    private modelOperation;
+    readonly open: (request: Request, server: Bun.Server<Connection>) => Promise<Response | undefined>;
+    finished(): void;
+    disposeAsync(): Promise<void>;
+}
+export interface SetupRoster {
+    refresh(): Promise<void>;
+}

package/dev-setup.d.ts

@@ -0,0 +1,16 @@
+import type { Setup } from "./setup.js";
+/**
+ * How the page reads this machine's setup and skips its steps. Not any
+ * project's: every page on the server shares one machine. Each handler is a
+ * property, so `dev` hands them straight to its routes.
+ */
+export declare class SetupRoutes {
+    #private;
+    constructor(setup: Setup);
+    /** Every step checked, by area, and the one to do next. */
+    readonly read: () => Promise<Response>;
+    /** Marks setup seen, so the page stops nudging towards it. */
+    readonly see: () => Promise<Response>;
+    /** Skips the step `/api/setup/:step/skipped` names, or asks for it again. */
+    readonly skip: (request: Request) => Promise<Response>;
+}

package/dev-shell.d.ts

@@ -0,0 +1,70 @@
+import type { AsyncResource } from "webappwiz/disposable";
+import type { ProcessEntry } from "webappwiz/system";
+import { Duration, type Timer } from "webappwiz/time";
+import type { ProcessHandle } from "./agent-process.js";
+import type { Connection } from "./dev-sockets.js";
+import type { RemotePty } from "./remote-pty.js";
+import type { RemotePtyOptions } from "./remote-worker.js";
+/** Bigger than any screen, and small enough that a typo cannot hurt. */
+export declare const MAX_SIZE = 1000;
+/**
+ * How long a keyed shell stays once its page's socket goes, for the page to
+ * come back to it: through a reload, or a restart of `splates server`.
+ */
+export declare const TERMINAL_GRACE: Duration;
+/** The shells a terminal opens, as a worker runs them. */
+export type TerminalShell = RemotePty;
+/** What a terminal needs of the worker it runs on. */
+export interface ShellHost {
+    pty(options: RemotePtyOptions): TerminalShell;
+    /** Takes back a shell the worker kept through a restart; see `RemoteWorker.resumePty`. */
+    resumePty(handle: ProcessHandle): TerminalShell;
+    processes(): Promise<ProcessEntry[]>;
+}
+/** A shell handed to the next run of `splates server`, as `coordinator.json` keeps it. */
+export interface KeptShell {
+    key: string;
+    handle: ProcessHandle;
+}
+/**
+ * One shell the server runs for a page's terminal, by its key: the page's
+ * socket shows it, and may go and come back, through a reload or a restart
+ * of `splates server`, the worker redrawing the screen for the one that comes
+ * back. One with no key ends with its socket; one with a key stays
+ * `TERMINAL_GRACE` after it, or until the page says it is closing it.
+ */
+export declare class Shell implements AsyncResource {
+    readonly key: string | null;
+    readonly pty: TerminalShell;
+    /** The worker the shell runs on, where its job in front is read from. */
+    private readonly worker;
+    private readonly timer;
+    /** Hears that the shell is gone: exited, closed, or let go. */
+    private readonly gone;
+    private socket;
+    private grace;
+    private ended;
+    constructor(key: string | null, pty: TerminalShell, 
+    /** The worker the shell runs on, where its job in front is read from. */
+    worker: ShellHost, timer: Timer, 
+    /** Hears that the shell is gone: exited, closed, or let go. */
+    gone: (shell: Shell) => void);
+    /** What the next run takes the shell back by, once it has a key. */
+    get kept(): KeptShell | null;
+    /**
+     * Shows the shell on `socket`, in place of any before it: one come back
+     * to a shell has the worker redraw its screen first.
+     */
+    attach(socket: Bun.ServerWebSocket<Connection>, back: boolean): void;
+    /** Keeps the shell `TERMINAL_GRACE` for a page to come back to it. */
+    wait(): void;
+    /** The page's `socket` went: keyed, the shell waits for it to come back. */
+    detach(socket: Bun.ServerWebSocket<Connection>): void;
+    message(socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    /** Tells the page what the shell runs in front, or null at its prompt. */
+    private front;
+    /** Lets go of the shell for the next run to take back, without ending it. */
+    release(): void;
+    /** Hangs up, as closing a terminal window does. */
+    disposeAsync(): Promise<void>;
+}

package/dev-slot.d.ts

@@ -0,0 +1,28 @@
+import { type Logger } from "webappwiz/log";
+import { type Slot, Slots } from "./slots.js";
+import type { SplatesDeps } from "./splates.js";
+/** How `splates server --slot` starts its server: with what added. */
+export interface SlotStart {
+    slot: Slot;
+    /** The public host it answers on, as in fox.example.com. */
+    host: string;
+    /** The slot's home, its `SPLATES_HOME`, and the word it serves under. */
+    env: Record<string, string>;
+}
+/**
+ * Readies the slot this checkout holds, claimed now when it holds none: its
+ * tunnel, made on the slot's first claim, and its home, `~/.splates/slots/<word>`,
+ * which keeps its own projects, roster and tunnel apart from the machine's, so
+ * it never drives the agents of the `splates server` serving your projects. Its
+ * home starts out with a throwaway project of its own, made on the first
+ * start, so its page has one to show.
+ */
+export declare function devSlot(ctx: SplatesDeps): Promise<SlotStart>;
+/**
+ * Stops the server this tree's slot last ran, if it still runs, as one does
+ * when its wrapper was killed or it was started again: it holds a port, and
+ * its cloudflared still serves the slot's host from it, so the new server
+ * would answer beside old code. Only this tree ever holds the word, so the
+ * server is this task's own to stop.
+ */
+export declare function stopLeftover(slots: Slots, slot: Slot, log: Pick<Logger, "info">): Promise<void>;

package/dev-sockets.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What one WebSocket the server upgraded does, handed over as the socket's
+ * data on the upgrade, since Bun takes one handler for every socket: a
+ * terminal's shell, a dictation's transcription.
+ */
+export interface Connection {
+    open(socket: Bun.ServerWebSocket<Connection>): void;
+    message(socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    /** The socket closed, from either end. */
+    closed(socket: Bun.ServerWebSocket<Connection>): void;
+}
+/** The server's one handler, which leaves each socket to its own connection. */
+export declare const CONNECTIONS: Bun.WebSocketHandler<Connection>;

package/dev-task-ports.d.ts

@@ -0,0 +1,73 @@
+import type { Resource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import { type Clock } from "webappwiz/time";
+import { type Access } from "./dev-access.js";
+import type { Served } from "./dev-project.js";
+import type { Connection } from "./dev-sockets.js";
+import type { RemoteWorker } from "./remote-worker.js";
+import { type PortOwners, type TaskPort } from "./task-ports.js";
+/** One task port, with where to open it. */
+export interface PortLink extends TaskPort {
+    /** On the coordinator's machine. */
+    local: string;
+    /** Through the saved base host, behind Access; null with none saved. */
+    remote: string | null;
+}
+/**
+ * The ports each task's processes listen on, found on the worker that runs
+ * them, as VS Code finds the ports to forward: each one forwarded to a
+ * loopback port here, down the worker's socket, and, under a saved base
+ * host, served at `<task>-<port>.<base>` to whoever Cloudflare Access lets
+ * in, and never without it. DNS and TLS for the base are the operator's.
+ */
+export declare class DevTaskPorts implements Resource, Claimer {
+    private readonly deps;
+    private readonly forwards;
+    private looked;
+    private readonly clock;
+    constructor(deps: {
+        /** The worker the tasks' agents run on. */
+        worker: RemoteWorker;
+        /** Each served project's worktrees and agents. */
+        owners: () => Promise<PortOwners>;
+        /** `<task>-<port>.<base>` is a task port's; null for none. */
+        base: string | null;
+        /** What lets a request reach a task port, which none does without. */
+        access: Access | null;
+        log: Logger;
+        clock?: Clock;
+    });
+    /** Each port a task serves now, forwarded, with its links. */
+    links(): Promise<PortLink[]>;
+    /** `GET /api/ports`: `links`, as JSON. */
+    readonly list: () => Promise<Response>;
+    /**
+     * Answers `request` when its host is a task port's, proxying it to the
+     * task's server; null for any other host, which the page's routes answer.
+     */
+    claim(request: Request, server: Bun.Server<Connection>): Promise<Response | undefined> | null;
+    dispose(): void;
+    private proxy;
+    /** The ports tasks serve: as last seen while fresh, unless `again`. */
+    private look;
+    private read;
+    /**
+     * The forward to `port` on the worker, made on first use. A local
+     * worker's port is open here already, so its forward takes any port; a
+     * remote one's keeps its number when it is free.
+     */
+    private forward;
+    private link;
+}
+/** Every served project's worktrees and agents, those that failed to open left out. */
+export declare function portOwnersOf(served: Map<string, Promise<Served>>): Promise<PortOwners>;
+/** What answers a task port's request before the page's routes do. */
+export interface Claimer {
+    /** Its answer to `request`, or null to leave it to the route. */
+    claim(request: Request, server: Bun.Server<Connection>): Promise<Response | undefined> | null;
+}
+/**
+ * `routes`, each handler asking `claimer` first: Bun matches a route by its
+ * path alone, so a task port's `/` would otherwise reach the page's.
+ */
+export declare function claimedFirst<Routes extends Record<string, unknown>>(routes: Routes, claimer: Claimer): Routes;