@fastagent-sh/fastagent 0.28.0 → 0.30.0

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/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,17 +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 { defineAgent, defineSchedule, needs, type AgentConfig, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.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 { 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

@@ -4,7 +4,14 @@ export { ContentNameError, addContent, createAgent, listContent, removeContent,
 export { readContentSource } from "./content/source.js";
 export { SignInCancelled, } from "./sign-in-api.js";
 export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.js";
-export { defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.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 { 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/locked-file.d.ts

@@ -3,8 +3,8 @@ export interface LockResult<T> {
     /** New file content to persist under the lock; undefined = no write. */
     next?: string;
 }
-/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
-export declare function withLockedFile<T>(path: string, fn: (current: string | undefined) => Promise<LockResult<T>>, 
+/** Serialized read-modify-write. `replace` commits immediately under the lock; those writes survive a later failure. */
+export declare function withLockedFile<T>(path: string, fn: (current: string | undefined, replace: (next: string) => void) => Promise<LockResult<T>>, 
 /**
  * `mode`: the replaced file's permissions; default {@link SECRET_FILE_MODE}, for the credential and catalog files.
  * `create: false` locks a file that may not exist without creating it (the lock is `<file>.lock` either way), for a

package/dist/locked-file.js

@@ -26,7 +26,7 @@ function writeTarget(path) {
     // ever shows up in a real layout.
     return link?.isSymbolicLink() ? resolve(dirname(path), readlinkSync(path)) : path;
 }
-/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
+/** Serialized read-modify-write. `replace` commits immediately under the lock; those writes survive a later failure. */
 export async function withLockedFile(path, fn, 
 /**
  * `mode`: the replaced file's permissions; default {@link SECRET_FILE_MODE}, for the credential and catalog files.
@@ -71,7 +71,12 @@ options = {}) {
     try {
         throwIfCompromised();
         const current = existsSync(path) ? readFileSync(path, "utf8") : undefined;
-        const out = await fn(current);
+        const replace = (next) => {
+            throwIfCompromised();
+            options.signal?.throwIfAborted();
+            writeFileAtomic(writeTarget(path), next, options.mode ?? SECRET_FILE_MODE);
+        };
+        const out = await fn(current, replace);
         throwIfCompromised();
         // The last moment a caller that gave up can keep its change off disk: waiting for the lock may have outlasted it
         // (another process held the lock through the caller's timeout or cancel).
@@ -79,7 +84,7 @@ options = {}) {
         // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only spelling that applies
         // the mode before the content is reachable.
         if (out.next !== undefined) {
-            writeFileAtomic(writeTarget(path), out.next, options.mode ?? SECRET_FILE_MODE);
+            replace(out.next);
         }
         throwIfCompromised();
         result = out.result;

package/dist/mcp/auth.d.ts

@@ -0,0 +1,22 @@
+import { type AuthorizationServerMetadata, type OAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
+import { McpError, type McpGrantRecord, type McpGrantStore } from "../mcp-api.ts";
+export interface McpDiscovery {
+    metadata: AuthorizationServerMetadata;
+    resourceMetadata: OAuthProtectedResourceMetadata;
+    issuer: string;
+    resource: string;
+}
+export declare function discoverMcp(url: string, fetchImpl: typeof globalThis.fetch): Promise<McpDiscovery>;
+export declare function checkGrantTarget(record: McpGrantRecord, url: string, discovery?: McpDiscovery): void;
+export declare function mcpFailure(error: unknown, operation: string, server?: string): McpError;
+export declare function grantToken(input: {
+    store: McpGrantStore;
+    id: string;
+    url: string;
+    fetch: typeof globalThis.fetch;
+    discovery?: McpDiscovery;
+    rejectedGeneration?: number;
+}): Promise<{
+    token: string;
+    generation: number;
+}>;