@fastagent-sh/fastagent 0.13.0 → 0.15.0

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

@@ -1,17 +1,52 @@
 /**
- * The per-turn context a tool's `execute` can read (beyond its abort signal): the SESSION the current
- * turn runs in. A `defineTool` tool is built ONCE and reused across sessions, so the session can't be a
- * closure — it rides an AsyncLocalStorage set around the harness turn (invoke.ts) and read inside
- * `execute` (tool.ts). Undefined outside a turn (e.g. `fastagent tool`, which runs a tool with no
- * session). This is what lets a tool know which conversation it is in — the mechanism the agent's
- * self-scheduling `wake` tool needs to fire a later turn back into the SAME session.
- *
- * Only `session` lives here (a per-turn runtime value). Deploy-time ambients a tool closes over at
- * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
+ * Per-turn capabilities shared by every FastAgent-defined tool. A tool is built once and reused across
+ * turns, so current cwd/session/activation bindings ride AsyncLocalStorage rather than definition
+ * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { SessionTreeEntry } from "@earendil-works/pi-agent-core";
+/** FastAgent's read-only port over the current conversation manager. Serving and chat adapt their
+ * different concrete session implementations to this one tool-runtime contract. */
+export interface ReadonlySessionManager {
+    getSessionId(): string;
+    getHeader(): Promise<{
+        id: string;
+        timestamp: string;
+    }>;
+    getBranch(): Promise<SessionTreeEntry[]>;
+}
+/**
+ * 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;
+    /** Working directory for this execution. Falls back to process.cwd() only for an unbound direct call. */
+    cwd?: string;
+    /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
+    sessionManager?: ReadonlySessionManager;
+    /** 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

@@ -1,13 +1,15 @@
 /**
- * The per-turn context a tool's `execute` can read (beyond its abort signal): the SESSION the current
- * turn runs in. A `defineTool` tool is built ONCE and reused across sessions, so the session can't be a
- * closure — it rides an AsyncLocalStorage set around the harness turn (invoke.ts) and read inside
- * `execute` (tool.ts). Undefined outside a turn (e.g. `fastagent tool`, which runs a tool with no
- * session). This is what lets a tool know which conversation it is in — the mechanism the agent's
- * self-scheduling `wake` tool needs to fire a later turn back into the SAME session.
- *
- * Only `session` lives here (a per-turn runtime value). Deploy-time ambients a tool closes over at
- * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
+ * Per-turn capabilities shared by every FastAgent-defined tool. A tool is built once and reused across
+ * turns, so current cwd/session/activation bindings ride AsyncLocalStorage rather than definition
+ * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 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,23 +1,52 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
+import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
 export interface ToolContext {
+    /** Working directory for this execution. */
+    cwd: string;
     /** 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.) */
-    session?: string;
+    /** Current conversation manager. Present during serving/chat; absent for sessionless direct calls. */
+    sessionManager?: ReadonlySessionManager;
+    /** 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>;
 }
-export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): AgentTool;
+/** 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>): FastagentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
 export interface ToolCollision {
     name: string;

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,38 @@ 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, {
+                cwd: store?.cwd ?? process.cwd(),
+                signal,
+                sessionManager: store?.sessionManager,
+                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/wake-tool.d.ts

@@ -15,6 +15,3 @@ export declare function parseDelayMs(input: string | number): number | undefined
 export declare function withWakeTool(tools: AgentTool[], stateRoot: string, enabled: boolean): AgentTool[];
 /** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
 export declare function makeWakeTool(stateRoot: string, now?: () => Date): AgentTool;
-/** Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring
- *  that is no longer needed). Session-scoped — a conversation can never cancel another's. */
-export declare function makeUnwakeTool(stateRoot: string): AgentTool;

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

@@ -2,7 +2,7 @@
  * The built-in `wake` tool: the agent's self-scheduling surface. Calling it records a one-shot wake-up
  * (wakeups.ts); the scheduler fires it back into the SAME session, so the agent resumes THIS
  * conversation after a delay ("check the deploy in 10 minutes"). The session comes from the turn
- * context (ToolContext.session, set around the harness turn); the state root is closed over at build
+ * context (ToolContext.sessionManager, set around the harness turn); the state root is closed over at build
  * time (where it is known — the workspace opener), never read from the turn.
  *
  * Mounted by the opener ONLY when `config.selfSchedule` is on AND on the serving path (`dev`/`start`, where
@@ -67,14 +67,15 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
             prompt: z.string().min(1).describe("the instruction for the woken turn (runs in this same conversation)"),
         }),
         execute(input, ctx) {
-            if (!ctx.session)
+            const session = ctx.sessionManager?.getSessionId();
+            if (!session)
                 return "wake is only available inside a conversation (there is no session to resume).";
             if ((input.in === undefined) === (input.cron === undefined)) {
                 return "pass exactly one of `in` (one-shot) or `cron` (recurring).";
             }
             if (input.cron !== undefined) {
                 // addWakeup validates the cron and DERIVES the first instant itself — one computation, one truth.
-                const r = addWakeup(stateRoot, { session: ctx.session, prompt: input.prompt, cron: input.cron, tz: input.tz }, now());
+                const r = addWakeup(stateRoot, { session, prompt: input.prompt, cron: input.cron, tz: input.tz }, now());
                 if (!r.ok)
                     return r.error; // guardrail message the model can act on
                 return `OK — recurring wake ${r.id} (cron "${input.cron}"${input.tz ? ` ${input.tz}` : ""}), first at ${r.fireAt}: ${input.prompt}. Use unwake({ id: "${r.id}" }) to stop it.`;
@@ -84,7 +85,7 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
                 return `couldn't parse "in" (${JSON.stringify(input.in)}) — use a unit like "30m" / "2h" / "1d", or a number of seconds (a bare number as text like "120" is rejected).`;
             }
             const at = new Date(now().getTime() + ms);
-            const r = addWakeup(stateRoot, { session: ctx.session, prompt: input.prompt, fireAt: at }, now());
+            const r = addWakeup(stateRoot, { session, prompt: input.prompt, fireAt: at }, now());
             if (!r.ok)
                 return r.error; // guardrail message the model can act on
             return `OK — I'll wake up at ${r.fireAt} (id ${r.id}) to: ${input.prompt}. Use unwake({ id: "${r.id}" }) if it becomes unnecessary.`;
@@ -93,16 +94,17 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
 }
 /** Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring
  *  that is no longer needed). Session-scoped — a conversation can never cancel another's. */
-export function makeUnwakeTool(stateRoot) {
+function makeUnwakeTool(stateRoot) {
     return defineTool({
         name: "unwake",
         description: "Cancel one of YOUR pending wake-ups (one-shot or recurring) by the id `wake` returned. Use it when " +
             "a scheduled follow-up is no longer needed — especially to stop a recurring wake once its job is done.",
         input: z.object({ id: z.string().min(1).describe("the wake-up id (returned by `wake`)") }),
         execute(input, ctx) {
-            if (!ctx.session)
+            const session = ctx.sessionManager?.getSessionId();
+            if (!session)
                 return "unwake is only available inside a conversation.";
-            return removeWakeup(stateRoot, input.id, ctx.session)
+            return removeWakeup(stateRoot, input.id, session)
                 ? `OK — wake-up ${input.id} cancelled.`
                 : `no pending wake-up ${input.id} in this conversation (already fired, or not yours).`;
         },

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

@@ -1,5 +1,9 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
+import type { SessionControl } from "../../session.ts";
+import type { SessionObserver } from "./invoke.ts";
+import type { PiSessionReader, PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
@@ -24,7 +28,51 @@ export interface CreatePiAgentFromWorkspaceOptions {
      * and never poll). The built-in `wake` tool mounts only when this is set AND `config.selfSchedule` is on.
      */
     serving?: boolean;
+    /** Assemble the session control plane over this workspace's session store and return it as
+     *  {@link sessionControl} — the store is created inside this opener, so the hub must be wired
+     *  here too (an external `createPiSessionControl` cannot exist before the store does).
+     *  Default: `config.sessionControl` AND {@link serving} — the config key means "serve the control
+     *  plane", so one-shot commands (invoke/fire) do not assemble an unused hub. Pass explicitly to
+     *  override either way. */
+    sessionControl?: boolean;
+    /** Additional raw tap with the FULL vocabulary: run events composed after the
+     *  {@link sessionControl} hub's observer, plus the hub's own boundary-mutation events
+     *  (`state_changed`/`compaction_*`) via the hub's tap. TRUSTED seam: since Phase 2a an observer
+     *  receives each run's live modulation handles (see `SessionObserver`) — for read-only consumers
+     *  use the hub's `events()` stream instead. */
+    observer?: SessionObserver;
 }
+/**
+ * The workspace assembly FRONT HALF — everything that is independent of how pi consumes the
+ * definition (transient harness for serving vs resident AgentSession for chat / session control):
+ * config → model spec → agentDir → the full tool surface ({@link resolveWorkspaceTools} — the ONE
+ * place it is computed) → state root → auth path. Both {@link createPiAgentFromWorkspace} and the
+ * session builder (session-builder.ts) consume this, so THESE inputs cannot drift between the two
+ * consumption shapes. (Definition loading and prompt assembly stay per-consumer: serving re-reads
+ * them live per invoke, the session builder snapshots at startup and lets pi append skills/env.)
+ */
+export interface WorkspaceAssembly {
+    config: FastagentConfig;
+    configPath?: string;
+    /** The resolved "provider/modelId" spec in use. */
+    modelSpec: string;
+    /** Absolute agent-definition dir (config.agentDir resolved against dir; = dir when unset). */
+    agentDir: string;
+    /** Absolute state root (FASTAGENT_STATE_DIR > <dir>/.fastagent). */
+    stateRoot: string;
+    /** Absolute credentials file (--auth-path/authPath option > FASTAGENT_AUTH_PATH > <stateRoot>/auth.json). */
+    authPath: string;
+    /** The full mounted tool surface (config.tools + discovered tools/, search_tools applied). */
+    tools: AgentTool[];
+    toolNames: string[];
+    deferredToolNames: string[];
+    toolCollisions: ToolCollision[];
+    toolFailures: ModuleLoadFailure[];
+}
+export declare function resolveWorkspaceAssembly(dir: string, options?: {
+    model?: string;
+    authPath?: string;
+}): Promise<WorkspaceAssembly>;
 /**
  * "Point at a workspace → agent": 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
@@ -45,8 +93,15 @@ 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/. */
+    /** The session store in use — also a {@link PiSessionReader}. */
+    sessions: PiSessionStore & PiSessionReader;
+    /** The observation plane over this workspace's sessions; present iff `options.sessionControl`. */
+    sessionControl?: SessionControl;
+    /** 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

@@ -9,17 +9,13 @@
  * watch and can point sessions at a mounted volume.
  */
 import { mkdir } from "node:fs/promises";
-import { defaultAuthPath, defaultSessionsDir, loadConfig, resolveAgentDir, resolveModelSpec, resolveStateRoot, } from "./config.js";
+import { defaultSessionsDir, loadConfig, resolveAgentDir, resolveAuthPath, resolveModelSpec, resolveStateRoot, } from "./config.js";
 import { createPiAgentFromDefinition, resolveWorkspaceTools } from "./create.js";
+import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
 import { ensureStateRootSelfIgnored } from "./definition.js";
 import { jsonlSessionStore } from "./sessions.js";
-/**
- * "Point at a workspace → agent": 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.
- */
-export async function createPiAgentFromWorkspace(dir, options = {}) {
+export async function resolveWorkspaceAssembly(dir, options = {}) {
     const { config, path: configPath } = await loadConfig(dir);
     const modelSpec = resolveModelSpec(options.model, config);
     if (!modelSpec) {
@@ -28,34 +24,96 @@ 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.
     const stateRoot = resolveStateRoot(dir);
+    // The credentials file: project-level by default (under the state root); only resolved here, never
+    // created (a missing file reads as not-configured — `fastagent login` creates it).
+    const authPath = resolveAuthPath(dir, options.authPath);
+    // Self-ignore the state root iff it lands in-tree — which covers everything under it (sessions, auth,
+    // every channel's `channels/<kind>` home). HERE, not in the serving opener: every consumer of this
+    // assembly can WRITE under the state root (serving: sessions/channels; the session builder: pi's
+    // `/login` writing auth.json), so resolving a workspace's state root must make it leak-safe.
+    await ensureStateRootSelfIgnored(dir, stateRoot);
+    return {
+        config,
+        configPath,
+        modelSpec,
+        agentDir,
+        stateRoot,
+        authPath,
+        tools,
+        toolNames,
+        deferredToolNames,
+        toolCollisions,
+        toolFailures,
+    };
+}
+/**
+ * "Point at a workspace → agent": 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.
+ */
+export async function createPiAgentFromWorkspace(dir, options = {}) {
+    const { config, configPath, modelSpec, agentDir, stateRoot, authPath, tools, toolNames, deferredToolNames, toolCollisions, toolFailures, } = await resolveWorkspaceAssembly(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 workspace's own `wake` wins if defined.
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
     const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
     await mkdir(sessionsDir, { recursive: true });
-    // The credentials file: project-level by default (under the self-ignored state root); only READ here,
-    // so no mkdir (a missing file reads as not-configured — `fastagent login` creates it).
-    const authPath = options.authPath ?? defaultAuthPath(stateRoot);
-    // Self-ignore the state root iff it lands in-tree — which covers everything under it (sessions, auth,
-    // every channel's `channels/<kind>` home), including a custom in-tree `FASTAGENT_STATE_DIR`. A
-    // per-path override to an external volume is out-of-tree and correctly left alone.
-    await ensureStateRootSelfIgnored(dir, stateRoot);
+    const sessions = jsonlSessionStore({ dir: sessionsDir, cwd: dir });
+    // The hub is wired HERE because the store is created here: chicken-and-egg otherwise (the hub
+    // needs the store; the agent needs the hub's observer). Boundary parts (models/factory/lease)
+    // only exist after the assembly below — the hub takes them as a lazy thunk, filled by the
+    // assembly's onAssembly callback (assembly completes before this function returns, so every
+    // dispatch sees them). An extra caller observer composes after the hub's (TRUSTED seam).
+    let boundaryParts;
+    const caller = options.observer;
+    const wantControl = options.sessionControl ?? (config.sessionControl === true && options.serving === true);
+    const hub = wantControl
+        ? createPiSessionControl({
+            sessions,
+            boundary: () => boundaryParts,
+            // 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 (set_model).
+            tap: caller ? (session, event) => caller(session, event) : undefined,
+        })
+        : undefined;
+    const observer = hub
+        ? caller
+            ? (session, event, run) => {
+                hub.observer(session, event, run);
+                caller(session, event, run);
+            }
+            : hub.observer
+        : caller;
     const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
         model: modelSpec,
+        thinkingLevel: config.thinkingLevel,
         cwd: dir,
         tools: mountedTools,
         authPath,
         // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
-        sessions: jsonlSessionStore({ dir: sessionsDir, cwd: dir }),
+        sessions,
+        observer,
+        onAssembly: hub
+            ? (parts) => {
+                boundaryParts = {
+                    lease: parts.lease,
+                    models: parts.models,
+                    harnessFactory: parts.harnessFactory,
+                };
+            }
+            : undefined,
     });
     return {
         agent,
         definition,
+        sessions,
+        sessionControl: hub?.control,
         agentDir,
         config,
         configPath,
@@ -64,6 +122,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
         sessionsDir,
         authPath,
         toolNames,
+        deferredToolNames,
         toolCollisions,
         toolFailures,
     };

package/dist/feishu.d.ts

@@ -1,2 +1,2 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";
+export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuWebSocketChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";

package/dist/feishu.js

@@ -1,2 +1,2 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";
+export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";

package/dist/host/node.d.ts

@@ -1,4 +1,5 @@
 import type { Agent } from "../agent.ts";
+import type { SessionControl } from "../session.ts";
 /** A mounted request handler (a channel's fetch, or a plain route like health). */
 export type ChannelHandler = (req: Request) => Response | Promise<Response>;
 /** This deployment's HTTP surface: route key → handler. Key is `"/path"` or `"METHOD /path"`. */
@@ -13,11 +14,26 @@ export type Routes = Record<string, ChannelHandler>;
 export interface ChannelContext {
     agent: Agent;
     stateRoot: string;
+    /** The serving session-control hub, when the serve wires one (`config.sessionControl`). Channels
+     *  use it for DISPATCH only (the user-facing stop command); observation stays on the data plane. */
+    control?: SessionControl;
 }
-/** A `channels/<name>.ts` default export: receives the mount context, returns the routes it mounts.
- *  Adapters (`telegramChannel(opts)`, `githubChannel(opts)`) RETURN one of these, so user glue holds
- *  only policy — the framework pipes `agent`/`stateRoot` to the adapter without transiting user code. */
+/** A `channels/<name>.ts` route channel: receives mount context and returns its HTTP routes. */
 export type ChannelModule = (ctx: ChannelContext) => Routes;
+/** One logical long connection's lifecycle. `ready` settles after its first usable connection — and
+ * when `signal` aborts before one exists it must still settle: resolution then means cancellation, not
+ * readiness (the server skips ready-side effects once the signal is aborted; it must never hang).
+ * `closed` resolves after abort-driven shutdown and rejects on a terminal connection failure. */
+export interface LongConnection {
+    ready: Promise<void>;
+    closed: Promise<void>;
+}
+/** A long-connection channel is an explicit module object rather than an HTTP-route factory.
+ * The adapter owns reconnects and treats `signal` as its sole shutdown command. */
+export interface LongConnectionChannelModule {
+    name: string;
+    connect(ctx: ChannelContext, signal: AbortSignal): LongConnection;
+}
 /** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
 export declare function parseRouteKey(key: string): {
     method?: string;
@@ -29,13 +45,14 @@ export declare function parseRouteKey(key: string): {
  */
 export declare function router(routes: Routes): ChannelHandler;
 /**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller close
- * it — no logging/signals/exit (the CLI owns those). `listening` resolves with the bound port (useful
- * for port 0) or rejects on a bind error.
+ * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
+ * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
+ * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
  */
 export declare function serveNode(handler: ChannelHandler, options: {
     port: number;
 }): {
     listening: Promise<number>;
     close: () => Promise<void>;
+    closeAllConnections: () => void;
 };

package/dist/host/node.js

@@ -32,9 +32,9 @@ export function router(routes) {
     };
 }
 /**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller close
- * it — no logging/signals/exit (the CLI owns those). `listening` resolves with the bound port (useful
- * for port 0) or rejects on a bind error.
+ * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
+ * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
+ * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
  */
 export function serveNode(handler, options) {
     const server = createServer(nodeListener(async (req) => handler(req)));
@@ -46,5 +46,6 @@ export function serveNode(handler, options) {
         });
     });
     const close = () => new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
-    return { listening, close };
+    const closeAllConnections = () => server.closeAllConnections();
+    return { listening, close, closeAllConnections };
 }

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./core.ts";
+export * from "./session.ts";
 export * from "./pi.ts";

package/dist/index.js

@@ -2,4 +2,5 @@
 // Contract/channel-only consumers should prefer `@fastagent-sh/fastagent/core`; pi-specific consumers
 // may use `@fastagent-sh/fastagent/pi`. The root remains the supported all-in-one surface.
 export * from "./core.js";
+export * from "./session.js";
 export * from "./pi.js";

package/dist/lark.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
  *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
-export { larkChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
+export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";

package/dist/lark.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
  *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
-export { larkChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
+export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";

package/dist/observe.js

@@ -28,6 +28,9 @@ export function logAgentLoop(agent, sink = (line) => log.debug(line)) {
                 else if (e.type === "tool_ended") {
                     sink(`[agent]   tool ${e.isError ? "✗" : "✓"} ${toolName.get(e.id) ?? e.id} → ${preview(e.content)}`);
                 }
+                else if (e.type === "retrying") {
+                    sink(`[agent]   retrying (${e.attempt}/${e.maxAttempts} in ${e.delayMs}ms): ${oneLine(e.reason)}`);
+                }
                 else if (e.type === "completed") {
                     if (thinking.trim() !== "")
                         sink(`[agent]   thinking: ${oneLine(thinking)}`);