@fastagent-sh/fastagent 0.28.0 → 0.30.0

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.js

@@ -6,8 +6,9 @@
  * 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
+ * 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
  * 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
@@ -18,9 +19,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, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, } 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";
@@ -50,7 +52,12 @@ function readTicket(id) {
         throw error;
     }
 }
-const writeTicket = (ticket) => writeFileAtomic(ticketPath(ticket.ticket), JSON.stringify(ticket));
+/**
+ * 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`.
+ */
+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";
 /**
  * Change the ticket `id` while its step still runs; one that has ended is returned as it ended. A writer that read it
@@ -246,7 +253,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))
@@ -385,6 +392,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 +446,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

package/dist/content/declare.js

@@ -1,18 +1,18 @@
 /**
- * WHAT AN AUTHOR DECLARES an agent works on, read and refused in ONE place (file.ts reads the files through
- * it): the `content` map of `context.json`, which is shared and so holds only repositories every instance reaches, and
- * the `content` map of `context.local.json`, the directories of this machine it is bound to. Pure: what is on the disk
- * is resolve.ts's question. docs/design/agent-model.md §3 is the rule.
+ * WHAT AN AGENT WORKS ON, declared and refused in ONE place (file.ts reads the files through it): the `content` map of
+ * the program's `context.json`, which holds only repositories every instance reaches, and the `content` map of an
+ * instance's `fastagent.json`, which adds repositories and directories of its own. An instance only adds: a name the
+ * program declares is not one it may take. Pure: what is on the disk is resolve.ts's question.
+ * docs/design/agent-artifact.md §3.3 and §4.2 are the rule.
  */
-import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
-import { CONTEXT_FILE, LOCAL_CONTEXT_FILE, isUnderDir } from "../paths.js";
+import { isAbsolute } from "node:path";
+import { CONTEXT_FILE, configurationPath, isUnderDir } from "../paths.js";
 /**
- * The keys an entry and a binding carry, in the order they are written: where it is, then how it is treated. One list
- * each, so a key the reader accepts is one the writer keeps.
+ * The keys an entry carries, in the order they are written: where it is, then how it is treated. One list each, so a
+ * key the reader accepts is one the writer keeps.
  */
-const ENTRY_KEYS = ["github", "ref", "description"];
-const BINDING_KEYS = ["path", "description"];
+const GITHUB_KEYS = ["github", "ref", "description"];
+const PATH_KEYS = ["path", "description"];
 /** A name becomes a directory name, so it is one path segment (the spelling a release's agent name has). */
 const NAME = /^[A-Za-z0-9_-]+$/;
 /** Whether `name` can name a content entry. */
@@ -24,13 +24,9 @@ const GITHUB_REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 export function isGithubRepo(repo) {
     return GITHUB_REPO.test(repo);
 }
-/** `entry` with its keys in {@link ENTRY_KEYS} order: the form written. */
+/** `entry` with its keys in the order they are written. */
 export function canonicalEntry(entry) {
-    return pick(entry, ENTRY_KEYS);
-}
-/** `binding` with its keys in {@link BINDING_KEYS} order: the form written. */
-export function canonicalBinding(binding) {
-    return pick(binding, BINDING_KEYS);
+    return pick(entry, "github" in entry ? GITHUB_KEYS : PATH_KEYS);
 }
 function pick(value, keys) {
     const out = {};
@@ -41,42 +37,26 @@ function pick(value, keys) {
     }
     return out;
 }
-/** Read `context.json`'s `content` map (undefined is none). Every refusal names the entry; nothing is defaulted. */
-export function declareContent(raw) {
-    return entriesByName(raw).map(([name, entry]) => declareOne(name, entry));
+/**
+ * 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 function declareContent(raw, from) {
+    return entriesByName(raw).map(([name, entry]) => declareOne(name, entry, from));
 }
 /**
- * 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.
+ * 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 function declareBindings(raw, declared, agentDir) {
-    return entriesByName(raw).map(([name, binding]) => {
-        const at = `content "${name}"`;
-        const e = objectWithKeys(at, binding, BINDING_KEYS);
-        if (typeof e.path !== "string" || e.path === "")
-            throw new Error(`${at}: "path" must be a non-empty string`);
-        const path = absolutePath(e.path, agentDir);
-        const shared = declared.find((entry) => entry.name.toLowerCase() === name.toLowerCase());
-        if (shared !== undefined) {
-            if (shared.name !== name) {
-                throw new Error(`${at} binds the entry ${CONTEXT_FILE} names "${shared.name}": spell it the same`);
-            }
-            if (e.description !== undefined) {
-                throw new Error(`${at} binds this machine's checkout of the entry ${CONTEXT_FILE} declares, which says "description" for ` +
-                    `every instance: give it only "path"`);
-            }
-            return { name, path, kind: "checkout" };
+export function joinContent(program, instance) {
+    for (const added of instance) {
+        const taken = program.find((entry) => entry.name.toLowerCase() === added.name.toLowerCase());
+        if (taken !== undefined) {
+            throw new Error(`content "${added.name}" is declared by the program (${CONTEXT_FILE} names "${taken.name}") and by the ` +
+                `instance: an instance adds to the program's content and does not replace it — name it otherwise`);
         }
-        const description = descriptionOf(at, e);
-        return { name, path, kind: "local", ...(description !== undefined ? { description } : {}) };
-    });
-}
-/** `path` as written in `context.local.json`, absolute: `~/` is the home directory, a relative one the agent's. */
-function absolutePath(path, agentDir) {
-    if (path === "~" || path.startsWith("~/"))
-        return join(homedir(), path.slice(1));
-    return isAbsolute(path) ? resolve(path) : resolve(agentDir, path);
+    }
+    return [...program, ...instance];
 }
 /** The entries of a `content` map, each name checked, unique ignoring case. */
 function entriesByName(raw) {
@@ -110,24 +90,43 @@ function objectWithKeys(at, value, keys) {
     }
     return e;
 }
-function descriptionOf(at, e) {
-    if (e.description !== undefined && (typeof e.description !== "string" || e.description === "")) {
-        throw new Error(`${at}: "description" must be a non-empty string`);
+/** `path` as written in an instance configuration, absolute: `~/` is the home directory, a relative one `base`'s. */
+function absolutePath(path, from, at) {
+    const absolute = configurationPath(path, from.base);
+    if (absolute === undefined) {
+        throw new Error(`${at}: "path" must be absolute here, since ${from.file} is not a file its directory could anchor`);
     }
-    return e.description;
+    return absolute;
 }
-function declareOne(name, entry) {
+function declareOne(name, entry, from) {
     const at = `content "${name}"`;
-    const e = objectWithKeys(at, entry, ENTRY_KEYS);
-    for (const key of ["github", "ref"]) {
+    const e = objectWithKeys(at, entry, [...GITHUB_KEYS, "path"]);
+    if (from.origin === "program" && e.path !== undefined) {
+        throw new Error(`${at}: ${from.file} is shared, so it declares only the repositories every instance reaches — add a directory ` +
+            `to the instance's configuration instead (fastagent content add <dir>)`);
+    }
+    for (const key of ["github", "ref", "path"]) {
         if (e[key] !== undefined && (typeof e[key] !== "string" || e[key] === "")) {
             throw new Error(`${at}: "${key}" must be a non-empty string`);
         }
     }
-    const description = descriptionOf(at, e);
+    if (e.description !== undefined && (typeof e.description !== "string" || e.description === "")) {
+        throw new Error(`${at}: "description" must be a non-empty string`);
+    }
+    const base = {
+        name,
+        origin: from.origin,
+        ...(e.description !== undefined ? { description: e.description } : {}),
+    };
+    if (e.github !== undefined && e.path !== undefined)
+        throw new Error(`${at} names both "github" and "path": give one`);
+    if (e.path !== undefined) {
+        if (e.ref !== undefined)
+            throw new Error(`${at}: "ref" applies to a repository, and ${at} is a directory`);
+        return { ...base, kind: "local", path: absolutePath(e.path, from, at) };
+    }
     if (e.github === undefined) {
-        throw new Error(`${at} needs "github": ${CONTEXT_FILE} is shared, so it declares only what every instance reaches — bind a ` +
-            `directory of this machine in ${LOCAL_CONTEXT_FILE} instead (fastagent content add <dir>)`);
+        throw new Error(`${at} needs "github"${from.origin === "instance" ? ' or "path"' : ""}`);
     }
     const repo = e.github;
     if (!isGithubRepo(repo))
@@ -136,7 +135,7 @@ function declareOne(name, entry) {
     // git reads a leading "-" as an option, and no branch, tag or commit name has one.
     if (ref?.startsWith("-"))
         throw new Error(`${at}: "ref" must name a branch, tag or commit, got "${ref}"`);
-    return { name, repo, ...(ref !== undefined ? { ref } : {}), ...(description !== undefined ? { description } : {}) };
+    return { ...base, kind: "github", repo, ...(ref !== undefined ? { ref } : {}) };
 }
 /**
  * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is