@fastagent-sh/fastagent 0.29.0 → 0.30.1

package/dist/harnesses/pi-durable/text.js

@@ -1,7 +1,8 @@
 /**
- * The definition's text (architecture.md §3), read for each request so an edit takes effect on the next answer:
- * `SYSTEM.md` and `AGENTS.md` as prompt sections, `skills/` as Agent Skills (agentskills.io) and `prompts/` as prompt
- * templates. A skill is loaded as pi does it: the prompt lists each one's name, description and location, the model
+ * The definition's text (architecture.md §3) and the instance's (agent-artifact.md §4.2), read for each request so an
+ * edit takes effect on the next answer: `SYSTEM.md` and `AGENTS.md` as prompt sections, `skills/` as Agent Skills
+ * (agentskills.io) and `prompts/` as prompt templates, each with the files and directories the instance adds
+ * (text-sources.ts). A skill is loaded as pi does it: the prompt lists each one's name, description and location, the model
  * reads its `SKILL.md` when a task matches, and `/skill:<name>` loads it into the message.
  */
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
@@ -9,7 +10,7 @@ import { basename, join } from "node:path";
 import { section } from "@earendil-works/pi-durable";
 import { parse as parseYaml } from "yaml";
 import { log } from "../../log.js";
-import { isAgentcoreRuntime, isDeployedWorkspace } from "../../paths.js";
+import { NOUN, declareText, programText, whatIs } from "./text-sources.js";
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 const SKILL_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /** A file's YAML frontmatter and its body. A file without frontmatter is all body. */
@@ -49,14 +50,37 @@ function directories(dir) {
         }
     });
 }
-/** The agent's skills: `skills/<name>/SKILL.md`. One that breaks the specification is reported and skipped. */
-export function readSkills(agentDir) {
-    const root = join(agentDir, "skills");
+/**
+ * Whether a source is there to read as `kind`: one an instance declared that has gone, or become what its kind is not,
+ * is reported, not read as empty.
+ */
+function present({ path, declaredBy }, kind) {
+    const found = whatIs(path);
+    if (found === NOUN[kind] || (found !== undefined && declaredBy === undefined))
+        return true;
+    if (declaredBy !== undefined) {
+        report(`${path}: ${declaredBy} declares it, and ${found === undefined ? "it is gone" : `it is a ${found} now`}`);
+    }
+    return false;
+}
+const collisionOf = (kind, name, taken, file, byInstance) => `${kind} "${name}" is declared by ${taken} and ${file}` +
+    (byInstance ? `: an instance adds to the program's ${kind}s and does not replace them — name it otherwise` : "");
+/** The skills in `sources`: `<dir>/<name>/SKILL.md`. One that breaks the specification is reported and skipped. */
+function loadSkills(sources, collide) {
     const skills = [];
+    for (const source of sources) {
+        if (present(source, "skills"))
+            readSkillsOf(source, skills, collide);
+    }
+    return skills;
+}
+/** The skills of one directory, added to `skills`. */
+function readSkillsOf(source, skills, collide) {
+    const root = source.path;
     for (const entry of directories(root)) {
         const baseDir = join(root, entry);
         const filePath = join(baseDir, "SKILL.md");
-        const label = `skills/${entry}/SKILL.md`;
+        const label = filePath;
         if (!existsSync(filePath))
             continue;
         let fields;
@@ -77,8 +101,10 @@ export function readSkills(agentDir) {
             report(`${label}: "description" must be a text of at most 1024 characters`);
             continue;
         }
-        if (skills.some((skill) => skill.name === name)) {
-            report(`${label}: another skill is named "${name}"`);
+        const taken = skills.find((skill) => skill.name === name);
+        if (taken !== undefined) {
+            const byInstance = source.declaredBy !== undefined;
+            collide(collisionOf("skill", name, taken.filePath, filePath, byInstance), byInstance);
             continue;
         }
         skills.push({
@@ -89,29 +115,53 @@ export function readSkills(agentDir) {
             disableModelInvocation: fields["disable-model-invocation"] === true,
         });
     }
-    return skills;
 }
-/** The agent's prompt templates: `prompts/<name>.md`, a `description` in the frontmatter and the body as the text. */
-function readTemplates(agentDir) {
-    const root = join(agentDir, "prompts");
-    if (!existsSync(root))
-        return [];
-    return readdirSync(root)
-        .sort()
-        .flatMap((entry) => {
-        if (!entry.endsWith(".md"))
-            return [];
-        const label = `prompts/${entry}`;
-        try {
-            const { fields, body } = frontmatter(readFileSync(join(root, entry), "utf8"), label);
-            const description = typeof fields.description === "string" ? fields.description : undefined;
-            return [{ name: entry.slice(0, -3), ...(description === undefined ? {} : { description }), body }];
-        }
-        catch (error) {
-            report(`${label}: ${error instanceof Error ? error.message : String(error)}`);
-            return [];
+/** The skills the agent offers, reported and skipped as above. */
+export const readSkills = (sources) => loadSkills(sources, report);
+/** The prompt templates in `sources`: `<dir>/<name>.md`, a `description` in the frontmatter and the body as the text. */
+function loadTemplates(sources, collide) {
+    const templates = [];
+    const files = new Map();
+    for (const source of sources) {
+        if (!present(source, "prompts"))
+            continue;
+        for (const entry of readdirSync(source.path).sort()) {
+            if (!entry.endsWith(".md"))
+                continue;
+            const file = join(source.path, entry);
+            const name = entry.slice(0, -3);
+            const taken = files.get(name);
+            if (taken !== undefined) {
+                const byInstance = source.declaredBy !== undefined;
+                collide(collisionOf("prompt template", name, taken, file, byInstance), byInstance);
+                continue;
+            }
+            try {
+                const { fields, body } = frontmatter(readFileSync(file, "utf8"), file);
+                const description = typeof fields.description === "string" ? fields.description : undefined;
+                templates.push({ name, ...(description === undefined ? {} : { description }), body });
+                files.set(name, file);
+            }
+            catch (error) {
+                report(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+            }
         }
-    });
+    }
+    return templates;
+}
+/**
+ * The instance's text as it will be read: declared, and refused when an instance entry takes a name the program (or an
+ * earlier instance entry) has. Called at open; what goes wrong afterwards is reported as each message reads it.
+ */
+export function openText(dir, instance) {
+    const text = declareText(dir, instance);
+    const refuse = (problem, byInstance) => {
+        if (byInstance)
+            throw new Error(`${instance?.label}: ${problem}`);
+    };
+    loadSkills(text.skills, refuse);
+    loadTemplates(text.prompts, refuse);
+    return text;
 }
 /** Arguments as a shell splits them: by whitespace, with `"…"` or `'…'` keeping one argument together. */
 export function parseArguments(text) {
@@ -170,14 +220,14 @@ function loadedSkill(skill, args) {
     return args.trim() === "" ? block : `${block}\n\n${args.trim()}`;
 }
 /** What a Caller may offer as `/<name>`: the prompt templates, then `skill:<name>` for each skill. */
-export function readCommands(agentDir) {
+export function readCommands(text) {
     return [
-        ...readTemplates(agentDir).map((template) => ({
+        ...loadTemplates(text.prompts, report).map((template) => ({
             name: template.name,
             ...(template.description === undefined ? {} : { description: template.description }),
             expand: (args) => expandTemplate(template.body, parseArguments(args)),
         })),
-        ...readSkills(agentDir).map((skill) => ({
+        ...readSkills(text.skills).map((skill) => ({
             name: `skill:${skill.name}`,
             description: skill.description,
             expand: (args) => loadedSkill(skill, args),
@@ -217,39 +267,44 @@ const fileText = (path) => {
     const text = readFileSync(path, "utf8").trim();
     return text === "" ? undefined : text;
 };
+/** The instance's files of instructions, in the order it declared them. */
+function instructionsText(sources) {
+    const texts = sources.filter((source) => present(source, "instructions")).flatMap(({ path }) => fileText(path) ?? []);
+    return texts.length === 0 ? undefined : texts.join("\n\n");
+}
 /**
  * The prompt the definition contributes: `SYSTEM.md` as written, `AGENTS.md` as project context, the skills, where it
- * works, and, deployed, what of a change it makes to itself lasts. `wake`: the agent has the wake tool.
+ * works, and, deployed, what of a change it makes to itself lasts. `wake`: the agent has the wake tool; `runsAs` says
+ * whether it is deployed, and where.
  */
 export function definitionSections(agentDir, content, options) {
+    const text = options.text ?? programText(agentDir);
     return [
         section("system", () => fileText(join(agentDir, "SYSTEM.md")), { tag: false }),
         section("project_context", () => fileText(join(agentDir, "AGENTS.md"))),
-        section("skills", () => skillsPrompt(readSkills(agentDir))),
-        section("content", () => contentSection({ agentDir, content })),
-        section("self_change", () => (isDeployedWorkspace() ? selfChangeSection(options.wake) : undefined)),
+        section("instance_context", () => instructionsText(text.instructions)),
+        section("skills", () => skillsPrompt(readSkills(text.skills))),
+        section("content", () => contentSection({ agentDir, workdir: options.workdir ?? agentDir, content })),
+        section("self_change", () => options.runsAs.deployed ? selfChangeSection(options.wake, options.runsAs.agentcore) : undefined),
     ];
 }
 /**
  * What takes effect when, and the agent's own path to a new capability, are the same on every host; how long the
  * storage lives is the host's answer: AgentCore's managed mount is reset by every deploy, so telling that agent to keep
- * work "outside the definition" would name a location its next deploy erases. The skill it writes lives in the
- * definition directory, which the next deployment replaces (or, on AgentCore, erases with everything else), so the
- * sentence says so, and where a skill that should outlast it has to go.
+ * work in its directory would name a location its next deploy erases; elsewhere the directory is the host's storage,
+ * which every deployment keeps. Its definition is the image's either way, so the sentence says where a capability that
+ * should outlast a deployment has to go.
  */
-function selfChangeSection(wake) {
-    const deployment = isAgentcoreRuntime()
-        ? "Every deployment of a new version resets this host's storage entirely"
-        : "Each deployment replaces your directory with the author's release";
-    return (`Your directory survives restarts, including uncommitted work; /tmp does not. ${deployment}, so anything that ` +
-        `must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database). ` +
-        `SYSTEM.md, AGENTS.md, skills/ and prompts/ are read for every message; changes to code in src/ (tools, ` +
-        `extensions, channels, schedules) or to configuration (fastagent.config.ts, context.json, package.json) take ` +
-        `effect when the service restarts. A tool you install yourself (apt-get, npm install -g) belongs to this machine ` +
-        `and is gone when its container is replaced. To give yourself a new capability now, write a skill — a SKILL.md in ` +
-        `your definition's skills/ directory, with any script it needs run through bash. It lasts until the next ` +
-        `deployment replaces that directory, so a capability that should outlast it belongs in the author's release: ` +
-        `propose it to them.` +
+function selfChangeSection(wake, agentcore) {
+    const storage = agentcore
+        ? "Every deployment of a new version resets this host's storage entirely, your directory with it, so anything " +
+            "that must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database)."
+        : "Your directory is this host's storage and survives deployments of a new version.";
+    return (`Your directory survives restarts, including uncommitted work; /tmp does not. ${storage} ` +
+        `Your definition (SYSTEM.md, AGENTS.md, skills/, prompts/, src/ and the configuration) is the author's release, ` +
+        `read as it was built from where it is installed: a copy of it you make in your directory is not read. A tool you install ` +
+        `yourself (apt-get, npm install -g) belongs to this machine and is gone when its container is replaced. A ` +
+        `capability that should outlast a deployment belongs in the author's release: propose it to them.` +
         // Named only when it has the tool: naming a tool the model does not have invites calls to it.
         (wake ? " To schedule your own follow-up work, use the wake tool." : ""));
 }
@@ -257,8 +312,6 @@ function selfChangeSection(wake) {
 function contentKind(c) {
     if (c.kind !== "github")
         return "a directory on this machine";
-    if (!c.clone)
-        return `a checkout of github ${c.repo} on this machine`;
     // Brought up to date in place at each start where git can do so without touching the agent's work; what the agent
     // changes stays, and reaches anyone else only when pushed. The declared ref is what it follows, not a claim about
     // where it is: a clone the agent moved elsewhere is left there.
@@ -270,9 +323,12 @@ function contentKind(c) {
  * with its location and where a change there goes. A result written where it does not last is how knowledge gets
  * lost, so the agent is told which is which.
  */
-function contentSection({ agentDir, content }) {
-    const own = `Your working directory, ${agentDir}, is your own directory: it holds your definition, and files you create ` +
-        `land there unless you put them elsewhere.`;
+function contentSection({ agentDir, workdir, content, }) {
+    const own = workdir === agentDir
+        ? `Your working directory, ${agentDir}, is your own directory: it holds your definition, and files you create ` +
+            `land there unless you put them elsewhere.`
+        : `Your working directory, ${workdir}, is your own directory: files you create land there unless you put them ` +
+            `elsewhere. Your definition is in ${agentDir}, which you read and do not change.`;
     if (content.length === 0)
         return `${own} Nothing else is declared for you: you work only in your own directory.`;
     const line = (c) => `- ${c.name}: ${c.location} (${contentKind(c)})${c.description !== undefined ? ` ${c.description}` : ""}`;

package/dist/harnesses/pi-durable/wake.js

@@ -3,7 +3,7 @@
  * the instance's state (schedule/wakeups.ts), which the scheduler fires. A pair over one store: a definition that
  * defines either name gets neither.
  */
-import { Type } from "@earendil-works/pi-ai";
+import { num, obj, opt, str, union } from "@earendil-works/pi-schema";
 import { defineExtension, defineTool } from "@earendil-works/pi-durable";
 import { addWakeup, parseDelayMs, removeWakeup } from "../../schedule/wakeups.js";
 import { sessionIdOf } from "./ids.js";
@@ -32,13 +32,13 @@ export function wakeExtension(stateRoot, options = {}) {
                     "same conversation with `prompt` as its instruction, tagged with the wake-up's id so you can tell it from a " +
                     "user's, and you keep the full context of this conversation. Its plain reply is delivered to no one: to " +
                     "reach a person it must call a delivery tool (a channel's send tool), as a scheduled job does.",
-                parameters: Type.Object({
-                    in: Type.Optional(Type.Union([Type.String(), Type.Number()], {
+                parameters: obj({
+                    in: opt(union([str(), num()], {
                         description: 'one-shot delay: a duration string with a unit ("30m" / "2h" / "1d"), or a number of seconds',
                     })),
-                    cron: Type.Optional(Type.String({ description: 'recurring: a 5-field cron expression (e.g. "0 9 * * *")' })),
-                    tz: Type.Optional(Type.String({ description: 'IANA timezone for `cron` (default "UTC")' })),
-                    prompt: Type.String({
+                    cron: opt(str({ description: 'recurring: a 5-field cron expression (e.g. "0 9 * * *")' })),
+                    tz: opt(str({ description: 'IANA timezone for `cron` (default "UTC")' })),
+                    prompt: str({
                         minLength: 1,
                         description: "the instruction for the woken message (it arrives in this same conversation)",
                     }),
@@ -73,8 +73,8 @@ export function wakeExtension(stateRoot, options = {}) {
                 name: "unwake",
                 description: "Cancel one of YOUR pending wake-ups (one-shot or recurring) by the id `wake` returned. Use it when a " +
                     "scheduled follow-up is no longer needed, especially to stop a recurring wake once its job is done.",
-                parameters: Type.Object({
-                    id: Type.String({ minLength: 1, description: "the wake-up id (returned by `wake`)" }),
+                parameters: obj({
+                    id: str({ minLength: 1, description: "the wake-up id (returned by `wake`)" }),
                 }),
                 execute: async (args, api, context) => {
                     const session = await sessionIdOf(api, context);

package/dist/http/client.js

@@ -48,9 +48,15 @@ const reasonOf = (error) => error.reason;
 const unsent = (error) => ["EncodeError", "InvalidUrlError"].includes(reasonOf(error)?._tag ?? "");
 const said = (error) => (error instanceof Error ? error.message : String(error));
 /** What stopped a request that left, said for a Caller. */
-const whatFailed = (baseUrl, error) => reasonOf(error)?._tag === "TransportError"
-    ? `could not reach the agent at ${baseUrl}: ${said(error)}`
-    : `the agent at ${baseUrl} answered what this client cannot read: ${said(error)}`;
+const whatFailed = (baseUrl, error) => {
+    if (reasonOf(error)?._tag === "TransportError")
+        return `could not reach the agent at ${baseUrl}: ${said(error)}`;
+    const answered = `the agent at ${baseUrl} answered what this client cannot read: ${said(error)}`;
+    // A serve mounts the API only while it holds a key (SPEC §9.6): a host that is up and has none answers 404 here.
+    return reasonOf(error)?.response?.status === 404
+        ? `${answered} (a deployment serves no Agent API without a FASTAGENT_API_KEY, and AgentCore serves none)`
+        : answered;
+};
 /**
  * A read's failure, and a write's other than a send's: a refusal as the agent answered it; one that could not get
  * through or met a server's error may be sent again, since repeating any request but a send does no harm (§7);

package/dist/http/contract.d.ts

@@ -464,6 +464,9 @@ declare const AgentHttpApi_base: HttpApi.HttpApi<"fastagent", HttpApiGroup.HttpA
     readonly event: Schema.String;
     readonly data: Schema.String;
 }>, never, never>, Schema.Never, {
+    readonly type: "message";
+    readonly message: Message;
+} | {
     readonly type: "entry";
     readonly entry: Entry;
 } | {
@@ -499,9 +502,6 @@ declare const AgentHttpApi_base: HttpApi.HttpApi<"fastagent", HttpApiGroup.HttpA
         readonly retryable: boolean;
         readonly details?: Schema.Json | undefined;
     };
-} | {
-    readonly type: "message";
-    readonly message: Message;
 } | {
     readonly type: string;
 }> | Schema.toCodecJson<typeof Message>, Schema.toCodecJson<Schema.decodeTo<Schema.declare<AgentError, AgentError>, Schema.Struct<{

package/dist/http/server.d.ts

@@ -11,7 +11,7 @@ export declare function apiTurnedOff(config: {
         api?: boolean;
     };
 }): boolean;
-export declare const API_TURNED_OFF = "fastagent.config.ts says http.api: false";
+export declare const API_TURNED_OFF = "the configuration says http.api: false";
 export declare function apiKeysFrom(value: string | undefined): string[];
 export interface ApiHandler {
     fetch: ChannelHandler;

package/dist/http/server.js

@@ -26,7 +26,7 @@ export const API_KEY_VARIABLE = "FASTAGENT_API_KEY";
 export function apiTurnedOff(config) {
     return config.http?.api === false;
 }
-export const API_TURNED_OFF = "fastagent.config.ts says http.api: false";
+export const API_TURNED_OFF = "the configuration says http.api: false";
 export function apiKeysFrom(value) {
     return (value ?? "")
         .split(",")

package/dist/index.d.ts

@@ -5,21 +5,24 @@
  */
 export type { Agent, AgentErrorData, AgentInfo, CompactOptions, ContentPart, CreateSessionOptions, EntriesOptions, Entry, ErrorCode, Json, ListOptions, Message, MessageKey, MessageStatus, MessageStreamEvent, ModelRef, Page, SendRequest, Session, SessionChanges, SessionEvent, SessionSettings, SessionStatus, ThinkingLevel, Tokens, Usage, WaitOptions, } from "./agent-api.ts";
 export { AgentError, LIMITS, hasEnded } from "./agent-api.ts";
-export { openAgent, type LocalAgent, type OpenAgentOptions, type ServeAgentOptions, } from "./harnesses/pi-durable/serve.ts";
+export { openAgent, type InstanceLocation, type LocalAgent, type OpenAgentOptions, type ServeAgentOptions, } from "./harnesses/pi-durable/serve.ts";
 export type { Service } from "./service.ts";
-export { ContentNameError, addContent, createAgent, listContent, removeContent, type ContentEdit, type CreatedAgent, } from "./authoring.ts";
+export { ContentNameError, addContent, createAgent, listContent, removeContent, type ContentEdit, type ContentScope, type CreatedAgent, } from "./authoring.ts";
 export type { ContentAddition, SourceOptions } from "./content/source.ts";
 export { readContentSource } from "./content/source.ts";
-export type { BoundContent, ContentBinding, ContentEntry } from "./content/declare.ts";
+export type { ContentEntry } from "./content/declare.ts";
 export type { ResolvedContent } from "./content/resolve.ts";
 export { SignInCancelled, type Credential, type CredentialStore, type ProviderAuth, type SignInEvent, type SignInInteraction, type SignInMethod, type SignInOption, type SignInPrompt, type SignInRequest, type SignInResult, } from "./sign-in-api.ts";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.ts";
-export { McpError, type McpErrorCode, type McpOptions, type McpAuthorization, type McpGrantRecord, type McpGrantSummary, type McpGrantStore, type McpGrantAccess, type McpServerSummary, type McpSignInRequest, type McpSignInInteraction, } from "./mcp-api.ts";
+export { McpError, type McpErrorCode, type McpOptions, type McpInspectOptions, type McpConfigInput, type McpAuthorization, type McpGrantRecord, type McpGrantSummary, type McpGrantStore, type McpGrantAccess, type McpServerSummary, type McpSignInRequest, type McpSignInInteraction, } from "./mcp-api.ts";
+export { baseEnv } from "./child-env.ts";
 export { inspectMcp } from "./mcp/host.ts";
 export { signInMcp } from "./mcp/sign-in.ts";
 export { mcpGrantFile } from "./mcp/grants.ts";
-export { defineAgent, defineSchedule, needs, type AgentConfig, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.ts";
+export { byIngress, defineAgent, defineSchedule, needs, type ByIngress, type Ingress, type AgentConfig, type AgentDefaults, type SettingsOf, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.ts";
+export type { InstanceConfig } from "./harnesses/pi-durable/config.ts";
 export type { ScheduleConfig } from "./schedule/schedule.ts";
+export { defineDefinition, type AgentDefinition } from "./harnesses/pi-durable/definition.ts";
 export { defineChannel, type ChannelContext, type ChannelHandler, type ChannelModule, type ForkSource, type LongConnection, type LongConnectionChannelModule, type Routes, } from "./channel.ts";
 export { readBodyCapped } from "./channels/body.ts";
 export { text } from "./channels/respond.ts";

package/dist/index.js

@@ -5,10 +5,13 @@ export { readContentSource } from "./content/source.js";
 export { SignInCancelled, } from "./sign-in-api.js";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.js";
 export { McpError, } from "./mcp-api.js";
+export { baseEnv } from "./child-env.js";
 export { inspectMcp } from "./mcp/host.js";
 export { signInMcp } from "./mcp/sign-in.js";
 export { mcpGrantFile } from "./mcp/grants.js";
-export { defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.js";
+export { byIngress, defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.js";
+// What `fastagent build` writes into a package's generated entry, never written by hand.
+export { defineDefinition } from "./harnesses/pi-durable/definition.js";
 export { defineChannel, } from "./channel.js";
 // What a channel reads a request with, answers with, and compares its platform's secret with (constant time).
 export { readBodyCapped } from "./channels/body.js";

package/dist/instance-name.d.ts

@@ -0,0 +1,7 @@
+export declare const INSTANCE_NAME_ENV = "FASTAGENT_NAME";
+/** `name`, when it can name an instance: one path segment of letters, digits, `-` and `_`; refused otherwise. */
+export declare function checkInstanceName(name: string): string;
+/** The name `FASTAGENT_NAME` gives: unset and empty are the same, as for the path variables. */
+export declare function enteredInstanceName(env?: NodeJS.ProcessEnv): string | undefined;
+/** The instance's name: `given` when there is one (refused when it is not a segment), else the definition's, as one. */
+export declare function instanceName(definitionName: string, given?: string): string;

package/dist/instance-name.js

@@ -0,0 +1,26 @@
+/**
+ * An instance's name (agent-artifact.md §4.5): the one thing `info().name` and a host's report call it. An explicit name
+ * is one path segment, so it is safe to name a directory after, and is refused otherwise; the
+ * default is the definition's name made into one (`@scope/pkg` is not one), so two instances of one definition on one
+ * machine take distinct names only by being given them.
+ */
+import { stripEdges } from "./strip-edges.js";
+export const INSTANCE_NAME_ENV = "FASTAGENT_NAME";
+const SEGMENT = /^[A-Za-z0-9_-]+$/;
+/** `name`, when it can name an instance: one path segment of letters, digits, `-` and `_`; refused otherwise. */
+export function checkInstanceName(name) {
+    if (!SEGMENT.test(name)) {
+        throw new Error(`the instance name ${JSON.stringify(name)} must be one path segment of letters, digits, "-" and "_"`);
+    }
+    return name;
+}
+/** The name `FASTAGENT_NAME` gives: unset and empty are the same, as for the path variables. */
+export function enteredInstanceName(env = process.env) {
+    return env[INSTANCE_NAME_ENV] || undefined;
+}
+/** The instance's name: `given` when there is one (refused when it is not a segment), else the definition's, as one. */
+export function instanceName(definitionName, given) {
+    if (given !== undefined)
+        return checkInstanceName(given);
+    return stripEdges(definitionName.replace(/[^A-Za-z0-9_-]/g, "-"), (char) => char === "-") || "agent";
+}

package/dist/lark.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical Feishu engine. */
-export { larkChannel, larkIngress, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
+export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
 export { larkThreads, larkTransport, type FeishuTransport as LarkTransport } from "./channels/feishu/shared-api.ts";

package/dist/lark.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical Feishu engine. */
-export { larkChannel, larkIngress, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
+export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
 export { larkThreads, larkTransport } from "./channels/feishu/shared-api.js";

package/dist/mcp/client.js

@@ -1,6 +1,6 @@
 /** Instance-owned MCP clients. The scope also joins refreshes after a caller abandons its wait. */
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
-import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { DEFAULT_INHERITED_ENV_VARS, StdioClientTransport } from "@modelcontextprotocol/client/stdio";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -11,6 +11,15 @@ import { checkGrantTarget, discoverMcp, grantToken, mcpFailure } from "./auth.js
 import { mcpFetch, openMcpNetwork } from "./network.js";
 import { checkedGrant } from "./grants.js";
 import { log } from "../log.js";
+/**
+ * The SDK starts a stdio server over `{ ...getDefaultEnvironment(), ...env }`, which adds this process's own `HOME`,
+ * `PATH`, `USER` and the like under whatever is given. Naming each of them with no value, where `env` holds none,
+ * leaves the server with exactly `env`: Node drops a variable whose value is undefined.
+ */
+function ownEnvironment(env) {
+    const withheld = Object.fromEntries(DEFAULT_INHERITED_ENV_VARS.filter((name) => !(name in env)).map((name) => [name, undefined]));
+    return { ...withheld, ...env };
+}
 export async function openMcpClients(servers, auth, options = {}) {
     const lifetime = Scope.makeUnsafe();
     const cleanupErrors = [];
@@ -52,7 +61,7 @@ export async function openMcpClients(servers, auth, options = {}) {
                     command: server.command,
                     args: server.args,
                     cwd: server.cwd,
-                    env: server.env,
+                    env: ownEnvironment(server.env),
                     stderr: "pipe",
                 });
                 // Draining prevents a noisy child from blocking. Raw stderr can contain its supplied secrets.

package/dist/mcp/config.d.ts

@@ -1,19 +1,18 @@
 import * as Schema from "effect/Schema";
 import { type DeclaredSecret } from "../declared-secrets.ts";
-export declare const MCP_FILE = ".mcp.json";
-declare const Configuration: Schema.Struct<{
-    readonly mcpServers: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
-        readonly type: Schema.optional<Schema.Literal<"stdio">>;
-        readonly command: Schema.NonEmptyString;
-        readonly args: Schema.optional<Schema.$Array<Schema.String>>;
-        readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
-    }>, Schema.Struct<{
-        readonly type: Schema.Literal<"http">;
-        readonly url: Schema.String;
-        readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
-    }>]>>;
-}>;
-export type McpConfiguration = typeof Configuration.Type;
+import { type McpConfigInput } from "../mcp-api.ts";
+declare const Declaration: Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.optional<Schema.Literal<"stdio">>;
+    readonly command: Schema.NonEmptyString;
+    readonly args: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"http">;
+    readonly url: Schema.String;
+    readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+}>]>;
+/** One server as an `mcpServers` map holds it. */
+export type McpServerDeclaration = typeof Declaration.Type;
 export type McpServer = {
     name: string;
     type: "stdio";
@@ -27,8 +26,61 @@ export type McpServer = {
     url: string;
     headers: Record<string, string>;
 };
-export declare function readMcpConfiguration(dir: string): McpConfiguration;
-export declare function mcpSecrets(dir: string): DeclaredSecret[];
-export declare function checkMcpUrl(value: string, server?: string): URL;
-export declare function resolveMcpServers(dir: string, env: Readonly<Record<string, string | undefined>>, only?: string): McpServer[];
+/** A server and where it was declared: what its refusals name, and what a relative command is relative to. */
+export interface McpDeclaration {
+    name: string;
+    server: McpServerDeclaration;
+    /** The file that declared it, as a refusal names it. */
+    file: string;
+    /** The directory that file is in. None for an object, whose commands with a path must be absolute. */
+    base?: string;
+    origin: "program" | "instance";
+}
+/** The instance configuration as far as MCP reads it: its `mcpServers`, and where it is from. */
+export interface McpInstance {
+    values: unknown;
+    label: string;
+    directory?: string;
+}
+/** An instance's servers, checked: what `resolveConfig` asks of a configuration, so its refusal is the file's. */
+export declare function checkInstanceServers(instance: McpInstance): void;
+/**
+ * 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 declare function declareMcp(dir: string, instance?: McpInstance): McpDeclaration[];
+/** An instance configuration given to `inspectMcp` or `signInMcp`: an object, or the absolute path of a `fastagent.json`. */
+export declare function mcpInstance(config: McpConfigInput | undefined): McpInstance | undefined;
+/** The secrets the servers' `${NAME}` references need: each required, declared where the server is. */
+export declare function mcpSecrets(declarations: readonly McpDeclaration[]): DeclaredSecret[];
+/**
+ * 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 declare function literalCredentials(declarations: readonly McpDeclaration[]): {
+    file: string;
+    server: string;
+    field: "headers" | "env";
+    key: string;
+}[];
+/**
+ * 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 declare function relativeCommands(declarations: readonly McpDeclaration[]): (McpDeclaration & {
+    command: string;
+})[];
+/** What to write instead of a literal credential, which a header's value usually carries a scheme in front of. */
+export declare function literalCredentialAdvice({ field, key }: {
+    field: "headers" | "env";
+    key: string;
+}): string;
+export declare function checkMcpUrl(value: string, server?: string, file?: string): URL;
+export declare function resolveMcpServers(declarations: readonly McpDeclaration[], env: Readonly<Record<string, string | undefined>>, only: string | undefined, 
+/** Where a stdio server runs: the instance's workspace, whoever declared it. */
+cwd: string, 
+/** What every process the instance starts gets (child-env.ts), under a stdio server's own `env`. */
+processEnv: Readonly<Record<string, string>>): McpServer[];
 export {};