@fastagent-sh/fastagent 0.24.2 → 0.24.4

package/dist/engines/pi/agent-session-factory.js

@@ -3,20 +3,55 @@
  * durable record, per invoke.
  */
 import { dirname } from "node:path";
-import { BUILTIN_EXTENSIONS, DISCOVERY, readMachine, withMachine } from "./machine.js";
-import { ExtensionRunner, ModelRegistry, SessionManager, createAgentSessionServices, createCodemodeExtension, createToolSearchExtension, createAgentSessionFromServices, getAgentDir, initTheme, } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_EXTENSIONS, DISCOVERY, readMachine, withMachine, } from "./machine.js";
+import { ExtensionRunner, ModelRegistry, SessionManager, createAgentSessionServices, createCodemodeExtension, createToolSearchExtension, createAgentSessionFromServices, createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, getAgentDir, initTheme, } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
 import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
 import { resolveModel } from "./config.js";
-import { activePath, resolveSessionSettings } from "./session-settings.js";
+import { MissingModel, activePath, resolveSessionSettings } from "./session-settings.js";
 import { DEFAULT_THINKING_LEVEL, withModelRegistration } from "./models.js";
 import { registerAccountModels } from "./openai-account-models.js";
-import { asksToEndRun, markEndsRun } from "./turn-kit.js";
+import { abortedAnswer, asksToEndRun, markEndsRun } from "./turn-kit.js";
 import { agentSessionManager, sessionToolActivation, turnContext } from "./tool-context.js";
+/**
+ * What pi's own coding tools say about themselves in its default prompt. The coding tools fastagent mounts are pi's
+ * `AgentTool`s, which carry neither field, and they replace pi's definitions of the same name, so without this pi's
+ * tool list would lose them and its rules would lose their guidelines.
+ */
+const PI_TOOL_PROMPTS = new Map([
+    createReadToolDefinition,
+    createBashToolDefinition,
+    createEditToolDefinition,
+    createWriteToolDefinition,
+    createGrepToolDefinition,
+    createFindToolDefinition,
+    createLsToolDefinition,
+].map((create) => {
+    const definition = create(".");
+    return [
+        definition.name,
+        { promptSnippet: definition.promptSnippet, promptGuidelines: definition.promptGuidelines },
+    ];
+}));
+/**
+ * The line pi's default prompt lists a tool by. pi lists only tools that have one; an authored tool's is the first
+ * line of its description, so `defineTool` needs no field of its own.
+ */
+function promptFields(tool) {
+    const own = tool;
+    const pi = PI_TOOL_PROMPTS.get(tool.name);
+    const promptSnippet = own.promptSnippet ?? pi?.promptSnippet ?? tool.description?.split("\n")[0]?.trim();
+    const promptGuidelines = own.promptGuidelines ?? pi?.promptGuidelines;
+    return {
+        ...(promptSnippet ? { promptSnippet } : {}),
+        ...(promptGuidelines ? { promptGuidelines } : {}),
+    };
+}
 /** fastagent's tools as pi tool definitions, bound to ONE session. */
 function toolDefinitions(tools, bound, sessionId) {
     return tools.map((tool) => ({
         ...tool,
+        ...promptFields(tool),
         label: tool.label || tool.name,
         execute: (id, params, signal, onUpdate, ctx) => {
             const binding = bound.current;
@@ -159,10 +194,34 @@ const nativeExtensions = BUILTIN_EXTENSIONS.map((name) => ({
     replaceable: true,
     builtin: true,
 }));
+/**
+ * FastAgent's own prompt sections, added on `before_agent_start`: pi renders custom sections after its own, so they
+ * survive a `SYSTEM.md` that replaced pi's default, and they stay out of the slot `APPEND_SYSTEM.md` fills.
+ */
+function fastagentSections(sections) {
+    return {
+        name: "fastagent-sections",
+        hidden: true,
+        factory: (pi) => {
+            pi.on("before_agent_start", (event) => {
+                Object.assign(event.systemPromptOptions.sections, sections);
+            });
+        },
+    };
+}
 /** The resource posture a fastagent definition asks pi for — ONE definition of it, for both assemblies. */
 export function definitionResourceLoaderOptions(source) {
+    const { definition } = source;
     return {
-        extensionFactories: [...nativeExtensions, compactAdmission, recordEndsRun],
+        extensionFactories: [
+            ...nativeExtensions,
+            compactAdmission,
+            recordEndsRun,
+            recordAbortedAnswers,
+            ...(definition.sections && Object.keys(definition.sections).length > 0
+                ? [fastagentSections(definition.sections)]
+                : []),
+        ],
         // The machine's extensions are its owner's setup, not this agent's.
         noExtensions: true,
         // Explicit paths survive noExtensions, including Pi's built-ins; so they would also survive the machine's own
@@ -171,13 +230,14 @@ export function definitionResourceLoaderOptions(source) {
             ...source.machine.builtinExtensions.map((name) => `builtin:${name}`),
             ...(source.extensionPaths ?? []),
         ],
-        // Not pi's: fastagent already loads the SAME files into segment ② (`loadProjectContextFiles` in
-        // definition.ts). Leaving both on would put every AGENTS.md in the prompt twice.
+        // Not pi's discovery: the definition read them (definition.ts), and pi renders what it is handed.
         noContextFiles: true,
-        // The IDENTITY is the definition's, whatever the machine thinks. Inheriting skills is inheriting capability;
-        // inheriting a system prompt would be the agent becoming someone else's agent.
-        systemPromptOverride: () => source.systemPrompt() || " ",
-        appendSystemPromptOverride: () => [],
+        agentsFilesOverride: () => ({ agentsFiles: definition.contextFiles ?? [] }),
+        // The IDENTITY is the definition's, whatever the machine thinks: pi's `base` here is the machine's SYSTEM.md, and
+        // it is never used. Inheriting skills is inheriting capability; inheriting a system prompt would be the agent
+        // becoming someone else's agent. Undefined leaves pi to build its default.
+        systemPromptOverride: () => definition.systemPrompt,
+        appendSystemPromptOverride: () => (definition.appendSystemPrompt ? [definition.appendSystemPrompt] : []),
         /**
          * THE DEFINITION'S SKILLS, PLUS THE MACHINE'S — an agent inherits the box it runs on (machine.ts), and the
          * definition wins a name collision.
@@ -187,11 +247,14 @@ export function definitionResourceLoaderOptions(source) {
          */
         noSkills: true,
         skillsOverride: () => ({
-            skills: withMachine(toPiSkills(source.skills()), source.machine.skills),
+            skills: withMachine(toPiSkills(definition.skills), source.machine.skills),
             diagnostics: [],
         }),
         noPromptTemplates: true,
-        promptsOverride: () => ({ prompts: [...source.machine.prompts], diagnostics: [] }),
+        promptsOverride: () => ({
+            prompts: withMachine(toPiPrompts(definition.prompts ?? []), source.machine.prompts),
+            diagnostics: [],
+        }),
     };
 }
 /**
@@ -217,6 +280,23 @@ const recordEndsRun = {
         });
     },
 };
+/**
+ * Records an answer that failed because its run was stopped as aborted ({@link abortedAnswer}), through pi's
+ * `message_end` replacement, which runs before pi appends the message to the record and before the plane's own
+ * listener sees it. `ctx.signal` is the run's own abort signal, the one pi's readings use.
+ */
+const recordAbortedAnswers = {
+    name: "fastagent-record-aborted-answers",
+    hidden: true,
+    factory: (pi) => {
+        pi.on("message_end", (event, ctx) => {
+            if (event.message.role !== "assistant")
+                return;
+            const aborted = abortedAnswer(event.message, ctx.signal);
+            return aborted ? { message: aborted } : undefined;
+        });
+    },
+};
 /** Manual compactions waiting for pi's admission, keyed by the session's record (what an extension's `ctx` names). */
 const compactAdmissions = new WeakMap();
 const COMPACT_ADMISSION = "fastagent-compact-admission";
@@ -293,8 +373,7 @@ export async function definitionServices(options) {
         settingsManager: machine.settingsManager(),
         resourceLoaderOptions: {
             ...definitionResourceLoaderOptions({
-                systemPrompt: () => definition.systemPrompt,
-                skills: () => definition.skills,
+                definition,
                 machine,
                 extensionPaths,
             }),
@@ -341,18 +420,37 @@ export function piAgentSessionFactory(options) {
             initTheme();
             themeReady = true;
         }
+        // Without a default, a turn that cannot run must leave no conversation behind in the listing. A new record with
+        // nothing to inherit records no model, so it is refused before it is created. One that inherits may get a model
+        // from its parent, which only the copy decides (the store's cut), so it is created and, if still model-less,
+        // removed below. The caller holds this session's lease, so nothing else creates the record in between.
+        const existed = options.modelSpec ? true : (await sessions.openIfExists(sessionId)) !== undefined;
+        if (!existed && !inherit)
+            throw new MissingModel(sessionId, []);
         // Publish the record before loading resources: boundary writes must find it while binding is in flight.
         const sessionManager = await sessions.openOrCreate(sessionId, inherit);
         const definition = await options.readDefinition();
         const { modelRuntime } = await options.engine();
         const services = await definitionServices({ cwd, modelRuntime, definition, extensionPaths });
-        const model = resolveModel(modelRuntime, options.modelSpec);
+        const model = options.modelSpec ? resolveModel(modelRuntime, options.modelSpec) : undefined;
         // What the session RUNS on: the boundary plane records model/thinking overrides as entries, and pi does not read
         // them back.
-        const settings = resolveSessionSettings(activePath(sessionManager), modelRuntime, {
-            model,
+        const path = activePath(sessionManager);
+        const settings = resolveSessionSettings(path, modelRuntime, {
+            ...(model ? { model } : {}),
             thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
         });
+        if (!settings) {
+            const missing = new MissingModel(sessionId, path);
+            if (!existed) {
+                // The record this bind created for a thread whose parent supplied no model. A failed removal is reported on
+                // its own and does not replace `missing`: the caller still needs the missing_model answer and its fix.
+                await sessions.delete(sessionId).catch((error) => {
+                    log.warn(`[fastagent] session ${sessionId}: could not remove the record of a refused turn: ${String(error)}`);
+                });
+            }
+            throw missing;
+        }
         const { session } = await bindPiSession({
             services,
             sessionManager,
@@ -402,6 +500,19 @@ export function piAgentSessionFactory(options) {
         return session;
     };
 }
+/** The definition's prompt templates as pi's. */
+function toPiPrompts(prompts) {
+    return prompts.map((prompt) => {
+        const baseDir = dirname(prompt.filePath);
+        return {
+            name: prompt.name,
+            description: prompt.description ?? "",
+            content: prompt.content,
+            filePath: prompt.filePath,
+            sourceInfo: { path: prompt.filePath, source: "fastagent", scope: "project", origin: "top-level", baseDir },
+        };
+    });
+}
 /** fastagent's Skill (content inline) as pi's (read from filePath at invocation time). */
 function toPiSkills(skills) {
     return skills.map((skill) => {

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

@@ -63,3 +63,9 @@ export declare function rewriteConfigModel(src: string, spec: string): string |
  * would refuse to start an agent whose config names a model.
  */
 export declare function resolveModelSpec(flag: string | undefined, config: FastagentConfig, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The refusal of a process that runs the agent here (the CLI's dev/start/invoke/routine run, and chat) when no
+ * default model resolves. The agent itself opens without one; such a process would fail every new conversation, so it
+ * stops at startup instead.
+ */
+export declare function missingDefaultModel(): Error;

package/dist/engines/pi/config.js

@@ -189,3 +189,11 @@ export function rewriteConfigModel(src, spec) {
 export function resolveModelSpec(flag, config, env = process.env) {
     return flag ?? (env.FASTAGENT_MODEL || config.model);
 }
+/**
+ * The refusal of a process that runs the agent here (the CLI's dev/start/invoke/routine run, and chat) when no
+ * default model resolves. The agent itself opens without one; such a process would fail every new conversation, so it
+ * stops at startup instead.
+ */
+export function missingDefaultModel() {
+    return new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
+}

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

@@ -45,29 +45,15 @@ export declare function resolveAgentTools(config: FastagentConfig, agentDir: str
      *  asserts it (open.ts) — this function must stay reportable. */
     toolSecrets: Map<string, DeclaredSecret[]>;
 }>;
-/** The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two deviations. */
-export declare function piBasePrompt(options?: {
-    tools?: MountedTool[];
-    persona?: string;
-    /** The {@link BUILTIN_EXTENSIONS} this machine leaves enabled (`Machine.builtinExtensions`); all by default. */
-    builtinExtensions?: readonly string[];
-}): string;
-export interface AssembleSystemPromptOptions {
-    /**
-     * Base prompt (①), REQUIRED — no default: a defaulted piBasePrompt() would render "Available tools: (none)" even
-     * when tools are mounted.
-     */
-    base: string;
-    /**
-     * ② project-context files (AGENTS.md et al. from loadProjectContextFiles); each wrapped `<project_instructions
-     * path=…>`.
-     */
-    contextFiles?: Array<{
-        path: string;
-        content: string;
-    }>;
-}
-export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
+/**
+ * FastAgent's own prompt sections (docs/design/agent-model.md §2): what pi's prompt cannot know. Each is a named
+ * section pi renders after its own, so it holds whoever wrote the rest of the prompt.
+ */
+export declare function fastagentPromptSections(options: {
+    tools: readonly MountedTool[];
+    /** The {@link BUILTIN_EXTENSIONS} this machine leaves enabled (`Machine.builtinExtensions`). */
+    builtinExtensions: readonly string[];
+}): Record<string, string>;
 /** The assembly, as a value: what every rung builds and what the agent runs on. */
 export interface PiAssembly {
     lease: Lease;
@@ -76,10 +62,13 @@ export interface PiAssembly {
     modelRuntime: () => Promise<ModelRuntime>;
     /** A fresh runtime for every session, before loading its extensions. */
     createModelRuntime: () => Promise<ModelRuntime>;
-    /** The registry and configured model, resolved on first use (a credential read is async). */
+    /**
+     * The registry and the default model, resolved on first use (a credential read is async). No model when the
+     * assembly has no default: each session then runs on the model it records (agent-session-factory.ts).
+     */
     engine: () => Promise<{
         modelRuntime: ModelRuntime;
-        model: AnyModel;
+        model?: AnyModel;
     }>;
     /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
     thinkingLevel: ThinkingLevel;
@@ -101,8 +90,8 @@ export interface CreatePiAgentOptions {
     /** Reasoning effort (pi's scale). */
     thinkingLevel?: ThinkingLevel;
     /**
-     * The system prompt itself — no engine base and no wrapping (unlike the directory path, which assembles the engine
-     * base + AGENTS.md as segment ② + persona.md as segment ①).
+     * The system prompt itself — no engine base and no wrapping (unlike the directory path, where pi builds its default
+     * prompt, or SYSTEM.md replaces it, and AGENTS.md, APPEND_SYSTEM.md and FastAgent's sections are added).
      */
     instructions?: string | (() => string);
     /** The tool set to mount: authored tools or pi's cwd-bound coding tools, both AgentTool. */
@@ -129,11 +118,17 @@ export interface CreatePiAgentOptions {
 export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
 /** L2 options. */
 export interface CreatePiAgentFromDefinitionOptions {
-    /** Model spec "provider/modelId", resolved against {@link models}. */
-    model: string;
+    /**
+     * The default model spec "provider/modelId", resolved against {@link models}. Optional: without it, a session runs
+     * on the model it records, and one that records none fails its invoke with `missing_model`.
+     */
+    model?: string;
     /** Reasoning effort (pi's scale). */
     thinkingLevel?: ThinkingLevel;
-    /** Override the engine base prompt (segment ①). */
+    /**
+     * Replaces pi's default prompt, as `SYSTEM.md` does, and outranks it. Required when `tools` replaces the coding
+     * tools and the directory has no `SYSTEM.md`: pi's default would claim tools the agent does not have.
+     */
     base?: string;
     tools?: MountedTool[];
     /**

package/dist/engines/pi/create.js

@@ -145,70 +145,57 @@ export async function resolveAgentTools(config, agentDir, cwd) {
         ]),
     };
 }
-// Fastagent owns identity and project context; Pi appends skills and cwd for both serving and chat.
-/** The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two deviations. */
-export function piBasePrompt(options = {}) {
-    const mounted = options.tools ?? [];
-    const builtinExtensions = options.builtinExtensions ?? BUILTIN_EXTENSIONS;
-    // Deferred tools stay OUT of the list: their schemas are not in the request until activated, so naming them here
-    // would invite calls to tools that don't exist yet.
-    const tools = mounted.filter(isDefaultActiveTool);
+// pi builds the prompt (its default, or SYSTEM.md in its place); FastAgent adds its own named sections after it.
+/** The tools pi's default prompt says the agent has ("reading files, executing commands, editing code"). */
+const CODING_IDENTITY_TOOLS = ["read", "bash", "edit", "write"];
+/**
+ * Refuse a prompt that would claim tools the agent does not have: pi's default says the agent reads files, runs
+ * commands and edits code, which an embedder that replaced the coding tools made false. A prompt of the agent's own
+ * (`base`, or `SYSTEM.md`) describes it instead. Checked at assembly and on every turn, since `SYSTEM.md` is re-read
+ * per turn and an agent may delete it.
+ */
+function refuseDefaultPromptOverReplacedTools(tools, hasOwnPrompt) {
+    if (hasOwnPrompt)
+        return;
+    const mounted = new Set(tools.map((tool) => tool.name));
+    const missing = CODING_IDENTITY_TOOLS.filter((name) => !mounted.has(name));
+    if (missing.length === 0)
+        return;
+    throw new Error(`the coding tools were replaced (${missing.join(", ")} not mounted), so pi's default prompt, which says the agent ` +
+        `reads files, runs commands and edits code, does not describe this agent: pass \`base\` or write SYSTEM.md`);
+}
+/**
+ * FastAgent's own prompt sections (docs/design/agent-model.md §2): what pi's prompt cannot know. Each is a named
+ * section pi renders after its own, so it holds whoever wrote the rest of the prompt.
+ */
+export function fastagentPromptSections(options) {
+    const sections = {};
+    const mountedNames = new Set(options.tools.map((tool) => tool.name));
     // Only `deferred` tools are tool_search's to load (the session activates it for them); `codemode` ones are listed
     // in codemode's own description, and an inactive direct tool is reached only through an authored activation.
     // A disabled tool-search leaves them no way in, and naming tool_search would invite calls to a tool that is not there.
-    const deferredCount = mounted.filter((tool) => tool.exposure === "deferred" && hasWayIn(tool, builtinExtensions)).length;
-    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 (core.md §2),
-    // keeping the tools list + guidelines below.
-    const mountedNames = new Set(mounted.map((tool) => tool.name));
-    const fullCodingSurface = ["read", "bash", "edit", "write"].every((name) => mountedNames.has(name));
-    const identity = options.persona?.trim() ||
-        (fullCodingSurface
-            ? "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."
-            : "You are an AI assistant operating inside pi, an agent harness. Help users using only the tools and context available to you.");
-    const deferredNote = deferredCount > 0
-        ? `\n\n${deferredCount} additional tool(s) are registered but not loaded — use tool_search to find and load them before concluding a capability is missing.`
-        : "";
+    const deferredCount = options.tools.filter((tool) => tool.exposure === "deferred" && hasWayIn(tool, options.builtinExtensions)).length;
+    if (deferredCount > 0) {
+        sections.deferred_tools = `${deferredCount} additional tool(s) are registered but not loaded — use tool_search to find and load them before concluding a capability is missing.`;
+    }
     // What takes effect when, and the agent's own path to a new capability, are the same on every host; only how long
     // the storage lives differs, below. The skill it writes lives in the definition directory, which the next
     // deployment replaces (or, on AgentCore, erases with everything else) — so the sentence says so, and where a skill
     // that should outlast it has to go. A skill outside the definition would survive, but it is machine state, read
     // once per process (machine.ts), so it would not be live.
-    const RUNTIME_CHANGES = ` Markdown definition files are read each turn; changes to tools, channels or configuration take effect when the service restarts. To give yourself a new capability now, write a skill — a SKILL.md in your definition's skills/ directory, with any script it needs run through bash. It lasts until the next deployment replaces that directory, so a capability that should outlast it belongs in the author's release: propose it to them.${
-    // Named only when mounted (a serve; not a one-shot invoke), like the deferred tools above: naming a tool the model does not
-    // have invites calls to it.
+    const runtimeChanges = ` Markdown definition files are read each turn; changes to tools, channels or configuration take effect when the service restarts. To give yourself a new capability now, write a skill — a SKILL.md in your definition's skills/ directory, with any script it needs run through bash. It lasts until the next deployment replaces that directory, so a capability that should outlast it belongs in the author's release: propose it to them.${
+    // Named only when mounted (a serve; not a one-shot invoke), like the deferred tools above: naming a tool the model
+    // does not have invites calls to it.
     mountedNames.has("wake") ? " To schedule your own follow-up work, use the wake tool." : ""}`;
-    // How long the storage lives is the HOST's answer, not a deployment-wide one: AgentCore's managed
-    // mount is reset by every deploy, so telling that agent to keep work "outside the definition" would
-    // name a location its next deploy erases.
-    const deploymentNote = !isDeployedWorkspace()
-        ? ""
-        : isAgentcoreRuntime()
-            ? `\n\nYour workspace survives restarts, including uncommitted work; /tmp does not. Every deployment of a new version resets this host's storage entirely, so anything that must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database).${RUNTIME_CHANGES}`
-            : `\n\nYour workspace survives restarts and deployments, including uncommitted work; /tmp does not. A new deployment replaces your definition directory with the author's release, so keep ongoing project work outside it.${RUNTIME_CHANGES}`;
-    return `${identity}
-
-Available tools:
-${toolsList}${deferredNote}
-
-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${deploymentNote}`;
-}
-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`;
+    // How long the storage lives is the HOST's answer, not a deployment-wide one: AgentCore's managed mount is reset by
+    // every deploy, so telling that agent to keep work "outside the definition" would name a location its next deploy
+    // erases.
+    if (isDeployedWorkspace()) {
+        sections.self_change = isAgentcoreRuntime()
+            ? `Your workspace survives restarts, including uncommitted work; /tmp does not. Every deployment of a new version resets this host's storage entirely, so anything that must outlive a deployment belongs in an external system (a git remote, an issue tracker, a database).${runtimeChanges}`
+            : `Your workspace survives restarts and deployments, including uncommitted work; /tmp does not. A new deployment replaces your definition directory with the author's release, so keep ongoing project work outside it.${runtimeChanges}`;
     }
-    return prompt;
+    return sections;
 }
 /** Shared low-level wiring: resolve the model spec against the collection, default the K ports, build the parts. */
 function assemblePi(opts) {
@@ -225,7 +212,11 @@ function assemblePi(opts) {
     };
     let engine;
     const resolveEngine = () => {
-        engine ??= modelRuntime().then((runtime) => ({ modelRuntime: runtime, model: resolveModel(runtime, opts.model) }));
+        const spec = opts.model;
+        engine ??= modelRuntime().then((runtime) => ({
+            modelRuntime: runtime,
+            ...(spec ? { model: resolveModel(runtime, spec) } : {}),
+        }));
         return engine;
     };
     // Deny omitted coding names so discovery cannot reintroduce tools a lower-level caller excluded.
@@ -233,7 +224,7 @@ function assemblePi(opts) {
     const sessionFactory = piAgentSessionFactory({
         sessions,
         engine: async () => ({ modelRuntime: await createModelRuntime() }),
-        modelSpec: opts.model,
+        ...(opts.model ? { modelSpec: opts.model } : {}),
         thinkingLevel: opts.thinkingLevel,
         tools: opts.tools,
         readDefinition: opts.readDefinition,
@@ -267,8 +258,9 @@ export function createPiAgent(options) {
         thinkingLevel: options.thinkingLevel,
         models: models.createRuntime,
         catalog: models.runtime,
+        // No instructions is an empty prompt, not pi's default: this path takes the prompt whole.
         readDefinition: () => ({
-            systemPrompt: typeof instructions === "function" ? instructions() : instructions,
+            systemPrompt: (typeof instructions === "function" ? instructions() : instructions) || " ",
             skills,
         }),
         tools: options.tools,
@@ -283,8 +275,8 @@ export function createPiAgent(options) {
  * is built here from the credential options.
  */
 export async function assemblePiFromDefinition(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.
+    // `dir` = the agent-definition dir; `cwd` (default = dir) is the run root where tools operate and whose ancestors are
+    // walked for project 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
@@ -294,6 +286,12 @@ export async function assemblePiFromDefinition(dir, options) {
     // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by the resolved
     // dir).
     reportFindingsIfChanged(definition.dir, definition);
+    // pi treats an empty prompt as none and builds its default, so a blank `base` would look like a prompt of the
+    // caller's own while being nothing.
+    if (options.base !== undefined && options.base.trim() === "") {
+        throw new Error("`base` is empty: pass the prompt the agent should use, or leave `base` out for pi's default");
+    }
+    refuseDefaultPromptOverReplacedTools(tools, options.base !== undefined || definition.systemPrompt !== undefined);
     const { providers } = options;
     const models = options.models ?? agentModels(dir, options, { cwd, env, ...(providers ? { providers } : {}) });
     // Built at boot, so a malformed models.json fails the assembly rather than its first turn. The directory's own
@@ -317,15 +315,15 @@ export async function assemblePiFromDefinition(dir, options) {
         readDefinition: async () => {
             const def = await loadAgentDefinition(dir, { cwd, env });
             reportFindingsIfChanged(def.dir, def);
+            const systemPrompt = options.base ?? def.systemPrompt?.content;
+            refuseDefaultPromptOverReplacedTools(tools, systemPrompt !== undefined);
             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.
-                    base: options.base ?? piBasePrompt({ tools, persona: def.persona, builtinExtensions }),
-                    // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
-                    contextFiles: def.contextFiles,
-                }),
+                ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+                ...(def.appendSystemPrompt ? { appendSystemPrompt: def.appendSystemPrompt.content } : {}),
+                contextFiles: def.contextFiles,
+                sections: fastagentPromptSections({ tools, builtinExtensions }),
                 skills: def.skills,
+                prompts: def.prompts,
             };
         },
         tools,

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

@@ -1,39 +1,68 @@
-import { type ExecutionEnv, type Skill, type SkillDiagnostic } from "@earendil-works/pi-agent-core";
+import { type ExecutionEnv, type PromptTemplateDiagnostic, type Skill, type SkillDiagnostic } from "@earendil-works/pi-agent-core";
 /** A same-name skill collision (the discarded side). */
 export interface SkillCollision {
     name: string;
     winnerPath: string;
     loserPath: string;
 }
+/**
+ * Two places in the definition holding the same thing: `SYSTEM.md` and `.pi/SYSTEM.md`, or one prompt template in
+ * `prompts/` and `.pi/prompts/`. The first is used; the other is reported, because it is a file the author wrote that
+ * does nothing.
+ */
+export interface DefinitionShadow {
+    what: string;
+    winnerPath: string;
+    loserPath: string;
+}
+/** A file the definition holds verbatim, with where it came from. */
+export interface DefinitionFile {
+    path: string;
+    content: string;
+}
+/** A prompt template of the definition's own (`prompts/`, `.pi/prompts/`). */
+export interface DefinitionPrompt {
+    name: string;
+    description?: string;
+    content: string;
+    filePath: string;
+}
+export type DefinitionDiagnostic = SkillDiagnostic | PromptTemplateDiagnostic;
 /** Result of loading a definition directory. */
 export interface LoadedDefinition {
-    /** Project-context files feeding segment ② `<project_context>`, sourced via pi's `loadProjectContextFiles`. */
+    /** Project-context files (AGENTS.md), sourced via pi's `loadProjectContextFiles`; pi renders them. */
     contextFiles: Array<{
         path: string;
         content: string;
     }>;
-    /**
-     * Verbatim `persona.md` content — the authored persona that OVERRIDES segment ①'s identity line (piBasePrompt keeps
-     * the tool list + guidelines; NOT a full system-prompt replacement — that is L1 createPiAgent's `instructions`).
-     * undefined when absent → segment ① is the default engine identity.
-     */
-    persona?: string;
+    /** `SYSTEM.md`, else `.pi/SYSTEM.md`: replaces pi's default prompt. Absent → pi builds its default. */
+    systemPrompt?: DefinitionFile;
+    /** `APPEND_SYSTEM.md`, else `.pi/APPEND_SYSTEM.md`: added after the prompt, whichever it is. */
+    appendSystemPrompt?: DefinitionFile;
     skills: Skill[];
-    /** Non-fatal per-file skill problems reported by pi's loader. */
-    diagnostics: SkillDiagnostic[];
-    /** Same-name conflicts across mounts (first-wins). */
+    prompts: DefinitionPrompt[];
+    /** Non-fatal per-file problems reported by pi's skill and prompt-template loaders. */
+    diagnostics: DefinitionDiagnostic[];
+    /** Same-name skill conflicts across the definition's skill directories (first wins). */
     collisions: SkillCollision[];
-    /** Absolute agent-definition directory path (persona.md/skills/ live here). */
+    /** Same-name files and prompt templates across the definition's locations (first wins). */
+    shadowed: DefinitionShadow[];
+    /** Paths that exist in the definition and are deliberately not loaded, each with why. */
+    ignored: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** Absolute agent-definition directory path. */
     dir: string;
 }
 export interface LoadAgentDefinitionOptions {
-    /** Working directory whose ancestors are walked for context files (segment ②). */
+    /** Working directory whose ancestors are walked for context files. */
     cwd?: string;
     env?: ExecutionEnv;
 }
 /**
- * Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd,
- * agentDir }).
+ * Read an agent definition: its prompt files, skills and prompt templates from `agentDir`; the project context from
+ * pi's loadProjectContextFiles({ cwd, agentDir }).
  */
 export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
 /** Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none. */
@@ -41,18 +70,5 @@ export declare function loadExtensionPaths(agentDir: string, options?: {
     cwd?: string;
     env?: ExecutionEnv;
 }): Promise<string[]>;
-/**
- * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same loader, same
- * containment guard, same first-wins collision rule).
- */
-export declare function loadAgentSkills(agentDir: string, options?: {
-    cwd?: string;
-    env?: ExecutionEnv;
-}): Promise<{
-    skills: Skill[];
-    diagnostics: SkillDiagnostic[];
-    collisions: SkillCollision[];
-    dir: string;
-}>;
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath. */
 export declare function canonicalPath(p: string): string;