@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/engines/pi/auth.js

@@ -1,8 +1,8 @@
 /**
  * Auth for the pi engine: a read-WRITE {@link CredentialStore} over a fastagent credentials file,
  * consumed by the `Models` collection (models.ts). The path is project-level by default
- * (`<dir>/.fastagent/auth.json`, resolved by the opener); {@link GLOBAL_AUTH_PATH} is the global
- * location used as the override target / login default, not an implicit per-provider fallback.
+ * (`<agentDir>/.secrets/auth.json`, resolved by the opener); {@link GLOBAL_AUTH_PATH} is the
+ * global location used as the override target / login default, not an implicit per-provider fallback.
  *
  * Project-level default + NO implicit project↔global fallback, for two reasons: (1) isolation — each
  * agent can use a different account/subscription; (2) fail-visibly — a missing credential surfaces at
@@ -27,18 +27,20 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { GLOBAL_HOME_DIR, SECRETS_DIRNAME } from "../../paths.js";
 import { log } from "../../log.js";
 import { setTimeout as sleep } from "node:timers/promises";
 import lockfile from "proper-lockfile";
 /**
- * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`). The project-level default is
- * `<dir>/.fastagent/auth.json` (computed by the opener and by `fastagent login`); this is only the
- * `loginFlow()` PROGRAMMATIC fallback (when a caller omits `authPath`) and the path to point
- * `--auth-path`/`FASTAGENT_AUTH_PATH` at to deliberately share ONE credential file across projects
- * (safe — one file, one lock-serialized refresh lifecycle). The `fastagent login` CLI is project-
- * level by default, never this.
+ * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery
+ * home `~/.fastagent/` — which carries the same unified shape as a workspace (`.secrets/auth.json`).
+ * The project-level default is `<agentDir>/.secrets/auth.json` (computed by the opener and by
+ * `fastagent login`); this is only the `loginFlow()` PROGRAMMATIC fallback (when a caller omits
+ * `authPath`) and the path to point `--auth-path`/`FASTAGENT_AUTH_PATH` at to deliberately share ONE
+ * credential file across projects (safe — one file, one lock-serialized refresh lifecycle). The
+ * `fastagent login` CLI is project-level by default, never this.
  */
-export const GLOBAL_AUTH_PATH = join(homedir(), ".fastagent", "auth.json");
+export const GLOBAL_AUTH_PATH = join(homedir(), GLOBAL_HOME_DIR, SECRETS_DIRNAME, "auth.json");
 /** A valid stored credential, or undefined — a foreign/old entry reads as not-configured, not a crash. */
 function pick(creds, providerId) {
     const cred = creds[providerId];
@@ -183,7 +185,7 @@ function parseForWrite(raw, where) {
     return creds;
 }
 /** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
- *  the directory opener passes the project-level `<dir>/.fastagent/auth.json`). */
+ *  the directory opener passes the project-level `<root>/.secrets/auth.json`). */
 export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
     return {

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 agent dir.
  */
+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,22 +1,58 @@
 /**
- * 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 { assertInsideAgentDir } from "../../paths.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 assertInsideAgentDir(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 agent dir.
  */
 export async function discoverChannelFiles(dir) {
-    await assertInsideWorkspace(dir, "channels");
+    await assertInsideAgentDir(dir, "channels");
     let names;
     try {
         names = await readdir(join(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");
+    await assertInsideAgentDir(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;
             }
-            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.
+            if (typeof mod.default !== "function") {
+                throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
+            }
+            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,271 +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 { isDeferredTool, loadTools, mergeDiscoveredTools } from "./tool.js";
-import { withSearchTool } from "./search-tools.js";
-import { additiveActivation, turnContext } from "./tool-context.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) {
-    /** The turn's {@link ToolActivation} over pi's AgentSession — the chat counterpart of invoke.ts's
-     *  harness bridge, so the SAME builtin search_tools serves both paths. Additive; unknown names
-     *  filtered (`setActiveToolsByName` is authoritative on the session and rebuilds its prompt — our
-     *  static override keeps the prompt identical to serving). */
-    function chatToolActivation(session) {
-        // Same serialization as invoke.ts's bridge (there per turn; here per session — chat turns are
-        // interactive, so per-session is equivalent): the read-modify-write below is only race-free while
-        // nothing awaits between read and write, and pi's session setters happening to be synchronous today
-        // is not a contract worth betting parallel tool batches on. Built ONCE per session (createRuntime),
-        // so parallel calls actually share the chain.
-        let chain = Promise.resolve([]);
-        return {
-            active: () => session.getActiveToolNames(),
-            registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
-            activate(names) {
-                const run = async () => {
-                    const current = session.getActiveToolNames();
-                    const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
-                    if (added.length > 0)
-                        session.setActiveToolsByName([...current, ...added]);
-                    return added;
-                };
-                const result = chain.then(run, run); // run after the predecessor settles, success or failure
-                chain = result.catch(() => []); // the caller sees a rejection on `result`; the chain stays usable
-                return result;
-            },
-        };
-    }
-    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 merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-        // Chat EMULATES deferral, like serving (what you iterate is what you serve): the builtin loader
-        // mounts when a deferred tool exists, the initial active set excludes deferred tools (applied on
-        // the session in createRuntime below — pi's TUI session starts all-active), and the activation
-        // bridge below rides the same turn context the serving path uses, so the SAME search_tools works
-        // against pi's AgentSession instead of fastagent's harness.
-        const tools = withSearchTool(merged.tools);
-        const crossCollisions = merged.collisions;
-        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). Each execute runs inside the turn context with the CURRENT session's activation bridge — the
-        // assembly is memoized across /new//resume/fork rebuilds while the session changes, so the bridge
-        // resolves through sessionRef at call time, exactly like the serving path resolves its harness.
-        const customToolDefs = customTools.map((t) => ({
-            name: t.name,
-            label: t.name,
-            description: t.description ?? "",
-            parameters: t.parameters,
-            // Propagate the execution mode — an activating tool (the builtin loader) declares "sequential"
-            // so pi serializes its batch; without this, pi's outer active-set diff double-stamps parallels.
-            executionMode: t.executionMode,
-            execute: (id, params, signal) => {
-                const bound = sessionRef.current;
-                // Unreachable by construction (createRuntime sets sessionRef before any turn can run a tool).
-                // Throw rather than silently run outside the turn context — that would disguise a broken
-                // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
-                if (!bound)
-                    throw new Error("chat tool executed before its session was built (lifecycle invariant broken)");
-                return turnContext.run({ session: bound.session.sessionId, tools: bound.activation }, () => 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);
-    // The CURRENT pi session + its activation bridge, BOUND TOGETHER — rebuilt on /new//resume/fork
-    // while the memoized assembly (and its tool execute closures) stays. The bridge must share the
-    // session's lifetime, NOT be rebuilt per tool call (a per-call chain serializes nothing). Note on
-    // parallel batches: pi wraps SDK customTools in its own before/after active-set diff, so an
-    // activating tool must carry `executionMode: "sequential"` (the builtin loader does) — pi then runs
-    // the whole batch serially and the outer diff sees correct snapshots.
-    const sessionRef = {};
-    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,
-        });
-        sessionRef.current = { session: result.session, activation: chatToolActivation(result.session) };
-        // Deferral emulation: pi's TUI session starts with everything active — narrow it by SUBTRACTING
-        // the deferred names from whatever is active (robust to pi mounting tools of its own; an
-        // exact-set-equality gate would silently stop narrowing the day pi adds one). Applied on EVERY
-        // build including /resume: pi's chat session does not record activations (its SessionContext has
-        // no activeToolNames), so "restore prior activations" is not implementable here — deferral stays
-        // consistently ON and a resumed conversation re-discovers via search_tools (documented divergence
-        // from serving, where activations persist in the session).
-        const deferredNames = customTools.filter(isDeferredTool).map((t) => t.name);
-        if (deferredNames.length > 0) {
-            const active = result.session.getActiveToolNames();
-            if (deferredNames.some((n) => active.includes(n))) {
-                result.session.setActiveToolsByName(active.filter((n) => !deferredNames.includes(n)));
-            }
-        }
-        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 { buildAgentSessionRuntime } 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 buildAgentSessionRuntime(dir, options);
     await new InteractiveMode(runtime, {}).run();
 }