@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/service.d.ts

@@ -1,158 +1,197 @@
-/**
- * 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 type { Agent } from "./agent.ts";
 import { type PrefixMount } from "./channels/serve.ts";
 import { type LoadedLongConnectionChannel } from "./channels/discover.ts";
 import type { SessionControl } from "./session.ts";
 import type { ChannelHandler, Routes } from "./channel.ts";
-import type { LoadedSchedule } from "./schedule/schedule.ts";
+import type { LoadedRoutine } from "./schedule/routine.ts";
 export interface ServingSurface {
-    routes: Routes;
+    /**
+     * The routes that AUTHENTICATE NOBODY — `GET /health`, `POST /invoke`, and `POST /run` where the definition
+     * declares routines, minus what a channel took over or `http.invoke: false` withheld. Kept APART from the channels' rather than merged with a list of which keys are
+     * which: three separate decisions read this (browser reachability, the JSON body gate, what the startup line
+     * calls unauthenticated), and while it was a derived list each of them could answer differently.
+     */
+    unverified: Routes;
+    /**
+     * What the `channels/` files serve. Exempt from both guards because a channel checks its platform's signature
+     * inside itself — an assumption about the author for a CUSTOM channel, not a property we enforce (§14).
+     */
+    selfVerifying: Routes;
     /** Prefix-owning handlers mounted beside the routes (the session control plane). */
     mounts?: readonly PrefixMount[];
     longConnections: LoadedLongConnectionChannel[];
     /** Route-channel basenames; the tunnel registers only this subset. */
     routeChannels: string[];
-    builtinInvoke: boolean;
-    /** Flip health between 200 and 503. Two-way on purpose: a long connection that dies after coming
-     *  up leaves the surface serving something it no longer has, and a load balancer should hear it. */
+    /** Flip health between 200 and 503. */
     setReady(value: boolean): void;
 }
+/** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
+export declare const DEFAULT_HTTP_PORT = 8787;
 /**
- * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
- * POST `/invoke` only when neither a route nor a long-connection channel was declared.
+ * What a serve publishes on its port, and to which browsers — the config file's `http` block minus `port`, carried
+ * as-is into the assembly so every reader (the routes, the startup report, deploy's pre-flight, AgentCore's inert-key
+ * warnings) reads ONE value. The port is not here: the assembly binds nothing, so only the CLI reads it.
  */
-export declare function routesFor(agentDir: string, agent: Agent, stateRoot: string, control: SessionControl | undefined, options?: {
-    builtinInvoke?: boolean;
-}): Promise<ServingSurface>;
+export interface HttpSurface {
+    /**
+     * The origins a BROWSER may call this serve from. The default, with this unset, answers EVERY origin: any page your
+     * users visit can call this port and read the reply, and every route here is unauthenticated. Set it to your front
+     * end's real domain to take that back (`["*"]` is the default said out loud; an empty list is refused, because it
+     * reads as "nobody" and would mean the opposite).
+     */
+    cors?: readonly string[];
+    /**
+     * Serve the data plane, `POST /invoke`. On by default: it is the framework's interface, and a deployment that can
+     * only be reached through a chat channel is still worth curling. Set it `false` when this port is public and the
+     * channels' own signature checks are meant to be the only way in — the route is unauthenticated and runs a turn
+     * with the agent's full tool authority.
+     */
+    invoke?: boolean;
+    /**
+     * Serve `POST /run` (and `GET /routines`), which run a routine this definition declares by name. It follows
+     * `invoke` unless set: turning the anonymous turn endpoint off must not leave a second one open behind it. Set it
+     * `true` for the one combination that gets wrong — no `/invoke`, but an external clock (a crontab, a CI job) driving
+     * the routines. It has no effect where `routines/` declares nothing; there is no route then.
+     */
+    run?: boolean;
+}
 /**
- * Refuse channel routes the control plane would swallow.
+ * Does this surface serve `POST /run`, given a routine to run? It FOLLOWS `invoke` unless `run` says otherwise (see
+ * {@link HttpSurface.run}). ONE function because the assembly mounts the route and `preflightDeploy` names it; a
+ * default spelled twice is a default that moves once.
+ */
+export declare function shouldServeRun(http: HttpSurface | undefined): boolean;
+/**
+ * What an anonymous caller of a port can do, worst first — the ONE wording the startup report and deploy's pre-flight
+ * both print, each from its own facts (what mounted vs what will mount).
+ */
+export declare function describeAnonymousSurface(open: {
+    invoke: boolean;
+    run: boolean;
+    controlPrefix?: string;
+}): string[];
+/**
+ * The surface this deployment serves: the DATA plane (`POST /invoke`), `GET /health`, and the discovered channels.
  *
- * `router` refuses this too, and would catch it a moment later; this exists for the sentence, not
- * the check — an author who lands a route under `/control` needs to hear about `sessionControl`,
- * which the host has no way to mention. Both ask {@link pathUnderPrefix}, so there is one rule with
- * two wordings, not two rules.
+ * `/invoke` is the framework's interface, so it is served whatever channels a definition declares (unless
+ * `http.invoke: false`). It is RESERVED for the same reason `/control/*` is: a channel taking that path would silently replace the one route every client,
+ * every doc and the startup line all name. `/health` stays overridable — a probe is the deployment's to shape.
+ */
+export declare function routesFor(agentDir: string, agent: Agent, stateRoot: string, control: SessionControl | undefined, 
+/**
+ * `http.invoke: false` withholds the data plane. Two callers, two reasons: the AgentCore adapter serves the
+ * Runtime's `/invocations` contract instead, and an author sets it to leave the channels' signature checks as the
+ * only way into a public port.
  *
- * Called from BOTH mount points: here at boot, and again on agentcore's lazy path, whose channels
- * load after this ran against an empty base.
+ * `routines` mounts `POST /run` and `GET /routines` (per {@link shouldServeRun}). Passed in rather than loaded here
+ * so the routes and the resident clock cannot disagree about which routines exist (`loadServingRoutines`).
  */
+options?: {
+    http?: HttpSurface;
+    routines?: readonly LoadedRoutine[];
+}): Promise<ServingSurface>;
+/** Refuse channel routes the control plane would swallow. */
 export declare function assertNoControlPlaneCollision(channelRoutes: Routes, plane: PrefixMount): void;
-export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, options?: {
-    agent?: Agent;
-}): {
+export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined): {
     routes: Routes;
     mounts: PrefixMount[];
-    /** The plane's bearer token and prefix — how a caller distributes access (the CLI writes it to
-     *  `<stateRoot>/control.json` for local discovery; an embedder hands it out itself). */
-    control?: {
-        token: string;
-        prefix: string;
-    };
+    /** The prefix the plane owns, when it is published — what a startup line names. */
+    controlPrefix?: string;
 };
 /**
- * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
- * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals. Returns the
- * loaded schedules so a serving surface that needs them (the AgentCore adapter's fire binding) shares
- * ONE load instead of re-discovering. `externalClock` (AgentCore) arms no resident cron timers.
+ * Load the agent's `routines/`, gated.
+ *
+ * Separate from {@link startSchedules} because two things need the SAME list and one of them runs first: the
+ * `POST /run` route is built with the routes (so a channel cannot take that path unnoticed), and the resident
+ * clock starts later, inside the service's scope. Loading twice would let them disagree about which routines exist.
+ */
+export declare function loadServingRoutines(agentDir: string): Promise<LoadedRoutine[]>;
+/**
+ * Start the clock over routines {@link loadServingRoutines} already gated — on every serve, routines or not: the
+ * agent's own wake-ups are a default capability, and this is what fires them.
  */
-export declare function startSchedules(agentDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean, options?: {
+export declare function startSchedules(agent: Agent, stateRoot: string, routines: LoadedRoutine[], options?: {
     externalClock?: boolean;
-}): Promise<{
-    schedules: LoadedSchedule[];
+}): {
+    routines: LoadedRoutine[];
     stop: () => void;
-}>;
+};
 export interface AgentService {
-    /** The assembled Fetch handler: channel routes, the control plane, and health. Mount it wherever
-     *  your host speaks `(Request) => Response`; `nodeListener` bridges it to Node's `(req, res)`. */
+    /** The assembled Fetch handler: channel routes, the control plane, and health. */
     handler: ChannelHandler;
     /** The agent behind it — invoke it directly when you also want a programmatic path. */
     agent: Agent;
-    /** The literal routes `handler` was composed from — for a startup line naming what is served.
-     *  Mounted prefixes are not here: nothing outside the assembly needed them, and a field kept for a
-     *  hypothetical caller is a field nobody maintains. */
+    /** The literal routes `handler` was composed from — for a startup line naming what is served. */
     routes: Routes;
     agentDir: string;
     workspace: string;
-    /** What actually mounted, for a startup line: channel files serving routes, long connections, and
-     *  whether the built-in `POST /invoke` fallback is one of the routes. That last one is a FACT of
-     *  the assembly, not something to re-infer from a path — a channel may legally author
-     *  `POST /invoke` with a protocol of its own. */
+    /**
+     * What actually mounted, for a startup line: channel files serving routes, and long connections.
+     */
     channels: {
         routes: string[];
         longConnections: string[];
-        builtinInvoke: boolean;
     };
-    schedules: readonly LoadedSchedule[];
-    /** Settles when every long connection is up — immediately when there are none. REJECTS if one
-     *  fails to come up, after closing the service: a host must not report itself serving while a
-     *  declared channel is dead, and health answers 503 until this resolves. */
+    /**
+     * The route keys on this port that AUTHENTICATE NOBODY — `GET /health`, `POST /invoke`, and `POST /run` where
+     * the definition declares routines, minus what a channel took over or `http.invoke: false` withheld. The FACT a caller needs to describe this surface: reading it off
+     * `routes` instead answers a different question, since a channel may serve one of those paths with a protocol of
+     * its own. That mistake ran in both directions here — a try-it curl for a route that 404s, and a warning about an
+     * unauthenticated `/invoke` that was really a signature-checked channel.
+     */
+    unverifiedRoutes: readonly string[];
+    /**
+     * The cross-origin allow-list this service was assembled with (`http.cors`), or `undefined` for the `*` default.
+     * Read by the startup report for the same reason as {@link AgentService.unverifiedRoutes}: what a caller says
+     * about this surface must come from what was actually assembled, not from re-deriving it.
+     */
+    corsOrigins?: readonly string[];
+    routines: readonly LoadedRoutine[];
+    /** Settles when every long connection is up — immediately when there are none. */
     ready: Promise<void>;
-    /** The control plane's bearer token and prefix, when `sessionControl` is on — how a caller hands
-     *  access to a client. The CLI writes it to `<stateRoot>/control.json` for `fastagent attach`; an
-     *  embedder mounted inside a larger app has no port of its own to describe and distributes it
-     *  itself. */
-    control?: {
-        token: string;
-        prefix: string;
-    };
-    /** Stop long connections and schedules. Idempotent; also runs when `options.signal` aborts. */
+    /** The control plane's prefix, when `sessionControl` is on. */
+    controlPrefix?: string;
+    /**
+     * Stop long connections and routines. It does NOT drain agent turns: a turn takes seconds to minutes, and the
+     * deployment wants the old process gone in under a second (`SHUTDOWN_GRACE_MS` in `src/cli/serve.ts`). What makes
+     * that safe is replay, not waiting — a chat turn's intent is durable before it is accepted and its channel
+     * replays it on the next boot (`channels/kit/turn-store.ts`), and an in-flight HTTP/SSE caller sees the stream
+     * drop and retries. The one path with neither is a routine fire, whose claim is written before the turn: it
+     * stays skipped, and the next boot records it as `interrupted` rather than losing it silently.
+     */
     close(): Promise<void>;
 }
 /** What {@link mountAgentService} needs beyond an opened directory. */
 export interface MountAgentServiceOptions {
-    /** Wrap the agent before anything consumes it — every consumer (routes, control plane, schedules)
-     *  must get the SAME one, which is why this is a hook rather than the caller's own call. `dev`
-     *  passes `logAgentLoop`. */
+    /** Wrap the agent before anything consumes it. */
     wrapAgent?: (agent: Agent) => Agent;
     /** Aborting this closes the service, exactly like calling {@link AgentService.close}. */
     signal?: AbortSignal;
-    /** Called when a long connection ends on its own — a dropped socket-mode channel, say. The CLI
-     *  exits; an embedded host may prefer to log. Default: log an error. */
+    /** Called when a long connection ends on its own — a dropped socket-mode channel, say. */
     onChannelClosed?: (name: string, error?: unknown) => void;
-    /** How long `close()` waits for a channel to stop before reporting it stuck (default 5s). The CLI
-     *  shortens it so its own forced exit lands after this answer, not before it. */
+    /** How long `close()` waits for a channel to stop before reporting it stuck (default 5s). */
     closeTimeoutMs?: number;
 }
-/**
- * What the assembly needs from an opened agent directory — the whole of it. Spelled as its own type
- * rather than an engine's return shape: every field here is either the SPEC contract or a path, so
- * an engine that is not pi can satisfy it without either side knowing about the other.
- */
+/** What the assembly needs from an opened agent directory — the whole of it. */
 export interface MountableAgent {
     agent: Agent;
-    /** The definition dir: where channels/, tools/ and schedules/ are read from. */
+    /** The definition dir: where channels/, tools/ and routines/ are read from. */
     agentDir: string;
     /** The agent's cwd. */
     workspace: string;
-    /** Where durable state lives (channel state, sessions, schedule fires). */
+    /** Where durable state lives (channel state, sessions, routine fires). */
     stateRoot: string;
-    /** Present iff this agent published a control plane. */
+    /** The session-control hub, when the opener built one. A serve has it whether or not `/control/*` is published:
+     *  a chat channel's stop command reaches the running turn through it. */
     sessionControl?: SessionControl;
-    /** Whether the agent schedules its own follow-up turns. REQUIRED, not optional-with-a-default:
-     *  an engine that forgot it would turn self-scheduling off silently, which is exactly the bug
-     *  this type was introduced with. */
-    selfSchedule: boolean;
+    /** Whether that hub is ALSO served as `/control/*` (`config.sessionControl`). Required, not defaulted: an
+     *  embedder assembling this by hand would otherwise lose the plane to a 404 with nothing said anywhere. */
+    publishControl: boolean;
+    /** What the port publishes, and to which browsers — the config's `http` block ({@link HttpSurface}). */
+    http?: HttpSurface;
 }
 /**
- * The assembly itself, over an already-opened directory: channels, the control plane, schedules and
- * long connections, composed into one handler.
- *
- * {@link createAgentService} is this plus opening the directory. `dev`/`start` open separately — their
- * startup report needs the opened values before anything mounts — and then arrive here, so there is
- * one assembly rather than one per caller.
+ * The assembly itself, over an already-opened directory: channels, the control plane, routines and long connections,
+ * composed into one handler.
  */
 export declare function mountAgentService(opened: MountableAgent, options?: MountAgentServiceOptions): Promise<AgentService>;