@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/cli/fail.js

@@ -1,5 +1,4 @@
-import { resolvePlacement } from "../paths.js";
-import { gateSecrets } from "../secrets-gate.js";
+import { findAgentDir, resolveAgentDir } from "../paths.js";
 /** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
 function stderrHasColors() {
     return process.stderr.isTTY === true && (process.stderr.hasColors?.() ?? false);
@@ -8,36 +7,39 @@ function stderrHasColors() {
 export function errorPrefix(colors = stderrHasColors()) {
     return colors ? "\x1b[1;31mError:\x1b[0m" : "Error:";
 }
+let failureRecorder;
+/**
+ * A ticket's process (ticket.ts): a failure that ends the process is the ticket's failure too, recorded before the
+ * process exits, wherever in a long command it happens.
+ */
+export function recordFailures(record) {
+    failureRecorder = record;
+}
 /**
  * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain `Error` — print
  * just the message. Anything else (a TypeError, a non-Error throw) is a bug: keep the stack.
  */
 export function failStartup(error) {
+    failureRecorder?.(error instanceof Error ? error.message : String(error));
     if (error instanceof Error && error.constructor === Error)
         console.error(`${errorPrefix()} ${error.message}`);
     else
         console.error(errorPrefix(), error);
     process.exit(1);
 }
-/**
- * {@link gateSecrets} at the process boundary, for a command that runs ONE owner's code (`fastagent
- * tool`, `fastagent routine run`). The gate throws SYNCHRONOUSLY, so there is no promise to hang the usual
- * `.catch(failStartup)` on, and a raw throw reaches `cli.ts`'s top-level await as a Node stack that
- * buries the one line naming the file. The catch translates that expected failure into the CLI's
- * single-line refusal and exits 1; nothing is recovered.
- */
-export function gateSecretsOrExit(input) {
+/** THE addressing entry point for commands: the agent directory `dir` names, or exit 1 with the one-line refusal. */
+export function agentDirOrExit(dir) {
     try {
-        gateSecrets(input);
+        return resolveAgentDir(dir);
     }
     catch (error) {
         failStartup(error);
     }
 }
-/** THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. */
-export function placementOrExit(dir) {
+/** {@link findAgentDir} for a command that also works without an agent: undefined when there is none, exit 1 inside one. */
+export function optionalAgentDirOrExit(dir) {
     try {
-        return resolvePlacement(dir);
+        return findAgentDir(dir);
     }
     catch (error) {
         failStartup(error);
@@ -48,6 +50,7 @@ export function placementOrExit(dir) {
  * command body): print the message and exit 2.
  */
 export function failUsage(message) {
+    failureRecorder?.(message);
     console.error(`${errorPrefix()} ${message}`);
     process.exit(2);
 }

package/dist/cli/invoke-stream.d.ts

@@ -1,3 +1,12 @@
-/** Render an Agent event stream to two sinks plus an exit code. */
-import type { AgentEvent } from "../agent.ts";
-export declare function runInvokeStream(events: AsyncIterable<AgentEvent>, out: (text: string) => void, err: (line: string) => void): Promise<number>;
+/** Render one message's answer, as `messages.stream` delivers it, plus an exit code: 0 only for `completed`. */
+import { type Message, type MessageStreamEvent } from "../agent-api.ts";
+/** A command that sends a message exits 0 only when it completed. */
+export declare const exitCodeOf: (message: Pick<Message, "status">) => number;
+/** The answer as text on `out`, what the tools did and why it failed on `err`. */
+export declare function runInvokeStream(events: AsyncIterable<MessageStreamEvent>, out: (text: string) => void, err: (line: string) => void): Promise<number>;
+/**
+ * The answer as JSON lines, for a program to read: the message's events as `messages.stream` delivers them, its
+ * `message` first, through its `done`. A message that ends no other way ends with the line that says why: `rejected`
+ * when the agent refused it, a `stream_error` event, or `unfinished` when the events end first.
+ */
+export declare function runInvokeJson(events: AsyncIterable<MessageStreamEvent>, line: (json: string) => void): Promise<number>;

package/dist/cli/invoke-stream.js

@@ -1,35 +1,97 @@
+/** Render one message's answer, as `messages.stream` delivers it, plus an exit code: 0 only for `completed`. */
+import { AgentError, errorData } from "../agent-api.js";
+import { answerText } from "../answer-text.js";
+/** A command that sends a message exits 0 only when it completed. */
+export const exitCodeOf = (message) => (message.status === "completed" ? 0 : 1);
+function failure(message) {
+    const { status, error } = message;
+    if (status === "completed")
+        return undefined;
+    if (error === undefined)
+        return status;
+    return `${error.code}: ${error.message}${error.retryable ? " (retryable)" : ""}`;
+}
+/**
+ * Read `events` to their end with `read`, which answers an exit code once the message has ended; a send the agent
+ * refused rejects the first read, and is said by `refused`.
+ */
+async function readMessage(events, read, refused) {
+    try {
+        for await (const event of events) {
+            const exit = read(event);
+            if (exit !== undefined)
+                return exit;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof AgentError))
+            throw error;
+        refused(error);
+        return 1;
+    }
+    return undefined;
+}
+/** The answer as text on `out`, what the tools did and why it failed on `err`. */
 export async function runInvokeStream(events, out, err) {
-    const toolName = new Map(); // tool_ended carries no name — remember it from tool_started
-    let exitCode = 0;
-    for await (const event of events) {
+    const toolName = new Map(); // a tool result carries the id; its name came with tool_started
+    const textOf = answerText();
+    const exit = await readMessage(events, (event) => {
+        const text = event.type === "delta" || event.type === "entry" ? textOf(event) : "";
+        if (text !== "")
+            out(text);
         switch (event.type) {
-            case "text":
-                out(event.delta);
-                break;
             case "tool_started":
-                toolName.set(event.id, event.name);
+                toolName.set(event.toolCallId, event.name);
                 err(`[tool] ${event.name}`);
-                break;
+                return undefined;
             case "tool_progress":
-                err(`[tool] ${toolName.get(event.id) ?? event.id} › ${clipStatus(event.text)}`);
-                break;
-            case "tool_ended":
-                if (event.isError)
-                    err(`[tool] ${toolName.get(event.id) ?? event.id} failed`);
-                break;
+                err(`[tool] ${toolName.get(event.toolCallId) ?? event.toolCallId} › ${clipStatus(event.text)}`);
+                return undefined;
             case "retrying":
                 // Operator-facing: include the reason (channels show a neutral customer line instead).
                 err(`[fastagent] transient failure — retrying (${event.attempt}/${event.maxAttempts} in ${event.delayMs}ms): ${event.reason}`);
-                break;
-            case "failed":
-                err(`[fastagent] failed: ${event.details}${event.retryable ? " (retryable)" : ""}`);
-                exitCode = 1;
-                break;
-            case "completed":
-                break; // terminal success — nothing to render (structured data, if any, is not a CLI concern)
+                return undefined;
+            case "stream_error":
+                err(`[fastagent] ${event.error.message}`);
+                return 1;
+            case "entry": {
+                const data = event.entry.data;
+                if (event.entry.kind === "tool_result" && data.isError) {
+                    err(`[tool] ${toolName.get(data.toolCallId ?? "") ?? data.toolCallId} failed`);
+                }
+                return undefined;
+            }
+            case "done": {
+                const failed = failure(event.message);
+                if (failed !== undefined)
+                    err(`[fastagent] failed: ${failed}`);
+                return exitCodeOf(event.message);
+            }
+            default:
+                return undefined;
         }
-    }
-    return exitCode;
+    }, (error) => err(`[fastagent] rejected: ${error.code}: ${error.message}`));
+    if (exit !== undefined)
+        return exit;
+    err("[fastagent] the stream ended before the message did");
+    return 1;
+}
+/**
+ * The answer as JSON lines, for a program to read: the message's events as `messages.stream` delivers them, its
+ * `message` first, through its `done`. A message that ends no other way ends with the line that says why: `rejected`
+ * when the agent refused it, a `stream_error` event, or `unfinished` when the events end first.
+ */
+export async function runInvokeJson(events, line) {
+    const exit = await readMessage(events, (event) => {
+        line(JSON.stringify(event));
+        if (event.type === "stream_error")
+            return 1;
+        return event.type === "done" ? exitCodeOf(event.message) : undefined;
+    }, (error) => line(JSON.stringify({ type: "rejected", error: errorData(error) })));
+    if (exit !== undefined)
+        return exit;
+    line(JSON.stringify({ type: "unfinished", reason: "the stream ended before the message did" }));
+    return 1;
 }
 /** How much of a status line a terminal gets, in code points. */
 const STATUS_MAX = 120;

package/dist/cli/kernel.d.ts

@@ -1,12 +1,17 @@
 /** CLI kernel — commands as data. */
 import { Command } from "commander";
-/** One positional argument, in commander syntax: `<name>` required, `[dir]` optional. */
+/**
+ * One positional argument, in commander syntax: `<name>` required, `[dir]` optional, `<names...>` one or more (the
+ * command receives them as an array).
+ */
 interface ArgSpec {
     name: string;
     description: string;
     default?: string;
     /** Closed value set — the parser rejects anything else as a usage error (exit 2). */
     choices?: string[];
+    /** Passed on as given, an empty value included: another program's arguments (`env exec`). */
+    verbatim?: boolean;
 }
 /** One flag, in the flag DSL: `--json`, or `--bind <addr>` for a value-taking flag. */
 export interface FlagSpec {
@@ -14,6 +19,8 @@ export interface FlagSpec {
     description: string;
     /** Parsed but left out of help: an internal seam between two fastagent processes, not a user-facing flag. */
     hidden?: boolean;
+    /** May be given more than once; the command receives every value, in order, as an array. */
+    repeatable?: boolean;
 }
 interface ExampleSpec {
     cmd: string;
@@ -37,7 +44,7 @@ export interface CommandSpec {
      * The implementation: positional args in declaration order (an optional arg without a default is `undefined`), then
      * the parsed flags.
      */
-    run?: (args: (string | undefined)[], flags: Record<string, unknown>) => Promise<void> | void;
+    run?: (args: (string | string[] | undefined)[], flags: Record<string, unknown>) => Promise<void> | void;
 }
 export interface ProgramOptions {
     /** Printed by `-v`/`--version`. */

package/dist/cli/kernel.js

@@ -9,7 +9,7 @@ const specOf = new WeakMap();
 export function buildProgram(specs, options = {}) {
     const exit = options.exit ?? ((code) => process.exit(code));
     const program = new Command("fastagent");
-    program.description("Serve a file-defined agent — SYSTEM.md, skills/, tools/, channels/ — as a live service.");
+    program.description("Serve a file-defined agent — SYSTEM.md, skills/, src/ — as a live service.");
     // The exit-code policy: commander throws only for parse-level events — help/version displays carry exitCode 0 (→
     // 0), everything else it rejects is a usage error (→ 2).
     program.exitOverride((err) => exit(err.exitCode === 0 ? 0 : 2));
@@ -52,17 +52,26 @@ function register(parent, spec) {
         if (a.choices)
             arg.choices(a.choices);
         // A required argument means a non-empty VALUE, not just a present token.
-        if (a.name.startsWith("<") && !a.choices) {
-            arg.argParser((value) => {
+        if (a.name.startsWith("<") && !a.choices && !a.verbatim) {
+            const nonEmpty = (value) => {
                 if (value.trim() === "")
                     throw new InvalidArgumentError("must not be empty.");
                 return value;
-            });
+            };
+            // A parser of a variadic argument replaces commander's own collecting, so it collects too.
+            if (a.name.endsWith("...>"))
+                arg.argParser((value, previous = []) => [...previous, nonEmpty(value)]);
+            else
+                arg.argParser(nonEmpty);
         }
         cmd.addArgument(arg);
     }
-    for (const f of spec.flags ?? [])
-        cmd.addOption(new Option(f.flags, f.description).hideHelp(f.hidden === true));
+    for (const f of spec.flags ?? []) {
+        const option = new Option(f.flags, f.description).hideHelp(f.hidden === true);
+        if (f.repeatable)
+            option.argParser((value, previous = []) => [...previous, value]);
+        cmd.addOption(option);
+    }
     for (const sub of spec.subcommands ?? [])
         register(cmd, sub);
     const run = spec.run;

package/dist/cli/login-relay.d.ts

@@ -1,12 +1,13 @@
 import type { Readable, Writable } from "node:stream";
-import type { LoginIO, LoginMethod } from "../engines/pi/login.ts";
+import type { LoginIO } from "../harnesses/models/login.ts";
+import type { SignInMethod } from "../sign-in-api.ts";
 /** How a login on the box ended, as the box reports it. */
 export type RelayResult = 
 /** Logged in now: `method` is how, `path` where the box saved it. */
 {
     ok: true;
     provider: string;
-    method: LoginMethod;
+    method: SignInMethod;
     path: string;
 }
 /**
@@ -24,7 +25,7 @@ export type RelayResult =
 };
 /**
  * The box half: a {@link LoginIO} over `input`/`output`. Once `input` ends (the session dropped), every pending and
- * later question reads as backed out, so the flow ends in `LoginCancelled` instead of waiting forever.
+ * later question reads as backed out, so the flow ends in `SignInCancelled` instead of waiting forever.
  */
 export declare function stdioLoginIO(input: Readable, output: Writable): {
     io: LoginIO;
@@ -32,7 +33,8 @@ export declare function stdioLoginIO(input: Readable, output: Writable): {
 };
 /**
  * The terminal half: drive `io` from what the box sends on `from`, answering on `to`. Resolves with the box's
- * `result` line when `from` ends, or `undefined` when it ended without one. A line that is not the wire (a host
+ * `result` line when `from` ends, `undefined` when it ended without one, or a failure of this side's own when the box
+ * speaks an older wire than this one (`BOX_CLI_PREDATES`). A line that is not the wire (a host
  * CLI's banner, a shell's error) goes to `passthrough`, so nothing the box printed is lost.
  */
 export declare function relayLogin(from: Readable, to: Writable, io: LoginIO, passthrough: (line: string) => void): Promise<RelayResult | undefined>;

package/dist/cli/login-relay.js

@@ -8,10 +8,11 @@
  * seen doing so), so an ended stream without that line is a failure, whatever the exit code says.
  */
 import { createInterface } from "node:readline";
+import { BOX_CLI_PREDATES } from "../deploy/box-shell.js";
 const send = (out, message) => void out.write(`${JSON.stringify(message)}\n`);
 /**
  * The box half: a {@link LoginIO} over `input`/`output`. Once `input` ends (the session dropped), every pending and
- * later question reads as backed out, so the flow ends in `LoginCancelled` instead of waiting forever.
+ * later question reads as backed out, so the flow ends in `SignInCancelled` instead of waiting forever.
  */
 export function stdioLoginIO(input, output) {
     const pending = new Map();
@@ -47,9 +48,9 @@ export function stdioLoginIO(input, output) {
     return {
         io: {
             select: (message, options) => ask((id) => ({ type: "select", id, message, options })),
-            prompt: (message, opts) => ask((id) => ({ type: "prompt", id, message, hidden: opts?.hidden === true }), opts?.signal),
+            prompt: (message, opts) => ask((id) => ({ type: "prompt", id, message, hidden: opts?.hidden === true, redirect: opts?.redirect === true }), opts?.signal),
             note: (message) => send(output, { type: "note", message }),
-            openUrl: (url) => send(output, { type: "open", url }),
+            openUrl: (url, userCode) => send(output, { type: "open", url, ...(userCode ? { userCode } : {}) }),
         },
         result: (result) => {
             send(output, { type: "result", ...result });
@@ -59,7 +60,8 @@ export function stdioLoginIO(input, output) {
 }
 /**
  * The terminal half: drive `io` from what the box sends on `from`, answering on `to`. Resolves with the box's
- * `result` line when `from` ends, or `undefined` when it ended without one. A line that is not the wire (a host
+ * `result` line when `from` ends, `undefined` when it ended without one, or a failure of this side's own when the box
+ * speaks an older wire than this one (`BOX_CLI_PREDATES`). A line that is not the wire (a host
  * CLI's banner, a shell's error) goes to `passthrough`, so nothing the box printed is lost.
  */
 export function relayLogin(from, to, io, passthrough) {
@@ -68,6 +70,8 @@ export function relayLogin(from, to, io, passthrough) {
     const answer = (id, value) => send(to, { id, value: value ?? null });
     const prompts = new Map();
     let result;
+    /** Why this relay stopped the box itself: a box whose wire this CLI cannot read whole. */
+    let refused;
     const lines = createInterface({ input: from });
     lines.on("line", (line) => {
         const message = parse(line);
@@ -78,9 +82,17 @@ export function relayLogin(from, to, io, passthrough) {
                 void io.select(message.message, message.options).then((value) => answer(message.id, value));
                 return;
             case "prompt": {
+                if (typeof message.redirect !== "boolean") {
+                    // An older box: which of its prompts takes the browser's address cannot be told, so none could be answered
+                    // from the redirect this side catches. Its input ends, so it stops instead of waiting on a paste.
+                    refused = BOX_CLI_PREDATES;
+                    to.end();
+                    return;
+                }
                 const controller = new AbortController();
                 prompts.set(message.id, controller);
-                void io.prompt(message.message, { hidden: message.hidden, signal: controller.signal }).then((value) => {
+                const asked = { hidden: message.hidden, redirect: message.redirect, signal: controller.signal };
+                void io.prompt(message.message, asked).then((value) => {
                     prompts.delete(message.id);
                     if (!controller.signal.aborted)
                         answer(message.id, value);
@@ -93,7 +105,7 @@ export function relayLogin(from, to, io, passthrough) {
             case "note":
                 return io.note(message.message);
             case "open":
-                return io.openUrl(message.url);
+                return io.openUrl(message.url, message.userCode);
             case "result": {
                 const { type: _, ...rest } = message;
                 result = rest;
@@ -104,7 +116,7 @@ export function relayLogin(from, to, io, passthrough) {
     return new Promise((resolve) => lines.on("close", () => {
         for (const controller of prompts.values())
             controller.abort();
-        resolve(result);
+        resolve(refused === undefined ? result : { ok: false, reason: "failed", message: refused });
     }));
 }
 const WIRE_TYPES = new Set(["select", "prompt", "abort", "note", "open", "result"]);

package/dist/cli/models-view.d.ts

@@ -1,4 +1,8 @@
-import type { ProviderAuthStatus } from "../engines/pi/models.ts";
+/**
+ * CLI presenter for the model-facing commands: `fastagent models [search]` output and the first-run picker's option
+ * list.
+ */
+import { type ProviderAuthStatus } from "../harnesses/models/models.ts";
 /** One first-run picker entry (@clack/prompts option shape). */
 export interface ModelPickerOption {
     value: string;

package/dist/cli/models-view.js

@@ -2,7 +2,7 @@
  * CLI presenter for the model-facing commands: `fastagent models [search]` output and the first-run picker's option
  * list.
  */
-import { providerOf } from "../engines/pi/config.js";
+import { providerOf } from "../harnesses/models/models.js";
 /** The remedy hint for a non-ready provider, by what picking it actually does. */
 function remedy(login) {
     if (login === "oauth")

package/dist/cli/person.d.ts

@@ -0,0 +1,10 @@
+export interface Person {
+    /** A step this run waits on: `instructions`, at `url`; `until`, when the step itself lapses (ms since the epoch). */
+    waitsOn(url: string, instructions: string, until?: number): void;
+    /** The step waited on is done: the run carries on without the person. */
+    carriesOn(): void;
+    /** A step left to the person once this run ends, which nothing here waits for; at `url`, when it has one. */
+    afterwards(instructions: string, url?: string): void;
+}
+/** The person at this terminal: told, and the page opened for them. */
+export declare const terminalPerson: Person;

package/dist/cli/person.js

@@ -0,0 +1,23 @@
+/**
+ * What an app's setup says to the person setting it up, for the steps only they can take. At a terminal it is printed,
+ * and the page opened. In a coding agent's run it goes to the ticket the agent hands its person (ticket.ts): the step
+ * the run waits on as `need_user_action`, and a step left to them after it as `afterwards`.
+ */
+import { openExternalUrl } from "../open-url.js";
+/** The person at this terminal: told, and the page opened for them. */
+export const terminalPerson = {
+    waitsOn(url, instructions, until) {
+        const lapses = until === undefined ? "" : `, valid for ${Math.round((until - Date.now()) / 60_000)} minutes`;
+        console.error(`[fastagent] ${instructions} — opening ${url} (waiting${lapses}; keep this running)`);
+        openExternalUrl(url);
+    },
+    carriesOn() { },
+    afterwards(instructions, url) {
+        if (url === undefined) {
+            console.error(`[fastagent] ${instructions}`);
+            return;
+        }
+        console.error(`[fastagent] ${instructions} — opening ${url}`);
+        openExternalUrl(url);
+    },
+};