@fastagent-sh/fastagent 0.13.0 → 0.14.0

package/dist/cli/serve.js

@@ -0,0 +1,90 @@
+import { createInvokeHandler } from "../channels/http.js";
+import { text } from "../channels/respond.js";
+import { loadChannels } from "../engines/pi/channel.js";
+import { reportModuleLoadFailures } from "../engines/pi/report.js";
+import { parseRouteKey, router, serveNode } from "../host/node.js";
+import { log } from "../log.js";
+import { openExternalUrl } from "../open-url.js";
+import { loadSchedules } from "../schedule/discover.js";
+import { createScheduler } from "../schedule/scheduler.js";
+import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
+import { failStartup } from "./fail.js";
+/**
+ * The routes this deployment serves: a default `GET /health` plus the workspace's discovered
+ * `channels/` — or the default invoke channel at POST /invoke when none are declared.
+ */
+export async function routesFor(workspaceDir, agent, stateRoot) {
+    const { routes, collisions, failures } = await loadChannels(workspaceDir, { agent, stateRoot });
+    for (const c of collisions) {
+        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
+    }
+    reportModuleLoadFailures(failures);
+    if (failures.length > 0 || collisions.length > 0) {
+        throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
+            `fix it, or rename an intentionally disabled file to *.disabled`);
+    }
+    const channels = Object.keys(routes).length > 0 ? routes : { "POST /invoke": createInvokeHandler(agent) };
+    // Add a default GET /health unless a channel already covers it (overlap, not exact-key: an
+    // any-method `/health` also handles GET, so the built-in steps aside).
+    const healthCovered = Object.keys(channels).some((k) => {
+        const e = parseRouteKey(k);
+        return e.path === "/health" && (e.method === undefined || e.method === "GET");
+    });
+    return healthCovered ? channels : { "GET /health": () => text("ok\n", 200), ...channels };
+}
+/** Serve `routes` via the Node host. serveNode owns binding; the CLI owns policy (errors, ready signal, log). */
+export function serve(routes, port, onListening) {
+    serveNode(router(routes), { port }).listening.then((boundPort) => {
+        process.send?.({ type: "ready", port: boundPort }); // tell the dev supervisor we bound + on which port
+        log.info(`[fastagent] http channel on :${boundPort}`);
+        log.info(`[fastagent] routes: ${Object.keys(routes).join(", ") || "(none)"}`);
+        onListening?.(boundPort);
+    }, (error) => {
+        if (error.code === "EADDRINUSE")
+            failStartup(new Error(`port ${port} is already in use; choose another with --port`));
+        failStartup(new Error(`cannot bind http channel on :${port}: ${error.message}`));
+    });
+}
+/**
+ * Start a Cloudflare tunnel + announce/register webhooks once the server is bound — unless this is a
+ * watch-supervisor worker, where the supervisor owns the long-lived tunnel so the public URL survives
+ * reloads.
+ */
+export function maybeTunnel(workspaceDir, boundPort, tunnel) {
+    if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
+        return;
+    void startCloudflareTunnel(boundPort).then((t) => {
+        if (!t)
+            return;
+        void announceWebhooks(workspaceDir, t.url, { openUrl: openExternalUrl });
+        // Single-process (start / --no-watch): close the tunnel on exit (watch mode's supervisor owns its own).
+        const cleanup = () => {
+            t.close();
+            process.exit(0);
+        };
+        process.once("SIGINT", cleanup);
+        process.once("SIGTERM", cleanup);
+    });
+}
+/**
+ * Load and start the workspace's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on (the scheduler also polls the agent's self-scheduled
+ * wake-ups, which the built-in `wake` tool creates only when opted in). Shares the SAME (trace-wrapped)
+ * agent the routes serve, so a scheduled turn is observed like any other. Best-effort stop on exit; dev's
+ * watch restart re-reads schedules with the worker (schedules are a code input). Single-process.
+ */
+export async function startSchedules(workspaceDir, agent, stateRoot, selfSchedule) {
+    const { schedules, failures } = await loadSchedules(workspaceDir).catch(failStartup);
+    reportModuleLoadFailures(failures);
+    // Nothing to run when there are neither static `schedules/` nor self-scheduling (the `wake` tool, and
+    // thus any wake-up to poll, is mounted only when config.selfSchedule is on) — skip the poller entirely.
+    if (schedules.length === 0 && !selfSchedule)
+        return;
+    const scheduler = createScheduler({ agent, stateRoot, schedules });
+    scheduler.start();
+    if (schedules.length > 0)
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
+    const stop = () => scheduler.stop();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}

package/dist/cli/shared.d.ts

@@ -0,0 +1,24 @@
+/** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
+export declare function isInteractive(): boolean;
+/**
+ * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
+ * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
+ * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
+ * bad `PORT` env is broken runtime configuration (1).
+ */
+export declare function parsePort(value: string | undefined, source: string, from: "flag" | "env"): number | undefined;
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
+export declare function reportAuth(modelSpec: string, authPath: string): Promise<void>;
+/**
+ * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
+ * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
+ * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
+ * configured it stays silent and lets the opener raise its clear "missing model" error. The pick is
+ * exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it, and best-effort written back to
+ * the config so the next run is quiet.
+ */
+export declare function resolveFirstRunModel(workspaceDir: string, options?: {
+    model?: string;
+    authPath?: string;
+    input?: boolean;
+}): Promise<void>;

package/dist/cli/shared.js

@@ -0,0 +1,116 @@
+/**
+ * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report,
+ * and first-run model resolution. Bodies moved verbatim from cli.ts; the module-scoped flag access
+ * (`values.*`) became parameters.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { autocomplete, isCancel, select } from "@clack/prompts";
+import { fastagentCredentialStore } from "../engines/pi/auth.js";
+import { isValidPort, loadConfig, resolveAuthPath, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
+import { configuredModelSpecs, createPiModels, probeAuthSource } from "../engines/pi/models.js";
+import { formatAuthReport } from "../cli-auth.js";
+import { log } from "../log.js";
+import { failStartup, failUsage } from "./fail.js";
+/** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
+ * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
+ * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
+ * bad `PORT` env is broken runtime configuration (1).
+ */
+export function parsePort(value, source, from) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    if (!/^\d+$/.test(trimmed) || !isValidPort(Number(trimmed))) {
+        const message = `invalid ${source} "${value}": must be an integer 0-65535`;
+        if (from === "flag")
+            failUsage(message);
+        failStartup(new Error(message));
+    }
+    return Number(trimmed);
+}
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking. */
+export async function reportAuth(modelSpec, authPath) {
+    const provider = modelSpec.slice(0, modelSpec.indexOf("/"));
+    const source = await probeAuthSource(createPiModels({ authPath }), modelSpec);
+    // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
+    // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
+    const stored = source === undefined
+        ? await fastagentCredentialStore(authPath)
+            .read(provider)
+            .catch(() => undefined)
+        : undefined;
+    const report = formatAuthReport(provider, authPath, source, stored);
+    log.info(`[fastagent] ${report.line}`);
+    if (report.warn)
+        log.warn(`[fastagent] ${report.warn}`);
+}
+/**
+ * First-run model resolution for the serving commands. When no model is set (flag/env/config), and
+ * we're on a TTY, pick one from the providers the user is logged into and persist the choice. A no-op
+ * when a model is already set; on a non-TTY (CI/deploy), or with `--no-input`, or with nothing
+ * configured it stays silent and lets the opener raise its clear "missing model" error. The pick is
+ * exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it, and best-effort written back to
+ * the config so the next run is quiet.
+ */
+export async function resolveFirstRunModel(workspaceDir, options = {}) {
+    const { config, path: configPath } = await loadConfig(workspaceDir).catch(failStartup);
+    if (resolveModelSpec(options.model, config))
+        return; // already set (flag > FASTAGENT_MODEL > config)
+    if (options.input === false)
+        return; // --no-input: never prompt (clig) — the opener raises the clear error
+    if (!isInteractive())
+        return; // CI/deploy: the opener throws the actionable missing-model error
+    const authPath = resolveAuthPath(workspaceDir, options.authPath);
+    let specs;
+    try {
+        specs = await configuredModelSpecs(createPiModels({ authPath }));
+    }
+    catch (error) {
+        // Enumerating providers/auth threw — a system fault (a corrupt auth store, a throwing provider),
+        // NOT "not logged in". Surface it instead of masking it as the login hint; the opener then still
+        // raises the clear missing-model error.
+        log.warn(`[fastagent] could not list configured models: ${error.message}`);
+        return;
+    }
+    if (specs.length === 0) {
+        log.warn(`[fastagent] no model set and no authenticated provider — run \`fastagent login\`, then \`fastagent dev\``);
+        return;
+    }
+    const r = await (specs.length > 7 ? autocomplete : select)({
+        message: "Choose a model for this agent",
+        options: specs.map((s) => ({ value: s, label: s })),
+    });
+    if (isCancel(r))
+        return; // cancelled: let the opener report the missing model
+    const chosen = r;
+    process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
+    await persistModelChoice(workspaceDir, configPath, chosen);
+}
+/**
+ * Best-effort persist the picked model so the next run does not prompt. Only rewrites the commented
+ * `model:` placeholder the scaffold writes (or an existing `model:` line); anything else (zero-config,
+ * a hand-shaped config) is left untouched with a printed hint. Never throws — persistence is a convenience.
+ */
+async function persistModelChoice(workspaceDir, configPath, spec) {
+    const hint = () => console.error(`[fastagent] using ${spec} for this run; set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
+    if (!configPath)
+        return hint();
+    try {
+        const replaced = rewriteConfigModel(await readFile(configPath, "utf8"), spec);
+        if (!replaced)
+            return hint();
+        await writeFile(configPath, replaced);
+        console.error(`[fastagent] saved model ${JSON.stringify(spec)} to ${relative(workspaceDir, configPath)}`);
+    }
+    catch {
+        hint();
+    }
+}