@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/content/file.d.ts

@@ -1,32 +1,43 @@
 import { type DeclaredEnvironment } from "../environment/declare.ts";
-import { type BoundContent, type ContentBinding, type ContentDeclaration, type ContentEntry, type DeclaredContent } from "./declare.ts";
+import { type ContentEntry, type DeclaredContent } from "./declare.ts";
 /** `context.json` as read: the content entries as written and as declared, and the environment. */
 export interface ContextFile {
     $schema?: string;
     content: Record<string, ContentEntry>;
     declared: DeclaredContent[];
     environment?: DeclaredEnvironment;
-}
-/** `context.local.json` as read: the bindings as written and as declared. */
-export interface LocalContextFile {
-    content: Record<string, ContentBinding>;
-    bound: BoundContent[];
+    /** The program's MCP servers as written. Their shape is the MCP reader's to check; an edit keeps them as they are. */
+    mcpServers?: Record<string, unknown>;
 }
 /** Read `text`, the contents of `path`, whole: what an edit, which writes the whole, reads. */
 export declare function parseContextFile(text: string, path: string): ContextFile;
-/** Read `text`, the contents of `path`, whole, beside the entries `context.json` declares. */
-export declare function parseLocalContextFile(text: string, path: string, declared: readonly DeclaredContent[], agentDir: string): LocalContextFile;
 /** The agent's `context.json`, read whole. */
 export declare function readContextFile(agentDir: string): ContextFile;
-/** The content of the agent in `agentDir`: what `context.json` declares, and what this machine binds. */
-export declare function loadContent(agentDir: string): ContentDeclaration;
+/** The instance configuration's content, as far as this reads it: its `content` map and where it is from. */
+export interface InstanceContent {
+    values: unknown;
+    label: string;
+    /** The configuration file's directory, which a relative `path` is relative to. */
+    directory?: string;
+}
+/**
+ * The content of the agent whose program is in `agentDir`: what its `context.json` declares, and what `instance` adds
+ * to it (an instance only adds: a name both declare is refused).
+ */
+export declare function loadContent(agentDir: string, instance?: InstanceContent): DeclaredContent[];
+/** What an instance configuration's `content` declares. */
+export declare function instanceContent({ values, label, directory }: InstanceContent): DeclaredContent[];
 /** The environment the agent in `agentDir` declares, or undefined when it declares none. */
 export declare function loadEnvironment(agentDir: string): DeclaredEnvironment | undefined;
+/** The program's `mcpServers` map as written in `context.json`, and the file's path, which names it in a refusal. */
+export declare function readProgramMcpServers(agentDir: string): {
+    values: unknown;
+    path: string;
+};
 /** The text `context.json` is written as. An environment that declares nothing is left out. */
 export declare function contextFileText(file: {
     $schema?: string;
     content: Record<string, ContentEntry>;
     environment?: DeclaredEnvironment;
+    mcpServers?: Record<string, unknown>;
 }): string;
-/** The text `context.local.json` is written as. */
-export declare function localContextFileText(content: Record<string, ContentBinding>): string;

package/dist/content/file.js

@@ -1,19 +1,19 @@
 /**
- * The agent's `context.json` and this machine's `context.local.json`, read in ONE place, so the opener, `info`,
- * `content list`, `env`, `tool` and deploy read one declaration; and the one shape each is written in. A reader
- * declares the part it uses (its content, or its environment), so a part that is refused stops what uses it and is
- * reported where it is, not as the other's; an edit declares the whole, since it writes the whole. JSON, like
- * `mcp.json` and `package.json`, so a command, a client or the agent itself can edit it without touching TypeScript.
+ * The program's `context.json` and the content an instance's configuration adds, read in ONE place, so the opener,
+ * `info`, `content list`, `env`, `tool` and deploy read one declaration; and the one shape `context.json` is written
+ * in. A reader declares the part it uses (its content, or its environment), so a part that is refused stops what uses
+ * it and is reported where it is, not as the other's; an edit declares the whole, since it writes the whole. JSON,
+ * like `mcp.json` and `package.json`, so a command, a client or the agent itself can edit it without touching
+ * TypeScript.
  */
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { CONTEXT_FILE, LOCAL_CONTEXT_FILE } from "../paths.js";
+import { CONTEXT_FILE } from "../paths.js";
 import { declareEnvironment } from "../environment/declare.js";
-import { declareBindings, declareContent, } from "./declare.js";
-const FILE_KEYS = ["$schema", "content", "environment"];
-const LOCAL_FILE_KEYS = ["content"];
+import { declareContent, joinContent } from "./declare.js";
+const FILE_KEYS = ["$schema", "content", "environment", "mcpServers"];
 /** `text`, the contents of `path`, as the object a context file is: refused when the file itself is wrong. */
-function parseFile(text, path, keys = FILE_KEYS) {
+function parseFile(text, path) {
     let raw;
     try {
         raw = JSON.parse(text);
@@ -25,12 +25,17 @@ function parseFile(text, path, keys = FILE_KEYS) {
         throw new Error(`${path} must hold a JSON object`);
     const file = raw;
     for (const key of Object.keys(file)) {
-        if (!keys.includes(key))
-            throw new Error(`${path}: unknown key "${key}" (valid keys: ${keys.join(", ")})`);
+        if (!FILE_KEYS.includes(key)) {
+            throw new Error(`${path}: unknown key "${key}" (valid keys: ${FILE_KEYS.join(", ")})`);
+        }
     }
     if (file.$schema !== undefined && typeof file.$schema !== "string") {
         throw new Error(`${path}: "$schema" must be a string`);
     }
+    if (file.mcpServers !== undefined &&
+        (typeof file.mcpServers !== "object" || file.mcpServers === null || Array.isArray(file.mcpServers))) {
+        throw new Error(`${path}: "mcpServers" must be an object of servers by name`);
+    }
     return file;
 }
 /** One part of `context.json` at `path`, declared by `declare`; its refusal names the file. */
@@ -45,24 +50,19 @@ function declarePart(path, declare) {
 /** Read `text`, the contents of `path`, whole: what an edit, which writes the whole, reads. */
 export function parseContextFile(text, path) {
     const file = parseFile(text, path);
-    const declared = declarePart(path, () => declareContent(file.content));
+    const declared = declarePart(path, () => declareContent(file.content, { origin: "program", file: CONTEXT_FILE }));
     const environment = declarePart(path, () => declareEnvironment(file.environment));
     return {
         ...(file.$schema !== undefined ? { $schema: file.$schema } : {}),
         content: (file.content ?? {}),
         declared,
         ...(environment !== undefined ? { environment } : {}),
+        ...(file.mcpServers !== undefined ? { mcpServers: file.mcpServers } : {}),
     };
 }
-/** Read `text`, the contents of `path`, whole, beside the entries `context.json` declares. */
-export function parseLocalContextFile(text, path, declared, agentDir) {
-    const file = parseFile(text, path, LOCAL_FILE_KEYS);
-    const bound = declarePart(path, () => declareBindings(file.content, declared, resolve(agentDir)));
-    return { content: (file.content ?? {}), bound };
-}
-/** The agent's context file `name` and its path, or undefined text when it has none (it declares nothing). */
-function contextFileAt(agentDir, name = CONTEXT_FILE) {
-    const path = join(resolve(agentDir), name);
+/** The agent's `context.json` and its path, or undefined text when it has none (it declares nothing). */
+function contextFileAt(agentDir) {
+    const path = join(resolve(agentDir), CONTEXT_FILE);
     try {
         return { path, text: readFileSync(path, "utf8") };
     }
@@ -77,16 +77,25 @@ export function readContextFile(agentDir) {
     const { path, text } = contextFileAt(agentDir);
     return text === undefined ? { content: {}, declared: [] } : parseContextFile(text, path);
 }
-/** This machine's `context.local.json` for the agent in `agentDir`, read whole, beside what it `declared`. */
-function readLocalContextFile(agentDir, declared) {
-    const { path, text } = contextFileAt(agentDir, LOCAL_CONTEXT_FILE);
-    return text === undefined ? { content: {}, bound: [] } : parseLocalContextFile(text, path, declared, agentDir);
-}
-/** The content of the agent in `agentDir`: what `context.json` declares, and what this machine binds. */
-export function loadContent(agentDir) {
+/**
+ * The content of the agent whose program is in `agentDir`: what its `context.json` declares, and what `instance` adds
+ * to it (an instance only adds: a name both declare is refused).
+ */
+export function loadContent(agentDir, instance) {
     const { path, text } = contextFileAt(agentDir);
-    const declared = text === undefined ? [] : declarePart(path, () => declareContent(parseFile(text, path).content));
-    return { declared, bound: readLocalContextFile(agentDir, declared).bound };
+    const program = text === undefined
+        ? []
+        : declarePart(path, () => declareContent(parseFile(text, path).content, { origin: "program", file: CONTEXT_FILE }));
+    return joinContent(program, instance === undefined ? [] : instanceContent(instance));
+}
+/** What an instance configuration's `content` declares. */
+export function instanceContent({ values, label, directory }) {
+    const content = typeof values === "object" && values !== null ? values.content : undefined;
+    return declarePart(label, () => declareContent(content, {
+        origin: "instance",
+        file: label,
+        ...(directory === undefined ? {} : { base: directory }),
+    }));
 }
 /** The environment the agent in `agentDir` declares, or undefined when it declares none. */
 export function loadEnvironment(agentDir) {
@@ -96,6 +105,11 @@ export function loadEnvironment(agentDir) {
     const file = parseFile(text, path);
     return declarePart(path, () => declareEnvironment(file.environment));
 }
+/** The program's `mcpServers` map as written in `context.json`, and the file's path, which names it in a refusal. */
+export function readProgramMcpServers(agentDir) {
+    const { path, text } = contextFileAt(agentDir);
+    return { values: text === undefined ? undefined : parseFile(text, path).mcpServers, path };
+}
 /** The text `context.json` is written as. An environment that declares nothing is left out. */
 export function contextFileText(file) {
     const packages = file.environment?.packages ?? {};
@@ -110,10 +124,9 @@ export function contextFileText(file) {
         ...(file.$schema !== undefined ? { $schema: file.$schema } : {}),
         content: file.content,
         ...(Object.keys(environment).length > 0 ? { environment } : {}),
+        ...(file.mcpServers !== undefined && Object.keys(file.mcpServers).length > 0
+            ? { mcpServers: file.mcpServers }
+            : {}),
     };
     return `${JSON.stringify(out, null, 2)}\n`;
 }
-/** The text `context.local.json` is written as. */
-export function localContextFileText(content) {
-    return `${JSON.stringify({ content }, null, 2)}\n`;
-}

package/dist/content/git.d.ts

@@ -8,16 +8,6 @@ export declare function checkoutOf(dir: string): {
     root: string;
     origin?: string;
 } | undefined;
-/**
- * Why the directory `local` cannot stand for github `repo` on this machine, or undefined when it can: it is the root
- * of a checkout whose `origin` is that repository.
- */
-export declare function checkoutProblem(local: string, repo: string): string | undefined;
-/**
- * What to say when the checkout `dir` is not at `ref`, or undefined when it is: on that branch, or at the commit `ref`
- * names. FastAgent never moves a checkout the user owns, so this is said, not acted on.
- */
-export declare function refNotice(dir: string, ref: string): string | undefined;
 /**
  * What a start did with a clone: made it, moved it to what the remote has now, found it there already, or kept it as
  * it is, for the `reason` given (git refused to touch the agent's work, or the remote could not be reached).

package/dist/content/git.js

@@ -3,11 +3,11 @@
  * `ref`, and a clone, made or brought up to date in place. git's own configuration applies throughout (credential helpers, `url.<base>.insteadOf`), so
  * a private repository is reached the way the user's own `git clone` reaches it.
  */
-import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { gitFor } from "../git.js";
 const WHY = "github content needs it on this machine";
-const { answer: gitAnswer } = gitFor(WHY);
+const { answer: checkoutAnswer } = gitFor(WHY);
 /** The `owner/repo` a GitHub remote URL names, in any of its spellings (https, ssh, scp-like), or undefined. */
 export function githubRepoOf(url) {
     const match = /^(?:(?:https?|git|ssh):\/\/(?:[^@/]+@)?github\.com\/|(?:[^@/:]+@)?github\.com:)([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/i.exec(url.trim());
@@ -24,46 +24,12 @@ function githubUrl(repo) {
 export function checkoutOf(dir) {
     if (!existsSync(dir) || !statSync(dir).isDirectory())
         return undefined;
-    const root = gitAnswer(["rev-parse", "--show-toplevel"], dir);
+    const root = checkoutAnswer(["rev-parse", "--show-toplevel"], dir);
     if (root === undefined)
         return undefined;
-    const origin = gitAnswer(["config", "--get", "remote.origin.url"], root);
+    const origin = checkoutAnswer(["config", "--get", "remote.origin.url"], root);
     return { root, ...(origin ? { origin } : {}) };
 }
-/**
- * Why the directory `local` cannot stand for github `repo` on this machine, or undefined when it can: it is the root
- * of a checkout whose `origin` is that repository.
- */
-export function checkoutProblem(local, repo) {
-    if (!existsSync(local))
-        return "does not exist";
-    const checkout = checkoutOf(local);
-    if (checkout === undefined)
-        return "is not a git checkout";
-    if (realpathSync(checkout.root) !== realpathSync(local))
-        return `is inside the checkout ${checkout.root}, not its root`;
-    const of = checkout.origin === undefined ? undefined : githubRepoOf(checkout.origin);
-    if (of?.toLowerCase() !== repo.toLowerCase()) {
-        return `is a checkout of ${checkout.origin ?? "no origin"}, not of github ${repo}`;
-    }
-    return undefined;
-}
-/**
- * What to say when the checkout `dir` is not at `ref`, or undefined when it is: on that branch, or at the commit `ref`
- * names. FastAgent never moves a checkout the user owns, so this is said, not acted on.
- */
-export function refNotice(dir, ref) {
-    const branch = gitAnswer(["symbolic-ref", "--quiet", "--short", "HEAD"], dir);
-    if (branch === ref)
-        return undefined;
-    const head = gitAnswer(["rev-parse", "HEAD"], dir);
-    const target = gitAnswer(["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`], dir);
-    if (head !== undefined && head === target) {
-        return undefined;
-    }
-    const at = branch ?? `a detached ${head?.slice(0, 7) ?? "HEAD"}`;
-    return `the checkout is on ${at}, declared ${ref}; it is left as it is`;
-}
 /** A commit named in full: fetched by its hash, since `clone --branch` takes only a branch or a tag. */
 const FULL_COMMIT = /^[0-9a-f]{40}$/i;
 /**
@@ -97,7 +63,7 @@ const HELPER_KEY = "credential.https://github.com.helper";
  */
 export async function refreshClone(repo, ref, dir, env = process.env) {
     // The agent's environment, whose GITHUB_TOKEN the clone's credential helper reads.
-    const { run: runGit } = gitFor(WHY, env);
+    const { run: runGit, answer: gitAnswer } = gitFor(WHY, env);
     // A library caller can hand this anything; git reads a leading "-" as an option, and no repository or ref has one
     // (a declaration with one is refused at load, declare.ts).
     if (repo.startsWith("-") || ref?.startsWith("-")) {

package/dist/content/resolve.d.ts

@@ -1,4 +1,4 @@
-import { type BoundContent, type ContentDeclaration, type DeclaredContent } from "./declare.ts";
+import { type DeclaredContent } from "./declare.ts";
 import { type CloneOutcome } from "./git.ts";
 /** A content entry, resolved for this instance. */
 export type ResolvedContent = {
@@ -8,42 +8,38 @@ export type ResolvedContent = {
     description?: string;
     /** Where the agent reaches it on this instance, absolute. */
     location: string;
-    /** What to tell the user about how it resolved: a checkout off its `ref`, a clone not made yet. */
+    /** What to tell the user about how it resolved: a clone not made yet. */
     notices: string[];
 } & ({
-    /** A directory only this machine has, bound in `context.local.json`. */
+    /** A directory of this machine, where the instance configuration says. */
     kind: "local";
 } | {
+    /** A clone fastagent makes at `content/<name>` and brings up to date at each start while it holds nothing of the agent's. */
     kind: "github";
     /** `owner/repo`. */
     repo: string;
     ref?: string;
-    /**
-     * A clone fastagent makes at `content/<name>` and brings up to date at each start while it holds nothing of the
-     * agent's. False when this machine binds its own checkout, which is never touched.
-     */
-    clone: boolean;
 });
+/** The directories an instance's content is kept apart from. */
+export interface ContentPlaces {
+    /** The definition's own directory, which is released and read as it is. */
+    dir: string;
+    /** The instance's working directory, where clones are made. */
+    workdir: string;
+}
 /** Resolve the agent's content for this instance. Refuses, naming the entry, what cannot be. */
-export declare function resolveContent(agentDir: string, { declared, bound }: ContentDeclaration): ResolvedContent[];
+export declare function resolveContent(declared: readonly DeclaredContent[], places: ContentPlaces): ResolvedContent[];
 /**
- * The bindings of a directory only this machine has that point at nothing here: the directory was moved or removed.
- * Not an error, since the binding is this machine's alone; the agent is not told of it, and whoever opens the agent
- * says so.
+ * Whether the content `name` can be the directory `target` of this machine: one that exists, and is apart from the
+ * definition's directory, since a definition is released, content is kept, and one directory cannot be both. The
+ * working directory is the instance's own writable place, so a directory inside it is only a directory the agent
+ * already reaches. Refuses, naming the entry, what cannot be.
  */
-export declare function contentAbsentHere({ bound }: ContentDeclaration): BoundContent[];
-/** What is said of a binding {@link contentAbsentHere} returns, after the word "content". */
-export declare function absentNotice(binding: BoundContent): string;
-/**
- * Whether the content `name` can be bound to the directory `target` of this machine: a directory, apart from the agent
- * directory, and for a declared repository the root of a checkout of it. Returns what to tell the user (a checkout off
- * its `ref`); refuses, naming the entry, what cannot be.
- */
-export declare function checkBinding(agentDir: string, name: string, target: string, repository?: Pick<DeclaredContent, "repo" | "ref">): string[];
+export declare function checkDirectory({ dir }: Pick<ContentPlaces, "dir">, name: string, target: string): void;
 /**
  * Make a clone real, or bring it up to date at its `ref` in place, by git's rules, which never overwrite what the
  * agent did in it (git.ts `refreshClone`): what git refuses, or a remote that cannot be reached, keeps it as it is,
- * with the reason. Only a process that runs the agent calls this. A checkout this machine binds is never cloned over.
+ * with the reason. Only a process that runs the agent calls this.
  */
 export declare function cloneContent(entry: Extract<ResolvedContent, {
     kind: "github";

package/dist/content/resolve.js

@@ -1,83 +1,58 @@
 /**
  * WHERE each content entry is, for THIS instance: the one answer the prompt, the coding tools, authored tools, `info`
- * and `deploy` all read (docs/design/core.md §2). A repository `context.json` declares is fastagent's clone at
- * `content/<name>`, or this machine's own checkout of it where `context.local.json` binds one; a directory only this
- * machine has is where its binding says. Reads the disk (git included); never the network, never a write. Making a
- * clone real is `cloneContent`'s, and only a process that runs the agent asks for it.
+ * and `deploy` all read (docs/design/core.md §2). A repository is fastagent's clone at `content/<name>` in the
+ * instance's working directory; a directory is where the instance configuration says. Reads the disk (git included);
+ * never the network, never a write. Making a clone real is `cloneContent`'s, and only a process that runs the agent
+ * asks for it.
  */
 import { lstatSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { LOCAL_CONTEXT_FILE, contentEntryPath } from "../paths.js";
+import { contentEntryPath } from "../paths.js";
 import { nestingError } from "./declare.js";
-import { checkoutProblem, refNotice, refreshClone } from "./git.js";
+import { refreshClone } from "./git.js";
 import { ensureContentDir } from "./mount.js";
 /** Resolve the agent's content for this instance. Refuses, naming the entry, what cannot be. */
-export function resolveContent(agentDir, { declared, bound }) {
-    const shared = declared.map((entry) => resolveRepository(agentDir, entry, bound.find((binding) => binding.kind === "checkout" && binding.name === entry.name)));
-    const local = bound
-        .filter((binding) => binding.kind === "local" && statOrMissing(binding.path) !== undefined)
-        .map((binding) => resolveLocal(agentDir, binding));
-    return [...shared, ...local];
+export function resolveContent(declared, places) {
+    return declared.map((entry) => entry.kind === "github" ? resolveRepository(places, entry) : resolveLocal(places, entry));
 }
-/**
- * The bindings of a directory only this machine has that point at nothing here: the directory was moved or removed.
- * Not an error, since the binding is this machine's alone; the agent is not told of it, and whoever opens the agent
- * says so.
- */
-export function contentAbsentHere({ bound }) {
-    return bound.filter((binding) => binding.kind === "local" && statOrMissing(binding.path) === undefined);
-}
-/** What is said of a binding {@link contentAbsentHere} returns, after the word "content". */
-export function absentNotice(binding) {
-    return (`${binding.name}: bound in ${LOCAL_CONTEXT_FILE} to ${binding.path}, which does not exist here: the agent is ` +
-        `not told of it`);
-}
-function resolveRepository(agentDir, entry, checkout) {
+function resolveRepository({ workdir }, entry) {
     const { name, description } = entry;
-    const repository = {
-        name,
-        ...(description !== undefined ? { description } : {}),
-        kind: "github",
-        repo: entry.repo,
-        ...(entry.ref !== undefined ? { ref: entry.ref } : {}),
-    };
-    if (checkout !== undefined && statOrMissing(checkout.path) !== undefined) {
-        const location = realpathSync(checkout.path);
-        const notices = checkBinding(agentDir, name, location, entry);
-        return { ...repository, location, notices, clone: false };
-    }
-    const location = contentEntryPath(agentDir, name);
+    const location = contentEntryPath(workdir, name);
     const found = lstatOrMissing(location);
     if (found?.isSymbolicLink()) {
         throw new Error(`content "${name}": content/${name} is a link, and content/ holds only the clones fastagent makes — remove ` +
-            `the link, and bind a checkout of your own in ${LOCAL_CONTEXT_FILE} instead (fastagent content add <dir>)`);
+            `the link, and add the directory it points at as content of its own (fastagent content add <dir>)`);
     }
     if (found && !found.isDirectory())
         throw new Error(`content "${name}": ${location} is not a directory`);
-    const notices = found ? [] : ["not cloned yet: it is cloned when the agent starts"];
-    if (checkout !== undefined) {
-        notices.unshift(`bound in ${LOCAL_CONTEXT_FILE} to ${checkout.path}, which does not exist here: the clone is used`);
-    }
-    return { ...repository, location, notices, clone: true };
-}
-function resolveLocal(agentDir, binding) {
-    const { name, description } = binding;
-    const location = realpathSync(binding.path);
-    checkBinding(agentDir, name, location);
     return {
         name,
         ...(description !== undefined ? { description } : {}),
+        kind: "github",
+        repo: entry.repo,
+        ...(entry.ref !== undefined ? { ref: entry.ref } : {}),
         location,
-        notices: [],
+        notices: found ? [] : ["not cloned yet: it is cloned when the agent starts"],
+    };
+}
+function resolveLocal(places, entry) {
+    const { name, description } = entry;
+    checkDirectory(places, name, entry.path);
+    return {
+        name,
+        ...(description !== undefined ? { description } : {}),
         kind: "local",
+        location: realpathSync(entry.path),
+        notices: [],
     };
 }
 /**
- * Whether the content `name` can be bound to the directory `target` of this machine: a directory, apart from the agent
- * directory, and for a declared repository the root of a checkout of it. Returns what to tell the user (a checkout off
- * its `ref`); refuses, naming the entry, what cannot be.
+ * Whether the content `name` can be the directory `target` of this machine: one that exists, and is apart from the
+ * definition's directory, since a definition is released, content is kept, and one directory cannot be both. The
+ * working directory is the instance's own writable place, so a directory inside it is only a directory the agent
+ * already reaches. Refuses, naming the entry, what cannot be.
  */
-export function checkBinding(agentDir, name, target, repository) {
+export function checkDirectory({ dir }, name, target) {
     const stat = statOrMissing(target);
     if (!stat)
         throw new Error(`content "${name}": ${target} does not exist`);
@@ -85,25 +60,16 @@ export function checkBinding(agentDir, name, target, repository) {
         throw new Error(`content "${name}": ${target} is not a directory`);
     // A symlink can still put one inside the other, so ask of the real paths — including for an agent directory `init`
     // is about to create, which a symlinked ancestor still places.
-    const nested = nestingError(realPathOf(agentDir), realpathSync(target), name);
+    const nested = nestingError(realPathOf(dir), realpathSync(target), name);
     if (nested)
         throw new Error(nested);
-    if (repository === undefined)
-        return [];
-    const problem = checkoutProblem(target, repository.repo);
-    if (problem)
-        throw new Error(`content "${name}": ${target} ${problem}`);
-    const offRef = repository.ref === undefined ? undefined : refNotice(target, repository.ref);
-    return offRef ? [offRef] : [];
 }
 /**
  * Make a clone real, or bring it up to date at its `ref` in place, by git's rules, which never overwrite what the
  * agent did in it (git.ts `refreshClone`): what git refuses, or a remote that cannot be reached, keeps it as it is,
- * with the reason. Only a process that runs the agent calls this. A checkout this machine binds is never cloned over.
+ * with the reason. Only a process that runs the agent calls this.
  */
 export async function cloneContent(entry, env = process.env) {
-    if (!entry.clone)
-        throw new Error(`content "${entry.name}" is bound to the checkout ${entry.location}, not a clone`);
     ensureContentDir(dirname(entry.location));
     return refreshClone(entry.repo, entry.ref, entry.location, env).catch((error) => {
         throw new Error(`content "${entry.name}": ${error.message}`);

package/dist/content/source.d.ts

@@ -1,4 +1,4 @@
-import { type ContentBinding, type ContentEntry } from "./declare.ts";
+import { type ContentEntry } from "./declare.ts";
 export interface SourceOptions {
     name?: string;
     /** A github entry's branch, tag or commit. */
@@ -6,19 +6,18 @@ export interface SourceOptions {
     description?: string;
 }
 /**
- * A content entry to add, by name: the repository `context.json` declares for every instance, this machine's binding
- * in `context.local.json`, or both (a checkout of the declared repository). At least one.
+ * A content entry to add, by name. It is written to the instance's `fastagent.json`, or, with `program`, to the
+ * program's `context.json`, which every instance of it reaches and so holds repositories only.
  */
 export interface ContentAddition {
     name: string;
-    entry?: ContentEntry;
-    binding?: ContentBinding;
+    entry: ContentEntry;
+    program?: boolean;
 }
 /**
  * The addition `source` asks for, with what to tell the user about how it was read. `github:owner/repo` is a
- * repository fastagent clones. The root of a checkout whose `origin` is on GitHub is that repository, declared for
- * every instance and bound to this checkout here. Any other directory, a subdirectory of such a checkout included, is
- * bound on this machine alone. The name defaults to the repository's or the directory's.
+ * repository fastagent clones. Any other source is a directory the agent works in as it is, a checkout of a GitHub
+ * repository included, which is then said. The name defaults to the repository's or the directory's.
  */
 export declare function readContentSource(source: string, cwd: string, options?: SourceOptions): {
     addition: ContentAddition;

package/dist/content/source.js

@@ -1,52 +1,34 @@
 /**
  * What a command's `<source>` adds (`init --content`, `fastagent content add`; docs/design/agent-cli.md §3), read the
- * same way by both: `github:owner/repo`, the root of a GitHub checkout, or any other directory.
+ * same way by both: `github:owner/repo`, or a directory.
  */
-import { realpathSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { isGithubRepo } from "./declare.js";
 import { checkoutOf, githubRepoOf } from "./git.js";
 /**
  * The addition `source` asks for, with what to tell the user about how it was read. `github:owner/repo` is a
- * repository fastagent clones. The root of a checkout whose `origin` is on GitHub is that repository, declared for
- * every instance and bound to this checkout here. Any other directory, a subdirectory of such a checkout included, is
- * bound on this machine alone. The name defaults to the repository's or the directory's.
+ * repository fastagent clones. Any other source is a directory the agent works in as it is, a checkout of a GitHub
+ * repository included, which is then said. The name defaults to the repository's or the directory's.
  */
 export function readContentSource(source, cwd, options = {}) {
-    const treated = {
-        ...(options.description !== undefined ? { description: options.description } : {}),
-    };
-    const ref = options.ref !== undefined ? { ref: options.ref } : {};
+    const treated = options.description !== undefined ? { description: options.description } : {};
     const repoName = (repo) => repo.slice(repo.indexOf("/") + 1);
     if (source.startsWith("github:")) {
         const repo = source.slice("github:".length);
         if (!isGithubRepo(repo))
             throw new Error(`${source} names no repository: write github:owner/repo`);
+        const ref = options.ref !== undefined ? { ref: options.ref } : {};
         return {
             addition: { name: options.name ?? repoName(repo), entry: { github: repo, ...ref, ...treated } },
             notes: [],
         };
     }
+    if (options.ref !== undefined) {
+        throw new Error(`--ref applies to a repository, and ${resolve(cwd, source)} is a directory`);
+    }
     const dir = resolve(cwd, source);
     const checkout = checkoutOf(dir);
     const repo = checkout?.origin === undefined ? undefined : githubRepoOf(checkout.origin);
-    const atRoot = checkout !== undefined && realpathSync(dir) === realpathSync(checkout.root);
-    if (repo !== undefined && atRoot) {
-        const root = checkout.root;
-        return {
-            addition: {
-                name: options.name ?? repoName(repo),
-                entry: { github: repo, ...ref, ...treated },
-                binding: { path: root },
-            },
-            notes: [],
-        };
-    }
-    if (options.ref !== undefined) {
-        throw new Error(`--ref applies to a repository, and ${dir} is bound as a directory of this machine`);
-    }
-    const notes = repo !== undefined && !atRoot
-        ? [`${dir} is in a checkout of github ${repo}: add github:${repo} for the whole repository`]
-        : [];
-    return { addition: { name: options.name ?? basename(dir), binding: { path: dir, ...treated } }, notes };
+    const notes = repo === undefined ? [] : [`${dir} is in a checkout of github ${repo}: add github:${repo} to have it cloned`];
+    return { addition: { name: options.name ?? basename(dir), entry: { path: dir, ...treated } }, notes };
 }

package/dist/credentials-page.d.ts

@@ -0,0 +1,26 @@
+import type { SetupGuide } from "./channels/setup.ts";
+/** What the person pastes at one step: its fields are checked together. */
+export interface CredentialsStep {
+    label: string;
+    guide: SetupGuide;
+    fields: readonly {
+        name: string;
+        label: string;
+        secret?: boolean;
+    }[];
+}
+export interface CredentialsPage {
+    url: string;
+    /** Settles once every value was accepted; rejects when `accept` failed for a reason other than a refusal. */
+    done: Promise<void>;
+    close(): Promise<void>;
+}
+export declare function startCredentialsPage(input: {
+    /** "Connect Slack". */
+    title: string;
+    /** What the done page says: "Slack connected". */
+    doneHeading: string;
+    steps: readonly CredentialsStep[];
+    /** Check a step's values and keep them. Throws {@link SetupRefused} to stay on the form with the reason; anything else ends the page. */
+    accept(step: number, values: Record<string, string>): Promise<void>;
+}): Promise<CredentialsPage>;