@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/service.js

@@ -1,32 +1,12 @@
-/**
- * The product, as one call: an agent directory becomes a live service.
- *
- * That phrase is the promise on the README, and until this existed only the CLI could keep it. The
- * assembly parts live here too — `routesFor`, `mountSessionControl`, `startSchedules` — because a
- * public entry may not reach into `cli/`: that directory decides process-level things (`fail.ts`
- * calls `process.exit`) which a library mounted inside someone's app does not get to decide.
- * Everything else was parts: assemble the agent, discover channels, mount the control plane, start
- * schedules, open long connections, compose a router. An embedder had to know that list and get its
- * order right, and getting it wrong is silent: a plane that 404s while advertising itself, a
- * schedule that never fires.
- *
- * So the assembly lives here, and `dev`/`start` are callers. AgentCore is the one exception, and a
- * substantive one: its channels load lazily after a state-snapshot restore, so it cannot use an
- * assembly that discovers them eagerly (cli/commands/start.ts says so at the branch).
- */
-import { mkdirSync, rmSync } from "node:fs";
-import { writeFileAtomic } from "./atomic-write.js";
-import { join } from "node:path";
-import { classifyBind, clientHost } from "./bind.js";
-import { createControlPlane } from "./channels/control.js";
+import { CONTROL_TOKEN_ENV, createControlPlane } from "./channels/control.js";
 import { createInvokeHandler } from "./channels/http.js";
 import { text } from "./channels/respond.js";
-import { parseRouteKey, pathUnderPrefix } from "./channels/serve.js";
+import { parseRouteKey, pathUnderPrefix, router } from "./channels/serve.js";
 import { loadChannels } from "./channels/discover.js";
 import { loadSchedules } from "./schedule/discover.js";
 import { createScheduler } from "./schedule/scheduler.js";
-import { router } from "./channels/serve.js";
-import { log, reportModuleLoadFailures } from "./log.js";
+import { log } from "./log.js";
+import { reportModuleLoadFailures } from "./loader.js";
 /** Default wait for a channel's `closed` before reporting it stuck. A channel that ignores its
  *  abort signal must not hang a caller's teardown — or, during a failed start, keep the original
  *  error from arriving. The CLI passes a shorter one: its own forced exit must come AFTER this, or
@@ -71,7 +51,7 @@ export async function routesFor(agentDir, agent, stateRoot, control, options = {
         control,
     });
     for (const c of collisions) {
-        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
+        log.warn(`[fastagent] channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
     }
     reportModuleLoadFailures(failures);
     if (failures.length > 0 || collisions.length > 0) {
@@ -114,51 +94,36 @@ export function assertNoControlPlaneCollision(channelRoutes, plane) {
             `rename the channel route or disable sessionControl in fastagent.config`);
     }
 }
-export function mountSessionControl(routes, control, stateRoot, options = {}) {
+export function mountSessionControl(routes, control, options = {}) {
     if (!control)
-        return { routes, mounts: [], announce: () => () => { } };
-    const token = crypto.randomUUID();
+        return { routes, mounts: [] };
+    // WHO OWNS the secret. Per-boot mint is right locally: discovery is `control.json` and its file
+    // permissions, which works because both holders share a filesystem. A deployment removes that
+    // premise — a token minted in the container is replaced every restart and reachable only by shelling
+    // in — so there the deployer mints it and injects it here, like the wake/ingress secrets.
+    // Trimmed on read, like `.env` values already are: a token pasted from a dashboard with a trailing
+    // newline would otherwise become the box's token verbatim, and every caller holding the clean value
+    // gets a bare 401 — the undiagnosable symptom, one character wide.
+    const injected = process.env[CONTROL_TOKEN_ENV]?.trim();
+    // SET BUT EMPTY is the deployed default, not an edge case: the generated Compose topology writes
+    // every secret as `NAME: "${NAME:-}"`, so an operator who skipped this one lands here. Falling back
+    // silently would leave exactly the symptom the injection exists to remove — a token the caller does
+    // not have — with nothing in the log to tell it apart from a deployment that never asked.
+    if (injected === "") {
+        log.warn(`[fastagent] ${CONTROL_TOKEN_ENV} is set but empty — minting a per-boot token instead; callers holding ` +
+            "the deploy-time value will get 401 (set it, or read the minted one from control.json on the box)");
+    }
+    else if (injected !== undefined && injected.length < 16) {
+        // Length is a crude proxy for entropy — sixteen `a`s pass. It is aimed at `changeme`, which this
+        // change makes newly dangerous: the plane went from unusable-in-a-deployment to usable by whoever
+        // holds this string, and the empty case is the only other thing that says anything.
+        log.warn(`[fastagent] ${CONTROL_TOKEN_ENV} is ${injected.length} characters — it is the ONLY thing between ` +
+            "/control/* (steer, stop, rewrite a session) and anyone who can reach the port; use a random value (uuidgen)");
+    }
+    const token = injected || crypto.randomUUID();
     const plane = createControlPlane(control, { token, agent: options.agent });
     assertNoControlPlaneCollision(routes, plane);
-    return {
-        routes,
-        mounts: [plane],
-        control: { token, prefix: plane.prefix },
-        // Writes the discovery file and hands back its removal. It installs NO signal handlers: a
-        // library mounted inside someone's app must not change how that app exits — the CLI wires the
-        // returned cleanup into its own shutdown, an embedder into `close()`.
-        announce: (boundPort) => {
-            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
-            const path = join(stateRoot, "control.json");
-            const url = `http://${clientHost(options.host)}:${boundPort}`;
-            writeFileAtomic(path, `${JSON.stringify({ url, token })}\n`, 0o600);
-            log.info(`[fastagent] session control on /control/* (token in ${path})`);
-            // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths
-            // warn loudly, and the LAN path must not be the silent third way past the local trust story.
-            // A loopback bind closes exactly that reach, so it earns silence.
-            const bind = classifyBind(options.host);
-            if (bind !== "loopback") {
-                log.warn(`[fastagent] the port binds ${bind === "wildcard" ? "all interfaces" : `${options.host} (off this machine)`}: ` +
-                    "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
-                    "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs: design §14)");
-            }
-            if (options.tunnel) {
-                // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC.
-                log.warn("[fastagent] --tunnel exposes /control/* (steer/abort/set_model) at the public tunnel URL, " +
-                    "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs: design §14)");
-            }
-            // Removed on shutdown so a stale file cannot point a client at a dead port: `attach` then
-            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
-            return () => {
-                try {
-                    rmSync(path, { force: true });
-                }
-                catch {
-                    /* the file is advisory — shutdown must not fail on it */
-                }
-            };
-        },
-    };
+    return { routes, mounts: [plane], control: { token, prefix: plane.prefix } };
 }
 /**
  * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
@@ -199,11 +164,7 @@ export async function mountAgentService(opened, options = {}) {
     const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
     const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
     const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { builtinInvoke: true });
-    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
-        agent,
-        ...(options.control?.tunnel !== undefined ? { tunnel: options.control.tunnel } : {}),
-        ...(options.control?.host !== undefined ? { host: options.control.host } : {}),
-    });
+    const withControl = mountSessionControl(routed.routes, sessionControl, { agent });
     // Composed BEFORE anything starts. `router` re-validates what `loadChannels` and the control
     // mount already checked, so on THIS path it should not fail — but "should not" is not an ordering
     // guarantee, and a throw after the scheduler ticks and channels dial would leave both running
@@ -211,7 +172,6 @@ export async function mountAgentService(opened, options = {}) {
     const handler = router(withControl.routes, withControl.mounts);
     const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule);
     const abort = new AbortController();
-    let unannounce;
     // A connection that drops while others are still dialling must not be undone by their later
     // readiness: the service is missing a declared channel from that moment on, whatever else arrives.
     let dropped = false;
@@ -237,7 +197,6 @@ export async function mountAgentService(opened, options = {}) {
             abort.abort();
             scheduled.stop();
             options.signal?.removeEventListener("abort", onAbort);
-            unannounce?.(); // a stale discovery file would point a client at a dead port
             // A failure to stop is the caller's to know about — swallowing it would let `close()` report
             // success over a channel still holding on. Bounded, because a channel that ignores its abort
             // signal must not hang the teardown either.
@@ -346,9 +305,6 @@ export async function mountAgentService(opened, options = {}) {
         schedules: scheduled.schedules,
         ready,
         ...(withControl.control ? { control: withControl.control } : {}),
-        announce: (boundPort) => {
-            unannounce = withControl.announce(boundPort);
-        },
         close,
     };
 }

package/dist/session-remote.d.ts

@@ -1,9 +1,9 @@
 /**
- * The remote `SessionControl` — the client half of the Phase 3 transport (design §13). Engine- and
- * server-neutral: speaks only the wire protocol `createControlPlane` serves (HTTP JSON + SSE with the
- * {sessionId, epoch, seq, event} envelope) and re-exposes the SAME `SessionControl` interface, so
- * local and remote consumers are isomorphic — client code does not change when the agent moves out
- * of process.
+ * The remote `SessionControl` — the client half of the HTTP + SSE transport
+ * (docs/design/session-control.md §13). Engine- and server-neutral: speaks only the wire protocol
+ * `createControlPlane` serves (HTTP JSON + SSE with the {sessionId, epoch, seq, event} envelope) and
+ * re-exposes the SAME `SessionControl` interface, so local and remote consumers are isomorphic —
+ * client code does not change when the agent moves out of process.
  *
  * Envelope consumption is internal: a seq gap (loss in transit on this connection) — and any
  * mid-stream transport failure, a server restart included (its connections drop) — THROWS from
@@ -15,13 +15,18 @@
  * visible as a thrown iteration error, a failed request as a rejected promise.
  */
 import type { Agent } from "./agent.ts";
-import type { SessionControl } from "./session.ts";
+import { type SessionControl } from "./session.ts";
 /** A control request the server answered with a non-2xx status. Carries the STRUCTURED status so a
  *  consumer distinguishing auth failure (401 — stale token, unrecoverable) from transient transport
  *  trouble branches on `status`, never on message prose. */
 export declare class ControlRequestError extends Error {
     readonly status: number;
-    constructor(status: number, body: string);
+    /** The plane's own error code, when the reply carried one (`sessions()` is the only read that
+     *  does today — design §13). Absent for a plain-text rejection (401) or a proxy's page: a caller
+     *  distinguishing "this deployment cannot list sessions" from "the endpoint is unreachable" reads
+     *  THIS, not the status. */
+    readonly code?: string;
+    constructor(status: number, body: string, code?: string);
 }
 /** Connection parameters shared by BOTH remote planes (`connectSessionControl` and
  *  `connectAgent`) — plane-neutral on purpose: one endpoint, one token, two contracts. */

package/dist/session-remote.js

@@ -1,5 +1,6 @@
-import { SSE_HEARTBEAT_MS } from "./channels/http.js";
+import { SSE_HEARTBEAT_MS } from "./channels/sse.js";
 import { abortFirstIterator } from "./collect.js";
+import { isAddressableSession, } from "./session.js";
 /** Dead-connection watchdog for SSE reads: the server heartbeats every SSE_HEARTBEAT_MS, so a
  *  PENDING READ seeing no bytes (of ANY kind — comments included) for this many missed beats
  *  means the connection is a black hole. The stream is aborted and surfaced as an error, so a
@@ -31,11 +32,34 @@ function idleWatchdog(abort) {
  *  trouble branches on `status`, never on message prose. */
 export class ControlRequestError extends Error {
     status;
-    constructor(status, body) {
+    /** The plane's own error code, when the reply carried one (`sessions()` is the only read that
+     *  does today — design §13). Absent for a plain-text rejection (401) or a proxy's page: a caller
+     *  distinguishing "this deployment cannot list sessions" from "the endpoint is unreachable" reads
+     *  THIS, not the status. */
+    code;
+    constructor(status, body, code) {
         super(`control request failed: ${status} ${body}`);
         this.status = status;
+        if (code !== undefined)
+            this.code = code;
     }
 }
+/** A non-2xx reply as an error, carrying the plane's code when the reply declared one. */
+async function controlError(res) {
+    const body = await res.text();
+    if (!res.headers.get("content-type")?.includes("application/json"))
+        return new ControlRequestError(res.status, body);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        // The reply declared JSON and is not — a protocol fault worth seeing, but not worth losing the
+        // status over: both travel in one error rather than a bare SyntaxError from a rejection path.
+        return new ControlRequestError(res.status, `${body} (declared application/json but did not parse)`);
+    }
+    return new ControlRequestError(res.status, body, typeof parsed?.code === "string" ? parsed.code : undefined);
+}
 /**
  * Connect and return a remote `SessionControl`. Async because `capabilities()` is synchronous in
  * the contract: the static declaration is fetched ONCE here and served from memory — which also
@@ -59,10 +83,110 @@ export async function connectSessionControl(options) {
     const get = async (path, timeoutMs = REQUEST_TIMEOUT_MS) => {
         const res = await fetchFn(`${base}${path}`, { headers, signal: AbortSignal.timeout(timeoutMs) });
         if (!res.ok)
-            throw new ControlRequestError(res.status, await res.text());
+            throw await controlError(res);
         return (await res.json());
     };
     const capabilities = await get("/control/capabilities");
+    const eventsOf = (session) => {
+        // Each ITERATION opens its own connection (gen/abort created inside asyncIterator), matching
+        // the local hub's "every iteration is a fresh subscription" — a shared single-use generator
+        // would make the second for-await silently empty, breaking local/remote isomorphism.
+        // The abort controller lives OUTSIDE the generator: a consumer's `return()`/`break` while the
+        // generator is suspended on a quiet SSE read must abort the fetch FIRST — an async generator's
+        // own finally only runs after the pending await settles, which a silent stream never does.
+        const openStream = (abort) => (async function* iterate() {
+            // Armed BEFORE the fetch: the connect phase (headers never arriving from a black-holed
+            // endpoint) is otherwise a window no timeout covers — the same watchdog terminates it,
+            // with headers-arrival counting as the first sign of life.
+            const watchdog = idleWatchdog(abort);
+            watchdog.arm(); // the connect await is a pending read
+            try {
+                const res = await fetchFn(`${base}/control/sessions/${encodeURIComponent(session)}/events`, {
+                    headers,
+                    signal: abort.signal,
+                });
+                watchdog.disarm(); // headers arrived
+                if (!res.ok) {
+                    // The error body is a pending read too — a half-dead tunnel serving 4xx headers then
+                    // black-holing the body must not hang the round outside every budget. Re-armed: the
+                    // watchdog aborts the read and the round fails with the dead-connection diagnosis.
+                    watchdog.arm();
+                    throw new ControlRequestError(res.status, await res.text());
+                }
+                if (!res.body)
+                    throw new Error("control events: response has no body");
+                let nextSeq = 0;
+                for await (const data of sseData(res.body, watchdog)) {
+                    // Parse discipline, same as the other two wire planes (dispatch parses, invoke
+                    // classifies drift): a non-JSON or non-envelope payload is PROTOCOL MISMATCH —
+                    // thrown, so a consumer's failure budget applies — never misdiagnosed as an
+                    // in-transit gap whose remedy (reconnect) can never fix it.
+                    let wire;
+                    try {
+                        // The ONE envelope type (control.ts's WireEvent) — an inline shape would let the
+                        // envelope drift server-side while this cast silently kept the old fields.
+                        wire = JSON.parse(data);
+                    }
+                    catch (parseError) {
+                        throw new Error(`control events: non-JSON data on the stream (${String(parseError)}) — protocol mismatch?`);
+                    }
+                    if (typeof wire !== "object" ||
+                        wire === null ||
+                        typeof wire.seq !== "number" ||
+                        typeof wire.event !== "object" ||
+                        wire.event === null ||
+                        typeof wire.event.type !== "string") {
+                        throw new Error("control events: malformed envelope — the endpoint does not speak this protocol version");
+                    }
+                    // Envelope checks — consumed HERE. (epoch is not compared: it cannot change within
+                    // one connection — see the header note.) A gap THROWS like a protocol mismatch: the
+                    // consumer's failure path (budget, its own io) owns the diagnostic — a library-level
+                    // log would bypass consumer output discipline, and a silent clean end would be
+                    // indistinguishable from the server closing normally.
+                    if (wire.seq !== nextSeq) {
+                        throw new Error(`control events: sequence gap (expected ${nextSeq}, got ${wire.seq}) — events were lost in transit; resync via entries()`);
+                    }
+                    nextSeq = wire.seq + 1;
+                    yield wire.event;
+                }
+            }
+            catch (error) {
+                if (abort.signal.aborted) {
+                    if (watchdog.stale()) {
+                        throw new Error(`control events: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection; resync via entries()`);
+                    }
+                    return; // the consumer walked away — clean end, not an error
+                }
+                throw error;
+            }
+            finally {
+                watchdog.stop();
+                abort.abort();
+            }
+        })();
+        return {
+            [Symbol.asyncIterator]() {
+                const abort = new AbortController();
+                // Abort-first cancellation (see abortFirstIterator): aborting the connection unblocks a
+                // generator suspended on a quiet stream read.
+                return abortFirstIterator(openStream(abort), () => abort.abort());
+            },
+        };
+    };
+    /** A write that answers a `SessionResult`: the result rides HTTP 200 either way (`ok: false` is a
+     *  protocol answer, not a transport failure), so a non-2xx here is a REAL transport/auth fault. */
+    const write = async (path, method, body) => {
+        const res = await fetchFn(`${base}${path}`, {
+            method,
+            headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(PAYLOAD_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw await controlError(res);
+        return (await res.json());
+    };
+    const id = (session) => encodeURIComponent(session);
     return {
         capabilities: () => capabilities,
         // NOT prefetched like capabilities: a live definition can grow a skill between calls, so the
@@ -82,98 +206,50 @@ export async function connectSessionControl(options) {
                 throw error;
             }
         },
-        state: (session) => get(`/control/state?session=${encodeURIComponent(session)}`),
-        entries: (session, opts) => get(`/control/entries?session=${encodeURIComponent(session)}${opts?.since !== undefined ? `&since=${encodeURIComponent(opts.since)}` : ""}`, PAYLOAD_TIMEOUT_MS),
-        async dispatch(session, command) {
-            const res = await fetchFn(`${base}/control/dispatch`, {
-                method: "POST",
-                headers: { ...headers, "content-type": "application/json" },
-                body: JSON.stringify({ session, command }),
-                signal: AbortSignal.timeout(PAYLOAD_TIMEOUT_MS),
-            });
-            if (!res.ok)
-                throw new ControlRequestError(res.status, await res.text());
-            return (await res.json());
-        },
-        events(session) {
-            // Each ITERATION opens its own connection (gen/abort created inside asyncIterator), matching
-            // the local hub's "every iteration is a fresh subscription" — a shared single-use generator
-            // would make the second for-await silently empty, breaking local/remote isomorphism.
-            // The abort controller lives OUTSIDE the generator: a consumer's `return()`/`break` while the
-            // generator is suspended on a quiet SSE read must abort the fetch FIRST — an async generator's
-            // own finally only runs after the pending await settles, which a silent stream never does.
-            const openStream = (abort) => (async function* iterate() {
-                // Armed BEFORE the fetch: the connect phase (headers never arriving from a black-holed
-                // endpoint) is otherwise a window no timeout covers — the same watchdog terminates it,
-                // with headers-arrival counting as the first sign of life.
-                const watchdog = idleWatchdog(abort);
-                watchdog.arm(); // the connect await is a pending read
-                try {
-                    const res = await fetchFn(`${base}/control/events?session=${encodeURIComponent(session)}`, {
-                        headers,
-                        signal: abort.signal,
-                    });
-                    watchdog.disarm(); // headers arrived
-                    if (!res.ok) {
-                        // The error body is a pending read too — a half-dead tunnel serving 4xx headers then
-                        // black-holing the body must not hang the round outside every budget. Re-armed: the
-                        // watchdog aborts the read and the round fails with the dead-connection diagnosis.
-                        watchdog.arm();
-                        throw new ControlRequestError(res.status, await res.text());
-                    }
-                    if (!res.body)
-                        throw new Error("control events: response has no body");
-                    let nextSeq = 0;
-                    for await (const data of sseData(res.body, watchdog)) {
-                        // Parse discipline, same as the other two wire planes (dispatch parses, invoke
-                        // classifies drift): a non-JSON or non-envelope payload is PROTOCOL MISMATCH —
-                        // thrown, so a consumer's failure budget applies — never misdiagnosed as an
-                        // in-transit gap whose remedy (reconnect) can never fix it.
-                        let wire;
-                        try {
-                            // The ONE envelope type (control.ts's WireEvent) — an inline shape would let the
-                            // envelope drift server-side while this cast silently kept the old fields.
-                            wire = JSON.parse(data);
-                        }
-                        catch (parseError) {
-                            throw new Error(`control events: non-JSON data on the stream (${String(parseError)}) — protocol mismatch?`);
-                        }
-                        if (typeof wire.seq !== "number" || typeof wire.event !== "object" || wire.event === null) {
-                            throw new Error("control events: malformed envelope — the endpoint does not speak this protocol version");
-                        }
-                        // Envelope checks — consumed HERE. (epoch is not compared: it cannot change within
-                        // one connection — see the header note.) A gap THROWS like a protocol mismatch: the
-                        // consumer's failure path (budget, its own io) owns the diagnostic — a library-level
-                        // log would bypass consumer output discipline, and a silent clean end would be
-                        // indistinguishable from the server closing normally.
-                        if (wire.seq !== nextSeq) {
-                            throw new Error(`control events: sequence gap (expected ${nextSeq}, got ${wire.seq}) — events were lost in transit; resync via entries()`);
-                        }
-                        nextSeq = wire.seq + 1;
-                        yield wire.event;
-                    }
+        sessions: {
+            // Rejects when the deployment cannot enumerate its store — the coded 503 arrives as a
+            // ControlRequestError carrying `sessions_unavailable`, so a client can tell it from an
+            // unreachable endpoint instead of retrying forever.
+            list: () => get("/control/sessions", PAYLOAD_TIMEOUT_MS),
+            // PUT: the fork is idempotent, and so is the request that carries it. `into` becomes a path
+            // segment exactly like `get`'s id, so it is refused on the same rule — without this the local
+            // plane answers `invalid_command` while the wire answers 404 from a URL that normalised away.
+            // ASYNC, so the guard REJECTS rather than throwing out of a method typed `Promise`: a caller
+            // that wrote `.catch(…)` — or handed this to `Promise.all` — must not be surprised by a
+            // synchronous throw. (`get` may throw: it is synchronous by signature.)
+            fork: async ({ from, at, into }) => {
+                if (!isAddressableSession(into)) {
+                    throw new Error(`session id ${JSON.stringify(into)} cannot travel as a URL path segment — this transport cannot address it`);
                 }
-                catch (error) {
-                    if (abort.signal.aborted) {
-                        if (watchdog.stale()) {
-                            throw new Error(`control events: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection; resync via entries()`);
-                        }
-                        return; // the consumer walked away — clean end, not an error
-                    }
-                    throw error;
+                return write(`/control/sessions/${id(into)}`, "PUT", { from, at });
+            },
+            // The local hub's handle is a pure binding; so is this one — an id and the transport above it.
+            // Nothing is FETCHED here, which is what keeps the two isomorphic. What is checked is the one
+            // thing the wire cannot express: `.` and `..` survive `encodeURIComponent` and are then
+            // normalised away by URL parsing, so every call on such a handle would arrive at a DIFFERENT
+            // route — `.` reads as the collection (200 JSON, which the SSE reader ends as a silently empty
+            // stream) and `..` as a 404 the local plane answers normally. Refused at the binding, where a
+            // caller can see it, rather than once per call in a place it looks like a server answer.
+            get: (session) => {
+                if (!isAddressableSession(session)) {
+                    throw new Error(`session id ${JSON.stringify(session)} cannot travel as a URL path segment — this transport cannot address it`);
                 }
-                finally {
-                    watchdog.stop();
-                }
-            })();
-            return {
-                [Symbol.asyncIterator]() {
-                    const abort = new AbortController();
-                    // Abort-first cancellation (see abortFirstIterator): aborting the connection unblocks a
-                    // generator suspended on a quiet stream read.
-                    return abortFirstIterator(openStream(abort), () => abort.abort());
-                },
-            };
+                return {
+                    id: session,
+                    state: () => get(`/control/sessions/${id(session)}`),
+                    entries: (options) => get(`/control/sessions/${id(session)}/entries${options?.since !== undefined ? `?since=${encodeURIComponent(options.since)}` : ""}`, PAYLOAD_TIMEOUT_MS),
+                    events: () => eventsOf(session),
+                    update: (patch) => write(`/control/sessions/${id(session)}`, "PATCH", patch),
+                    steer: (prompt) => write(`/control/sessions/${id(session)}/actions`, "POST", { type: "steer", prompt }),
+                    followUp: (prompt) => write(`/control/sessions/${id(session)}/actions`, "POST", { type: "follow_up", prompt }),
+                    abort: () => write(`/control/sessions/${id(session)}/actions`, "POST", { type: "abort" }),
+                    compact: (options) => write(`/control/sessions/${id(session)}/actions`, "POST", {
+                        type: "compact",
+                        ...(options?.instructions !== undefined ? { instructions: options.instructions } : {}),
+                    }),
+                    delete: () => write(`/control/sessions/${id(session)}`, "DELETE"),
+                };
+            },
         },
     };
 }
@@ -218,9 +294,7 @@ export function connectAgent(options) {
                     };
                     return;
                 }
-                // Exactly-one-terminal discipline across the wire: a drop AFTER the server's terminal
-                // must not append a second one (catch included), and a stream that ends WITHOUT one
-                // (server died mid-run) must be closed with a failed — never a terminal-less end.
+                // A terminal closes the stream. Cleanup errors must not append a second terminal.
                 let terminalSeen = false;
                 // Armed BEFORE the fetch — the run's driver must not hang on a black-holed connect
                 // either (the connect await is a pending read; headers arriving disarm it).
@@ -258,38 +332,30 @@ export function connectAgent(options) {
                             event = JSON.parse(data);
                         }
                         catch (parseError) {
-                            // Protocol drift (version skew, non-SSE middlebox), NOT transport trouble:
-                            // re-sending the same prompt cannot fix an unparseable stream — retryable: false.
-                            // (Guarded by terminalSeen: garbage AFTER the terminal must not add a second one.)
-                            if (!terminalSeen) {
-                                yield {
-                                    type: "failed",
-                                    details: `remote invoke: unparseable event on the stream (${String(parseError)})`,
-                                    retryable: false,
-                                };
-                            }
+                            yield {
+                                type: "failed",
+                                details: `remote invoke: unparseable event on the stream (${String(parseError)})`,
+                                retryable: false,
+                            };
                             return;
                         }
                         // Shape check, same discipline as the events plane: `data: null` / `data: 42` is
                         // valid JSON but protocol drift — it must not TypeError into the catch below and be
                         // misclassified as retryable network trouble.
                         if (typeof event !== "object" || event === null || typeof event.type !== "string") {
-                            if (!terminalSeen) {
-                                yield {
-                                    type: "failed",
-                                    details: "remote invoke: non-event data on the stream — protocol mismatch?",
-                                    retryable: false,
-                                };
-                            }
+                            yield {
+                                type: "failed",
+                                details: "remote invoke: non-event data on the stream — protocol mismatch?",
+                                retryable: false,
+                            };
                             return;
                         }
-                        if (event.type === "completed" || event.type === "failed")
-                            terminalSeen = true;
+                        terminalSeen = event.type === "completed" || event.type === "failed";
                         yield event;
+                        if (terminalSeen)
+                            return;
                     }
-                    if (!terminalSeen) {
-                        yield { type: "failed", details: "remote invoke: stream ended without a terminal", retryable: true };
-                    }
+                    yield { type: "failed", details: "remote invoke: stream ended without a terminal", retryable: true };
                 }
                 catch (error) {
                     if (abort.signal.aborted) {
@@ -307,6 +373,7 @@ export function connectAgent(options) {
                 }
                 finally {
                     watchdog.stop();
+                    abort.abort();
                 }
             })();
             // ONE stream per invoke, like a local async generator (which is its own iterator): a second