@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/harnesses/pi-durable/build.js

@@ -0,0 +1,270 @@
+/**
+ * `fastagent build` (agent-artifact.md §3.4): a source project compiled into `dist/`, a package that holds everything
+ * an open reads and nothing of the machine that built it. The project's own TypeScript compiles it, per file and
+ * unbundled, with the options FastAgent sets; the text and resources are copied; the entry is generated, the
+ * definition's modules as static imports.
+ */
+import { spawn } from "node:child_process";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { instanceConfigSchema } from "./config.js";
+import { BUILD_FILE, DIST_DIR, buildRecord, copyFiles, copyPlan } from "./built.js";
+import { declareMcp, literalCredentialAdvice, literalCredentials, relativeCommands } from "../../mcp/config.js";
+import { AGENT_CONFIG_FILE, exists, isUnderDir } from "../../paths.js";
+import { readPackageJson } from "../../runtime.js";
+import { HARNESS_PACKAGES } from "../../version.js";
+import { DEFINITION_FORMAT } from "./definition.js";
+import { loadSourceDefinition } from "./open.js";
+import { REGISTRY_KINDS } from "./registry.js";
+const STAGING_DIR = join(".fastagent", "build");
+/** The JSON Schema of an instance's `fastagent.json` for this program: an editor's `$schema`, and the package's own. */
+const SCHEMA_FILE = "fastagent.schema.json";
+const FASTAGENT_PACKAGE = "@fastagent-sh/fastagent";
+/** A declaration file: types only, so the compiler emits nothing for it, wherever it is (a workspace package's). */
+const DECLARATION = /\.d\.[cm]?ts$/;
+const MIN_TYPESCRIPT = 7;
+export async function buildProject(directory, options = {}) {
+    // The same refusals `dev` makes, before anything is written: a build of a definition that does not open is no build.
+    const definition = await loadSourceDefinition(directory);
+    const { dir } = definition;
+    await requireModulePackage(dir);
+    const dist = join(dir, DIST_DIR);
+    // Built apart and moved into place whole: a build that fails leaves the `dist/` before it as it was.
+    const staging = join(dir, STAGING_DIR);
+    await rm(staging, { recursive: true, force: true });
+    try {
+        await mkdir(staging, { recursive: true });
+        const code = await compile(dir, staging, definition, options.check !== false);
+        await copyFiles(dir, staging, await copyPlan(dir, code));
+        requireShippedCommands(dir, staging);
+        await writeEntry(staging, definition);
+        await writeFile(join(staging, "package.json"), await distPackageJson(dir, definition));
+        await writeFile(join(staging, SCHEMA_FILE), `${JSON.stringify(instanceConfigSchema(definition.config.settings), null, 2)}\n`);
+        await writeFile(join(staging, BUILD_FILE), await buildRecord(dir, code));
+        await rm(dist, { recursive: true, force: true });
+        await rename(staging, dist);
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+    return { dist, definition, warnings: literalMcpCredentials(dir) };
+}
+/** The compiler reads a `.ts` file as CommonJS without a package that says otherwise, and refuses its `import`s. */
+async function requireModulePackage(dir) {
+    if (!(await exists(join(dir, "package.json")))) {
+        throw new Error(`fastagent build needs ${join(dir, "package.json")}, with "type": "module"`);
+    }
+    if ((await readPackageJson(dir)).type !== "module") {
+        throw new Error(`fastagent build compiles ES modules: set "type": "module" in ${join(dir, "package.json")}`);
+    }
+}
+/** The project's `tsc`, by the package's own `bin`: FastAgent does not carry a compiler, as Next.js does not. */
+function projectTsc(dir) {
+    try {
+        const manifest = createRequire(join(dir, "package.json")).resolve("typescript/package.json");
+        const { bin, version } = JSON.parse(readFileSync(manifest, "utf8"));
+        if (bin?.tsc === undefined)
+            throw new Error(`${manifest} has no tsc`);
+        // The options the build sets (--ignoreConfig, --erasableSyntaxOnly, --rewriteRelativeImportExtensions) are 7's.
+        if (!(Number.parseInt(version ?? "", 10) >= MIN_TYPESCRIPT)) {
+            throw new Error(`fastagent build needs TypeScript ${MIN_TYPESCRIPT} or newer; ${dir} has ${version ?? "an unknown version"}`);
+        }
+        return join(dirname(manifest), bin.tsc);
+    }
+    catch (error) {
+        if (error.code !== "MODULE_NOT_FOUND")
+            throw error;
+        throw new Error(`fastagent build compiles with the project's TypeScript, and ${dir} has none: npm install --save-dev typescript`, { cause: error });
+    }
+}
+/** What the compiler is run with: FastAgent sets it, and the author's `tsconfig.json` is the editor's. */
+function tscArguments(dir, outDir, roots, more) {
+    return [
+        projectTsc(dir),
+        "--ignoreConfig",
+        "--pretty",
+        "false",
+        "--target",
+        "es2022",
+        "--module",
+        "nodenext",
+        "--moduleResolution",
+        "nodenext",
+        "--strict",
+        "--skipLibCheck",
+        "--verbatimModuleSyntax",
+        // What `dev` runs is Node's type stripping: the build compiles only what it would run.
+        "--erasableSyntaxOnly",
+        "--allowImportingTsExtensions",
+        "--rewriteRelativeImportExtensions",
+        "--resolveJsonModule",
+        "--allowJs",
+        "--rootDir",
+        dir,
+        "--outDir",
+        outDir,
+        ...more,
+        ...roots.map((file) => join(dir, file)),
+    ];
+}
+/**
+ * The source files the compiler reads, split into the project's (relative, what the build records) and those outside
+ * it, which `dist/` cannot hold: `tsc` reports one (TS6059) yet writes its output beside it, and with `--noCheck`
+ * reports nothing and succeeds, so the files are listed first and the build refuses before anything is emitted.
+ * Dependencies (`node_modules`, the compiler's own libraries) and declaration files, which emit nothing, are neither.
+ */
+async function programFiles(dir, roots) {
+    const { output } = await run(process.execPath, tscArguments(dir, dir, roots, ["--listFilesOnly"]), dir);
+    const inside = [];
+    const outside = [];
+    for (const file of output.split("\n").map((line) => line.trim())) {
+        if (!isAbsolute(file) || file.split(sep).includes("node_modules"))
+            continue;
+        const rel = relative(dir, file);
+        if (rel.startsWith("..")) {
+            if (!DECLARATION.test(file))
+                outside.push(file);
+        }
+        else {
+            inside.push(rel.split(sep).join("/"));
+        }
+    }
+    return { inside, outside };
+}
+/**
+ * The configuration and every registered module, compiled with what they import; a type error fails the build.
+ * Answers the project's source files the compiler read.
+ */
+async function compile(dir, outDir, definition, check) {
+    const roots = [
+        ...((await exists(join(dir, AGENT_CONFIG_FILE))) ? [AGENT_CONFIG_FILE] : []),
+        ...REGISTRY_KINDS.flatMap((kind) => definition.registry[kind].map(({ file }) => file)),
+    ];
+    if (roots.length === 0)
+        return [];
+    const { inside, outside } = await programFiles(dir, roots);
+    if (outside.length > 0) {
+        throw new Error(`the project imports source from outside ${dir}, which ${DIST_DIR}/ cannot hold: ${outside.join(", ")}`);
+    }
+    const { code, output } = await run(process.execPath, tscArguments(dir, outDir, roots, check ? [] : ["--noCheck"]), dir);
+    if (code !== 0)
+        throw new Error(`tsc refused the project (exit ${code}):\n${output.trim()}`);
+    // The configuration's declaration alone: it types the package's entry by the program's settings.
+    if (roots.includes(AGENT_CONFIG_FILE)) {
+        const declared = await run(process.execPath, tscArguments(dir, outDir, [AGENT_CONFIG_FILE], ["--declaration", "--emitDeclarationOnly", "--noCheck"]), dir);
+        if (declared.code !== 0) {
+            throw new Error(`tsc could not write the declaration of ${AGENT_CONFIG_FILE}:\n${declared.output.trim()}`);
+        }
+    }
+    return inside;
+}
+function run(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let output = "";
+        child.stdout.on("data", (chunk) => (output += chunk.toString()));
+        child.stderr.on("data", (chunk) => (output += chunk.toString()));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code, output }));
+    });
+}
+/** `index.js`, the package's default export: the definition, its modules imported statically. */
+async function writeEntry(dist, definition) {
+    const emitted = (file) => `./${file.replace(/\.(ts|mts)$/, (ext) => (ext === ".mts" ? ".mjs" : ".js"))}`;
+    const lines = [
+        "// Generated by fastagent build: do not edit.",
+        'import { dirname } from "node:path";',
+        'import { fileURLToPath } from "node:url";',
+        `import { defineDefinition } from ${JSON.stringify(FASTAGENT_PACKAGE)};`,
+    ];
+    const hasConfig = await exists(join(dist, "fastagent.config.js"));
+    if (hasConfig)
+        lines.push('import config from "./fastagent.config.js";');
+    let index = 0;
+    const kinds = REGISTRY_KINDS.map((kind) => {
+        const entries = definition.registry[kind].map(({ file, name }) => {
+            const local = `m${index++}`;
+            lines.push(`import ${local} from ${JSON.stringify(emitted(file))};`);
+            return `    { file: ${JSON.stringify(file)}, name: ${JSON.stringify(name)}, value: ${local} },`;
+        });
+        return `  ${kind}: [\n${entries.map((entry) => `  ${entry}`).join("\n")}${entries.length > 0 ? "\n" : ""}  ],`;
+    });
+    const source = `${lines.join("\n")}
+
+export default defineDefinition({
+  format: ${DEFINITION_FORMAT},
+  builtWith: ${JSON.stringify(definition.builtWith)},
+  name: ${JSON.stringify(definition.name)},
+  version: ${JSON.stringify(definition.version)},
+  dir: dirname(fileURLToPath(import.meta.url)),
+  config: ${hasConfig ? "config ?? {}" : "{}"},
+  registry: {
+${kinds.map((kind) => `  ${kind}`).join("\n")}
+  },
+});
+`;
+    await writeFile(join(dist, "index.js"), source);
+    const typed = await exists(join(dist, "fastagent.config.d.ts"));
+    const fastagent = JSON.stringify(FASTAGENT_PACKAGE);
+    await writeFile(join(dist, "index.d.ts"), typed
+        ? `import type { AgentDefinition, SettingsOf } from ${fastagent};\nimport type config from "./fastagent.config.js";\n` +
+            `declare const definition: AgentDefinition<SettingsOf<typeof config>>;\nexport default definition;\n`
+        : `import type { AgentDefinition } from ${fastagent};\ndeclare const definition: AgentDefinition;\nexport default definition;\n`);
+}
+/**
+ * The package `dist/` is: the project's name, version and own dependencies, with FastAgent and the pi packages its
+ * code imports as peers, so an app that installs several agents holds one copy of each (§3.5).
+ */
+async function distPackageJson(dir, definition) {
+    const pkg = (await readPackageJson(dir));
+    const peers = new Set([FASTAGENT_PACKAGE, ...HARNESS_PACKAGES]);
+    const dependencies = {};
+    const peerDependencies = {};
+    for (const [name, range] of Object.entries(pkg.dependencies ?? {})) {
+        (peers.has(name) ? peerDependencies : dependencies)[name] = range;
+    }
+    const out = {
+        name: pkg.name ?? basename(dir),
+        version: definition.version,
+        ...(pkg.description === undefined ? {} : { description: pkg.description }),
+        ...(pkg.license === undefined ? {} : { license: pkg.license }),
+        type: "module",
+        exports: {
+            ".": { types: "./index.d.ts", default: "./index.js" },
+            [`./${SCHEMA_FILE}`]: `./${SCHEMA_FILE}`,
+        },
+        ...(Object.keys(dependencies).length > 0 ? { dependencies } : {}),
+        ...(Object.keys(peerDependencies).length > 0 ? { peerDependencies } : {}),
+    };
+    return `${JSON.stringify(out, null, 2)}\n`;
+}
+/**
+ * A program's stdio command with a path is relative to its package, which in `dev` is the project and after a build is
+ * `dist/`, holding only what the build copied. One the build did not copy works in `dev` and is not there on a box, so
+ * it is refused here, against what was actually written to `staging`, rather than found when the box starts.
+ */
+function requireShippedCommands(dir, staging) {
+    for (const { name, file, command } of relativeCommands(declareMcp(dir))) {
+        const inProject = resolve(dir, command);
+        const shipped = join(staging, relative(dir, inProject));
+        if (isUnderDir(inProject, dir) && existsSync(shipped))
+            continue;
+        const dependency = isUnderDir(inProject, dir) && relative(dir, inProject).split(sep)[0] === "node_modules";
+        throw new Error(`${file} mcpServers.${name}: the command "${command}" ` +
+            (dependency
+                ? `is in node_modules, which the box installs for itself and ${DIST_DIR}/ does not hold: run the package by ` +
+                    `name (\`npx <package>\`) or give the absolute path it has there`
+                : existsSync(inProject)
+                    ? `is not in ${DIST_DIR}/, which holds only what the build copies (assets/, skills/, prompts/ and the ` +
+                        `resources beside code): move it under assets/`
+                    : `does not exist in the project`));
+    }
+}
+/** What a build says of a literal credential in the program's `mcpServers`, which the package publishes. */
+function literalMcpCredentials(dir) {
+    return literalCredentials(declareMcp(dir)).map((literal) => `${literal.file} mcpServers.${literal.server}.${literal.field}.${literal.key} is a literal value, and ` +
+        `${DIST_DIR}/ is published: ${literalCredentialAdvice(literal)} and give the value as a secret`);
+}

package/dist/harnesses/pi-durable/built.d.ts

@@ -0,0 +1,24 @@
+import { type AgentDefinition } from "./definition.ts";
+export declare const DIST_DIR = "dist";
+/** Beside the package's entry: the format and fingerprint of the build, and the code files it read. */
+export declare const BUILD_FILE = "build.json";
+/**
+ * The files the build copies into `dist/` beside what it compiled, as project-relative `[from, to]`: the text and data
+ * of the root, `skills/`, `prompts/` and `assets/` whole, and in each directory the code lives in, every file that is
+ * not code or a test (a module's resource is relative to the module, so it lands beside it). A link is followed to
+ * what it names, and one back into a directory being listed is refused.
+ */
+export declare function copyPlan(dir: string, code: readonly string[]): Promise<string[]>;
+/** Copy each of `files`, project-relative, from `dir` to `to`. */
+export declare function copyFiles(dir: string, to: string, files: readonly string[]): Promise<void>;
+export declare function buildRecord(dir: string, code: readonly string[]): Promise<string>;
+/**
+ * The definition of the project's `dist/`: refused, naming `fastagent build`, when there is none or, with
+ * `checkSources`, when the project has moved on from it. A deployed box's project is the release's copy, which the
+ * agent works in and edits, so only a local `start` asks whether the author forgot to build.
+ */
+export declare function loadProjectBuild(directory: string, { checkSources }: {
+    checkSources: boolean;
+}): Promise<AgentDefinition>;
+/** The definition a built package (`dist/`, or one installed under `node_modules`) exports. */
+export declare function loadBuiltDefinition(dist: string): Promise<AgentDefinition>;

package/dist/harnesses/pi-durable/built.js

@@ -0,0 +1,136 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * What `dist/` is, as a project and an opener both see it (agent-artifact.md §3.4): which of the project's files go
+ * into it, the fingerprint the build records of what it read, and the opener that refuses a `dist/` the project has
+ * moved on from.
+ */
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, readdir, realpath, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { CONTEXT_FILE, exists } from "../../paths.js";
+import { assertDefinition } from "./definition.js";
+import { registryFiles } from "./registry.js";
+export const DIST_DIR = "dist";
+/** Beside the package's entry: the format and fingerprint of the build, and the code files it read. */
+export const BUILD_FILE = "build.json";
+const CODE = /\.(ts|mts|cts|tsx|js|mjs|cjs|jsx)$/;
+const TEST = /\.(test|spec)\.[a-z]+$/;
+/** What never leaves the project, wherever it is: secrets, dependencies, history, the build's own output. */
+const NEVER_COPIED = /^(\.env(\..*)?|\.secrets|node_modules|\.git|\.DS_Store)$/;
+/** The program's text and data at the project root (§3.4). */
+const ROOT_FILES = ["SYSTEM.md", "AGENTS.md", CONTEXT_FILE, "README.md"];
+const ROOT_DIRS = ["skills", "prompts", "assets"];
+const LICENSE = /^LICEN[CS]E(\..*)?$/i;
+/**
+ * The files the build copies into `dist/` beside what it compiled, as project-relative `[from, to]`: the text and data
+ * of the root, `skills/`, `prompts/` and `assets/` whole, and in each directory the code lives in, every file that is
+ * not code or a test (a module's resource is relative to the module, so it lands beside it). A link is followed to
+ * what it names, and one back into a directory being listed is refused.
+ */
+export async function copyPlan(dir, code) {
+    const files = [];
+    for (const name of await readdir(dir)) {
+        if (ROOT_FILES.includes(name) || LICENSE.test(name))
+            files.push(name);
+    }
+    for (const name of ROOT_DIRS) {
+        if (await exists(join(dir, name)))
+            files.push(...(await filesIn(dir, name, () => true)));
+    }
+    const compiledIn = new Set(code.filter((file) => file.includes("/")).map((file) => file.split("/")[0]));
+    for (const name of [...compiledIn].filter((name) => !ROOT_DIRS.includes(name))) {
+        files.push(...(await filesIn(dir, name, (file) => !CODE.test(file) && !TEST.test(file))));
+    }
+    return [...new Set(files)].sort();
+}
+async function filesIn(dir, rel, include, within = []) {
+    const here = await realpath(join(dir, rel));
+    if (within.includes(here))
+        throw new Error(`${rel} links back to ${here}, a directory this build is copying`);
+    const files = [];
+    for (const entry of await readdir(join(dir, rel), { withFileTypes: true })) {
+        if (NEVER_COPIED.test(entry.name))
+            continue;
+        const path = `${rel}/${entry.name}`;
+        const target = await stat(join(dir, path));
+        if (target.isDirectory())
+            files.push(...(await filesIn(dir, path, include, [...within, here])));
+        else if (target.isFile() && include(entry.name))
+            files.push(path);
+    }
+    return files;
+}
+/** Copy each of `files`, project-relative, from `dir` to `to`. */
+export async function copyFiles(dir, to, files) {
+    for (const file of files) {
+        await mkdir(dirname(join(to, file)), { recursive: true });
+        await copyFile(join(dir, file), join(to, file));
+    }
+}
+async function digest(path) {
+    try {
+        return createHash("sha256")
+            .update(await readFile(path))
+            .digest("hex");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+/**
+ * Everything the build reads from the project, as one hash: the code the compiler read, the modules the registry lists
+ * now, the files it would copy, and `package.json`. Runtime writes (state, secrets, an agent's own output) are none of
+ * these, so running an agent never makes its build stale.
+ */
+async function fingerprintOf(dir, code) {
+    const files = new Set([...code, ...(await registryFiles(dir)), ...(await copyPlan(dir, code)), "package.json"]);
+    const hash = createHash("sha256");
+    for (const file of [...files].sort())
+        hash.update(`${file}\0${await digest(join(dir, file))}\n`);
+    return hash.digest("hex");
+}
+export async function buildRecord(dir, code) {
+    const record = { code: [...code].sort(), fingerprint: await fingerprintOf(dir, code) };
+    return `${JSON.stringify(record, null, 2)}\n`;
+}
+/** Why `dist/` of the project in `dir` cannot be opened, or nothing when it is the build of the project as it is. */
+async function builtProblem(dir, checkSources) {
+    const rebuild = "run `fastagent build`";
+    const dist = join(dir, DIST_DIR);
+    if (!(await exists(join(dist, BUILD_FILE))))
+        return `${dist} holds no build: ${rebuild}`;
+    if (!checkSources)
+        return undefined;
+    const record = JSON.parse(await readFile(join(dist, BUILD_FILE), "utf8"));
+    return (await fingerprintOf(dir, record.code)) === record.fingerprint
+        ? undefined
+        : `${dist} was built from other sources than ${dir} holds now: ${rebuild}`;
+}
+/**
+ * The definition of the project's `dist/`: refused, naming `fastagent build`, when there is none or, with
+ * `checkSources`, when the project has moved on from it. A deployed box's project is the release's copy, which the
+ * agent works in and edits, so only a local `start` asks whether the author forgot to build.
+ */
+export async function loadProjectBuild(directory, { checkSources }) {
+    const problem = await builtProblem(directory, checkSources);
+    if (problem !== undefined)
+        throw new Error(problem);
+    return loadBuiltDefinition(join(directory, DIST_DIR));
+}
+/** The definition a built package (`dist/`, or one installed under `node_modules`) exports. */
+export async function loadBuiltDefinition(dist) {
+    const entry = join(dist, "index.js");
+    if (!(await exists(entry)))
+        throw new Error(`${dist} has no index.js: it is not a built agent package`);
+    return assertDefinition((await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href))).default);
+}

package/dist/harnesses/pi-durable/config.d.ts

@@ -0,0 +1,81 @@
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { type Schema } from "@earendil-works/pi-schema";
+import type { ContentEntry } from "../../content/declare.ts";
+import { type McpServerDeclaration } from "../../mcp/config.ts";
+import type { AgentConfig, AgentDefaults, Ingress } from "./define.ts";
+import type { AgentDefinition } from "./definition.ts";
+/**
+ * What an instance may set over the program's defaults: `fastagent.json`, or the same shape as an object. Beside the
+ * defaults, what only an instance adds: content, and instructions, skills and prompt templates (relative paths are the
+ * file's directory's).
+ */
+export type InstanceConfig<Settings = unknown> = AgentDefaults<Settings> & {
+    /** The instance's name, one path segment. Default: the program's name made one. */
+    name?: string;
+    content?: Record<string, ContentEntry>;
+    /** MCP servers the instance adds to the program's: a name both declare refuses the open. */
+    mcpServers?: Record<string, McpServerDeclaration>;
+    instructions?: string[];
+    skills?: string[];
+    prompts?: string[];
+};
+/** An instance configuration and where it is from, said in a refusal and as a value's source. */
+export interface InstanceConfigSource {
+    values: unknown;
+    label: string;
+    /** The configuration file's directory, which its relative paths are relative to. None for an object. */
+    directory?: string;
+}
+/** The JSON Schema of an instance's `fastagent.json` for a program with `settings`: what `fastagent build` publishes. */
+export declare function instanceConfigSchema(settings: Schema | undefined): Schema;
+/**
+ * The program's `fastagent.config.ts` default export, checked: the constants it may hold, its `settings` schema, and
+ * its defaults in the shape an instance's configuration has. Without one, no constants and no defaults.
+ */
+export declare function checkProgramConfig(config: unknown, file: string): AgentConfig;
+/** A `fastagent.json` read: refused when it cannot be read or is not JSON, naming the file. */
+export declare function readInstanceConfigFile(path: string): Promise<InstanceConfigSource>;
+/** The configuration `FASTAGENT_CONFIG` names, when it names one. */
+export declare function namedInstanceConfig(env?: NodeJS.ProcessEnv): Promise<InstanceConfigSource | undefined>;
+/** The instance configuration `dev` runs a project with: the one named by `--config` or `FASTAGENT_CONFIG`, else the project's own. */
+export declare function devInstanceConfig(dir: string): Promise<InstanceConfigSource | undefined>;
+/** The `fastagent.json` a development project holds at its root, when it holds one. */
+export declare function projectInstanceConfig(dir: string): Promise<InstanceConfigSource | undefined>;
+/** A channel's platform app, for one whose URL only a person sets (SPEC.md §8, `channels.<name>.app`). */
+interface ChannelApp {
+    id: string;
+    team?: string;
+    url?: string;
+}
+/** What an open reads of the configuration: the program's defaults with an instance's over them. */
+export interface EffectiveConfig {
+    /** The instance's name as its configuration gives it; none when it gives none (`instanceName` defaults it). */
+    name?: string;
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    http?: {
+        port?: number;
+        api?: boolean;
+        publicUrl?: string;
+    };
+    deploy?: {
+        agentcore?: {
+            idleTimeoutSeconds?: number;
+        };
+    };
+    channels?: Readonly<Record<string, {
+        ingress?: Ingress;
+        app?: ChannelApp;
+    }>>;
+    settings: Readonly<Record<string, unknown>>;
+    /** Where each value is from, by its path (`http.port`, `settings.repo`): "program default", or the instance's label. */
+    sources: Readonly<Record<string, string>>;
+}
+/**
+ * The configuration an instance of `definition` opens with: the program's defaults, the instance's over them, the
+ * merged settings checked against the program's `settings` schema (a required one no one gave refuses, naming it).
+ */
+export declare function resolveConfig(definition: AgentDefinition, instance?: InstanceConfigSource): EffectiveConfig;
+/** The value at a dotted `path` of `config`. */
+export declare function configValue(config: EffectiveConfig, path: string): unknown;
+export {};