@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/channels/agentcore.js

@@ -0,0 +1,260 @@
+/**
+ * AWS AgentCore Runtime adapter: serve fastagent's whole HTTP surface through the Runtime's service
+ * contract. AgentCore gives a container exactly TWO paths — `POST /invocations` (the only ingress,
+ * reached via the SigV4 `InvokeAgentRuntime` API) and `GET /ping` (health) — and no public URL, so
+ * the deployment fronts webhooks with a thin forwarder Lambda and delivers cron slots from
+ * EventBridge Scheduler; both arrive here as an ENVELOPE in the /invocations payload:
+ *
+ *  - `{ kind: "webhook", method, path, headers?, bodyB64? }` — a verbatim webhook request captured
+ *    by the forwarder. Reconstructed into a real `Request` and dispatched to the SAME channel routes
+ *    a direct deployment serves — signature verification (Telegram secret token, Feishu signatures)
+ *    runs unchanged inside the channel. The channel's HTTP response travels back INSIDE the
+ *    transport reply (`{ status, headers, bodyB64 }`, transport always 200): AgentCore folds a
+ *    container non-2xx into its own 424 RuntimeClientError, so riding the real status inside the
+ *    envelope is the only way the forwarder can re-emit it verbatim (a Feishu URL-verification
+ *    challenge needs the exact body + content-type back).
+ *  - `{ kind: "schedule-fire", name, slot }` — one cron instant from the external clock. Dispatched
+ *    to {@link fireScheduleOnce}-shaped `fire` with the slot as the idempotency key (EventBridge
+ *    delivery is at-least-once; a duplicate slot must not double-fire).
+ *  - `{ kind: "invoke", session, text }` — the programmatic data plane; streams the invoke back as
+ *    SSE (AgentCore's streaming response form), reusing the HTTP channel's handler wholesale.
+ *
+ * `/ping` reports `HealthyBusy` while process-wide background work is in flight (busy.ts) — webhook
+ * channels ACK fast and run turns fire-and-forget, and AgentCore ends an idle session, so without
+ * this signal a long turn would be killed mid-flight right after its ACK. `Healthy` when idle lets
+ * the platform reclaim the microVM (that idle-to-zero IS the point of this deployment).
+ */
+import { Buffer } from "node:buffer";
+import { timingSafeEqual } from "node:crypto";
+import { beginWork, onIdle } from "./busy.js";
+import { router } from "../host/node.js";
+import { log } from "../log.js";
+import { rememberWakeAlarmUrl } from "../schedule/wake-alarm.js";
+import { readBodyCapped } from "./body.js";
+import { createInvokeHandler } from "./http.js";
+import { text } from "./respond.js";
+import { MAX_ENVELOPE_BYTES, MAX_WEBHOOK_BODY_BYTES } from "./agentcore-limits.js";
+const unsnapshottedWarning = "[agentcore] this envelope carried no state-snapshot URLs — the state root is LOCAL ONLY and the " +
+    "platform erases it on the next deploy (redeploy with a current fastagent to restore durability)";
+const jsonHeaders = { "content-type": "application/json" };
+const json = (body, status) => new Response(`${JSON.stringify(body)}\n`, { status, headers: jsonHeaders });
+/** Compare an untrusted envelope secret without leaking a matching-prefix timing signal. */
+function secretMatches(actual, expected) {
+    if (typeof actual !== "string" || expected === undefined)
+        return false;
+    const actualBytes = Buffer.from(actual);
+    const expectedBytes = Buffer.from(expected);
+    return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+/**
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }`. The caller merges it
+ * over its routes (collision-checked at the mount site, serve.ts) — the inner routes stay mounted
+ * too, which is harmless (AgentCore routes only /invocations and /ping into the container) and keeps
+ * a local `curl` debug surface.
+ */
+export function agentcoreRoutes(options) {
+    const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
+    const dispatch = router(routes);
+    const invokeHandler = createInvokeHandler(agent);
+    // Snapshot on the 0-in-flight edge: webhook channels ACK fast and finish the turn in the
+    // background, so "the request returned" is NOT when the state root settles.
+    if (stateSync)
+        onIdle(() => stateSync.save());
+    let warnedUnsnapshotted = false;
+    let stateReadyFired = false;
+    const handleInvocation = async (req) => {
+        const body = await readBodyCapped(req, MAX_ENVELOPE_BYTES);
+        if ("tooLarge" in body)
+            return text("envelope too large\n", 413);
+        let envelope;
+        try {
+            envelope = JSON.parse(body.text);
+        }
+        catch {
+            return text("invalid json\n", 400);
+        }
+        if (envelope === null || typeof envelope !== "object" || typeof envelope.kind !== "string") {
+            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint", ... }\n', 400);
+        }
+        // AUTHENTICATION BOUNDARY. `InvokeAgentRuntime` is an ordinary IAM action, so "reached this
+        // handler" proves nothing about the sender. Only an envelope carrying the shared secret is the
+        // forwarder's; anything else is the PUBLIC data plane, which may run exactly one kind (`invoke`)
+        // and may NOT carry internal fields — riding a `state` or `wake` URL on a public invoke would
+        // redirect the state snapshot (auth.json) or the alarm callback (the wake secret) to the caller.
+        // Internal fields are DROPPED rather than rejected: a public caller has no business knowing them.
+        const trusted = secretMatches(envelope.auth, ingressSecret);
+        if (!trusted) {
+            if (envelope.kind !== "invoke") {
+                log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
+                return text("forbidden\n", 403);
+            }
+            envelope.wake = undefined;
+            envelope.state = undefined;
+        }
+        // The forwarder rides its public URL along on every envelope — persist it (write-if-changed) so
+        // the wake-alarm sink can call back. Written AFTER the restore below: a stale snapshot copy must
+        // not win over the URL this deployment is actually reachable at. A bad persist must not fail the turn.
+        const rememberUrl = () => {
+            if (typeof envelope.wake?.url !== "string")
+                return;
+            try {
+                rememberWakeAlarmUrl(stateRoot, envelope.wake.url);
+            }
+            catch (e) {
+                log.error(`[agentcore] could not persist the wake-alarm URL: ${String(e)}`);
+            }
+        };
+        // Cross-deploy state: the platform wipes /mnt/state on every version update, so the durable copy
+        // must be pulled back BEFORE anything reads it. A failed restore fails the request — serving an
+        // empty agent (and then snapshotting that emptiness over the good copy) is the worse outcome.
+        if (stateSync) {
+            if (envelope.state && typeof envelope.state.getUrl === "string" && typeof envelope.state.putUrl === "string") {
+                stateSync.use(envelope.state);
+            }
+            else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
+                // webhook/schedule-fire/wake-poke reach us ONLY through the forwarder, which always mints the
+                // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
+                // once per process (a direct `invoke` legitimately has none — its session storage is its own).
+                warnedUnsnapshotted = true;
+                log.warn(unsnapshottedWarning);
+            }
+            try {
+                await stateSync.ready();
+            }
+            catch (e) {
+                log.error(`[agentcore] state restore failed: ${String(e)}`);
+                return text(`state restore failed: ${String(e)}\n`, 503);
+            }
+        }
+        rememberUrl();
+        // The state root is authoritative only now — anything that must READ it at startup (the wake-alarm
+        // reconcile) runs here, once, rather than at boot against a mount the platform just wiped.
+        if (onStateReady && !stateReadyFired) {
+            stateReadyFired = true;
+            onStateReady();
+        }
+        switch (envelope.kind) {
+            case "webhook": {
+                const { method, path, query, headers, bodyB64 } = envelope;
+                if (typeof method !== "string" || typeof path !== "string" || !path.startsWith("/")) {
+                    return text('webhook envelope needs { "method": string, "path": "/..." }\n', 400);
+                }
+                if (typeof bodyB64 === "string" && Buffer.byteLength(bodyB64, "base64") > MAX_WEBHOOK_BODY_BYTES) {
+                    return json({
+                        status: 413,
+                        headers: { "content-type": "text/plain" },
+                        bodyB64: Buffer.from("payload too large\n").toString("base64"),
+                    }, 200);
+                }
+                const inner = new Request(`http://agentcore.local${path}${typeof query === "string" && query !== "" ? `?${query}` : ""}`, {
+                    method,
+                    headers: headers ?? {},
+                    body: typeof bodyB64 === "string" && method !== "GET" && method !== "HEAD"
+                        ? Buffer.from(bodyB64, "base64")
+                        : undefined,
+                });
+                const response = await dispatch(inner);
+                // Buffer the channel's ACK (webhook ACKs are small by design — the turn itself runs
+                // fire-and-forget) and ride it inside the transport reply, byte-exact.
+                const replyBody = Buffer.from(await response.arrayBuffer());
+                const replyHeaders = {};
+                response.headers.forEach((value, key) => {
+                    replyHeaders[key] = value;
+                });
+                const reply = {
+                    status: response.status,
+                    headers: replyHeaders,
+                    bodyB64: replyBody.toString("base64"),
+                };
+                return json(reply, 200);
+            }
+            case "schedule-fire": {
+                const { name, slot } = envelope;
+                if (typeof name !== "string" || typeof slot !== "string" || Number.isNaN(Date.parse(slot))) {
+                    return text('schedule-fire envelope needs { "name": string, "slot": ISO-date }\n', 400);
+                }
+                // No fire capability (no schedules in this definition) or an unknown name is deploy drift —
+                // an external clock rule outliving the schedule it fired for. 404 keeps it VISIBLE in the
+                // clock's logs (a 200 would silently absorb every future fire).
+                if (!fire)
+                    return text(`no schedules in this deployment (schedule-fire "${name}")\n`, 404);
+                // The whole agent turn runs inside this request — but the CALLER (the forwarder Lambda) may
+                // time out and drop the connection while the turn keeps running server-side. Count it as
+                // in-flight work so /ping holds the session (HealthyBusy) for the remainder.
+                const workDone = beginWork();
+                try {
+                    const outcome = await fire(name, new Date(slot));
+                    return json(outcome, 200);
+                }
+                catch (e) {
+                    if (e instanceof UnknownScheduleError)
+                        return text(`${e.message}\n`, 404);
+                    // A claim-state fault (unreadable/unwritable fires.json) — surface it as the request's
+                    // failure so the external clock's logs carry it (fail visibly, never a silent absorb).
+                    log.error(`[agentcore] schedule-fire ${name} failed: ${String(e)}`);
+                    return text(`schedule-fire failed: ${String(e)}\n`, 500);
+                }
+                finally {
+                    workDone();
+                }
+            }
+            case "checkpoint": {
+                // Deliberately does NOT wait for idle: the durable turn intent is persisted BEFORE the
+                // webhook ACK (turn-store.ts), so a flush right now already carries the interrupted turn —
+                // and blocking a deploy on a turn that may run for minutes would be the worse trade.
+                if (!stateSync)
+                    return json({ written: false, reason: "no state sync in this deployment" }, 200);
+                try {
+                    // The reply is the ONLY thing telling the operator whether an in-flight turn was
+                    // protected, so it reports what actually happened — `written: false` (nothing to write)
+                    // reads differently from `written: true`, and a failure is a failure.
+                    return json(await stateSync.checkpoint(), 200);
+                }
+                catch (e) {
+                    log.error(`[agentcore] checkpoint failed: ${String(e)}`);
+                    return text(`checkpoint failed: ${String(e)}\n`, 500);
+                }
+            }
+            case "wake-poke": {
+                // The poke's job is DONE by arriving: the invocation woke (or kept awake) the container, and
+                // the wake pump (boot drain + 30s poll) fires whatever is due. Nothing to dispatch.
+                return json({ ok: true }, 200);
+            }
+            case "invoke": {
+                // Reuse the HTTP channel's handler wholesale (SSE, cancellation, backpressure) by handing it
+                // the shape it already validates — one protocol, one implementation.
+                const inner = new Request("http://agentcore.local/invoke", {
+                    method: "POST",
+                    headers: jsonHeaders,
+                    body: JSON.stringify({ session: envelope.session, text: envelope.text }),
+                });
+                return invokeHandler(inner);
+            }
+            default:
+                return text(`unknown envelope kind "${envelope.kind}"\n`, 400);
+        }
+    };
+    // Settle-then-snapshot: when the envelope leaves nothing in flight, its writes are final now (a
+    // background turn instead reports through the idle edge above).
+    const invocations = async (req) => {
+        const response = await handleInvocation(req);
+        if (stateSync && !isBusy())
+            stateSync.save();
+        return response;
+    };
+    return {
+        "POST /invocations": invocations,
+        // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive
+        // (background turns in flight). No time_of_last_update — the platform tracks status changes
+        // itself, and a timestamp advancing every ping would defeat the idle timeout (their docs warn).
+        "GET /ping": () => json({ status: isBusy() ? "HealthyBusy" : "Healthy" }, 200),
+    };
+}
+/** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does
+ *  not have — the adapter maps it to 404 (deploy drift stays visible in the external clock's logs). */
+export class UnknownScheduleError extends Error {
+    constructor(name) {
+        super(`unknown schedule "${name}"`);
+        this.name = "UnknownScheduleError";
+    }
+}

package/dist/channels/busy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
+ * fire-and-forget on this process's event loop (host/node.ts) — so "is this process busy?" is not
+ * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
+ * task-tracker side tasks) report here; a serving surface that must stay alive while background
+ * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.
+ *
+ * Deliberately a counter, not a registry: consumers need only "any work in flight?"; keeping the
+ * module dependency-free lets both channel primitives import it without cycles.
+ */
+/**
+ * Mark one unit of background work as started. Returns its completion callback — idempotent, so a
+ * caller may safely settle it from multiple cleanup paths (finally + catch) without double-counting.
+ */
+export declare function beginWork(): () => void;
+/**
+ * Subscribe to the 0-in-flight edge: the moment the process finishes its last background turn.
+ * Returns an unsubscribe. Used by the AgentCore adapter to push its state snapshot exactly when the
+ * state root has settled and before the platform may reclaim the idle microVM.
+ */
+export declare function onIdle(listener: () => void): () => void;
+/** How many units of background work are currently in flight (0 = idle). */
+export declare function activeWork(): number;

package/dist/channels/busy.js

@@ -0,0 +1,53 @@
+/**
+ * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
+ * fire-and-forget on this process's event loop (host/node.ts) — so "is this process busy?" is not
+ * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
+ * task-tracker side tasks) report here; a serving surface that must stay alive while background
+ * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.
+ *
+ * Deliberately a counter, not a registry: consumers need only "any work in flight?"; keeping the
+ * module dependency-free lets both channel primitives import it without cycles.
+ */
+let inFlight = 0;
+const idleListeners = new Set();
+/**
+ * Mark one unit of background work as started. Returns its completion callback — idempotent, so a
+ * caller may safely settle it from multiple cleanup paths (finally + catch) without double-counting.
+ */
+export function beginWork() {
+    inFlight += 1;
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        inFlight -= 1;
+        if (inFlight > 0)
+            return;
+        for (const listener of idleListeners) {
+            // A listener fault must not corrupt the counter or starve the others (this runs inside a
+            // channel's `finally`): report and carry on.
+            try {
+                listener();
+            }
+            catch (e) {
+                console.error(`[fastagent] idle listener failed: ${String(e)}`);
+            }
+        }
+    };
+}
+/**
+ * Subscribe to the 0-in-flight edge: the moment the process finishes its last background turn.
+ * Returns an unsubscribe. Used by the AgentCore adapter to push its state snapshot exactly when the
+ * state root has settled and before the platform may reclaim the idle microVM.
+ */
+export function onIdle(listener) {
+    idleListeners.add(listener);
+    return () => {
+        idleListeners.delete(listener);
+    };
+}
+/** How many units of background work are currently in flight (0 = idle). */
+export function activeWork() {
+    return inFlight;
+}

package/dist/channels/context-buffer.d.ts

@@ -0,0 +1,35 @@
+/** Per-message bound INSIDE that budget. The fold is a digest of many messages competing for one
+ *  allowance, so the job here is fairness, not fidelity: one rambler must not price out everyone who
+ *  spoke after them. 280 against 4000 keeps at least ~14 messages in a full buffer. A referent — the
+ *  single message the asker points at — is the opposite job and takes REFERENT_MAX_CODE_POINTS. */
+export declare const BUFFER_LINE_MAX_CHARS = 280;
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded
+ *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
+ *  group posting many attachments between summons. Skipped ones must be counted into the prompt
+ *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
+ *  each channel's attachment collector caps against this. */
+export declare const BUFFER_ATTACH_MAX = 3;
+export interface ContextBuffer<E> {
+    /** Record an un-summoned message. Persists BEFORE returning (pre-ACK; see the module header). */
+    push(placeKey: string, entry: E): void;
+    /** Render the fold text and snapshot the consumed entries (see the module header's consume protocol). */
+    peek(placeKey: string): {
+        text: string;
+        consumed: E[];
+    };
+    /** Remove exactly `consumed` (by identity) — call on the turn's `completed` event, when the folded
+     *  discussion provably lives in the durable session. Consumes entries WHOLE, including ones whose
+     *  attachments failed to load or were cap-skipped: their text is in the session (keeping them would
+     *  re-fold duplicate text), and the prompt note said what is missing; re-post an attachment to use
+     *  it. Post-ACK: a failed write is logged, never thrown (it must not abort the turn's delivery). */
+    commit(placeKey: string, consumed: E[]): void;
+}
+export declare function createContextBuffer<E>(options: {
+    path: string;
+    /** Log label, e.g. "[telegram]". */
+    label: string;
+    /** Shape validator for one persisted entry (the IO boundary — see the module header). */
+    isEntry: (value: unknown) => value is E;
+    /** One fold line for an entry — ALSO the eviction cost basis. */
+    line: (entry: E) => string;
+}): ContextBuffer<E>;

package/dist/channels/context-buffer.js

@@ -0,0 +1,103 @@
+/**
+ * Generic durable context buffer — the SHARED mechanics behind each stateful channel's
+ * "un-summoned group discussion" module (telegram/feishu/slack `context-buffer.ts`): recent
+ * un-summoned messages per conversation "place", kept under a char budget and folded into the next
+ * answered turn in that place, so a summoned agent has the discussion it didn't see turn-by-turn.
+ *
+ * Channel-neutral and generic over the entry shape (like ../turn-store.ts): the channel supplies its
+ * entry type, the shape validator (state files are an IO boundary — valid JSON of the WRONG shape
+ * must degrade exactly like a corrupt file: warn + empty, never flow in as trusted data), the
+ * fold-line renderer, and its log label. What stays per channel: the entry type itself, place-key
+ * derivation, and buffered-attachment selection (platform resource shapes are real differences).
+ *
+ * DURABLE, with the consume protocol every channel inherits:
+ *  - `push` persists synchronously BEFORE the transport ACK (an ACKed delivery is not redelivered,
+ *    so ACK-then-persist would be a silent-loss window): a throw becomes the webhook's 500 and the
+ *    platform redelivers once the disk recovers — staged on a copy and rolled back on a failed
+ *    write, so the redelivery does not double-append the entry already in memory.
+ *  - `peek` renders WITHOUT clearing and snapshots exactly which entries it consumed.
+ *  - `commit` removes only that snapshot, by object identity, on the turn's `completed` — so a
+ *    failure or crash before `completed` leaves the discussion intact for the next summon, and a
+ *    message that arrives while the turn runs survives for the next answered turn (a whole-bucket
+ *    delete would lose it).
+ */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+/** Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded
+ *  the OLDEST un-summoned messages are dropped (not a time window: a quiet group keeps its
+ *  sparse-but-relevant lines, a busy burst is capped). The `line` renderer is the eviction cost
+ *  basis: the budget must price what the fold actually renders, or it would systematically overrun. */
+const BUFFER_MAX_CHARS = 4000;
+/** Per-message bound INSIDE that budget. The fold is a digest of many messages competing for one
+ *  allowance, so the job here is fairness, not fidelity: one rambler must not price out everyone who
+ *  spoke after them. 280 against 4000 keeps at least ~14 messages in a full buffer. A referent — the
+ *  single message the asker points at — is the opposite job and takes REFERENT_MAX_CODE_POINTS. */
+export const BUFFER_LINE_MAX_CHARS = 280;
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded
+ *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
+ *  group posting many attachments between summons. Skipped ones must be counted into the prompt
+ *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
+ *  each channel's attachment collector caps against this. */
+export const BUFFER_ATTACH_MAX = 3;
+export function createContextBuffer(options) {
+    const { path, label, isEntry, line } = options;
+    const load = () => {
+        const raw = loadStateFile(path);
+        if (raw === undefined)
+            return new Map();
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.values(raw).every((entries) => Array.isArray(entries) && entries.every(isEntry))) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`${label} unexpected shape in ${path} — starting with an empty context buffer`);
+        return new Map();
+    };
+    const buffers = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
+    return {
+        push(placeKey, entry) {
+            const previous = buffers.get(placeKey);
+            const entries = previous ? [...previous] : [];
+            entries.push(entry);
+            let total = entries.reduce((sum, candidate) => sum + line(candidate).length + 1, 0);
+            while (entries.length > 1 && total > BUFFER_MAX_CHARS) {
+                const dropped = entries.shift();
+                if (dropped)
+                    total -= line(dropped).length + 1;
+            }
+            buffers.set(placeKey, entries);
+            try {
+                persist();
+            }
+            catch (error) {
+                if (previous)
+                    buffers.set(placeKey, previous);
+                else
+                    buffers.delete(placeKey);
+                throw error;
+            }
+        },
+        peek(placeKey) {
+            const entries = buffers.get(placeKey) ?? [];
+            return { text: entries.map(line).join("\n"), consumed: [...entries] };
+        },
+        commit(placeKey, consumed) {
+            const entries = buffers.get(placeKey);
+            if (!entries)
+                return;
+            const remaining = entries.filter((entry) => !consumed.includes(entry));
+            if (remaining.length === 0)
+                buffers.delete(placeKey);
+            else
+                buffers.set(placeKey, remaining);
+            try {
+                persist();
+            }
+            catch (error) {
+                log.error(`${label} context-buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(error)}`);
+            }
+        },
+    };
+}

package/dist/channels/control.d.ts

@@ -0,0 +1,28 @@
+import { type SessionControl, type SessionEvent } from "../session.ts";
+import type { Agent } from "../agent.ts";
+import type { Routes } from "../host/node.ts";
+/** The SSE payload: one control-plane event in its transport envelope. */
+export interface WireEvent {
+    sessionId: string;
+    /** Serving-process incarnation (per `controlRoutes` call). A change means the server restarted:
+     *  live continuity is gone — run the reconnect steps (entries cursor + state). */
+    epoch: string;
+    /** Per-connection monotonic counter. A gap means events were lost in transit on THIS connection. */
+    seq: number;
+    event: SessionEvent;
+}
+export interface ControlRoutesOptions {
+    /** Shared bearer secret, required on every route. Never optional: an unauthenticated
+     *  remote-control endpoint must not be constructible by omission. */
+    token: string;
+    /** The DATA plane over the wire: when provided, `POST /control/invoke` mounts the standard
+     *  invoke handler behind the same bearer token — a remote client (Web panel, desktop app,
+     *  `attach`) can START runs regardless of which channels occupy `/invoke`. Same contract, same
+     *  SSE event stream; disconnecting the response cancels the run (SPEC cancellation). */
+    agent?: Agent;
+}
+/**
+ * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ */
+export declare function controlRoutes(control: SessionControl, options: ControlRoutesOptions): Routes;