@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/README.md

@@ -42,7 +42,7 @@ FastAgent is the missing bridge from local agent directory to live service.
 - **Durable by default.** Every conversation lives in the instance's storage, and an accepted message is answered after a restart. Built on the open-source [pi](https://github.com/earendil-works/pi) durable harness.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key, plus your own providers in code; typed tools in `src/tools/` (TypeBox-validated); Agent Skills loaded on demand.
 - **App embedding — your stack, we plug in.** Open the agent in your own process and call it like any function, behind your auth, with your database and infra; mount its channels in your Next / Astro / Hono / Bun / Node app with one handler. FastAgent composes with your app, never owns it.
-- **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway|agentcore` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels; AWS Bedrock AgentCore gets a one-stack CloudFormation topology (webhooks via a forwarder Lambda, schedules via EventBridge). Durable ingress remains yours.
+- **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway|agentcore` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; AWS Bedrock AgentCore gets a one-stack CloudFormation topology (webhooks via a forwarder Lambda, schedules via EventBridge). Durable ingress remains yours.
 
 ## Design philosophy
 
@@ -107,9 +107,14 @@ There is no FastAgent build step: the agent folder is the deployable unit.
 ## Embed in an app
 
 ```ts
-import { openAgent } from "@fastagent-sh/fastagent";
-
-const agent = await openAgent("./agent", { model: "openai/gpt-5.5" });
+import { baseEnv, openAgent } from "@fastagent-sh/fastagent";
+import support from "@acme/support-agent"; // the default export of a package `fastagent build` made
+
+const agent = await openAgent(support, {
+  root: "/var/lib/myapp/support",
+  env: baseEnv(process.env),
+  model: "openai/gpt-5.5",
+});
 
 const session = await agent.sessions.create();
 for await (const event of agent.messages.stream({ sessionId: session.id, content: "hi" })) {

package/dist/atomic-write.d.ts

@@ -3,16 +3,15 @@
  *
  * The temp name is FIXED (`<path>.tmp`), which rests on one process writing one state root: a deployment runs one
  * container, `dev`'s supervisor respawns its worker only after the old one has exited, and these writes are
- * synchronous. Slack's onboarding state is the documented exception (`add slack` plus the config-token rotation at
- * `--tunnel` startup); it stays fixed because that window is one rare, self-repairing write, and because the fixed
- * name is the seam channel tests use to inject a write failure. Revisit before adding a writer that is neither.
+ * synchronous. The fixed name is also the seam channel tests use to inject a write failure. Revisit before adding a
+ * writer that is not one process's synchronous write.
  *
  * `mode` is applied to the temp first, so the content is never briefly world-readable, and the `chmod` is not
  * 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 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
+ * `sharedWriters` is for a file SEVERAL processes may write at once (the model catalog's lists, which every process
+ * that refreshes them writes): 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

@@ -7,16 +7,15 @@ import { dirname } from "node:path";
  *
  * The temp name is FIXED (`<path>.tmp`), which rests on one process writing one state root: a deployment runs one
  * container, `dev`'s supervisor respawns its worker only after the old one has exited, and these writes are
- * synchronous. Slack's onboarding state is the documented exception (`add slack` plus the config-token rotation at
- * `--tunnel` startup); it stays fixed because that window is one rare, self-repairing write, and because the fixed
- * name is the seam channel tests use to inject a write failure. Revisit before adding a writer that is neither.
+ * synchronous. The fixed name is also the seam channel tests use to inject a write failure. Revisit before adding a
+ * writer that is not one process's synchronous write.
  *
  * `mode` is applied to the temp first, so the content is never briefly world-readable, and the `chmod` is not
  * 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 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
+ * `sharedWriters` is for a file SEVERAL processes may write at once (the model catalog's lists, which every process
+ * that refreshes them writes): 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

@@ -1,4 +1,3 @@
-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";
@@ -10,8 +9,7 @@ export declare class ContentNameError extends Error {
     name: string;
 }
 export interface InitAgentOptions {
-    /** What the agent works on: repositories into `context.json`, this machine's directories into
-     *  `context.local.json`. */
+    /** What the agent works on: repositories for its program into `context.json`, the rest into `fastagent.json`. */
     content?: ContentAddition[];
     /**
      * Install the agent's dependencies, after the scaffold and before its first commit, so the lockfile is in that
@@ -32,13 +30,20 @@ export interface CreatedAgent {
      */
     repository: string;
 }
+/** Where an agent's content is declared and kept: which instance configuration is edited, and where clones go. */
+export interface ContentScope {
+    /** The instance configuration to edit, absolute. Default: `fastagent.json` in the agent directory. */
+    config?: string;
+    /** The instance's working directory, where a clone is made. Default: the agent directory. */
+    workdir?: string;
+}
 /**
  * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
  * repository whose first commit is what was written, since the agent changes itself and version control is how its
  * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
  *
  * `content` gives it any number of entries, each a directory of this machine or a GitHub repository. They are all
- * checked before anything is written, and one that is refused leaves no directory. Two entries may bind the same
+ * checked before anything is written, and one that is refused leaves no directory. Two entries may be the same
  * directory, or one inside the other; the agent then reaches it by both names.
  */
 export declare function createAgent(dir: string, options?: {
@@ -54,12 +59,11 @@ export declare function initAgent(dir: string, options?: InitAgentOptions): Prom
     content: ResolvedContent[];
 }>;
 /**
- * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. Missing local directories
- * are listed separately; an agent opened here is not told of them.
+ * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. An entry that cannot be
+ * resolved (a directory that is gone) refuses, naming it.
  */
-export declare function listContent(agentDir: string): Promise<{
+export declare function listContent(agentDir: string, scope?: ContentScope): Promise<{
     content: ResolvedContent[];
-    absent: BoundContent[];
 }>;
 /**
  * The edited declaration resolved for this machine; an already-open agent keeps its startup snapshot until reopened.
@@ -70,17 +74,30 @@ export interface ContentEdit {
     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}.
+ * Add a content entry to the agent in `agentDir`: to the instance configuration (`fastagent.json`, or the file
+ * `scope.config` names), or with `program` to the program's `context.json`. A name that cannot be one, or that the
+ * agent already has in either (ignoring case), is a {@link ContentNameError}.
  */
-export declare function addContent(agentDir: string, addition: ContentAddition): Promise<ContentEdit>;
+export declare function addContent(agentDir: string, addition: ContentAddition, scope?: ContentScope): 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
+ * Remove the agent's content entry named `name` (ignoring case), from whichever of `context.json` and the instance
+ * configuration holds it. 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>;
+export declare function removeContent(agentDir: string, name: string, scope?: ContentScope): Promise<ContentEdit>;
+/**
+ * Set what the instance configuration says of the channel `channel` (`channels.<channel>` in `fastagent.json` in
+ * `agentDir`, or the file `scope.config` names): `entry` over what it holds, the rest of the file kept as it is. Under
+ * the lock content edits take, since they write the same file.
+ */
+export declare function setChannelConfig(agentDir: string, channel: string, entry: {
+    ingress?: "webhook" | "connection";
+    app?: {
+        id: string;
+        team?: string;
+        url?: string;
+    };
+}, scope?: Pick<ContentScope, "config">): Promise<void>;
 /**
  * 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.

package/dist/authoring.js

@@ -7,16 +7,15 @@
  */
 import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { dirname, isAbsolute, 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 { CONTEXT_FILE, INSTANCE_CONFIG_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 { canonicalEntry, declareContent, isContentName, joinContent, } from "./content/declare.js";
+import { contextFileText, loadContent, parseContextFile } from "./content/file.js";
+import { checkDirectory, resolveContent } from "./content/resolve.js";
 import { withLockedFile } from "./locked-file.js";
-/** `context.json` is part of the definition, read by whoever reads the agent. */
+/** `context.json` and `fastagent.json` are part of an agent's text: 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
@@ -25,13 +24,24 @@ const CONTEXT_FILE_MODE = 0o644;
 export class ContentNameError extends Error {
     name = "ContentNameError";
 }
+const placesOf = (dir, scope = {}) => {
+    const config = scope.config ?? join(dir, INSTANCE_CONFIG_FILE);
+    for (const [name, path] of [
+        ["config", scope.config],
+        ["workdir", scope.workdir],
+    ]) {
+        if (path !== undefined && !isAbsolute(path))
+            throw new Error(`${name} must be an absolute path, and is "${path}"`);
+    }
+    return { dir, workdir: scope.workdir ?? dir, config };
+};
 /**
  * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
  * repository whose first commit is what was written, since the agent changes itself and version control is how its
  * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
  *
  * `content` gives it any number of entries, each a directory of this machine or a GitHub repository. They are all
- * checked before anything is written, and one that is refused leaves no directory. Two entries may bind the same
+ * checked before anything is written, and one that is refused leaves no directory. Two entries may be the same
  * directory, or one inside the other; the agent then reaches it by both names.
  */
 export async function createAgent(dir, options = {}) {
@@ -43,25 +53,25 @@ export async function createAgent(dir, options = {}) {
  */
 export async function initAgent(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 places = placesOf(agentDir);
+    let maps = { program: {}, instance: {} };
+    for (const addition of options.content ?? [])
+        maps = withAddition(places, 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 rm(join(agentDir, INSTANCE_CONFIG_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.program).length > 0) {
+            writeFileAtomic(join(agentDir, CONTEXT_FILE), contextFileText({ content: maps.program }), CONTEXT_FILE_MODE);
         }
-        if (Object.keys(maps.bindings).length > 0) {
-            writeFileAtomic(join(agentDir, LOCAL_CONTEXT_FILE), localContextFileText(maps.bindings), CONTEXT_FILE_MODE);
+        if (Object.keys(maps.instance).length > 0) {
+            writeFileAtomic(places.config, instanceFileText({}, maps.instance), CONTEXT_FILE_MODE);
         }
     }
     catch (error) {
@@ -69,166 +79,176 @@ export async function initAgent(dir, options = {}) {
     }
     if (options.install)
         await options.install(agentDir).catch(removeAll);
-    const content = resolveContent(agentDir, declarationOf(agentDir, maps));
+    const content = resolveContent(declarationOf(places, maps), places);
     return { dir: agentDir, created, content, repository: await initRepository(agentDir) };
 }
 /**
- * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. Missing local directories
- * are listed separately; an agent opened here is not told of them.
+ * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. An entry that cannot be
+ * resolved (a directory that is gone) refuses, naming it.
  */
-export async function listContent(agentDir) {
-    const dir = resolveAgentDir(agentDir);
-    const declaration = loadContent(dir);
-    return { content: resolveContent(dir, declaration), absent: contentAbsentHere(declaration) };
+export async function listContent(agentDir, scope) {
+    const places = placesOf(resolveAgentDir(agentDir), scope);
+    return { content: resolveContent(loadContent(places.dir, instanceSourceOf(places)), places) };
 }
 /**
- * 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}.
+ * Add a content entry to the agent in `agentDir`: to the instance configuration (`fastagent.json`, or the file
+ * `scope.config` names), or with `program` to the program's `context.json`. A name that cannot be one, or that the
+ * agent already has in either (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) } : {}),
-        };
+export async function addContent(agentDir, addition, scope) {
+    const places = placesOf(resolveAgentDir(agentDir), scope);
+    const declaration = await editContent(places, (maps) => {
+        const next = withAddition(places, maps, addition).maps;
+        return { result: declarationOf(places, next), next };
     });
-    const notes = addition.binding !== undefined ? unignoredLocalFile(dir) : [];
-    return { name: addition.name, content: resolveContent(dir, declaration), notes };
+    return { name: addition.name, content: resolveContent(declaration, places), 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
+ * Remove the agent's content entry named `name` (ignoring case), from whichever of `context.json` and the instance
+ * configuration holds it. 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) } : {}),
+export async function removeContent(agentDir, name, scope) {
+    const places = placesOf(resolveAgentDir(agentDir), scope);
+    const { removed, wasClone, declaration } = await editContent(places, (maps) => {
+        const found = entryNamed(maps, name);
+        const next = {
+            program: without(maps.program, found),
+            instance: without(maps.instance, found),
         };
+        const declaration = declarationOf(places, next);
+        // What is left is resolved before it is written, so an entry that cannot 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(declaration, places);
+        const was = declarationOf(places, maps).find((entry) => entry.name === found);
+        return { result: { removed: found, wasClone: was?.kind === "github", declaration }, next };
     });
     const notes = [];
-    if (wasDeclared && lstatSync(contentEntryPath(dir, removed), { throwIfNoEntry: false })) {
+    if (wasClone && lstatSync(contentEntryPath(places.workdir, 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 };
+    return { name: removed, content: resolveContent(declaration, places), 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
+ * directory can be the content, 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`);
+function withAddition(places, maps, addition) {
+    const { name, entry, program } = addition;
     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());
+    const taken = [...Object.keys(maps.program), ...Object.keys(maps.instance)].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`);
+    if (program === true && !("github" in entry)) {
+        throw new Error(`content "${name}": ${CONTEXT_FILE} is shared, so it declares only repositories every instance reaches`);
+    }
+    const written = { ...(program === true ? maps.program : maps.instance), [name]: canonicalEntry(entry) };
+    const next = program === true ? { ...maps, program: written } : { ...maps, instance: written };
+    const declaration = declarationOf(places, next);
+    const declared = declaration.find((d) => d.name === name);
+    if (declared.kind === "github") {
+        if (lstatSync(contentEntryPath(places.workdir, name), { throwIfNoEntry: false })) {
+            throw new Error(`content/${name} already exists in ${places.workdir}: 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);
+        checkDirectory(places, name, declared.path);
     }
-    resolveContent(agentDir, declaration);
+    resolveContent(declaration, places);
     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 declarationOf(places, maps) {
+    return joinContent(declareContent(maps.program, { origin: "program", file: CONTEXT_FILE }), declareContent(maps.instance, { origin: "instance", file: places.config, base: dirname(places.config) }));
 }
 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}.
- */
+/** Where the entry `name` matches ignoring case is written: its name. 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;
+    const names = [...Object.keys(maps.program), ...Object.keys(maps.instance)];
+    const found = names.find((key) => key.toLowerCase() === name.toLowerCase());
     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"})`);
+        return found;
+    throw new ContentNameError(`no content named "${name}" (this agent has: ${[...new Set(names)].join(", ") || "none"})`);
+}
+/** The instance configuration's content, as `loadContent` reads it: from the file, or none when there is none. */
+function instanceSourceOf(places) {
+    const text = textIfExists(places.config);
+    if (text === undefined)
+        return undefined;
+    return { values: parseInstanceFile(text, places.config), label: places.config, directory: dirname(places.config) };
+}
+/** `text`, the contents of the instance configuration at `path`, as the object it is. */
+function parseInstanceFile(text, path) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${path} must hold a JSON object`);
+    return raw;
+}
+/** The instance configuration as written: `file` as it is, with `content` replaced (left out when empty). */
+function instanceFileText(file, content) {
+    const { content: _replaced, ...rest } = file;
+    return `${JSON.stringify(Object.keys(content).length > 0 ? { ...rest, content } : rest, null, 2)}\n`;
 }
 /**
- * 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.
+ * Run `edit` over both files that hold content under ONE lock, `context.json`'s, which env edits take too: whether a
+ * name is taken is asked of both, so two edits that write different files must still queue behind each other. The lock
+ * creates neither file; what `edit` returns is written under it, the instance configuration first. A file that holds
+ * the same content as before is not rewritten.
  */
-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 });
+async function editContent(places, edit) {
+    const programPath = join(places.dir, CONTEXT_FILE);
+    return withLockedFile(programPath, async (programText) => {
+        const program = programText === undefined ? { content: {}, declared: [] } : parseContextFile(programText, programPath);
+        const instanceText = textIfExists(places.config);
+        const instance = instanceText === undefined ? {} : parseInstanceFile(instanceText, places.config);
+        const maps = {
+            program: program.content,
+            instance: (instance.content ?? {}),
+        };
+        const out = edit(maps);
+        if (!sameEntries(out.next.instance, maps.instance)) {
+            writeFileAtomic(places.config, instanceFileText(instance, out.next.instance), fileMode(places.config));
+        }
+        return {
+            result: out.result,
+            ...(sameEntries(out.next.program, maps.program)
+                ? {}
+                : { next: contextFileText({ ...program, content: out.next.program }) }),
+        };
+    }, { mode: fileMode(programPath), create: false });
 }
+const sameEntries = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 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.
+ * Set what the instance configuration says of the channel `channel` (`channels.<channel>` in `fastagent.json` in
+ * `agentDir`, or the file `scope.config` names): `entry` over what it holds, the rest of the file kept as it is. Under
+ * the lock content edits take, since they write the same file.
  */
-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`];
+export async function setChannelConfig(agentDir, channel, entry, scope) {
+    const places = placesOf(resolveAgentDir(agentDir), scope);
+    const programPath = join(places.dir, CONTEXT_FILE);
+    await withLockedFile(programPath, async () => {
+        const text = textIfExists(places.config);
+        const file = text === undefined ? {} : parseInstanceFile(text, places.config);
+        const channels = (file.channels ?? {});
+        const next = { ...file, channels: { ...channels, [channel]: { ...channels[channel], ...entry } } };
+        writeFileAtomic(places.config, `${JSON.stringify(next, null, 2)}\n`, fileMode(places.config));
+        return { result: undefined };
+    }, { mode: fileMode(programPath), create: false });
 }
 /**
  * Replace the environment `context.json` declares with what `change` makes of it as it is now, under the lock content

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

@@ -13,7 +13,9 @@ export declare const ENVELOPE_KINDS: readonly ["webhook", "schedule-fire", "wake
  *
  * WHAT IT ACTUALLY GUARDS, in one line: only the forwarder may tell the container where the forwarder is. That URL
  * (`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.
+ * principal who could set it would redirect that callback and collect the secret along with every pending wake-up. It
+ * is also where the container points its webhook channels (their platform's credentials sent to the platform, and a
+ * URL the platform would then deliver every message to).
  *
  * 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,
@@ -40,6 +42,7 @@ export interface CarriedRequest {
 export type AgentcoreEnvelope = {
     /** Shared secret proving this envelope came from the forwarder (FASTAGENT_INGRESS_SECRET). */
     auth?: string;
+    /** Where the forwarder is: the wake-alarm callback, and where the platforms reach the webhook channels. */
     wake?: {
         url: string;
     };
@@ -64,8 +67,10 @@ 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 deployed definition (`login --deployment` needs one) and does not construct the channels.
+ * EVERY forwarder topology — schedule-only URLs refuse ordinary public traffic). It answers `{ ok, webhooks }`: the
+ * outcome of each webhook channel the container points itself, `pending` until it ends. Also accepted from the IAM
+ * door, where it only opens the deployed definition (`login --deployment` needs one) and does not construct the
+ * channels.
  */
  | {
     kind: "probe";

package/dist/channels/agentcore-protocol.js

@@ -15,7 +15,9 @@ export const ENVELOPE_KINDS = ["webhook", "schedule-fire", "wake-poke", "probe"]
  *
  * WHAT IT ACTUALLY GUARDS, in one line: only the forwarder may tell the container where the forwarder is. That URL
  * (`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.
+ * principal who could set it would redirect that callback and collect the secret along with every pending wake-up. It
+ * is also where the container points its webhook channels (their platform's credentials sent to the platform, and a
+ * URL the platform would then deliver every message to).
  *
  * 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,

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

@@ -24,4 +24,5 @@ export declare function mountAgentcore(options: {
     onStateReady?: () => void;
     /** The channel surface, initialized once by the adapter on trusted ingress. */
     channels: AgentcoreAdapterOptions["channels"];
+    webhooks?: AgentcoreAdapterOptions["webhooks"];
 }): Routes;