@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/answer-text.js

@@ -0,0 +1,18 @@
+/** Feed it a message's stream; it answers the text each event adds. */
+export function answerText() {
+    let streamed = "";
+    return (event) => {
+        if (event.type === "delta") {
+            if (event.channel !== "text")
+                return "";
+            streamed += event.text;
+            return event.text;
+        }
+        if (event.type !== "entry" || event.entry.kind !== "assistant")
+            return "";
+        const text = String(event.entry.data.text ?? "");
+        const missing = text.startsWith(streamed) ? text.slice(streamed.length) : "";
+        streamed = "";
+        return missing;
+    };
+}

package/dist/atomic-write.d.ts

@@ -11,8 +11,8 @@
  * redundant with it: `writeFileSync` honours `mode` only when it CREATES the file, so a temp left behind by a crashed
  * writer would keep its old, possibly looser permissions.
  *
- * `sharedWriters` is for a file SEVERAL processes may write at once (the merged models file, content-addressed, so
- * every writer writes the same bytes): each writes its own temp, and the last rename wins. A fixed temp there would
+ * `sharedWriters` is for a file SEVERAL processes may write at once (the generated `.fastagent/` files, which every
+ * command that reads the definition writes with the same bytes): each writes its own temp, and the last rename wins. A fixed temp there would
  * let one writer's rename take the other's file and fail it with ENOENT. No test exercises that race: it needs two
  * processes renaming within the same moment, which a test cannot arrange without being flaky.
  */

package/dist/atomic-write.js

@@ -15,8 +15,8 @@ import { dirname } from "node:path";
  * redundant with it: `writeFileSync` honours `mode` only when it CREATES the file, so a temp left behind by a crashed
  * writer would keep its old, possibly looser permissions.
  *
- * `sharedWriters` is for a file SEVERAL processes may write at once (the merged models file, content-addressed, so
- * every writer writes the same bytes): each writes its own temp, and the last rename wins. A fixed temp there would
+ * `sharedWriters` is for a file SEVERAL processes may write at once (the generated `.fastagent/` files, which every
+ * command that reads the definition writes with the same bytes): each writes its own temp, and the last rename wins. A fixed temp there would
  * let one writer's rename take the other's file and fail it with ENOENT. No test exercises that race: it needs two
  * processes renaming within the same moment, which a test cannot arrange without being flaky.
  */

package/dist/authoring.d.ts

@@ -0,0 +1,77 @@
+import { type BoundContent } from "./content/declare.ts";
+import type { DeclaredEnvironment } from "./environment/declare.ts";
+import { type ResolvedContent } from "./content/resolve.ts";
+import type { ContentAddition } from "./content/source.ts";
+/**
+ * A refusal about a content entry's NAME: one that cannot name an entry, one the agent already has, one it does not
+ * have. The caller can fix it by naming another (the CLI exits 2 and asks for `--name`).
+ */
+export declare class ContentNameError extends Error {
+    name: string;
+}
+export interface CreateAgentOptions {
+    /** What the agent works on and knows: repositories into `context.json`, this machine's directories into
+     *  `context.local.json`. */
+    content?: ContentAddition[];
+    /**
+     * Install the agent's dependencies, after the scaffold and before its first commit, so the lockfile is in that
+     * commit; the agent's code imports them. A rejection is a failed create: the scaffold is removed again and the error
+     * thrown, as when writing the content fails, so the directory is empty for a retry. One that reports its failure
+     * some other way (the CLI's resolves, and says the install failed) leaves the agent created.
+     */
+    install?: (dir: string) => Promise<void>;
+}
+export interface CreatedAgent {
+    /** The agent directory, absolute. */
+    dir: string;
+    /** The files written, relative to `dir`. */
+    created: string[];
+    /** The content, resolved for this instance. */
+    content: ResolvedContent[];
+    /**
+     * What became of the agent's git repository, as a sentence to show: created with the scaffold as its first commit,
+     * or why not (inside a repository that tracks it, git missing, no commit identity).
+     */
+    repository: string;
+}
+/**
+ * Create an agent in `dir`, which must be new or empty. Every content entry is checked before anything is written, and
+ * the scaffold is removed again when writing the content fails. The agent is then a git repository whose first commit
+ * is what was written:
+ * it changes itself, and version control is how its author goes back to a version that worked.
+ */
+export declare function createAgent(dir: string, options?: CreateAgentOptions): Promise<CreatedAgent>;
+/**
+ * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
+ * machine binds that are not here: the agent is not told of those.
+ */
+export declare function listContent(agentDir: string): Promise<{
+    content: ResolvedContent[];
+    absent: BoundContent[];
+}>;
+/**
+ * What an edit leaves: the entry it added or removed, by name, the agent's content after it, and what to tell the
+ * user about what was left on this machine.
+ */
+export interface ContentEdit {
+    name: string;
+    content: ResolvedContent[];
+    notes: string[];
+}
+/**
+ * Add a content entry to the agent in `agentDir`: its repository to `context.json`, its directory on this machine to
+ * `context.local.json`, or both. A name that cannot be one, or that the agent already has (ignoring case), is a
+ * {@link ContentNameError}.
+ */
+export declare function addContent(agentDir: string, addition: ContentAddition): Promise<ContentEdit>;
+/**
+ * Remove the agent's content entry named `name` (ignoring case), from `context.json` and from this machine's
+ * `context.local.json`. A clone at `content/<name>` is left as it is, and said: it may hold the agent's work, and
+ * fastagent never deletes a directory in `content/`. A name the agent does not have is a {@link ContentNameError}.
+ */
+export declare function removeContent(agentDir: string, name: string): Promise<ContentEdit>;
+/**
+ * Replace the environment `context.json` declares with what `change` makes of it as it is now, under the lock content
+ * edits take, keeping the rest of the file as it is; and return what was written.
+ */
+export declare function writeEnvironment(agentDir: string, change: (current: DeclaredEnvironment | undefined) => DeclaredEnvironment): Promise<DeclaredEnvironment>;

package/dist/authoring.js

@@ -0,0 +1,238 @@
+/**
+ * Creating an agent and editing its content: `fastagent init` and `fastagent content` are thin wrappers over these (and
+ * `fastagent env` writes its declaration through {@link writeEnvironment}), so the rules live here, not in a command.
+ * Nothing here prints or exits; every refusal is thrown with the message the CLI shows. Not exported from the package
+ * (#847 decides how a client reaches them).
+ */
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { writeFileAtomic } from "./atomic-write.js";
+import { GitNotInstalled, gitFor } from "./git.js";
+import { CONTEXT_FILE, LOCAL_CONTEXT_FILE, contentEntryPath, resolveAgentDir } from "./paths.js";
+import { initRepository, scaffoldAgent } from "./scaffold/init.js";
+import { canonicalBinding, canonicalEntry, declareBindings, declareContent, isContentName, } from "./content/declare.js";
+import { contextFileText, loadContent, localContextFileText, parseContextFile, parseLocalContextFile, } from "./content/file.js";
+import { checkBinding, contentAbsentHere, resolveContent } from "./content/resolve.js";
+import { withLockedFile } from "./locked-file.js";
+/** `context.json` is part of the definition, read by whoever reads the agent. */
+const CONTEXT_FILE_MODE = 0o644;
+/**
+ * A refusal about a content entry's NAME: one that cannot name an entry, one the agent already has, one it does not
+ * have. The caller can fix it by naming another (the CLI exits 2 and asks for `--name`).
+ */
+export class ContentNameError extends Error {
+    name = "ContentNameError";
+}
+/**
+ * Create an agent in `dir`, which must be new or empty. Every content entry is checked before anything is written, and
+ * the scaffold is removed again when writing the content fails. The agent is then a git repository whose first commit
+ * is what was written:
+ * it changes itself, and version control is how its author goes back to a version that worked.
+ */
+export async function createAgent(dir, options = {}) {
+    const agentDir = resolve(dir);
+    const additions = options.content ?? [];
+    let maps = { content: {}, bindings: {} };
+    for (const addition of additions)
+        maps = withAddition(agentDir, maps, addition).maps;
+    const { created, undo } = await scaffoldAgent(agentDir);
+    const removeAll = async (error) => {
+        await rm(join(agentDir, CONTEXT_FILE), { force: true });
+        await rm(join(agentDir, LOCAL_CONTEXT_FILE), { force: true });
+        await undo();
+        throw error;
+    };
+    // The content was checked above, so a refusal here is one that check could not foresee (the disk changed in
+    // between); the scaffold goes with it, or a retry would find "already an agent" declaring no content.
+    try {
+        if (Object.keys(maps.content).length > 0) {
+            writeFileAtomic(join(agentDir, CONTEXT_FILE), contextFileText({ content: maps.content }), CONTEXT_FILE_MODE);
+        }
+        if (Object.keys(maps.bindings).length > 0) {
+            writeFileAtomic(join(agentDir, LOCAL_CONTEXT_FILE), localContextFileText(maps.bindings), CONTEXT_FILE_MODE);
+        }
+    }
+    catch (error) {
+        await removeAll(error);
+    }
+    if (options.install)
+        await options.install(agentDir).catch(removeAll);
+    const content = resolveContent(agentDir, declarationOf(agentDir, maps));
+    return { dir: agentDir, created, content, repository: await initRepository(agentDir) };
+}
+/**
+ * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
+ * machine binds that are not here: the agent is not told of those.
+ */
+export async function listContent(agentDir) {
+    const dir = resolveAgentDir(agentDir);
+    const declaration = loadContent(dir);
+    return { content: resolveContent(dir, declaration), absent: contentAbsentHere(declaration) };
+}
+/**
+ * Add a content entry to the agent in `agentDir`: its repository to `context.json`, its directory on this machine to
+ * `context.local.json`, or both. A name that cannot be one, or that the agent already has (ignoring case), is a
+ * {@link ContentNameError}.
+ */
+export async function addContent(agentDir, addition) {
+    const dir = resolveAgentDir(agentDir);
+    const declaration = await editContext(dir, (shared, local) => {
+        const { maps } = withAddition(dir, mapsOf(shared, local), addition);
+        return {
+            result: declarationOf(dir, maps),
+            ...(addition.entry !== undefined ? { shared: contextFileText({ ...shared, content: maps.content }) } : {}),
+            ...(addition.binding !== undefined ? { local: localContextFileText(maps.bindings) } : {}),
+        };
+    });
+    const notes = addition.binding !== undefined ? unignoredLocalFile(dir) : [];
+    return { name: addition.name, content: resolveContent(dir, declaration), notes };
+}
+/**
+ * Remove the agent's content entry named `name` (ignoring case), from `context.json` and from this machine's
+ * `context.local.json`. A clone at `content/<name>` is left as it is, and said: it may hold the agent's work, and
+ * fastagent never deletes a directory in `content/`. A name the agent does not have is a {@link ContentNameError}.
+ */
+export async function removeContent(agentDir, name) {
+    const dir = resolveAgentDir(agentDir);
+    const { removed, wasDeclared, declaration } = await editContext(dir, (shared, local) => {
+        const found = entryNamed(mapsOf(shared, local), name);
+        const maps = {
+            content: without(shared.content, found.name),
+            bindings: without(local.content, found.name),
+        };
+        const declaration = declarationOf(dir, maps);
+        // What is left is resolved before it is written, so an entry that cannot be refuses the edit rather than failing
+        // it once it is made. The removed one is not asked: removing a broken entry is how it is mended.
+        resolveContent(dir, declaration);
+        return {
+            result: { removed: found.name, wasDeclared: found.shared, declaration },
+            ...(found.shared ? { shared: contextFileText({ ...shared, content: maps.content }) } : {}),
+            ...(found.local ? { local: localContextFileText(maps.bindings) } : {}),
+        };
+    });
+    const notes = [];
+    if (wasDeclared && lstatSync(contentEntryPath(dir, removed), { throwIfNoEntry: false })) {
+        notes.push(`content/${removed} is left as it is: it may hold the agent's work — delete it once nothing in it is needed`);
+    }
+    return { name: removed, content: resolveContent(dir, declaration), notes };
+}
+/**
+ * `maps` with `addition` among them, checked as a whole before anything is written: its name can name an entry and is
+ * not taken (ignoring case), the entry is valid, a repository to clone has nothing at `content/<name>` yet, a
+ * directory to bind can be bound, and every other entry still resolves (one that does not refuses the edit, not fails
+ * it once made).
+ */
+function withAddition(agentDir, maps, addition) {
+    const { name, entry, binding } = addition;
+    if (entry === undefined && binding === undefined)
+        throw new Error(`content "${name}": nothing to add`);
+    if (!isContentName(name)) {
+        throw new ContentNameError(`"${name}" cannot name content (one path segment of letters, digits, "-" and "_")`);
+    }
+    const taken = [...Object.keys(maps.content), ...Object.keys(maps.bindings)].find((key) => key.toLowerCase() === name.toLowerCase());
+    if (taken)
+        throw new ContentNameError(`this agent already has content named "${taken}"`);
+    const next = {
+        content: entry !== undefined ? { ...maps.content, [name]: canonicalEntry(entry) } : maps.content,
+        bindings: binding !== undefined ? { ...maps.bindings, [name]: canonicalBinding(binding) } : maps.bindings,
+    };
+    const declaration = declarationOf(agentDir, next);
+    if (binding === undefined) {
+        if (lstatSync(contentEntryPath(agentDir, name), { throwIfNoEntry: false })) {
+            throw new Error(`content/${name} already exists in ${agentDir}: move it away first`);
+        }
+    }
+    else {
+        const bound = declaration.bound.find((b) => b.name === name);
+        const repository = declaration.declared.find((d) => d.name === name);
+        checkBinding(agentDir, name, bound.path, repository);
+    }
+    resolveContent(agentDir, declaration);
+    return { maps: next };
+}
+/** `maps` declared: what every reader of the files would read from them. */
+function declarationOf(agentDir, maps) {
+    const declared = declareContent(maps.content);
+    return { declared, bound: declareBindings(maps.bindings, declared, agentDir) };
+}
+function mapsOf(shared, local) {
+    return { content: shared.content, bindings: local.content };
+}
+function without(map, name) {
+    return Object.fromEntries(Object.entries(map).filter(([key]) => key !== name));
+}
+/**
+ * Where the entry `name` matches ignoring case is written: its name, and which of the two files hold it. One the agent
+ * does not have is a {@link ContentNameError}.
+ */
+function entryNamed(maps, name) {
+    const matches = (key) => key.toLowerCase() === name.toLowerCase();
+    const shared = Object.keys(maps.content).find(matches);
+    const local = Object.keys(maps.bindings).find(matches);
+    const found = shared ?? local;
+    if (found !== undefined)
+        return { name: found, shared: shared !== undefined, local: local !== undefined };
+    const names = [...new Set([...Object.keys(maps.content), ...Object.keys(maps.bindings)])];
+    throw new ContentNameError(`no content named "${name}" (this agent has: ${names.join(", ") || "none"})`);
+}
+/**
+ * Run `edit` over both context files under ONE lock, `context.json`'s, which env edits take too: whether a name is
+ * taken is asked of both files, so two edits that write different files must still queue behind each other. The lock
+ * creates neither file; what `edit` returns for a file is written under it, `context.local.json` first.
+ */
+async function editContext(dir, edit) {
+    const sharedPath = join(dir, CONTEXT_FILE);
+    const localPath = join(dir, LOCAL_CONTEXT_FILE);
+    return withLockedFile(sharedPath, async (sharedText) => {
+        const shared = sharedText === undefined ? { content: {}, declared: [] } : parseContextFile(sharedText, sharedPath);
+        const localText = textIfExists(localPath);
+        const local = localText === undefined
+            ? { content: {}, bound: [] }
+            : parseLocalContextFile(localText, localPath, shared.declared, dir);
+        const out = edit(shared, local);
+        if (out.local !== undefined)
+            writeFileAtomic(localPath, out.local, fileMode(localPath));
+        return { result: out.result, next: out.shared };
+    }, { mode: fileMode(sharedPath), create: false });
+}
+function textIfExists(path) {
+    return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+/**
+ * What to say when git would commit `context.local.json`: it names directories of this machine, so committed it would
+ * point every other checkout of the agent at paths it does not have. `init` ignores it; an agent made before that may
+ * not. Asked only of an agent in a git repository, and never failing an edit that has already been made.
+ */
+function unignoredLocalFile(dir) {
+    const git = gitFor("to check that context.local.json stays out of git");
+    try {
+        if (git.answer(["rev-parse", "--is-inside-work-tree"], dir) !== "true")
+            return [];
+        if (git.answer(["check-ignore", "-q", LOCAL_CONTEXT_FILE], dir) !== undefined)
+            return [];
+    }
+    catch (error) {
+        if (error instanceof GitNotInstalled)
+            return [];
+        throw error;
+    }
+    return [`${LOCAL_CONTEXT_FILE} holds directories of this machine and git does not ignore it: add it to .gitignore`];
+}
+/**
+ * Replace the environment `context.json` declares with what `change` makes of it as it is now, under the lock content
+ * edits take, keeping the rest of the file as it is; and return what was written.
+ */
+export async function writeEnvironment(agentDir, change) {
+    const path = join(resolveAgentDir(agentDir), CONTEXT_FILE);
+    return withLockedFile(path, async (src) => {
+        const file = parseContextFile(src ?? "{}", path);
+        const environment = change(file.environment);
+        return { result: environment, next: contextFileText({ ...file, environment }) };
+    }, { mode: fileMode(path) });
+}
+/** The mode a rewrite of `path` keeps: its own, or the definition's default for a new one. */
+function fileMode(path) {
+    const stat = statSync(path, { throwIfNoEntry: false });
+    return stat === undefined ? CONTEXT_FILE_MODE : stat.mode & 0o777;
+}

package/dist/channel.d.ts

@@ -1,27 +1,39 @@
 /**
- * The Channel contract — the trigger side of the product boundary (core.md §1), beside `agent.ts` (what an engine
- * implements) and `session.ts` (the serving control plane). Pure types: importing a host, a framework, or an engine
- * here is forbidden, as in those two.
+ * The Channel contract: how a channel is mounted beside the Agent it talks to (agent-api.ts, SPEC.md §8.1), and
+ * `defineChannel`, which types a channel file's export. Importing a host, a framework, or a harness here is forbidden.
  */
-import type { Agent } from "./agent.ts";
-import type { SessionControl } from "./session.ts";
+import type { Agent, CreateSessionOptions } from "./agent-api.ts";
 /** A mounted request handler (a channel's fetch, or a plain route like health). */
 export type ChannelHandler = (req: Request) => Response | Promise<Response>;
 /** This deployment's HTTP surface: route key → handler. */
 export type Routes = Record<string, ChannelHandler>;
-/**
- * What the framework hands a channel at mount time: the assembled agent plus the resolved state ROOT (absolute;
- * `FASTAGENT_STATE_DIR` > `<root>/.state`).
- */
+/** The session a new conversation forks from, as `sessions.create` takes it; `undefined` starts it empty. */
+export type ForkSource = CreateSessionOptions["forkFrom"];
+/** What a channel is handed when it is mounted, and all it is handed. */
 export interface ChannelContext {
+    /** The Agent, in process. */
     agent: Agent;
-    stateRoot: string;
-    /** The serving session-control hub: every serve has it, so a stop command reaches the live run through it.
-     *  `config.sessionControl` decides only whether the SAME hub is also published as `/control/*` (and wires its
-     *  write side). Absent only when an embedder mounts a service without one. */
-    control?: SessionControl;
+    /**
+     * The session the conversation `key` talks in: the one this channel recorded for it, or a new one created and
+     * recorded before it is returned, so a message is sent only into a recorded session. With `forkFrom`, a new one is
+     * a fork of what it answers, asked only when `key` has no session yet. Calls for one key are taken one at a time,
+     * so two first messages of a new conversation get one session.
+     */
+    sessionFor(key: string, options?: {
+        forkFrom?: () => Promise<ForkSource>;
+    }): Promise<string>;
+    /** The session recorded for `key`, without creating one: what a stop command asks of a place nothing was said in. */
+    recordedSession(key: string): string | undefined;
+    /**
+     * Run `work` after the route has answered, one at a time per `place` (a chat, a thread) in the order they arrived,
+     * counted as work in flight, which `dev`'s restart and AgentCore's `/ping` wait for. It keeps no record: a turn the
+     * process stops before it runs is lost unless the platform delivers its event again. A failure goes to the log.
+     */
+    turn(place: string, work: () => Promise<void>): void;
+    /** The channel's own directory, `<state root>/channels/<the channel file's name>`, for the records it must keep. */
+    stateDir: string;
 }
-/** A `channels/<name>.ts` route channel: receives mount context and returns its HTTP routes. */
+/** A `channels/<name>.ts` route channel: receives its context and returns its HTTP routes. */
 export type ChannelModule = (ctx: ChannelContext) => Routes;
 export interface LongConnection {
     ready: Promise<void>;
@@ -32,3 +44,5 @@ export interface LongConnectionChannelModule {
     name: string;
     connect(ctx: ChannelContext, signal: AbortSignal): LongConnection;
 }
+/** What a channel file default-exports, typed: its routes for a context, or a long connection. */
+export declare function defineChannel<T extends ChannelModule | LongConnectionChannelModule>(channel: T): T;

package/dist/channel.js

@@ -1 +1,4 @@
-export {};
+/** What a channel file default-exports, typed: its routes for a context, or a long connection. */
+export function defineChannel(channel) {
+    return channel;
+}

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

@@ -6,7 +6,7 @@ export declare const RESERVED_PATHS: {
     readonly wakeAlarm: "/__fastagent/wake-alarm";
 };
 /** Every kind the container's `POST /invocations` dispatches on. */
-export declare const ENVELOPE_KINDS: readonly ["webhook", "routine-fire", "routine-run", "invoke", "wake-poke", "probe"];
+export declare const ENVELOPE_KINDS: readonly ["webhook", "schedule-fire", "wake-poke", "probe"];
 /**
  * Did this envelope come from the FORWARDER, rather than from some other principal holding
  * `bedrock-agentcore:InvokeAgentRuntime`?
@@ -15,8 +15,8 @@ export declare const ENVELOPE_KINDS: readonly ["webhook", "routine-fire", "routi
  * (`envelope.wake.url`) is where the container later POSTs its wake alarms, carrying `FASTAGENT_WAKE_SECRET` — so a
  * principal who could set it would redirect that callback and collect the secret along with every pending wake-up.
  *
- * The other thing it gates — the non-`invoke` kinds — is DEPTH, not a boundary. Every one of them is weaker than
- * the `invoke` the same caller may already send: `routine-fire` runs a prompt the definition wrote down,
+ * The other thing it gates — the kinds other than `api` — is DEPTH, not a boundary. Every one of them is weaker than
+ * the `api` the same caller may already send: `schedule-fire` runs a prompt the definition wrote down,
  * `webhook` reaches only channel routes that verify their own platform's signature, `wake-poke` wakes, `probe`
  * reports. IAM is what decides who gets to ask at all.
  *
@@ -26,6 +26,16 @@ export declare const ENVELOPE_KINDS: readonly ["webhook", "routine-fire", "routi
 export declare function fromForwarder(envelope: {
     auth?: unknown;
 } | undefined, expected: string | undefined): boolean;
+/** An HTTP request carried inside an envelope, byte-exact. */
+export interface CarriedRequest {
+    method: string;
+    path: string;
+    /** Raw query string, no leading `?`. */
+    query?: string;
+    headers?: Record<string, string>;
+    /** The body, base64 (byte-exact). */
+    bodyB64?: string;
+}
 /** What the forwarder Lambda / EventBridge deliver in the `/invocations` payload. */
 export type AgentcoreEnvelope = {
     /** Shared secret proving this envelope came from the forwarder (FASTAGENT_INGRESS_SECRET). */
@@ -33,22 +43,10 @@ export type AgentcoreEnvelope = {
     wake?: {
         url: string;
     };
-} & ({
+} /** A platform's webhook, verbatim: its headers carry the signature material its channel checks. */ & (({
     kind: "webhook";
-    /** Original webhook request line, verbatim. */
-    method: string;
-    path: string;
-    /**
-     * Original raw query string (no leading `?`) — "verbatim" includes it; a channel reading
-     * `request.url.searchParams` must see what the webhook sender sent.
-     */
-    query?: string;
-    /** Original headers — signature material (secret tokens, Feishu signatures) rides here. */
-    headers?: Record<string, string>;
-    /** Original body, base64 (webhook bodies are JSON but the tunnel must be byte-exact). */
-    bodyB64?: string;
-} | {
-    kind: "routine-fire";
+} & CarriedRequest) | {
+    kind: "schedule-fire";
     name: string;
     /**
      * The instant EventBridge scheduled this fire for — the clock's NAME for the occurrence, stable across its
@@ -56,24 +54,6 @@ export type AgentcoreEnvelope = {
      * never recomputes it.
      */
     occurrence: string;
-} | {
-    /**
-     * Run a declared routine BY NAME — the `POST /run` contract on the host that publishes no routes.
-     *
-     * On the IAM door, like `invoke`, and for the same reason: the forwarder never emits this, so it can only
-     * come from a direct `InvokeAgentRuntime` call, where AWS has already said who the caller is. That makes
-     * by-name running STRICTER here than on a host with a public URL, where the same route is anonymous.
-     *
-     * Separate from `routine-fire` because they are different contracts, not two spellings: a fire names an
-     * OCCURRENCE our own clock produced and claims it (dedup across redeliveries, a fire history, the overlap
-     * policy); this names only the work (schedule/run.ts).
-     */
-    kind: "routine-run";
-    name: string;
-} | {
-    kind: "invoke";
-    session: string;
-    text: string;
 }
 /**
  * An EventBridge wake-up poke: the invocation ITSELF is the payload — it wakes the container, whose boot drain / 30s
@@ -85,7 +65,7 @@ export type AgentcoreEnvelope = {
 /**
  * The deploy driver's post-deploy verification (relayed by the forwarder's reserved probe path, which answers on
  * EVERY forwarder topology — schedule-only URLs refuse ordinary public traffic). Also accepted from the IAM door,
- * where it only opens the workspace (`login --deployment` needs one) and does not construct the channels.
+ * where it only opens the deployed definition (`login --deployment` needs one) and does not construct the channels.
  */
  | {
     kind: "probe";
@@ -99,24 +79,30 @@ export interface WebhookReply {
     headers: Record<string, string>;
     bodyB64: string;
 }
-/** One desired alarm: mirror of a pending wake-up (id names the EventBridge schedule; at = fireAt). */
+/** One desired one-shot alarm: a pending wake-up's next instant, which pokes the container. */
 export interface WakeAlarm {
+    /** One per INSTANT (`<wake id>@<instant>`), so mirroring again never rewrites a spent alarm. */
     id: string;
     at: string;
 }
-/** The wire shape the wake sink POSTs to {@link RESERVED_PATHS.wakeAlarm} (the forwarder validates `secret`). */
-export interface WakeAlarmRequest {
-    secret: string;
-    alarms: WakeAlarm[];
+/**
+ * One desired RECURRING schedule: a `schedules/` file as an EventBridge cron schedule, which EventBridge fires on its
+ * own clock. Each fire delivers `{scheduleFire: {name, occurrence: <aws.scheduler.scheduled-time>}}`, the instant it
+ * was scheduled for, repeated byte-identical on every redelivery, which is what lets the container claim it once.
+ */
+export interface RecurringSchedule {
+    name: string;
+    /** EventBridge's `cron(...)` (schedule/eventbridge-cron.ts). */
+    expression: string;
+    /** IANA zone the expression is evaluated in. */
+    tz: string;
 }
 /**
- * What EventBridge hands the forwarder when a cron rule fires: which schedule, and which occurrence of it.
- * `occurrence` is `<aws.scheduler.scheduled-time>` — the clock names its own fire, which is the only thing that
- * survives a retry (schedule/run.ts).
+ * The wire shape the wake sink POSTs to {@link RESERVED_PATHS.wakeAlarm} (the forwarder validates `secret`). The
+ * schedules are the WHOLE desired set: the forwarder deletes a recurring schedule it holds that is not in it.
  */
-export interface ScheduleFireEvent {
-    scheduleFire: {
-        name: string;
-        occurrence: string;
-    };
+export interface WakeAlarmRequest {
+    secret: string;
+    alarms: WakeAlarm[];
+    schedules: RecurringSchedule[];
 }

package/dist/channels/agentcore-protocol.js

@@ -8,7 +8,7 @@ export const RESERVED_PATHS = {
     wakeAlarm: "/__fastagent/wake-alarm",
 };
 /** Every kind the container's `POST /invocations` dispatches on. */
-export const ENVELOPE_KINDS = ["webhook", "routine-fire", "routine-run", "invoke", "wake-poke", "probe"];
+export const ENVELOPE_KINDS = ["webhook", "schedule-fire", "wake-poke", "probe"];
 /**
  * Did this envelope come from the FORWARDER, rather than from some other principal holding
  * `bedrock-agentcore:InvokeAgentRuntime`?
@@ -17,8 +17,8 @@ export const ENVELOPE_KINDS = ["webhook", "routine-fire", "routine-run", "invoke
  * (`envelope.wake.url`) is where the container later POSTs its wake alarms, carrying `FASTAGENT_WAKE_SECRET` — so a
  * principal who could set it would redirect that callback and collect the secret along with every pending wake-up.
  *
- * The other thing it gates — the non-`invoke` kinds — is DEPTH, not a boundary. Every one of them is weaker than
- * the `invoke` the same caller may already send: `routine-fire` runs a prompt the definition wrote down,
+ * The other thing it gates — the kinds other than `api` — is DEPTH, not a boundary. Every one of them is weaker than
+ * the `api` the same caller may already send: `schedule-fire` runs a prompt the definition wrote down,
  * `webhook` reaches only channel routes that verify their own platform's signature, `wake-poke` wakes, `probe`
  * reports. IAM is what decides who gets to ask at all.
  *

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

@@ -1,28 +1,18 @@
-/** The AgentCore serving assembly — the same product as `mountAgentService`, built differently because the host is. */
-import type { Agent } from "../agent.ts";
+/** The AgentCore serving assembly — the same product as `serveAgent`, built differently because the host is. */
+import type { Agent } from "../agent-api.ts";
 import type { Routes } from "../channel.ts";
-import type { LoadedRoutine } from "../schedule/routine.ts";
-import { type AgentService, type MountableAgent } from "../service.ts";
+import type { Schedule } from "../schedule/schedule.ts";
+import { type ServableAgent, type ServedAgent, type Service } from "../service.ts";
 import { type AgentcoreAdapterOptions } from "./agentcore.ts";
-import type { ChannelHandler } from "../channel.ts";
 /**
  * Runtime filesystems appear on invocation, so even opening the definition must be deferred — in the TWO stages that
  * differ in what a retry would cost.
  */
 export declare function deferAgentcoreService<T>(stages: {
     prepare: () => Promise<T>;
-    assemble: (prepared: T) => Promise<AgentService>;
-}): {
-    handler: ChannelHandler;
-    close: () => Promise<void>;
-};
-export interface MountAgentcoreServiceOptions {
-    /** Wrap the opened agent before anything binds to it (the CLI's turn trace). */
-    wrapAgent?: (agent: Agent) => Agent;
-    /** The process entry owns the global wake-alarm sink; activation reconciles it once. */
-    onStateReady?: () => void;
-}
-export declare function mountAgentcoreService(opened: MountableAgent, options?: MountAgentcoreServiceOptions): Promise<AgentService>;
+    assemble: (prepared: T) => Promise<ServedAgent>;
+}): Service;
+export declare function mountAgentcoreService(opened: ServableAgent): Promise<ServedAgent>;
 /**
  * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) — the deployed container's ONLY reachable
  * surface (channels/agentcore.ts).
@@ -30,7 +20,7 @@ export declare function mountAgentcoreService(opened: MountableAgent, options?:
 export declare function mountAgentcore(options: {
     agent: Agent;
     stateRoot: string;
-    routines: readonly LoadedRoutine[];
+    schedules: () => readonly Schedule[];
     onStateReady?: () => void;
     /** The channel surface, initialized once by the adapter on trusted ingress. */
     channels: AgentcoreAdapterOptions["channels"];