@fastagent-sh/fastagent 0.12.0

package/dist/engines/pi/config.js

@@ -0,0 +1,285 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The config subsystem: schema (defineConfig), loading (loadConfig), and value interpretation
+ * (resolveModel, resolveModelSpec). One concern: everything about fastagent.config.ts.
+ *
+ * Red line: config describes deployment/runtime choices, never authored identity or expertise (those
+ * live in persona.md + skills, with AGENTS.md as project context). Deleting the config still leaves a
+ * zero-config agent runnable with a model supplied by --model / FASTAGENT_MODEL.
+ */
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { moduleLoadHint } from "../../loader.js";
+/** Identity function for typing and IDE completion (vite/next-style). */
+export function defineConfig(config) {
+    return config;
+}
+/** A valid bindable port. */
+export function isValidPort(n) {
+    return Number.isInteger(n) && n >= 0 && n <= 65535;
+}
+/** Validate an optional `string[]` config field where each entry must match `shape` — used for
+ *  deploy.secrets (env-var names) and deploy.apt (package names); undefined is fine (field omitted). */
+function validateStringList(value, key, shape, desc, path) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value))
+        throw new Error(`${path}: "${key}" must be an array of strings`);
+    for (const [i, v] of value.entries()) {
+        if (typeof v !== "string" || !shape.test(v)) {
+            throw new Error(`${path}: "${key}[${i}]" must be ${desc}`);
+        }
+    }
+}
+/** 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 const WORKSPACE_CONFIG_NAMES = ["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 async function loadConfig(dir) {
+    const found = WORKSPACE_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
+    if (found.length === 0)
+        return { config: {} };
+    if (found.length > 1) {
+        throw new Error(`${dir}: multiple fastagent config files found; keep exactly one (${found.map((p) => basename(p)).join(", ")})`);
+    }
+    // biome-ignore lint/style/noNonNullAssertion: length checked above — exactly one element here
+    const path = found[0];
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+    }
+    catch (error) {
+        throw new Error(`${path}: ${error.message}${moduleLoadHint(error)}`);
+    }
+    const config = mod.default;
+    if (!config || typeof config !== "object") {
+        throw new Error(`${path}: must default-export defineConfig({...})`);
+    }
+    const c = config;
+    // Unknown keys throw: defineConfig only type-protects .ts authors; a typo in a .js/.mjs config
+    // (`modle:`) must not silently degrade to zero-config.
+    for (const key of Object.keys(c)) {
+        if (key !== "model" &&
+            key !== "agentDir" &&
+            key !== "tools" &&
+            key !== "http" &&
+            key !== "deploy" &&
+            key !== "selfSchedule") {
+            throw new Error(`${path}: unknown key "${key}" (valid keys: model, agentDir, tools, http, deploy, selfSchedule)`);
+        }
+    }
+    if (c.model !== undefined && typeof c.model !== "string") {
+        throw new Error(`${path}: "model" must be a "provider/modelId" string`);
+    }
+    if (c.agentDir !== undefined && typeof c.agentDir !== "string") {
+        throw new Error(`${path}: "agentDir" must be a string (a subdirectory relative to the config file)`);
+    }
+    if (typeof c.agentDir === "string") {
+        // Enforce the documented "subdirectory of the config dir" contract: an escaping agentDir (e.g.
+        // "../shared") would still resolve for tool/channel/persona discovery, but `dev`'s chokidar only
+        // watches the config dir subtree — edits outside it would silently never trigger a restart. Reject
+        // it here (fail visibly) rather than let hot-reload break without a signal.
+        const rel = relative(dir, resolve(dir, c.agentDir));
+        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+            throw new Error(`${path}: "agentDir" ("${c.agentDir}") must be a subdirectory of the config directory, not escape it`);
+        }
+        // An explicitly declared agentDir that doesn't exist is a typo until proven otherwise ("./agnet"):
+        // without this check every opener would assemble an EMPTY agent (no persona, no skills, no tools)
+        // with zero errors — the worst silent failure this config can produce. Deliberately NOT auto-created:
+        // config load is read-only (no implicit operations), and a mkdir would turn the typo into a served
+        // empty agent plus a junk directory.
+        // lstat, not stat: a symlink would pass the literal containment check above while its TARGET lives
+        // outside the config dir — exactly what that check exists to prevent (dev's watch would silently
+        // never see edits). Same rule as init's parent preflight: reject, don't follow.
+        const agentDirAbs = resolve(dir, c.agentDir);
+        const st = lstatSync(agentDirAbs, { throwIfNoEntry: false });
+        if (!st) {
+            throw new Error(`${path}: "agentDir" ("${c.agentDir}") does not exist — create it, or fix the path`);
+        }
+        if (st.isSymbolicLink()) {
+            // Separate message: to its user a symlink LOOKS like a working directory — name the reason and the fix.
+            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is a symlink — not allowed (its target can live outside the ` +
+                `config directory, where dev's watch would never see edits); use a real directory, or point agentDir at the target's real path`);
+        }
+        if (!st.isDirectory()) {
+            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is not a directory`);
+        }
+        // The leaf lstat can't see a symlinked INTERMEDIATE segment (agentDir "./a/b" with `a` → outside):
+        // realpath equality covers every segment under the config dir in one comparison. dir itself is
+        // realpath'd on both sides, so a symlinked config-dir path (macOS /tmp) stays legal.
+        if (realpathSync(agentDirAbs) !== resolve(realpathSync(dir), relative(dir, agentDirAbs))) {
+            throw new Error(`${path}: "agentDir" ("${c.agentDir}") resolves through a symlink — not allowed (the target can ` +
+                `live outside the config directory, where dev's watch would never see edits); use the real path`);
+        }
+    }
+    if (c.selfSchedule !== undefined && typeof c.selfSchedule !== "boolean") {
+        throw new Error(`${path}: "selfSchedule" must be a boolean`);
+    }
+    if (c.tools !== undefined && !Array.isArray(c.tools)) {
+        throw new Error(`${path}: "tools" must be an array of AgentTool`);
+    }
+    if (c.tools !== undefined) {
+        for (const [i, tool] of c.tools.entries()) {
+            if (!tool || typeof tool !== "object") {
+                throw new Error(`${path}: "tools[${i}]" must be an AgentTool object`);
+            }
+            const candidate = tool;
+            if (typeof candidate.name !== "string" || typeof candidate.execute !== "function") {
+                throw new Error(`${path}: "tools[${i}]" must have string "name" and function "execute"`);
+            }
+        }
+    }
+    if (c.http !== undefined && (typeof c.http !== "object" || c.http === null)) {
+        throw new Error(`${path}: "http" must be an object`);
+    }
+    for (const key of Object.keys(c.http ?? {})) {
+        if (key !== "port") {
+            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port)`);
+        }
+    }
+    if (c.http?.port !== undefined && (typeof c.http.port !== "number" || !isValidPort(c.http.port))) {
+        throw new Error(`${path}: "http.port" must be an integer 0-65535`);
+    }
+    if (c.deploy !== undefined && (typeof c.deploy !== "object" || c.deploy === null)) {
+        throw new Error(`${path}: "deploy" must be an object`);
+    }
+    for (const key of Object.keys(c.deploy ?? {})) {
+        if (key !== "secrets" && key !== "apt") {
+            throw new Error(`${path}: unknown key "deploy.${key}" (valid keys: secrets, apt)`);
+        }
+    }
+    // secrets are UPPER_SNAKE env-var names (deploy reads their VALUES from the local env); apt entries are
+    // Debian package names. Both go into a shell/env context on the host, so shape-validate them — catches a
+    // typo and refuses an injection-shaped value from an otherwise-trusted config.
+    validateStringList(c.deploy?.secrets, "deploy.secrets", /^[A-Z_][A-Z0-9_]*$/, "an UPPER_SNAKE env-var name", path);
+    validateStringList(c.deploy?.apt, "deploy.apt", /^[a-z0-9][a-z0-9.+-]*$/, "a Debian package name", path);
+    return { config: c, path };
+}
+/**
+ * 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 function resolveAgentDir(dir, config) {
+    return resolve(dir, config.agentDir ?? ".");
+}
+/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+export function resolveModel(models, spec) {
+    const slash = spec.indexOf("/");
+    if (slash < 1 || slash === spec.length - 1) {
+        throw new Error(`model must be "provider/modelId" (e.g. "openai-codex/gpt-5.5"), got "${spec}"`);
+    }
+    const provider = spec.slice(0, slash);
+    const modelId = spec.slice(slash + 1);
+    const model = models.getModel(provider, modelId);
+    if (!model) {
+        throw new Error(`unknown model "${spec}" (provider "${provider}" / id "${modelId}" not in registry); run \`fastagent models\` to list available specs`);
+    }
+    return model;
+}
+/** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
+export function listModels(models) {
+    const specs = [];
+    for (const provider of models.getProviders()) {
+        for (const model of provider.getModels())
+            specs.push(`${provider.id}/${model.id}`);
+    }
+    return specs.sort();
+}
+/**
+ * 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 function rewriteConfigModel(src, spec) {
+    const line = `  model: ${JSON.stringify(spec)},`;
+    const commented = /^[ \t]*\/\/[ \t]*model:.*$/m;
+    const active = /^[ \t]*model:[ \t]*["'].*$/m;
+    if (commented.test(src))
+        return src.replace(commented, line);
+    if (active.test(src))
+        return src.replace(active, line);
+    return null;
+}
+/** Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. */
+export function resolveModelSpec(flag, config, env = process.env) {
+    return flag ?? env.FASTAGENT_MODEL ?? config.model;
+}
+/**
+ * Resolve a user-supplied path override (a CLI flag or an env var) to an absolute path, expanding a
+ * leading `~`/`~/` to the home dir FIRST. Path-valued config from `.env` (or any non-shell source)
+ * never gets the shell's `~` expansion, so a bare `resolve("~/x")` would silently create a literal `~`
+ * directory — a fail-silently footgun for a secret/state path. Expanding here makes `~` mean home
+ * everywhere these knobs are read.
+ */
+function resolveOverridePath(raw) {
+    if (!raw)
+        return undefined;
+    const expanded = raw === "~" ? homedir() : raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw;
+    return resolve(expanded);
+}
+/**
+ * `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 function resolveSessionsDirOverride(flag, env = process.env) {
+    return resolveOverridePath(flag ?? env.FASTAGENT_SESSIONS_DIR);
+}
+/**
+ * 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 function resolveAuthPathOverride(flag, env = process.env) {
+    return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
+}
+/**
+ * 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 function projectStateDir(dir) {
+    return join(dir, ".fastagent");
+}
+/**
+ * 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 function resolveStateRoot(dir, env = process.env) {
+    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? resolve(projectStateDir(dir));
+}
+/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
+export function defaultAuthPath(stateRoot) {
+    return join(stateRoot, "auth.json");
+}
+/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+export function resolveAuthPath(dir, flag, env = process.env) {
+    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveStateRoot(dir, env));
+}
+/** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
+export function defaultSessionsDir(stateRoot) {
+    return join(stateRoot, "sessions");
+}

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

@@ -0,0 +1,127 @@
+import type { AgentTool, ExecutionEnv, Skill } from "@earendil-works/pi-agent-core";
+import type { Provider } from "@earendil-works/pi-ai";
+import type { Agent } from "../../agent.ts";
+import { type FastagentConfig } from "./config.ts";
+import { type LoadedDefinition } from "./definition.ts";
+import { type PiSessionStore } from "./sessions.ts";
+import type { ModuleLoadFailure } from "../../loader.ts";
+import { type ToolCollision } from "./tool.ts";
+import { type Lease } from "./invoke.ts";
+/** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
+export declare function piDefaultTools(cwd: string): AgentTool[];
+/** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
+export declare function resolveTools(config: FastagentConfig, cwd: string): AgentTool[];
+/**
+ * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * existing win), plus the non-default tool names and collisions to report. One source for the
+ * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
+ */
+export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
+    tools: AgentTool[];
+    toolNames: string[];
+    toolCollisions: ToolCollision[];
+    toolFailures: ModuleLoadFailure[];
+}>;
+/**
+ * The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two
+ * deviations: the pi-TUI docs section is dropped (those paths don't exist in deployments), and the
+ * tool list is generated from the actually-mounted tools (base and toolset must agree). An authored
+ * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
+ */
+export declare function piBasePrompt(options?: {
+    tools?: AgentTool[];
+    persona?: string;
+}): string;
+export interface AssembleSystemPromptOptions {
+    /**
+     * Base prompt (①), REQUIRED — no default: a defaulted piBasePrompt() would render
+     * "Available tools: (none)" even when tools are mounted. Pass piBasePrompt({ tools }) for pi.
+     */
+    base: string;
+    /** ② project-context files (AGENTS.md et al. from loadProjectContextFiles); each wrapped `<project_instructions path=…>`. */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** ③ Skills for the <available_skills> listing. */
+    skills?: Skill[];
+    /** ④ Env context, caller-provided (keeps this function pure). Omitted = segment omitted. */
+    date?: string;
+    cwd?: string;
+}
+export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
+/** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
+export interface CreatePiAgentOptions {
+    /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
+    model: string;
+    /**
+     * The system prompt itself — verbatim, no engine base and no wrapping (unlike the directory path,
+     * which assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string
+     * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
+     */
+    instructions?: string | (() => string);
+    tools?: AgentTool[];
+    skills?: Skill[];
+    /**
+     * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint /
+     * test fake — selected by the `model` spec's provider id. Built-ins cover the rest; static keys
+     * still come from the {@link authPath} credentials file (fastagent login) or env, not from here.
+     */
+    providers?: Provider[];
+    /**
+     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/auth.json`; the
+     * directory opener passes the project-level `<dir>/.fastagent/auth.json` instead. Env vars are still
+     * consulted when a provider is absent from the file (resolution order is upstream-owned).
+     */
+    authPath?: string;
+    /** Session persistence. Defaults to in-memory; inject jsonlSessionStore for restart-surviving continuity. */
+    sessions?: PiSessionStore;
+    /** Harness filesystem/process environment. Defaults to local NodeExecutionEnv (cwd). This is not yet
+     *  a sandbox boundary for pi's cwd-bound coding tools; a sandbox adapter must wire those tools too. */
+    env?: ExecutionEnv;
+    /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
+    lease?: Lease;
+}
+/** L1: assemble from typed parts. */
+export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
+/**
+ * L2 options. `instructions`/`skills` are absent by design — they come from the definition directory
+ * (AGENTS.md + skills/), which is the whole point of L2.
+ */
+export interface CreatePiAgentFromDefinitionOptions {
+    /** Model spec "provider/modelId", resolved against {@link models}. */
+    model: string;
+    /** Override the engine base prompt (segment ①). Defaults to piBasePrompt({ tools, persona }) using the
+     *  live-read persona.md; pass base to fully opt out of persona.md. */
+    base?: string;
+    /** Override tools. Defaults to piDefaultTools (lock down with a custom list). */
+    tools?: AgentTool[];
+    /**
+     * The agent's working directory: where the default tools operate AND whose ancestors are walked for
+     * ② project context (AGENTS.md). Defaults to `dir` (flat: the definition dir is also the run root).
+     * Set it to the enclosing repo so a coding agent whose definition lives in `dir` operates on — and
+     * reads the AGENTS.md of — that repo (core.md scenario grid).
+     */
+    cwd?: string;
+    /** Extra providers registered on top of the built-ins (your own gateway / self-hosted endpoint). */
+    providers?: Provider[];
+    /**
+     * Credentials file (see {@link CreatePiAgentOptions.authPath}). Being dir-aware, this rung defaults
+     * to the PROJECT-level `<dir>/.fastagent/auth.json` (matching `fastagent dev`/`start` on the same
+     * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
+     */
+    authPath?: string;
+    sessions?: PiSessionStore;
+    /** Harness environment; see {@link CreatePiAgentOptions.env}. The default coding tools and project-
+     *  context loader remain local today, so injecting this alone does not sandbox a directory agent. */
+    env?: ExecutionEnv;
+    lease?: Lease;
+}
+/**
+ * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
+ * call. Returns the definition so callers can surface diagnostics/collisions.
+ */
+export declare function createPiAgentFromDefinition(dir: string, options: CreatePiAgentFromDefinitionOptions): Promise<{
+    agent: Agent;
+    definition: LoadedDefinition;
+}>;

package/dist/engines/pi/create.js

@@ -0,0 +1,222 @@
+/**
+ * Agent assembly (configuration-time): the engine assets (tools, prompt) plus the reusable ladder
+ * that puts a pi agent together.
+ *
+ *   L2  createPiAgentFromDefinition(dir, options)   — load a definition directory, assemble, then L1.
+ *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
+ *   L0  createPiAgentFromHarness({ harnessFactory }) — in invoke.ts (its body is the turn mechanism).
+ *
+ * Above L2 sits the workspace opener createPiAgentFromWorkspace (workspace.ts), which both `dev` and
+ * `start` drive. Each rung calls the one below; options narrow as you go up (L2 owns systemPrompt/skills —
+ * they come from the definition; the openers own model/tools — from config resolution).
+ */
+import { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
+import { createCodingTools } from "@earendil-works/pi-coding-agent";
+import { defaultAuthPath, resolveModel, resolveStateRoot } from "./config.js";
+import { loadAgentDefinition } from "./definition.js";
+import { piHarnessFactory } from "./harness.js";
+import { createPiModels } from "./models.js";
+import { reportDefinitionWarnings } from "./report.js";
+import { inMemorySessionStore } from "./sessions.js";
+import { loadTools, mergeDiscoveredTools } from "./tool.js";
+import { createPiAgentFromHarness } from "./invoke.js";
+// ── §1 tools ─────────────────────────────────────────────────────────────────
+//
+// The full pi toolset is the default for fidelity: authors vibe in local pi with it, so serving with
+// fewer tools is behavior drift. Isolation is the K-side ExecutionEnv/sandbox's job, not the tool
+// layer's; locking down for public exposure = passing a restricted `tools` list (a deployment posture).
+/** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
+export function piDefaultTools(cwd) {
+    return createCodingTools(cwd);
+}
+/** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
+export function resolveTools(config, cwd) {
+    const defaults = piDefaultTools(cwd);
+    return config.tools ? [...defaults, ...config.tools] : defaults;
+}
+/**
+ * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * existing win), plus the non-default tool names and collisions to report. One source for the
+ * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
+ */
+export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
+    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the run root the agent operates on);
+    // discovered `tools/` come from `agentDir` (the agent's own surface). They coincide in the flat case.
+    const discovered = await loadTools(agentDir);
+    const { tools, collisions } = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+    const toolCollisions = [...discovered.collisions, ...collisions];
+    const defaultNames = new Set(piDefaultTools(cwd).map((t) => t.name));
+    const toolNames = tools.map((t) => t.name).filter((n) => !defaultNames.has(n));
+    return { tools, toolNames, toolCollisions, toolFailures: discovered.failures };
+}
+// ── §2 prompt: four-segment systemPrompt assembly ───────────────────────────
+//
+//   systemPrompt = ① base (engine asset; a persona.md persona overrides its identity line)
+//                + ② project context (AGENTS.md files via pi's loadProjectContextFiles, <project_context>-wrapped)
+//                + ③ skills listing + ④ env context (date/cwd)
+//
+// AGENTS.md ≠ system prompt. Pure functions: segment ④ inputs (date/cwd) are caller-provided, so the
+// same inputs always produce the same prompt (testable, reproducible).
+/**
+ * The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two
+ * deviations: the pi-TUI docs section is dropped (those paths don't exist in deployments), and the
+ * tool list is generated from the actually-mounted tools (base and toolset must agree). An authored
+ * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
+ */
+export function piBasePrompt(options = {}) {
+    const tools = options.tools ?? [];
+    const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
+    // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
+    // (the standalone×code-repo cell's persona; core.md §11), keeping the tools list + guidelines below.
+    const identity = options.persona?.trim() ||
+        "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
+    return `${identity}
+
+Available tools:
+${toolsList}
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+- Be concise in your responses
+- Show file paths clearly when working with files`;
+}
+export function assembleSystemPrompt(options) {
+    let prompt = options.base;
+    const contextFiles = options.contextFiles ?? [];
+    if (contextFiles.length > 0) {
+        // Mirrors pi's system-prompt.js: one <project_context> block, one <project_instructions path=…> per file.
+        prompt += `\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n`;
+        for (const { path, content } of contextFiles) {
+            prompt += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
+        }
+        prompt += `</project_context>\n`;
+    }
+    if (options.skills && options.skills.length > 0) {
+        prompt += `\n${formatSkillsForSystemPrompt(options.skills)}\n`;
+    }
+    if (options.date)
+        prompt += `\nCurrent date: ${options.date}`;
+    if (options.cwd)
+        prompt += `\nCurrent working directory: ${options.cwd}`;
+    return prompt;
+}
+// ── §3 the reusable assembly ladder: L1 / L2 ────────────────────────────────
+/**
+ * Shared low-level wiring: resolve the model spec against the collection, default the K ports, build
+ * the agent. Internal — the public rungs decide the systemPrompt (L1 from instructions, L2 from the
+ * directory) and route through here.
+ */
+function buildPiAgent(opts) {
+    const models = createPiModels({ providers: opts.providers, authPath: opts.authPath });
+    return createPiAgentFromHarness({
+        lease: opts.lease,
+        harnessFactory: piHarnessFactory({
+            sessions: opts.sessions ?? inMemorySessionStore(),
+            env: opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() }),
+            models,
+            model: resolveModel(models, opts.model),
+            systemPrompt: opts.systemPrompt,
+            tools: opts.tools,
+            skills: opts.skills,
+            live: opts.live,
+        }),
+    });
+}
+/**
+ * L1 system prompt: `instructions` ARE the prompt (no engine base, no wrapping); the skills listing
+ * is appended only when skills are mounted (the model must know what it can invoke). A factory so a
+ * dynamic `instructions` and per-invoke freshness both work; undefined when there is nothing to send.
+ */
+function instructionsPrompt(instructions, skills) {
+    const hasSkills = skills !== undefined && skills.length > 0;
+    if (instructions === undefined && !hasSkills)
+        return undefined;
+    return () => {
+        const prose = typeof instructions === "function" ? instructions() : (instructions ?? "");
+        const listing = hasSkills ? formatSkillsForSystemPrompt(skills) : "";
+        return [prose, listing].filter((s) => s !== "").join("\n");
+    };
+}
+/** L1: assemble from typed parts. */
+export function createPiAgent(options) {
+    return buildPiAgent({
+        model: options.model,
+        providers: options.providers,
+        authPath: options.authPath,
+        systemPrompt: instructionsPrompt(options.instructions, options.skills),
+        tools: options.tools,
+        skills: options.skills,
+        sessions: options.sessions,
+        env: options.env,
+        lease: options.lease,
+    });
+}
+/** Stable identity of a definition's non-fatal findings, for change-detection in `live` (dedup only). */
+function findingsSignature(def) {
+    const collisions = def.collisions.map((c) => `c:${c.name}:${c.winnerPath}:${c.loserPath}`);
+    const diagnostics = def.diagnostics.map((d) => `d:${d.code}:${d.path}`);
+    return [...collisions, ...diagnostics].sort().join("\n");
+}
+/**
+ * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
+ * call. Returns the definition so callers can surface diagnostics/collisions.
+ */
+export async function createPiAgentFromDefinition(dir, options) {
+    // `dir` = the agent-definition dir (persona.md/skills/); `cwd` (default = dir) is the run root where
+    // tools operate and whose ancestors are walked for ② context.
+    const cwd = options.cwd ?? dir;
+    const env = options.env ?? new NodeExecutionEnv({ cwd });
+    // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to
+    // report (skills/diagnostics/collisions). Serving does NOT close over it — see `live` below.
+    const definition = await loadAgentDefinition(dir, { cwd: env.cwd, env });
+    // Findings the caller already reported at boot; `live` re-reports only when the set CHANGES — a
+    // runtime-written bad skill surfaces the moment it appears, while a static finding does not spam
+    // every turn's log. A log-dedup memo, not session state (stateless invoke holds).
+    let reportedFindings = findingsSignature(definition);
+    const tools = options.tools ?? piDefaultTools(env.cwd);
+    const agent = buildPiAgent({
+        model: options.model,
+        providers: options.providers,
+        // Dir-aware default: the same state-root-derived file the opener uses for this dir (the opener
+        // passes an explicit authPath, so this only affects direct L2 callers).
+        authPath: options.authPath ?? defaultAuthPath(resolveStateRoot(dir)),
+        // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
+        // edits (the author's, or the agent's own self-modification) take effect on the next turn with
+        // no process restart — restarts are reserved for code (tools/channels/config, module cache).
+        // One read yields prompt AND skills (they can never diverge), `date` is the turn's date, and the
+        // fs cost is a few reads against a model call. Broken edits stay visible: a throw-class problem
+        // (unreadable AGENTS.md) fails that turn's invoke, and the loader's NON-fatal findings (bad
+        // SKILL.md frontmatter, name collisions — returned as data, not thrown) are warned the moment
+        // the finding set changes (boot findings are the baseline) — a runtime-written bad skill must
+        // not silently vanish from the agent, and a static one must not spam every turn's log. The
+        // next good edit heals both.
+        live: async () => {
+            const def = await loadAgentDefinition(dir, { cwd: env.cwd, env });
+            const sig = findingsSignature(def);
+            if (sig !== reportedFindings) {
+                reportedFindings = sig;
+                reportDefinitionWarnings(def.collisions, def.diagnostics);
+            }
+            return {
+                systemPrompt: assembleSystemPrompt({
+                    // Segment ①: an authored persona (persona.md, def.persona) overrides the engine identity,
+                    // re-read per turn like AGENTS.md so edits go live; options.base still wins for full control.
+                    base: options.base ?? piBasePrompt({ tools, persona: def.persona }),
+                    // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
+                    contextFiles: def.contextFiles,
+                    skills: def.skills,
+                    date: new Date().toISOString().slice(0, 10),
+                    cwd: env.cwd,
+                }),
+                skills: def.skills,
+            };
+        },
+        tools,
+        sessions: options.sessions,
+        env,
+        lease: options.lease,
+    });
+    return { agent, definition };
+}