@fastagent-sh/fastagent 0.24.4 → 0.26.0

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

@@ -0,0 +1,116 @@
+/**
+ * pi-durable's input submissions as the Agent API's messages (SPEC.md §5): a submission is a message, its request
+ * id carries the Caller's key, and its settlement is the message's end.
+ */
+import { randomUUID } from "node:crypto";
+import { isRetryableAssistantError } from "@earendil-works/pi-ai/utils/retry";
+import { agentError, errorData, } from "../../agent-api.js";
+import { hasToolCalls, replyText, thinkingOf, usageOf } from "./entries.js";
+const KEY = "key:";
+/**
+ * How pi-ai's `Models.applyAuth` says a provider has no credential (`ModelsError` "auth"). The settled submission keeps
+ * only that text, and the outcome is read from what was recorded, so it does not change once a credential is added.
+ */
+const NOT_CONFIGURED = "Provider is not configured: ";
+/** Every message is submitted with a request id, so its entry can name it: the Caller's key, or one of our own. */
+export function requestIdFor(idempotencyKey) {
+    return idempotencyKey === undefined ? `id:${randomUUID()}` : `${KEY}${idempotencyKey}`;
+}
+function idempotencyKeyOf(requestId) {
+    return requestId?.startsWith(KEY) ? requestId.slice(KEY.length) : undefined;
+}
+export function isInput(record) {
+    return record?.type === "input";
+}
+export function hasEnded(record) {
+    return record.status === "done" || record.status === "unanswered";
+}
+/** The queued inputs in the order they will be taken: steers before follow-ups, each in arrival order. */
+export function queuedInputs(inbox) {
+    const items = inbox?.items ?? [];
+    const of = (mode) => items.filter((item) => item.mode === mode).map((item) => item.id);
+    return [...of("steer"), ...of("followUp")];
+}
+/** A message as the API has it. An ended one needs its answer entry: the entry pi-durable settled it with. */
+export function messageOf(record, ids, answer) {
+    const key = idempotencyKeyOf(record.requestId);
+    const identity = {
+        id: ids.encode(record.id),
+        sessionId: ids.encode(record.conversationId),
+        ...(key === undefined ? {} : { idempotencyKey: key }),
+    };
+    switch (record.status) {
+        case "queued":
+            return { ...identity, status: "queued" };
+        case "placed":
+            return { ...identity, status: "running", entryId: ids.encode(record.entry) };
+        default:
+            return {
+                ...identity,
+                ...(record.entry === undefined ? {} : { entryId: ids.encode(record.entry) }),
+                ...end(record, ids, answer),
+            };
+    }
+}
+function end(record, ids, answer) {
+    if (record.status === "unanswered")
+        return unanswered(record);
+    const reply = answer?.model?.[0];
+    if (reply?.role !== "assistant") {
+        throw new Error(`message ${record.id} was answered by entry ${record.answer}, which holds no reply`);
+    }
+    // A run a tool ended (`control.terminate`) settles on the reply that called it, which is not an answer (§5.4).
+    if (hasToolCalls(reply))
+        return { status: "completed" };
+    return {
+        status: reply.stopReason === "length" ? "incomplete" : "completed",
+        answer: { entryId: ids.encode(record.answer), text: replyText(reply) },
+    };
+}
+function unanswered(record) {
+    const detail = typeof record.detail === "string" ? record.detail : undefined;
+    const failed = (error) => ({ status: "failed", error: errorData(error) });
+    switch (record.reason) {
+        case "aborted":
+            return { status: "canceled" };
+        case "no_model":
+            return failed(agentError("missing_model", "The session's model was not among the agent's models when it was to answer"));
+        case "model_error": {
+            const message = detail ?? "The model call failed";
+            if (message.startsWith(NOT_CONFIGURED))
+                return failed(agentError("auth_required", message));
+            // pi-ai classifies a failed reply by its error text alone, which is all a settled submission keeps.
+            const retryable = isRetryableAssistantError({ stopReason: "error", errorMessage: message });
+            return failed({ ...errorData(agentError("model_error", message)), retryable });
+        }
+        case "reset":
+            return failed(agentError("internal", "The session was reset before this message was answered"));
+        default:
+            return failed(agentError("internal", detail ?? `The message was not answered: ${record.reason}`, { reason: record.reason }));
+    }
+}
+/** The session as it is now, from its documents as one commit or one event snapshot holds them. */
+export function sessionOf(id, live, usage, agent) {
+    const partial = live?.generation?.message;
+    const thinking = partial === undefined ? undefined : thinkingOf(partial);
+    return {
+        id,
+        status: live?.run === undefined ? "idle" : "running",
+        ...(agent?.model === undefined ? {} : { model: { provider: agent.model.provider, modelId: agent.model.modelId } }),
+        ...(agent?.thinkingLevel === undefined ? {} : { thinkingLevel: agent.thinkingLevel }),
+        ...(agent?.instructions === undefined ? {} : { instructions: agent.instructions }),
+        // Only the list this API sets; pi-durable's other form (`{ remove }`) is set through `harness`, not here.
+        ...(Array.isArray(agent?.tools) ? { tools: [...agent.tools] } : {}),
+        ...(partial === undefined
+            ? {}
+            : { reply: { text: replyText(partial), ...(thinking === undefined ? {} : { thinking }) } }),
+        usage: usageOfState(usage),
+    };
+}
+/** What a conversation's `pi.usage`, or the instance's total, says it spent. */
+export function usageOfState(usage) {
+    return { models: tokensOf(usage?.models), tools: tokensOf(usage?.tools) };
+}
+function tokensOf(bucket) {
+    return Object.fromEntries(Object.entries(bucket ?? {}).map(([key, value]) => [key, usageOf(value)]));
+}

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

@@ -0,0 +1,95 @@
+import type { ModelThinkingLevel, Models, Provider } from "@earendil-works/pi-ai";
+import { type Extension, type HarnessSettings, type ModelRef, type Storage, type ToolRegistration } from "@earendil-works/pi-durable";
+import type { ResolvedContent } from "../../content/resolve.ts";
+import { type DeclaredSecret } from "../../declared-secrets.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
+import { type Schedule } from "../../schedule/schedule.ts";
+import { type DurableAgent, type Unfinished } from "./agent.ts";
+import { type AgentConfig } from "./define.ts";
+import { type Registry } from "./registry.ts";
+/** An agent package as it was read: where it is, its configuration, and the modules its registry lists. */
+export interface AgentDefinition {
+    dir: string;
+    name: string;
+    config: AgentConfig;
+    registry: Registry;
+}
+export declare function modelRefOf(spec: string, where: string): ModelRef;
+/** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
+export declare function loadConfig(dir: string): Promise<AgentConfig>;
+/** The default model a process here runs with: `--model` > `FASTAGENT_MODEL` > the configuration's `model`. */
+export declare function modelSpecFor(config: AgentConfig, flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/** Read the agent package in `dir`: `fastagent.config.ts` (optional) and `.fastagent/registry.ts`, generated first. */
+export declare function loadDefinition(directory: string): Promise<AgentDefinition>;
+/** The secrets the definition declares, wherever: its code's `needs`, and `context.json`'s command variables. */
+export declare function definitionSecrets(definition: AgentDefinition): DeclaredSecret[];
+/**
+ * The list a person deploying or running the agent reads instead of its code (`.fastagent/secrets.json`): each name
+ * once, what it is for, whether the agent runs without it, and where it is declared.
+ */
+export declare function secretsManifest(definition: AgentDefinition): {
+    name: string;
+    description?: string;
+    optional: boolean;
+    declaredIn: string[];
+}[];
+/** Generate the registry, read the definition, and write its secrets manifest beside the registry. */
+export declare function prepareDefinition(dir: string): Promise<AgentDefinition>;
+/** The definition's code, built with the values of the secrets it declares. */
+export interface BuiltDefinition {
+    tools: ToolRegistration[];
+    extensions: Extension[];
+    providers: Provider[];
+    /** By name, the file's: what a serve mounts or connects. */
+    channels: Map<string, ChannelModule | LongConnectionChannelModule>;
+    /** What the scheduler fires, each named by its file. */
+    schedules: Schedule[];
+}
+/**
+ * Refuse to run while a required secret has no value, naming where it is declared; otherwise build every module with
+ * the values it declared, and refuse one that is not what its directory holds.
+ */
+export declare function buildDefinition(definition: AgentDefinition, env?: NodeJS.ProcessEnv): BuiltDefinition;
+/**
+ * The definition's code built only to read its shape (which channels, with which ingress, which schedules, which
+ * providers): a declared secret `env` holds no value for has a stand-in, since the shape must not depend on whether
+ * this machine holds the values. Whatever a build refuses, this refuses too.
+ */
+export declare function buildDefinitionShape(definition: AgentDefinition, env: NodeJS.ProcessEnv): BuiltDefinition;
+/**
+ * The providers of the definition in `agentDir`, for a command that reads models without serving (`models`, `login`,
+ * the first-run picker): with the values `env` holds and stand-ins for the rest, so listing a model or signing in to
+ * it needs no secret the serve would. Without these a provider in code, or one replacing a built-in's id, would be
+ * unknown there, or verified against the built-in's endpoint.
+ */
+export declare function definitionProviders(agentDir: string, env?: NodeJS.ProcessEnv): Promise<Provider[]>;
+export interface AssembleAgentOptions {
+    storage: Storage;
+    /** What the agent works on and knows (`context.json`'s content), resolved for this instance. */
+    content?: readonly ResolvedContent[];
+    /** The definition's code, built once with its secrets (`buildDefinition`). */
+    code: BuiltDefinition;
+    /**
+     * pi-ai's built-ins and the definition's providers over the instance's credentials, lists refreshed: the model
+     * environment's (environment.ts), so the Agent runs on the lists its startup report reads.
+     */
+    models: Models;
+    /** Why the lists of {@link models} are not current, when they are not: said with a default model none offers. */
+    catalogProblem?: string;
+    /** What a deployment sets over the definition's defaults (a flag, `FASTAGENT_MODEL`). */
+    model?: string;
+    thinkingLevel?: ModelThinkingLevel;
+    settings?: HarnessSettings;
+    /** Where the instance's state is: given by a serve, whose scheduler fires the wake-ups `wake` keeps there. */
+    stateRoot?: string;
+    /** Whether that scheduler runs now: an app's `openAgent` runs one only while it serves. Default always. */
+    wakeTicking?: () => boolean;
+    unfinished?: Unfinished;
+    /**
+     * What the agent's environment adds to this process's, for the commands it runs: its value file's variables and its
+     * packages' PATH.
+     */
+    environment?: Readonly<Record<string, string>>;
+}
+/** Open the definition as an Agent over `models`: the coding tools, then its own. */
+export declare function assembleAgent(definition: AgentDefinition, options: AssembleAgentOptions): Promise<DurableAgent>;

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

@@ -0,0 +1,330 @@
+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;
+};
+/**
+ * A definition assembled onto pi-durable (architecture.md §3): its configuration and generated registry read, its
+ * secrets checked as one list, its code built with them, and an Agent opened over pi-ai's built-in models with the
+ * text, tools and extensions installed. `dev`, `start` and an embedder call the same function.
+ */
+import { existsSync } from "node:fs";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { basename, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRegistry, defineExtension, } from "@earendil-works/pi-durable";
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+import { CodingTools } from "@earendil-works/pi-durable/tools";
+import { loadEnvironment } from "../../content/file.js";
+import { describeSecrets, missingSecrets } from "../../declared-secrets.js";
+import { declaredVariables } from "../../environment/declare.js";
+import { channelModuleProblem } from "../../channels/discover.js";
+import { AGENT_CONFIG_FILE as CONFIG_FILE } from "../../paths.js";
+import { readPackageJson } from "../../runtime.js";
+import { DEV_SERVE_ENV } from "../../serving-command.js";
+import { MAX_SCHEDULES, scheduleConfigProblem } from "../../schedule/schedule.js";
+import { openDurableAgent } from "./agent.js";
+import { isNeeds } from "./define.js";
+import { GENERATED_DIR, REGISTRY_FILE, REGISTRY_KINDS, generateRegistry } from "./registry.js";
+import { definitionSections, readCommands } from "./text.js";
+import { WAKE_EXTENSION, WAKE_TOOLS, wakeExtension } from "./wake.js";
+const SECRETS_MANIFEST_FILE = "secrets.json";
+const CONFIG_KEYS = ["name", "description", "model", "thinkingLevel", "extensions", "providers", "http", "deploy"];
+const DEFINITION_EXTENSION = "fastagent.definition";
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+async function importDefault(path, what) {
+    try {
+        return (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href))).default;
+    }
+    catch (error) {
+        throw new Error(`${what}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/** An object whose keys are among `keys`, or the refusal naming the one that is not and the ones there are. */
+function checkKeys(value, keys, where) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(`${where} must be an object`);
+    for (const key of Object.keys(value)) {
+        if (!keys.includes(key))
+            throw new Error(`${where}: unknown key "${key}" (keys: ${keys.join(", ")})`);
+    }
+}
+/** Refuse what a type check would have: Node strips types without checking them, so a typo reaches here. */
+function checkConfig(config, file) {
+    if (config === undefined)
+        return {};
+    if (typeof config !== "object" || config === null || Array.isArray(config)) {
+        throw new Error(`${file} must default-export defineAgent({ ... })`);
+    }
+    checkKeys(config, CONFIG_KEYS, file);
+    const { model, thinkingLevel, extensions, providers, http, deploy } = config;
+    if (http !== undefined) {
+        checkKeys(http, ["port", "api"], `${file}: "http"`);
+        const port = http.port;
+        if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535)) {
+            throw new Error(`${file}: "http.port" must be an integer 0-65535`);
+        }
+        if (http.api !== undefined && typeof http.api !== "boolean") {
+            throw new Error(`${file}: "http.api" must be true or false`);
+        }
+    }
+    if (deploy !== undefined) {
+        checkKeys(deploy, ["agentcore"], `${file}: "deploy"`);
+        if (deploy.agentcore !== undefined) {
+            checkKeys(deploy.agentcore, ["idleTimeoutSeconds"], `${file}: "deploy.agentcore"`);
+            // AWS's own bounds for idleRuntimeSessionTimeout: a value outside them is refused by CloudFormation minutes
+            // into `deploy agentcore --run`, after the image build.
+            const idle = deploy.agentcore.idleTimeoutSeconds;
+            if (idle !== undefined && (!Number.isInteger(idle) || idle < 60 || idle > 1209600)) {
+                throw new Error(`${file}: "deploy.agentcore.idleTimeoutSeconds" must be an integer 60-1209600 (seconds)`);
+            }
+        }
+    }
+    if (model !== undefined)
+        modelRefOf(model, `${file}: "model"`);
+    if (thinkingLevel !== undefined && !THINKING_LEVELS.includes(thinkingLevel)) {
+        throw new Error(`${file}: "thinkingLevel" must be one of ${THINKING_LEVELS.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`);
+    }
+    return config;
+}
+export function modelRefOf(spec, where) {
+    const slash = typeof spec === "string" ? spec.indexOf("/") : -1;
+    if (slash < 1 || slash === spec.length - 1) {
+        throw new Error(`${where} must be "provider/modelId", got ${JSON.stringify(spec)}`);
+    }
+    return { provider: spec.slice(0, slash), modelId: spec.slice(slash + 1) };
+}
+/** The agent package's `fastagent.config.ts`, checked; `{}` without one. */
+export async function loadConfig(dir) {
+    const configPath = join(dir, CONFIG_FILE);
+    return checkConfig(existsSync(configPath) ? await importDefault(configPath, CONFIG_FILE) : undefined, CONFIG_FILE);
+}
+/** The default model a process here runs with: `--model` > `FASTAGENT_MODEL` > the configuration's `model`. */
+export function modelSpecFor(config, flag, env = process.env) {
+    return flag ?? (env.FASTAGENT_MODEL || config.model);
+}
+/** Read the agent package in `dir`: `fastagent.config.ts` (optional) and `.fastagent/registry.ts`, generated first. */
+export async function loadDefinition(directory) {
+    // Absolute, since the prompt names the definition's files by it and the agent's tools resolve a relative path against
+    // the agent's own working directory, which is this one.
+    const dir = resolve(directory);
+    const config = await loadConfig(dir);
+    const registryPath = join(dir, GENERATED_DIR, REGISTRY_FILE);
+    if (!existsSync(registryPath)) {
+        throw new Error(`${GENERATED_DIR}/${REGISTRY_FILE} is missing: generate it from src/ before opening the agent`);
+    }
+    let registry;
+    try {
+        registry = (await import(__rewriteRelativeImportExtension(pathToFileURL(registryPath).href)));
+    }
+    catch (error) {
+        // The registry imports every module, so a module that fails to load (or has no default export) fails here.
+        throw new Error(`loading src/ through ${GENERATED_DIR}/${REGISTRY_FILE}: ${error.message}`, {
+            cause: error,
+        });
+    }
+    const packageName = (await readPackageJson(dir));
+    const name = config.name ?? (typeof packageName.name === "string" ? packageName.name : basename(dir));
+    return { dir, name, config, registry };
+}
+/** Every value the definition can hold `Needs` in, with where it is: modules by file, configuration by key. */
+function declarers(definition) {
+    return [
+        ...REGISTRY_KINDS.flatMap((kind) => definition.registry[kind].map(({ file, value }) => ({ source: file, value }))),
+        ...(definition.config.extensions ?? []).map((value, i) => ({ source: `${CONFIG_FILE} extensions[${i}]`, value })),
+        ...(definition.config.providers ?? []).map((value, i) => ({ source: `${CONFIG_FILE} providers[${i}]`, value })),
+    ];
+}
+/** The secrets the definition declares, wherever: its code's `needs`, and `context.json`'s command variables. */
+export function definitionSecrets(definition) {
+    return [
+        ...declarers(definition).flatMap(({ source, value }) => isNeeds(value) ? value.secrets.map((secret) => ({ ...secret, source })) : []),
+        ...declaredVariables(loadEnvironment(definition.dir)),
+    ];
+}
+/**
+ * The list a person deploying or running the agent reads instead of its code (`.fastagent/secrets.json`): each name
+ * once, what it is for, whether the agent runs without it, and where it is declared.
+ */
+export function secretsManifest(definition) {
+    const byName = new Map();
+    for (const secret of definitionSecrets(definition)) {
+        const entry = byName.get(secret.name) ?? { name: secret.name, optional: true, declaredIn: [] };
+        entry.optional &&= secret.optional === true;
+        entry.declaredIn.push(secret.source);
+        if (entry.description === undefined && secret.description !== undefined)
+            entry.description = secret.description;
+        byName.set(secret.name, entry);
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Generate the registry, read the definition, and write its secrets manifest beside the registry. */
+export async function prepareDefinition(dir) {
+    await generateRegistry(dir);
+    const definition = await loadDefinition(dir);
+    writeFileAtomic(join(dir, GENERATED_DIR, SECRETS_MANIFEST_FILE), `${JSON.stringify(secretsManifest(definition), null, 2)}\n`, undefined, true);
+    return definition;
+}
+/** What one value is once its secrets are supplied, or why it is not what its place holds. */
+function built(source, value, values, accept) {
+    const resolved = isNeeds(value) ? value.build(values) : value;
+    const problem = accept(resolved);
+    if (problem !== undefined)
+        throw new Error(`${source}: ${problem}`);
+    return resolved;
+}
+const toolProblem = (value) => {
+    const tool = value;
+    return typeof tool?.name === "string" &&
+        typeof tool.description === "string" &&
+        typeof tool.parameters === "object" &&
+        typeof tool.execute === "function"
+        ? undefined
+        : "must default-export a tool (defineTool from @earendil-works/pi-durable), or needs(...) around one";
+};
+const extensionProblem = (value) => typeof value?.name === "string"
+    ? undefined
+    : "must be an extension (defineExtension from @earendil-works/pi-durable), or needs(...) around one";
+const providerProblem = (value) => typeof value?.id === "string" ? undefined : "must be a pi-ai provider (createProvider)";
+const channelProblem = channelModuleProblem;
+const scheduleProblem = (value) => value?.kind !== "fastagent.schedule"
+    ? "must default-export defineSchedule({ ... }), or needs(...) around one"
+    : scheduleConfigProblem(value);
+/**
+ * Refuse to run while a required secret has no value, naming where it is declared; otherwise build every module with
+ * the values it declared, and refuse one that is not what its directory holds.
+ */
+export function buildDefinition(definition, env = process.env) {
+    const missing = missingSecrets(definitionSecrets(definition), env);
+    if (missing.length > 0) {
+        throw new Error(`missing required secrets: ${describeSecrets(missing)} (set them in the environment)`);
+    }
+    const values = (value) => isNeeds(value) ? Object.fromEntries(value.secrets.map(({ name }) => [name, env[name] || undefined])) : {};
+    const { registry, config } = definition;
+    const tools = registry.tools.map(({ file, value }) => ({
+        source: file,
+        ...named(built(file, value, values(value), toolProblem)),
+    }));
+    const extensions = [
+        ...registry.extensions.map(({ file, value }) => ({
+            source: file,
+            ...named(built(file, value, values(value), extensionProblem)),
+        })),
+        ...(config.extensions ?? []).map((value, i) => {
+            const source = `${CONFIG_FILE} extensions[${i}]`;
+            return { source, ...named(built(source, value, values(value), extensionProblem)) };
+        }),
+    ];
+    const channels = registry.channels.map(({ file, name, value }) => ({
+        source: file,
+        name,
+        value: built(file, value, values(value), channelProblem),
+    }));
+    const schedules = registry.schedules.map(({ file, name, value }) => ({
+        source: file,
+        name,
+        value: built(file, value, values(value), scheduleProblem),
+    }));
+    refuseTwins("tool", tools);
+    // pi-durable replaces an extension installed under a name already taken, its tools and sections with it.
+    refuseTwins("extension", [
+        { source: "pi-durable's coding tools", name: CodingTools.name },
+        { source: "FastAgent's definition extension", name: DEFINITION_EXTENSION },
+        { source: "FastAgent's wake tools", name: WAKE_EXTENSION },
+        ...extensions,
+    ]);
+    refuseTwins("channel", channels);
+    refuseTwins("schedule", schedules);
+    if (schedules.length > MAX_SCHEDULES) {
+        throw new Error(`${schedules.length} schedules in src/schedules/: an agent runs at most ${MAX_SCHEDULES}`);
+    }
+    return {
+        tools: tools.map(({ value }) => value),
+        extensions: extensions.map(({ value }) => value),
+        providers: (config.providers ?? []).map((value, i) => built(`${CONFIG_FILE} providers[${i}]`, value, values(value), providerProblem)),
+        channels: new Map(channels.map(({ name, value }) => [name, value])),
+        schedules: schedules.map(({ name, value: { kind: _kind, ...config } }) => ({ name, ...config })),
+    };
+}
+/**
+ * The definition's code built only to read its shape (which channels, with which ingress, which schedules, which
+ * providers): a declared secret `env` holds no value for has a stand-in, since the shape must not depend on whether
+ * this machine holds the values. Whatever a build refuses, this refuses too.
+ */
+export function buildDefinitionShape(definition, env) {
+    const values = Object.fromEntries(definitionSecrets(definition).map(({ name }) => [name, "(no value here)"]));
+    for (const [name, value] of Object.entries(env))
+        if (value)
+            values[name] = value;
+    return buildDefinition(definition, values);
+}
+/**
+ * The providers of the definition in `agentDir`, for a command that reads models without serving (`models`, `login`,
+ * the first-run picker): with the values `env` holds and stand-ins for the rest, so listing a model or signing in to
+ * it needs no secret the serve would. Without these a provider in code, or one replacing a built-in's id, would be
+ * unknown there, or verified against the built-in's endpoint.
+ */
+export async function definitionProviders(agentDir, env = process.env) {
+    return buildDefinitionShape(await prepareDefinition(agentDir), env).providers;
+}
+const named = (value) => ({ name: value.name, value });
+/** Refuse two of a kind under one name: whichever is installed or kept last would silently stand in for the other. */
+function refuseTwins(kind, entries) {
+    const first = new Map();
+    for (const { source, name } of entries) {
+        const earlier = first.get(name);
+        if (earlier !== undefined)
+            throw new Error(`${earlier} and ${source} both define the ${kind} "${name}"`);
+        first.set(name, source);
+    }
+}
+/** Open the definition as an Agent over `models`: the coding tools, then its own. */
+export async function assembleAgent(definition, options) {
+    const { dir, config } = definition;
+    const { code, models } = options;
+    const spec = options.model ?? config.model;
+    const model = spec === undefined ? undefined : modelRefOf(spec, "the default model");
+    if (model !== undefined && models.getModel(model.provider, model.modelId) === undefined) {
+        const stale = options.catalogProblem === undefined ? "" : `, and ${options.catalogProblem}`;
+        throw new Error(`unknown model "${spec}": no provider "${model.provider}" offers "${model.modelId}"${stale}`);
+    }
+    const ownWake = [...code.tools, ...code.extensions.flatMap((extension) => extension.tools ?? [])].some(({ name }) => WAKE_TOOLS.includes(name));
+    const registry = createRegistry();
+    registry.install(CodingTools);
+    // After the coding tools, so a tool of the definition's own with one of their names replaces it.
+    registry.install(defineExtension({
+        name: DEFINITION_EXTENSION,
+        sections: definitionSections(dir, options.content ?? [], { wake: ownWake || options.stateRoot !== undefined }),
+        tools: code.tools,
+    }));
+    for (const extension of code.extensions)
+        registry.install(extension);
+    if (options.stateRoot !== undefined && !ownWake) {
+        registry.install(wakeExtension(options.stateRoot, options.wakeTicking === undefined ? {} : { ticking: options.wakeTicking }));
+    }
+    const thinkingLevel = options.thinkingLevel ?? config.thinkingLevel;
+    return openDurableAgent({
+        storage: options.storage,
+        models,
+        registry,
+        name: definition.name,
+        ...(config.description === undefined ? {} : { description: config.description }),
+        ...(model === undefined ? {} : { model }),
+        ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
+        ...(options.settings === undefined ? {} : { settings: options.settings }),
+        ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
+        // What the agent runs is not `dev`'s own serving, even when `dev` is what runs the agent.
+        env: ({ cwd }) => new NodeExecutionEnv({ cwd: cwd ?? dir, shellEnv: { ...options.environment, [DEV_SERVE_ENV]: undefined } }),
+        commands: () => readCommands(dir),
+    });
+}

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

@@ -0,0 +1,30 @@
+/**
+ * What the Agent reads from pi-durable, as Effects: a session's conversation, its published entries in either
+ * direction, a message as it is now, and the session. The operations and the event streams share them, so a Caller
+ * reads the same facts through each.
+ */
+import type { Context } from "@earendil-works/chord/context";
+import { type Conversation, type ConversationId, type EntryQuery, type EntryRecord, type Harness } from "@earendil-works/pi-durable";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import type { Entry, Message, Session } from "../../agent-api.ts";
+import { type PortFailure } from "../../effect-port.ts";
+import type { Ids } from "./ids.ts";
+import type { Sessions } from "./sessions.ts";
+import { type InputRecord } from "./messages.ts";
+export type Reads = ReturnType<typeof durableReads>;
+export declare function durableReads(harness: Harness, ids: Ids, sessions: Pick<Sessions, "has">, context: Context): {
+    conversation: (sessionId: string) => Effect.Effect<Conversation | undefined, PortFailure>;
+    history: (conversation: Conversation, query: Omit<EntryQuery, "conversationId">) => Stream.Stream<EntryRecord, PortFailure, never>;
+    published: (conversation: Conversation, query: Omit<EntryQuery, "conversationId">) => Stream.Stream<EntryRecord, PortFailure, never>;
+    publishedPages: (conversation: Conversation, query: Omit<EntryQuery, "conversationId">) => Stream.Stream<EntryRecord[], PortFailure, never>;
+    visibleEntry: (conversation: Conversation, entryId: string) => Effect.Effect<EntryRecord | undefined, PortFailure, never>;
+    newestPublished: (conversation: Conversation, atOrBefore: number | undefined) => Effect.Effect<import("@earendil-works/pi-durable").EntryId | undefined, PortFailure, never>;
+    publish: (records: readonly EntryRecord[]) => Effect.Effect<Entry[], PortFailure>;
+    message: (record: InputRecord, known?: readonly EntryRecord[]) => Effect.Effect<Message, PortFailure>;
+    submission: (messageId: string) => Effect.Effect<InputRecord | undefined, PortFailure, never>;
+    submissionByKey: (conversation: Conversation, requestId: string) => Effect.Effect<InputRecord | undefined, PortFailure, never>;
+    inbox: (conversation: Conversation) => Effect.Effect<Readonly<import("@earendil-works/pi-durable").InboxState> | undefined, PortFailure, never>;
+    session: (conversation: Pick<Conversation, "id">) => Effect.Effect<Session, PortFailure>;
+    sessionsOf: (conversations: readonly ConversationId[]) => Effect.Effect<Session[], PortFailure>;
+};