@fastagent-sh/fastagent 0.28.0 → 0.30.0

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

@@ -0,0 +1,266 @@
+/**
+ * The configuration of an instance (agent-artifact.md §3.2, §4.2): what the program declares as its `defaults` and
+ * its `settings` schema, what an instance sets over them, and the one value they resolve to, each leaf with the place
+ * it came from. One JSON Schema describes the shape: it checks the program's defaults and an instance's file alike,
+ * and `fastagent build` publishes it as `fastagent.schema.json`.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { arr, bool, compile, int, map, obj, oneOf, opt, str, union, unknown, } from "@earendil-works/pi-schema";
+import { instanceContent } from "../../content/file.js";
+import { checkInstanceServers } from "../../mcp/config.js";
+import { checkInstanceName } from "../../instance-name.js";
+import { modelRefOf } from "../../model-ref.js";
+import { INSTANCE_CONFIG_ENV, INSTANCE_CONFIG_FILE, resolveOverridePath } from "../../paths.js";
+const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+const PROGRAM_DEFAULT = "program default";
+const CONSTANTS = ["name", "description", "extensions", "providers"];
+/** Keys that were the program's own before they became defaults. */
+const FORMER_CONSTANTS = ["model", "thinkingLevel", "http", "deploy"];
+/** An instance's content entry: a repository, or a directory (its detailed refusals are content/declare.ts's). */
+const CONTENT_ENTRY = union([
+    obj({
+        github: str({ description: "The repository, owner/repo" }),
+        ref: opt(str({ description: "The branch, tag or commit to clone" })),
+        description: opt(str({ description: "One sentence for the agent: what this is, and how to treat it" })),
+    }),
+    obj({
+        path: str({ description: "A directory of this machine: absolute, ~/, or relative to this file" }),
+        description: opt(str({ description: "One sentence for the agent: what this is, and how to treat it" })),
+    }),
+]);
+/** An absolute `https://` URL without a trailing slash, query or fragment: what `<publicUrl>/<path>` is built from. */
+const PUBLIC_URL_PATTERN = "^https://[^/?#\\s]+(/[^?#\\s]*[^/?#\\s])?$";
+/** The program's `settings` with no property required: an instance gives some of them, the program's defaults the rest. */
+function partial(settings) {
+    const { required: _required, ...rest } = settings;
+    return rest;
+}
+/** What the program's defaults and an instance's configuration may hold. `settings` is the program's, or none. */
+function shape(settings) {
+    return {
+        model: opt(str({ description: 'The default model, "provider/modelId"', minLength: 3 })),
+        thinkingLevel: opt(oneOf(THINKING_LEVELS)),
+        http: opt(obj({
+            port: opt(int({ minimum: 0, maximum: 65535, description: "The port a serve listens on" })),
+            api: opt(bool({ description: "Whether a serve answers the Agent API under /v1" })),
+            publicUrl: opt(str({
+                description: "The public base URL the platforms reach this instance at, any mount prefix included: the serve " +
+                    "points each webhook channel there",
+                pattern: PUBLIC_URL_PATTERN,
+            })),
+        })),
+        deploy: opt(obj({
+            // AWS's own bounds for idleRuntimeSessionTimeout: a value outside them is refused by CloudFormation minutes
+            // into `deploy agentcore --run`, after the image build.
+            agentcore: opt(obj({ idleTimeoutSeconds: opt(int({ minimum: 60, maximum: 1209600 })) })),
+        })),
+        channels: opt(map(obj({
+            app: opt(obj({
+                id: str({ description: "The platform's app ID" }),
+                team: opt(str({ description: "Slack's workspace (team) ID" })),
+                url: opt(str({
+                    description: "The channel's URL a person set on the platform's app page and the platform verified",
+                    pattern: "^https://[^?#\\s]+$",
+                })),
+            })),
+            ingress: opt(oneOf(["webhook", "connection"], {
+                description: "How the channel receives: webhook (inbound HTTP) or connection (one it opens and keeps)",
+            })),
+        }))),
+        settings: opt(settings === undefined ? obj({}) : partial(settings)),
+    };
+}
+/** The JSON Schema of an instance's `fastagent.json` for a program with `settings`: what `fastagent build` publishes. */
+export function instanceConfigSchema(settings) {
+    const paths = (description) => opt(arr(str({ minLength: 1 }), { description, uniqueItems: true }));
+    return obj({
+        $schema: opt(str()),
+        ...shape(settings),
+        name: opt(str({ description: "The instance's name: one path segment of letters, digits, - and _" })),
+        content: opt(map(CONTENT_ENTRY)),
+        mcpServers: opt(map(unknown(), {
+            description: "MCP servers this instance adds to the program's, by name, in the MCP ecosystem's entry shape (checked when the instance opens)",
+        })),
+        instructions: paths("Files of instructions added after the program's AGENTS.md, relative to this file"),
+        skills: paths("Directories of skills (one SKILL.md per subdirectory) added to the program's, relative to this file"),
+        prompts: paths("Directories of prompt templates (one .md file each) added to the program's, relative to this file"),
+    });
+}
+/** Refuse `value`, naming `where`, when `schema` does not accept it: each failing path, and why. */
+function check(schema, value, where) {
+    const validator = compile(schema);
+    if (validator.check(value))
+        return;
+    const problems = validator
+        .errors(value)
+        .map(({ path, message }) => `${path === "" ? "(the value)" : path} ${message}`);
+    throw new Error(`${where}: ${problems.join("; ")}`);
+}
+/** Defaults, or an instance's values, in the shape both have; `schemaWhere` names the model's place in a refusal. */
+function checkValues(values, settings, where, shapeOf) {
+    check(shapeOf(settings), values, where);
+    const { model } = values;
+    if (model !== undefined)
+        modelRefOf(model, `${where}: /model`);
+}
+/**
+ * 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 function checkProgramConfig(config, file) {
+    if (config === undefined)
+        return {};
+    if (typeof config !== "object" || config === null || Array.isArray(config)) {
+        throw new Error(`${file} must default-export defineAgent({ ... })`);
+    }
+    const { settings, defaults, extensions, providers } = config;
+    const keys = [...CONSTANTS, "settings", "defaults"];
+    for (const key of Object.keys(config)) {
+        if (keys.includes(key))
+            continue;
+        const moved = FORMER_CONSTANTS.includes(key) ? ': it is a default now, under "defaults"' : "";
+        throw new Error(`${file}: unknown key "${key}"${moved} (keys: ${keys.join(", ")})`);
+    }
+    for (const [key, list] of [
+        ["extensions", extensions],
+        ["providers", providers],
+    ]) {
+        if (list !== undefined && !Array.isArray(list))
+            throw new Error(`${file}: "${key}" must be an array`);
+    }
+    if (settings !== undefined) {
+        if (settings?.type !== "object") {
+            throw new Error(`${file}: "settings" must be an object schema (obj({ ... }) from @earendil-works/pi-schema)`);
+        }
+        try {
+            compile(settings);
+        }
+        catch (error) {
+            throw new Error(`${file}: "settings" is not a JSON Schema: ${error.message}`, { cause: error });
+        }
+    }
+    if (defaults !== undefined)
+        checkValues(defaults, settings, `${file} defaults`, (s) => obj(shape(s)));
+    return config;
+}
+/** An instance configuration, checked against the shape of a program with `settings`. */
+function checkInstanceConfig(source, settings) {
+    const { values, label } = source;
+    if (typeof values === "object" && values !== null) {
+        // Its own refusals name the entry and say what is wrong with it, which a schema's cannot.
+        instanceContent(source);
+        checkInstanceServers(source);
+        const { name } = values;
+        if (typeof name === "string") {
+            try {
+                checkInstanceName(name);
+            }
+            catch (error) {
+                throw new Error(`${label}: ${error.message}`);
+            }
+        }
+    }
+    checkValues(values, settings, label, instanceConfigSchema);
+    const { $schema: _schema, ...config } = values;
+    return config;
+}
+/** A `fastagent.json` read: refused when it cannot be read or is not JSON, naming the file. */
+export async function readInstanceConfigFile(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`cannot read the instance configuration ${path}: ${error.message}`, { cause: error });
+    }
+    try {
+        return { values: JSON.parse(text), label: path, directory: dirname(path) };
+    }
+    catch (error) {
+        throw new Error(`${path} is not JSON: ${error.message}`, { cause: error });
+    }
+}
+/** The configuration `FASTAGENT_CONFIG` names, when it names one. */
+export async function namedInstanceConfig(env = process.env) {
+    const path = resolveOverridePath(env[INSTANCE_CONFIG_ENV]);
+    return path === undefined ? undefined : readInstanceConfigFile(path);
+}
+/** The instance configuration `dev` runs a project with: the one named by `--config` or `FASTAGENT_CONFIG`, else the project's own. */
+export async function devInstanceConfig(dir) {
+    return (await namedInstanceConfig()) ?? (await projectInstanceConfig(dir));
+}
+/** The `fastagent.json` a development project holds at its root, when it holds one. */
+export async function projectInstanceConfig(dir) {
+    const path = join(dir, INSTANCE_CONFIG_FILE);
+    return existsSync(path) ? readInstanceConfigFile(path) : undefined;
+}
+/** The channels whose platform lets only a person set the URL: Slack's always, Lark's where its config API is missing. */
+const PERSON_SET_URL = ["slack", "lark"];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Put `layer` over `into`: objects merge, anything else replaces; each leaf written is recorded as from `label`. */
+function overlay(into, layer, label, sources, at = "") {
+    for (const [key, value] of Object.entries(layer)) {
+        const path = at === "" ? key : `${at}.${key}`;
+        if (key === "__proto__")
+            throw new Error(`${label}: ${path} is not a setting: "__proto__" cannot be a key`);
+        if (!isRecord(value)) {
+            into[key] = value;
+            sources[path] = label;
+            continue;
+        }
+        if (!isRecord(into[key])) {
+            into[key] = {};
+            delete sources[path];
+        }
+        overlay(into[key], value, label, sources, path);
+    }
+}
+/**
+ * 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 function resolveConfig(definition, instance) {
+    const { defaults, settings } = definition.config;
+    const merged = {};
+    const sources = {};
+    if (defaults !== undefined) {
+        checkValues(defaults, settings, `${definition.name} defaults`, (s) => obj(shape(s)));
+        overlay(merged, defaults, PROGRAM_DEFAULT, sources);
+    }
+    if (instance !== undefined) {
+        overlay(merged, checkInstanceConfig(instance, settings), instance.label, sources);
+    }
+    const values = (merged.settings ?? {});
+    check(settings ?? obj({}), values, `the settings of ${definition.name}`);
+    const channels = new Set(definition.registry.channels.map(({ name }) => name));
+    // The file that named a channel: whichever of its leaves one set.
+    const namedIn = (name) => Object.entries(sources).find(([path]) => path.startsWith(`channels.${name}.`))?.[1] ?? "the configuration";
+    for (const [name, entry] of Object.entries((merged.channels ?? {}))) {
+        if (entry.app !== undefined && !PERSON_SET_URL.includes(name)) {
+            throw new Error(`${namedIn(name)}: channels.${name}.app is for a channel whose ` +
+                `platform lets only a person set its URL (${PERSON_SET_URL.join(", ")})`);
+        }
+        if (!channels.has(name)) {
+            throw new Error(`${namedIn(name)}: channels.${name} names no channel of ` +
+                `${definition.name} (${channels.size === 0 ? "it has none" : `its channels: ${[...channels].join(", ")}`})`);
+        }
+    }
+    return { ...merged, settings: values, sources };
+}
+/** The value at a dotted `path` of `config`. */
+export function configValue(config, path) {
+    let value = config;
+    for (const key of path.split("."))
+        value = isRecord(value) ? value[key] : undefined;
+    return value;
+}

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

@@ -5,18 +5,13 @@
  */
 import type { ModelThinkingLevel, Provider } from "@earendil-works/pi-ai";
 import type { Extension } from "@earendil-works/pi-durable";
+import type { Schema } from "@earendil-works/pi-schema";
 import type { ScheduleConfig } from "../../schedule/schedule.ts";
-export interface AgentConfig {
-    /** Default: `package.json`'s name. */
-    name?: string;
-    description?: string;
-    /** `"provider/modelId"`: what a session that names none answers with; a deployment may override it. */
+/** What an instance may set over the program's `defaults`, and what a program's `defaults` are (agent-artifact.md §3.2). */
+export interface AgentDefaults<Settings = unknown> {
+    /** `"provider/modelId"`: what a session that names none answers with; a flag or `FASTAGENT_MODEL` may override it. */
     model?: string;
     thinkingLevel?: ModelThinkingLevel;
-    /** Third-party capabilities, installed after `src/extensions/`. */
-    extensions?: readonly (Extension | Needs<Extension>)[];
-    /** Model providers beyond pi-ai's built-ins (a self-hosted endpoint, a gateway); a built-in's id replaces it. */
-    providers?: readonly (Provider | Needs<Provider>)[];
     http?: {
         /** The port a serve listens on, for its channels' webhooks and its health check. */
         port?: number;
@@ -25,6 +20,11 @@ export interface AgentConfig {
          * which `deploy` gives a key. `false` keeps it to its channels and schedules, whatever key its environment holds.
          */
         api?: boolean;
+        /**
+         * The public base URL the platforms reach this instance at, any mount prefix included (`https://x.fly.dev/agent`):
+         * a serve points each webhook channel there. Unset, none is pointed. Never inferred from the environment.
+         */
+        publicUrl?: string;
     };
     /** How the agent is deployed, where a host needs to be told. */
     deploy?: {
@@ -32,9 +32,35 @@ export interface AgentConfig {
             idleTimeoutSeconds?: number;
         };
     };
+    /**
+     * Each channel by its file's name: how it receives, for a channel that can do either (`byIngress`). Unset, `dev`
+     * receives by WebSocket (no public URL there) and everything else by webhook, which a host that wakes on a request
+     * needs.
+     */
+    channels?: Record<string, {
+        ingress?: Ingress;
+    }>;
+    /** Values of the program's `settings`; an instance gives the rest. */
+    settings?: Partial<Settings>;
 }
+export interface AgentConfig<Settings = unknown> {
+    /** Constant: default `package.json`'s name. */
+    name?: string;
+    /** Constant. */
+    description?: string;
+    /** Constant: third-party capabilities, installed after `src/extensions/`. */
+    extensions?: readonly (Extension | Needs<Extension>)[];
+    /** Constant: model providers beyond pi-ai's built-ins (a self-hosted endpoint, a gateway); a built-in's id replaces it. */
+    providers?: readonly (Provider | Needs<Provider>)[];
+    /** What each instance may choose, as an object schema (`obj({ ... })` from `@earendil-works/pi-schema`); no secrets. */
+    settings?: Schema<Settings>;
+    /** What an instance gets unless its configuration says otherwise. */
+    defaults?: AgentDefaults<Settings>;
+}
+/** The settings an `AgentConfig` declares: what `fastagent build` types a package's definition by. */
+export type SettingsOf<Config> = Config extends AgentConfig<infer Settings> ? Settings : unknown;
 /** @public */
-export declare function defineAgent(config: AgentConfig): AgentConfig;
+export declare function defineAgent<Settings = unknown>(config: AgentConfig<Settings>): AgentConfig<Settings>;
 /** One secret a piece of code reads: by name, or with what it is for and whether the code runs without it. */
 /** @public */
 export type SecretSpec = string | {
@@ -63,11 +89,35 @@ export interface Needs<T> {
         description?: string;
         optional: boolean;
     }[];
-    build(values: Record<string, string | undefined>): T;
+    build(values: Record<string, string | undefined>, settings: Readonly<Record<string, unknown>>): T;
 }
-/** @public */
-export declare function needs<const S extends readonly SecretSpec[], T>(secrets: S, build: (values: SecretValues<S>) => T): Needs<T>;
+/**
+ * Wrap a module so it is built when an instance opens, with the values of the secrets it declares and the instance's
+ * resolved `settings` (the program's `settings` schema, defaults and the instance's values, checked). Annotate the
+ * second parameter with `SettingsOf<typeof config>` to type it. With no secrets, `needs([], (_, settings) => ...)`.
+ * @public
+ */
+export declare function needs<const S extends readonly SecretSpec[], T, Settings = Readonly<Record<string, unknown>>>(secrets: S, build: (values: SecretValues<S>, settings: Settings) => T): Needs<T>;
 export declare function isNeeds(value: unknown): value is Needs<unknown>;
+/** How a channel receives: inbound HTTP requests, or a connection it opens itself and keeps. */
+export type Ingress = "webhook" | "connection";
+/** A channel that can receive either way, each way's module (or `needs` around it) under its name. */
+export interface ByIngress<T = unknown> {
+    readonly kind: "fastagent.by-ingress";
+    readonly webhook: T | Needs<T>;
+    readonly connection: T | Needs<T>;
+}
+/**
+ * Default-export from `src/channels/<name>.ts` a channel that receives either way: each instance takes the one its
+ * configuration names (`channels.<name>.ingress`), and without one `dev` takes `connection` and everything else
+ * `webhook`. Each way declares its own secrets, so an instance is asked only for its way's.
+ * @public
+ */
+export declare function byIngress<T>(ways: {
+    webhook: T | Needs<T>;
+    connection: T | Needs<T>;
+}): ByIngress<T>;
+export declare function isByIngress(value: unknown): value is ByIngress;
 /** What `src/schedules/<name>.ts` default-exports. */
 export interface DefinedSchedule extends ScheduleConfig {
     readonly kind: "fastagent.schedule";

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

@@ -3,7 +3,12 @@ import { isEnvName } from "../../declared-secrets.js";
 export function defineAgent(config) {
     return config;
 }
-/** @public */
+/**
+ * Wrap a module so it is built when an instance opens, with the values of the secrets it declares and the instance's
+ * resolved `settings` (the program's `settings` schema, defaults and the instance's values, checked). Annotate the
+ * second parameter with `SettingsOf<typeof config>` to type it. With no secrets, `needs([], (_, settings) => ...)`.
+ * @public
+ */
 export function needs(secrets, build) {
     const declared = secrets.map((spec) => typeof spec === "string"
         ? { name: spec, optional: false }
@@ -17,11 +22,27 @@ export function needs(secrets, build) {
         if (!isEnvName(name))
             throw new Error(`needs: ${JSON.stringify(name)} is not an environment variable name`);
     }
-    return { kind: "fastagent.needs", secrets: declared, build: (values) => build(values) };
+    return {
+        kind: "fastagent.needs",
+        secrets: declared,
+        build: (values, settings) => build(values, settings),
+    };
 }
 export function isNeeds(value) {
     return value?.kind === "fastagent.needs";
 }
+/**
+ * Default-export from `src/channels/<name>.ts` a channel that receives either way: each instance takes the one its
+ * configuration names (`channels.<name>.ingress`), and without one `dev` takes `connection` and everything else
+ * `webhook`. Each way declares its own secrets, so an instance is asked only for its way's.
+ * @public
+ */
+export function byIngress(ways) {
+    return { kind: "fastagent.by-ingress", webhook: ways.webhook, connection: ways.connection };
+}
+export function isByIngress(value) {
+    return value?.kind === "fastagent.by-ingress";
+}
 /** @public */
 export function defineSchedule(config) {
     return { kind: "fastagent.schedule", ...config };

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

@@ -0,0 +1,72 @@
+import type { DeclaredSecret } from "../../declared-secrets.ts";
+import { type McpInstance } from "../../mcp/config.ts";
+import { type AgentConfig, type Ingress } from "./define.ts";
+import { type Registry } from "./registry.ts";
+/** What an opener of this FastAgent reads; a definition made for another refuses. */
+export declare const DEFINITION_FORMAT = 1;
+declare const DEFINITION: unique symbol;
+declare const SETTINGS: unique symbol;
+/** A way of receiving that reads a secret: one channel's, by its name. */
+interface IngressCondition {
+    channel: string;
+    ingress: Ingress;
+}
+/** A secret an instance must or may be given (SPEC.md §8): each name once, required when any declaration requires it. */
+interface DeclaredInput {
+    name: string;
+    description?: string;
+    optional: boolean;
+    declaredIn: readonly string[];
+    /** Only these channels' ways read it; absent, every instance does. */
+    whenIngress?: readonly IngressCondition[];
+}
+/** `AgentDefinition<Settings>`: typed by the program's settings, so an embedder's `settings` input is checked. */
+export interface AgentDefinition<Settings = unknown> {
+    /** Phantom: carries `Settings` to the open's input types; nothing exists at run time. */
+    readonly [SETTINGS]?: Settings;
+    readonly [DEFINITION]: true;
+    readonly format: number;
+    /** The FastAgent version that made it: what a refusal of its format asks the opener to install. */
+    readonly builtWith: string;
+    readonly name: string;
+    readonly version: string;
+    /** Absolute: the program's files, its text, `context.json` and `mcp.json`. */
+    readonly dir: string;
+    readonly config: AgentConfig;
+    readonly registry: Registry;
+    readonly inputs: {
+        readonly secrets: readonly DeclaredInput[];
+    };
+}
+/** The value an opener was given, checked to be a definition this FastAgent assembles; a refusal says why. */
+export declare function assertDefinition(value: unknown): AgentDefinition;
+type DefinitionSpec = Omit<AgentDefinition, typeof DEFINITION | "inputs">;
+/** The value, frozen down to its lists and entries; the modules' own exports stay as their authors made them. */
+export declare function defineDefinition(spec: DefinitionSpec): AgentDefinition;
+/** The channels part of a configuration: how each channel that receives either way receives. */
+interface ChannelsConfig {
+    channels?: Readonly<Record<string, {
+        ingress?: Ingress;
+    }>>;
+}
+/** A channels configuration and whether `fastagent dev` serves the instance (else the process's own say, `servedByDev`). */
+export interface IngressConfig extends ChannelsConfig {
+    dev?: boolean;
+}
+/**
+ * How the channel `name` receives under `config`: what it names, else WebSocket under `dev` (no public URL there) and
+ * webhook everywhere else (a host that wakes on a request reaches it only that way).
+ */
+export declare function chosenIngress(config: IngressConfig, name: string, dev?: boolean): Ingress;
+type Declaring = Pick<DefinitionSpec, "registry" | "config" | "dir">;
+/**
+ * The secrets the definition's code reads (`needs()`) and its commands do (`context.json`'s variables): an instance's,
+ * under its `config`, or every way's with none.
+ */
+export declare function codeSecrets(definition: Declaring, config?: IngressConfig): DeclaredSecret[];
+/**
+ * Every declaration of a secret, each where it is: the code's, then the references of the MCP servers, the program's
+ * and, given `instance`, the ones it adds.
+ */
+export declare function definitionSecrets(definition: Declaring, config?: IngressConfig, instance?: McpInstance): DeclaredSecret[];
+export {};

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

@@ -0,0 +1,143 @@
+/**
+ * A definition as a value (agent-artifact.md §3.5): what `dev` loads from a source project and what a built package
+ * will export, one frozen shape every opener assembles from. Its declared inputs are read once, when it is made.
+ */
+import { loadEnvironment } from "../../content/file.js";
+import { declaredVariables } from "../../environment/declare.js";
+import { declareMcp, mcpSecrets } from "../../mcp/config.js";
+import { AGENT_CONFIG_FILE as CONFIG_FILE } from "../../paths.js";
+import { servedByDev } from "../../serving-command.js";
+import { isByIngress, isNeeds } from "./define.js";
+import { REGISTRY_KINDS } from "./registry.js";
+/** What an opener of this FastAgent reads; a definition made for another refuses. */
+export const DEFINITION_FORMAT = 1;
+const DEFINITION = Symbol.for("fastagent.definition");
+/** The value an opener was given, checked to be a definition this FastAgent assembles; a refusal says why. */
+export function assertDefinition(value) {
+    if (typeof value !== "object" || value === null || !(DEFINITION in value)) {
+        throw new Error("openAgent needs an agent package's default export (a definition `fastagent build` made)");
+    }
+    const definition = value;
+    if (definition.format !== DEFINITION_FORMAT) {
+        throw new Error(`${definition.name} was built as definition format ${definition.format}, and this FastAgent opens format ` +
+            `${DEFINITION_FORMAT}: install @fastagent-sh/fastagent ${definition.builtWith}`);
+    }
+    return definition;
+}
+/** The value, frozen down to its lists and entries; the modules' own exports stay as their authors made them. */
+export function defineDefinition(spec) {
+    const registry = Object.freeze(Object.fromEntries(REGISTRY_KINDS.map((kind) => [
+        kind,
+        Object.freeze(spec.registry[kind].map((entry) => Object.freeze({ ...entry }))),
+    ])));
+    const config = Object.freeze({
+        ...spec.config,
+        ...(spec.config.extensions === undefined ? {} : { extensions: Object.freeze([...spec.config.extensions]) }),
+        ...(spec.config.providers === undefined ? {} : { providers: Object.freeze([...spec.config.providers]) }),
+        ...(spec.config.settings === undefined ? {} : { settings: deepFreeze(structuredClone(spec.config.settings)) }),
+        ...(spec.config.defaults === undefined ? {} : { defaults: deepFreeze(structuredClone(spec.config.defaults)) }),
+    });
+    return Object.freeze({
+        [DEFINITION]: true,
+        ...spec,
+        config,
+        registry,
+        inputs: Object.freeze({ secrets: Object.freeze(byName(definitionSecrets(spec))) }),
+    });
+}
+/** Plain data, frozen all the way down: a schema and defaults are JSON, which no instance may change. */
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        for (const inner of Object.values(value))
+            deepFreeze(inner);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * One input per name, in name order: required when any declaration requires it, every place it is declared, and the
+ * ways of receiving that read it when only some do.
+ */
+function byName(declared) {
+    const groups = new Map();
+    for (const secret of declared)
+        groups.set(secret.name, [...(groups.get(secret.name) ?? []), secret]);
+    return [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, all]) => {
+        const optional = all.every((secret) => secret.optional);
+        const description = all.find((secret) => secret.description !== undefined)?.description;
+        const whenIngress = conditionsOf(optional ? all : all.filter((secret) => !secret.optional));
+        return Object.freeze({
+            name,
+            ...(description === undefined ? {} : { description }),
+            optional,
+            declaredIn: Object.freeze([...new Set(all.map((secret) => secret.declaredIn))]),
+            ...(whenIngress === undefined ? {} : { whenIngress: Object.freeze(whenIngress) }),
+        });
+    });
+}
+/**
+ * The ways of receiving under which `deciding` reads a name: none when one of them always does, or when a channel's
+ * both ways do, since every instance then receives one of them.
+ */
+function conditionsOf(deciding) {
+    if (deciding.some((secret) => secret.when === undefined))
+        return undefined;
+    const conditions = [];
+    for (const { when } of deciding) {
+        const { channel, ingress } = when;
+        if (!conditions.some((c) => c.channel === channel && c.ingress === ingress))
+            conditions.push({ channel, ingress });
+    }
+    const bothWays = conditions.some(({ channel }) => conditions.filter((c) => c.channel === channel).length === 2);
+    return bothWays ? undefined : conditions;
+}
+/**
+ * How the channel `name` receives under `config`: what it names, else WebSocket under `dev` (no public URL there) and
+ * webhook everywhere else (a host that wakes on a request reaches it only that way).
+ */
+export function chosenIngress(config, name, dev = config.dev ?? servedByDev()) {
+    return config.channels?.[name]?.ingress ?? (dev ? "connection" : "webhook");
+}
+/**
+ * Every value the definition can hold `Needs` in, with where it is: modules by file, configuration by key. A channel
+ * that receives either way is the way `config` chooses; with no configuration, both ways, each with its condition.
+ */
+function declarers({ registry, config }, instance) {
+    const ways = ({ file, name, value }) => {
+        if (!isByIngress(value))
+            return [{ declaredIn: file, value }];
+        if (instance !== undefined)
+            return [{ declaredIn: file, value: value[chosenIngress(instance, name)] }];
+        return ["webhook", "connection"].map((ingress) => ({
+            declaredIn: file,
+            value: value[ingress],
+            when: { channel: name, ingress },
+        }));
+    };
+    return [
+        ...REGISTRY_KINDS.flatMap((kind) => registry[kind].flatMap(ways)),
+        ...(config.extensions ?? []).map((value, i) => ({ declaredIn: `${CONFIG_FILE} extensions[${i}]`, value })),
+        ...(config.providers ?? []).map((value, i) => ({ declaredIn: `${CONFIG_FILE} providers[${i}]`, value })),
+    ];
+}
+/**
+ * The secrets the definition's code reads (`needs()`) and its commands do (`context.json`'s variables): an instance's,
+ * under its `config`, or every way's with none.
+ */
+export function codeSecrets(definition, config) {
+    return [
+        ...declarers(definition, config).flatMap(({ declaredIn, value, when }) => isNeeds(value)
+            ? value.secrets.map((secret) => ({ ...secret, declaredIn, ...(when === undefined ? {} : { when }) }))
+            : []),
+        ...declaredVariables(loadEnvironment(definition.dir)),
+    ];
+}
+/**
+ * Every declaration of a secret, each where it is: the code's, then the references of the MCP servers, the program's
+ * and, given `instance`, the ones it adds.
+ */
+export function definitionSecrets(definition, config, instance) {
+    return [...codeSecrets(definition, config), ...mcpSecrets(declareMcp(definition.dir, instance))];
+}

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

@@ -1,7 +1,8 @@
 /**
- * `sessions.events` (SPEC.md §6.1) over pi-durable's event stream of one conversation: the entries asked for, a
- * `state` snapshot, then what each commit adds. pi-durable captures its snapshot and the registration for later
- * commits atomically, so the replay ends at the snapshot's newest entry and the live part starts after it.
+ * `sessions.events` (SPEC.md §6.1) over pi-durable's view of one conversation: the entries asked for, a `state`
+ * snapshot, then what each commit changes. The view is observed synchronously, one revision per commit, so the
+ * replay ends at the first revision's newest entry and the live part, diffed from one revision to the next, starts
+ * after it. Every revision is kept: a message that is placed and answered between two reads still gets its `done`.
  */
 import type { Context } from "@earendil-works/chord/context";
 import { type Harness } from "@earendil-works/pi-durable";