@fastagent-sh/fastagent 0.13.0 → 0.15.0

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

@@ -1,31 +1,37 @@
-import { type ChannelContext, type Routes } from "../../host/node.ts";
+import { type ChannelContext, type LongConnection, type Routes } from "../../host/node.ts";
 import { type ModuleLoadFailure } from "../../loader.ts";
 /** A dropped route: two channels claim the same key. Surfaced, never silent. */
 export interface ChannelCollision {
     route: string;
     source: string;
 }
+/** A long-connection module bound to the same context route factories receive. Internal serving shape. */
+export interface LoadedLongConnectionChannel {
+    name: string;
+    connect(signal: AbortSignal): LongConnection;
+}
 /**
- * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing, unlike {@link loadChannels}. It enforces the SAME containment guard so info reports
- * exactly the surface dev/start would accept: a channels/ symlink escaping the workspace is rejected
- * here too. This path is independent of loadChannels', so it must guard the boundary on its own.
+ * Import channel files without mounting route factories or opening connections. Deployment needs only
+ * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
  */
-export declare function discoverChannelFiles(dir: string): Promise<string[]>;
+export declare function inspectChannels(dir: string): Promise<{
+    channels: string[];
+    routeChannels: string[];
+    longConnectionChannels: string[];
+    failures: ModuleLoadFailure[];
+}>;
 /**
- * Discover channels in `<dir>/channels/`: each `*.ts|.js|.mjs` default-exports a `(ctx) => Routes`
- * factory ({@link ChannelModule}), called here with the mount context; the returned route maps are
- * merged (first file wins a route-key clash, the dropped route surfaced).
- *
- * A channel file broken for ANY reason — a failed import, a factory that throws when called (a missing
- * env var is the common deploy case), or a malformed shape (not a function, not a Routes object, a bad
- * handler/route key) — is collected in `failures` without preventing validation of sibling files. The
- * serving CLI treats any such failure as fatal: a declared channel must not silently disappear or cause
- * the default `/invoke` route to mount. Programmatic callers can inspect the returned data themselves.
- * Routes are validated fully before any merge, so a throw mounts no partial routes.
+ * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
+ * WITHOUT importing. A symlinked channels directory must remain inside the workspace.
  */
+export declare function discoverChannelFiles(dir: string): Promise<string[]>;
+/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
 export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<{
     routes: Routes;
+    longConnections: LoadedLongConnectionChannel[];
+    routeChannels: string[];
+    longConnectionChannels: string[];
     collisions: ChannelCollision[];
     failures: ModuleLoadFailure[];
 }>;

package/dist/engines/pi/channel.js

@@ -1,19 +1,55 @@
 /**
- * Channel discovery (the N axis, filesystem form): a workspace declares its inbound surface by
- * dropping files in `channels/`, mirroring `tools/`. Each file wires a third-party adapter to the
- * app's `on()` glue and returns the routes it mounts. There is no config-level channel list — a
- * channel always needs glue, so it is always a file.
+ * Channel discovery (the N axis, filesystem form). A channel file default-exports either the existing
+ * route factory `(ctx) => Routes`, or an explicit long-connection module `{ name, connect(ctx, signal) }`.
  */
 import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { parseRouteKey } from "../../host/node.js";
-import { assertInsideWorkspace } from "../../workspace.js";
+import { parseRouteKey, } from "../../host/node.js";
 import { isModuleFile, loadModuleDir } from "../../loader.js";
+import { assertInsideWorkspace } from "../../workspace.js";
+function longConnectionModule(value) {
+    return value !== null && typeof value === "object" && typeof value.connect === "function";
+}
+function validateLongConnectionModule(value, label) {
+    if (typeof value.name !== "string" || value.name.trim() === "") {
+        throw new Error(`${label}: long-connection channel name must be a non-empty string`);
+    }
+}
+/**
+ * Import channel files without mounting route factories or opening connections. Deployment needs only
+ * the authored structural fact: function exports are route channels; `{ connect() }` exports are
+ * long-connection channels. There is no second ingress/lifecycle declaration to keep in sync.
+ */
+export async function inspectChannels(dir) {
+    await assertInsideWorkspace(dir, "channels");
+    const { modules, failures } = await loadModuleDir(join(dir, "channels"));
+    const channels = [];
+    const routeChannels = [];
+    const longConnectionChannels = [];
+    for (const { name, label, file, mod } of modules) {
+        try {
+            if (typeof mod.default === "function") {
+                channels.push(name);
+                routeChannels.push(name);
+                continue;
+            }
+            if (longConnectionModule(mod.default)) {
+                validateLongConnectionModule(mod.default, label);
+                channels.push(name);
+                longConnectionChannels.push(name);
+                continue;
+            }
+            throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
+        }
+        catch (error) {
+            failures.push({ label, file, message: error.message });
+        }
+    }
+    return { channels, routeChannels, longConnectionChannels, failures };
+}
 /**
  * Channel file basenames under `<dir>/channels/` — the authoring view (`fastagent info`), which lists
- * WITHOUT importing, unlike {@link loadChannels}. It enforces the SAME containment guard so info reports
- * exactly the surface dev/start would accept: a channels/ symlink escaping the workspace is rejected
- * here too. This path is independent of loadChannels', so it must guard the boundary on its own.
+ * WITHOUT importing. A symlinked channels directory must remain inside the workspace.
  */
 export async function discoverChannelFiles(dir) {
     await assertInsideWorkspace(dir, "channels");
@@ -28,75 +64,68 @@ export async function discoverChannelFiles(dir) {
     }
     return names
         .filter(isModuleFile)
-        .map((n) => n.replace(/\.(ts|js|mjs)$/, ""))
+        .map((name) => name.replace(/\.(ts|js|mjs)$/, ""))
         .sort();
 }
-/**
- * Discover channels in `<dir>/channels/`: each `*.ts|.js|.mjs` default-exports a `(ctx) => Routes`
- * factory ({@link ChannelModule}), called here with the mount context; the returned route maps are
- * merged (first file wins a route-key clash, the dropped route surfaced).
- *
- * A channel file broken for ANY reason — a failed import, a factory that throws when called (a missing
- * env var is the common deploy case), or a malformed shape (not a function, not a Routes object, a bad
- * handler/route key) — is collected in `failures` without preventing validation of sibling files. The
- * serving CLI treats any such failure as fatal: a declared channel must not silently disappear or cause
- * the default `/invoke` route to mount. Programmatic callers can inspect the returned data themselves.
- * Routes are validated fully before any merge, so a throw mounts no partial routes.
- */
+function validateRoutes(value, label) {
+    if (value === null || typeof value !== "object" || value instanceof Map) {
+        throw new Error(`${label} must return a Routes object`);
+    }
+    const routes = Object.entries(value);
+    if (routes.length === 0) {
+        throw new Error(`${label} declared no routes — return a non-empty { "METHOD /path": handler } object`);
+    }
+    for (const [route, handler] of routes) {
+        if (typeof handler !== "function") {
+            throw new Error(`${label}: route "${route}" must map to a handler function, got ${typeof handler}`);
+        }
+        if (!parseRouteKey(route).path.startsWith("/")) {
+            throw new Error(`${label}: route "${route}" is not a valid route key (expected "METHOD /path" or "/path")`);
+        }
+    }
+    return routes;
+}
+/** Discover, validate, and bind all channel modules. No long connection is opened here; the CLI owns it. */
 export async function loadChannels(dir, ctx) {
-    // The contract says stateRoot is absolute; enforce it at the mount boundary so a relative root fails
-    // fast HERE instead of silently re-anchoring some channel's state on the process cwd.
     if (!isAbsolute(ctx.stateRoot)) {
         throw new Error(`ChannelContext.stateRoot must be absolute, got "${ctx.stateRoot}"`);
     }
-    // A symlinked channels/ is followed only if it stays inside the workspace, so a deploy that copies
-    // the dir includes it (the directory is the agent).
     await assertInsideWorkspace(dir, "channels");
     const { modules, failures } = await loadModuleDir(join(dir, "channels"));
     const routes = {};
+    const longConnections = [];
+    const routeChannels = [];
+    const longConnectionChannels = [];
     const collisions = [];
-    for (const { label, file, mod } of modules) {
-        // Collect every per-file failure so the caller can report all broken channels in one pass. The CLI
-        // then fails startup rather than silently dropping a declared route; direct callers own their policy.
-        // Routes are VALIDATED fully before any are merged, so a throw mid-validation mounts NO partial routes.
+    for (const { name, label, file, mod } of modules) {
         try {
-            const factory = mod.default;
-            if (typeof factory !== "function") {
-                throw new Error(`${label} must default-export (ctx) => Routes`);
+            if (longConnectionModule(mod.default)) {
+                validateLongConnectionModule(mod.default, label);
+                const channel = mod.default;
+                longConnections.push({
+                    name: channel.name,
+                    connect: (signal) => channel.connect(ctx, signal),
+                });
+                longConnectionChannels.push(name);
+                continue;
+            }
+            if (typeof mod.default !== "function") {
+                throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
             }
-            const declared = factory(ctx);
-            // A Promise needs its own branch before the object check: mark it handled (a rejected async setup
-            // must not go unhandled) and reject it with a precise message rather than the zero-routes one.
+            const declared = mod.default(ctx);
             if (declared !== null &&
                 typeof declared === "object" &&
                 typeof declared.then === "function") {
                 declared.catch(() => { });
-                throw new Error(`${label} must return Routes synchronously, not a Promise (an async factory is not supported)`);
-            }
-            if (declared === null || typeof declared !== "object") {
-                throw new Error(`${label} must return a Routes object, got ${declared === null ? "null" : typeof declared}`);
-            }
-            const declaredRoutes = Object.entries(declared);
-            if (declaredRoutes.length === 0) {
-                throw new Error(`${label} declared no routes — return a non-empty { "METHOD /path": handler } object (a Promise, Map, array, or {} yields none)`);
-            }
-            // Validate every route BEFORE merging any (no partial mount on a later throw).
-            for (const [route, handler] of declaredRoutes) {
-                if (typeof handler !== "function") {
-                    throw new Error(`${label}: route "${route}" must map to a handler function, got ${typeof handler}`);
-                }
-                if (!parseRouteKey(route).path.startsWith("/")) {
-                    throw new Error(`${label}: route "${route}" is not a valid route key (expected "METHOD /path" or "/path")`);
-                }
+                throw new Error(`${label} must return Routes synchronously, not a Promise`);
             }
+            const declaredRoutes = validateRoutes(declared, label);
             for (const [route, handler] of declaredRoutes) {
                 const parsed = parseRouteKey(route);
-                // Overlap, not literal-key, equality: the router treats a bare `/path` as any-method, so
-                // `/webhook` and `POST /webhook` clash. `GET /x` vs `POST /x` is fine.
-                const clash = Object.keys(routes).some((k) => {
-                    const e = parseRouteKey(k);
-                    return (e.path === parsed.path &&
-                        (e.method === undefined || parsed.method === undefined || e.method === parsed.method));
+                const clash = Object.keys(routes).some((key) => {
+                    const existing = parseRouteKey(key);
+                    return (existing.path === parsed.path &&
+                        (existing.method === undefined || parsed.method === undefined || existing.method === parsed.method));
                 });
                 if (clash) {
                     collisions.push({ route, source: label });
@@ -104,10 +133,11 @@ export async function loadChannels(dir, ctx) {
                 }
                 routes[route] = handler;
             }
+            routeChannels.push(name);
         }
         catch (error) {
             failures.push({ label, file, message: error.message });
         }
     }
-    return { routes, collisions, failures };
+    return { routes, longConnections, routeChannels, longConnectionChannels, collisions, failures };
 }

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

@@ -1,19 +1,7 @@
-import { type AgentSessionRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
-export interface RunPiChatOptions {
-    /** Model spec override (the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
-    model?: string;
-}
-/**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
- * skills resolved exactly as the dev opener does). Split from {@link runPiChat} so the assembly —
- * the fidelity-critical part — is inspectable without launching the TUI.
- */
-export declare function buildChatRuntime(dir: string, options?: RunPiChatOptions, 
-/** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
-sessionManager?: SessionManager): Promise<AgentSessionRuntime>;
+import { type BuildSessionRuntimeOptions } from "./session-builder.ts";
 /**
  * Open the workspace's agent in pi's interactive TUI and run until the user exits. The agent is
- * fastagent's assembled agent (same model/tools/skills/prompt as dev/start serve); pi's TUI handles
- * login, rendering, and same-workspace sessions natively.
+ * fastagent's assembled agent (same model/tools/skills/prompt/auth as dev/start serve); pi's TUI
+ * handles login, rendering, and same-workspace sessions natively.
  */
-export declare function runPiChat(dir: string, options?: RunPiChatOptions): Promise<void>;
+export declare function runPiChat(dir: string, options?: BuildSessionRuntimeOptions): Promise<void>;

package/dist/engines/pi/chat.js

@@ -3,198 +3,18 @@
  * engine-neutral channel: it drives pi's full session API (InteractiveMode) for fidelity, so it lives
  * under engines/pi/ and is not re-exported.
  *
- * FIDELITY: chat must run the SAME agent dev/start serve, not pi's vanilla discovery (which would walk
- * AGENTS.md up to the repo root and discover skills from pi's own global dirs). So fastagent's
- * assembly is INJECTED into pi's session:
- *   - prompt  → systemPromptOverride = base + instructions ONLY; pi appends the skill section and env
- *               (cwd) itself (including it here would duplicate it).
- *   - skills  → skillsOverride (fastagent's skills, for the section + invocation).
- *   - tools   → default coding tools by NAME (pi rebuilds them cwd-bound for rich rendering) +
- *               fastagent's custom tools via pi's customTools path (so they survive /new, /resume, fork).
- *
- * Cross-workspace session switches are rejected: `.env` is process-global, so one chat TUI is one
- * workspace.
- *
- * AUTH: chat is the one command that does NOT use fastagent's credential file. It drives pi's own
- * session services (`createAgentSessionServices`, auth from pi's `~/.pi` via `getAgentDir()`), so you
- * log in through pi's TUI, not `fastagent login`. `--auth-path`/`FASTAGENT_AUTH_PATH` therefore do not
- * apply here, and `createPiModels()` below is used only to RESOLVE the model descriptor (never for auth).
- */
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { InteractiveMode, SessionManager, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
-import { loadConfig, resolveAgentDir, resolveModel, resolveModelSpec } from "./config.js";
-import { assembleSystemPrompt, piBasePrompt, piDefaultTools, resolveTools } from "./create.js";
-import { createPiModels } from "./models.js";
-import { canonicalPath, loadAgentDefinition } from "./definition.js";
-import { loadTools, mergeDiscoveredTools } from "./tool.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
-/**
- * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
- * skills resolved exactly as the dev opener does). Split from {@link runPiChat} so the assembly —
- * the fidelity-critical part — is inspectable without launching the TUI.
- */
-export async function buildChatRuntime(dir, options = {}, 
-/** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
-sessionManager) {
-    async function resolveAssembly(cwd) {
-        const { config } = await loadConfig(cwd);
-        const modelSpec = resolveModelSpec(options.model, config);
-        if (!modelSpec) {
-            throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
-        }
-        // Resolution only — the Models' auth is unused here; chat's auth is pi's own (~/.pi via the session
-        // services), so authPath is intentionally not threaded in. See the AUTH note in the header.
-        const model = resolveModel(createPiModels(), modelSpec);
-        const env = new NodeExecutionEnv({ cwd });
-        // Same agentDir/cwd split as dev/start: persona/skills/tools from agentDir, ② context walked from cwd.
-        const agentDir = resolveAgentDir(cwd, config);
-        const definition = await loadAgentDefinition(agentDir, { cwd, env });
-        reportDefinitionWarnings(definition.collisions, definition.diagnostics);
-        // Same tool resolution as the dev opener, then split: defaults go to pi by NAME (rebuilt cwd-bound
-        // for rich rendering); customs go through pi's `customTools` path so they survive /new, /resume, fork.
-        const discovered = await loadTools(agentDir);
-        const { tools, collisions: crossCollisions } = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-        reportToolCollisions([...discovered.collisions, ...crossCollisions]);
-        reportModuleLoadFailures(discovered.failures);
-        const defaultNames = piDefaultTools(cwd).map((t) => t.name);
-        const customTools = tools.filter((t) => !defaultNames.includes(t.name));
-        // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts it).
-        const customToolDefs = customTools.map((t) => ({
-            name: t.name,
-            label: t.name,
-            description: t.description ?? "",
-            parameters: t.parameters,
-            execute: (id, params, signal) => t.execute(id, params, signal),
-        }));
-        // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
-        // them here would duplicate them).
-        const systemPrompt = assembleSystemPrompt({
-            base: piBasePrompt({ tools, persona: definition.persona }),
-            contextFiles: definition.contextFiles,
-        });
-        return { model, definition, defaultNames, customTools, customToolDefs, systemPrompt };
-    }
-    // pi calls the factory again on /new, /resume, switch, and fork. Config/tools dynamic imports are
-    // ESM-cached, so treating same-cwd rebuilds as hot reload would yield a half-fresh agent (fresh
-    // AGENTS.md/skills, stale config/tools). Keep chat a coherent startup snapshot: restart to load
-    // edits. And keep it workspace-scoped — `.env` is process-global, so a switch to another cwd would
-    // leak env or require mutating global env at runtime.
-    const rootCwd = canonicalPath(dir);
-    let assembly;
-    const assemblyFor = (cwd) => {
-        // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would
-        // otherwise mismatch a non-realpath rootCwd.
-        const activeCwd = canonicalPath(cwd);
-        if (activeCwd !== rootCwd) {
-            throw workspaceScopeError(activeCwd);
-        }
-        assembly ??= resolveAssembly(rootCwd);
-        return assembly;
-    };
-    const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
-        const { model, definition, defaultNames, customTools, customToolDefs, systemPrompt } = await assemblyFor(cwd);
-        const services = await createAgentSessionServices({
-            cwd,
-            resourceLoaderOptions: {
-                // Definition-only, like dev/start: suppress pi's machine-global discovery (the developer's own
-                // ~/.pi extensions, slash commands, global AGENTS.md, APPEND_SYSTEM.md) so chat runs the same
-                // agent that gets served, not the authoring machine's pi setup on top.
-                noExtensions: true,
-                noPromptTemplates: true,
-                noContextFiles: true,
-                systemPromptOverride: () => systemPrompt,
-                appendSystemPromptOverride: () => [],
-                // Replace pi's discovered skills with fastagent's. fastagent's Skill (content inline) is
-                // reshaped to pi-coding-agent's (read from filePath/baseDir at invocation time).
-                skillsOverride: (base) => ({
-                    skills: definition.skills.map((s) => ({
-                        name: s.name,
-                        description: s.description,
-                        filePath: s.filePath,
-                        baseDir: dirname(s.filePath),
-                        sourceInfo: {
-                            path: s.filePath,
-                            source: "fastagent",
-                            scope: "project",
-                            origin: "top-level",
-                            baseDir: dirname(s.filePath),
-                        },
-                        disableModelInvocation: s.disableModelInvocation ?? false,
-                    })),
-                    diagnostics: base.diagnostics,
-                }),
-            },
-        });
-        const result = await createAgentSessionFromServices({
-            services,
-            sessionManager,
-            sessionStartEvent,
-            model,
-            tools: [...defaultNames, ...customTools.map((t) => t.name)],
-            customTools: customToolDefs,
-        });
-        return { ...result, services, diagnostics: services.diagnostics };
-    };
-    const runtime = await createAgentSessionRuntime(createRuntime, {
-        cwd: rootCwd,
-        agentDir: getAgentDir(),
-        sessionManager: sessionManager ?? SessionManager.create(rootCwd),
-    });
-    enforceWorkspaceScopedSessionSwitches(runtime, rootCwd);
-    return runtime;
-}
-function workspaceScopeError(targetCwd) {
-    return new Error(`fastagent chat is workspace-scoped: cannot switch to ${targetCwd}; run \`fastagent chat ${targetCwd}\` instead`);
-}
-function readSessionHeaderCwd(sessionPath) {
-    const resolvedPath = resolve(sessionPath);
-    if (!existsSync(resolvedPath))
-        return undefined;
-    for (const line of readFileSync(resolvedPath, "utf8").split(/\r?\n/)) {
-        if (!line.trim())
-            continue;
-        try {
-            const entry = JSON.parse(line);
-            if (entry.type === "session")
-                return typeof entry.cwd === "string" ? canonicalPath(entry.cwd) : undefined;
-        }
-        catch {
-            // Ignore malformed lines the same way pi's session loader does; no header cwd → caller pins root.
-        }
-    }
-    return undefined;
-}
-/**
- * Keep resume/import inside the chat's single workspace, deciding BEFORE delegating to pi. The chat
- * process is chdir'd into rootCwd, so a session with no cwd header already lands on rootCwd. The gap
- * is a session that EXPLICITLY records a different cwd: pi would bind it and the factory would reject
- * it — but only AFTER tearing the live session down. Reject such a switch up front.
+ * The TUI is ONE consumer of the shared definition-aware builder (session-builder.ts) — the same
+ * assembly, model surface, and fastagent auth that serving uses. Log in with `fastagent login` (or
+ * pi's TUI `/login`, which writes through the same credential store into the workspace auth file).
  */
-function enforceWorkspaceScopedSessionSwitches(runtime, rootCwd) {
-    const rejectForeignTarget = (sessionPath, cwdOverride) => {
-        const target = cwdOverride !== undefined ? canonicalPath(cwdOverride) : readSessionHeaderCwd(sessionPath);
-        if (target !== undefined && target !== rootCwd)
-            throw workspaceScopeError(target);
-    };
-    const switchSession = runtime.switchSession.bind(runtime);
-    runtime.switchSession = async (...args) => {
-        rejectForeignTarget(args[0], args[1]?.cwdOverride);
-        return switchSession(...args);
-    };
-    const importFromJsonl = runtime.importFromJsonl.bind(runtime);
-    runtime.importFromJsonl = async (...args) => {
-        rejectForeignTarget(args[0], args[1]);
-        return importFromJsonl(...args);
-    };
-}
+import { InteractiveMode } from "@earendil-works/pi-coding-agent";
+import { buildWorkspaceSessionRuntime } from "./session-builder.js";
 /**
  * Open the workspace's agent in pi's interactive TUI and run until the user exits. The agent is
- * fastagent's assembled agent (same model/tools/skills/prompt as dev/start serve); pi's TUI handles
- * login, rendering, and same-workspace sessions natively.
+ * fastagent's assembled agent (same model/tools/skills/prompt/auth as dev/start serve); pi's TUI
+ * handles login, rendering, and same-workspace sessions natively.
  */
 export async function runPiChat(dir, options = {}) {
-    const runtime = await buildChatRuntime(dir, options);
+    const runtime = await buildWorkspaceSessionRuntime(dir, options);
     await new InteractiveMode(runtime, {}).run();
 }

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

@@ -1,9 +1,14 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import type { AnyModel } from "./harness.ts";
+import { type AnyModel } from "./harness.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
+    /** Reasoning effort for the model, pi's scale ("off" | "minimal" | "low" | "medium" | "high" |
+     *  "xhigh" | "max"). Unset = pi's default. Authors tune thinking in the pi TUI while vibing — this
+     *  is the serving-side counterpart (fidelity). Levels a model doesn't support are clamped by pi. */
+    thinkingLevel?: ThinkingLevel;
     /**
      * The agent-definition subdirectory (persona.md, skills/, tools/, channels/), relative to the config
      * file's directory. Default: the config directory itself (flat — today's behaviour). Point it at a
@@ -12,8 +17,9 @@ export interface FastagentConfig {
      * subdir and does not collide with the host's `tools/`/`src/` (core.md scenario grid).
      */
     agentDir?: string;
-    /** Extra custom tools, appended after pi defaults — never replaces them. */
-    tools?: AgentTool[];
+    /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
+     *  plus the optional `deferred` marker (see defineTool). */
+    tools?: FastagentTool[];
     http?: {
         port?: number;
     };
@@ -21,6 +27,15 @@ export interface FastagentConfig {
      *  Off by default — self-scheduling is an autonomy capability, opt in when you want it. Only takes
      *  effect on the serving path (`dev`/`start`, where the scheduler poller honors a wake-up). */
     selfSchedule?: boolean;
+    /**
+     * Serve the session control plane over HTTP (`/control/*`: state/entries/events + dispatch —
+     * steer/abort/compact/set_model…) for remote consumers: a Web panel, a desktop app, `fastagent
+     * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
+     * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
+     * binds all interfaces, so the routes are LAN-reachable with the token as the only protection —
+     * firewall the port, or wrap it for real exposure (design §14).
+     */
+    sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a
      *  Dockerfile / hand-set variables. */
     deploy?: {
@@ -56,6 +71,10 @@ export declare function loadConfig(dir: string): Promise<LoadedConfig>;
  * already validated that agentDir stays under `dir`.
  */
 export declare function resolveAgentDir(dir: string, config: FastagentConfig): string;
+/** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
+ *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
+ *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
+export declare function providerOf(spec: string): string;
 /** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
@@ -84,11 +103,6 @@ export declare function resolveSessionsDirOverride(flag: string | undefined, env
  * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
  */
 export declare function resolveAuthPathOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
- * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
- */
-export declare function projectStateDir(dir: string): string;
 /**
  * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
  * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels