@fastagent-sh/fastagent 0.14.0 → 0.15.0

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

@@ -1,15 +1,20 @@
 /**
- * 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
@@ -31,8 +36,10 @@ export interface ToolActivation {
     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). */

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

@@ -1,13 +1,7 @@
 /**
- * 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();

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

@@ -1,16 +1,14 @@
 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";
+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.) 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;
+    /** 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
@@ -48,7 +46,7 @@ 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;
+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

@@ -69,7 +69,12 @@ export function defineTool(options) {
                     },
                 }
                 : undefined;
-            const result = wrapResult(await options.execute(parsed.data, { signal, session: store?.session, tools }));
+            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

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,6 +93,10 @@ export declare function createPiAgentFromWorkspace(dir: string, options?: Create
     sessionsDir: string;
     /** Absolute credentials file in use (for the startup report). */
     authPath: string;
+    /** 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[];

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) {
@@ -33,18 +29,67 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     // 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,
@@ -52,11 +97,23 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
         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,

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)}`);

package/dist/pi.d.ts

@@ -1,15 +1,16 @@
 export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.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 type { ReadonlySessionManager, 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 type { AgentTool, ExecutionEnv, Session, SessionTreeEntry, Skill, SkillDiagnostic, } from "@earendil-works/pi-agent-core";
 export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";
 export { createPiAgentFromWorkspace, type CreatePiAgentFromWorkspaceOptions, } from "./engines/pi/workspace.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
 export { defineConfig, listModels, resolveModel, type FastagentConfig } from "./engines/pi/config.ts";
-export { inProcessLease, type Lease, type Release } from "./engines/pi/invoke.ts";
+export { inProcessLease, type Lease, type Release, type SessionObserver } from "./engines/pi/invoke.ts";
+export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./engines/pi/session-control.ts";
 export type { AnyModel } from "./engines/pi/harness.ts";
-export { inMemorySessionStore, jsonlSessionStore, type PiSessionStore } from "./engines/pi/sessions.ts";
+export { inMemorySessionStore, jsonlSessionStore, type PiSessionReader, type PiSessionStore, } from "./engines/pi/sessions.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
 export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
 export type { Models } from "@earendil-works/pi-ai";

package/dist/pi.js

@@ -6,7 +6,8 @@ export { loadChannels } from "./engines/pi/channel.js";
 export { createPiAgentFromWorkspace, } from "./engines/pi/workspace.js";
 export { defineConfig, listModels, resolveModel } from "./engines/pi/config.js";
 export { inProcessLease } from "./engines/pi/invoke.js";
-export { inMemorySessionStore, jsonlSessionStore } from "./engines/pi/sessions.js";
+export { createPiSessionControl, } from "./engines/pi/session-control.js";
+export { inMemorySessionStore, jsonlSessionStore, } from "./engines/pi/sessions.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
 export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
 export { createProvider } from "@earendil-works/pi-ai";

package/dist/scaffold/add-channel.d.ts

@@ -1,4 +1,14 @@
-export type ChannelKind = "github" | "telegram" | "feishu" | "lark";
+import type { FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
+export type ChannelKind = "github" | "telegram" | "slack" | "feishu" | "lark";
+/** Group-visibility choice shared by the slack/feishu/lark onboarding flows. Each channel keeps its
+ * own channel-level type (`SlackGroupBehavior`, `FeishuGroupBehavior`) — this is the CLI-side value. */
+export type GroupBehavior = "context" | "mentions";
+/** A resolved group-behavior decision plus whether the author actually chose it (flag or prompt).
+ * A defaulted "context" (non-interactive, no flag) must never drive a sensitive-scope write. */
+export interface GroupBehaviorChoice {
+    behavior: GroupBehavior;
+    explicit: boolean;
+}
 /** An env var a scaffolded channel reads. `generate` = a random-string secret the CLI can pre-fill. */
 export interface ChannelEnv {
     name: string;
@@ -9,8 +19,8 @@ export interface ChannelEnv {
 }
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export declare const CHANNEL_KINDS: ChannelKind[];
-/** The env vars + next-step lines a scaffolded channel needs (for the CLI to print). */
-export declare function channelSetup(kind: ChannelKind): {
+/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
+export declare function channelSetup(kind: ChannelKind, ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehavior): {
     env: ChannelEnv[];
     steps: string[];
 };
@@ -19,7 +29,7 @@ export declare function channelSetup(kind: ChannelKind): {
  * copies it to `.env` finds the vars already there. No-op when there is no `.env.example` or the block
  * is already present. Placeholders only — no real secret lands in the committable template.
  */
-export declare function appendChannelEnv(dir: string, kind: ChannelKind): Promise<boolean>;
+export declare function appendChannelEnv(dir: string, kind: ChannelKind, ingress?: FeishuSubscriptionMode): Promise<boolean>;
 export interface DotEnvWriteResult {
     /** Generated secret vars written as active `KEY=value` lines. */
     written: string[];
@@ -34,14 +44,17 @@ export interface DotEnvWriteResult {
  * (e.g. TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is
  * ready to edit while no fake secret is committed to the user's mental model.
  */
-export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[]): Promise<DotEnvWriteResult>;
+export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[], ingress?: FeishuSubscriptionMode): Promise<DotEnvWriteResult>;
 /** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
 export declare function channelExists(dir: string, kind: ChannelKind): Promise<boolean>;
 /**
  * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
  * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
  */
-export declare function scaffoldChannel(dir: string, kind: ChannelKind): Promise<string>;
+export declare function scaffoldChannel(dir: string, kind: ChannelKind, options?: {
+    ingress?: FeishuSubscriptionMode;
+    groupBehavior?: GroupBehavior;
+}): Promise<string>;
 /**
  * Verify the workspace is ready to host a channel: an ESM package.json that declares
  * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that