@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/content/declare.d.ts

@@ -0,0 +1,70 @@
+/** One content entry as `context.json` holds it, under its name: a repository. */
+export interface ContentEntry {
+    /** The repository, `owner/repo`. */
+    github: string;
+    /** The branch, tag or commit to clone. */
+    ref?: string;
+    /** The agent knows it and does not write it. */
+    readonly?: boolean;
+    /** One sentence for the agent: what this is, and how to treat it. */
+    description?: string;
+}
+/** A declared entry, read. */
+export interface DeclaredContent {
+    name: string;
+    /** `owner/repo`. */
+    repo: string;
+    ref?: string;
+    readonly: boolean;
+    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;
+    readonly?: boolean;
+    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. */
+    kind: "local";
+    readonly: boolean;
+    description?: string;
+});
+/** What an agent's content is declared as: the shared declaration, and this machine's bindings. */
+export interface ContentDeclaration {
+    declared: DeclaredContent[];
+    bound: BoundContent[];
+}
+/** 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. */
+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.
+ */
+export declare function declareBindings(raw: unknown, declared: readonly DeclaredContent[], agentDir: string): BoundContent[];
+/**
+ * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
+ * released, writable content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
+ * it of the real paths.
+ */
+export declare function nestingError(agentDir: string, location: string, name: string): string | undefined;

package/dist/content/declare.js

@@ -0,0 +1,163 @@
+/**
+ * WHAT AN AUTHOR DECLARES an agent works on or knows, 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.
+ */
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { CONTEXT_FILE, LOCAL_CONTEXT_FILE, 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.
+ */
+const ENTRY_KEYS = ["github", "ref", "readonly", "description"];
+const BINDING_KEYS = ["path", "readonly", "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. */
+export function isContentName(name) {
+    return NAME.test(name);
+}
+const GITHUB_REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** Whether `repo` names a GitHub repository, `owner/repo`. */
+export function isGithubRepo(repo) {
+    return GITHUB_REPO.test(repo);
+}
+/** `entry` with its keys in {@link ENTRY_KEYS} order: the form 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);
+}
+function pick(value, keys) {
+    const out = {};
+    for (const key of keys) {
+        const field = value[key];
+        if (field !== undefined)
+            out[key] = field;
+    }
+    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 `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.
+ */
+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`);
+            }
+            for (const key of ["readonly", "description"]) {
+                if (e[key] !== undefined) {
+                    throw new Error(`${at} binds this machine's checkout of the entry ${CONTEXT_FILE} declares, which says "${key}" for ` +
+                        `every instance: give it only "path"`);
+                }
+            }
+            return { name, path, kind: "checkout" };
+        }
+        const treatment = treatmentOf(at, e);
+        return { name, path, kind: "local", ...treatment };
+    });
+}
+/** `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);
+}
+/** The entries of a `content` map, each name checked, unique ignoring case. */
+function entriesByName(raw) {
+    if (raw === undefined)
+        return [];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`"content" must be an object of entries by name`);
+    }
+    const seen = new Map();
+    return Object.entries(raw).map(([name, entry]) => {
+        if (!NAME.test(name)) {
+            throw new Error(`content "${name}": a name is one path segment of letters, digits, "-" and "_"`);
+        }
+        const key = name.toLowerCase();
+        const taken = seen.get(key);
+        // Equal ignoring case is the same name: it becomes a directory, and some filesystems do not tell them apart.
+        if (taken !== undefined) {
+            throw new Error(`two content entries are named "${taken}" and "${name}" — names must differ ignoring case`);
+        }
+        seen.set(key, name);
+        return [name, entry];
+    });
+}
+function objectWithKeys(at, value, keys) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${at} must be an object`);
+    const e = value;
+    for (const key of Object.keys(e)) {
+        if (!keys.includes(key))
+            throw new Error(`${at}: unknown key "${key}" (valid keys: ${keys.join(", ")})`);
+    }
+    return e;
+}
+function treatmentOf(at, e) {
+    if (e.description !== undefined && (typeof e.description !== "string" || e.description === "")) {
+        throw new Error(`${at}: "description" must be a non-empty string`);
+    }
+    if (e.readonly !== undefined && typeof e.readonly !== "boolean")
+        throw new Error(`${at}: "readonly" must be a boolean`);
+    const description = e.description;
+    return { readonly: e.readonly === true, ...(description !== undefined ? { description } : {}) };
+}
+function declareOne(name, entry) {
+    const at = `content "${name}"`;
+    const e = objectWithKeys(at, entry, ENTRY_KEYS);
+    for (const key of ["github", "ref"]) {
+        if (e[key] !== undefined && (typeof e[key] !== "string" || e[key] === "")) {
+            throw new Error(`${at}: "${key}" must be a non-empty string`);
+        }
+    }
+    const treatment = treatmentOf(at, e);
+    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>)`);
+    }
+    const repo = e.github;
+    if (!isGithubRepo(repo))
+        throw new Error(`${at}: "github" must be "owner/repo", got "${repo}"`);
+    const ref = e.ref;
+    // 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 } : {}), ...treatment };
+}
+/**
+ * A directory the agent is bound to and the agent directory are kept apart (agent-model.md §2): a definition is
+ * released, writable content is kept, and one directory cannot be both. The ONE statement of the rule; resolve.ts asks
+ * it of the real paths.
+ */
+export function nestingError(agentDir, location, name) {
+    if (!isAbsolute(location))
+        throw new Error(`nestingError: "${location}" is not absolute`);
+    if (isUnderDir(agentDir, location)) {
+        return (`content "${name}" (${location}) contains the agent directory ${agentDir} — an agent lives in a directory of ` +
+            `its own: move it out of ${location}, or bind other content`);
+    }
+    if (isUnderDir(location, agentDir)) {
+        return (`content "${name}" (${location}) is inside the agent directory ${agentDir} — content is a directory of its ` +
+            `own: move it out, or bind other content`);
+    }
+    return undefined;
+}

package/dist/content/file.d.ts

@@ -0,0 +1,32 @@
+import { type DeclaredEnvironment } from "../environment/declare.ts";
+import { type BoundContent, type ContentBinding, type ContentDeclaration, 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[];
+}
+/** 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 environment the agent in `agentDir` declares, or undefined when it declares none. */
+export declare function loadEnvironment(agentDir: string): DeclaredEnvironment | undefined;
+/** 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;
+}): string;
+/** The text `context.local.json` is written as. */
+export declare function localContextFileText(content: Record<string, ContentBinding>): string;

package/dist/content/file.js

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CONTEXT_FILE, LOCAL_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"];
+/** `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) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON: ${error.message}`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        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.$schema !== undefined && typeof file.$schema !== "string") {
+        throw new Error(`${path}: "$schema" must be a string`);
+    }
+    return file;
+}
+/** One part of `context.json` at `path`, declared by `declare`; its refusal names the file. */
+function declarePart(path, declare) {
+    try {
+        return declare();
+    }
+    catch (error) {
+        throw new Error(`${path}: ${error.message}`);
+    }
+}
+/** 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 environment = declarePart(path, () => declareEnvironment(file.environment));
+    return {
+        ...(file.$schema !== undefined ? { $schema: file.$schema } : {}),
+        content: (file.content ?? {}),
+        declared,
+        ...(environment !== undefined ? { environment } : {}),
+    };
+}
+/** 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);
+    try {
+        return { path, text: readFileSync(path, "utf8") };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path };
+        throw error;
+    }
+}
+/** The agent's `context.json`, read whole. */
+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) {
+    const { path, text } = contextFileAt(agentDir);
+    const declared = text === undefined ? [] : declarePart(path, () => declareContent(parseFile(text, path).content));
+    return { declared, bound: readLocalContextFile(agentDir, declared).bound };
+}
+/** The environment the agent in `agentDir` declares, or undefined when it declares none. */
+export function loadEnvironment(agentDir) {
+    const { path, text } = contextFileAt(agentDir);
+    if (text === undefined)
+        return undefined;
+    const file = parseFile(text, path);
+    return declarePart(path, () => declareEnvironment(file.environment));
+}
+/** The text `context.json` is written as. An environment that declares nothing is left out. */
+export function contextFileText(file) {
+    const packages = file.environment?.packages ?? {};
+    const aptPackages = file.environment?.aptPackages ?? [];
+    const variables = file.environment?.variables ?? {};
+    const environment = {
+        ...(Object.keys(packages).length > 0 ? { packages } : {}),
+        ...(aptPackages.length > 0 ? { aptPackages } : {}),
+        ...(Object.keys(variables).length > 0 ? { variables } : {}),
+    };
+    const out = {
+        ...(file.$schema !== undefined ? { $schema: file.$schema } : {}),
+        content: file.content,
+        ...(Object.keys(environment).length > 0 ? { environment } : {}),
+    };
+    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

@@ -0,0 +1,41 @@
+/** The `owner/repo` a GitHub remote URL names, in any of its spellings (https, ssh, scp-like), or undefined. */
+export declare function githubRepoOf(url: string): string | undefined;
+/**
+ * The checkout `dir` is in: its root, and its `origin` as configured (not as `insteadOf` rewrites it). Undefined when
+ * `dir` is not a directory inside a git checkout.
+ */
+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).
+ */
+export type CloneOutcome = {
+    outcome: "cloned" | "updated" | "current";
+} | {
+    outcome: "kept";
+    reason: string;
+};
+/**
+ * Clone github `repo` at `ref` (its default branch when unset) into `dir`, or bring the clone there up to date IN
+ * PLACE, by git's own rules: a fetch, then a fast-forward of the branch it is on, or a checkout of the tag or commit
+ * it is pinned to. git refuses whatever would overwrite the agent's work (a changed file the update touches, an
+ * untracked file it would replace, commits the remote does not have), and the clone is then kept as it is, with
+ * git's reason; so it is when the fetch fails, or when the clone is on another branch than declared. Nothing is
+ * deleted: the agent's branches, stashes and the changes an update does not touch stay where they are.
+ * - None yet: cloned beside it and renamed into place. A first clone that fails stops the start.
+ * - A clone of another repository there (the entry was renamed or redeclared): refused, naming it.
+ */
+export declare function refreshClone(repo: string, ref: string | undefined, dir: string): Promise<CloneOutcome>;

package/dist/content/git.js

@@ -0,0 +1,217 @@
+/**
+ * The git GitHub content needs on this machine: which repository a checkout is of, whether it is at the declared
+ * `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 { basename, dirname, join } from "node:path";
+import { gitFor } from "../git.js";
+const { answer: gitAnswer, run: runGit } = gitFor("github content needs it on this machine");
+/** 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());
+    return match ? `${match[1]}/${match[2]}` : undefined;
+}
+/** The URL fastagent clones github `repo` from. */
+function githubUrl(repo) {
+    return `https://github.com/${repo}.git`;
+}
+/**
+ * The checkout `dir` is in: its root, and its `origin` as configured (not as `insteadOf` rewrites it). Undefined when
+ * `dir` is not a directory inside a git checkout.
+ */
+export function checkoutOf(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return undefined;
+    const root = gitAnswer(["rev-parse", "--show-toplevel"], dir);
+    if (root === undefined)
+        return undefined;
+    const origin = gitAnswer(["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;
+/**
+ * git aborts a transfer that moves under 1 KB/s for 15 seconds, so a network that drops packets silently does not hold
+ * a start until TCP gives up, while a large transfer that is moving is left alone. http(s) only. Not covered by a
+ * test: it takes a remote that stops answering.
+ */
+const SLOW_NETWORK = ["-c", "http.lowSpeedLimit=1000", "-c", "http.lowSpeedTime=15"];
+/**
+ * The ref that holds the commit a clone pinned to a commit was last put on. Fetching a commit by its hash creates no
+ * ref, and without one every commit of a detached clone would look like the agent's own.
+ */
+const PINNED = "refs/remotes/origin/pinned";
+/**
+ * The credential a clone of fastagent's reaches GitHub with when git has none of its own: `GITHUB_TOKEN`, read from
+ * the environment each time git asks, so the token is never written to disk. Set in the clone's own config, so the
+ * agent's `git push` there uses it too. git asks its own helpers first (a credential manager on a laptop), then this
+ * one, which answers nothing when the variable is unset.
+ */
+const TOKEN_HELPER = '!f() { test "$1" = get && test -n "$GITHUB_TOKEN" && printf "username=x-access-token\\npassword=%s\\n" "$GITHUB_TOKEN"; }; f';
+const HELPER_KEY = "credential.https://github.com.helper";
+/**
+ * Clone github `repo` at `ref` (its default branch when unset) into `dir`, or bring the clone there up to date IN
+ * PLACE, by git's own rules: a fetch, then a fast-forward of the branch it is on, or a checkout of the tag or commit
+ * it is pinned to. git refuses whatever would overwrite the agent's work (a changed file the update touches, an
+ * untracked file it would replace, commits the remote does not have), and the clone is then kept as it is, with
+ * git's reason; so it is when the fetch fails, or when the clone is on another branch than declared. Nothing is
+ * deleted: the agent's branches, stashes and the changes an update does not touch stay where they are.
+ * - None yet: cloned beside it and renamed into place. A first clone that fails stops the start.
+ * - A clone of another repository there (the entry was renamed or redeclared): refused, naming it.
+ */
+export async function refreshClone(repo, ref, dir) {
+    // 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("-")) {
+        throw new Error(`github ${repo}${ref !== undefined ? ` at ${ref}` : ""} would reach git as an option`);
+    }
+    if (!existsSync(dir))
+        return cloneInto(repo, ref, dir);
+    const origin = gitAnswer(["config", "--get", "remote.origin.url"], dir);
+    if (origin === undefined || githubRepoOf(origin)?.toLowerCase() !== repo.toLowerCase()) {
+        throw new Error(`${dir} is a clone of ${origin ?? "no repository"}, not of github ${repo}: move it away (push what should last ` +
+            `first), then start again`);
+    }
+    const kept = (reason) => ({ outcome: "kept", reason });
+    const branch = gitAnswer(["symbolic-ref", "--quiet", "--short", "HEAD"], dir);
+    const declared = ref ?? gitAnswer(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], dir)?.replace(/^origin\//, "");
+    if (branch !== undefined && branch !== declared) {
+        return kept(`it is on branch ${branch}, declared ${ref ?? `the default branch${declared ? `, ${declared}` : ""}`}`);
+    }
+    if (branch === undefined) {
+        if (ref === undefined)
+            return kept("it is on a detached commit, declared the default branch");
+        // Moving a detached HEAD away from commits of its own would leave them held by nothing.
+        if (gitAnswer(["rev-list", "--count", "HEAD", "--not", "--branches", "--tags", "--remotes"], dir) !== "0") {
+            return kept("it has commits no branch or tag holds");
+        }
+    }
+    // A clone made before the helper existed, or whose config was edited, gets it back.
+    await runGit(["config", HELPER_KEY, TOKEN_HELPER], dir);
+    const before = gitAnswer(["rev-parse", "HEAD"], dir);
+    // Pinned to a commit and on it: nothing a remote says can change that.
+    if (ref !== undefined && FULL_COMMIT.test(ref) && before === ref.toLowerCase())
+        return { outcome: "current" };
+    try {
+        await runGit([...SLOW_NETWORK, "fetch", "-q", "--end-of-options", "origin", branch ?? ref], dir);
+    }
+    catch (error) {
+        return kept(`could not reach github ${repo}: ${gitReason(error)}`);
+    }
+    if (gitAnswer(["rev-parse", "FETCH_HEAD^{commit}"], dir) === before)
+        return { outcome: "current" };
+    try {
+        if (branch !== undefined) {
+            await runGit(["merge", "-q", "--ff-only", "FETCH_HEAD"], dir);
+        }
+        else {
+            await runGit(["checkout", "-q", "--detach", "FETCH_HEAD"], dir);
+            await runGit(["update-ref", PINNED, "HEAD"], dir);
+        }
+    }
+    catch (error) {
+        return kept(`git would not update it: ${gitReason(error)}`);
+    }
+    return { outcome: "updated" };
+}
+/** git's own words for a refusal, without its hints. */
+function gitReason(error) {
+    return error.message
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "" && !line.startsWith("hint:"))
+        .join(" ");
+}
+/**
+ * Clone github `repo` at `ref` into `dir`, which does not exist: built beside it and renamed into place, so another
+ * process reads no clone or a whole one. When another process put its own there first, that one stands and this one
+ * is discarded. Shallow: a starting point to work from; a later fetch brings the history an update needs.
+ */
+async function cloneInto(repo, ref, dir) {
+    const parent = dirname(dir);
+    mkdirSync(parent, { recursive: true });
+    const next = join(parent, `.${basename(dir)}.next-${process.pid}-${Date.now()}`);
+    const url = githubUrl(repo);
+    try {
+        try {
+            if (ref !== undefined && FULL_COMMIT.test(ref)) {
+                await runGit(["init", "-q", next], parent);
+                await runGit(["config", HELPER_KEY, TOKEN_HELPER], next);
+                await runGit(["remote", "add", "origin", url], next);
+                await runGit([...SLOW_NETWORK, "fetch", "-q", "--depth", "1", "--end-of-options", "origin", ref], next);
+                await runGit(["checkout", "-q", "--detach", "FETCH_HEAD"], next);
+                await runGit(["update-ref", PINNED, "HEAD"], next);
+            }
+            else {
+                // One token, and `--` before the operands: a declared value never reaches git as an option of its own.
+                const branch = ref !== undefined ? [`--branch=${ref}`] : [];
+                await runGit([
+                    ...SLOW_NETWORK,
+                    "clone",
+                    "-q",
+                    "--depth",
+                    "1",
+                    "--config",
+                    `${HELPER_KEY}=${TOKEN_HELPER}`,
+                    ...branch,
+                    "--",
+                    url,
+                    next,
+                ], parent);
+            }
+        }
+        catch (error) {
+            throw new Error(`could not clone github ${repo}${ref !== undefined ? ` at ${ref}` : ""}: ${error.message} — ` +
+                `git's own credentials on this machine are used (a credential helper, or url.<base>.insteadOf for SSH)`);
+        }
+        try {
+            renameSync(next, dir);
+        }
+        catch (error) {
+            // Another process's clone got there first (renaming onto a directory that is not empty fails): it stands.
+            const code = error.code;
+            if ((code === "ENOTEMPTY" || code === "EEXIST") && existsSync(dir))
+                return { outcome: "current" };
+            throw error;
+        }
+        return { outcome: "cloned" };
+    }
+    finally {
+        rmSync(next, { recursive: true, force: true });
+    }
+}

package/dist/content/mount.d.ts

@@ -0,0 +1,2 @@
+/** Make `dir`, the agent's `content/`, ready to hold a clone, and return it. */
+export declare function ensureContentDir(dir: string): string;

package/dist/content/mount.js

@@ -0,0 +1,15 @@
+/**
+ * The agent's `content/`, where fastagent clones the repositories `context.json` declares. The directory carries its
+ * own `.gitignore` (`*`), as `.secrets/` does: each clone is its repository's, never the definition's, so it stays out
+ * of git even in an agent whose own `.gitignore` predates it.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Make `dir`, the agent's `content/`, ready to hold a clone, and return it. */
+export function ensureContentDir(dir) {
+    mkdirSync(dir, { recursive: true });
+    const ignore = join(dir, ".gitignore");
+    if (!existsSync(ignore))
+        writeFileSync(ignore, "*\n");
+    return dir;
+}