@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/engines/pi/open.js

@@ -1,39 +1,90 @@
 /**
- * Open a definition directory into an agent — the single agent opener BOTH `fastagent dev` and
- * `fastagent start` drive.
- *
- * A thin command-posture composition over L2 `createPiAgentFromDefinition`: open the directory →
- * resolve model (flag > env > config) and tools (append-after-defaults) → pick session storage →
- * call L2. dev and start share the SAME assembly here (what you iterate is what you serve); they
- * differ only at the CLI — dev watches and uses the in-tree sessions default, start runs without
- * watch and can point sessions at a mounted volume.
+ * Open a definition directory into an agent — the single agent opener BOTH `fastagent dev` and `fastagent start`
+ * drive.
  */
 import { mkdir } from "node:fs/promises";
-import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, } from "./config.js";
-import { resolveStateRoot, resolvePlacement } from "../../paths.js";
-import { agentOf, assemblePiFromDefinition, resolveAgentTools } from "./create.js";
+import { loadConfig, resolveAuthLayers, resolveModelSpec, } from "./config.js";
+import { resolveSessionsDir, resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { agentOf, assemblePiFromDefinition, definitionModelRuntime, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
+import { refuseBrokenDeclarations } from "../../loader.js";
 import { loadAgentSkills } from "./definition.js";
+import { servedExtensionCommands } from "./agent-session-factory.js";
 import { reportFindingsIfChanged } from "./report.js";
+import { readMachine, withMachine } from "./machine.js";
 import { piSessionRecordStore } from "./session-store.js";
+import { gateSecrets } from "../../secrets-gate.js";
+/**
+ * The names a `/` composer completes: this agent's skills — the definition's, plus the ones its machine lends
+ * (machine.ts) —, the commands its `extensions/` register, and the machine's prompt templates.
+ *
+ * `source` says how a name is INVOKED, which is the one thing a client needs from it: a `skill` is sent as
+ * `/skill:<name>`, an `extension` command and a `prompt` as `/<name>` (docs/design/session-control.md §5.1.1).
+ *
+ * The definition is read live, like every turn reads it; the machine is the process's one read, the same snapshot a
+ * bound session runs on, so the menu cannot offer a name the next prompt would not expand. The same holds for
+ * extensions: `served` is what sessions load — the assembly's entry points, discovered once, and the runtime turns run
+ * on (asked only when there are extensions) — never a fresh scan of `extensions/`.
+ */
+export async function agentCommands(agentDir, workspace, served) {
+    const own = await loadAgentSkills(agentDir, { cwd: workspace });
+    // A skill whose frontmatter broke simply is not in `skills` — it would vanish from the composer with no signal.
+    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 });
+    // 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 [
+        ...withMachine(own.skills, machine.skills).map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            source: "skill",
+        })),
+        ...extensionCommands.map((command) => ({
+            name: command.invocationName,
+            ...(command.description ? { description: command.description } : {}),
+            source: "extension",
+        })),
+        ...machine.prompts
+            .filter((prompt) => !shadowed.has(prompt.name))
+            .map((prompt) => ({
+            name: prompt.name,
+            ...(prompt.description ? { description: prompt.description } : {}),
+            source: "prompt",
+        })),
+    ];
+}
 export async function resolveAgentAssembly(dir, options = {}) {
-    // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery;
-    // its parent — the WORKSPACE — is what the agent works on: its cwd and the start of the ②-context
-    // walk (that is where it reads the project's AGENTS.md from).
+    // Placement is structural (resolvePlacement): the AGENT DIR carries definition + config + machinery; its parent.
     const { agentDir, workspace } = resolvePlacement(dir);
     const { config, path: configPath } = await loadConfig(agentDir);
     const modelSpec = resolveModelSpec(options.model, config);
     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 } = await resolveAgentTools(config, agentDir, workspace);
-    // 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); the finer overrides below still win.
+    const { tools, toolNames, deferredToolNames, 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
+    // first and one pass reports every secret the definition actually wants.
+    refuseBrokenDeclarations(toolFailures);
+    // Both gates live here rather than inside resolveAgentTools, which `info` and `fastagent tool` call to REPORT on a
+    // 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"
+    // 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`); only resolved here, never
-    // created (a missing file reads as not-configured — `fastagent login` creates it).
-    const authPath = resolveAuthPath(agentDir, options.authPath);
+    // The credentials file: project-level by default (under `<agentDir>/.secrets`).
+    const auth = resolveAuthLayers(agentDir, options.authPath);
     return {
         config,
         configPath,
@@ -41,26 +92,43 @@ export async function resolveAgentAssembly(dir, options = {}) {
         agentDir,
         workspace,
         stateRoot,
-        authPath,
+        auth,
         tools,
         toolNames,
         deferredToolNames,
         toolCollisions,
-        toolFailures,
+        toolSecrets,
     };
 }
 /**
- * "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. Throws a clear error when
- * no model source is set (fail visibly at startup). Returns everything an entry point needs to report
- * what it assembled.
+ * 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.
+ *
+ * `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 } = 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();
+}
+/**
+ * "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, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveAgentAssembly(dir, options);
-    // Mount the built-in `wake` tool only when BOTH: this is a long-running serve (the poller honors it) AND
-    // the author opted into self-scheduling (config.selfSchedule). The agent's own `wake` wins if defined.
-    const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
-    const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, auth, tools, toolNames, deferredToolNames, toolCollisions, } = await resolveAgentAssembly(dir, options);
+    // 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);
+    // An explicit value is used as given (the store resolves a relative one against the WORKSPACE); without one, the
+    // resolution every reader shares (config.ts), so a serve and an `info` never report on different directories.
+    const sessionsDir = options.sessionsDir ?? resolveSessionsDir(agentDir);
     await mkdir(sessionsDir, { recursive: true });
     const sessions = piSessionRecordStore({ dir: sessionsDir, cwd: workspace });
     const { assembly, definition } = await assemblePiFromDefinition(agentDir, {
@@ -68,51 +136,43 @@ export async function createPiAgentFromDir(dir, options = {}) {
         thinkingLevel: config.thinkingLevel,
         cwd: workspace,
         tools: mountedTools,
-        authPath,
+        auth,
         // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
         sessions,
     });
-    // The hub is wired HERE because the store is created here (an external `createPiSessionControl`
-    // cannot exist before the store does). Its writes contend on the assembly's own lease and validate
-    // against its own registry — the value above is what makes "same" true. An extra caller observer
-    // composes after the hub's (TRUSTED seam).
+    // The hub is wired HERE because the store is created here (an external `createPiSessionControl` cannot exist before
+    // the store does).
     const caller = options.observer;
-    const wantControl = options.sessionControl ?? (config.sessionControl === true && options.serving === true);
+    // TWO decisions, not one. The hub is in-process bookkeeping over the run observer: a serve gets it unconditionally,
+    // because `/stop` in a chat is an ordinary thing to ask for and reaching the live run is the only way to answer it.
+    // Publishing `/control/*` — steer, rewrite, delete, unauthenticated at whatever URL this serves on — is the
+    // separate decision `config.sessionControl` makes, and it is the only one that also wires the boundary.
+    const publish = options.sessionControl ?? config.sessionControl === true;
+    const wantControl = publish || options.serving === true;
     let hub;
     if (wantControl) {
-        // The hub's surface is synchronous (`capabilities()` lists the allowed models), while building
-        // the registry reads credentials and is not. Resolve it ONCE here — the opener is async anyway,
-        // and the first turn would have paid the same read — so every boundary mutation validates
-        // against the same registry the runs use.
-        const { modelRuntime, model } = await assembly.engine();
-        hub = createPiSessionControl({
-            sessions,
-            boundary: {
+        // The hub's surface is synchronous (`capabilities()` lists the allowed models), while building the registry reads
+        // credentials and is not. Resolved only when the boundary is wired, so an ordinary serve does not pay for it.
+        const boundary = publish
+            ? await assembly.engine().then(({ modelRuntime, model }) => ({
                 lease: assembly.lease,
                 models: modelRuntime,
                 sessionFactory: assembly.sessionFactory,
                 defaults: { model, thinkingLevel: assembly.thinkingLevel },
-            },
-            // Skills ARE the names a client offers — the resolved set, after collisions were decided
-            // first-wins, which a client cannot reconstruct from the directory. Read LIVE (the directory
-            // is the agent: a skill added while serving is in play on the next turn, so it must be
-            // listable now) and SKILLS-ONLY: this is called when a composer opens its completion list,
-            // and the full load's ② context walk buys nothing here.
-            commands: async () => {
-                const loaded = await loadAgentSkills(agentDir, { cwd: workspace });
-                // A skill whose frontmatter broke simply is not in `skills` — it would disappear from the
-                // author's composer with no signal anywhere. The memo is SHARED with the turn path (keyed
-                // by dir), so a finding is warned when it appears, not once per reader that notices it.
-                reportFindingsIfChanged(loaded.dir, loaded);
-                return loaded.skills.map((skill) => ({
-                    name: skill.name,
-                    description: skill.description,
-                    source: "skill",
-                }));
-            },
-            // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
-            // and never cross the data plane's observer seam — without this, an audit tap wired here
-            // would miss exactly the mutations it most needs to see (`update({ model })`).
+            }))
+            : undefined;
+        hub = createPiSessionControl({
+            sessions,
+            boundary,
+            // What a client offers is what a turn WOULD run, which since this agent inherits its machine is not the
+            // definition alone. Built through the same resource posture the turn uses, so the menu cannot list a name
+            // 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,
+            }),
+            // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub and never cross the
+            // data plane's observer seam.
             tap: caller ? (session, event) => caller(session, event) : undefined,
         });
     }
@@ -130,7 +190,8 @@ export async function createPiAgentFromDir(dir, options = {}) {
         definition,
         sessions,
         sessionControl: hub?.control,
-        selfSchedule: config.selfSchedule ?? false,
+        publishControl: publish,
+        http: config.http,
         agentDir,
         workspace,
         config,
@@ -138,10 +199,9 @@ export async function createPiAgentFromDir(dir, options = {}) {
         modelSpec,
         stateRoot,
         sessionsDir,
-        authPath,
+        auth,
         toolNames,
         deferredToolNames,
         toolCollisions,
-        toolFailures,
     };
 }

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

@@ -1,6 +1,6 @@
 /**
- * Render assembly warnings to stderr — the one place both the CLI runners and the `chat` runtime show
- * the non-fatal definition/tool findings the loaders return as data. One copy so the wording can't drift.
+ * Render assembly warnings to stderr — the one place both the CLI runners and the `chat` runtime show the non-fatal
+ * definition/tool findings the loaders return as data.
  */
 import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
 import type { SkillCollision } from "./definition.ts";
@@ -9,16 +9,7 @@ type Findings = {
     collisions: SkillCollision[];
     diagnostics: SkillDiagnostic[];
 };
-/**
- * THE door for definition findings: warns only when this dir's set CHANGED since the last report.
- * Every reader calls it — boot, the per-turn live read, the control plane's command list — so a
- * finding is announced when it appears and never repeated. There is deliberately no "record without
- * printing" variant: a memo entry that trusts some other caller to have printed would silently
- * swallow findings for a caller that does not.
- *
- * `dir` must be the RESOLVED definition root (`LoadedDefinition.dir`), or two spellings of one path
- * become two memos and warn twice.
- */
+/** 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;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;

package/dist/engines/pi/report.js

@@ -5,23 +5,9 @@ function findingsSignature(def) {
     const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
     return [...collisions, ...diagnostics].sort().join("\n");
 }
-/**
- * The last reported finding set PER DEFINITION DIR. One memo for every reader of a definition (the
- * per-turn live read, the control plane's command list), because the thing being deduped is the
- * FINDING, not the reader: a newly broken skill deserves one warning, not one per code path that
- * noticed it, and a static one deserves none at all.
- */
+/** The last reported finding set PER DEFINITION DIR. */
 const lastFindings = new Map();
-/**
- * THE door for definition findings: warns only when this dir's set CHANGED since the last report.
- * Every reader calls it — boot, the per-turn live read, the control plane's command list — so a
- * finding is announced when it appears and never repeated. There is deliberately no "record without
- * printing" variant: a memo entry that trusts some other caller to have printed would silently
- * swallow findings for a caller that does not.
- *
- * `dir` must be the RESOLVED definition root (`LoadedDefinition.dir`), or two spellings of one path
- * become two memos and warn twice.
- */
+/** THE door for definition findings: warns only when this dir's set CHANGED since the last report. */
 export function reportFindingsIfChanged(dir, def) {
     const sig = findingsSignature(def);
     if (lastFindings.get(dir) === sig)

package/dist/engines/pi/search-tools.d.ts

@@ -1,12 +1,4 @@
 import { type MountedTool } from "./tool.ts";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own.
- *  Typed on the MOUNTED tool, not the authored one: it inspects names and deferral and never executes,
- *  so narrowing here would reject the very set it is handed (pi's defaults take the turn's context). */
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
 export declare function withSearchTool(tools: MountedTool[]): MountedTool[];
-/** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
- *
- * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
- * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
- * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
- * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
 export declare function makeSearchToolsTool(): MountedTool;

package/dist/engines/pi/search-tools.js

@@ -1,16 +1,8 @@
-/**
- * The built-in `search_tools` loader — the discovery surface for deferred tools (defineTool
- * `deferred: true`). A deferred tool's schema is not in the request and the model cannot see it; this
- * loader is how it finds and activates one. Mounted automatically (withSearchTool) only when a
- * deferred tool exists; a workspace tool named `search_tools` wins — the author owns the concept then
- * (same rule as the wake pair).
- */
+/** The built-in `search_tools` loader — the discovery surface for deferred tools (defineTool `deferred: true`). */
 import { z } from "zod";
 import { log } from "../../log.js";
 import { defineTool, isDeferredTool, stripDeferredMarker } from "./tool.js";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own.
- *  Typed on the MOUNTED tool, not the authored one: it inspects names and deferral and never executes,
- *  so narrowing here would reject the very set it is handed (pi's defaults take the turn's context). */
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
 export function withSearchTool(tools) {
     if (!tools.some(isDeferredTool))
         return tools;
@@ -19,41 +11,23 @@ export function withSearchTool(tools) {
         return [...tools, makeSearchToolsTool()];
     let fixed = authored;
     if (isDeferredTool(fixed)) {
-        // A deferred LOADER is a contradiction — it is the only entry point to the deferred tools, so
-        // nothing could ever activate it (or, through it, them): every deferred tool would be silently
-        // unreachable. Ignore the marker and keep the loader active (fail visibly, keep the capability).
+        // A deferred LOADER is a contradiction — it is the only entry point to the deferred tools, so nothing could ever
+        // activate it (or, through it, them).
         log.warn("[fastagent] search_tools is marked deferred — ignoring the marker: the loader must stay active, or no deferred tool could ever be activated");
         fixed = stripDeferredMarker(fixed);
     }
-    if (fixed.executionMode !== "sequential") {
-        // A non-sequential loader silently revives the parallel double-attribution (pi's diff around SDK
-        // tools in chat) — enforce the mode rather than hope the author read the docs; warn so they know.
-        log.warn('[fastagent] search_tools lacks executionMode: "sequential" — forcing it: parallel loader calls would misattribute activations');
-        fixed = { ...fixed, executionMode: "sequential" };
-    }
     return fixed === authored ? tools : tools.map((t) => (t === authored ? fixed : t));
 }
-/** Activation cap per search: activation is additive, session-persisted, and has NO deactivate path —
- *  without a cap, one broad token ("get", "file") would permanently activate half the catalog and
- *  silently spend the entire deferral benefit for the rest of the conversation. Over the cap nothing
- *  activates; the model gets the candidates and narrows the query. */
+/** Activation cap per search: activation is additive, session-persisted, and has NO deactivate path. */
 const MAX_ACTIVATIONS_PER_SEARCH = 5;
-/** Miss-path listing cap — same rationale as the activation cap: a typo query must not pour the whole
- *  catalog (the thing deferral keeps OUT of the context) back in as a tool result. */
+/** Miss-path listing cap — same rationale as the activation cap. */
 const MAX_MISS_LISTING = 10;
-/** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
- *
- * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
- * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
- * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
- * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
 export function makeSearchToolsTool() {
     return defineTool({
         name: "search_tools",
-        executionMode: "sequential",
         description: 
-        // First line short on purpose: the base prompt's tools list truncates at the first newline, and
-        // the discovery guidance below would otherwise flood it (and duplicate its deferred note).
+        // First line short on purpose: the base prompt's tools list truncates at the first newline, and the discovery
+        // guidance below would otherwise flood it (and duplicate its deferred note).
         "Discover and activate additional tools.\n" +
             "Part of this agent's toolset is inactive until needed: search by keywords (e.g. what you are " +
             "trying to do), and matching inactive tools are activated and become callable from that point on " +
@@ -65,19 +39,18 @@ export function makeSearchToolsTool() {
         async execute(input, ctx) {
             if (!ctx.tools)
                 return "tool activation is unavailable outside a conversation turn.";
-            // Search the WHOLE registered catalog: the loader is the only discovery surface, and in a long
-            // conversation the model does not remember what it activated — a "No tools matched" answer for
-            // an ALREADY-ACTIVE tool would push it toward the exact wrong conclusion (capability missing).
-            // ponytail: naive keyword match (any query token as a case-insensitive substring of
-            // name+description) with a hard per-search activation cap above — the two named ceilings are
-            // relevance and irreversibility; swap in scoring/embeddings if catalogs outgrow this.
+            // Search the WHOLE registered catalog: the loader is the only discovery surface, and in a long conversation the
+            // model does not remember what it activated.
+            // ponytail: naive keyword match (any query token as a case-insensitive substring of name+description) under a
+            // hard per-search activation cap — the two ceilings are relevance and irreversibility; swap in
+            // scoring/embeddings if catalogs outgrow this.
             const tokens = input.query
                 .toLowerCase()
                 .split(/[^a-z0-9]+/)
                 .filter(Boolean);
-            // AND semantics: EVERY token must hit — "adding a word narrows" must actually hold, or the
-            // over-cap "narrow the query" instruction sends the model in circles (OR would widen with each
-            // word, and a shared prefix like "fetch" could make a whole tool family permanently over-cap).
+            // AND semantics: EVERY token must hit — "adding a word narrows" must actually hold, or the over-cap "narrow the
+            // query" instruction sends the model in circles (OR would widen with each word, and a shared prefix like
+            // "fetch" could make a whole tool family permanently over-cap).
             const matchesQuery = (t) => {
                 const haystack = `${t.name} ${t.description}`.toLowerCase();
                 return tokens.every((token) => haystack.includes(token));
@@ -85,19 +58,16 @@ export function makeSearchToolsTool() {
             const describe = (t) => `${t.name} — ${t.description.split("\n")[0]}`;
             const active = new Set(ctx.tools.active());
             const registered = ctx.tools.registered();
-            // A query with no searchable tokens (all punctuation/symbols) must not match: `every` over an
-            // empty token list is vacuously true, and a noise query would otherwise activate the catalog.
+            // A query with no searchable tokens (all punctuation/symbols) must not match.
             if (tokens.length === 0)
                 return `"${input.query}" contains no searchable keywords — describe the capability you need.`;
-            // Exact-name shortcut: the guaranteed escape hatch from the cap — a query that IS an INACTIVE
-            // registered tool's name addresses that one tool, no keyword scoring in the way. An exact match
-            // on an ACTIVE tool falls through to keyword matching: it must not swallow the discovery of
-            // other, still-inactive keyword matches.
+            // Exact-name shortcut: the guaranteed escape hatch from the cap — a query that IS an INACTIVE registered tool's
+            // name addresses that one tool, no keyword scoring in the way.
             const exact = registered.find((t) => t.name.toLowerCase() === input.query.trim().toLowerCase());
             const activeMatches = registered.filter((t) => active.has(t.name) && (t === exact || matchesQuery(t)));
             const inactiveMatches = exact && !active.has(exact.name) ? [exact] : registered.filter((t) => !active.has(t.name) && matchesQuery(t));
-            // Same listing cap as every other branch — a wide token can match most of the ACTIVE set too
-            // (in chat that includes pi's default tools), and no answer may pour a catalog into the context.
+            // Same listing cap as every other branch — a wide token can match most of the ACTIVE set too (in chat that
+            // includes pi's default tools), and no answer may pour a catalog into the context.
             const listedActive = activeMatches.slice(0, MAX_MISS_LISTING);
             const moreActive = activeMatches.length - listedActive.length;
             const activeNote = activeMatches.length > 0
@@ -109,15 +79,14 @@ export function makeSearchToolsTool() {
                 const inactive = registered.filter((t) => !active.has(t.name));
                 if (inactive.length === 0)
                     return "All tools are already active — nothing to discover.";
-                // Cap the miss listing like the activation cap — both guard the same semantic (don't pour the
-                // catalog back into the context the deferral exists to protect).
+                // Cap the miss listing like the activation cap — both guard the same semantic (don't pour the catalog back
+                // into the context the deferral exists to protect).
                 const listed = inactive.slice(0, MAX_MISS_LISTING);
                 const more = inactive.length - listed.length;
                 return `No tools matched "${input.query}". Inactive tools: ${listed.map(describe).join("; ")}${more > 0 ? ` … and ${more} more — search with different keywords.` : ""}`;
             }
             if (inactiveMatches.length > MAX_ACTIVATIONS_PER_SEARCH) {
-                // Same listing cap as the miss path — an over-cap answer must not pour the catalog into the
-                // context either. Names alone suffice: the exact-name escape only needs a name to query.
+                // Same listing cap as the miss path — an over-cap answer must not pour the catalog into the context either.
                 const listed = inactiveMatches.slice(0, MAX_MISS_LISTING);
                 const more = inactiveMatches.length - listed.length;
                 return `${inactiveMatches.length} inactive tools matched "${input.query}" — too many to activate at once (activation is permanent for this conversation). Narrow the query (or query an exact name). Matches: ${listed
@@ -125,8 +94,8 @@ export function makeSearchToolsTool() {
                     .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
             }
             const activated = ctx.tools.activate(inactiveMatches.map((t) => t.name));
-            // Report what actually happened, not what was attempted: a parallel sibling call may have
-            // activated the same matches first, leaving nothing new here — an empty "Activated:" would lie.
+            // Report what actually happened, not what was attempted: a parallel sibling call may have activated the same
+            // matches first, leaving nothing new here.
             if (activated.length === 0) {
                 return `Matched ${inactiveMatches.map((t) => t.name).join(", ")} — already active (possibly activated by a concurrent call). Call them directly.${activeNote ? ` ${activeNote}` : ""}`;
             }

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

@@ -1,23 +1,9 @@
-/**
- * `createAgentService` — the product as one call, with pi supplying the engine.
- *
- * The ASSEMBLY is engine-neutral and lives in `src/service.ts`: it takes a {@link MountableAgent}
- * (the SPEC contract plus three paths) and knows nothing about how that agent was built. What is
- * pi-specific is opening a DIRECTORY into one, which is why this shortcut lives here and the
- * assembly does not. A second engine ships its own opener and reuses `mountAgentService` unchanged.
- */
+/** `createAgentService` — the product as one call, with pi supplying the engine. */
 import { type AgentService, type MountAgentServiceOptions } from "../../service.ts";
 export interface CreateAgentServiceOptions extends MountAgentServiceOptions {
     model?: string;
     authPath?: string;
     sessionsDir?: string;
 }
-/**
- * Open an agent directory as a live service: one handler, mounted wherever you serve.
- *
- * ```ts
- * const service = await createAgentService("./my-agent");
- * app.use("/agent", nodeListener(service.handler));
- * ```
- */
+/** Open an agent directory as a live service: one handler, mounted wherever you serve. */
 export declare function createAgentService(dir: string, options?: CreateAgentServiceOptions): Promise<AgentService>;

package/dist/engines/pi/service.js

@@ -1,21 +1,7 @@
-/**
- * `createAgentService` — the product as one call, with pi supplying the engine.
- *
- * The ASSEMBLY is engine-neutral and lives in `src/service.ts`: it takes a {@link MountableAgent}
- * (the SPEC contract plus three paths) and knows nothing about how that agent was built. What is
- * pi-specific is opening a DIRECTORY into one, which is why this shortcut lives here and the
- * assembly does not. A second engine ships its own opener and reuses `mountAgentService` unchanged.
- */
+/** `createAgentService` — the product as one call, with pi supplying the engine. */
 import { mountAgentService } from "../../service.js";
 import { createPiAgentFromDir } from "./open.js";
-/**
- * Open an agent directory as a live service: one handler, mounted wherever you serve.
- *
- * ```ts
- * const service = await createAgentService("./my-agent");
- * app.use("/agent", nodeListener(service.handler));
- * ```
- */
+/** Open an agent directory as a live service: one handler, mounted wherever you serve. */
 export async function createAgentService(dir, options = {}) {
     const opened = await createPiAgentFromDir(dir, {
         ...(options.model !== undefined ? { model: options.model } : {}),

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

@@ -1,16 +1,12 @@
 import { type AgentSessionRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
 export interface BuildSessionRuntimeOptions {
-    /** Model spec override (the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
+    /** Model spec override (the CLI --model flag). */
     model?: string;
-    /** Credentials file override (the CLI --auth-path flag). Precedence: this > FASTAGENT_AUTH_PATH >
-     *  the agent's default `<agentDir>/.secrets/auth.json`. */
+    /** Credentials file override (the SDK `authPath` option; the CLI has only `FASTAGENT_AUTH_PATH`). */
     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). Split from the TUI launcher so the
- * assembly — the fidelity-critical part — is inspectable and reusable without launching a TUI.
+ * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools, skills, and auth
+ * resolved exactly as the serving opener does).
  */
-export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, 
-/** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
-sessionManager?: SessionManager): Promise<AgentSessionRuntime>;
+export declare function buildAgentSessionRuntime(dir: string, options?: BuildSessionRuntimeOptions, sessionManager?: SessionManager): Promise<AgentSessionRuntime>;