@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/mcp/config.js

@@ -1,11 +1,16 @@
-/** The sole MCP declaration: .mcp.json in the agent directory, resolved against this instance's environment. */
+/**
+ * The MCP servers an instance opens (agent-artifact.md §3.3, §4.2): the program's, the `mcpServers` map of its
+ * `context.json`, and what the instance adds, the `mcpServers` map of its `fastagent.json`. One list, read once, that
+ * every reader (the open, `inspectMcp`, sign-in, the secrets list, the build's warning) is given.
+ */
 import { readFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import * as Schema from "effect/Schema";
 import * as SchemaIssue from "effect/SchemaIssue";
+import { readProgramMcpServers } from "../content/file.js";
 import { isEnvName } from "../declared-secrets.js";
 import { McpError } from "../mcp-api.js";
-export const MCP_FILE = ".mcp.json";
+import { CONTEXT_FILE } from "../paths.js";
 const Strings = Schema.Record(Schema.String, Schema.String);
 const Stdio = Schema.Struct({
     type: Schema.optional(Schema.Literal("stdio")),
@@ -18,21 +23,15 @@ const Http = Schema.Struct({
     url: Schema.String,
     headers: Schema.optional(Strings),
 });
-const Configuration = Schema.Struct({ mcpServers: Schema.Record(Schema.String, Schema.Union([Stdio, Http])) });
-export function readMcpConfiguration(dir) {
-    const file = join(dir, MCP_FILE);
-    let text;
+const Declaration = Schema.Union([Stdio, Http]);
+const Servers = Schema.Record(Schema.String, Declaration);
+/** The `mcpServers` map `raw` holds (undefined is none), checked; every refusal names `file` and, where it can, the server. */
+function declareServers(raw, file) {
+    if (raw === undefined)
+        return {};
+    let servers;
     try {
-        text = readFileSync(file, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return { mcpServers: {} };
-        throw error;
-    }
-    let config;
-    try {
-        config = Schema.decodeUnknownSync(Schema.fromJsonString(Configuration))(text, { onExcessProperty: "error" });
+        servers = Schema.decodeUnknownSync(Servers)(raw, { onExcessProperty: "error" });
     }
     catch (error) {
         const paths = error instanceof Error && SchemaIssue.isIssue(error.cause)
@@ -40,43 +39,133 @@ export function readMcpConfiguration(dir) {
             : [];
         throw new McpError("configuration", `${file}: invalid MCP configuration at ${JSON.stringify(paths)}; expected stdio command/args/env or http url/headers; unknown fields are refused`);
     }
-    for (const [name, server] of Object.entries(config.mcpServers)) {
+    for (const [name, server] of Object.entries(servers)) {
         if (!/^[a-zA-Z0-9_-]+$/.test(name) || name.includes("__") || name.length > 40) {
             throw new McpError("configuration", `${file}: server names must be 1–40 letters, digits, hyphens or underscores, without __`);
         }
         if (server.type === "http")
-            checkMcpUrl(server.url, name);
+            checkMcpUrl(server.url, name, file);
         else
             for (const key of Object.keys(server.env ?? {})) {
                 if (!isEnvName(key))
                     throw new McpError("configuration", `${file}: invalid environment variable name for ${name}`, name);
             }
         for (const value of configStrings(server))
-            variables(value, name);
+            variables(value, name, file);
+    }
+    return servers;
+}
+/** An instance's servers, checked: what `resolveConfig` asks of a configuration, so its refusal is the file's. */
+export function checkInstanceServers(instance) {
+    declareServers(mapOf(instance.values), instance.label);
+}
+const mapOf = (values) => typeof values === "object" && values !== null ? values.mcpServers : undefined;
+/**
+ * The servers of the program in `dir` and of `instance`. An instance only adds: a name both declare is refused, naming
+ * both, so nothing is shadowed.
+ */
+export function declareMcp(dir, instance) {
+    const own = readProgramMcpServers(dir);
+    const program = Object.entries(declareServers(own.values, own.path)).map(([name, server]) => ({ name, server, file: CONTEXT_FILE, base: resolve(dir), origin: "program" }));
+    if (instance === undefined)
+        return program;
+    const added = Object.entries(declareServers(mapOf(instance.values), instance.label)).map(([name, server]) => ({
+        name,
+        server,
+        file: instance.label,
+        ...(instance.directory === undefined ? {} : { base: instance.directory }),
+        origin: "instance",
+    }));
+    for (const { name } of added) {
+        if (program.some((declared) => declared.name === name)) {
+            throw new McpError("configuration", `MCP server "${name}" is declared by the program (${CONTEXT_FILE}) and by the instance (${instance.label}): an ` +
+                `instance adds to the program's servers and does not replace them — name it otherwise`);
+        }
+    }
+    return [...program, ...added];
+}
+/** An instance configuration given to `inspectMcp` or `signInMcp`: an object, or the absolute path of a `fastagent.json`. */
+export function mcpInstance(config) {
+    if (config === undefined)
+        return undefined;
+    if (typeof config !== "string")
+        return { values: config, label: "the config object" };
+    if (!isAbsolute(config))
+        throw new McpError("configuration", `config must be an absolute path, and is ${JSON.stringify(config)}`);
+    let text;
+    try {
+        text = readFileSync(config, "utf8");
+    }
+    catch (error) {
+        throw new McpError("configuration", `cannot read the instance configuration ${config}: ${error.message}`);
+    }
+    try {
+        return { values: JSON.parse(text), label: config, directory: dirname(config) };
+    }
+    catch (error) {
+        throw new McpError("configuration", `${config} is not JSON: ${error.message}`);
     }
-    return config;
 }
 function configStrings(server) {
     return server.type === "http"
         ? Object.values(server.headers ?? {})
         : [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {})];
 }
-function variables(value, server) {
+function variables(value, server, file) {
     const names = [];
     const rest = value.replace(/\$\{([^}]*)\}/g, (_match, name) => {
         if (!isEnvName(name))
-            throw new McpError("configuration", `${MCP_FILE}: ${server} supports only \${NAME} substitutions`, server);
+            throw new McpError("configuration", `${file}: ${server} supports only \${NAME} substitutions`, server);
         names.push(name);
         return "";
     });
     if (rest.includes("${") || rest.includes("$("))
-        throw new McpError("configuration", `${MCP_FILE}: unsupported substitution in ${server}`, server);
+        throw new McpError("configuration", `${file}: unsupported substitution in ${server}`, server);
     return names;
 }
-export function mcpSecrets(dir) {
-    return Object.entries(readMcpConfiguration(dir).mcpServers).flatMap(([server, config]) => configStrings(config).flatMap((value) => variables(value, server).map((name) => ({ name, source: `${MCP_FILE} mcpServers.${server}` }))));
+/** The secrets the servers' `${NAME}` references need: each required, declared where the server is. */
+export function mcpSecrets(declarations) {
+    return declarations.flatMap(({ name, server, file }) => configStrings(server).flatMap((value) => variables(value, name, file).map((secret) => ({
+        name: secret,
+        declaredIn: `${file} mcpServers.${name}`,
+        optional: false,
+    }))));
+}
+/**
+ * The header and environment values with no `${VAR}` in them: the format allows a literal credential, and where the
+ * file travels (a build publishes it, a deploy bakes or delivers it) each is said. FastAgent cannot tell a secret from a
+ * setting, so a caller warns and never refuses.
+ */
+export function literalCredentials(declarations) {
+    return declarations.flatMap(({ name, server, file }) => {
+        const [field, entries] = server.type === "http" ? ["headers", server.headers ?? {}] : ["env", server.env ?? {}];
+        return Object.entries(entries)
+            .filter(([, value]) => value !== "" && !value.includes("${"))
+            .map(([key]) => ({ file, server: name, field, key }));
+    });
 }
-export function checkMcpUrl(value, server) {
+/**
+ * The stdio servers whose command is a path relative to the file that declares it, as it is written: what a build or a
+ * deploy has to be able to deliver, since a script is not found on a `PATH`. A command that starts with a `${VAR}` is
+ * left to the variable, and `args` are never read as paths, since FastAgent cannot know which strings are.
+ */
+export function relativeCommands(declarations) {
+    return declarations.flatMap((declaration) => {
+        const { server } = declaration;
+        const command = server.type === "http" ? undefined : server.command;
+        return command !== undefined && /[/\\]/.test(command) && !isAbsolute(command) && !command.startsWith("${")
+            ? [{ ...declaration, command }]
+            : [];
+    });
+}
+/** What to write instead of a literal credential, which a header's value usually carries a scheme in front of. */
+export function literalCredentialAdvice({ field, key }) {
+    const name = key.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+    return field === "headers"
+        ? `replace the secret in it with \${${name}} (a scheme stays: \`Bearer \${${name}}\`)`
+        : `write \${${name}}`;
+}
+export function checkMcpUrl(value, server, file = "mcpServers") {
     const url = URL.parse(value);
     if (!url ||
         value.includes("${") ||
@@ -86,32 +175,22 @@ export function checkMcpUrl(value, server) {
         url.hash ||
         (url.protocol !== "https:" &&
             !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) {
-        throw new McpError("configuration", `${MCP_FILE}: MCP endpoints require HTTPS (HTTP is allowed only on loopback), without userinfo or fragments`, server);
+        throw new McpError("configuration", `${file}: MCP endpoints require HTTPS (HTTP is allowed only on loopback), without userinfo or fragments`, server);
     }
     return url;
 }
-// These are execution necessities, not the other models' or servers' credentials.
-const INHERITED = [
-    "PATH",
-    "HOME",
-    "USERPROFILE",
-    "SystemRoot",
-    "SYSTEMROOT",
-    "TEMP",
-    "TMP",
-    "TMPDIR",
-    "LANG",
-    "LC_ALL",
-];
-export function resolveMcpServers(dir, env, only) {
-    const config = readMcpConfiguration(dir);
-    return Object.entries(config.mcpServers)
-        .filter(([name]) => only === undefined || name === only)
-        .map(([name, server]) => {
+export function resolveMcpServers(declarations, env, only, 
+/** Where a stdio server runs: the instance's workspace, whoever declared it. */
+cwd, 
+/** What every process the instance starts gets (child-env.ts), under a stdio server's own `env`. */
+processEnv) {
+    return declarations
+        .filter(({ name }) => only === undefined || name === only)
+        .map(({ name, server, file, base }) => {
         const expand = (value) => value.replace(/\$\{([^}]*)\}/g, (_match, key) => {
             const result = env[key];
             if (!result)
-                throw new McpError("configuration", `${MCP_FILE}: ${name} requires ${key}`, name);
+                throw new McpError("configuration", `${file}: ${name} requires ${key}`, name);
             return result;
         });
         if (server.type === "http") {
@@ -120,21 +199,25 @@ export function resolveMcpServers(dir, env, only) {
                 new Headers(headers);
             }
             catch {
-                throw new McpError("configuration", `${MCP_FILE}: invalid HTTP headers for ${name}`, name);
+                throw new McpError("configuration", `${file}: invalid HTTP headers for ${name}`, name);
             }
-            return { name, type: "http", url: checkMcpUrl(server.url, name).href, headers };
+            return { name, type: "http", url: checkMcpUrl(server.url, name, file).href, headers };
         }
         let command = expand(server.command);
-        if (!isAbsolute(command) && /[/\\]/.test(command))
-            command = resolve(dir, command);
+        if (!isAbsolute(command) && /[/\\]/.test(command)) {
+            if (base === undefined) {
+                throw new McpError("configuration", `${file}: the command "${command}" has a path and no file to be relative to: write an absolute path or a bare command`, name);
+            }
+            command = resolve(base, command);
+        }
         return {
             name,
             type: "stdio",
             command,
             args: (server.args ?? []).map(expand),
-            cwd: resolve(dir),
+            cwd: resolve(cwd),
             env: {
-                ...Object.fromEntries(INHERITED.flatMap((key) => (env[key] === undefined ? [] : [[key, env[key]]]))),
+                ...processEnv,
                 ...Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(value)])),
             },
         };

package/dist/mcp/host.d.ts

@@ -1,6 +1,9 @@
-import { type McpAuthorization, type McpOptions, type McpServerSummary } from "../mcp-api.ts";
+import { type McpAuthorization, type McpInspectOptions, type McpOptions, type McpServerSummary } from "../mcp-api.ts";
 import { type McpServer } from "./config.ts";
+/** The project's `.secrets/`: where the CLI keeps them. A write first makes the directory ignored by git. */
 export declare function mcpAuthorization(dir: string, env: NodeJS.ProcessEnv, stateRoot: string, options?: McpOptions): McpAuthorization;
+/** The instance's state directory: where an app that is given no store keeps them, beside its other state. */
+export declare function mcpAuthorizationInState(stateRoot: string, options?: McpOptions): McpAuthorization;
 export declare function writeMcpBinding(stateRoot: string, server: string, id: string | undefined): Promise<void>;
 export declare function mcpContext(dir: string, options?: McpOptions): {
     agentDir: string;
@@ -13,4 +16,4 @@ export declare function mcpContext(dir: string, options?: McpOptions): {
 export declare function httpServer(servers: readonly McpServer[], name: string): Extract<McpServer, {
     type: "http";
 }>;
-export declare function inspectMcp(dir: string, options?: McpOptions): Promise<McpServerSummary[]>;
+export declare function inspectMcp(dir: string, options?: McpInspectOptions): Promise<McpServerSummary[]>;

package/dist/mcp/host.js

@@ -2,13 +2,13 @@
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import * as Schema from "effect/Schema";
-import { McpError } from "../mcp-api.js";
+import { McpError, } from "../mcp-api.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
 import { agentValues, prepareSecretsDirectory, unprotectedSecretsNote } from "../value-file.js";
 import { log } from "../log.js";
 import { withLockedFile } from "../locked-file.js";
 import { checkedGrant, mcpGrantFile } from "./grants.js";
-import { readMcpConfiguration, checkMcpUrl } from "./config.js";
+import { checkMcpUrl, declareMcp, mcpInstance } from "./config.js";
 const Bindings = Schema.Record(Schema.String, Schema.String);
 function decodeBindings(raw) {
     if (raw === undefined)
@@ -20,7 +20,16 @@ function decodeBindings(raw) {
         throw new McpError("storage", "Invalid MCP bindings file; refusing to overwrite it");
     }
 }
+/** The project's `.secrets/`: where the CLI keeps them. A write first makes the directory ignored by git. */
 export function mcpAuthorization(dir, env, stateRoot, options = {}) {
+    const secretsDir = resolveSecretsDir(dir, env);
+    return authorizationIn({ file: join(secretsDir, "mcp-auth.json"), prepare: () => prepareSecretsDirectory(dir, secretsDir) }, stateRoot, options);
+}
+/** The instance's state directory: where an app that is given no store keeps them, beside its other state. */
+export function mcpAuthorizationInState(stateRoot, options = {}) {
+    return authorizationIn({ file: join(stateRoot, "mcp-auth.json") }, stateRoot, options);
+}
+function authorizationIn(home, stateRoot, options) {
     if ((options.store === undefined) !== (options.bindings === undefined))
         throw new McpError("configuration", "MCP store and bindings must be supplied together");
     if (options.store && options.bindings)
@@ -34,10 +43,9 @@ export function mcpAuthorization(dir, env, stateRoot, options = {}) {
         if (error.code !== "ENOENT")
             throw error;
     }
-    const secretsDir = resolveSecretsDir(dir, env);
-    const file = mcpGrantFile(join(secretsDir, "mcp-auth.json"));
+    const file = mcpGrantFile(home.file);
     const protectedWrite = async (write) => {
-        const unprotected = await prepareSecretsDirectory(dir, secretsDir);
+        const unprotected = await home.prepare?.();
         await write();
         if (unprotected !== undefined)
             log.warn(`[fastagent] ${unprotectedSecretsNote(unprotected)}`);
@@ -85,7 +93,7 @@ export function httpServer(servers, name) {
 }
 export async function inspectMcp(dir, options = {}) {
     const { agentDir, auth } = mcpContext(dir, options);
-    return Promise.all(Object.entries(readMcpConfiguration(agentDir).mcpServers).map(async ([name, declaration]) => {
+    return Promise.all(declareMcp(agentDir, mcpInstance(options.config)).map(async ({ name, server: declaration }) => {
         const server = { ...declaration, name, type: declaration.type ?? "stdio" };
         const id = Object.hasOwn(auth.bindings, server.name) ? auth.bindings[server.name] : undefined;
         const raw = id === undefined ? undefined : await auth.store.read(id);

package/dist/mcp/sign-in.js

@@ -3,7 +3,7 @@ import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { resolve } from "node:path";
 import { agentValues } from "../value-file.js";
-import { resolveMcpServers } from "./config.js";
+import { declareMcp, mcpInstance, resolveMcpServers } from "./config.js";
 import { registerClient, startAuthorization, exchangeAuthorization, selectClientAuthMethod, validateAuthorizationResponseIssuer, } from "@modelcontextprotocol/client";
 import * as Effect from "effect/Effect";
 import * as Deferred from "effect/Deferred";
@@ -24,7 +24,7 @@ export async function signInMcp(request) {
         throw new McpError("configuration", "Invalid MCP sign-in timeout or callback port", request.server);
     }
     const dir = resolve(request.agentDir);
-    const server = httpServer(resolveMcpServers(dir, { ...process.env, ...agentValues(dir), ...request.variables }, request.server), request.server);
+    const server = httpServer(resolveMcpServers(declareMcp(dir, mcpInstance(request.config)), { ...process.env, ...agentValues(dir), ...request.variables }, request.server, dir, {}), request.server);
     let saved;
     const work = Effect.gen(function* () {
         const network = yield* Effect.acquireRelease(port(() => openMcpNetwork(server.url, request.fetch)), (value) => portCleanup("MCP network", () => value.close()));

package/dist/mcp-api.d.ts

@@ -54,6 +54,18 @@ export interface McpOptions {
     /** Trusted transport override: the host must enforce connection-level DNS/IP and redirect safety itself. */
     fetch?: typeof globalThis.fetch;
 }
+/**
+ * The instance configuration as far as MCP reads it: an object, or the absolute path of a `fastagent.json`. Its
+ * `mcpServers` add to the program's (`context.json`), and a name in both refuses.
+ */
+export type McpConfigInput = {
+    mcpServers?: Readonly<Record<string, unknown>>;
+    [key: string]: unknown;
+} | string;
+/** What `inspectMcp` is given beside the grants: the instance configuration whose servers it reads with the program's. */
+export interface McpInspectOptions extends McpOptions {
+    config?: McpConfigInput;
+}
 export interface McpServerSummary {
     name: string;
     transport: "stdio" | "http";
@@ -90,4 +102,6 @@ export interface McpSignInRequest {
     timeoutSeconds?: number;
     variables?: Readonly<Record<string, string>>;
     fetch?: McpOptions["fetch"];
+    /** The instance configuration whose servers are read with the program's. */
+    config?: McpConfigInput;
 }

package/dist/paths.d.ts

@@ -14,20 +14,20 @@ export declare function selectAgentEnvironment(environment: AgentEnvironment, en
 /** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
 export declare const STATE_DIRNAME = ".state";
 /**
- * Where fastagent clones the repositories `context.json` declares, `content/<name>` in the agent dir. Never an env
- * override: a machine that has a checkout of its own binds it in {@link LOCAL_CONTEXT_FILE} instead.
+ * Where fastagent clones the repositories an agent's content declares, `content/<name>` in the instance's working
+ * directory. Never an env override: a machine that has a checkout of its own adds it as a directory instead.
  */
 export declare const CONTENT_DIRNAME = "content";
 /** The agent's context declaration (`context.json`), beside its config: shared, so only what every instance reaches. */
 export declare const CONTEXT_FILE = "context.json";
-/** The directories of THIS machine the agent is bound to: never committed, never deployed. */
-export declare const LOCAL_CONTEXT_FILE = "context.local.json";
 /**
  * THE config filename. One spelling, not a family: fastagent generates this file, so a choice of extension buys
  * an author nothing and costs a precedence order plus a "you have two of them" failure path. Everything else an
  * author writes (`tools/`, `channels/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
  */
 export declare const AGENT_CONFIG_FILE = "fastagent.config.ts";
+/** The instance configuration a development project holds beside its `fastagent.config.ts`. */
+export declare const INSTANCE_CONFIG_FILE = "fastagent.json";
 /** The agent `dir` sits INSIDE (the nearest proper ancestor that IS an agent dir), or undefined. */
 export declare function enclosingAgentDir(dir: string): string | undefined;
 /**
@@ -50,10 +50,24 @@ export declare function readTextIfExists(p: string): Promise<string | undefined>
  */
 export declare function resolveOverridePath(raw: string | undefined): string | undefined;
 /**
- * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
- * Explicit paths win; production otherwise uses `.state/production`, dev uses `.state`.
+ * A path as an instance configuration writes it, absolute: `~/` is the home directory, a relative one is `base`'s (the
+ * configuration file's directory). Undefined for a relative one when there is no file to anchor it.
+ */
+export declare function configurationPath(path: string, base: string | undefined): string | undefined;
+/** Where an instance is, from the environment: the root, or its state and its workspace apart (agent-artifact.md §4.1). */
+export declare const INSTANCE_ROOT_ENV = "FASTAGENT_ROOT";
+export declare const INSTANCE_WORKDIR_ENV = "FASTAGENT_WORKDIR";
+export declare const INSTANCE_STATE_ENV = "FASTAGENT_STATE_DIR";
+export declare const INSTANCE_CONFIG_ENV = "FASTAGENT_CONFIG";
+/** Where fastagent keeps what it makes for a local instance of the project in `dir`, one directory per environment. */
+export declare const INSTANCES_DIRNAME = ".fastagent";
+/**
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/): the state
+ * directory, else `.state` in the instance root, which is the project's default one when none is given.
  */
 export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
+/** The agent's working directory: the workspace directory, else the instance root, which is the project's default one. */
+export declare function resolveWorkdir(dir: string, env?: NodeJS.ProcessEnv): string;
 /** Where fastagent clones the content entry `name` of the agent in `dir`. */
 export declare function contentEntryPath(dir: string, name: string): string;
 /**
@@ -63,9 +77,9 @@ export declare function contentEntryPath(dir: string, name: string): string;
 export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
 /** Is this process the deployed container the generated artifacts describe? ONE reading of the
  *  environment fact the image states, so a second spelling cannot drift from it. */
-export declare function isDeployedWorkspace(): boolean;
+export declare function isDeployedWorkspace(env?: NodeJS.ProcessEnv): boolean;
 /** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
-export declare function isAgentcoreRuntime(): boolean;
+export declare function isAgentcoreRuntime(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Which host this deployed box runs on, for the command that logs it in (`login --deployment <host>`). Read from what
  * each platform puts in a box's environment (`FLY_APP_NAME`, `RAILWAY_SERVICE_ID`) or what our AgentCore template

package/dist/paths.js

@@ -29,20 +29,20 @@ function environmentPath(dir, segment, env) {
 /** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
 export const STATE_DIRNAME = ".state";
 /**
- * Where fastagent clones the repositories `context.json` declares, `content/<name>` in the agent dir. Never an env
- * override: a machine that has a checkout of its own binds it in {@link LOCAL_CONTEXT_FILE} instead.
+ * Where fastagent clones the repositories an agent's content declares, `content/<name>` in the instance's working
+ * directory. Never an env override: a machine that has a checkout of its own adds it as a directory instead.
  */
 export const CONTENT_DIRNAME = "content";
 /** The agent's context declaration (`context.json`), beside its config: shared, so only what every instance reaches. */
 export const CONTEXT_FILE = "context.json";
-/** The directories of THIS machine the agent is bound to: never committed, never deployed. */
-export const LOCAL_CONTEXT_FILE = "context.local.json";
 /**
  * THE config filename. One spelling, not a family: fastagent generates this file, so a choice of extension buys
  * an author nothing and costs a precedence order plus a "you have two of them" failure path. Everything else an
  * author writes (`tools/`, `channels/`) still accepts `.ts`/`.js`/`.mjs` — that is THEIR code.
  */
 export const AGENT_CONFIG_FILE = "fastagent.config.ts";
+/** The instance configuration a development project holds beside its `fastagent.config.ts`. */
+export const INSTANCE_CONFIG_FILE = "fastagent.json";
 /**
  * "Not there" and "could not look" are different answers, and only the first may read as an absence: an agent
  * directory the caller cannot enter (EACCES) reported as no-agent-here ends in `run \`fastagent init\`` — over a
@@ -131,11 +131,44 @@ export function resolveOverridePath(raw) {
     return resolve(expanded);
 }
 /**
- * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/):
- * Explicit paths win; production otherwise uses `.state/production`, dev uses `.state`.
+ * A path as an instance configuration writes it, absolute: `~/` is the home directory, a relative one is `base`'s (the
+ * configuration file's directory). Undefined for a relative one when there is no file to anchor it.
+ */
+export function configurationPath(path, base) {
+    if (path === "~" || path.startsWith("~/"))
+        return join(homedir(), path.slice(1));
+    if (isAbsolute(path))
+        return resolve(path);
+    return base === undefined ? undefined : resolve(base, path);
+}
+/** Where an instance is, from the environment: the root, or its state and its workspace apart (agent-artifact.md §4.1). */
+export const INSTANCE_ROOT_ENV = "FASTAGENT_ROOT";
+export const INSTANCE_WORKDIR_ENV = "FASTAGENT_WORKDIR";
+export const INSTANCE_STATE_ENV = "FASTAGENT_STATE_DIR";
+export const INSTANCE_CONFIG_ENV = "FASTAGENT_CONFIG";
+/** Where fastagent keeps what it makes for a local instance of the project in `dir`, one directory per environment. */
+export const INSTANCES_DIRNAME = ".fastagent";
+/**
+ * The instance root of the project in `dir` when none is given (agent-artifact.md §4.1): `.fastagent/dev/` for `dev`,
+ * and `.fastagent/start/` for the commands that run what `start` runs, kept apart so a trial of the production build
+ * never reads or writes the development sessions and clones.
+ */
+function defaultInstanceRoot(dir, env) {
+    return join(resolve(dir), INSTANCES_DIRNAME, env[AGENT_ENVIRONMENT_ENV] === "production" ? "start" : "dev");
+}
+/**
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/): the state
+ * directory, else `.state` in the instance root, which is the project's default one when none is given.
  */
 export function resolveStateRoot(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? environmentPath(dir, STATE_DIRNAME, env);
+    return (resolveOverridePath(env[INSTANCE_STATE_ENV]) ??
+        join(resolveOverridePath(env[INSTANCE_ROOT_ENV]) ?? defaultInstanceRoot(dir, env), STATE_DIRNAME));
+}
+/** The agent's working directory: the workspace directory, else the instance root, which is the project's default one. */
+export function resolveWorkdir(dir, env = process.env) {
+    return (resolveOverridePath(env[INSTANCE_WORKDIR_ENV]) ??
+        resolveOverridePath(env[INSTANCE_ROOT_ENV]) ??
+        defaultInstanceRoot(dir, env));
 }
 /** Where fastagent clones the content entry `name` of the agent in `dir`. */
 export function contentEntryPath(dir, name) {
@@ -150,12 +183,12 @@ export function resolveSecretsDir(dir, env = process.env) {
 }
 /** Is this process the deployed container the generated artifacts describe? ONE reading of the
  *  environment fact the image states, so a second spelling cannot drift from it. */
-export function isDeployedWorkspace() {
-    return Boolean(process.env.FASTAGENT_RELEASE_FILE);
+export function isDeployedWorkspace(env = process.env) {
+    return Boolean(env.FASTAGENT_RELEASE_FILE);
 }
 /** Is this process running inside the AgentCore Runtime? Set by the generated deploy artifacts. */
-export function isAgentcoreRuntime() {
-    return process.env.FASTAGENT_AGENTCORE === "1";
+export function isAgentcoreRuntime(env = process.env) {
+    return env.FASTAGENT_AGENTCORE === "1";
 }
 /**
  * Which host this deployed box runs on, for the command that logs it in (`login --deployment <host>`). Read from what

package/dist/runtime-websocket.d.ts

@@ -0,0 +1,14 @@
+import * as undici from "undici";
+export declare const RuntimeWebSocket: {
+    new (url: string | URL, protocols?: string | string[] | undici.WebSocketInit): undici.WebSocket;
+    prototype: undici.WebSocket;
+    readonly CLOSED: number;
+    readonly CLOSING: number;
+    readonly CONNECTING: number;
+    readonly OPEN: number;
+};
+export type RuntimeWebSocket = InstanceType<typeof RuntimeWebSocket>;
+/** Send a ping on `socket`, or `undefined` when this runtime cannot. */
+export declare function pinger(socket: RuntimeWebSocket): (() => void) | undefined;
+/** Call `onPong` for each pong `socket` receives. Returns what stops it. */
+export declare function watchPongs(socket: RuntimeWebSocket, onPong: () => void): () => void;

package/dist/runtime-websocket.js

@@ -0,0 +1,39 @@
+/**
+ * The runtime's own WebSocket and the pings it can send, for the two places that hold a WebSocket open against a
+ * service that drops one nobody pings: Slack's Socket Mode and AgentCore's command shell.
+ *
+ * Node's undici sends a ping with `undici.ping` and reports the pong on a diagnostics channel; Bun 1.4.4 and later has
+ * both in its `undici` shim. Before that the shim has no `ping` and its WebSocket is the runtime's own, which pings with
+ * its `ping()` and reports a `pong` event. A runtime with neither has no pings: `pinger` says so, and the caller decides.
+ *
+ * A namespace import, because Bun's `undici` is a shim that leaves out what it does not have, and a named import of a
+ * missing export fails the whole module's link.
+ */
+import { channel } from "node:diagnostics_channel";
+import * as undici from "undici";
+export const RuntimeWebSocket = undici.WebSocket ?? globalThis.WebSocket;
+const undiciPings = undici.WebSocket !== undefined && typeof undici.ping === "function";
+const nativePing = (socket) => socket.ping;
+/** Send a ping on `socket`, or `undefined` when this runtime cannot. */
+export function pinger(socket) {
+    if (undiciPings)
+        return () => undici.ping(socket);
+    return typeof nativePing(socket) === "function" ? () => nativePing(socket)?.call(socket) : undefined;
+}
+/** Call `onPong` for each pong `socket` receives. Returns what stops it. */
+export function watchPongs(socket, onPong) {
+    if (undiciPings) {
+        const pongs = channel("undici:websocket:pong");
+        const listener = (message) => {
+            if (message.websocket === socket)
+                onPong();
+        };
+        pongs.subscribe(listener);
+        return () => pongs.unsubscribe(listener);
+    }
+    if (typeof nativePing(socket) !== "function")
+        return () => { };
+    const listener = () => onPong();
+    socket.addEventListener("pong", listener);
+    return () => socket.removeEventListener("pong", listener);
+}

package/dist/scaffold/add-channel.d.ts

@@ -1,34 +1,26 @@
-import { type ValueWriteResult } from "../value-file.ts";
-import { type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
 export type ChannelKind = "telegram" | "slack" | "feishu" | "lark";
 /** An env var a scaffolded channel reads. */
-export interface ChannelEnv {
+interface ChannelEnv {
     name: string;
     hint: string;
     /** Required for the channel to run. */
     required: boolean;
-    generate?: boolean;
 }
-/** The channel kinds `fastagent add <kind>` can scaffold. */
-export declare const CHANNEL_KINDS: ChannelKind[];
-/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
-export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscriptionMode, 
-/** Whether `<PREFIX>_INGRESS` is explicitly set in this environment. */
-pinned?: boolean): {
+interface ChannelScaffold {
     env: ChannelEnv[];
+    /** Channel instructions with paths and the serving command filled by the CLI. */
     steps: string[];
-};
+}
+/** The channel kinds `fastagent add <kind>` can scaffold. */
+export declare const CHANNEL_KINDS: ChannelKind[];
+/** The env vars and next-step lines a scaffolded channel has. */
+export declare function channelSetup(kind: ChannelKind): ChannelScaffold;
 /**
  * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who copies it to
  * `.env` finds the vars already there. Every var the channel can declare, whichever way this machine receives it:
  * the file is what a collaborator or CI fills for a deployment, which receives Feishu/Lark by webhook.
  */
 export declare function appendChannelEnv(dir: string, kind: ChannelKind): Promise<boolean>;
-/**
- * Append generated channel secrets to the selected environment's value file, and a placeholder for each the channel
- * reads that nothing generated. Existing non-empty values are kept.
- */
-export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[], ingress?: FeishuSubscriptionMode): Promise<ValueWriteResult>;
 /** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
 export declare function channelExists(dir: string, kind: ChannelKind): Promise<boolean>;
 /** Scaffold `src/channels/<kind>.ts` into {@link dir}. */
@@ -40,3 +32,4 @@ export declare function scaffoldCompanionTools(dir: string, kind: ChannelKind):
  * channel file imports it).
  */
 export declare function assertChannelReady(dir: string): Promise<void>;
+export {};