@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/cli/commands/init.js

@@ -1,45 +1,47 @@
-/** `fastagent init [dir]`: scaffold a runnable agent and install its dependencies. */
+/** `fastagent init <dir> [--content <dir>]...`: scaffold a runnable agent and install its dependencies. */
 import { spawn } from "node:child_process";
-import { basename, resolve } from "node:path";
-import { DEFAULT_AGENT_DIRNAME, agentsAt, displayPath } from "../../paths.js";
-import { agentDirName, agentDirNameError, scaffoldAgent } from "../../scaffold/init.js";
-import { failStartup, failUsage } from "../fail.js";
+import { resolve } from "node:path";
+import { displayPath } from "../../paths.js";
+import { initAgent } from "../../authoring.js";
+import { readContentSource } from "../../content/source.js";
+import { failEdit } from "./content.js";
+import { contentLines } from "../content-view.js";
+import { failStartup } from "../fail.js";
 export async function runInit(dirArg, opts) {
     const dir = resolve(dirArg);
-    // A rejected flag VALUE is the usage class, same as one the parser rejects.
-    const requested = agentDirName(opts.agentDir);
-    const invalid = agentDirNameError(requested);
-    if (invalid)
-        failUsage(`--agent-dir "${requested}" ${invalid}`);
-    const { agentDir: rel, created } = await scaffoldAgent(dir, { agentDir: requested }).catch(failStartup);
-    // The agent dir is where the manifest lives, so the install runs there — never against a surrounding workspace's
-    // package.json (its deps are its own concern).
-    const agentDir = resolve(dir, rel);
-    console.error(`[fastagent] initialized ${dir} — agent in ./${rel}/`);
-    console.error(`  created: ${created.join(", ")}`);
-    // A second agent beside an existing one is a supported shape, not an accident (an engineer's, a PM's and a content
-    // owner's agent can drive one repository), but it changes how this workspace resolves from now on — so say it HERE,
-    // at the moment it becomes true, instead of at the next command's refusal.
-    const siblings = agentsAt(dir).map((a) => basename(a));
-    if (siblings.length > 1) {
-        const pick = siblings.includes(DEFAULT_AGENT_DIRNAME)
-            ? `\`${DEFAULT_AGENT_DIRNAME}\` answers by default; set FASTAGENT_AGENT=<name> for another`
-            : `set FASTAGENT_AGENT=<name> (in your shell or .envrc) to pick one`;
-        console.error(`[fastagent] note: ${dir} now holds ${siblings.length} agents (${siblings.join(", ")}) — ${pick}`);
-    }
+    // Every source is read, and every entry checked (by initAgent), BEFORE anything is created.
+    const read = await Promise.resolve()
+        .then(() => opts.content.map((source) => readContentSource(source, process.cwd())))
+        .catch(failStartup);
     let installFailed = false;
-    if (opts.install) {
-        console.error(`[fastagent] installing dependencies (npm install in ${rel})…`);
-        installFailed = (await npmInstall(agentDir)) !== 0;
-        if (installFailed)
-            console.error(`[fastagent] warn: npm install failed — run it manually in ${agentDir} before \`fastagent dev\``);
-    }
+    const { created, content, repository } = await initAgent(dir, {
+        content: read.map((source) => source.addition),
+        ...(opts.install
+            ? {
+                install: async (agentDir) => {
+                    console.error(`[fastagent] installing dependencies (npm install)…`);
+                    installFailed = (await npmInstall(agentDir)) !== 0;
+                    if (installFailed) {
+                        console.error(`[fastagent] warn: npm install failed — run it manually in ${agentDir} before \`fastagent dev\``);
+                    }
+                },
+            }
+            : {}),
+    }).catch(failEdit(""));
+    console.error(`[fastagent] created ${dir}`);
+    for (const note of read.flatMap((source) => source.notes))
+        console.error(`  ${note}`);
+    if (content.length > 0)
+        for (const [label, value] of contentLines(content))
+            console.error(`  ${label} ${value}`);
+    console.error(`  files: ${created.join(", ")}`);
+    console.error(`[fastagent] git: ${repository}`);
     console.error(`  next steps:`);
     const cdTarget = displayPath(process.cwd(), dir);
     if (cdTarget)
         console.error(`    cd ${cdTarget}`);
     if (!opts.install || installFailed)
-        console.error(`    (cd ${rel} && npm install)`);
+        console.error(`    npm install`);
     console.error(`    fastagent dev   # serve locally and iterate`);
     console.error(`    fastagent add skill <owner/repo/path>   # vendor more skills from GitHub`);
 }

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

@@ -2,5 +2,11 @@ export interface InvokeOptions {
     model?: string;
     /** false ⇔ `--no-input`. */
     input?: boolean;
+    json?: boolean;
+    session?: string;
+    /** A served agent's base URL: the message goes there, over its Agent API. */
+    url?: string;
+    /** The key `url` is called with; else the first in the agent's production values. */
+    key?: string;
 }
 export declare function runInvoke(message: string, dirArg: string, opts: InvokeOptions): Promise<void>;

package/dist/cli/commands/invoke.js

@@ -1,21 +1,137 @@
-/** `fastagent invoke <message> [dir]`: run ONE turn against the assembled agent, then exit. */
-import { randomUUID } from "node:crypto";
-import { createPiAgentFromDir } from "../../engines/pi/open.js";
-import { runInvokeStream } from "../invoke-stream.js";
-import { failStartup } from "../fail.js";
+/**
+ * `fastagent invoke <message> [agent]`: send ONE message to the opened agent, print its answer, then exit. Every run
+ * prints its session's id; `--session <id>` sends the message into that session, continuing it. `--url` sends it to a
+ * served agent instead, over its Agent API (SPEC.md §9.6), with the same output and exit code.
+ */
+import { join, relative, resolve } from "node:path";
+import { AgentError } from "../../agent-api.js";
+import { enterAgentEnv } from "../../env.js";
+import { dotEnvPath, loadEnvValues } from "../../value-file.js";
+import { installProxyFetch } from "../../proxy.js";
+import { modelRefOf } from "../../harnesses/pi-durable/open.js";
+import { openServing } from "../../harnesses/pi-durable/serve.js";
+import { connectAgent } from "../../http/client.js";
+import { API_KEY_VARIABLE, apiKeysFrom } from "../../http/server.js";
+import { resolveStateRoot, selectAgentEnvironment } from "../../paths.js";
+import { runInvokeJson, runInvokeStream } from "../invoke-stream.js";
+import { failStartup, failUsage, optionalAgentDirOrExit } from "../fail.js";
 import { enterAgentCommand, reportAuth } from "../shared.js";
+/**
+ * `invoke`'s sessions, apart from the instance's storage, so `invoke` runs beside a serve of this directory, which holds
+ * that one; one `invoke` at a time holds this one.
+ */
+const invokeStorageFile = (stateRoot) => join(stateRoot, "invoke.sqlite");
+/**
+ * The session to send into, a new one or `sessionId`, set to the model this run resolved: every run answers with the
+ * model its flags and configuration name, a continued session included.
+ */
+async function sessionFor(agent, sessionId, settings, file) {
+    if (sessionId === undefined)
+        return (await agent.sessions.create(settings)).id;
+    await agent.sessions.update(sessionId, settings).catch((error) => {
+        if (error instanceof AgentError && error.code === "not_found") {
+            throw new Error(`--session ${sessionId}: no such session in ${file}; pass an id an earlier invoke printed`);
+        }
+        throw error;
+    });
+    return sessionId;
+}
+/** A refusal as the line an operator reads: its code, then what it says. */
+const refusal = (error) => error instanceof AgentError ? new Error(`${error.code}: ${error.message}`) : error;
+/** Print the message's answer as it is written, then exit with what it ended as: 0 only for `completed`. */
+async function answer(events, json) {
+    // Both renderers exit 1 unless the message completed: CI gates on it.
+    const exitCode = json
+        ? await runInvokeJson(events, (line) => process.stdout.write(`${line}\n`))
+        : await runInvokeStream(events, (text) => process.stdout.write(text), (line) => console.error(line));
+    if (!json)
+        process.stdout.write("\n");
+    return exitCode;
+}
+/**
+ * The key `--url` calls with: `--key`, or the first of `FASTAGENT_API_KEY` in the agent's production values, which
+ * `deploy` writes there and carries to the deployment.
+ */
+function deploymentKey(agentDir, url) {
+    selectAgentEnvironment("production");
+    const file = dotEnvPath(agentDir);
+    const [key] = apiKeysFrom(loadEnvValues(file).get(API_KEY_VARIABLE));
+    if (key === undefined) {
+        failUsage(`no key to call ${url} with: pass --key, or set ${API_KEY_VARIABLE} in ${relative(process.cwd(), file) || file} ` +
+            "(deploy writes one there)");
+    }
+    return key;
+}
+/**
+ * Enter this machine's environment and the proxy it declares, as every command that sends a request does, and answer
+ * the key to call `url` with: `--key`, from anywhere (the ambient environment when no agent is here), or the agent's.
+ */
+function enterForUrl(dirArg, key, url) {
+    const agentDir = optionalAgentDirOrExit(resolve(dirArg));
+    if (agentDir === undefined) {
+        installProxyFetch();
+        if (key === undefined) {
+            failUsage(`no key to call ${url} with: pass --key, or run this in the agent whose deploy wrote one`);
+        }
+        return key;
+    }
+    enterAgentEnv(agentDir);
+    return key ?? deploymentKey(agentDir, url);
+}
+/** `--url`: the message sent to a served agent over its Agent API, in a session there; nothing opens here. */
+async function runRemoteInvoke(message, dirArg, opts) {
+    const { url } = opts;
+    let settings;
+    try {
+        settings = opts.model === undefined ? undefined : { model: modelRefOf(opts.model, "--model") };
+    }
+    catch (error) {
+        failUsage(error instanceof Error ? error.message : String(error));
+    }
+    const agent = connectAgent(url, { apiKey: enterForUrl(dirArg, opts.key, url) });
+    console.error(`[fastagent] invoke: ${url}`);
+    const sessionId = await remoteSession(agent, opts.session, settings, url).catch((error) => failStartup(refusal(error)));
+    console.error(`[fastagent] session ${sessionId} (continue it with --session ${sessionId})`);
+    process.exit(await answer(agent.messages.stream({ sessionId, content: message }), opts.json));
+}
+/** The served agent's session to send into: a new one, or `sessionId`, set to `--model` when one is given. */
+async function remoteSession(agent, sessionId, settings, url) {
+    if (sessionId === undefined)
+        return (await agent.sessions.create(settings)).id;
+    const found = settings === undefined ? agent.sessions.get(sessionId) : agent.sessions.update(sessionId, settings);
+    await found.catch((error) => {
+        if (error instanceof AgentError && error.code === "not_found") {
+            throw new Error(`--session ${sessionId}: no such session at ${url}; pass an id an earlier invoke printed`);
+        }
+        throw error;
+    });
+    return sessionId;
+}
 export async function runInvoke(message, dirArg, opts) {
-    const placement = await enterAgentCommand(dirArg, opts);
-    const { modelSpec } = placement;
-    const { agent, models } = await createPiAgentFromDir(placement.agentDir, { model: modelSpec }).catch(failStartup);
-    // BOTH directories, like dev/start: which agent ran, and what it worked on.
-    console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
-    await reportAuth(models, modelSpec);
-    // Fresh session per invoke (one-shot, no resume). runInvokeStream maps events→IO: reply→stdout,
-    // tool/failure→stderr, exit 1 iff the turn failed (so CI can gate on it).
-    const exitCode = await runInvokeStream(agent.invoke({ session: randomUUID() }, { text: message }), (text) => process.stdout.write(text), (line) => console.error(line));
-    process.stdout.write("\n");
+    if (opts.url !== undefined)
+        return runRemoteInvoke(message, dirArg, { ...opts, url: opts.url });
+    if (opts.key !== undefined)
+        failUsage("--key is the key --url calls with: pass --url too");
+    const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts);
+    const file = invokeStorageFile(resolveStateRoot(agentDir));
+    const { agent, models, definition } = await openServing(agentDir, {
+        model: modelSpec,
+        storage: { file, holders: "another `fastagent invoke` of this agent" },
+        // Its messages do not outlive it: one a stopped invoke left is not run again by the next.
+        unfinished: "abort",
+    }).catch(failStartup);
+    console.error(`[fastagent] invoke: ${agentDir} (${modelSpec})`);
+    await reportAuth(models, modelSpec, agentDir);
+    const { thinkingLevel } = definition.config;
+    const settings = {
+        model: modelRefOf(modelSpec, "the model"),
+        ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
+    };
+    const sessionId = await sessionFor(agent, opts.session, settings, file).catch(failStartup);
+    console.error(`[fastagent] session ${sessionId} (continue it with --session ${sessionId})`);
+    const exitCode = await answer(agent.messages.stream({ sessionId, content: message }), opts.json);
+    await agent.close();
     // Always exit explicitly: the undici proxy agent's keep-alive sockets would otherwise hold the event loop open
-    // after a successful one-shot turn.
+    // after a successful one-shot message.
     process.exit(exitCode);
 }

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

@@ -1,13 +1,42 @@
+/**
+ * `fastagent login [provider]`: sign in to a model provider, into the project-level auth file
+ * (`<agentDir>/.secrets/auth.json`) by default, or `FASTAGENT_AUTH_PATH`. In a terminal it asks, as pi's `/login`
+ * does; otherwise (a script, a coding agent: no terminal, `--no-input` or `--json`) nothing is asked and nothing
+ * waits: what it needs is named, and a person's step is handed back with a ticket to check (ticket.ts).
+ * `--deployment` runs the same login on this agent's deployed box instead (box-login.ts); `--stdio` is the box's half.
+ */
+import type { AuthInteraction } from "@earendil-works/pi-ai";
+import { type TicketStep } from "../ticket.ts";
 export interface LoginOptions {
     /** `-g`: store in the user-global file, which an agent reads for a provider it has no other credential for. */
     global?: boolean;
     /** false ⇔ `--no-input`. */
     input?: boolean;
-    /** `--deployment [host]`: log in this workspace's deployment (`true` when no host was named). */
-    deployment?: string | boolean;
+    /** `--method account|api-key`: how to sign in, for a provider that offers both. */
+    method?: string;
+    /** `--json`: the outcome as one JSON object on stdout. */
+    json?: boolean;
+    /** `--timeout <seconds>`: how long the sign-in stays open. */
+    timeout?: string;
+    /** `--check <ticket>`: where a sign-in started without a terminal stands. */
+    check?: string;
+    /** `--code <address>` (with `--check`): the address the person's browser ended on, or the code it showed. */
+    code?: string;
+    /** `--ticket <id>`: the process that runs a ticket's sign-in. */
+    ticket?: string;
+    /** `--deployment <host>`: log in this agent's deployment on that host. */
+    deployment?: string;
     /** `--stdio`: the box's half of `--deployment` — the flow speaks the relay wire on stdin/stdout. */
     stdio?: boolean;
     /** `--if-missing` (with `--stdio`): keep a credential already stored for the provider. */
     ifMissing?: boolean;
 }
 export declare function runLogin(provider: string | undefined, opts: LoginOptions): Promise<void>;
+/**
+ * pi-ai's account sign-in, run by a ticket's process with no one to answer it. A choice takes its first option, pi's
+ * default (the browser sign-in); a text question is left blank, the one pi-ai's account sign-ins ask being Copilot's
+ * optional Enterprise domain (a required one fails in the provider's own flow, which the ticket reports); a secret it
+ * cannot take; the code or address a browser ends on comes from `login --check --code`, unless the provider's callback
+ * brings it first. Not public: a test seam.
+ */
+export declare function signInInteraction(step: TicketStep, provider: string): AuthInteraction;