@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/atomic-write.d.ts

@@ -1,12 +1,16 @@
 /**
  * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
  *
- * The temp name is fixed (`<path>.tmp`). That is safe here because no two processes write one state
- * root: a deployment runs one container, and `dev`'s supervisor respawns its worker only after the
- * old one has EXITED (dev-supervisor.ts) — and these writes are synchronous, so an exited process
- * has none in flight. The fixed name is also the seam several channel tests use to inject a write
- * failure, by occupying that path with a directory. A unique name would trade that seam for a race
- * this codebase does not have; revisit it if a second writer ever becomes real.
+ * The temp name is fixed (`<path>.tmp`). It holds wherever one process writes one state root: a
+ * deployment runs one container, `dev`'s supervisor respawns its worker only after the old one has
+ * EXITED (dev-supervisor.ts), and these writes are synchronous, so an exited process has none in
+ * flight. Slack's onboarding state is the one file with two writers — `add slack`, and the
+ * config-token rotation inside `--tunnel` webhook registration — so a second terminal running
+ * `add slack --replace-config` can overlap a live `dev --tunnel`. Kept fixed anyway: that window is
+ * a single write at tunnel startup, its repair is the `add slack --replace-config` the registration
+ * failure already prints, and the fixed name is the seam several channel tests use to inject a write
+ * failure by occupying that path with a directory. Revisit for a writer that is neither rare nor
+ * self-repairing.
  *
  * `mode` is applied to the temp first, so the content is never briefly world-readable.
  *
@@ -16,4 +20,4 @@
  * It runs on the temp, before the rename — the final path is then never observable with the wrong
  * permissions, which a chmod after the rename cannot promise.
  */
-export declare function writeFileAtomic(path: string, data: string, mode?: number): void;
+export declare function writeFileAtomic(path: string, data: string | Buffer, mode?: number): void;

package/dist/atomic-write.js

@@ -1,22 +1,27 @@
 /**
- * One spelling of "a reader sees the whole file or none of it" for SYNCHRONOUS writes, after four
- * copies of it drifted apart: two identical, two with different temp names and different permission
- * handling.
+ * One spelling of "a reader sees the whole file or none of it", after five copies of it drifted
+ * apart: two identical, three with different temp names and different permission handling.
  *
- * Slack's onboarding state stays on its own async path — this is deliberately not an async API, and
- * converting that caller is a separate question from de-duplicating these four.
+ * Synchronous, and there is no async sibling: every caller either sits on a path where a KB-sized
+ * write must complete BEFORE a transport ACK (channel state — an ACKed delivery is not redelivered)
+ * or on a CLI/startup path where the cost is not observable. An async spelling would buy one of them
+ * nothing and cost this module a second set of rules to keep true.
  */
 import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 /**
  * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
  *
- * The temp name is fixed (`<path>.tmp`). That is safe here because no two processes write one state
- * root: a deployment runs one container, and `dev`'s supervisor respawns its worker only after the
- * old one has EXITED (dev-supervisor.ts) — and these writes are synchronous, so an exited process
- * has none in flight. The fixed name is also the seam several channel tests use to inject a write
- * failure, by occupying that path with a directory. A unique name would trade that seam for a race
- * this codebase does not have; revisit it if a second writer ever becomes real.
+ * The temp name is fixed (`<path>.tmp`). It holds wherever one process writes one state root: a
+ * deployment runs one container, `dev`'s supervisor respawns its worker only after the old one has
+ * EXITED (dev-supervisor.ts), and these writes are synchronous, so an exited process has none in
+ * flight. Slack's onboarding state is the one file with two writers — `add slack`, and the
+ * config-token rotation inside `--tunnel` webhook registration — so a second terminal running
+ * `add slack --replace-config` can overlap a live `dev --tunnel`. Kept fixed anyway: that window is
+ * a single write at tunnel startup, its repair is the `add slack --replace-config` the registration
+ * failure already prints, and the fixed name is the seam several channel tests use to inject a write
+ * failure by occupying that path with a directory. Revisit for a writer that is neither rare nor
+ * self-repairing.
  *
  * `mode` is applied to the temp first, so the content is never briefly world-readable.
  *

package/dist/channels/agentcore-limits.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The HOST's body ceilings, and the one place they are computed.
+ *
+ * Lambda Function URLs cap a request at 6 MB, so the forwarder cannot deliver more than that no
+ * matter what the adapter accepts; the body arrives base64-encoded (×4/3) inside a JSON envelope, so
+ * the ORIGINAL body ceiling is smaller still. This is a real capability difference from a resident
+ * host — the GitHub channel's own contract is 25 MiB — which is why `deploy agentcore` states it at
+ * plan time rather than letting an oversized payload surface as an opaque 502.
+ */
 /**
  * Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion.
  * Enforced by both the public forwarder and the runtime adapter.

package/dist/channels/agentcore-limits.js

@@ -1,3 +1,12 @@
+/**
+ * The HOST's body ceilings, and the one place they are computed.
+ *
+ * Lambda Function URLs cap a request at 6 MB, so the forwarder cannot deliver more than that no
+ * matter what the adapter accepts; the body arrives base64-encoded (×4/3) inside a JSON envelope, so
+ * the ORIGINAL body ceiling is smaller still. This is a real capability difference from a resident
+ * host — the GitHub channel's own contract is 25 MiB — which is why `deploy agentcore` states it at
+ * plan time rather than letting an oversized payload surface as an opaque 502.
+ */
 /** AWS Lambda Function URLs accept request payloads up to 6 MB. */
 const FUNCTION_URL_REQUEST_LIMIT = 6 * 1000 * 1000;
 /**

package/dist/channels/agentcore-service.d.ts

@@ -18,7 +18,7 @@ import type { Agent } from "../agent.ts";
 import type { Routes } from "../channel.ts";
 import type { LoadedSchedule } from "../schedule/schedule.ts";
 import { type AgentService, type MountableAgent } from "../service.ts";
-import { type RouteSurface } from "./agentcore.ts";
+import { type AgentcoreAdapterOptions } from "./agentcore.ts";
 export interface MountAgentcoreServiceOptions {
     /** Wrap the opened agent before anything binds to it (the CLI's turn trace). */
     wrapAgent?: (agent: Agent) => Agent;
@@ -34,21 +34,22 @@ export interface MountAgentcoreServiceOptions {
 export declare function isAgentcoreRuntime(): boolean;
 export declare function mountAgentcoreService(opened: MountableAgent, options?: MountAgentcoreServiceOptions): Promise<AgentService>;
 /**
- * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
- * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
- * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
- * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
- * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) — the deployed container's
+ * ONLY reachable surface (channels/agentcore.ts). Wired by `start` when `FASTAGENT_AGENTCORE=1` (set
+ * by the generated deploy artifacts, never by hand).
+ *
+ * The adapter IS the surface: the agent's channels live in a table INSIDE the envelope dispatch, a
+ * separate namespace from these two paths, so a channel route named `/invocations` is reached
+ * through the Function URL as itself and cannot shadow anything.
  */
-export declare function mountAgentcore(routes: Routes, options: {
+export declare function mountAgentcore(options: {
     agent: Agent;
     stateRoot: string;
     schedules: readonly LoadedSchedule[];
     onStateReady?: () => void;
     /** Cancels the adapter's process-global registrations on close. */
     signal?: AbortSignal;
-    /** The serving path's LAZY channel surface: constructed by the adapter on the first envelope
-     *  AFTER the state-snapshot restore, never at boot (channels/agentcore.ts). When absent,
-     *  `routes` is the dispatch target — for wirings whose state root is already authoritative. */
-    lazyChannels?: () => Promise<RouteSurface>;
+    /** The channel surface, constructed on the first envelope AFTER the state-snapshot restore — never
+     *  at boot, where the mount is pre-restore (channels/agentcore.ts). */
+    channels: AgentcoreAdapterOptions["channels"];
 }): Routes;

package/dist/channels/agentcore-service.js

@@ -4,7 +4,7 @@ import { assertNoControlPlaneCollision, mountSessionControl, routesFor, startSch
 import { UnknownScheduleError, agentcoreRoutes } from "./agentcore.js";
 import { createStateSync } from "./agentcore-state.js";
 import { activeWork } from "./busy.js";
-import { routeKeysConflict, router } from "./serve.js";
+import { router } from "./serve.js";
 /** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
 export function isAgentcoreRuntime() {
     return process.env.FASTAGENT_AGENTCORE === "1";
@@ -32,13 +32,13 @@ export async function mountAgentcoreService(opened, options = {}) {
     };
     // The adapter registers process-global listeners; this is what takes them down on close.
     const closed = new AbortController();
-    const adapterRoutes = mountAgentcore({}, {
+    const adapterRoutes = mountAgentcore({
         signal: closed.signal,
         agent,
         stateRoot,
         schedules: scheduled.schedules,
         onStateReady: options.onStateReady,
-        lazyChannels,
+        channels: lazyChannels,
     });
     const handler = router(adapterRoutes, withControl.mounts);
     log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
@@ -70,16 +70,18 @@ export async function mountAgentcoreService(opened, options = {}) {
     };
 }
 /**
- * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
- * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
- * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
- * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
- * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
+ * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) — the deployed container's
+ * ONLY reachable surface (channels/agentcore.ts). Wired by `start` when `FASTAGENT_AGENTCORE=1` (set
+ * by the generated deploy artifacts, never by hand).
+ *
+ * The adapter IS the surface: the agent's channels live in a table INSIDE the envelope dispatch, a
+ * separate namespace from these two paths, so a channel route named `/invocations` is reached
+ * through the Function URL as itself and cannot shadow anything.
  */
-export function mountAgentcore(routes, options) {
-    const { agent, stateRoot, schedules, onStateReady, lazyChannels, signal } = options;
-    const mounted = agentcoreRoutes({
-        routes: lazyChannels ?? { routes },
+export function mountAgentcore(options) {
+    const { agent, stateRoot, schedules, onStateReady, channels, signal } = options;
+    return agentcoreRoutes({
+        channels,
         agent,
         stateRoot,
         isBusy: () => activeWork() > 0,
@@ -102,10 +104,4 @@ export function mountAgentcore(routes, options) {
                 return fireScheduleOnce({ agent, stateRoot, schedule, slot });
             },
     });
-    const collisions = Object.keys(routes).filter((key) => Object.keys(mounted).some((adapterKey) => routeKeysConflict(key, adapterKey)));
-    if (collisions.length > 0) {
-        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the AgentCore adapter ` +
-            `(/invocations, /ping) — rename the channel route`);
-    }
-    return { ...routes, ...mounted };
 }

package/dist/channels/agentcore.d.ts

@@ -3,14 +3,6 @@ import type { StateSync, StateUrls } from "./agentcore-state.ts";
 import type { Routes } from "../channel.ts";
 import { type PrefixMount } from "../channels/serve.ts";
 import type { ScheduleFireOutcome } from "../schedule/scheduler.ts";
-/**
- * The HOST's webhook body limit, and the one place it is computed. Lambda Function URLs cap a request
- * at 6 MB, so the forwarder cannot deliver more than that no matter what the adapter accepts; the
- * body arrives base64-encoded (×4/3) inside a JSON envelope, so the ORIGINAL body ceiling is smaller
- * still. This is a real capability difference from a resident host — the GitHub channel's own
- * contract is 25 MiB — so `deploy agentcore` says so at plan time rather than letting an oversized
- * payload surface as an opaque 502.
- */
 /** What the forwarder Lambda / EventBridge deliver in the `/invocations` payload. Every kind may
  *  carry `wake` — the forwarder's self-resolved public URL, which the adapter persists so the wake
  *  ALARM sink (schedule/wake-alarm.ts) can call back without the URL being baked anywhere. */
@@ -79,13 +71,14 @@ export interface RouteSurface {
     mounts?: readonly PrefixMount[];
 }
 export interface AgentcoreAdapterOptions {
-    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health).
-     *  The serving path passes a LAZY factory: channel construction loads channel state and replays
-     *  durable turn intent, so on AgentCore it must not run until the state root is authoritative —
-     *  which happens at the first envelope's `stateSync.ready()` (the restore URLs only an envelope
-     *  carries), never at boot, where the mount is pre-restore (empty after every version update).
-     *  An eager `Routes` value remains supported for wirings whose state root is already durable. */
-    routes: RouteSurface | (() => Promise<RouteSurface> | RouteSurface);
+    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health),
+     *  built LAZILY: channel construction loads channel state and replays durable turn intent, so on
+     *  AgentCore it must not run until the state root is authoritative — which happens at the first
+     *  envelope's `stateSync.ready()` (the restore URLs only an envelope carries), never at boot, where
+     *  the mount is pre-restore (empty after every version update). A factory, not a value: there is no
+     *  moment during construction at which the right answer is knowable. May answer synchronously — the
+     *  resolution chain normalizes it either way. */
+    channels: () => Promise<RouteSurface> | RouteSurface;
     agent: Agent;
     /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
     stateRoot: string;
@@ -109,10 +102,9 @@ export interface AgentcoreAdapterOptions {
     onStateReady?: () => void;
 }
 /**
- * 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.
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }` — the whole of what the
+ * platform routes into the container. The agent's own channels are not beside these: they are a table
+ * inside the envelope dispatch below, reached only by unwrapping a forwarder envelope.
  */
 export declare function agentcoreRoutes(options: AgentcoreAdapterOptions): Routes;
 /** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does

package/dist/channels/agentcore.js

@@ -48,14 +48,13 @@ function secretMatches(actual, 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.
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }` — the whole of what the
+ * platform routes into the container. The agent's own channels are not beside these: they are a table
+ * inside the envelope dispatch below, reached only by unwrapping a forwarder envelope.
  */
 export function agentcoreRoutes(options) {
-    const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
-    // Lazy channel construction (see AgentcoreAdapterOptions.routes) — resolved ONCE per process, on
+    const { channels, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
+    // Lazy channel construction (see AgentcoreAdapterOptions.channels) — resolved ONCE per process, on
     // the first trusted envelope after the state root is authoritative, and the outcome is cached
     // EITHER WAY. Success: the same resident channels a direct host keeps. Failure too: construction
     // is an ACTIVATION with side effects — loadChannels builds every healthy channel (starting its
@@ -71,7 +70,7 @@ export function agentcoreRoutes(options) {
             // The factory runs INSIDE the chain: a synchronous throw must land in the cached rejection,
             // not escape before `dispatchP` is assigned (which would silently re-run the activation).
             dispatchP = Promise.resolve()
-                .then(() => (typeof routes === "function" ? routes() : routes))
+                .then(channels)
                 .then((surface) => router(surface.routes, surface.mounts));
             dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
         }
@@ -301,6 +300,14 @@ export function agentcoreRoutes(options) {
     };
     // 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).
+    //
+    // A public `invoke` is the one kind this MISSES, measurably: it answers with an unconsumed SSE
+    // stream, so the turn runs after this line and its records wait for the next envelope's snapshot.
+    // Counting it as in-flight work would close that and cost more than it buys — the stream drains at
+    // the CLIENT's pace, so one parked reader pins /ping at HealthyBusy and defeats the idle reclaim,
+    // which is the quota-exhaustion failure the ping contract below warns about. The kinds that carry
+    // conversations (webhook, schedule-fire, wake-poke) all run their turn inside the request or
+    // through `beginWork`, so they land on one of the two edges; `invoke` is the direct/debug door.
     const invocations = async (req) => {
         const response = await handleInvocation(req);
         if (stateSync && !isBusy())

package/dist/channels/control.d.ts

@@ -1,7 +1,36 @@
-import { type SessionControl, type SessionEvent } from "../session.ts";
+/**
+ * The session control plane over HTTP + SSE — the Phase 3 transport (design §13). Engine-neutral:
+ * consumes only the `SessionControl` contract. One transport serves every remote consumer (Web
+ * panel, desktop app, `fastagent attach`); the embedded API stays semantic-only and the ENVELOPE
+ * lives here: `id` (request correlation — implicit in HTTP), `epoch` (serving-process incarnation
+ * — INFORMATIONAL, for consumers correlating across connections; a restart surfaces as its
+ * connections dropping, so no one fences on it), `seq` (per-connection monotonic, detects loss in
+ * transit).
+ *
+ * SECURITY: these routes steer and stop runs, rewrite session properties, and delete records — a
+ * remote-control surface. The bearer token is REQUIRED (there is no unauthenticated mode) and is the only auth the framework owns; anything
+ * beyond a shared secret (principals, per-permission split, audit) is the wrapping host's job
+ * (design §14). Locally the serving process generates a per-boot token and writes it to
+ * `<stateRoot>/control.json` for local discovery — filesystem permissions guard the token, and the
+ * token guards the routes. That premise is shared-filesystem: a deployment breaks it, so there the
+ * DEPLOYER supplies the token ({@link CONTROL_TOKEN_ENV}) and both sides know it. How far those routes REACH is the bind address: all interfaces by
+ * default (containers require it), so the port is LAN-reachable and the mount warns accordingly —
+ * `--bind 127.0.0.1` (or `http.host`) closes exactly that reach, and the warning goes quiet because
+ * there is none left to state.
+ */
 import type { Agent } from "../agent.ts";
-import type { ChannelHandler } from "../channel.ts";
+import { type SessionControl, type SessionEvent } from "../session.ts";
 import { type PrefixMount } from "./serve.ts";
+/** A plane handler: the request, plus the session id the path named (`""` where the path has none). */
+type PlaneHandler = (req: Request, session: string) => Response | Promise<Response>;
+/** The plane's route table: `"<METHOD> <path>"` → handler, where at most one path segment is
+ *  {@link SESSION_SEGMENT}. */
+export type PlaneRoutes = Record<string, PlaneHandler>;
+/** The token, when the DEPLOYER owns it rather than the box (`mountSessionControl` reads it, `deploy`
+ *  carries it). Declared here with the prefix because both are the plane's public names: the serving
+ *  side and the deploy side must spell it identically, and a rename that hits only one of them fails
+ *  silently — the box mints its own and every caller the runbook told gets a 401. */
+export declare const CONTROL_TOKEN_ENV = "FASTAGENT_CONTROL_TOKEN";
 /** The SSE payload: one control-plane event in its transport envelope. */
 export interface WireEvent {
     sessionId: string;
@@ -23,16 +52,25 @@ export interface ControlPlaneOptions {
     agent?: Agent;
 }
 /**
- * Create the control plane as a mountable prefix owner: `GET
- * /control/capabilities|commands|state|entries|events` + `POST /control/dispatch`, all
- * bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
- * The plane OWNS {@link CONTROL_PREFIX}: it is mounted as one sub-application, answers its own
- * 404/405/preflight, and puts CORS headers on every reply — see {@link planeApp}.
+ * Create the control plane as a mountable prefix owner — a RESTful surface over
+ * {@link CONTROL_PREFIX}: sessions are a collection, a session is a resource, its history and event
+ * stream are sub-resources, and the things that HAPPEN to a run are posted to `…/actions`.
+ * The plane OWNS the prefix: it answers its own 404/405/preflight and puts CORS headers on every
+ * reply — see {@link planeApp}.
  */
 export declare function createControlPlane(control: SessionControl, options: ControlPlaneOptions): PrefixMount;
 /** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
- *  table is a set of literal paths. */
-export declare function mountControlPlane(routes: Record<string, ChannelHandler>): PrefixMount;
-/** The plane's route table. Exported so the conformance sweeps derive their route list from what is
- *  actually mounted, rather than from a hand-kept copy that cannot notice a new route. */
-export declare function controlPlaneRoutes(control: SessionControl, options: ControlPlaneOptions): Record<string, ChannelHandler>;
+ *  table is a set of paths, at most one segment of which is a session id. */
+export declare function mountControlPlane(routes: PlaneRoutes): PrefixMount;
+/**
+ * The plane's route table. Exported so the conformance sweeps derive their route list from what is
+ * actually mounted, rather than from a hand-kept copy that cannot notice a new route.
+ *
+ * The shape mirrors the contract: a collection, a resource, its sub-resources, and one action
+ * endpoint. What a session IS gets `GET`; what a session HAS gets `PATCH` (properties, last-wins);
+ * what happens TO a run gets `POST …/actions` (not a property — an event in time). `PUT` on a
+ * session id is the fork, and it is a PUT because a fork is idempotent by construction: the id is
+ * the caller's, the body says where the history came from, and repeating it changes nothing.
+ */
+export declare function controlPlaneRoutes(control: SessionControl, options: ControlPlaneOptions): PlaneRoutes;
+export {};