@fastagent-sh/fastagent 0.12.0

package/dist/engines/pi/auth.js

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ *
+ * 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
+ * startup instead of being masked by a machine-global one that won't exist on a fresh deploy box. A
+ * *fallback* specifically is refused because the only safe shape (read global, write the rotated token
+ * back to the project file) would diverge: OAuth refresh tokens are single-use, so consuming global's
+ * token and persisting the new one elsewhere leaves global stale for every other consumer.
+ *
+ * Sharing is still SAFE the right way: point everything at ONE file (`FASTAGENT_AUTH_PATH` → the
+ * global path). One file means one refresh lifecycle under `FileAuthStorageBackend`'s cross-process
+ * lock (refresh re-reads the latest token under the lock) — the documented same-machine pattern.
+ * fastagent's store stays SEPARATE from the pi CLI's `~/.pi/agent/auth.json` for the same single-
+ * lifecycle reason: two uncoordinated files over one grant would each rotate and break the other.
+ *
+ * Persistence + locking reuse pi's `FileAuthStorageBackend` (a cross-process file lock) on the WRITE
+ * path only. `read` is pi-ai's per-request hot path, so it stays UNLOCKED; the backend's in-place
+ * write opens only a sub-millisecond torn-read window, which `read` absorbs by re-reading. The write
+ * path refuses to overwrite a corrupt file (never clobbering other providers' credentials).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log } from "../../log.js";
+import { setTimeout as sleep } from "node:timers/promises";
+import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
+/**
+ * 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.
+ */
+export const GLOBAL_AUTH_PATH = join(homedir(), ".fastagent", "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];
+    return cred && (cred.type === "oauth" || cred.type === "api_key") ? cred : undefined;
+}
+/**
+ * Parse the credentials JSON for a WRITE: a corrupt file must THROW — serializing `{}` over it would
+ * wipe every other provider's credentials. The throw aborts the locked write, leaving the file intact.
+ */
+function parseForWrite(raw, where) {
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`refusing to overwrite corrupt auth file ${where} — fix or remove it`);
+    }
+}
+/** 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`). */
+export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
+    const warn = options.warn ?? ((message) => log.warn(message));
+    const backend = new FileAuthStorageBackend(authPath);
+    return {
+        async read(providerId) {
+            // UNLOCKED hot path: the only race is a sub-millisecond in-place write during an OAuth rotation,
+            // which can yield an empty/partial file. Re-read a few times before concluding it is corrupt;
+            // a valid `{}` (provider absent) returns immediately, so a not-configured read costs nothing.
+            for (let attempt = 0; attempt < 3; attempt++) {
+                let raw;
+                try {
+                    raw = readFileSync(authPath, "utf8");
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        return undefined; // missing/deleted
+                    warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
+                    return undefined;
+                }
+                if (raw !== "") {
+                    try {
+                        return pick(JSON.parse(raw), providerId);
+                    }
+                    catch {
+                        // A partial read mid-write parses as garbage — fall through and retry.
+                    }
+                }
+                if (attempt < 2)
+                    await sleep(2);
+            }
+            warn(`[fastagent] corrupt auth file ${authPath} — fix or remove it`);
+            return undefined;
+        },
+        modify(providerId, fn) {
+            return backend.withLockAsync(async (current) => {
+                const creds = parseForWrite(current, authPath); // corrupt → throw → no clobber
+                const next = await fn(pick(creds, providerId));
+                if (next === undefined)
+                    return { result: pick(creds, providerId) }; // unchanged: no write
+                creds[providerId] = next;
+                return { result: next, next: `${JSON.stringify(creds, null, 2)}\n` };
+            });
+        },
+        async delete(providerId) {
+            // No-op when nothing is stored: do NOT take the lock (which would create the file via the
+            // backend's ensureFileExists) on a machine that never stored this provider.
+            if (!existsSync(authPath))
+                return;
+            await backend.withLockAsync(async (current) => {
+                const creds = parseForWrite(current, authPath);
+                if (!(providerId in creds))
+                    return { result: undefined }; // absent: no write
+                delete creds[providerId];
+                return { result: undefined, next: `${JSON.stringify(creds, null, 2)}\n` };
+            });
+        },
+    };
+}

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

@@ -0,0 +1,31 @@
+import { type ChannelContext, 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;
+}
+/**
+ * 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.
+ */
+export declare function discoverChannelFiles(dir: string): Promise<string[]>;
+/**
+ * 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.
+ */
+export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<{
+    routes: Routes;
+    collisions: ChannelCollision[];
+    failures: ModuleLoadFailure[];
+}>;

package/dist/engines/pi/channel.js

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+import { readdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { parseRouteKey } from "../../host/node.js";
+import { assertInsideWorkspace } from "../../workspace.js";
+import { isModuleFile, loadModuleDir } from "../../loader.js";
+/**
+ * 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.
+ */
+export async function discoverChannelFiles(dir) {
+    await assertInsideWorkspace(dir, "channels");
+    let names;
+    try {
+        names = await readdir(join(dir, "channels"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return names
+        .filter(isModuleFile)
+        .map((n) => n.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.
+ */
+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 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.
+        try {
+            const factory = mod.default;
+            if (typeof factory !== "function") {
+                throw new Error(`${label} must default-export (ctx) => Routes`);
+            }
+            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 (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")`);
+                }
+            }
+            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));
+                });
+                if (clash) {
+                    collisions.push({ route, source: label });
+                    continue;
+                }
+                routes[route] = handler;
+            }
+        }
+        catch (error) {
+            failures.push({ label, file, message: error.message });
+        }
+    }
+    return { routes, collisions, failures };
+}

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

@@ -0,0 +1,19 @@
+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>;
+/**
+ * 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.
+ */
+export declare function runPiChat(dir: string, options?: RunPiChatOptions): Promise<void>;

package/dist/engines/pi/chat.js

@@ -0,0 +1,200 @@
+/**
+ * Chat: open a workspace into pi's interactive TUI (`fastagent chat`). A pi-specific COMMAND, not an
+ * 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
+ *               (date/cwd) itself (including them here would duplicate both).
+ *   - 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 (date/cwd) itself (including
+        // them here would duplicate both).
+        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.
+ */
+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);
+    };
+}
+/**
+ * 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.
+ */
+export async function runPiChat(dir, options = {}) {
+    const runtime = await buildChatRuntime(dir, options);
+    await new InteractiveMode(runtime, {}).run();
+}

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

@@ -0,0 +1,110 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { Models } from "@earendil-works/pi-ai";
+import type { AnyModel } from "./harness.ts";
+export interface FastagentConfig {
+    /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
+    model?: string;
+    /**
+     * 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
+     * sibling like `"./agent"` to serve an existing repo as a coding agent: the config dir stays the run
+     * root (cwd, whose AGENTS.md the agent reads as ② context), while the agent's own surface lives in the
+     * 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[];
+    http?: {
+        port?: number;
+    };
+    /** Mount the built-in `wake` tool so the agent can schedule its OWN follow-up turns (self-scheduling).
+     *  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;
+    /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a
+     *  Dockerfile / hand-set variables. */
+    deploy?: {
+        /** Extra secret env-var NAMES the deployed agent needs beyond the model key + channel secrets — e.g.
+         *  a `GH_TOKEN` its tools use. `deploy` carries each from the LOCAL env to the host secret store and
+         *  lists them in the runbook; a missing value gates `--run` (like a channel secret). */
+        secrets?: string[];
+        /** Extra apt packages baked into the generated image (Debian default repos: git, ripgrep, jq…). For a
+         *  package needing a custom apt repo (e.g. gh) or a different base image, provide your own Dockerfile
+         *  — `deploy` keeps an existing one. */
+        apt?: string[];
+    };
+}
+/** Identity function for typing and IDE completion (vite/next-style). */
+export declare function defineConfig(config: FastagentConfig): FastagentConfig;
+export interface LoadedConfig {
+    config: FastagentConfig;
+    /** Config file path; undefined when running zero-config. */
+    path?: string;
+}
+/** A valid bindable port. */
+export declare function isValidPort(n: number): boolean;
+/** The config filenames that make a directory a fastagent workspace, in load precedence. ONE source: the
+ *  loader (below) and `scaffoldWorkspace`'s already-a-workspace refusal both read this, so "is there a
+ *  config?" can't diverge between them when the set changes. */
+export declare const WORKSPACE_CONFIG_NAMES: readonly ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = zero-config; a wrong-shape file throws. */
+export declare function loadConfig(dir: string): Promise<LoadedConfig>;
+/**
+ * The agent-definition dir from config: `config.agentDir` resolved against `dir`, or `dir` itself when
+ * unset (flat). The ONE place this is computed — every opener (`dev`/`start`/`info`/`tool`/`deploy`/`chat`)
+ * calls it, so the "relative to the config dir, default `.`" rule can never diverge. loadConfig has
+ * already validated that agentDir stays under `dir`.
+ */
+export declare function resolveAgentDir(dir: string, config: FastagentConfig): 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`. */
+export declare function listModels(models: Models): string[];
+/**
+ * Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back.
+ * Handles the scaffold's commented placeholder (`// model: "…"`) and an existing `model:` line; returns
+ * null when neither is present (zero-config or a hand-shaped config) so the caller falls back to a
+ * printed hint instead of guessing where to insert. Text-level (not AST) on purpose — it only ever
+ * touches a line it recognizes, never reformats the author's file.
+ */
+export declare function rewriteConfigModel(src: string, spec: string): string | null;
+/** Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. */
+export declare function resolveModelSpec(flag: string | undefined, config: FastagentConfig, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * `start`'s sessions-dir override: `--sessions-dir` flag > `FASTAGENT_SESSIONS_DIR` env > undefined
+ * (the opener then falls back to {@link defaultSessionsDir} under the {@link resolveStateRoot} root).
+ * Resolved to absolute so the store and the startup report agree regardless of cwd.
+ */
+export declare function resolveSessionsDirOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
+ * falls back to {@link defaultAuthPath} under the {@link resolveStateRoot} root). Resolved to absolute
+ * so the store and the startup report agree regardless of cwd. No implicit project↔global fallback (isolation
+ * + fail-visibly; see auth.ts); to share one account across projects, point this at the global
+ * `~/.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
+ * and the startup report agree regardless of cwd. Definition: single lifecycle (precious, survives
+ * redeploy), single process — a container mounts ONE volume here. The finer knobs
+ * (`FASTAGENT_SESSIONS_DIR`, `FASTAGENT_AUTH_PATH`) still override their specific path on top.
+ *
+ * `FASTAGENT_STATE_DIR` is an OPERATOR override, so a relative value resolves against `process.cwd()`
+ * — the CLI convention its sibling knobs share (`resolveOverridePath`), NOT against `dir`. Only the
+ * DEFAULT (`<dir>/.fastagent`) is dir-anchored. Deployments set an absolute path (a mounted volume);
+ * a relative value is in-tree — hence self-ignored — only when run from the definition dir (cwd == dir).
+ */
+export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
+/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
+export declare function defaultAuthPath(stateRoot: string): string;
+/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+export declare function resolveAuthPath(dir: string, flag: string | undefined, env?: NodeJS.ProcessEnv): string;
+/** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
+export declare function defaultSessionsDir(stateRoot: string): string;