@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/service.js

@@ -18,14 +18,13 @@ 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";
 /** 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
@@ -117,7 +116,30 @@ export function assertNoControlPlaneCollision(channelRoutes, plane) {
 export function mountSessionControl(routes, control, stateRoot, options = {}) {
     if (!control)
         return { routes, mounts: [], announce: () => () => { } };
-    const token = crypto.randomUUID();
+    // 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 {
@@ -144,7 +166,7 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
             }
             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, " +
+                log.warn("[fastagent] --tunnel exposes /control/* (steer, stop, rewrite or delete a session) 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

package/dist/session-remote.d.ts

@@ -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 { 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,104 @@ 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.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;
+                }
+            }
+            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();
+            }
+        })();
+        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 +200,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;
-                }
-                finally {
-                    watchdog.stop();
+                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`);
                 }
-            })();
-            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"),
+                };
+            },
         },
     };
 }