@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/channels/webhooks.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A serve pointing its platforms at itself (SPEC.md §8, `Service.registerWebhooks`; channel-setup.md §5): which of its
+ * channels take a webhook, the step a person takes for each one the instance cannot set, and the registration that
+ * sets what the app's own credentials can set, on every call and without reading it first.
+ */
+import type { DeclaredChannel } from "./discover.ts";
+import { type RegistrationOutcome } from "./registration.ts";
+/** One webhook channel's registration (SPEC.md §8). */
+export interface WebhookRegistration {
+    /** The channel file's name. */
+    channel: string;
+    outcome: "pending" | RegistrationOutcome;
+    /** The URL it was, or is to be, pointed at; absent when no base URL is known. */
+    url?: string;
+    /** For `manual` and `failed`: what to do, said as the step to take. */
+    step?: string;
+}
+/** The first-party channels a webhook points at, in the order every report lists them. */
+export type WebhookKind = "telegram" | "slack" | "feishu" | "lark";
+/** The first-party channels among `channels` that receive by webhook, in {@link KINDS}' order. */
+export declare function webhookKinds(channels: readonly DeclaredChannel[]): WebhookKind[];
+/** The channel's default route. */
+export declare function webhookPath(kind: WebhookKind): string;
+/** The one line a person acts on to point `kind` at `baseUrl` by hand. */
+export declare function manualWebhookStep(kind: WebhookKind, baseUrl: string): string;
+/** Every webhook channel, not registered yet: what a serve reports until its registration ends. */
+export declare function pendingWebhooks(kinds: readonly WebhookKind[]): WebhookRegistration[];
+/**
+ * Point each of `kinds` at `<baseUrl>/<its path>` with the instance's own credentials (`env`): Telegram's `setWebhook`
+ * and Feishu's or Lark's event-subscription PATCH, set on every call (Telegram's `getWebhookInfo` returns no
+ * `secret_token`, and Feishu's route takes only a PATCH). Slack's Request URL is the app's configuration, which no
+ * credential the instance holds can change: its outcome is `manual`. Without a base URL nothing is pointed.
+ */
+export declare function registerOwnWebhooks(baseUrl: string | undefined, kinds: readonly WebhookKind[], env: NodeJS.ProcessEnv, options?: {
+    attempts?: number;
+    retryMs?: number;
+}): Promise<WebhookRegistration[]>;

package/dist/channels/webhooks.js

@@ -0,0 +1,70 @@
+import { registerFeishuWebhook } from "./feishu/register-webhook.js";
+import { DEPLOY_REGISTRATION_ATTEMPTS } from "./registration.js";
+import { registerTelegramWebhook } from "./telegram/register-webhook.js";
+import { log } from "../log.js";
+const feishuCloud = (kind) => ({
+    path: `/${kind}`,
+    manual: (url) => `${kind}: set the event Request URL in the developer console (Events & Callbacks) → ${url} (the app must be running when you save)`,
+});
+const KINDS = {
+    telegram: {
+        path: "/telegram",
+        manual: (url) => `telegram: set the webhook → ${url} (secret_token = TELEGRAM_SECRET_TOKEN)`,
+    },
+    slack: { path: "/slack", manual: (url) => `slack: set Event Subscriptions → Request URL → ${url}` },
+    feishu: feishuCloud("feishu"),
+    lark: feishuCloud("lark"),
+};
+/** The first-party channels among `channels` that receive by webhook, in {@link KINDS}' order. */
+export function webhookKinds(channels) {
+    const declared = new Set(channels.filter((c) => c.ingress === "webhook").map((c) => c.name));
+    return Object.keys(KINDS).filter((kind) => declared.has(kind));
+}
+/** The channel's default route. */
+export function webhookPath(kind) {
+    return KINDS[kind].path;
+}
+/** The one line a person acts on to point `kind` at `baseUrl` by hand. */
+export function manualWebhookStep(kind, baseUrl) {
+    return KINDS[kind].manual(`${baseUrl}${KINDS[kind].path}`);
+}
+/** Every webhook channel, not registered yet: what a serve reports until its registration ends. */
+export function pendingWebhooks(kinds) {
+    return kinds.map((channel) => ({ channel, outcome: "pending" }));
+}
+/**
+ * Point each of `kinds` at `<baseUrl>/<its path>` with the instance's own credentials (`env`): Telegram's `setWebhook`
+ * and Feishu's or Lark's event-subscription PATCH, set on every call (Telegram's `getWebhookInfo` returns no
+ * `secret_token`, and Feishu's route takes only a PATCH). Slack's Request URL is the app's configuration, which no
+ * credential the instance holds can change: its outcome is `manual`. Without a base URL nothing is pointed.
+ */
+export async function registerOwnWebhooks(baseUrl, kinds, env, options = {}) {
+    const registrations = [];
+    for (const kind of kinds) {
+        if (baseUrl === undefined) {
+            registrations.push({
+                channel: kind,
+                outcome: "manual",
+                step: `${kind}: no http.publicUrl in the instance configuration, so nothing points the app at this instance`,
+            });
+            continue;
+        }
+        const url = `${baseUrl}${KINDS[kind].path}`;
+        const step = KINDS[kind].manual(url);
+        if (kind === "slack") {
+            registrations.push({ channel: kind, outcome: "manual", url, step });
+            continue;
+        }
+        const attempts = options.attempts ?? DEPLOY_REGISTRATION_ATTEMPTS;
+        const retry = { attempts, ...(options.retryMs === undefined ? {} : { retryMs: options.retryMs }) };
+        // A registrar that throws ends its channel `failed`, said with why, never left `pending` for a reader to wait on.
+        const outcome = await (kind === "telegram"
+            ? registerTelegramWebhook(baseUrl, { env, ...retry })
+            : registerFeishuWebhook(baseUrl, kind, { env, ...retry })).catch((error) => {
+            log.error(`[fastagent] ${kind}: could not register its webhook: ${String(error)}`);
+            return "failed";
+        });
+        registrations.push({ channel: kind, outcome, url, ...(outcome === "registered" ? {} : { step }) });
+    }
+    return registrations;
+}

package/dist/child-env.d.ts

@@ -0,0 +1,16 @@
+/** The base environment `source` gives a process: the variables of the base list it holds, nothing else. */
+export declare function baseEnv(source: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export interface ProcessEnvironmentInputs {
+    /** The base environment (`baseEnv`). */
+    base: Readonly<Record<string, string>>;
+    /** The instance's secrets: only the declared names among them are passed on. */
+    secrets: Readonly<Record<string, string | undefined>>;
+    /** The names the definition declares (`needs()`, `context.json`'s environment variables). */
+    declared: readonly string[];
+    /** What the declared packages add (`mise env`): their commands ahead on the `PATH` the base gave. */
+    packages: Readonly<Record<string, string>>;
+    /** The agent's working directory. */
+    workdir: string;
+}
+/** What every process the agent starts gets, before an MCP server's own `env` is added for that server. */
+export declare function processEnvironment(inputs: ProcessEnvironmentInputs, workspaceParent: string): Record<string, string>;

package/dist/child-env.js

@@ -0,0 +1,30 @@
+/**
+ * The environment of the processes an instance starts (agent-artifact.md §5): the shell tool, stdio MCP servers and
+ * skill scripts. Assembled from inputs, never the host process's whole `process.env`, so a stray variable of the host
+ * (an API key, a cloud credential) cannot reach a command, and a declared one reaches every command.
+ */
+import { definedValues } from "./declared-secrets.js";
+const BASE_NAMES = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "LANG",
+    "TZ",
+    "TMPDIR",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+]);
+/** The base environment `source` gives a process: the variables of the base list it holds, nothing else. */
+export function baseEnv(source) {
+    return Object.fromEntries(Object.entries(definedValues(source)).filter(([name]) => BASE_NAMES.has(name) || name.startsWith("LC_")));
+}
+/** `GIT_CEILING_DIRECTORIES` at the workspace's parent, so git discovery stops at the workspace. */
+const GIT_CEILING = "GIT_CEILING_DIRECTORIES";
+/** What every process the agent starts gets, before an MCP server's own `env` is added for that server. */
+export function processEnvironment(inputs, workspaceParent) {
+    const held = definedValues(inputs.secrets);
+    const declared = Object.fromEntries(inputs.declared.flatMap((name) => (Object.hasOwn(held, name) ? [[name, held[name]]] : [])));
+    return { ...inputs.base, ...declared, ...inputs.packages, [GIT_CEILING]: workspaceParent };
+}

package/dist/cli/box-login.js

@@ -24,7 +24,10 @@ export async function loginOnBox(request) {
     ];
     let command;
     try {
-        command = boxLoginCommand(args, shell.storage);
+        command = boxLoginCommand(args, {
+            ...(shell.storage === undefined ? {} : { storage: shell.storage }),
+            ...(shell.program === undefined ? {} : { program: shell.program }),
+        });
     }
     catch (error) {
         return error.message;

package/dist/cli/channel-app.d.ts

@@ -0,0 +1,3 @@
+import type { WebhookKind } from "../channels/webhooks.ts";
+/** Record `url` as the confirmed URL of `kind`'s app in the configuration file `config`. */
+export declare function recordChannelUrl(agentDir: string, config: string, kind: WebhookKind, url: string, values: ReadonlyMap<string, string>): Promise<void>;

package/dist/cli/channel-app.js

@@ -0,0 +1,35 @@
+/**
+ * The binding of a channel whose URL only a person sets (Slack; Lark without its configuration API), recorded in an
+ * instance configuration once the deployment confirms the URL (`channels.<name>.app`, SPEC.md §8): what `deploy` at a
+ * terminal and `channels setup --record-url` both write.
+ */
+import { setChannelConfig } from "../authoring.js";
+import { createSlackApi } from "../channels/slack/slack-api.js";
+/**
+ * The app a recorded URL belongs to: Lark's App ID from its values; Slack's from its bot token, which names the app a
+ * bot belongs to (`bots.info`, which needs the `users:read` scope the app is created with).
+ */
+async function appOf(kind, values) {
+    if (kind === "lark") {
+        const id = values.get("LARK_APP_ID");
+        if (!id)
+            throw new Error("lark: no LARK_APP_ID in the values, so the URL cannot be recorded against its app");
+        return { id };
+    }
+    const botToken = values.get("SLACK_BOT_TOKEN");
+    if (!botToken)
+        throw new Error("slack: no SLACK_BOT_TOKEN in the values, so the URL cannot be recorded against its app");
+    const api = createSlackApi({ botToken });
+    const { teamId, botId } = await api.authTest();
+    const id = botId === undefined ? undefined : await api.botAppId(botId);
+    if (id === undefined)
+        throw new Error("slack: Slack named no app for this bot token (does it hold users:read?)");
+    return { id, ...(teamId === undefined ? {} : { team: teamId }) };
+}
+/** Record `url` as the confirmed URL of `kind`'s app in the configuration file `config`. */
+export async function recordChannelUrl(agentDir, config, kind, url, values) {
+    if (kind !== "slack" && kind !== "lark") {
+        throw new Error(`${kind}: its URL the instance sets itself, so there is nothing to record`);
+    }
+    await setChannelConfig(agentDir, kind, { app: { ...(await appOf(kind, values)), url } }, { config });
+}

package/dist/cli/channel-setup.d.ts

@@ -0,0 +1,38 @@
+import { type ChannelSetup, type SetupWay } from "../channels/setup.ts";
+import { type Person } from "./person.ts";
+declare const SETUPS: {
+    readonly telegram: ChannelSetup;
+    readonly slack: ChannelSetup;
+    readonly feishu: ChannelSetup;
+    readonly lark: ChannelSetup;
+};
+/** The channels whose app `channels setup` sets up. */
+export type SetupKind = keyof typeof SETUPS;
+export declare const isSetupKind: (name: string) => name is SetupKind;
+export interface SetUpChannelInput {
+    kind: SetupKind;
+    agentDir: string;
+    /** The value file the credentials are kept in. */
+    file: string;
+    way: SetupWay;
+    /** Whether this is the development instance. */
+    dev: boolean;
+    /** The command that runs this setup again. */
+    rerun: string;
+    /** Where the platform will reach the instance, when its configuration names it. */
+    publicUrl?: string;
+    /** A coding agent's person, through a ticket: asked on a page. Absent: asked at this terminal. */
+    person?: Person;
+}
+export interface SetUpOutcome {
+    /** The variables this run wrote. */
+    written: string[];
+    /** The variables that were set already, and are accepted. */
+    kept: string[];
+    /** What is left to the person once it is done. */
+    after: string[];
+}
+/** The variables a channel's app needs for `way`, in the order setup asks for them. */
+export declare function setupNames(kind: SetupKind, way: SetupWay): string[];
+export declare function setUpChannel(input: SetUpChannelInput): Promise<SetUpOutcome>;
+export {};

package/dist/cli/channel-setup.js

@@ -0,0 +1,195 @@
+/**
+ * Setting up one channel's platform app for one instance (channel-setup.md §2): ask a person for the values only they
+ * have, check each with the platform, and keep what is accepted in the instance's value file. Safe to run again: a value
+ * already there that the platform still accepts is kept, one it refuses is asked for again, a value setup makes itself
+ * is made once, and an app already created is not created again.
+ *
+ * What differs per channel is in `channels/<kind>/setup.ts`; this is how they are asked: at a terminal, or, for a coding
+ * agent that has none, on a page of this machine's (credentials-page.ts) that its person is sent to through a ticket.
+ */
+import { basename } from "node:path";
+import { isCancel, log as clackLog, password, text } from "@clack/prompts";
+import { feishuSetup } from "../channels/feishu/setup.js";
+import { larkSetup } from "../channels/lark/setup.js";
+import { slackSetup } from "../channels/slack/setup.js";
+import { SetupRefused, } from "../channels/setup.js";
+import { telegramSetup } from "../channels/telegram/setup.js";
+import { startCredentialsPage } from "../credentials-page.js";
+import { openExternalUrl } from "../open-url.js";
+import { startCloudflareTunnel } from "../tunnel.js";
+import { loadEnvValues, unprotectedSecretsNote, writeValues } from "../value-file.js";
+import { terminalPerson } from "./person.js";
+const SETUPS = {
+    telegram: telegramSetup,
+    slack: slackSetup,
+    feishu: feishuSetup,
+    lark: larkSetup,
+};
+const PRODUCTS = { telegram: "Telegram", slack: "Slack", feishu: "Feishu", lark: "Lark" };
+export const isSetupKind = (name) => Object.hasOwn(SETUPS, name);
+const say = (message) => console.error(`[fastagent] ${message}`);
+/** The variables a channel's app needs for `way`, in the order setup asks for them. */
+export function setupNames(kind, way) {
+    const plan = SETUPS[kind]({ way, appName: "", dev: true, rerun: "", startTunnel: startCloudflareTunnel });
+    return plan.values.flatMap((value) => value.kind === "paste" ? value.fields.map((one) => one.name) : value.kind === "create" ? value.names : [value.name]);
+}
+export async function setUpChannel(input) {
+    const { kind, agentDir, file, person } = input;
+    const plan = SETUPS[kind]({
+        way: input.way,
+        appName: basename(agentDir),
+        dev: input.dev,
+        rerun: input.rerun,
+        startTunnel: startCloudflareTunnel,
+        ...(input.publicUrl === undefined ? {} : { publicUrl: input.publicUrl }),
+    });
+    const written = [];
+    const kept = [];
+    /** A directory fastagent does not own that now holds a secret: said once, however many values went there. */
+    let unprotected;
+    const held = new Map();
+    for (const [name, value] of loadEnvValues(file))
+        if (value.trim() !== "")
+            held.set(name, value.trim());
+    /** Keep `entries` in one write: an app's values come together, and none of them may be lost to a later failure. */
+    const keep = async (entries, replace) => {
+        const names = entries.map((entry) => entry.name);
+        const result = await writeValues(agentDir, `${kind} channel`, entries, replace ? names : [], file);
+        unprotected ??= result.unprotectedSecretsDir;
+        for (const entry of entries)
+            held.set(entry.name, entry.value);
+        written.push(...names);
+    };
+    /**
+     * Whether this run has put an app's values in, or is about to: a value held beside them is an earlier app's (a token
+     * kept from one app must never go with the credentials of another), so it is asked for again.
+     */
+    let renewed = false;
+    const accept = async (step, values) => {
+        const note = await step.check(values);
+        renewed = true;
+        await keep(step.fields.map(({ name }) => ({ name, value: values[name] })), true);
+        say(`${step.fields.map((one) => one.name).join(", ")} saved to ${file}${note ? ` (${note})` : ""}`);
+    };
+    const pending = [];
+    /** Ask for the steps gathered so far, together: one page, however many tokens. */
+    const ask = async (steps) => {
+        if (steps.length === 0)
+            return;
+        if (person === undefined)
+            await askAtTerminal(steps, held, accept);
+        else
+            await askOnPage(kind, steps, held, accept, person);
+    };
+    const flush = () => ask(pending.splice(0));
+    for (const value of plan.values) {
+        if (value.kind === "make") {
+            if (held.has(value.name))
+                kept.push(value.name);
+            else
+                await keep([{ name: value.name, value: value.make() }], false);
+            continue;
+        }
+        if (value.kind === "create") {
+            if (value.names.every((name) => held.has(name))) {
+                kept.push(...value.names);
+                continue;
+            }
+            await flush();
+            renewed = true;
+            await keep(Object.entries(await value.create(person ?? terminalPerson)).map(([name, content]) => ({
+                name,
+                value: content,
+            })), true);
+            continue;
+        }
+        const names = value.fields.map((one) => one.name);
+        if (!renewed && pending.length === 0 && names.every((name) => held.has(name))) {
+            try {
+                const note = await value.check(Object.fromEntries(names.map((name) => [name, held.get(name)])));
+                kept.push(...names);
+                say(`${names.join(", ")} already set in ${file}${note ? ` (${note})` : ""} — keeping ${names.length > 1 ? "them" : "it"}`);
+                continue;
+            }
+            catch (error) {
+                if (!(error instanceof SetupRefused))
+                    throw error;
+                say(`${names.join(", ")} in ${file} is refused (${error.message}) — asking for another`);
+            }
+        }
+        if (value.capture === undefined) {
+            pending.push(value);
+            continue;
+        }
+        await flush();
+        const captured = await value.capture(held);
+        if (captured === undefined) {
+            await ask([value]);
+            continue;
+        }
+        await keep([{ name: names[0], value: captured }], true);
+        say(`${names[0]} captured and saved to ${file}`);
+    }
+    await flush();
+    if (unprotected !== undefined)
+        say(`note: ${unprotectedSecretsNote(unprotected, "where this instance keeps its values")}`);
+    return { written, kept, after: await plan.finish(held) };
+}
+const guideOf = (step, held) => typeof step.guide === "function" ? step.guide(held) : step.guide;
+async function askAtTerminal(steps, held, accept) {
+    for (const step of steps) {
+        const guide = guideOf(step, held);
+        clackLog.info(guide.instructions);
+        if (guide.url !== undefined) {
+            say(`opening ${guide.url}`);
+            openExternalUrl(guide.url);
+        }
+        for (;;) {
+            const values = {};
+            for (const one of step.fields) {
+                for (;;) {
+                    const message = `${one.label}`;
+                    const answer = one.secret === false ? await text({ message }) : await password({ message });
+                    if (isCancel(answer))
+                        throw new Error("setup cancelled");
+                    const pasted = String(answer).trim();
+                    if (pasted === "") {
+                        clackLog.error(`${one.label} is needed.`);
+                        continue;
+                    }
+                    values[one.name] = pasted;
+                    break;
+                }
+            }
+            try {
+                await accept(step, values);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof SetupRefused))
+                    throw error;
+                clackLog.error(`${error.message}${error.fix === undefined ? "" : ` ${error.fix}`}`);
+            }
+        }
+    }
+}
+async function askOnPage(kind, steps, held, accept, person) {
+    const product = PRODUCTS[kind];
+    const page = await startCredentialsPage({
+        title: `Connect ${product}`,
+        doneHeading: `${product} connected`,
+        steps: steps.map((step) => ({ label: step.label, guide: guideOf(step, held), fields: step.fields })),
+        accept: (index, values) => accept(steps[index], values),
+    });
+    const port = new URL(page.url).port;
+    try {
+        person.waitsOn(page.url, `paste ${steps.map((step) => step.label).join(" and ")} on this page. If the CLI runs remotely, forward this ` +
+            `loopback port to the same local port (SSH: ssh -N -L ${port}:127.0.0.1:${port} user@host), then open the ` +
+            "same URL in your browser. Keep the forwarding session open; never paste secrets into the conversation.");
+        await page.done;
+        person.carriesOn();
+    }
+    finally {
+        await page.close();
+    }
+}

package/dist/cli/commands/add.d.ts

@@ -1,22 +1,14 @@
 import { type ChannelKind } from "../../scaffold/add-channel.ts";
 export interface AddChannelOptions {
-    ingress?: string;
-    onboard?: boolean;
-    replaceConfig?: boolean;
-    environment?: string;
-    /** false ⇔ `--no-input`. */
-    input?: boolean;
     /** `--json`: the outcome as one JSON object on stdout. */
     json?: boolean;
-    /** `--check <ticket>`: where an app's setup started without a terminal stands. */
-    check?: string;
-    /** `--timeout <seconds>`: how long a setup started without a terminal stays open. */
-    timeout?: string;
-    /** `--ticket <id>`: the process that runs a ticket's setup. */
-    ticket?: string;
 }
-/** `fastagent add <kind> [dir]`: scaffold `src/channels/<kind>.ts`, the adapter configured with a starter policy. */
-export declare function runAddChannel(channelKind: ChannelKind, dirArg: string, opts: AddChannelOptions): Promise<void>;
+/**
+ * `add <channel>`: the program only (channel-setup.md §2). It writes the channel file and its tools and names the
+ * values they read in `.secrets/.env.example`; it asks nothing and creates no app. The app, and the values of the
+ * instance that runs it, are `channels setup`'s.
+ */
+export declare function runAddChannel(kind: ChannelKind, dirArg: string, opts: AddChannelOptions): Promise<void>;
 /** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
 export declare function runAddSkill(source: string | undefined, dirArg: string, opts: {
     update?: boolean;