@fastagent-sh/fastagent 0.27.0 → 0.29.0

package/README.md

@@ -152,9 +152,10 @@ The package exports the supported surface only, from one entry per kind of user,
 | The Agent API | `Agent`, `AgentError` ([Agent API](docs/SPEC.md)) | Stable within its version |
 | Directory → agent → service | `openAgent`, `LocalAgent`, `serve()`'s `Service` (`fetch`, `listen`) | Usable now, may tighten before 1.0 |
 | Over HTTP | `connectAgent` (`/client`), the `/v1` routes ([Agent API](docs/SPEC.md) §9) | Stable within its version |
-| A host embedding agents | `createAgent`, `CredentialStore`, `credentialFile`, `signIn`, `signInOptions`, `providerAuth` ([embedding](docs/embedding.md#6-a-desktop-host)) | Usable now, may tighten before 1.0 |
+| A host embedding agents | `createAgent`, `addContent`, `removeContent`, `listContent`, `CredentialStore`, `credentialFile`, `signIn`, `signInOptions`, `providerAuth` ([embedding](docs/embedding.md#6-a-desktop-host)) | Usable now, may tighten before 1.0 |
+| MCP tools and authorization | `inspectMcp`, `signInMcp`, `mcpGrantFile`, `McpGrantStore` ([MCP servers](docs/mcp.md)) | Usable now, may tighten before 1.0 |
 | Authoring | `defineAgent`, `defineChannel`, `defineSchedule`, `needs`, `sessionIdOf`, `readBodyCapped`, `text`, `secretEquals` | Usable now, may tighten before 1.0 |
-| Not exported | The assembly's parts (`router`, `createScheduler`), content editing, the model environment, harness internals | No compatibility promise |
+| Not exported | The assembly's parts (`router`, `createScheduler`), the environment's edit (`writeEnvironment`), the model environment, harness internals | No compatibility promise |
 
 A tool or an extension is pi-durable's own (`defineTool`, `defineExtension` from `@earendil-works/pi-durable`), and a
 custom provider is pi-ai's (`createProvider` from `@earendil-works/pi-ai`): `init` adds both packages to the agent.
@@ -189,7 +190,7 @@ The Agent API leaves room for capabilities that are not complete product feature
 - **Scale-out**: one process holds an instance's storage today; spreading one instance over several processes is future work.
 - **Sandboxed execution** — the coding tools, channels, and author-written code reach the local process directly; a sandbox around the complete agent process is future work.
 - **Observability export** — leveled logs exist today; an OpenTelemetry exporter does not.
-- **More channels and connectors** — community channels can use the channel kit; MCP servers as connectors are planned.
+- **More channels** — community channels can use the channel kit. External tools can also use [MCP servers](docs/mcp.md).
 - **More deploy targets** — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.
 
 See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.

package/dist/authoring.d.ts

@@ -10,7 +10,7 @@ export declare class ContentNameError extends Error {
     name: string;
 }
 export interface InitAgentOptions {
-    /** What the agent works on and knows: repositories into `context.json`, this machine's directories into
+    /** What the agent works on: repositories into `context.json`, this machine's directories into
      *  `context.local.json`. */
     content?: ContentAddition[];
     /**
@@ -36,26 +36,33 @@ export interface CreatedAgent {
  * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
  * repository whose first commit is what was written, since the agent changes itself and version control is how its
  * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
+ *
+ * `content` gives it any number of entries, each a directory of this machine or a GitHub repository. They are all
+ * checked before anything is written, and one that is refused leaves no directory. Two entries may bind the same
+ * directory, or one inside the other; the agent then reaches it by both names.
  */
-export declare function createAgent(dir: string): Promise<CreatedAgent>;
+export declare function createAgent(dir: string, options?: {
+    content?: ContentAddition[];
+}): Promise<CreatedAgent & {
+    content: ResolvedContent[];
+}>;
 /**
- * {@link createAgent} with what `fastagent init` adds: content, and the install. Every content entry is checked before
+ * {@link createAgent} with what `fastagent init` adds: the install. Every content entry is checked before
  * anything is written, and the scaffold is removed again when writing the content fails.
  */
 export declare function initAgent(dir: string, options?: InitAgentOptions): Promise<CreatedAgent & {
     content: ResolvedContent[];
 }>;
 /**
- * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
- * machine binds that are not here: the agent is not told of those.
+ * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. Missing local directories
+ * are listed separately; an agent opened here is not told of them.
  */
 export declare function listContent(agentDir: string): Promise<{
     content: ResolvedContent[];
     absent: BoundContent[];
 }>;
 /**
- * What an edit leaves: the entry it added or removed, by name, the agent's content after it, and what to tell the
- * user about what was left on this machine.
+ * The edited declaration resolved for this machine; an already-open agent keeps its startup snapshot until reopened.
  */
 export interface ContentEdit {
     name: string;

package/dist/authoring.js

@@ -2,7 +2,8 @@
  * Creating an agent and editing its content: `fastagent init` and `fastagent content` are thin wrappers over these (and
  * `fastagent env` writes its declaration through {@link writeEnvironment}), so the rules live here, not in a command.
  * Nothing here prints or exits; every refusal is thrown with the message the CLI shows. The package exports
- * {@link createAgent}; the content and environment edits wait for context packages, whose shape they follow.
+ * {@link createAgent} and the content edits ({@link addContent}, {@link removeContent}, {@link listContent}), which
+ * give an agent its own entries, without an alias prefix; the environment's edit is not exported.
  */
 import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
@@ -28,13 +29,16 @@ export class ContentNameError extends Error {
  * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
  * repository whose first commit is what was written, since the agent changes itself and version control is how its
  * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
+ *
+ * `content` gives it any number of entries, each a directory of this machine or a GitHub repository. They are all
+ * checked before anything is written, and one that is refused leaves no directory. Two entries may bind the same
+ * directory, or one inside the other; the agent then reaches it by both names.
  */
-export async function createAgent(dir) {
-    const { content: _, ...created } = await initAgent(dir);
-    return created;
+export async function createAgent(dir, options = {}) {
+    return initAgent(dir, options.content === undefined ? {} : { content: options.content });
 }
 /**
- * {@link createAgent} with what `fastagent init` adds: content, and the install. Every content entry is checked before
+ * {@link createAgent} with what `fastagent init` adds: the install. Every content entry is checked before
  * anything is written, and the scaffold is removed again when writing the content fails.
  */
 export async function initAgent(dir, options = {}) {
@@ -69,8 +73,8 @@ export async function initAgent(dir, options = {}) {
     return { dir: agentDir, created, content, repository: await initRepository(agentDir) };
 }
 /**
- * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
- * machine binds that are not here: the agent is not told of those.
+ * The on-disk declaration resolved for this machine, not an open agent's startup snapshot. Missing local directories
+ * are listed separately; an agent opened here is not told of them.
  */
 export async function listContent(agentDir) {
     const dir = resolveAgentDir(agentDir);

package/dist/channels/feishu/feishu-api.d.ts

@@ -19,6 +19,7 @@ export interface DownloadedFile {
  *  streaming once when it sees this. A plain code check on the typed error, exported instead of the
  *  class so no caller can construct/throw one. */
 export declare function isCardStreamingClosed(e: unknown): boolean;
+export declare function isFeishuCredentialsRefused(e: unknown): boolean;
 /** Whether the platform origin has no application-config route at all. Onboarding uses this narrow
  * signal to fall back to a manual token/mode setup; auth/scope/network failures must remain visible. */
 export declare function isFeishuConfigApiMissing(e: unknown): boolean;

package/dist/channels/feishu/feishu-api.js

@@ -61,6 +61,10 @@ class FeishuApiError extends Error {
 export function isCardStreamingClosed(e) {
     return e instanceof FeishuApiError && (e.code === 200850 || e.code === 300309);
 }
+// Lark's credential endpoint returns code 10003 for invalid app credentials; other errors remain fatal.
+export function isFeishuCredentialsRefused(e) {
+    return e instanceof FeishuApiError && e.call === "tenant_access_token" && e.status === 200 && e.code === 10003;
+}
 /** Whether the platform origin has no application-config route at all. Onboarding uses this narrow
  * signal to fall back to a manual token/mode setup; auth/scope/network failures must remain visible. */
 export function isFeishuConfigApiMissing(e) {

package/dist/channels/feishu/register-app.d.ts

@@ -24,6 +24,8 @@ interface FeishuAppAddons {
         items?: string[];
     };
 }
+/** JSON → gzip → base64url — the platform's fixed addons encoding. */
+export declare function encodeAddons(addons: FeishuAppAddons): string;
 export interface RegisterFeishuAppOptions {
     /** Pre-filled app name shown on the confirm page (`{user}` expands to the scanning user's name). */
     name?: string;

package/dist/channels/feishu/register-app.js

@@ -13,7 +13,7 @@ const ENDPOINT = "/oauth/v1/app/registration";
 /** Per-attempt timeout for one registration POST — small form/JSON round-trips. */
 const REQUEST_TIMEOUT_MS = 30_000;
 /** JSON → gzip → base64url — the platform's fixed addons encoding. */
-function encodeAddons(addons) {
+export function encodeAddons(addons) {
     return gzipSync(Buffer.from(JSON.stringify(addons), "utf8"))
         .toString("base64")
         .replace(/\+/g, "-")

package/dist/channels/lark/credentials-page.d.ts

@@ -0,0 +1,25 @@
+export interface LarkCredentials {
+    appId: string;
+    appSecret: string;
+}
+export declare class LarkCredentialsRefused extends Error {
+    readonly fix: string | undefined;
+    readonly why: string | undefined;
+    constructor(headline: string, options?: {
+        fix?: string;
+        why?: string;
+    });
+}
+export interface LarkCredentialsPage<T = LarkCredentials> {
+    url: string;
+    credentials: Promise<T>;
+    close(): Promise<void>;
+}
+export declare function startLarkCredentialsPage(input: {
+    consoleUrl: string;
+    check(credentials: LarkCredentials): Promise<void>;
+}): Promise<LarkCredentialsPage>;
+export declare function startLarkVerificationPage(input: {
+    consoleUrl: string;
+    save(token: string): Promise<void>;
+}): Promise<LarkCredentialsPage<string>>;

package/dist/channels/lark/credentials-page.js

@@ -0,0 +1,206 @@
+/** Loopback-only, single-use forms for Lark setup secrets; values never pass through the agent's conversation. */
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { field, formCard, openButton, privacy, prose, refusal, sendPage, setupRequestUrl, statusCard, step, submit, } from "../../setup-page.js";
+export class LarkCredentialsRefused extends Error {
+    fix;
+    why;
+    constructor(headline, options = {}) {
+        super(headline);
+        this.name = "LarkCredentialsRefused";
+        this.fix = options.fix;
+        this.why = options.why;
+    }
+}
+function readBody(request) {
+    return new Promise((resolve) => {
+        let body = "";
+        let tooLarge = false;
+        request.on("data", (chunk) => {
+            if (tooLarge)
+                return;
+            body += String(chunk);
+            if (Buffer.byteLength(body) > 16 * 1024)
+                tooLarge = true;
+        });
+        request.on("end", () => resolve(tooLarge ? undefined : body));
+        request.on("error", () => resolve(undefined));
+    });
+}
+export function startLarkCredentialsPage(input) {
+    return startPage({
+        heading: "Lark credentials verified",
+        form: (pasted, problem) => formCard("Connect Lark", [
+            step(1, "Create the app in Lark", prose("It opens with the permissions and event your agent needs already set.") +
+                openButton("Open Lark", input.consoleUrl)),
+            step(2, "Paste its credentials", (problem
+                ? refusal(problem.message, problem.fix, problem.why)
+                : prose("Find them under <b>Credentials &amp; Basic Info</b>.")) +
+                field({
+                    id: "app_id",
+                    label: "App ID",
+                    placeholder: "cli_…",
+                    value: pasted.get("app_id") ?? "",
+                    invalid: !!problem,
+                }) +
+                field({ id: "app_secret", label: "App Secret", secret: true, invalid: !!problem, autofocus: !!problem }) +
+                submit("Save and check") +
+                privacy()),
+        ].join("")),
+        accept: async (pasted) => {
+            const pair = { appId: (pasted.get("app_id") ?? "").trim(), appSecret: (pasted.get("app_secret") ?? "").trim() };
+            if (!pair.appId || !pair.appSecret) {
+                throw new LarkCredentialsRefused("Both values are needed.", {
+                    fix: "Copy the App ID and the App Secret from Credentials & Basic Info.",
+                });
+            }
+            await input.check(pair);
+            return pair;
+        },
+    });
+}
+export function startLarkVerificationPage(input) {
+    return startPage({
+        heading: "Verification Token saved",
+        form: (_pasted, problem) => formCard("Finish Lark webhook setup", [
+            step(1, "Copy the Verification Token", prose("Find it under <b>Events &amp; Callbacks</b> → Encryption Strategy. Choose webhook mode when setting the Request URL.") + openButton("Open Lark", input.consoleUrl)),
+            step(2, "Paste the token here", (problem ? refusal(problem.message, problem.fix) : "") +
+                field({
+                    id: "verification_token",
+                    label: "Verification Token",
+                    secret: true,
+                    invalid: !!problem,
+                    autofocus: !!problem,
+                }) +
+                submit("Save token") +
+                privacy()),
+        ].join("")),
+        accept: async (pasted) => {
+            const token = (pasted.get("verification_token") ?? "").trim();
+            if (!token)
+                throw new LarkCredentialsRefused("Verification Token is required.");
+            await input.save(token);
+            return token;
+        },
+    });
+}
+// A browser can leave during validation, before either response event can be subscribed to.
+function afterResponse(response, complete) {
+    if (response.destroyed || response.writableFinished)
+        complete();
+    else
+        response.once("close", complete);
+}
+async function startPage(input) {
+    const path = `/lark/credentials/${randomBytes(24).toString("hex")}`;
+    const { promise: credentials, resolve, reject } = Promise.withResolvers();
+    let checking = false;
+    let used = false;
+    let port = 0;
+    const server = createServer(async (request, response) => {
+        const url = setupRequestUrl(request, response);
+        if (url === undefined)
+            return;
+        const host = request.headers.host ?? "";
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+            response.writeHead(421).end("misdirected request\n");
+            return;
+        }
+        if (url.pathname !== path || (request.method !== "GET" && request.method !== "POST")) {
+            response.writeHead(404).end("not found\n");
+            return;
+        }
+        const expired = () => sendPage(response, 404, {
+            title: "FastAgent setup",
+            card: statusCard({
+                state: "failed",
+                heading: "This page is no longer in use",
+                next: "Go back to your coding agent.",
+            }),
+        });
+        if (used) {
+            expired();
+            return;
+        }
+        if (request.method === "GET") {
+            sendPage(response, 200, { title: "Connect Lark — FastAgent", card: input.form(new URLSearchParams()) });
+            return;
+        }
+        const site = request.headers["sec-fetch-site"];
+        if (site !== undefined && site !== "same-origin") {
+            response.writeHead(403).end("forbidden\n");
+            return;
+        }
+        const body = await readBody(request);
+        if (body === undefined) {
+            response.writeHead(413).end("payload too large\n");
+            return;
+        }
+        if (used) {
+            expired();
+            return;
+        }
+        if (checking) {
+            response.writeHead(409).end("another submission is being checked\n");
+            return;
+        }
+        checking = true;
+        const pasted = new URLSearchParams(body);
+        let accepted;
+        try {
+            accepted = await input.accept(pasted);
+        }
+        catch (error) {
+            checking = false;
+            // Only explicit input refusals stay on the form. Infrastructure and persistence errors fail the ticket.
+            if (error instanceof LarkCredentialsRefused) {
+                sendPage(response, 200, { title: "Connect Lark — FastAgent", card: input.form(pasted, error) });
+                return;
+            }
+            used = true;
+            afterResponse(response, () => reject(error));
+            sendPage(response, 200, {
+                title: "Setup stopped — FastAgent",
+                card: statusCard({
+                    state: "failed",
+                    heading: "Setup stopped",
+                    lede: error instanceof Error ? error.message : String(error),
+                    next: "Go back to your coding agent.",
+                }),
+            });
+            return;
+        }
+        used = true;
+        afterResponse(response, () => resolve(accepted));
+        sendPage(response, 200, {
+            title: `${input.heading} — FastAgent`,
+            card: statusCard({
+                state: "done",
+                heading: input.heading,
+                lede: "Your coding agent will say if anything is left to do in Lark.",
+                next: "Go back to your coding agent.",
+            }),
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("the Lark credentials page did not receive a local TCP port");
+    }
+    port = address.port;
+    return {
+        url: `http://127.0.0.1:${port}${path}`,
+        credentials,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        }),
+    };
+}

package/dist/channels/lark/onboard.d.ts

@@ -1,6 +1,12 @@
-import type { FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
+import { type FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
 /** Guided Lark-international onboarding. */
-export declare const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
+/**
+ * Lark's one-click launcher, where the person creates the app. The launcher is unbound (the bound confirm page is broken
+ * on the international cloud), but it merges the `addons` query parameter onto the app it creates, as Feishu's does: the
+ * scopes and the event the channel needs arrive with the app, so nothing is ticked in the console afterwards. A tenant
+ * may still withhold a scope; the permission check that follows creation names it.
+ */
+export declare function larkConsoleUrl(ingress: FeishuSubscriptionMode): string;
 /** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
 export declare function larkEventSecurityUrl(appId: string): string;
 export interface LarkOnboardIO {
@@ -10,6 +16,15 @@ export interface LarkOnboardIO {
     prompt(message: string, opts?: {
         hidden?: boolean;
     }): Promise<string | undefined>;
+    verificationToken?(consoleUrl: string): Promise<string>;
+    collect?(input: {
+        /** Lark's launcher, with what the channel needs set on the app it creates. */
+        consoleUrl: string;
+        check(appId: string, appSecret: string): Promise<void>;
+    }): Promise<{
+        appId: string;
+        appSecret: string;
+    }>;
 }
 interface LarkBootstrapResult {
     /** Challenge-captured token: the PATCH also switched Subscription mode to webhook. */
@@ -22,6 +37,7 @@ export interface LarkOnboardOptions {
     existing?: Readonly<Record<string, string | undefined>>;
     ingress?: FeishuSubscriptionMode;
     verifyCredentials(appId: string, appSecret: string): Promise<void>;
+    keep?(appId: string, appSecret: string): Promise<void>;
     bootstrapWebhook?(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
     /** The command that continues an interrupted setup: the one that started it (`add lark`, `deploy <host> --run`). */
     rerun?: string;

package/dist/channels/lark/onboard.js

@@ -1,5 +1,18 @@
+import { encodeAddons } from "../feishu/register-app.js";
+import { feishuAppAddons } from "../feishu/setup-mode.js";
 /** Guided Lark-international onboarding. */
-export const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
+/**
+ * Lark's one-click launcher, where the person creates the app. The launcher is unbound (the bound confirm page is broken
+ * on the international cloud), but it merges the `addons` query parameter onto the app it creates, as Feishu's does: the
+ * scopes and the event the channel needs arrive with the app, so nothing is ticked in the console afterwards. A tenant
+ * may still withhold a scope; the permission check that follows creation names it.
+ */
+export function larkConsoleUrl(ingress) {
+    const url = new URL("https://open.larksuite.com/page/launcher");
+    url.searchParams.set("from", "backend_oneclick");
+    url.searchParams.set("addons", encodeAddons(feishuAppAddons(ingress)));
+    return url.toString();
+}
 /** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
 export function larkEventSecurityUrl(appId) {
     return `https://open.larksuite.com/app/${encodeURIComponent(appId)}/event?tab=safe`;
@@ -17,15 +30,30 @@ export async function onboardLarkApp(io, opts) {
     const existingSecret = opts.existing?.LARK_APP_SECRET?.trim();
     const reuseExistingApp = Boolean(existingId && existingSecret);
     // Credentials are one App-scoped set.
+    // No ingress named is the webhook path below (a deploy's production app).
+    const consoleUrl = larkConsoleUrl(opts.ingress ?? "webhook");
+    let appId;
+    let appSecret;
+    const verify = async (appId, appSecret) => {
+        await opts.verifyCredentials(appId, appSecret);
+        if (!reuseExistingApp)
+            await opts.keep?.(appId, appSecret);
+    };
     if (reuseExistingApp) {
         io.note(`Reusing Lark app ${existingId}.`);
+        appId = required(existingId, "LARK_APP_ID", rerun);
+        appSecret = required(existingSecret, "LARK_APP_SECRET", rerun);
+        await verify(appId, appSecret);
+    }
+    else if (io.collect) {
+        ({ appId, appSecret } = await io.collect({ consoleUrl, check: verify }));
     }
     else {
-        io.openUrl(LARK_CONSOLE_URL, "create the app on Lark's one-click launcher; LARK_APP_ID and LARK_APP_SECRET are under Credentials & Basic Info");
+        io.openUrl(consoleUrl, "create the app on Lark's one-click launcher; LARK_APP_ID and LARK_APP_SECRET are under Credentials & Basic Info");
+        appId = required(await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID", rerun);
+        appSecret = required(await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET", rerun);
+        await verify(appId, appSecret);
     }
-    const appId = required(reuseExistingApp ? existingId : await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID", rerun);
-    const appSecret = required(reuseExistingApp ? existingSecret : await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET", rerun);
-    await opts.verifyCredentials(appId, appSecret);
     const eventSecurityUrl = larkEventSecurityUrl(appId);
     io.note("App ID / Secret verified.");
     if (opts.ingress === "websocket") {
@@ -47,7 +75,9 @@ export async function onboardLarkApp(io, opts) {
     }
     const verificationToken = required(bootstrap.token ||
         (reuseExistingApp ? opts.existing?.LARK_VERIFICATION_TOKEN?.trim() : undefined) ||
-        (await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN", rerun);
+        (io.verificationToken
+            ? await io.verificationToken(eventSecurityUrl)
+            : await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN", rerun);
     return {
         LARK_APP_ID: appId,
         LARK_APP_SECRET: appSecret,