@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/cli/commands/add.js

@@ -1,51 +1,124 @@
 /**
- * `fastagent add <channel>|skill` — scaffold channel glue (`channels/<kind>.ts`) or vendor an Agent Skills skill.
+ * `fastagent add <channel>|skill` — scaffold channel glue (`src/channels/<kind>.ts`) or vendor an Agent Skills skill.
  * slack/feishu/lark additionally CREATE OR RESUME the platform app.
  */
 import { randomBytes } from "node:crypto";
-import { readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
-import { isCancel, select } from "@clack/prompts";
-import { onboardFeishuCloudApp } from "../add-feishu.js";
-import { dotEnvPath, enterAgentEnv } from "../../env.js";
-import { resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath } from "../../paths.js";
+import { assertIndependentFeishuApps, larkCredentialsNeeded, onboardFeishuCloudApp } from "../add-feishu.js";
+import { terminalPerson } from "../person.js";
+import { isInteractive, shellArg } from "../shared.js";
+import { checkTicket, printReport, refusedCheck, runTicket, startTicket, ticketExitCode, ticketReport, } from "../ticket.js";
+import { cloudFor } from "../../channels/feishu/cloud.js";
+import { feishuIngressFor } from "../../channels/feishu/setup-mode.js";
+import { markDevServe, unmarkDevServe } from "../../serving-command.js";
+import { channelIngress } from "../../channels/discover.js";
+import { buildDefinitionShape, prepareDefinition } from "../../harnesses/pi-durable/open.js";
+import { dotEnvPath, enterAgentEnv, loadEnvValues } from "../../env.js";
+import { selectAgentEnvironment, resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, scaffoldCompanionTools, } from "../../scaffold/add-channel.js";
 import { vendorSkill } from "../../scaffold/vendor-skill.js";
-import { failStartup, failUsage, placementOrExit } from "../fail.js";
-/** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
+import { failStartup, failUsage, agentDirOrExit } from "../fail.js";
+import { unprotectedSecretsNote } from "../../value-file.js";
+/** Without a terminal, how long an app's setup stays open for the person to finish their part. */
+const UNATTENDED_TIMEOUT_SECONDS = 900;
+/** `fastagent add <kind> [dir]`: scaffold `src/channels/<kind>.ts`, the adapter configured with a starter policy. */
 export async function runAddChannel(channelKind, dirArg, opts) {
-    // The channel (glue + companion tool + secrets) is agent surface — everything lands in the AGENT DIR
-    // (`fastagent/`), the same place dev/start discover channels/.
+    if (opts.check !== undefined)
+        return checkSetup(channelKind, opts.check, opts);
+    if (opts.ticket !== undefined) {
+        // The process `startTicket` started: it takes the ticket before anything slow (the definition is built to plan),
+        // then does the whole `add`, its person the ticket's.
+        await runTicket(opts.ticket, async (step) => ({
+            ...(await addChannel(channelKind, await planAdd(channelKind, dirArg, opts), opts, step.person)),
+        }));
+        process.exit(0);
+    }
+    const plan = await planAdd(channelKind, dirArg, opts);
+    const unattended = opts.input === false || opts.json === true || !isInteractive();
+    if (unattended && opts.onboard !== false && channelKind !== "telegram") {
+        return setUpUnattended(channelKind, opts, plan);
+    }
+    const added = await addChannel(channelKind, plan, opts, terminalPerson).catch(failStartup);
+    if (opts.json)
+        console.log(JSON.stringify({ status: "done", ...added }, null, 2));
+    // App-creation flows leave platform/tunnel sockets behind that would otherwise hold the one-shot scaffold command
+    // open after all durable boundaries have completed.
+    process.exit(0);
+}
+/** What `add` settles before it changes anything, refusing what it can while nothing has changed. */
+async function planAdd(channelKind, dirArg, opts) {
+    // The channel (glue + companion tools + secrets) is agent surface: everything lands in the AGENT DIR.
     if (opts.replaceConfig && opts.onboard === false) {
         failUsage("--replace-config replaces onboarding credentials; it cannot be combined with --no-onboard");
     }
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
-    enterAgentEnv(target); // onboarding state follows the same FASTAGENT_STATE_DIR as serving/deploy
-    // Paths are printed to someone standing in their CWD, usually the workspace, while every file belongs to the AGENT
+    const target = agentDirOrExit(resolve(dirArg));
+    const environment = opts.environment ?? "dev";
+    if (environment !== "dev" && environment !== "production") {
+        failUsage(`--env must be "dev" or "production", got "${environment}"`);
+    }
+    selectAgentEnvironment(environment);
+    if (environment === "production")
+        unmarkDevServe();
+    else
+        markDevServe();
+    enterAgentEnv(target);
+    if (environment === "production" && (channelKind === "feishu" || channelKind === "lark")) {
+        try {
+            assertIndependentFeishuApps(target, [channelKind], loadEnvValues(dotEnvPath(target)));
+        }
+        catch (error) {
+            failStartup(error);
+        }
+    }
+    // Paths are printed to someone standing in their CWD, which may be elsewhere, while every file belongs to the AGENT
     // dir — prefix them, or they point at nothing.
     const agentFromCwd = displayPath(process.cwd(), target);
     const inAgent = (p) => (agentFromCwd === undefined ? p : join(agentFromCwd, p));
-    const envPath = dotEnvPath(target);
-    const envLabel = isUnderDir(envPath, target) ? inAgent(relative(target, envPath)) : envPath;
     // An existing channel file is authored glue: kept, never rewritten.
-    const file = join(target, "channels", `${channelKind}.ts`);
+    const file = join(target, "src", "channels", `${channelKind}.ts`);
     const existsAlready = await channelExists(target, channelKind).catch(failStartup);
-    const ingress = await resolveIngress(channelKind, file, existsAlready, opts.ingress);
-    const groupBehavior = await resolveGroupBehavior(channelKind, opts.groupBehavior);
+    const ingress = resolveIngress(channelKind, opts.ingress);
+    if (existsAlready &&
+        (ingress.setting || (environment === "production" && opts.onboard !== false)) &&
+        (channelKind === "feishu" || channelKind === "lark")) {
+        await assertChannelReadsSetting(target, channelKind, ingress.setting ?? { [`${cloudFor(channelKind).envPrefix}_INGRESS`]: ingress.ingress }, inAgent(relative(target, file)));
+    }
+    return {
+        target,
+        environment,
+        inAgent,
+        agentFromCwd,
+        file,
+        existsAlready,
+        ...ingress,
+        rerun: `fastagent add ${channelKind}${agentFromCwd === undefined ? "" : ` ${shellArg(agentFromCwd)}`}` +
+            `${environment === "production" ? " --env production" : ""}${opts.ingress ? ` --ingress ${opts.ingress}` : ""}` +
+            `${opts.replaceConfig ? " --replace-config" : ""}`,
+    };
+}
+/**
+ * Everything `add <kind>` does once the person's part can be done: the channel, its tools and variables, the app's
+ * onboarding through `person`, and the next steps, printed and returned with the variables it wrote.
+ */
+async function addChannel(channelKind, plan, opts, person) {
+    const { target, environment, inAgent, agentFromCwd, file, existsAlready, ingress, pinned, setting, rerun } = plan;
+    const envPath = dotEnvPath(target);
+    const envLabel = isUnderDir(envPath, target) ? inAgent(relative(target, envPath)) : envPath;
+    const before = loadEnvValues(envPath);
     if (existsAlready) {
-        console.error(`[fastagent] ${relative(target, file)} already exists — keeping it`);
+        console.error(`[fastagent] ${inAgent(relative(target, file))} already exists — keeping it`);
     }
     else {
-        await assertChannelReady(target).catch(failStartup);
-        await scaffoldChannel(target, channelKind, { ingress }).catch(failStartup);
-        console.error(`[fastagent] created ${relative(target, file)}`);
+        await assertChannelReady(target);
+        await scaffoldChannel(target, channelKind);
+        console.error(`[fastagent] created ${inAgent(relative(target, file))}`);
     }
     // Companion tools are the package's, not authored glue.
-    for (const tool of await scaffoldCompanionTools(target, channelKind).catch(failStartup)) {
-        console.error(`[fastagent] wrote ${relative(target, tool)}`);
+    for (const tool of await scaffoldCompanionTools(target, channelKind)) {
+        console.error(`[fastagent] wrote ${inAgent(relative(target, tool))}`);
     }
-    if (await appendChannelEnv(target, channelKind, ingress).catch(failStartup)) {
+    if (await appendChannelEnv(target, channelKind)) {
         console.error(`[fastagent] added ${channelKind} env vars to ${inAgent(join(SECRETS_DIRNAME, ".env.example"))}`);
     }
     // Stateful app onboarding is re-runnable after the scaffold boundary.
@@ -55,163 +128,201 @@ export async function runAddChannel(channelKind, dirArg, opts) {
         created = await onboardSlackInternalApp({
             target,
             stateRoot: resolveStateRoot(target),
-            groupBehavior,
             replaceConfig: opts.replaceConfig,
-        })
-            .then(() => undefined)
-            .catch(failStartup);
+            ...(person === terminalPerson ? {} : { person }),
+        }).then(() => undefined);
     }
-    else if (channelKind === "feishu" || channelKind === "lark") {
-        created = await onboardFeishuCloudApp(target, channelKind, ingress, groupBehavior).catch(failStartup);
+    else if ((channelKind === "feishu" || channelKind === "lark") && opts.onboard !== false) {
+        created = await onboardFeishuCloudApp(target, channelKind, ingress, rerun, person);
     }
-    const setup = channelSetup(channelKind, ingress, groupBehavior.behavior);
+    const setup = channelSetup(channelKind, ingress, pinned);
     const env = setup.env;
     const steps = channelKind === "slack" && opts.onboard !== false
         ? [
             // No line about the Request URL: the `dev --tunnel` line below is the whole instruction, and FastAgent sets
             // that URL itself when the agent first runs.
             "invite the app to each channel it should read",
-            "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
+            // The tool lines are the scaffold's (one list), whichever path set the app up.
+            ...setup.steps.filter((step) => step.includes("{tools}/")),
         ]
         : setup.steps;
     const generated = Object.fromEntries(env.filter((e) => e.generate).map((e) => [e.name, randomBytes(24).toString("hex")]));
     // Kind-neutral: every channel's generated secrets get the same treatment.
-    const dotEnv = await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {}), ingress).catch(failStartup);
+    const dotEnv = await appendChannelDotEnv(target, channelKind, { ...generated, ...created, ...setting }, [...Object.keys(created ?? {}), ...Object.keys(setting ?? {})], ingress);
     if (dotEnv.unprotectedSecretsDir) {
-        console.error(`[fastagent] note: ${dotEnv.unprotectedSecretsDir} (FASTAGENT_SECRETS_DIR) now holds a secret and has ` +
-            `no .gitignore — that directory is yours, so fastagent will not write one into it. Make sure git ` +
-            `does not track what is in there.`);
+        console.error(`[fastagent] note: ${unprotectedSecretsNote(dotEnv.unprotectedSecretsDir)}`);
     }
     if (dotEnv.written.length > 0) {
         console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to ${envLabel}`);
     }
-    const install = detectRuntime(target, await readPackageJson(target).catch(failStartup)).runtime === "bun"
-        ? "bun install"
-        : "npm install";
+    const install = detectRuntime(target, await readPackageJson(target)).runtime === "bun" ? "bun install" : "npm install";
+    const next = [];
+    /** One next step: printed, and returned for a caller that reads them as data. */
+    const step = (line) => {
+        next.push(line.trim());
+        console.error(`    ${line}`);
+    };
     console.error(`  next steps:`);
-    console.error(`    ${agentFromCwd === undefined ? install : `(cd ${agentFromCwd} && ${install})`}                      # if @fastagent-sh/fastagent is not installed yet`);
+    step(`${agentFromCwd === undefined ? install : `(cd ${agentFromCwd} && ${install})`}                      # if @fastagent-sh/fastagent is not installed yet`);
+    // Onboarding writes some itself (an app's ID and secret, a bot token) before the write above: what this `add` wrote is
+    // what the file holds now and did not before.
+    const now = loadEnvValues(envPath);
+    const written = [...now.keys()].filter((name) => now.get(name) && now.get(name) !== before.get(name));
     for (const e of env) {
-        if (dotEnv.alreadySet.includes(e.name))
-            continue; // the user already has it — nothing to do
-        if (dotEnv.written.includes(e.name)) {
+        if (!written.includes(e.name) && dotEnv.alreadySet.includes(e.name))
+            continue; // the user's already: nothing to do
+        if (written.includes(e.name)) {
             // Written, but its hint may still carry an action — keep the variable visible instead of silently absorbing it.
-            console.error(`    ${e.name} — ${e.generate ? "generated and " : ""}written to ${envLabel}   # ${e.hint}`);
+            step(`${e.name} — ${e.generate ? "generated and " : ""}written to ${envLabel}   # ${e.hint}`);
             continue;
         }
         const value = e.generate ? `=${generated[e.name]}` : "";
         const action = e.required ? "set" : "optionally set";
-        console.error(`    ${action} ${e.name}${value} in ${envLabel}   # ${e.hint}`);
+        step(`${action} ${e.name}${value} in ${envLabel}   # ${e.hint}`);
     }
-    // Steps carry `{channel}`/`{tools}` path placeholders (their filenames are the scaffold's private knowledge) —
-    // resolve them to the real agent-dir-relative locations here.
+    const serveCommand = environment === "production" ? "fastagent start" : "fastagent dev";
     for (const s of steps) {
-        console.error(`    ${s.replace("{channel}", inAgent(relative(target, file))).replace("{tools}", inAgent("tools"))}`);
+        step(s
+            .replace("{channel}", inAgent(relative(target, file)))
+            .replace("{tools}", inAgent(join("src", "tools")))
+            .replaceAll("{serve}", serveCommand));
     }
-    if (ingress === "websocket") {
-        console.error(`    fastagent dev            # no public URL or tunnel required`);
+    if (environment === "production") {
+        step(`fastagent deploy <host> --run   # deploy with the production app and credentials`);
+    }
+    else if (ingress === "websocket") {
+        step(`fastagent dev            # no public URL or tunnel required`);
     }
     else if (channelKind === "slack") {
-        console.error(`    fastagent dev --tunnel   # ${opts.onboard === false ? "serve locally + print the URL to paste into the Slack app's Event Subscriptions" : "start the agent — then message it in Slack"}`);
+        step(`fastagent dev --tunnel   # ${opts.onboard === false ? "serve locally + print the URL to paste into the Slack app's Event Subscriptions" : "start the agent — then message it in Slack"}`);
     }
     else if (channelKind !== "lark") {
-        console.error(`    fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
+        step(`fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
     }
-    // App-creation flows leave platform/tunnel sockets behind that would otherwise hold the one-shot scaffold command
-    // open after all durable boundaries have completed.
-    process.exit(0);
+    return { written, next_steps: next };
 }
-async function resolveIngress(kind, file, existsAlready, raw) {
+/** The command that reads an app's setup ticket, as every such ticket records it. */
+const setupCheck = (kind) => `fastagent add ${kind} --check`;
+/** What the person does for each kind's app, to follow "so they can". */
+const SETUP_ACTIONS = {
+    slack: "set up the Slack app: paste a configuration token on the page, then click Allow in Slack",
+    feishu: "confirm the new Feishu app",
+    lark: "finish setting up the Lark app",
+};
+/**
+ * `add slack|feishu|lark` with no one at a terminal to ask, for a coding agent: what the person must provide first is
+ * named (Lark's app credentials, in the file the agent reads), never asked for in the agent's conversation; then the
+ * app's setup runs in a process of its own (ticket.ts), and the command returns once the person has a step to take, it
+ * is done, or it is still working at it.
+ */
+async function setUpUnattended(kind, opts, at) {
+    const { target } = at;
+    if (kind === "lark") {
+        const needed = await larkCredentialsNeeded(target, at.rerun).catch(failStartup);
+        if (needed !== undefined) {
+            printReport(opts.json, needed.json, needed.text);
+            process.exit(0);
+        }
+    }
+    const timeout = opts.timeout === undefined ? UNATTENDED_TIMEOUT_SECONDS : Number(opts.timeout);
+    if (!Number.isInteger(timeout) || timeout <= 0)
+        failUsage(`--timeout must be a whole number of seconds`);
+    const ticket = await startTicket({
+        // One setup per agent, channel and environment: another agent's is its own business.
+        subject: `add:${kind}:${at.environment}:${target}`,
+        action: SETUP_ACTIONS[kind],
+        check: setupCheck(kind),
+        restart: at.rerun,
+        timeoutSeconds: timeout,
+        waitsFirst: false,
+        whenRunning: "replace",
+        command: {
+            file: process.execPath,
+            args: [
+                ...process.execArgv,
+                process.argv[1],
+                "add",
+                kind,
+                target,
+                ...(at.environment === "production" ? ["--env", "production"] : []),
+                ...(opts.ingress === undefined ? [] : ["--ingress", opts.ingress]),
+                ...(opts.replaceConfig ? ["--replace-config"] : []),
+            ],
+            cwd: process.cwd(),
+        },
+    });
+    reportSetup(ticket, opts, "started");
+    process.exit(ticketExitCode(ticket));
+}
+/** `add <kind> --check <ticket>`. */
+async function checkSetup(kind, id, opts) {
+    const refused = refusedCheck(id, setupCheck(kind));
+    if (refused !== undefined)
+        failUsage(refused);
+    // There: refusedCheck read it, and a ticket is pruned only a day after it ends.
+    const ticket = (await checkTicket(id));
+    reportSetup(ticket, opts, "checked");
+    process.exit(ticketExitCode(ticket));
+}
+/** An app's setup ticket for whoever started or checked it: the shared report, and what a finished setup adds. */
+function reportSetup(ticket, opts, when) {
+    const { json, text } = ticketReport(ticket, when, (result) => {
+        const written = result.written ?? [];
+        const next = result.next_steps ?? [];
+        return {
+            fields: { written, next_steps: next },
+            text: [...(written.length > 0 ? [`wrote ${written.join(", ")}`] : []), ...next.map((line) => `next: ${line}`)],
+            next: `The app is set up. Its next steps are in next_steps.`,
+        };
+    });
+    printReport(opts.json, json, text);
+}
+/**
+ * What `add` sets the app up for, and whether it writes the choice down. `--ingress` is the `<PREFIX>_INGRESS`
+ * setting in the selected environment. The channel rule supplies its default: WebSocket in dev, webhook in production.
+ */
+function resolveIngress(kind, raw) {
     if (raw !== undefined && raw !== "webhook" && raw !== "websocket") {
         failUsage(`--ingress must be "webhook" or "websocket", got "${raw}"`);
     }
-    const requested = raw;
     if (kind !== "feishu" && kind !== "lark")
-        return "webhook";
-    if (existsAlready) {
-        const source = await readFile(file, "utf8").catch(failStartup);
-        const factory = source.match(/\b(?:feishu|lark)(WebSocket)?Channel\s*\(/);
-        const existing = factory
-            ? factory[1] === "WebSocket"
-                ? "websocket"
-                : "webhook"
-            : undefined;
-        if (!existing) {
-            if (!requested) {
-                failUsage(`${file} uses an unrecognized channel factory — re-run with --ingress webhook|websocket to confirm its mode`);
-            }
-            return requested;
-        }
-        if (requested && requested !== existing) {
-            failStartup(new Error(`${file} already selects ${existing} delivery — changing mode is a migration; edit the factory and platform subscription together`));
-        }
-        return existing;
-    }
-    if (requested)
-        return requested;
-    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
-        console.error(`[fastagent] no interactive terminal — defaulting ${kind} ingress to webhook (use --ingress websocket)`);
-        return "webhook";
-    }
-    const answer = await select({
-        message: `How should ${kind === "feishu" ? "Feishu" : "Lark"} deliver events?`,
-        // The default must match the non-interactive branch above.
-        initialValue: "webhook",
-        options: [
-            {
-                value: "webhook",
-                label: "Webhook endpoint",
-                hint: "works on every deploy target; supports scale-to-zero; requires a public HTTPS URL",
-            },
-            {
-                value: "websocket",
-                label: "WebSocket long connection",
-                hint: "no public URL; needs an always-on process (not on AgentCore)",
-            },
-        ],
-    });
-    if (isCancel(answer))
-        failStartup(new Error(`${kind} onboarding cancelled`));
-    return answer;
+        return { ingress: "webhook", pinned: false };
+    const name = `${cloudFor(kind).envPrefix}_INGRESS`;
+    if (raw !== undefined)
+        return { ingress: raw, pinned: true, setting: { [name]: raw } };
+    try {
+        return {
+            ingress: feishuIngressFor(kind, process.env),
+            pinned: Boolean(process.env[name]?.trim()),
+        };
+    }
+    catch (error) {
+        // A malformed value in the environment: the author's to fix, said as the rule says it.
+        return failUsage(error.message);
+    }
 }
-async function resolveGroupBehavior(kind, raw) {
-    if (raw !== undefined && raw !== "context" && raw !== "mentions") {
-        failUsage(`--group-behavior must be "context" or "mentions", got "${raw}"`);
+/**
+ * A setting only takes effect in a channel file that reads it: one that names its factory receives the same way
+ * whatever the setting says, so writing the setting (and configuring the app for it) would change nothing but the app.
+ * Asked of the channel as the agent builds it, under the value this command is about to write.
+ */
+async function assertChannelReadsSetting(target, kind, setting, shown) {
+    Object.assign(process.env, setting); // the value this command writes anyway
+    const channel = await prepareDefinition(target)
+        .then((definition) => buildDefinitionShape(definition, process.env).channels.get(kind))
+        .catch((error) => failStartup(new Error(`the agent does not build (${error.message}) — fix it and re-run`)));
+    const [[name, value]] = Object.entries(setting);
+    const wanted = value === "webhook" ? "webhook" : "long-connection";
+    const shape = channel === undefined ? undefined : channelIngress(channel);
+    if (shape !== wanted) {
+        failStartup(new Error(`${shown} receives by ${shape === "webhook" ? "webhook" : "WebSocket"} whatever ${name} says — it names ` +
+            `its factory instead of reading the setting, so ${name}=${value} would change nothing but the app. Move ` +
+            `the file aside and re-run to scaffold one that reads it, or edit its factory yourself`));
     }
-    if (kind !== "feishu" && kind !== "lark" && kind !== "slack")
-        return { behavior: "context", explicit: false };
-    if (raw !== undefined)
-        return { behavior: raw, explicit: true };
-    const defaultBehavior = "context";
-    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
-        console.error(`[fastagent] no interactive terminal — assuming ${kind} group behavior ${defaultBehavior}; pass --group-behavior explicitly to override`);
-        return { behavior: defaultBehavior, explicit: false };
-    }
-    const choices = [
-        {
-            value: "context",
-            label: "Context-aware groups (recommended)",
-            hint: kind === "slack"
-                ? "bare replies in the Agent's threads + buffer; requires channel/group/mpim history scopes"
-                : "bare replies in the Agent's threads + buffer; im:message.group_msg delivers all group messages",
-        },
-        {
-            value: "mentions",
-            label: "Mention-only (least privilege)",
-            hint: "only explicit @Agent messages; no group-wide message permission",
-        },
-    ];
-    const answer = await select({
-        message: "Choose group-chat behavior",
-        initialValue: defaultBehavior,
-        options: choices,
-    });
-    if (isCancel(answer))
-        failStartup(new Error(`${kind} onboarding cancelled`));
-    return { behavior: answer, explicit: true };
 }
 /** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
 export async function runAddSkill(source, dirArg, opts) {
-    const { agentDir: target } = placementOrExit(resolve(dirArg));
+    const target = agentDirOrExit(resolve(dirArg));
     if (!source) {
         // A missing source is a usage error (exit 2), but the guide is worth more than a bare missing-argument line.
         failUsage(`add a skill — two ways:\n` +
@@ -225,7 +336,7 @@ export async function runAddSkill(source, dirArg, opts) {
     }
     // Skills are agent surface — vendored into the agent dir's `skills/`.
     enterAgentEnv(target); // a git-ref source is a network fetch (giget uses global fetch)
-    const { name, description, dest, hasScripts, diagnostics, overwritten } = await vendorSkill(target, source, {
+    const { name, description, dest, hasScripts, overwritten } = await vendorSkill(target, source, {
         update: opts.update ?? false,
     }).catch(failStartup);
     console.error(`[fastagent] ${overwritten ? "updated" : "vendored"} skill "${name}" → ${dest}/`);
@@ -233,10 +344,8 @@ export async function runAddSkill(source, dirArg, opts) {
         console.error(`  overwrote it — \`git diff ${dest}\` to review, \`git checkout ${dest}\` to revert`);
     if (description)
         console.error(`  ${description.length > 100 ? `${description.slice(0, 100)}…` : description}`);
-    for (const d of diagnostics)
-        console.error(`  warn: ${d.message}`);
     if (hasScripts) {
         console.error(`  warn: this skill ships scripts/ (executable code that runs in your agent) — review it before deploying`);
     }
-    console.error(`  next: mention "${name}" in APPEND_SYSTEM.md so the model knows when to use it; then \`fastagent dev\``);
+    console.error(`  next: mention "${name}" in SYSTEM.md so the model knows when to use it; then \`fastagent dev\``);
 }

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

@@ -0,0 +1,6 @@
+export declare function runAuthCheck(opts: {
+    provider?: string;
+    model?: string;
+    global?: boolean;
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/commands/auth.js

@@ -0,0 +1,50 @@
+import { enterAgentEnv } from "../../env.js";
+import { modelEnvironment } from "../../harnesses/models/environment.js";
+import { providerOf } from "../../harnesses/models/models.js";
+import { definitionProviders } from "../../harnesses/pi-durable/open.js";
+import { installProxyFetch } from "../../proxy.js";
+import { failStartup, failUsage, optionalAgentDirOrExit } from "../fail.js";
+const EXIT_CODES = { ready: 0, not_ready: 1, invalid: 2 };
+export async function runAuthCheck(opts) {
+    if (opts.provider === undefined && opts.model === undefined) {
+        failUsage("auth check needs --provider <id> or --model <provider/modelId>");
+    }
+    const agentDir = opts.global ? undefined : optionalAgentDirOrExit(process.cwd());
+    let providers = [];
+    if (agentDir) {
+        enterAgentEnv(agentDir);
+        providers = await definitionProviders(agentDir).catch(failStartup);
+    }
+    else {
+        installProxyFetch();
+    }
+    const environment = await modelEnvironment(agentDir, {}, providers);
+    let provider = opts.provider;
+    let modelId;
+    if (opts.model !== undefined) {
+        const ofModel = providerOf(opts.model);
+        modelId = opts.model.slice(ofModel.length + 1);
+        if (modelId === "" || environment.models.getModel(ofModel, modelId) === undefined) {
+            failUsage(`unknown model "${opts.model}": \`fastagent models\` lists the ones there are`);
+        }
+        if (provider !== undefined && provider !== ofModel)
+            failUsage(`${opts.model} is not a model of ${provider}`);
+        provider = ofModel;
+    }
+    const result = await check(environment, provider, modelId);
+    console.log(opts.json ? JSON.stringify(result) : result.status);
+    process.exitCode = EXIT_CODES[result.status];
+}
+async function check(environment, provider, modelId) {
+    if (environment.models.getProvider(provider) === undefined) {
+        return { status: "not_ready", provider, reason: "provider_not_found" };
+    }
+    const held = await environment.authStatus(provider, modelId);
+    const path = held.path === undefined ? {} : { path: held.path };
+    if (held.error !== undefined)
+        return { status: "invalid", provider, reason: "invalid_state", error: held.error, ...path };
+    if (held.source === undefined)
+        return { status: "not_ready", provider, reason: "credentials_not_configured", ...path };
+    const authType = held.source === "OAuth" ? "oauth" : "api_key";
+    return { status: "ready", provider, authType, source: held.source, ...path };
+}

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

@@ -0,0 +1,6 @@
+import { type SourceOptions } from "../../content/source.ts";
+/** A name refusal is the caller's to fix by naming another (exit 2); anything else is a startup failure (exit 1). */
+export declare function failEdit(hint: string): (error: unknown) => never;
+export declare function runContentList(dirArg: string, json: boolean): Promise<void>;
+export declare function runContentAdd(source: string, dirArg: string, opts: SourceOptions): Promise<void>;
+export declare function runContentRemove(name: string, dirArg: string): Promise<void>;

package/dist/cli/commands/content.js

@@ -0,0 +1,45 @@
+/**
+ * `fastagent content list|add|remove`: what the agent works on and knows, as `context.json` declares it and
+ * `context.local.json` binds it on this machine.
+ */
+import { resolve } from "node:path";
+import { ContentNameError, addContent, listContent, removeContent } from "../../authoring.js";
+import { readContentSource } from "../../content/source.js";
+import { contentLines } from "../content-view.js";
+import { failStartup, failUsage } from "../fail.js";
+/** A name refusal is the caller's to fix by naming another (exit 2); anything else is a startup failure (exit 1). */
+export function failEdit(hint) {
+    return (error) => {
+        if (error instanceof ContentNameError)
+            failUsage(`${error.message}${hint}`);
+        failStartup(error);
+    };
+}
+export async function runContentList(dirArg, json) {
+    const { content, absent } = await listContent(resolve(dirArg)).catch(failStartup);
+    if (json) {
+        console.log(JSON.stringify({ content, absent }, null, 2));
+        return;
+    }
+    for (const [label, value] of contentLines(content, absent))
+        console.log(`${`${label}:`.padEnd(10)} ${value}`);
+}
+export async function runContentAdd(source, dirArg, opts) {
+    const { addition, notes } = await Promise.resolve()
+        .then(() => readContentSource(source, process.cwd(), opts))
+        .catch(failStartup);
+    for (const note of notes)
+        console.error(`[fastagent] ${note}`);
+    const { name, content, notes: left } = await addContent(resolve(dirArg), addition).catch(failEdit(" — pass --name"));
+    const added = content.filter((entry) => entry.name === name);
+    for (const [label, value] of contentLines(added))
+        console.error(`[fastagent] ${label} ${value}`);
+    for (const note of left)
+        console.error(`[fastagent] ${note}`);
+}
+export async function runContentRemove(name, dirArg) {
+    const removed = await removeContent(resolve(dirArg), name).catch(failEdit(""));
+    console.error(`[fastagent] removed content ${removed.name}`);
+    for (const note of removed.notes)
+        console.error(`[fastagent] ${note}`);
+}