@fastagent-sh/fastagent 0.13.0 → 0.14.0

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

@@ -7,9 +7,20 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
-import type { AgentTool, ExecutionEnv, Skill } from "@earendil-works/pi-agent-core";
+import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
 import type { PiSessionStore } from "./sessions.ts";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
+ * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
+ * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
+ * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
+ * carry only what was actually discovered.
+ */
+export declare const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+export type PiSession = Awaited<ReturnType<PiSessionStore["openOrCreate"]>>;
+export declare function harnessSession(harness: AgentHarness): PiSession | undefined;
 /**
  * pi's Model with the API-shape generic erased — fastagent only passes models through to the
  * harness, so the generic carries no information. One alias keeps the `any` auditable.
@@ -24,6 +35,9 @@ export interface PiHarnessFactoryOptions {
     /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
     models: Models;
     model: AnyModel;
+    /** Reasoning effort for the model (pi's scale). Unset = fastagent's pinned default ("medium", pi
+     *  TUI parity — see {@link DEFAULT_THINKING_LEVEL}); unsupported levels are clamped by pi per model. */
+    thinkingLevel?: ThinkingLevel;
     tools?: AgentTool[];
     /**
      * Final assembled prompt, or a SYNC factory re-evaluated per invoke (how L1 serves dynamic
@@ -46,5 +60,6 @@ export interface PiHarnessFactoryOptions {
         skills?: Skill[];
     }>;
 }
+export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: AgentTool[], sessionId: string): string[] | undefined;
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;

package/dist/engines/pi/harness.js

@@ -7,6 +7,25 @@
  * historical entries back into context via buildContext().
  */
 import { AgentHarness } from "@earendil-works/pi-agent-core";
+import { log } from "../../log.js";
+import { isDeferredTool } from "./tool.js";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
+ * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
+ * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
+ * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
+ * carry only what was actually discovered.
+ */
+export const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+/** The session a factory-built harness is bound to — the seam the activation bridge (invoke.ts) uses
+ *  to write {@link TOOL_ACTIVATION_ENTRY} deltas (pi's harness keeps its session private). Absent for
+ *  a harness built outside {@link piHarnessFactory}: activation still works in-turn there, but is not
+ *  recorded — the factory owns persistence. */
+const harnessSessions = new WeakMap();
+export function harnessSession(harness) {
+    return harnessSessions.get(harness);
+}
 /**
  * Provider request retries. The OpenAI-family / Anthropic / Azure / Codex pi-ai adapters
  * implement client-side retries (429/5xx/request-phase network failures with backoff, honoring
@@ -19,23 +38,80 @@ import { AgentHarness } from "@earendil-works/pi-agent-core";
  * so a mid-stream failure surfaces as a `failed` event.
  */
 const PROVIDER_MAX_RETRIES = 2;
+/**
+ * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
+ * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
+ * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
+ * here means an upstream default change in either place cannot silently alter deployments. Models
+ * that don't support a level are clamped by pi per model.
+ */
+const DEFAULT_THINKING_LEVEL = "medium";
+/**
+ * Resolve the active-tool set for a fresh harness — the ONE place both fallbacks live. pi's harness
+ * WRITES active-tool changes to the session (`setActiveTools` → `active_tools_change`) but its
+ * constructor never reads them back — pi's long-lived TUI harness keeps the set in memory, while
+ * fastagent builds a FRESH harness per invoke, which would silently reset the session's active set
+ * every turn.
+ *
+ * No record (`null`) → the INITIAL set: every non-deferred tool; undefined when nothing is deferred
+ * (pi's default — all active — applies, and no session entry is ever written; tool-sets without
+ * deferral behave exactly as before deferral existed).
+ *
+ * A record is NOT replayed as a frozen snapshot — the active set is rebuilt as the UNION of the
+ * initial set and the recorded names (filtered to the mounted tools: the constructor THROWS on
+ * unknown names, so a recorded-but-removed tool would otherwise brick every future invoke of that
+ * session). On the serving path only the additive activation bridge writes records, so a record's
+ * real semantic is "which deferred tools this session activated" — layered on top of whatever the
+ * workspace mounts TODAY. A snapshot replay would silently freeze a later-added non-deferred tool
+ * out of every session the loader ever touched. Missing recorded names are logged (fail visibly) —
+ * ONCE per session+missing set: a fresh harness is built per invoke and channel sessions live for
+ * weeks, so an un-deduped warn would repeat every turn and dilute its own signal. A log-dedup memo
+ * (like L2's findings memo), not session state — the resolve stays derived from the session.
+ */
+const warnedRestores = new Set();
+export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
+    const anyDeferred = tools.some(isDeferredTool);
+    const initial = tools.filter((t) => !isDeferredTool(t)).map((t) => t.name);
+    if (recorded === null)
+        return anyDeferred ? initial : undefined;
+    const mounted = new Set(tools.map((t) => t.name));
+    const known = recorded.filter((name) => mounted.has(name));
+    const missing = recorded.filter((name) => !mounted.has(name));
+    if (missing.length > 0) {
+        const emit = warnedRestores.has(`${sessionId}\u0000${missing.join(",")}`) ? log.debug : log.warn;
+        warnedRestores.add(`${sessionId}\u0000${missing.join(",")}`);
+        emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${missing.join(", ")}`);
+    }
+    return [...new Set([...initial, ...known])];
+}
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export function piHarnessFactory(options) {
     return async (sessionId) => {
         const session = await options.sessions.openOrCreate(sessionId);
+        // One extra entry walk per invoke to collect the activation deltas — negligible against the model
+        // call, same trade as L2's per-invoke definition re-read. Serving sessions never branch, so a flat
+        // getEntries() read (no leaf-path walk) is correct.
+        const entries = await session.getEntries();
+        const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
+            ? (e.data?.names ?? [])
+            : []);
         const fresh = options.live ? await options.live() : undefined;
         const { systemPrompt } = options;
         const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
         const skills = fresh ? fresh.skills : options.skills;
-        return new AgentHarness({
+        const harness = new AgentHarness({
             env: options.env,
             session,
             models: options.models,
             model: options.model,
+            thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
             tools: options.tools,
+            activeToolNames: resolveHarnessActiveToolNames(activated.length > 0 ? activated : null, options.tools ?? [], sessionId),
             systemPrompt: prompt,
             resources: skills ? { skills } : undefined,
             streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
         });
+        harnessSessions.set(harness, session);
+        return harness;
     };
 }

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

@@ -1,6 +1,6 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { type Agent, type AgentEvent } from "../../agent.ts";
-import type { PiHarnessFactory } from "./harness.ts";
+import { type PiHarnessFactory } from "./harness.ts";
 export type Release = () => void;
 export interface Lease {
     /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */

package/dist/engines/pi/invoke.js

@@ -1,7 +1,8 @@
 import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { log } from "../../log.js";
-import { turnContext } from "./tool-context.js";
+import { TOOL_ACTIVATION_ENTRY, harnessSession } from "./harness.js";
+import { additiveActivation, turnContext } from "./tool-context.js";
 export function inProcessLease() {
     const busy = new Set();
     return {
@@ -129,6 +130,40 @@ export function errorToTerminal(error) {
     const details = error instanceof Error ? error.message : String(error);
     return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
 }
+/**
+ * The turn's {@link ToolActivation} over the live harness. `activate` is additive and filters to the
+ * registered names first — pi's `setActiveTools` THROWS on unknown names, and a loader must get a
+ * usable "nothing new" answer, not an exception. pi persists the change in the session, so the
+ * per-invoke restore (harness.ts) carries it into later turns.
+ */
+function toolActivation(harness) {
+    // Serialize activations per turn: "who activated first" must be decided HERE, not by whether pi's
+    // setActiveTools happens to mutate before its first await — parallel tool calls in one batch race
+    // their activate() calls, and the addedToolNames load points must not double-stamp.
+    let chain = Promise.resolve([]);
+    return {
+        active: () => harness.getActiveTools().map((t) => t.name),
+        registered: () => harness.getTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+        activate(names) {
+            const run = async () => {
+                const current = harness.getActiveTools().map((t) => t.name);
+                const added = additiveActivation(harness.getTools().map((t) => t.name), current, names);
+                if (added.length > 0) {
+                    await harness.setActiveTools([...current, ...added]);
+                    // Persist the DELTA in a dedicated entry — what the per-invoke resolve (harness.ts) reads.
+                    // pi's own active_tools_change record is a full snapshot and is deliberately ignored there.
+                    // Absent session (a harness built outside piHarnessFactory): in-turn activation still works,
+                    // it just isn't durable — the factory owns persistence.
+                    await harnessSession(harness)?.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
+                }
+                return added;
+            };
+            const result = chain.then(run, run); // run after the predecessor settles, success or failure
+            chain = result.catch(() => []); // the caller sees a rejection on `result`; the chain stays usable
+            return result;
+        },
+    };
+}
 /**
  * After a successful turn, compact the session if its context has grown past pi's threshold — a long
  * shared (group) or 1:1 conversation otherwise overflows the model's window. pi owns the mechanism
@@ -242,7 +277,7 @@ export function createPiAgentFromHarness(options) {
                 // (turnContext / ToolContext.session). prompt() starts the async work synchronously here, so the
                 // store propagates to the tool calls awaited within it.
                 const opts = await toPiPromptOptions(prompt);
-                const run = turnContext.run({ session: scope.session }, () => harness.prompt(prompt.text, opts));
+                const run = turnContext.run({ session: scope.session, tools: toolActivation(harness) }, () => harness.prompt(prompt.text, opts));
                 yield* queue.drainUntil(run);
                 let terminal;
                 try {

package/dist/engines/pi/login.js

@@ -6,7 +6,7 @@ function anySignal(...signals) {
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Map pi-ai's `AuthLoginCallbacks` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
+ * Map pi-ai's `AuthInteraction` onto the injected {@link LoginIO}. `doneSignal` fires when the flow
  * resolves, cancelling a prompt the provider left pending (a manual-code paste racing a callback
  * server it just won) so the one-shot CLI exits instead of hanging on stdin.
  */

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

@@ -0,0 +1,10 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+export declare function withSearchTool(tools: AgentTool[]): AgentTool[];
+/** 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(): AgentTool;

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

@@ -0,0 +1,138 @@
+/**
+ * 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).
+ */
+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. */
+export function withSearchTool(tools) {
+    if (!tools.some(isDeferredTool))
+        return tools;
+    const authored = tools.find((t) => t.name === "search_tools");
+    if (!authored)
+        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).
+        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. */
+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. */
+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).
+        "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 " +
+            "(if too many match, you get the candidates back — narrow the query, or query an exact tool " +
+            "name). ALWAYS search here before concluding a capability is missing.",
+        input: z.object({
+            query: z.string().min(1).describe("keywords describing the capability you need (e.g. 'weather forecast')"),
+        }),
+        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.
+            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).
+            const matchesQuery = (t) => {
+                const haystack = `${t.name} ${t.description}`.toLowerCase();
+                return tokens.every((token) => haystack.includes(token));
+            };
+            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.
+            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.
+            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.
+            const listedActive = activeMatches.slice(0, MAX_MISS_LISTING);
+            const moreActive = activeMatches.length - listedActive.length;
+            const activeNote = activeMatches.length > 0
+                ? `Already active (call directly): ${listedActive.map(describe).join("; ")}${moreActive > 0 ? ` … and ${moreActive} more` : ""}.`
+                : "";
+            if (inactiveMatches.length === 0) {
+                if (activeNote)
+                    return activeNote;
+                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).
+                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.
+                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
+                    .map((t) => t.name)
+                    .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
+            }
+            const activated = await 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.
+            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}` : ""}`;
+            }
+            const raced = inactiveMatches.filter((t) => !activated.includes(t.name));
+            return `Activated: ${inactiveMatches
+                .filter((t) => activated.includes(t.name))
+                .map(describe)
+                .join("; ")}.${raced.length > 0 ? ` Already active: ${raced.map((t) => t.name).join(", ")}.` : ""}${activeNote ? ` ${activeNote}` : ""} These tools are callable now.`;
+        },
+    });
+}

package/dist/engines/pi/tool-context.d.ts

@@ -10,8 +10,36 @@
  * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * The turn's tool-activation bridge — narrow closures over the CURRENT harness (invoke.ts builds it
+ * per turn), so a loader tool can activate deferred tools mid-turn without tool.ts importing the
+ * harness. pi records the change in the session (`active_tools_change`) and the per-invoke restore
+ * (harness.ts) carries it into later turns; defineTool's wrapper stamps the newly-activated names on
+ * the tool result (`addedToolNames`) — the load point native deferred-loading providers preserve the
+ * prompt-cache prefix with.
+ */
+export interface ToolActivation {
+    /** Names of the currently ACTIVE tools. */
+    active(): string[];
+    /** Every registered tool (active or not) — the discovery corpus for a loader like `search_tools`. */
+    registered(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /** ADDITIVE activation. Unknown names are filtered out before reaching pi (whose `setActiveTools`
+     *  THROWS on them); resolves the names actually newly activated (already-active names don't repeat). */
+    activate(names: string[]): Promise<string[]>;
+}
 export interface TurnContext {
     /** The session id of the current turn. */
     session: string;
+    /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
+     *  serving harness; chat.ts bridges pi's AgentSession (chat emulates deferral — same loader, same
+     *  semantics). Absent only outside any turn (a bare `fastagent tool` run). */
+    tools?: ToolActivation;
 }
 export declare const turnContext: AsyncLocalStorage<TurnContext>;
+/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
+ *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
+ *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
+export declare function additiveActivation(registered: string[], current: string[], names: string[]): string[];

package/dist/engines/pi/tool-context.js

@@ -11,3 +11,11 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 export const turnContext = new AsyncLocalStorage();
+/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
+ *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
+ *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
+export function additiveActivation(registered, current, names) {
+    const known = new Set(registered);
+    const active = new Set(current);
+    return [...new Set(names)].filter((name) => known.has(name) && !active.has(name));
+}

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

@@ -1,22 +1,53 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
+import { type ToolActivation } from "./tool-context.ts";
 export interface ToolContext {
     /** Abort signal for the current turn — honor it to cancel in-flight work on cancellation. */
     signal?: AbortSignal;
     /** The session id of the current turn — which conversation this tool is running in. A general tool
      *  capability: partition per-conversation data, tag logs, scope state. Undefined outside a turn (a bare
      *  `fastagent tool` run, or any call with no session). (The built-in `wake` tool is one consumer — it
-     *  fires a later turn back into this same session.) */
+     *  fires a later turn back into this same session.) In a `fastagent chat` turn this is pi's LOCAL
+     *  chat session id, not a served session — serving-coupled consumers like wake are not mounted there. */
     session?: string;
+    /** Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred}
+     *  tools with it — the built-in `search_tools` is one consumer). Provided by both the serving path
+     *  (invoke.ts, over the harness) and chat (over pi's AgentSession); undefined only outside any turn
+     *  (a bare `fastagent tool` run). */
+    tools?: ToolActivation;
 }
 export interface DefineToolOptions<I extends z.ZodType> {
     /** Explicit name. Usually omitted — a `tools/<name>.ts` tool is named from its filename. */
     name?: string;
     description: string;
     input: I;
+    /**
+     * Registered but NOT initially active: the tool's schema stays out of every request (and the model's
+     *  sight) until a loader — the built-in `search_tools`, mounted automatically when any deferred tool
+     *  exists — activates it mid-turn. For tool-heavy agents: fewer schemas per turn, and on providers
+     *  with native deferred loading the activation preserves the prompt-cache prefix. The trade-off:
+     *  discovery rides entirely on this description — write it for the search. Default: false.
+     */
+    deferred?: boolean;
+    /** pi's per-tool execution mode: "sequential" makes pi run any batch containing this tool serially.
+     *  REQUIRED for a tool that activates others (a loader): pi's own diff around SDK tools (chat)
+     *  would attribute one activation to two parallel calls otherwise. */
+    executionMode?: "sequential" | "parallel";
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
+/** An AgentTool with fastagent's deferral marker — the type for raw tools handed to fastagent
+ *  (`config.tools`, L1/L2 `tools`): plain `AgentTool` has no `deferred`, so an object literal with the
+ *  marker would fail excess-property checking against upstream's type. `defineTool` produces it. */
+export type FastagentTool = AgentTool & {
+    deferred?: boolean;
+};
+/** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
+ *  AgentTool object — pi ignores it). */
+export declare function isDeferredTool(tool: AgentTool): boolean;
+/** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
+ *  could never be activated and would strand every deferred tool). */
+export declare function stripDeferredMarker(tool: AgentTool): AgentTool;
 export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): AgentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
 export interface ToolCollision {

package/dist/engines/pi/tool.js

@@ -14,6 +14,19 @@ import { join } from "node:path";
 import { z } from "zod";
 import { loadModuleDir } from "../../loader.js";
 import { turnContext } from "./tool-context.js";
+/** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
+ *  AgentTool object — pi ignores it). */
+export function isDeferredTool(tool) {
+    return tool.deferred === true;
+}
+/** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
+ *  could never be activated and would strand every deferred tool). */
+export function stripDeferredMarker(tool) {
+    if (!isDeferredTool(tool))
+        return tool;
+    const { deferred: _drop, ...active } = tool;
+    return active;
+}
 /** Wrap a plain return value into pi's tool-result shape; pass a full result through unchanged. */
 function wrapResult(value) {
     if (value && typeof value === "object" && Array.isArray(value.content)) {
@@ -28,6 +41,8 @@ export function defineTool(options) {
         name: options.name ?? "",
         description: options.description,
         parameters,
+        ...(options.deferred ? { deferred: true } : {}),
+        ...(options.executionMode ? { executionMode: options.executionMode } : {}),
         async execute(_toolCallId, rawParams, signal) {
             const parsed = options.input.safeParse(rawParams);
             if (!parsed.success) {
@@ -35,7 +50,33 @@ export function defineTool(options) {
                 const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
                 return { content: [{ type: "text", text: `Invalid arguments: ${detail}` }], details: { error: detail } };
             }
-            return wrapResult(await options.execute(parsed.data, { signal, session: turnContext.getStore()?.session }));
+            const store = turnContext.getStore();
+            // Stamp tools THIS execute activates on its result — the load point that lets native
+            // deferred-loading providers add the definitions at this transcript position without
+            // invalidating the cached prompt prefix. The names come from this execute's OWN activate()
+            // calls (accumulated below), NOT from an active-set before/after diff: pi runs tool calls of a
+            // batch in parallel, and a snapshot diff would stamp a sibling's activation onto the wrong tool
+            // result, drifting the load point.
+            const added = [];
+            const tools = store?.tools
+                ? {
+                    ...store.tools,
+                    activate: async (names) => {
+                        // biome-ignore lint/style/noNonNullAssertion: guarded by the ternary above
+                        const activated = await store.tools.activate(names);
+                        added.push(...activated);
+                        return activated;
+                    },
+                }
+                : undefined;
+            const result = wrapResult(await options.execute(parsed.data, { signal, session: store?.session, tools }));
+            if (added.length > 0) {
+                // A copy, not a mutation: wrapResult passes a full AgentToolResult through by REFERENCE, and an
+                // author may legally return a shared/frozen result object — stamping in place would corrupt it
+                // across calls (or throw on frozen), only on the rare activating path.
+                return { ...result, addedToolNames: [...new Set([...(result.addedToolNames ?? []), ...added])] };
+            }
+            return result;
         },
     };
     return tool;

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

@@ -45,8 +45,11 @@ export declare function createPiAgentFromWorkspace(dir: string, options?: Create
     sessionsDir: string;
     /** Absolute credentials file in use (for the startup report). */
     authPath: string;
-    /** Non-default tool names in effect: config.tools + discovered tools/. */
+    /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
+     *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */
     toolNames: string[];
+    /** Tools registered but not initially active (deferred) — activated via search_tools. */
+    deferredToolNames: string[];
     toolCollisions: ToolCollision[];
     /** `tools/` files that failed to import — skipped, reported by the caller, never fatal. */
     toolFailures: ModuleLoadFailure[];

package/dist/engines/pi/workspace.js

@@ -28,7 +28,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     // The run root is `dir` (cwd — where config lives, whose AGENTS.md is ② context); the agent's own
     // surface (persona/skills/tools/channels) lives in `agentDir` (config.agentDir, or `dir` when flat).
     const agentDir = resolveAgentDir(dir, config);
-    const { tools, toolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
+    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
     // The state root: auth/sessions/channel state all derive from it, so FASTAGENT_STATE_DIR moves the
     // whole machine-state home in one knob (a container mounts one volume); the finer overrides below
     // still win for their specific path.
@@ -47,6 +47,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     await ensureStateRootSelfIgnored(dir, stateRoot);
     const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
         model: modelSpec,
+        thinkingLevel: config.thinkingLevel,
         cwd: dir,
         tools: mountedTools,
         authPath,
@@ -64,6 +65,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
         sessionsDir,
         authPath,
         toolNames,
+        deferredToolNames,
         toolCollisions,
         toolFailures,
     };

package/dist/pi.d.ts

@@ -1,5 +1,6 @@
 export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
-export { defineTool, loadTools, type DefineToolOptions, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export { defineTool, loadTools, type DefineToolOptions, type FastagentTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export type { ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
 export type { AgentTool, ExecutionEnv, Session, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
 export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";

package/dist/scaffold/add-channel.js

@@ -72,6 +72,7 @@ const CHANNEL_SCAFFOLDS = {
             },
         ],
         steps: [
+            "optional before publishing: add the sensitive im:message.group_msg permission (tenant-admin approval) to receive unmentioned managed-thread continuations and buffer other group discussion",
             "PUBLISH the app version on the page the CLI opened — the switch to webhook mode takes effect on publish (one click, once ever; no API for it)",
             "edit {channel} — routing policy (the header walks through the console setup, for hand-made apps)",
             "the event Request URL is auto-registered by `dev --tunnel` / `deploy --run`",
@@ -94,7 +95,8 @@ const CHANNEL_SCAFFOLDS = {
             },
         ],
         steps: [
-            "finish the console setup: enable Bot and add the permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
+            "finish the console setup: enable Bot and add the required permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
+            "optional before publishing: add the sensitive im:message.group_msg permission (tenant-admin approval) to receive unmentioned managed-thread continuations and buffer other group discussion",
             "run `fastagent dev --tunnel` and keep it running; if auto-registration reports a config-API 404, manually switch Subscription mode to webhook, set its printed https://…/lark Request URL, save, then create + publish a version",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
         ],

package/dist/scaffold/templates/fastagent.config.mjs

@@ -7,6 +7,7 @@
 // you have access to (`fastagent models` lists them).
 export default {
   // model: "openai-codex/gpt-5.5",
+  // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max); default "medium" (pi TUI parity)
   http: { port: 8787 },
   // selfSchedule: true, // mount the built-in `wake` tool: the agent schedules its own follow-up turns
   //                     // ("check the deploy in 10 min"). Cron jobs need no opt-in — drop a schedules/<name>.ts.