@fastagent-sh/fastagent 0.29.0 → 0.30.1

package/dist/cli/serve.d.ts

@@ -1,12 +1,12 @@
 import type { ServedAgent, ServeOptions, Service } from "../service.ts";
-import type { AgentConfig } from "../harnesses/pi-durable/define.ts";
+import type { EffectiveConfig } from "../harnesses/pi-durable/config.ts";
 /** Refuse `--tunnel` with a `--bind` that cloudflared cannot reach. */
 export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean): void;
 /**
  * What the CLI adds to the assembly: its shutdown grace, exit on a connection that drops, and the API's keys, none
  * when the definition turns the API off, whatever key the environment holds (a host's from an earlier deploy).
  */
-export declare function cliMountOptions(config: AgentConfig): ServeOptions;
+export declare function cliMountOptions(config: EffectiveConfig): ServeOptions;
 /**
  * Bind, report, warn about reach, open the tunnel, and close in order on a signal — the tail dev's worker and start
  * share once the service is assembled.
@@ -17,11 +17,10 @@ export declare function serveService(service: ServedAgent, bind: {
 }, posture: {
     tunnel: boolean;
     agentDir: string;
-    stateRoot: string;
-    config: AgentConfig;
+    config: EffectiveConfig;
 }): void;
 /** The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and what mounted. */
-export declare function reportServing(service: ServedAgent, host: string | undefined, boundPort: number, config: AgentConfig): void;
+export declare function reportServing(service: ServedAgent, host: string | undefined, boundPort: number, config: EffectiveConfig): void;
 /** The line that names WHERE the serve is — every posture reports it, including AgentCore's own surface. */
 export declare function bindLine(host: string | undefined, boundPort: number): string;
 /** Listen, and report ready — but only once the SERVICE is, which is not the same moment — until a signal closes it. */

package/dist/cli/serve.js

@@ -30,10 +30,10 @@ export function cliMountOptions(config) {
  */
 export function serveService(service, bind, posture) {
     const { host } = bind;
-    const { tunnel, agentDir, stateRoot, config } = posture;
+    const { tunnel, agentDir, config } = posture;
     serve(service, bind, (p) => {
         reportServing(service, host, p, config);
-        maybeTunnel(agentDir, service.channels.routes, p, tunnel, stateRoot);
+        maybeTunnel(agentDir, service.channels.routes, p, tunnel);
     });
 }
 /** The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and what mounted. */
@@ -108,16 +108,13 @@ export function serve(service, bind, onListening) {
     });
 }
 /** Start a Cloudflare tunnel for route channels only. */
-function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
+function maybeTunnel(agentDir, routeChannels, boundPort, tunnel) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
     void startCloudflareTunnel(boundPort).then((instance) => {
         if (!instance)
             return;
-        void announceWebhooks(agentDir, instance.url, declaredChannels(routeChannels), {
-            openUrl: openExternalUrl,
-            stateRoot,
-        });
+        void announceWebhooks(agentDir, instance.url, declaredChannels(routeChannels), { openUrl: openExternalUrl });
         const cleanup = () => instance.close();
         process.once("SIGINT", cleanup);
         process.once("SIGTERM", cleanup);

package/dist/cli/shared.d.ts

@@ -1,6 +1,10 @@
 import { type LoginIO } from "../harnesses/models/login.ts";
 import { type ModelEnvironment } from "../harnesses/models/environment.ts";
 import type { OpenedServing } from "../harnesses/pi-durable/serve.ts";
+import { type Project } from "../harnesses/pi-durable/open.ts";
+import { type InstanceFlags } from "./instance.ts";
+/** The project a command runs, when it is not the development one (`start` runs the build). */
+type LoadProject = (agentDir: string) => Promise<Project>;
 /** An agent directory a command entered, and the default model that then resolves, if any. */
 export interface EnteredAgent {
     agentDir: string;
@@ -15,7 +19,8 @@ export interface EnteredAgent {
 export declare function enterAgentDirectory(dirArg: string, opts: {
     model?: string;
     input?: boolean;
-}, before?: (agentDir: string) => Promise<void>): Promise<EnteredAgent>;
+    instance?: InstanceFlags;
+}, before?: (agentDir: string) => Promise<void>, load?: LoadProject): Promise<EnteredAgent>;
 /**
  * How every command that RUNS the agent on this machine enters it (dev, start, invoke, schedules run):
  * {@link enterAgentDirectory}, plus a default model. The agent opens without one, but a process here would then fail
@@ -24,7 +29,8 @@ export declare function enterAgentDirectory(dirArg: string, opts: {
 export declare function enterAgentCommand(dirArg: string, opts: {
     model?: string;
     input?: boolean;
-}, before?: (agentDir: string) => Promise<void>): Promise<Required<EnteredAgent>>;
+    instance?: InstanceFlags;
+}, before?: (agentDir: string) => Promise<void>, load?: LoadProject): Promise<Required<EnteredAgent>>;
 /** What `dev` and `start` say about the agent they just opened, in the order they say it. */
 export declare function reportAssembly(opened: OpenedServing, modelSpec: string, extras?: [label: string, value: string][]): Promise<void>;
 /** Both stdin and stdout are a terminal — the precondition for an interactive prompt. */
@@ -38,7 +44,10 @@ export declare function parsePort(value: string | undefined, source: string, fro
 export declare function parseBind(value: string | undefined): string | undefined;
 /** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
 export declare function reportAuth(models: ModelEnvironment, modelSpec: string, agentDir: string): Promise<void>;
+/** The line of `fastagent.config.ts` that keeps a picked model: what the picker prints, and what it must accept. */
+export declare function pickedModelLine(model: string): string;
 /** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
 export declare function terminalLoginIO(): LoginIO;
 /** A copy/paste-safe POSIX shell argument for a command the CLI prints. */
 export declare function shellArg(value: string): string;
+export {};

package/dist/cli/shared.js

@@ -2,6 +2,7 @@
  * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report, first-run model
  * resolution, and the login terminal IO.
  */
+import { definedValues } from "../declared-secrets.js";
 import { resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
@@ -9,12 +10,13 @@ import { loginFlow } from "../harnesses/models/login.js";
 import { SignInCancelled } from "../sign-in-api.js";
 import { modelEnvironment } from "../harnesses/models/environment.js";
 import { listModels, providerAuthStatuses, providerOf } from "../harnesses/models/models.js";
-import { definitionProviders, loadConfig, modelSpecFor } from "../harnesses/pi-durable/open.js";
+import { resolveConfig } from "../harnesses/pi-durable/config.js";
+import { buildDefinitionShape, definitionProviders, loadDevProject, modelSpecFor, } from "../harnesses/pi-durable/open.js";
 import { formatAuthReport } from "./auth-view.js";
 import { contentLines } from "./content-view.js";
 import { deployedHost, isDeployedWorkspace } from "../paths.js";
 import { log } from "../log.js";
-import { enterAgentEnv } from "../env.js";
+import { enterInstance } from "./instance.js";
 import { dotEnvPath } from "../value-file.js";
 import { openExternalUrl } from "../open-url.js";
 import { bindAddress, isBindAddress } from "../bind.js";
@@ -25,11 +27,11 @@ import { agentDirOrExit, failStartup, failUsage } from "./fail.js";
  * gates a missing model itself, by what will ship. `before`: what the command checks of the directory before a model
  * is asked for (`schedules run`: that the schedule it names exists).
  */
-export async function enterAgentDirectory(dirArg, opts, before) {
+export async function enterAgentDirectory(dirArg, opts, before, load) {
     const agentDir = agentDirOrExit(resolve(dirArg));
-    enterAgentEnv(agentDir);
+    enterInstance(agentDir, opts.instance);
     await before?.(agentDir);
-    const modelSpec = await resolveFirstRunModel(agentDir, opts);
+    const modelSpec = await resolveFirstRunModel(agentDir, opts, load);
     return { agentDir, ...(modelSpec ? { modelSpec } : {}) };
 }
 /**
@@ -37,11 +39,11 @@ export async function enterAgentDirectory(dirArg, opts, before) {
  * {@link enterAgentDirectory}, plus a default model. The agent opens without one, but a process here would then fail
  * every new conversation, so it stops at startup instead: exit 2, the choice a terminal's picker would have asked for.
  */
-export async function enterAgentCommand(dirArg, opts, before) {
-    const entered = await enterAgentDirectory(dirArg, opts, before);
+export async function enterAgentCommand(dirArg, opts, before, load) {
+    const entered = await enterAgentDirectory(dirArg, opts, before, load);
     const { modelSpec } = entered;
     if (!modelSpec) {
-        failUsage(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai/gpt-5.5"; ` +
+        failUsage(`missing model: set --model, "defaults.model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai/gpt-5.5"; ` +
             "`fastagent models` lists them)");
     }
     return { ...entered, modelSpec };
@@ -52,11 +54,11 @@ function reportLine(label, value) {
 }
 /** What `dev` and `start` say about the agent they just opened, in the order they say it. */
 export async function reportAssembly(opened, modelSpec, extras = []) {
-    const { definition, code, models, agentDir, stateRoot } = opened;
-    reportLine("agent", `${definition.name} — ${agentDir}`);
+    const { code, models, agentDir, workdir, stateRoot, config } = opened;
+    reportLine("agent", `${opened.name} — ${workdir}`);
     for (const [label, value] of contentLines(opened.content))
         reportLine(label, value);
-    reportLine("model", `${modelSpec}${definition.config.thinkingLevel ? ` (thinking: ${definition.config.thinkingLevel})` : ""}`);
+    reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
     await reportAuth(models, modelSpec, agentDir);
     const names = (list) => list.map(({ name }) => name).join(", ") || "(none)";
     reportLine("tools", names(code.tools));
@@ -126,24 +128,35 @@ export async function reportAuth(models, modelSpec, agentDir) {
  * The default model, for every command that runs the agent: `--model` > `FASTAGENT_MODEL` > `fastagent.config.ts`. With
  * none and a terminal, the first-run picker chooses one for this run (and logs in to its provider when needed).
  */
-async function resolveFirstRunModel(agentDir, options = {}) {
-    const config = await loadConfig(agentDir).catch(failStartup);
-    const configured = modelSpecFor(config, options.model);
-    if (configured)
-        return configured;
+async function resolveFirstRunModel(agentDir, options = {}, load) {
+    const configured = async () => {
+        const project = await (load ?? loadDevProject)(agentDir);
+        return { project, config: resolveConfig(project.definition, project.instance) };
+    };
+    // A custom loader's refusal is the caller's to report: AgentCore runs this inside a request, where an exit kills the container.
+    const { project, config } = await (load === undefined ? configured().catch(failStartup) : configured());
+    const spec = modelSpecFor(config, options.model);
+    if (spec)
+        return spec;
     if (options.input === false)
         return undefined; // --no-input: never prompt (clig) — the caller decides what's missing
     if (!isInteractive())
         return undefined; // CI/deploy: the caller raises the actionable missing-model error
-    const providers = await definitionProviders(agentDir).catch(failStartup);
-    const environment = await modelEnvironment(agentDir, {}, providers);
+    const providers = load === undefined
+        ? await definitionProviders(agentDir, process.env).catch(failStartup)
+        : buildDefinitionShape(project.definition, process.env).providers;
+    const environment = await modelEnvironment(agentDir, {}, providers, { environment: definedValues(process.env) });
     const chosen = await pickWithCredentials(environment.models, environment.auth?.path, providers);
     if (chosen === undefined)
         return undefined; // cancelled (or auth probe failed): the caller raises its clear error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
-    console.error(`[fastagent] picked ${chosen} — set \`model: ${JSON.stringify(chosen)}\` in fastagent.config.ts to keep it`);
+    console.error(`[fastagent] picked ${chosen} — set \`${pickedModelLine(chosen)}\` in fastagent.config.ts to keep it`);
     return chosen;
 }
+/** The line of `fastagent.config.ts` that keeps a picked model: what the picker prints, and what it must accept. */
+export function pickedModelLine(model) {
+    return `defaults: { model: ${JSON.stringify(model)} }`;
+}
 /** The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy. */
 async function pickWithCredentials(models, authPath, providers) {
     let statuses;

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,9 +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 by one process at a time:
- * the starting command until the step starts, then the step alone (or whoever finds its process gone). 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
@@ -18,9 +20,10 @@
  * stopped with it, by `stop` and when it exits.
  */
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync } 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";
 import { writeFileAtomic } from "../atomic-write.js";
 import { STATE_DIRNAME, globalHome } from "../paths.js";
 import { recordFailures } from "./fail.js";
@@ -31,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");
@@ -38,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")
@@ -50,11 +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"];
 /**
- * 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.
+ * 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 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. 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);
@@ -62,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;
@@ -141,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) {
@@ -222,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`
@@ -236,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
@@ -246,7 +284,7 @@ export async function checkTicket(id, address) {
     if (ticket === undefined)
         return undefined;
     if (address !== undefined && ticket.status === "need_user_action") {
-        writeFileAtomic(addressPath(id), address);
+        writeFileAtomic(addressPath(id), address, undefined, true);
         for (const deadline = Date.now() + ADDRESS_TIMEOUT_MS; Date.now() < deadline;) {
             ticket = readTicket(id);
             if (ticket.status !== "need_user_action" || !running(ticket.pid))
@@ -271,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
@@ -385,6 +424,33 @@ async function awaitAddress(id, signal) {
     }
     throw new Error("the step no longer waits for an address");
 }
+const LOG_TAIL_LINES = 12;
+const LOG_TAIL_BYTES = 8192;
+const LOG_LINE_CHARS = 300;
+/**
+ * The last lines of a ticket's log, without terminal colors: where a failed step says why. A coding agent reads a
+ * report once, and "see the output above" points at a log it has not opened.
+ */
+function logTail(id) {
+    const path = ticketLogPath(id);
+    if (!existsSync(path))
+        return [];
+    const size = statSync(path).size;
+    const start = Math.max(0, size - LOG_TAIL_BYTES);
+    const fd = openSync(path, "r");
+    try {
+        const buffer = Buffer.alloc(size - start);
+        readSync(fd, buffer, 0, buffer.length, start);
+        return stripVTControlCharacters(buffer.toString("utf8"))
+            .split("\n")
+            .map((line) => line.trim().slice(0, LOG_LINE_CHARS))
+            .filter((line) => line !== "")
+            .slice(-LOG_TAIL_LINES);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 /**
  * A ticket as its command reports it, with what to do next (`agent_next_steps`): one JSON object, or its lines for a
  * person. `done` is what the step's `result` adds to the report, beside a sentence for the agent.
@@ -412,17 +478,27 @@ export function ticketReport(ticket, when, done = (result) => ({ fields: result,
         const message = ticket.status === "expired" ? "it was not finished in time" : ticket.message;
         // What the step reached before it ended is still the person's: where to get the value it stopped for, say.
         const reached = left.length === 0 ? "" : `Tell the user what the steps it reached leave them: ${left.join(" ")} `;
+        // An expired step is not a fault: nobody finished it in time, and its log says nothing more.
+        const expired = ticket.status === "expired";
+        const tail = expired ? [] : logTail(ticket.ticket);
         return {
             json: {
                 ...base,
                 message,
                 log,
+                ...(tail.length === 0 ? {} : { log_tail: tail }),
                 ...(ticket.afterwards ? { afterwards: ticket.afterwards } : {}),
-                agent_next_steps: `${reached}To try again, run: ${ticket.restart} --json`,
+                agent_next_steps: expired
+                    ? `${reached}The step was not finished in time, which is not a fault: ask the user to complete it as soon ` +
+                        `as you run: ${ticket.restart} --json`
+                    : `${reached}The cause is in log_tail (the whole log is at log): fix what it names, then run: ` +
+                        `${ticket.restart} --json. The same inputs fail the same way unless the log shows a transient network or ` +
+                        `builder error.`,
             },
             text: [
                 `${ticket.status}: ${message}`,
                 `log: ${log}`,
+                ...tail.map((line) => `  | ${line}`),
                 ...left.map((line) => `left for the person: ${line}`),
                 `to try again: ${ticket.restart}`,
             ],

package/dist/content/declare.d.ts

@@ -1,62 +1,56 @@
-/** One content entry as `context.json` holds it, under its name: a repository. */
-export interface ContentEntry {
+/** One content entry as a file holds it, under its name: a repository, or a directory of this machine. */
+export type ContentEntry = {
     /** The repository, `owner/repo`. */
     github: string;
     /** The branch, tag or commit to clone. */
     ref?: string;
     /** One sentence for the agent: what this is, and how to treat it. */
     description?: string;
-}
+} | {
+    /** Absolute, `~/`, or relative to the instance configuration. */
+    path: string;
+    description?: string;
+};
 /** A declared entry, read. */
-export interface DeclaredContent {
+export type DeclaredContent = {
     name: string;
+    description?: string;
+    /** The input that declared it. */
+    origin: "program" | "instance";
+} & ({
+    kind: "github";
     /** `owner/repo`. */
     repo: string;
     ref?: string;
-    description?: string;
-}
-/**
- * One binding as `context.local.json` holds it, under its name: a directory of this machine. Under the name of an
- * entry `context.json` declares it is this machine's checkout of that repository, and carries only `path`.
- */
-export interface ContentBinding {
-    /** Absolute, `~/`, or relative to the agent directory. */
-    path: string;
-    description?: string;
-}
-/** A binding, read: `path` absolute. */
-export type BoundContent = {
-    name: string;
-    path: string;
-} & ({
-    /** This machine's checkout of the declared entry of the same name. */
-    kind: "checkout";
 } | {
-    /** A directory only this machine has. */
+    /** A directory of this machine, `path` absolute. */
     kind: "local";
-    description?: string;
+    path: string;
 });
-/** What an agent's content is declared as: the shared declaration, and this machine's bindings. */
-export interface ContentDeclaration {
-    declared: DeclaredContent[];
-    bound: BoundContent[];
+/** Where a `content` map was read from, for what a refusal says and how a path is read. */
+export interface ContentSource {
+    origin: DeclaredContent["origin"];
+    /** The file's name, or what an instance configuration is called. */
+    file: string;
+    /** What a relative path is relative to: the instance configuration's directory. None for one that is no file. */
+    base?: string;
 }
 /** Whether `name` can name a content entry. */
 export declare function isContentName(name: string): boolean;
 /** Whether `repo` names a GitHub repository, `owner/repo`. */
 export declare function isGithubRepo(repo: string): boolean;
-/** `entry` with its keys in {@link ENTRY_KEYS} order: the form written. */
+/** `entry` with its keys in the order they are written. */
 export declare function canonicalEntry(entry: ContentEntry): ContentEntry;
-/** `binding` with its keys in {@link BINDING_KEYS} order: the form written. */
-export declare function canonicalBinding(binding: ContentBinding): ContentBinding;
-/** Read `context.json`'s `content` map (undefined is none). Every refusal names the entry; nothing is defaulted. */
-export declare function declareContent(raw: unknown): DeclaredContent[];
 /**
- * Read `context.local.json`'s `content` map (undefined is none) beside `declared`, with relative paths resolved against
- * `agentDir`. A binding under a declared entry's name is that entry's checkout here; any other is a directory of this
- * machine alone.
+ * Read a `content` map (undefined is none) from `from`. Every refusal names the entry; nothing is defaulted. The
+ * program's declares repositories only, since it is shared; an instance's may name a directory too.
+ */
+export declare function declareContent(raw: unknown, from: ContentSource): DeclaredContent[];
+/**
+ * The program's entries and the instance's, as one list. An instance only adds: a name both declare (ignoring case,
+ * as names are a directory) is refused, naming both, so nothing is shadowed.
  */
-export declare function declareBindings(raw: unknown, declared: readonly DeclaredContent[], agentDir: string): BoundContent[];
+export declare function joinContent(program: readonly DeclaredContent[], instance: readonly DeclaredContent[]): DeclaredContent[];
 /**
  * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
  * released, content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks