@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/channels/agentcore-state.js

@@ -1,276 +0,0 @@
-/**
- * Cross-deploy durability for the state root on AgentCore.
- *
- * WHY THIS EXISTS: AgentCore's managed SessionStorage — the `/mnt/state` mount — is reset on every
- * runtime VERSION UPDATE, i.e. on EVERY deploy ("On runtime version update: Data wiped — fresh file
- * system on next invoke", AWS file-system configuration docs), and again after 14 idle days. The
- * mount is therefore a fast LOCAL disk, not the source of truth. Without this module a deploy
- * silently resurrects the agent with no sessions, no channel dedup, no pending wake-ups — and the
- * wake ALARM, which lives in the operator's EventBridge and survives independently, still fires into
- * that empty store: a miss with no error anywhere (exactly the silent-failure class the repo's
- * fail-visibly rule exists to prevent).
- *
- * The durable copy is ONE S3 object reached through PRESIGNED URLS minted per-envelope by the
- * forwarder Lambda. The container holds no AWS credentials (the platform injects none — verified on
- * a live deployment) and stays AWS-SDK-free: a snapshot is one `fetch` GET and one `fetch` PUT.
- *
- * Format: gzip(JSON `{ v, files: { relPath: base64 } }`). Deliberately NOT tar — the state root is a
- * handful of small JSON/JSONL files, and a single self-describing object makes restore ATOMIC: a
- * half-applied state root is far worse than a slightly stale one.
- */
-import { Buffer } from "node:buffer";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { dirname, join, relative, sep } from "node:path";
-import { gunzipSync, gzipSync } from "node:zlib";
-import { log } from "../log.js";
-import { beginWork } from "./busy.js";
-/** Snapshot envelope version — an unknown version fails the restore loudly (never a silent skip). */
-export const SNAPSHOT_VERSION = 1;
-/** Refuse to pack beyond this (before gzip): a runaway state root would OOM the microVM silently. */
-export const MAX_SNAPSHOT_BYTES = 64 << 20;
-/** Warn past this — the operator should know the snapshot is getting expensive to round-trip. */
-const WARN_SNAPSHOT_BYTES = 16 << 20;
-/** Upload deadline. Generous (a large snapshot on a cold network) but finite. */
-const PUT_TIMEOUT_MS = 60_000;
-/**
- * Files the snapshot must NOT carry. `control.json` is a PER-BOOT artifact (this process's control
- * URL + token, written once the port is known): snapshotting it would hand the next boot a file
- * advertising a dead endpoint and a token that no longer matches the one in memory.
- *
- * Everything else is durable and restores VERBATIM — including `auth.json`. The deploy seeds that
- * file from the builder machine, but the box's own copy is the one that has been REFRESHED, and this
- * snapshot is its volume: the same rule every other host states ("a credential already refreshed on
- * the volume is never overwritten"). The seed is bootstrap for a snapshot that has none.
- *
- * That sentence is only true because the generated template points FASTAGENT_SECRETS_DIR INSIDE the
- * state root (deploy/agentcore/plan.ts `SECRETS_DIR`) — nothing here special-cases credentials, the
- * walk below simply reaches them. Moving the secrets dir back out (e.g. to the sibling layout the
- * volume-backed hosts use) silently un-does it: the file stops being copied, the platform wipes it
- * with the microVM, and a single-use OAuth refresh token dies with it. `restores VERBATIM` is a
- * statement about where that directory is, not a property this module can enforce on its own.
- */
-const EXCLUDED = new Set(["control.json"]);
-/** Every regular file under `root`, as root-relative POSIX paths (stable across platforms). */
-async function walk(root, dir = root, out = []) {
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return out;
-        throw e;
-    }
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        // Symlinks/sockets/FIFOs are skipped on purpose: the state root holds plain files, and
-        // AgentCore's session storage does not support special files anyway.
-        if (entry.isDirectory())
-            await walk(root, full, out);
-        else if (entry.isFile())
-            out.push(relative(root, full).split(sep).join("/"));
-    }
-    return out;
-}
-/** Pack the whole state root into one gzipped snapshot object.
- *  ponytail: the WHOLE root, every idle edge — O(state size) per settled turn, and session jsonl
- *  grows without bound. Upgrade path when the 16 MiB warning is real for someone: a per-file
- *  manifest with content hashes, uploading only what changed. */
-export async function packStateRoot(stateRoot, maxBytes = MAX_SNAPSHOT_BYTES) {
-    const files = {};
-    let raw = 0;
-    for (const rel of await walk(stateRoot)) {
-        if (EXCLUDED.has(rel))
-            continue;
-        const content = await readFile(join(stateRoot, rel));
-        raw += content.byteLength;
-        if (raw > maxBytes) {
-            throw new Error(`state root exceeds ${maxBytes} bytes — it cannot be snapshotted for cross-deploy durability`);
-        }
-        files[rel] = content.toString("base64");
-    }
-    if (raw > WARN_SNAPSHOT_BYTES) {
-        log.warn(`[agentcore] state snapshot is large (${Math.round(raw / (1 << 20))} MiB) — every turn round-trips it`);
-    }
-    return gzipSync(Buffer.from(JSON.stringify({ v: SNAPSHOT_VERSION, files })));
-}
-/** Apply a snapshot over the state root. Returns how many files were written. */
-export async function unpackIntoStateRoot(stateRoot, packed) {
-    let snapshot;
-    try {
-        snapshot = JSON.parse(gunzipSync(packed).toString());
-    }
-    catch (e) {
-        throw new Error(`state snapshot is unreadable (${String(e)})`);
-    }
-    if (snapshot?.v !== SNAPSHOT_VERSION || typeof snapshot.files !== "object" || snapshot.files === null) {
-        throw new Error(`state snapshot has an unsupported shape (v=${String(snapshot?.v)})`);
-    }
-    let written = 0;
-    for (const [rel, b64] of Object.entries(snapshot.files)) {
-        // A snapshot is written by this same code, but it arrives over the network: refuse anything
-        // that could escape the state root.
-        if (rel.startsWith("/") || rel.split("/").includes("..")) {
-            throw new Error(`state snapshot contains an unsafe path (${rel})`);
-        }
-        if (EXCLUDED.has(rel))
-            continue; // never write a per-boot artifact from an older boot
-        const target = join(stateRoot, rel);
-        await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, Buffer.from(b64, "base64"));
-        written += 1;
-    }
-    return written;
-}
-export function createStateSync(options) {
-    const { stateRoot } = options;
-    const doFetch = options.fetchImpl ?? fetch;
-    let urls;
-    let restore;
-    let restored = false;
-    let saving;
-    let queued = false;
-    // Whether the upload loop is still able to pick up another round. Counting the upload as in-flight
-    // work (below) means ITS completion is itself a 0-in-flight edge, which re-enters save() — without
-    // this the snapshot would queue a redundant follow-up after every single upload.
-    let looping = false;
-    const runRestore = async (urls) => {
-        const res = await doFetch(urls.getUrl, { method: "GET" });
-        // ONLY a proven 404 is "first deploy". A missing key answers 404 only because the generated
-        // template grants the signer s3:ListBucket on the snapshot prefix — without it S3 folds "absent"
-        // into 403 (anti-enumeration). A 403 therefore means an expired or malformed signature, a
-        // revoked permission, or a template from before that grant — i.e. the snapshot may well exist.
-        // Reading 403 as "absent" would serve an empty agent and then overwrite the real snapshot with
-        // that emptiness.
-        if (res.status === 404) {
-            log.info("[agentcore] no state snapshot yet — starting from an empty state root (first deploy)");
-            restored = true;
-            return;
-        }
-        if (!res.ok) {
-            const hint = res.status === 403
-                ? " (an expired presigned URL, a revoked permission, or a template generated before the " +
-                    "ForwarderRole granted s3:ListBucket — S3 answers 403 even for a MISSING first-deploy " +
-                    "snapshot without it; regenerate with `fastagent deploy agentcore --force` and redeploy)"
-                : "";
-            throw new Error(`state snapshot GET failed: ${res.status}${hint}`);
-        }
-        const written = await unpackIntoStateRoot(stateRoot, Buffer.from(await res.arrayBuffer()));
-        log.info(`[agentcore] restored ${written} state file(s) from the snapshot`);
-        restored = true;
-    };
-    const refreshUrls = async () => {
-        if (!urls?.refresh)
-            return;
-        const res = await doFetch(urls.refresh.url, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ auth: urls.refresh.auth }),
-            signal: AbortSignal.timeout(PUT_TIMEOUT_MS),
-        });
-        if (!res.ok)
-            throw new Error(`state snapshot URL refresh failed: ${res.status}`);
-        const fresh = (await res.json());
-        if (typeof fresh.getUrl !== "string" || typeof fresh.putUrl !== "string") {
-            throw new Error("state snapshot URL refresh returned an invalid response");
-        }
-        urls = { ...urls, getUrl: fresh.getUrl, putUrl: fresh.putUrl };
-    };
-    const runSave = async () => {
-        // Counted as in-flight work for its whole duration: `save()` fires on the 0-in-flight edge, the
-        // exact moment /ping starts answering Healthy — without this the platform may reclaim the microVM
-        // mid-upload and the turn that just finished is lost with only a log line. Bounded too: a hung
-        // PUT would otherwise pin `saving` forever and block every later snapshot.
-        const workDone = beginWork();
-        looping = true;
-        try {
-            do {
-                queued = false;
-                if (!restored || !urls)
-                    return;
-                // A webhook turn may settle hours after its envelope. Re-mint immediately before every PUT
-                // instead of assuming the Lambda credentials that signed the envelope outlive the turn.
-                await refreshUrls();
-                const body = await packStateRoot(stateRoot);
-                const res = await doFetch(urls.putUrl, {
-                    method: "PUT",
-                    body: new Uint8Array(body),
-                    signal: AbortSignal.timeout(PUT_TIMEOUT_MS),
-                });
-                if (!res.ok) {
-                    const hint = res.status === 403 ? " (presigned URL or its temporary signing credentials may have expired)" : "";
-                    throw new Error(`state snapshot PUT failed: ${res.status}${hint}`);
-                }
-            } while (queued);
-        }
-        finally {
-            looping = false;
-            workDone();
-        }
-    };
-    return {
-        use(next) {
-            urls = next;
-        },
-        configured() {
-            return urls !== undefined;
-        },
-        ready() {
-            // No URLs = not an ingress envelope (a direct invoke has its own isolated storage): nothing to
-            // restore, and deliberately NOT cached, so the first envelope that does carry them still runs
-            // the restore.
-            if (!urls)
-                return Promise.resolve();
-            // One attempt per process otherwise: a rejected restore stays rejected so every subsequent
-            // envelope fails the same visible way instead of quietly serving an empty agent.
-            restore ??= runRestore(urls);
-            return restore;
-        },
-        save() {
-            if (!restored)
-                return; // never overwrite a good snapshot with a state root we failed to fill
-            if (saving) {
-                if (looping)
-                    queued = true; // otherwise this is the upload's own completion edge, not new work
-                return;
-            }
-            saving = runSave()
-                .catch((e) => {
-                log.error(`[agentcore] could not save the state snapshot: ${String(e)} — retrying when work next settles`);
-            })
-                .finally(() => {
-                saving = undefined;
-            });
-        },
-        async flush() {
-            while (saving)
-                await saving;
-        },
-        async checkpoint() {
-            if (!urls) {
-                return { written: false, reason: "this session has never served a forwarder envelope" };
-            }
-            if (!restored) {
-                return { written: false, reason: "the state root is not authoritative here (nothing restored)" };
-            }
-            // Never overlap an in-flight upload, then run a FRESH one: joining the running round could
-            // return before the bytes written moments ago (the interrupted turn's intent) are included.
-            while (saving)
-                await saving;
-            const run = runSave();
-            // Stored form never rejects (an unawaited rejection would be an unhandled crash); the caller
-            // awaits `run` itself and gets the error.
-            saving = run.then(() => { }, () => { });
-            const settle = saving.finally(() => {
-                saving = undefined;
-            });
-            try {
-                await run;
-            }
-            finally {
-                await settle;
-            }
-            return { written: true };
-        },
-    };
-}

package/dist/channels/github/github.d.ts

@@ -1,31 +0,0 @@
-import type { Schema } from "@octokit/webhooks-types";
-import type { ChannelModule } from "../../channel.ts";
-/** A verified GitHub webhook event. Header fields plus the official typed payload. */
-export interface GithubEvent {
-    /** `X-GitHub-Event` (e.g. "pull_request", "issue_comment"). */
-    event: string;
-    /** `payload.action` (e.g. "opened"), when present — the usual routing discriminant. */
-    action?: string;
-    /** `X-GitHub-Delivery` — unique per delivery. */
-    deliveryId: string;
-    /** The native payload (union of all events); narrow it, e.g. `if ("pull_request" in event.payload)`. */
-    payload: Schema;
-}
-/** What `on` returns per acted-on delivery: a session + the prompt text for the agent turn. */
-export interface Intent {
-    session: string;
-    text: string;
-}
-export interface GithubChannelOptions {
-    /** Webhook secret — verifies inbound deliveries (HMAC-SHA256 over the raw body). */
-    secret: string;
-    /** Map a verified event to the intents this agent acts on (empty array = ignore). */
-    on: (event: GithubEvent) => Intent[];
-}
-/**
- * Build a GitHub webhook channel: policy options in, a {@link ChannelModule} out (mounts
- * `POST /webhook`). `agent` arrives via the mount context. The adapter owns that route key; to serve
- * it elsewhere, re-key the returned module:
- * `(ctx) => ({ "POST /gh": githubChannel(opts)(ctx)["POST /webhook"]! })`.
- */
-export declare function githubChannel({ secret, on }: GithubChannelOptions): ChannelModule;

package/dist/channels/github/github.js

@@ -1,89 +0,0 @@
-/**
- * GitHub webhook channel: verify → route via `on(event)` → fire-and-forget agent turns, ACK 202.
- * The developer writes only `on`. Concurrency safety is the engine's per-session lease. A turn that
- * fails after the 202, or an in-flight turn on shutdown, is lost (server log only).
- */
-import { verify } from "@octokit/webhooks-methods";
-import { collect } from "../../collect.js";
-import { log } from "../../log.js";
-import { readBodyCapped } from "../body.js";
-import { beginWork } from "../busy.js";
-import { text } from "../respond.js";
-/** Raw body cap before verification — GitHub caps webhook payloads at 25 MB; reject larger early. */
-const MAX_WEBHOOK_BYTES = 25 << 20;
-/**
- * Build a GitHub webhook channel: policy options in, a {@link ChannelModule} out (mounts
- * `POST /webhook`). `agent` arrives via the mount context. The adapter owns that route key; to serve
- * it elsewhere, re-key the returned module:
- * `(ctx) => ({ "POST /gh": githubChannel(opts)(ctx)["POST /webhook"]! })`.
- */
-export function githubChannel({ secret, on }) {
-    const channel = ({ agent }) => ({
-        "POST /webhook": async (req) => {
-            if (req.method !== "POST")
-                return text("POST only\n", 405);
-            // Cap before verify: a public endpoint must not buffer an unbounded body (chunked bypasses Content-Length).
-            const body = await readBodyCapped(req, MAX_WEBHOOK_BYTES);
-            if ("tooLarge" in body)
-                return text("payload too large\n", 413);
-            const raw = body.text;
-            // Fail closed: verify() throws on an empty/missing arg, so treat any verify error as a clean 401.
-            const signature = req.headers.get("x-hub-signature-256");
-            if (!signature || !(await verify(secret, raw, signature).catch(() => false))) {
-                return text("invalid signature\n", 401);
-            }
-            const eventName = req.headers.get("x-github-event") ?? "";
-            if (eventName === "ping")
-                return new Response(null, { status: 204 });
-            // x-www-form-urlencoded (GitHub's UI default) wraps the JSON in a `payload` field; json is the body.
-            let json = raw;
-            if ((req.headers.get("content-type") ?? "").includes("application/x-www-form-urlencoded")) {
-                const field = new URLSearchParams(raw).get("payload");
-                if (field === null)
-                    return text("missing form payload\n", 400);
-                json = field;
-            }
-            let payload;
-            try {
-                payload = JSON.parse(json);
-            }
-            catch {
-                return text("invalid json\n", 400);
-            }
-            const event = {
-                event: eventName,
-                action: typeof payload.action === "string" ? payload.action : undefined,
-                deliveryId: req.headers.get("x-github-delivery") ?? "",
-                payload: payload, // trust boundary: the verified body is a GitHub event
-            };
-            // Fire each turn, return 202; the process runs them to completion. The lifecycle is logged to
-            // stderr — after the 202 there is no response body, so these lines are the operator's only signal
-            // (and the sink that keeps a post-ACK error from going unhandled).
-            const intents = on(event);
-            const label = event.action ? `${event.event}.${event.action}` : event.event;
-            for (let i = 0; i < intents.length; i++) {
-                const { session, text } = intents[i];
-                // Per-turn correlation id (deliveryId is unique per webhook; the index disambiguates fan-out),
-                // threaded through start/done/failed so a terminal line joins back to its start.
-                const turn = `${event.deliveryId}#${i}`;
-                log.info(`[github] turn start: turn=${turn} session=${session} event=${label}`);
-                const startedAt = Date.now();
-                // Post-ACK turns are process-wide in-flight work (busy.ts): a serving surface that must not
-                // idle mid-turn (the AgentCore /ping's HealthyBusy) has no other way to see them — and github
-                // turns have NO replay, so an idle reclaim here loses the review outright.
-                const workDone = beginWork();
-                void collect(agent.invoke({ session }, { text }))
-                    .then(() => log.info(`[github] turn done: turn=${turn} session=${session} (${Date.now() - startedAt}ms)`), (error) => log.error(`[github] turn failed: turn=${turn} session=${session} (${Date.now() - startedAt}ms): ${String(error)}`))
-                    .finally(workDone);
-            }
-            return new Response(null, { status: 202 });
-        },
-    });
-    return (ctx) => {
-        // Validate at activation so deploy may inspect the module shape before secrets are provisioned.
-        if (!secret) {
-            throw new Error("githubChannel requires a non-empty secret (the GitHub webhook secret, e.g. GITHUB_WEBHOOK_SECRET)");
-        }
-        return channel(ctx);
-    };
-}

package/dist/channels/github/scaffold/channel.ts

@@ -1,25 +0,0 @@
-import { githubChannel } from "@fastagent-sh/fastagent/github";
-
-// A channel = a third-party ADAPTER (githubChannel: verify + parse + ACK) configured with YOUR on() policy.
-// fastagent discovers this file under channels/, mounts POST /webhook, and pipes the agent to the
-// adapter — this file holds only policy. Set GITHUB_WEBHOOK_SECRET in .env (a missing secret fails at
-// startup — an empty key would accept forged deliveries) and point a GitHub webhook (JSON) at POST /webhook.
-export default githubChannel({
-  secret: process.env.GITHUB_WEBHOOK_SECRET ?? "",
-  // Map a verified event to the intents the agent acts on (empty array = ignore). Each review is
-  // INDEPENDENT and idempotent (it reconciles against the PR's existing comments), so use a
-  // distinct per-delivery session (event.deliveryId): overlapping deliveries then run on their
-  // own session without a shared-lease drop.
-  on: (event) => {
-    if (event.event === "pull_request" && event.action === "opened" && "pull_request" in event.payload) {
-      const { repository, pull_request } = event.payload;
-      return [
-        {
-          session: event.deliveryId,
-          text: `Review pull request #${pull_request.number} in ${repository.full_name}.`,
-        },
-      ];
-    }
-    return [];
-  },
-});

package/dist/cli/commands/attach.d.ts

@@ -1,108 +0,0 @@
-import { type SessionControl, type SessionEntry } from "../../session.ts";
-export interface AttachOptions {
-    /** Override the control endpoint (skip control.json discovery) — for a remote serve. */
-    url?: string;
-    token?: string;
-}
-export declare function runAttach(sessionArg: string, dirArg: string | undefined, opts: AttachOptions): Promise<void>;
-/** One round's observed facts, gathered by the loop (IO) and judged by {@link decideRound} (pure). */
-export type RoundOutcome = {
-    type: "progress";
-}
-/** Clean end that delivered nothing — indistinguishable from a half-dead proxy closing every stream. */
- | {
-    type: "empty";
-} | {
-    type: "error";
-    error: unknown;
-    isAuth: boolean;
-    /** discover(dir) compared against the current endpoint; remote endpoints report "unavailable". */
-    discovery: "unchanged" | "changed" | "unavailable";
-    /** The freshly discovered credentials when {@link discovery} is "changed". */
-    fresh?: {
-        url: string;
-        token: string;
-    };
-};
-export type RoundDecision = {
-    kind: "reset";
-} | {
-    kind: "exit";
-    message: string;
-} | {
-    kind: "try-reattach";
-    fresh: {
-        url: string;
-        token: string;
-    };
-} | {
-    kind: "retry";
-    warn: string;
-};
-/**
- * The reconnect policy for BOTH phases (`startup` = connectWithGrace, `steady` = the round loop),
- * pure and testable: every exit diagnosis and budget claim lives here. `downMs` is wall-clock time
- * since the phase's anchor (first connect attempt / first non-progress round). The phases differ
- * on priors, not principle: startup has never succeeded (short budget; a remote non-auth error
- * exits at once), steady-state had a working attach (longer budgets); the local-401-unchanged
- * diagnosis and reattach-on-changed-credentials apply identically to both.
- */
-export declare function decideRound(outcome: RoundOutcome, ctx: {
-    discovered: boolean;
-    downMs: number;
-    phase?: "startup" | "steady";
-}): RoundDecision;
-/** What one ROUND prints through (streamed deltas included), so tests can observe every path a
- *  round writes. Round output only: stdin-side acceptance/rejection lines print directly — they
- *  are immediate feedback to a user action and may interleave with a replay block. Timing knobs
- *  travel as their own parameter. */
-export interface AttachIo {
-    println: (line: string) => void;
-    /** Raw chunk, no newline — the streamed message_delta path. */
-    write: (chunk: string) => void;
-    warn: (line: string) => void;
-}
-/**
- * The backfill slice REDUCED TO THE ACTIVE PATH — a session is a tree (a leaf move, or a
- * compaction, leaves sibling branches behind), and printing the slice raw renders the abandoned
- * branch interleaved with the live one as if it were one conversation. Reachability is computed
- * backwards from the leaf; an entry whose parent lies BEFORE the slice is path-connected by
- * construction (its ancestors were rendered in an earlier round), so only what the walk cannot
- * reach is dropped. An engine that reports NO leaf says nothing about branches, so its slice stands
- * whole — the one case where "unknown" must not read as "off-path".
- */
-export declare function activePathSlice(entries: SessionEntry[], leafEntryId: string | undefined): SessionEntry[];
-/**
- * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
- * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
- * differently:
- *
- * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
- *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
- *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
- *   about to prove it names a real skill;
- * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
- * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
- *   an intent the typo did not express.
- *
- * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
- * printing them with a slash would invite the user straight back into this branch. Returns the
- * promise for the remote half, so a caller (or a test) can await the second line.
- */
-export declare function answerSlashInput(trimmed: string, control: Pick<SessionControl, "commands">, println: (line: string) => void): Promise<void>;
-/**
- * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
- * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager
- * registration (subscribed before response headers) covers the cursor→subscription window in the
- * normal case; `settleMs` is a HEURISTIC — on a very slow link an event can still land between the
- * backfill and the subscription taking effect, surfacing only at the next round's replay. Live
- * events carry no entry ids, so the cursor advances only on backfill; a replay may overlap what
- * was already seen live — labeled, not silently dropped. A 401 (stale token after a serve restart)
- * is thrown to the caller: unrecoverable here, never retried silently.
- */
-export declare function attachRound(control: SessionControl, session: string, cursor: string | undefined, io: AttachIo, 
-/** The subscribe→sync settle heuristic (see the round comment). Tests shrink it. */
-settleMs?: number): Promise<{
-    cursor: string | undefined;
-    sawProgress: boolean;
-}>;