@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/engines/pi/open.js

@@ -3,9 +3,11 @@
  * drive.
  */
 import { mkdir } from "node:fs/promises";
-import { loadConfig, resolveAuthLayers, resolveModelSpec, } from "./config.js";
-import { resolveSessionsDir, resolveStateRoot, resolvePlacement } from "../../paths.js";
-import { agentOf, assemblePiFromDefinition, definitionModelRuntime, resolveAgentTools } from "./create.js";
+import { join } from "node:path";
+import { loadConfig, resolveModelSpec } from "./config.js";
+import { AGENT_MODEL_CATALOG_FILE, resolveSessionsDir, resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { describeModels } from "./session-settings.js";
+import { agentOf, assemblePiFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
 import { refuseBrokenDeclarations } from "../../loader.js";
@@ -13,6 +15,8 @@ import { loadAgentSkills } from "./definition.js";
 import { servedExtensionCommands } from "./agent-session-factory.js";
 import { reportFindingsIfChanged } from "./report.js";
 import { readMachine, withMachine } from "./machine.js";
+import { createPiModelRuntime, globalCatalogPath, machineModelRuntime, refreshCatalog } from "./models.js";
+import { agentModels } from "./agent-models.js";
 import { piSessionRecordStore } from "./session-store.js";
 import { gateSecrets } from "../../secrets-gate.js";
 /**
@@ -33,9 +37,11 @@ export async function agentCommands(agentDir, workspace, served) {
     reportFindingsIfChanged(own.dir, own);
     const machine = await readMachine(workspace);
     const { extensionPaths } = served;
-    const extensionCommands = extensionPaths.length === 0
-        ? []
-        : await servedExtensionCommands({ cwd: workspace, modelRuntime: await served.modelRuntime(), extensionPaths });
+    const extensionCommands = await servedExtensionCommands({
+        cwd: workspace,
+        modelRuntime: await served.modelRuntime(),
+        extensionPaths,
+    });
     // pi dispatches an extension command before it expands a template, so a template it shadows never runs.
     const shadowed = new Set(extensionCommands.map((command) => command.invocationName));
     return [
@@ -66,7 +72,7 @@ export async function resolveAgentAssembly(dir, options = {}) {
     if (!modelSpec) {
         throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
     }
-    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures, toolSecrets } = await resolveAgentTools(config, agentDir, workspace);
+    const { tools, toolNames, indirectTools, toolCollisions, toolFailures, toolSecrets } = await resolveAgentTools(config, agentDir, workspace);
     // THE serving-path gate for tool declarations, in the order that costs the fewest round trips. A file that could
     // not be imported declares nothing, so its `secrets:` are missing from `toolSecrets` — gating secrets first would
     // report an incomplete set, and fixing the file could then reveal more missing values. Refuse the broken file
@@ -76,15 +82,13 @@ export async function resolveAgentAssembly(dir, options = {}) {
     // definition and must survive both faults; every path through this function is about to run ALL of the tools, so
     // no `owner`.
     //
-    // DEFERRED tools gate too, deliberately: `search_tools` can activate one mid-turn, so "registered"
+    // DEFERRED tools gate too, deliberately: native discovery can activate one mid-turn, so "registered"
     // means "may run in this process" — letting it start would put the empty-credential failure back
     // inside a turn. An author who does not want that opts out per tool by not declaring.
     gateSecrets({ declared: toolSecrets, failures: [] });
     // The state root: sessions/channel state/schedule state derive from it (FASTAGENT_STATE_DIR moves it in one knob —
     // a container points it at its volume).
     const stateRoot = resolveStateRoot(agentDir);
-    // The credentials file: project-level by default (under `<agentDir>/.secrets`).
-    const auth = resolveAuthLayers(agentDir, options.authPath);
     return {
         config,
         configPath,
@@ -92,37 +96,94 @@ export async function resolveAgentAssembly(dir, options = {}) {
         agentDir,
         workspace,
         stateRoot,
-        auth,
+        // Project-level by default (under `<agentDir>/.secrets`), with the global file behind it per provider.
+        models: agentModels(agentDir, options, { cwd: workspace }),
         tools,
         toolNames,
-        deferredToolNames,
+        indirectTools,
         toolCollisions,
         toolSecrets,
     };
 }
 /**
- * The model specs `createPiAgentFromDir(dir, { authPath })` could run now: the agent's registry (pi's built-ins plus
- * its `models.json`) filtered to the providers whose credentials are configured, sorted. The directory needs no model
- * set, and the same placement and credential layers as the opener apply, so a listed spec authenticates there.
- * Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
+ * L2 over a resolved front half: the ONE mapping from what the directory resolved to what the assembly runs on, for
+ * both session shapes (the served agent and `chat`'s resident one). Two copies of it drifted once (#566, chat ran at
+ * the wrong reasoning effort). `models` is the front's own, so the assembly runs on what the report describes.
+ */
+export function assembleFront(front, extra = {}) {
+    return assemblePiFromDefinition(front.agentDir, {
+        model: front.modelSpec,
+        thinkingLevel: front.config.thinkingLevel,
+        cwd: front.workspace,
+        tools: extra.tools ?? front.tools,
+        models: front.models,
+        ...(extra.sessions ? { sessions: extra.sessions } : {}),
+    });
+}
+/**
+ * The models `createPiAgentFromDir(dir, { authPath })` could run now, as a picker shows them (spec, name, the thinking
+ * levels a session on it accepts, context window), sorted by spec: the agent's registry (pi's built-ins, its
+ * `models.json`, and what its `extensions/` declare) filtered to the providers whose credentials are configured. The
+ * directory needs no model set, and the same placement and credential layers as the opener apply, so a listed spec
+ * authenticates there. Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
  *
  * `warn` reaches the credential store. An unreadable or corrupt credentials file otherwise reads as "nothing
  * configured", so a client that must not show that as an empty list passes a sink that throws.
  */
 export async function availableModelsFromDir(dir, options = {}) {
+    const { agentDir, workspace } = resolvePlacement(dir);
+    const models = await agentModels(agentDir, options, { cwd: workspace }).runtime();
+    return describeModels(await models.getAvailable());
+}
+/**
+ * Refresh the agent's model catalog (`<agent dir>/models-store.json`) with the credentials
+ * `createPiAgentFromDir(dir, { authPath })` would use, so a model released after the installed pi appears in
+ * {@link availableModelsFromDir} and runs. Only providers those credentials authenticate are fetched (pi asks pi.dev
+ * for no other). Nothing refreshes it on its own. The file is part of the definition: commit it, and it ships with a
+ * deploy, so the deployed agent knows the same models without a network call.
+ *
+ * Rejects, naming each provider that failed, when the refresh fails, outlasts 15 seconds or `PI_OFFLINE` is set, and
+ * when the credentials authenticate no provider at all.
+ */
+export function refreshModelCatalog(dir, options = {}) {
+    return refreshModelCatalogOver(dir, options);
+}
+/** {@link refreshModelCatalog} against another catalog server. Not public: a test seam. */
+export async function refreshModelCatalogOver(dir, options, catalogBaseUrl) {
     const { agentDir } = resolvePlacement(dir);
-    const models = await definitionModelRuntime(agentDir, {
-        auth: resolveAuthLayers(agentDir, options.authPath),
-        ...(options.warn ? { warn: options.warn } : {}),
-    });
-    return (await models.getAvailable()).map((model) => `${model.provider}/${model.id}`).sort();
+    const { credentials } = agentModels(agentDir, options);
+    await refreshCatalog(join(agentDir, AGENT_MODEL_CATALOG_FILE), (catalogFile) => createPiModelRuntime({
+        agentDir,
+        credentials,
+        catalogFile,
+        ...(catalogBaseUrl ? { catalogBaseUrl } : {}),
+    }), options.signal ? { signal: options.signal } : {});
+}
+/**
+ * Refresh the MACHINE's model catalog (`~/.fastagent/models-store.json`), which every agent here reads under its own,
+ * so one refresh serves them all and no file is written into any agent. Credentials resolve as for
+ * {@link refreshModelCatalog} without a directory: `credentialStore`, else `authPath`, else the global credentials file;
+ * the environment applies either way. Rejects for the same reasons. The file never ships with a deploy.
+ */
+export function refreshMachineModelCatalog(options = {}) {
+    return refreshMachineModelCatalogOver(options);
+}
+/** {@link refreshMachineModelCatalog} against another catalog server. Not public: a test seam. */
+export async function refreshMachineModelCatalogOver(options, catalogBaseUrl) {
+    const { credentials } = agentModels(undefined, options);
+    await refreshCatalog(globalCatalogPath(), (catalogFile) => machineModelRuntime({
+        credentials,
+        catalogFile,
+        ...(catalogBaseUrl ? { catalogBaseUrl } : {}),
+    }), options.signal ? { signal: options.signal } : {});
 }
 /**
  * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or the agent dir
  * itself), load the config, resolve model and tools, then L2.
  */
 export async function createPiAgentFromDir(dir, options = {}) {
-    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, auth, tools, toolNames, deferredToolNames, toolCollisions, } = await resolveAgentAssembly(dir, options);
+    const front = await resolveAgentAssembly(dir, options);
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, models, tools, toolNames, indirectTools, toolCollisions, } = front;
     // Every serve mounts the built-in `wake` tool: the agent's own follow-up work is a default capability, and a serve
     // is where the poller that honors it runs. A one-shot `invoke` has no poller, so nothing there would fire it.
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving);
@@ -131,15 +192,8 @@ export async function createPiAgentFromDir(dir, options = {}) {
     const sessionsDir = options.sessionsDir ?? resolveSessionsDir(agentDir);
     await mkdir(sessionsDir, { recursive: true });
     const sessions = piSessionRecordStore({ dir: sessionsDir, cwd: workspace });
-    const { assembly, definition } = await assemblePiFromDefinition(agentDir, {
-        model: modelSpec,
-        thinkingLevel: config.thinkingLevel,
-        cwd: workspace,
-        tools: mountedTools,
-        auth,
-        // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
-        sessions,
-    });
+    // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
+    const { assembly, definition } = await assembleFront(front, { tools: mountedTools, sessions });
     // The hub is wired HERE because the store is created here (an external `createPiSessionControl` cannot exist before
     // the store does).
     const caller = options.observer;
@@ -169,7 +223,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
             // the prompt would not expand — a second reading of "which skills exist" is how those two come to disagree.
             commands: () => agentCommands(agentDir, workspace, {
                 extensionPaths: assembly.extensionPaths,
-                modelRuntime: async () => (await assembly.engine()).modelRuntime,
+                modelRuntime: assembly.createModelRuntime,
             }),
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub and never cross the
             // data plane's observer seam.
@@ -199,9 +253,9 @@ export async function createPiAgentFromDir(dir, options = {}) {
         modelSpec,
         stateRoot,
         sessionsDir,
-        auth,
+        models,
         toolNames,
-        deferredToolNames,
+        indirectTools,
         toolCollisions,
     };
 }

package/dist/engines/pi/report.d.ts

@@ -5,6 +5,7 @@
 import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
 import type { SkillCollision } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
+import type { IndirectTool } from "./create.ts";
 type Findings = {
     collisions: SkillCollision[];
     diagnostics: SkillDiagnostic[];
@@ -12,5 +13,7 @@ type Findings = {
 /** THE door for definition findings: warns only when this dir's set CHANGED since the last report. */
 export declare function reportFindingsIfChanged(dir: string, def: Findings): void;
 export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
+/** The report line for the mounted tools the model is not given up front: each name with its way in. */
+export declare function describeIndirectTools(tools: readonly IndirectTool[]): string;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;
 export {};

package/dist/engines/pi/report.js

@@ -23,6 +23,17 @@ export function reportDefinitionWarnings(collisions, diagnostics) {
         log.warn(`[fastagent] ${d.code}: ${d.message} (${d.path})`);
     }
 }
+const REACH = {
+    tool_search: "loaded via tool_search",
+    codemode: "codemode scripts only",
+    hidden: "hidden",
+    inactive: "inactive until an authored loader activates it",
+    unreachable: "unreachable: pi's settings disable the built-in extension it needs",
+};
+/** The report line for the mounted tools the model is not given up front: each name with its way in. */
+export function describeIndirectTools(tools) {
+    return tools.map((tool) => `${tool.name} (${REACH[tool.reach]})`).join(", ");
+}
 export function reportToolCollisions(collisions) {
     for (const c of collisions) {
         log.warn(`[fastagent] tool "${c.name}" (${c.source}) dropped — a default/config tool already uses that name`);

package/dist/engines/pi/service.d.ts

@@ -1,8 +1,8 @@
 /** `createAgentService` — the product as one call, with pi supplying the engine. */
 import { type AgentService, type MountAgentServiceOptions } from "../../service.ts";
-export interface CreateAgentServiceOptions extends MountAgentServiceOptions {
+import type { CredentialSourceOptions } from "./auth.ts";
+export interface CreateAgentServiceOptions extends MountAgentServiceOptions, CredentialSourceOptions {
     model?: string;
-    authPath?: string;
     sessionsDir?: string;
 }
 /** Open an agent directory as a live service: one handler, mounted wherever you serve. */

package/dist/engines/pi/service.js

@@ -6,6 +6,7 @@ export async function createAgentService(dir, options = {}) {
     const opened = await createPiAgentFromDir(dir, {
         ...(options.model !== undefined ? { model: options.model } : {}),
         ...(options.authPath !== undefined ? { authPath: options.authPath } : {}),
+        ...(options.credentialStore !== undefined ? { credentialStore: options.credentialStore } : {}),
         ...(options.sessionsDir !== undefined ? { sessionsDir: options.sessionsDir } : {}),
         serving: true, // a mounted service is long-running: the scheduler poller runs
     });

package/dist/engines/pi/session-builder.d.ts

@@ -6,7 +6,8 @@ export interface BuildSessionRuntimeOptions {
     authPath?: string;
 }
 /**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools, skills, and auth
- * resolved exactly as the serving opener does).
+ * Build pi's interactive runtime over the SAME assembly `dev`/`start` serve ({@link assembleFront}): model
+ * registry, prompt, tools, skills, reasoning effort and credentials all come from it, so what differs is only the
+ * session's shape (one resident runtime rather than one session per invoke).
  */
 export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, sessionManager?: SessionManager): Promise<AgentSessionRuntime>;

package/dist/engines/pi/session-builder.js

@@ -4,109 +4,63 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { SessionManager, SettingsManager, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
-import { bindPiSession, definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
-import { readMachine } from "./machine.js";
+import { SessionManager, SettingsManager, createAgentSessionRuntime, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { bindPiSession, definitionServices } from "./agent-session-factory.js";
 import { resolveModel } from "./config.js";
-import { assembleSystemPrompt, piBasePrompt } from "./create.js";
-import { canonicalPath, loadAgentDefinition, loadExtensionPaths } from "./definition.js";
-import { DEFAULT_THINKING_LEVEL, createPiModelRuntime } from "./models.js";
-import { reportFindingsIfChanged, reportToolCollisions } from "./report.js";
-import { resolveAgentAssembly } from "./open.js";
+import { canonicalPath } from "./definition.js";
+import { reportToolCollisions } from "./report.js";
+import { assembleFront, resolveAgentAssembly } from "./open.js";
+import { resolvePlacement } from "../../paths.js";
 /**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools, skills, and auth
- * resolved exactly as the serving opener does).
+ * Build pi's interactive runtime over the SAME assembly `dev`/`start` serve ({@link assembleFront}): model
+ * registry, prompt, tools, skills, reasoning effort and credentials all come from it, so what differs is only the
+ * session's shape (one resident runtime rather than one session per invoke).
  */
 export async function buildAgentSessionRuntime(dir, options = {}, sessionManager) {
-    async function resolveAssembly(cwd) {
-        // The shared front half — the SAME placement/config/model-spec/tool/auth resolution the serving opener uses
-        // (open.ts).
-        const { config, modelSpec, agentDir, auth, stateRoot, tools, toolCollisions } = await resolveAgentAssembly(cwd, options);
-        reportToolCollisions(toolCollisions);
-        // ONE hub owns model resolution AND per-request auth.
-        // The fallback layer travels too: `chat` resolving credentials differently from dev/start/invoke is exactly the
-        // divergence the layer exists to remove.
-        const modelRuntime = await createPiModelRuntime({ auth, agentDir, stateRoot });
-        const env = new NodeExecutionEnv({ cwd });
-        const definition = await loadAgentDefinition(agentDir, { cwd, env });
-        reportFindingsIfChanged(definition.dir, definition);
-        // Assembly-time, like serving's: this whole function is memoized, so the scan and its warnings happen once per
-        // runtime rather than per session rebuild (/new, /resume, fork).
-        const extensionPaths = await loadExtensionPaths(agentDir, { cwd, env });
-        // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including them here would
-        // duplicate them).
-        const systemPrompt = assembleSystemPrompt({
-            base: piBasePrompt({ tools, persona: definition.persona }),
-            contextFiles: definition.contextFiles,
-        });
-        return {
-            modelRuntime,
-            modelSpec,
-            // Serving honors config.thinkingLevel (config → L2); the resident session must too (fidelity).
-            thinkingLevel: config.thinkingLevel,
-            definition,
-            extensionPaths,
-            tools,
-            systemPrompt,
-        };
+    async function resolveAssembly() {
+        const front = await resolveAgentAssembly(dir, options);
+        reportToolCollisions(front.toolCollisions);
+        const { assembly } = await assembleFront(front);
+        // Read ONCE per runtime: a rebuild (/new, fork) keeps the startup snapshot, because config and tools stay in the
+        // import cache and a half-refreshed agent is worse than a stale one. Restart chat to pick up edits.
+        return { modelSpec: front.modelSpec, assembly, definition: await assembly.readDefinition() };
     }
-    // pi calls the factory again on /new, /resume, switch, and fork.
-    const rootCwd = canonicalPath(dir);
+    // The workspace, like serving's: where tools run and what session records are keyed to. Canonical, because pi's
+    // process.cwd() fallback is a realpath and a symlinked workspace would otherwise mismatch it.
+    const rootCwd = canonicalPath(resolvePlacement(dir).workspace);
+    // pi calls the factory again on /new, /resume, switch, and fork; the assembly is built once.
     let assembly;
     const assemblyFor = (cwd) => {
-        // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would otherwise mismatch a
-        // non-realpath rootCwd.
         const activeCwd = canonicalPath(cwd);
         if (activeCwd !== rootCwd) {
             throw workspaceScopeError(activeCwd);
         }
-        assembly ??= resolveAssembly(rootCwd);
+        assembly ??= resolveAssembly();
         return assembly;
     };
     const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { modelRuntime, modelSpec, thinkingLevel, definition, extensionPaths, tools, systemPrompt } = await assemblyFor(cwd);
+        const { modelSpec, assembly, definition } = await assemblyFor(cwd);
         // Per session, NOT memoized with the assembly.
-        const machine = await readMachine(cwd);
-        const loaded = await createAgentSessionServices({
-            cwd,
-            // fastagent's models + auth hub replaces pi's default (~/.pi-backed) one — the auth unification point; see the
-            // header.
-            modelRuntime,
-            // PACKAGELESS, for the loader: fastagent never installs a pi package (machine.ts). Handed pi's own settings, the
-            // loader resolves `packages` itself — installing a missing one, and failing chat's start when that fails.
-            settingsManager: machine.settingsManager(),
-            // Chat's assembly is fixed for the life of the runtime (a rebuild makes a new one), so these read constants.
-            resourceLoaderOptions: definitionResourceLoaderOptions({
-                systemPrompt: () => systemPrompt,
-                skills: () => definition.skills,
-                machine,
-                extensionPaths,
-            }),
-        });
+        const modelRuntime = await assembly.createModelRuntime();
+        const loaded = await definitionServices({ cwd, modelRuntime, definition, extensionPaths: assembly.extensionPaths });
         // ...while the SESSION keeps pi's own file-backed settings, so `/settings` in the TUI still saves. pi persists by
         // re-reading the file under its lock and writing only the fields that changed, so `packages` there is untouched.
         const services = { ...loaded, settingsManager: SettingsManager.create(cwd, loaded.agentDir) };
-        reportExtensionErrors(services);
         // AFTER the services, because an extension may be what defines the model.
         const model = resolveModel(modelRuntime, modelSpec);
-        // The same bind serving performs, minus the activation record: pi's chat session has nowhere to put one, which is
-        // the documented divergence.
+        // Serving and chat restore the same native transcript declarations.
         const result = await bindPiSession({
             services,
             sessionManager,
             sessionStartEvent,
             model,
-            // The SPELLING serving uses (agent-session-factory), never `thinkingLevel` alone: pi resolves an ABSENT level
-            // from its own settings, which every posture now reads from the machine (`~/.pi/agent/settings.json`). A
-            // `/thinking` + Ctrl+S saved for coding would otherwise silently make this the one posture that answers at a
-            // different reasoning effort than the deployment does — the effort is the DEFINITION's (`thinkingLevel` in
-            // fastagent.config.ts), unlike the engine knobs around it.
-            thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
-            tools,
+            // Always set, never left for pi to fill: pi resolves an ABSENT level from the machine's settings, and the effort
+            // is the definition's (`thinkingLevel` in fastagent.config.ts), like serving's.
+            thinkingLevel: assembly.thinkingLevel,
+            tools: assembly.tools,
+            excludedToolNames: assembly.excludedToolNames,
             // A tool must see one spelling of the workspace, including when opened through a symlink.
             cwd: rootCwd,
-            recordActivations: false,
         });
         return { ...result, services, diagnostics: services.diagnostics };
     };

package/dist/engines/pi/session-control.d.ts

@@ -15,7 +15,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
 import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import type { SessionObserver, Lease } from "./turn-kit.ts";
+import { type SessionObserver, type Lease } from "./turn-kit.ts";
 import type { AnyModel } from "./models.ts";
 import type { PiAgentSessionFactory } from "./invoke-session.ts";
 import type { PiSessionRecordStore } from "./session-store.ts";
@@ -25,9 +25,9 @@ export declare const SUBSCRIBER_BUFFER_CAP = 10000;
 export declare const SUBSCRIBER_BUFFER_BYTES: number;
 /** What the plane's writes (`update` / `compact` / `fork` / `delete`) need — the SAME instances the
  *  agent assembly uses: the lease (a write must not race a run), the model registry (validation +
- *  allowedModels), and the session factory (compaction is a model call). Writes go through the
- *  record the hub's reader opened — after an existence check, so the control plane never creates
- *  a session (that is the data plane's monopoly). */
+ *  allowedModels), and the session factory (compaction is a model call). Two writes create a record:
+ *  fork's `into`, and `update()` on an id that has none (through the store's `openOrCreate`, like an
+ *  invoke). Every other write needs a record that exists. */
 export interface PiBoundaryWiring {
     lease: Lease;
     models: Models;