@fastagent-sh/fastagent 0.30.0 → 0.30.1

package/dist/cli/kernel.js

@@ -13,6 +13,9 @@ export function buildProgram(specs, options = {}) {
     // 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));
+    // commander reads a program option anywhere by default, a subcommand's values included: an `invoke --session <id>`
+    // whose id begins with "-v" (base64url, 1 in 4096) printed the version and exited 0. Only before the subcommand.
+    program.enablePositionalOptions();
     program.configureHelp({
         ...(options.helpWidth !== undefined ? { helpWidth: options.helpWidth } : {}),
         styleTitle: title,

package/dist/cli/ticket.d.ts

@@ -41,6 +41,13 @@ export interface Ticket {
 }
 /** What the step's process says while it runs: the place to look when it fails. */
 export declare const ticketLogPath: (id: string) => string;
+/**
+ * End the ticket `id` with `end`, unless something ended it first: the end is a file created once, by a hard link,
+ * which the kernel lets only one writer make, so two that both read the ticket as running (the step finishing as a
+ * person stops it) end it once. Answers the ticket as whoever ended it ended it. Not public: `update` ends a ticket,
+ * and a test seam.
+ */
+export declare function endTicket(id: string, end: Partial<Ticket>): Ticket;
 export interface TicketRequest {
     subject: string;
     action: string;

package/dist/cli/ticket.js

@@ -6,10 +6,11 @@
  * there is something for the person to do. The command's `--check <ticket>` reads where it stands from any process,
  * and hands the step the address a browser ended on when that browser could not reach this machine.
  *
- * A ticket is a file in the machine's own state, ~/.fastagent/.state/tickets, written whole (`writeFileAtomic`), but by
- * more than one process at once: the starting command until the step starts, then the step, and whoever finds its
- * process gone or replaces it (every `--check`, a newer step for the subject). One that has
- * ended stays as it ended. A newer step for the same subject stops an older one still waiting on its person, whose
+ * A ticket is two files in the machine's own state, ~/.fastagent/.state/tickets. One is the step as its process keeps
+ * it, written by one process at a time: the starting command until the step starts, then the step. The other is its
+ * end, written once, by whoever ends it first: the step itself, or a process that stops it, replaces it or finds it
+ * gone. An end is decided before what it decides is done, so a stop is the end of the step it stops even when the step
+ * hears the consequences of being stopped first, and nothing the step writes after reopens it. A newer step for the same subject stops an older one still waiting on its person, whose
  * process would otherwise hold what it holds (a sign-in's callback port, OpenAI's fixed) until it expires; so does one
  * still getting ready (reaching a box, opening a tunnel), which may hang there. One finishing what its person did (a
  * code exchanged, an app created from a pasted token) is never stopped halfway, and the newer attempt is answered
@@ -19,7 +20,7 @@
  * stopped with it, by `stop` and when it exits.
  */
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, } from "node:fs";
+import { closeSync, existsSync, linkSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -33,6 +34,7 @@ const ADDRESS_TIMEOUT_MS = 15_000;
 /** How long a stopped step's process has to let go of what it holds before it is killed. */
 const STOP_TIMEOUT_MS = 5_000;
 const POLL_MS = 200;
+const DAY_MS = 24 * 60 * 60 * 1000;
 /** Ticket files are random hex: anything else names no ticket, and no file outside the directory. */
 const TICKET_ID = /^[0-9a-f]{16}$/;
 const ticketsDir = () => join(globalHome(), STATE_DIRNAME, "tickets");
@@ -40,11 +42,10 @@ const ticketPath = (id) => join(ticketsDir(), `${id}.json`);
 const addressPath = (id) => join(ticketsDir(), `${id}.address`);
 /** What the step's process says while it runs: the place to look when it fails. */
 export const ticketLogPath = (id) => join(ticketsDir(), `${id}.log`);
-function readTicket(id) {
-    if (!TICKET_ID.test(id))
-        return undefined;
+const endPath = (id) => join(ticketsDir(), `${id}.end.json`);
+function readJson(path) {
     try {
-        return JSON.parse(readFileSync(ticketPath(id), "utf8"));
+        return JSON.parse(readFileSync(path, "utf8"));
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -52,16 +53,45 @@ function readTicket(id) {
         throw error;
     }
 }
+/** The ticket `id`: the step as its process keeps it, with its end over it once it has one. */
+function readTicket(id) {
+    if (!TICKET_ID.test(id))
+        return undefined;
+    const kept = readJson(ticketPath(id));
+    if (kept === undefined)
+        return undefined;
+    const end = readJson(endPath(id));
+    return end === undefined ? kept : { ...kept, ...end };
+}
+/** The step as its process keeps it: one writer at a time, the starting command and then the step. */
+const writeTicket = (ticket) => writeFileAtomic(ticketPath(ticket.ticket), JSON.stringify(ticket));
+const waiting = (ticket) => ticket.status === "starting" || ticket.status === "need_user_action" || ticket.status === "working";
+const ENDS = ["done", "failed", "expired"];
 /**
- * A ticket is written by several processes: the command that started the step, the step's own process, and every
- * `--check`. Each writes a temp of its own (`sharedWriters`): the fixed name is for one writer, and two of them rename
- * each other's file away or write one temp at once, which a reader sees as `Unexpected non-whitespace character after JSON`.
+ * End the ticket `id` with `end`, unless something ended it first: the end is a file created once, by a hard link,
+ * which the kernel lets only one writer make, so two that both read the ticket as running (the step finishing as a
+ * person stops it) end it once. Answers the ticket as whoever ended it ended it. Not public: `update` ends a ticket,
+ * and a test seam.
  */
-const writeTicket = (ticket) => writeFileAtomic(ticketPath(ticket.ticket), JSON.stringify(ticket), undefined, true);
-const waiting = (ticket) => ticket.status === "starting" || ticket.status === "need_user_action" || ticket.status === "working";
+export function endTicket(id, end) {
+    const draft = `${endPath(id)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(draft, JSON.stringify(end));
+    try {
+        linkSync(draft, endPath(id));
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    finally {
+        rmSync(draft, { force: true });
+    }
+    return readTicket(id);
+}
 /**
- * Change the ticket `id` while its step still runs; one that has ended is returned as it ended. A writer that read it
- * before it ended (a check that found its process gone the moment it finished) cannot reopen it.
+ * Change the ticket `id` while its step still runs; one that has ended is returned as it ended. An end is
+ * `endTicket`'s, so the first one written is the one that stays; anything else is the step's own record, which its
+ * process alone writes.
  */
 function update(id, change) {
     const current = readTicket(id);
@@ -69,6 +99,8 @@ function update(id, change) {
         throw new Error(`ticket ${id} is gone from ${ticketsDir()}`);
     if (!waiting(current))
         return current;
+    if (change.status !== undefined && ENDS.includes(change.status))
+        return endTicket(id, change);
     const next = { ...current, ...change };
     writeTicket(next);
     return next;
@@ -148,24 +180,23 @@ async function supersede(subject, now) {
     if (finishing !== undefined)
         return finishing;
     for (const ticket of runs) {
+        update(ticket.ticket, { status: "failed", message: `replaced by a newer attempt to ${ticket.action}` });
         if (ticket.pid !== undefined)
             await stop(ticket.pid);
-        update(ticket.ticket, { status: "failed", message: `replaced by a newer attempt to ${ticket.action}` });
     }
     return undefined;
 }
-/** Tickets a day past their end: each one's files go. */
+/** Tickets a day past their end: every file of each one goes. */
 function prune(now) {
     if (!existsSync(ticketsDir()))
         return;
-    for (const file of readdirSync(ticketsDir())) {
-        const id = file.slice(0, 16);
-        const ticket = TICKET_ID.test(id) ? readTicket(id) : undefined;
-        if (ticket !== undefined && ticket.expiresAt < now - 24 * 60 * 60 * 1000) {
-            for (const path of [ticketPath(id), addressPath(id), ticketLogPath(id)])
-                rmSync(path, { force: true });
-        }
-    }
+    const files = readdirSync(ticketsDir());
+    const past = new Set(files
+        .map((file) => file.slice(0, 16))
+        .filter((id) => TICKET_ID.test(id) && (readTicket(id)?.expiresAt ?? Number.POSITIVE_INFINITY) < now - DAY_MS));
+    for (const file of files)
+        if (past.has(file.slice(0, 16)))
+            rmSync(join(ticketsDir(), file), { force: true });
 }
 /** A new ticket, its step not started yet. Not public: what `startTicket` starts, and a test seam. */
 export function createTicket(request) {
@@ -229,13 +260,10 @@ export async function startTicket(input) {
     // Claimed and at work: the step writes the ticket now, so this command reports it as it is.
     if (!exited && !input.waitsFirst && ticket.status === "working")
         return ticket;
-    // Given up on, unclaimed or giving the person nothing: its process goes first, or it would hold its port and write
-    // the ticket after this.
+    // Given up on, unclaimed or giving the person nothing: the end first, then its process, which would hold its port.
     const stoppedItself = exited;
-    if (!stoppedItself && child.pid !== undefined)
-        await stop(child.pid);
     const within = `${startTimeoutMs / 1000}s: ${ticketLogPath(id)} says why`;
-    return update(id, {
+    const ended = update(id, {
         status: "failed",
         message: stoppedItself
             ? `it stopped before it started: ${ticketLogPath(id)} says why`
@@ -243,6 +271,9 @@ export async function startTicket(input) {
                 ? `it did not start within ${within}`
                 : `it gave the person nothing to do within ${within}`,
     });
+    if (!stoppedItself && child.pid !== undefined)
+        await stop(child.pid);
+    return ended;
 }
 /**
  * Where the step `id` stands. `address`: what the person's browser ended on (or the code its page showed), for a step
@@ -278,12 +309,13 @@ export async function stopTicket(id) {
         throw new Error(`ticket ${id} is gone from ${ticketsDir()}`);
     if (!waiting(ticket))
         return ticket;
-    if (ticket.pid !== undefined)
-        await stop(ticket.pid);
-    return update(id, {
+    const ended = update(id, {
         status: "failed",
         message: `stopped on request; what it was doing may be left half-done (${ticketLogPath(id)} says where it was)`,
     });
+    if (ticket.pid !== undefined)
+        await stop(ticket.pid);
+    return ended;
 }
 /**
  * Why the command whose `--check` is `check` cannot read ticket `id`: there is none on this machine, or it is another

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",