@fastagent-sh/fastagent 0.24.1 → 0.24.3

package/dist/engines/pi/definition.js

@@ -1,14 +1,25 @@
-/** Definition domain: read an agent definition directory (AGENTS.md + skills/) into memory. */
+/**
+ * Definition domain: read an agent definition directory into memory — its system prompt files, its skills and prompt
+ * templates (each from the agent directory's root spelling first, then pi's `.pi/` and the standard `.agents/` ones),
+ * and, until contexts exist, the AGENTS.md project context. docs/design/agent-model.md §2 is the rule this follows.
+ */
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { BACKGROUND_CONTEXT, loadSkills, } from "@earendil-works/pi-agent-core";
+import { BACKGROUND_CONTEXT, loadPromptTemplates, loadSkills, } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
 import { assertInsideAgentDir } from "../../paths.js";
+/** Where each resource is read from, in order: the root spelling first, then pi's, then the standard one. */
+const SYSTEM_PROMPT_FILES = ["SYSTEM.md", ".pi/SYSTEM.md"];
+const APPEND_SYSTEM_PROMPT_FILES = ["APPEND_SYSTEM.md", ".pi/APPEND_SYSTEM.md"];
+const SKILL_DIRS = ["skills", ".pi/skills", ".agents/skills"];
+const PROMPT_DIRS = ["prompts", ".pi/prompts"];
+/** The file `SYSTEM.md` and `APPEND_SYSTEM.md` replaced. Refused rather than ignored: its text would do nothing. */
+const RETIRED_PERSONA = "persona.md";
 /**
- * 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 async function loadAgentDefinition(agentDir, options = {}) {
     // One resolved default for the working directory (env cwd AND the context-walk start), so they can never diverge if
@@ -20,18 +31,76 @@ export async function loadAgentDefinition(agentDir, options = {}) {
         throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
     }
     const root = rootResult.value;
-    // ② project context, following pi: the agentDir's own AGENTS.md + every AGENTS.md walking cwd up to root
+    await refuseRetiredPersona(e, root);
+    // Project context, following pi: the agentDir's own AGENTS.md + every AGENTS.md walking cwd up to root
     // (loadProjectContextFiles).
     const contextFiles = loadProjectContextFiles({ cwd, agentDir: root });
-    // persona.md → segment ① persona (overrides the identity line).
-    const personaPath = join(root, "persona.md");
-    const personaRead = await e.readTextFile(personaPath, BACKGROUND_CONTEXT);
-    if (!personaRead.ok && personaRead.error.code !== "not_found") {
-        throw new Error(`cannot read ${personaPath}: ${personaRead.error.message}`);
+    const shadowed = [];
+    const ignored = [];
+    const systemPrompt = await readFirstFile(e, root, SYSTEM_PROMPT_FILES, "system prompt", shadowed, ignored);
+    const appendSystemPrompt = await readFirstFile(e, root, APPEND_SYSTEM_PROMPT_FILES, "appended prompt", shadowed, ignored);
+    const { skills, diagnostics: skillDiagnostics, collisions } = await readSkills(e, root);
+    const { prompts, diagnostics: promptDiagnostics } = await readPrompts(e, root, shadowed);
+    ignored.push(...(await ignoredPaths(e, root)));
+    return {
+        contextFiles,
+        ...(systemPrompt ? { systemPrompt } : {}),
+        ...(appendSystemPrompt ? { appendSystemPrompt } : {}),
+        skills,
+        prompts,
+        diagnostics: [...skillDiagnostics, ...promptDiagnostics],
+        collisions,
+        shadowed,
+        ignored,
+        dir: root,
+    };
+}
+async function exists(e, path) {
+    const info = await e.fileInfo(path, BACKGROUND_CONTEXT);
+    if (info.ok)
+        return true;
+    if (info.error.code === "not_found")
+        return false;
+    throw new Error(`cannot read ${path}: ${info.error.message}`);
+}
+async function refuseRetiredPersona(e, root) {
+    const path = join(root, RETIRED_PERSONA);
+    if (!(await exists(e, path)))
+        return;
+    throw new Error(`${path} is no longer read. Move its text to SYSTEM.md to replace pi's default prompt with an identity of the ` +
+        `agent's own, or to APPEND_SYSTEM.md to add standing instructions to pi's default prompt, which already says ` +
+        `who the agent is (pi's coding assistant) — an identity written there gives the model two`);
+}
+/**
+ * The first of `names` that exists, read; every later one that also exists is shadowed by it. A blank file counts as
+ * absent and is reported: pi treats an empty prompt as none, so it would change nothing while looking like a prompt
+ * of the agent's own.
+ */
+async function readFirstFile(e, root, names, what, shadowed, ignored) {
+    let found;
+    for (const name of names) {
+        const path = join(root, name);
+        const read = await e.readTextFile(path, BACKGROUND_CONTEXT);
+        if (!read.ok) {
+            if (read.error.code === "not_found")
+                continue;
+            throw new Error(`cannot read ${path}: ${read.error.message}`);
+        }
+        if (read.value.trim() === "") {
+            ignored.push({ path, reason: `empty, so it is not used as the ${what}` });
+            continue;
+        }
+        if (found)
+            shadowed.push({ what, winnerPath: found.path, loserPath: path });
+        else
+            found = { path, content: read.value };
     }
-    const persona = personaRead.ok ? personaRead.value : undefined;
-    const { skills, diagnostics, collisions } = await readSkills(e, root);
-    return { contextFiles, persona, skills, diagnostics, collisions, dir: root };
+    return found;
+}
+/** `.pi/extensions/` is pi's place for project extensions; a definition's are `extensions/`, and only those load. */
+async function ignoredPaths(e, root) {
+    const path = join(root, ".pi", "extensions");
+    return (await exists(e, path)) ? [{ path, reason: "not loaded: a definition's extensions live in extensions/" }] : [];
 }
 /** Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none. */
 export async function loadExtensionPaths(agentDir, options = {}) {
@@ -99,15 +168,22 @@ function warnSymlinkRefused(path) {
         `the definition so it travels with the artifact — move it in. (If it is not an extension, ` +
         `keep it outside extensions/ to silence this.)`);
 }
-/** The skills half, shared by the full load and {@link loadAgentSkills}. */
+/** The skills half of {@link loadAgentDefinition}. */
 async function readSkills(e, root) {
-    // The definition's OWN skills/ — its half of the answer. The machine's half is machine.ts's, and `withMachine`
-    // decides a name collision in this half's favour.
-    await assertInsideAgentDir(root, "skills");
-    const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")], BACKGROUND_CONTEXT);
+    // The definition's OWN skills — its half of the answer, from every place it may keep one, the root spelling first.
+    // The machine's half is machine.ts's, and `withMachine` decides a name collision in this half's favour.
+    for (const dir of SKILL_DIRS)
+        await assertInsideAgentDir(root, dir);
+    const { skills: raw, diagnostics } = await loadSkills(e, SKILL_DIRS.map((dir) => join(root, dir)), BACKGROUND_CONTEXT);
     const byName = new Map();
     const collisions = [];
     for (const skill of raw) {
+        // pi only warns about a `/` in a skill name, and loads it. The slash names the context a skill comes from, so a
+        // definition's own skill spelled that way could collide with a context's and is refused here.
+        if (skill.name.includes("/")) {
+            throw new Error(`skill "${skill.name}" (${skill.filePath}): a skill's name may not contain "/", which names the context a ` +
+                `skill comes from — rename it`);
+        }
         const existing = byName.get(skill.name);
         if (existing) {
             collisions.push({ name: skill.name, winnerPath: existing.filePath, loserPath: skill.filePath });
@@ -118,18 +194,35 @@ async function readSkills(e, root) {
     }
     return { skills: [...byName.values()], diagnostics, collisions };
 }
-/**
- * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same loader, same
- * containment guard, same first-wins collision rule).
- */
-export async function loadAgentSkills(agentDir, options = {}) {
-    const cwd = options.cwd ?? agentDir;
-    const e = options.env ?? new NodeExecutionEnv({ cwd });
-    const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
-    if (!rootResult.ok)
-        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
-    // `dir` is the RESOLVED root, like {@link LoadedDefinition.dir}.
-    return { ...(await readSkills(e, rootResult.value)), dir: rootResult.value };
+/** The prompt-template half: `prompts/`, then `.pi/prompts/`, first wins. */
+async function readPrompts(e, root, shadowed) {
+    const byName = new Map();
+    const diagnostics = [];
+    for (const dir of PROMPT_DIRS) {
+        await assertInsideAgentDir(root, dir);
+        const loaded = await loadPromptTemplates(e, join(root, dir), BACKGROUND_CONTEXT);
+        diagnostics.push(...loaded.diagnostics);
+        for (const template of loaded.promptTemplates) {
+            // pi's loader names a template after its file and reads direct children only, so this is its file.
+            const filePath = join(root, dir, `${template.name}.md`);
+            const existing = byName.get(template.name);
+            if (existing) {
+                shadowed.push({
+                    what: `prompt template "${template.name}"`,
+                    winnerPath: existing.filePath,
+                    loserPath: filePath,
+                });
+                continue;
+            }
+            byName.set(template.name, {
+                name: template.name,
+                ...(template.description ? { description: template.description } : {}),
+                content: template.content,
+                filePath,
+            });
+        }
+    }
+    return { prompts: [...byName.values()], diagnostics };
 }
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath. */
 export function canonicalPath(p) {

package/dist/engines/pi/invoke-session.d.ts

@@ -1,6 +1,7 @@
 /** Pi's per-invoke binding over a durable session record. */
-import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import { type Agent } from "../../agent.ts";
+import type { SessionEvent } from "../../session.ts";
 import type { SessionInheritance } from "./session-inheritance.ts";
 import { type Lease, type SessionObserver } from "./turn-kit.ts";
 /** Open or create a record and bind a session. */
@@ -12,4 +13,6 @@ export interface CreatePiAgentFromSessionOptions {
     /** Trusted observation tap; controls arrive with run_started, before session binding. */
     observer?: SessionObserver;
 }
+/** pi's session event as the observation plane's, or null for one it does not publish. Exported for tests only. */
+export declare function toSessionEvent(event: AgentSessionEvent, runId: string): SessionEvent | null;
 export declare function createPiAgentFromSession(options: CreatePiAgentFromSessionOptions): Agent;

package/dist/engines/pi/invoke-session.js

@@ -3,20 +3,22 @@ import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Queue from "effect/Queue";
-import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { ABORTED_CODE, MISSING_MODEL_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
 import { entryImages } from "./entry-images.js";
 import { cancellableStream } from "../../collect.js";
 import { log } from "../../log.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
 import { PortFailure, port, portAbort, portCleanup, portError } from "../../effect-port.js";
 import { SessionBusy, acquireSession, acquireSessionLease } from "./session-effects.js";
-import { errorToTerminal, inProcessLease, agentEventProjection, answerOutcome, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
+import { MissingModel } from "./session-settings.js";
+import { errorToTerminal, inProcessLease, agentEventProjection, answerOutcome, streamsThinkingDelta, asksToEndRun, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
 // Structured output is for scripts. Observation publishes Pi's display result, including bounded nested traces.
 function displayToolResult(result) {
     const { structuredContent: _internal, ...display } = result;
     return display;
 }
-function toSessionEvent(event, runId) {
+/** pi's session event as the observation plane's, or null for one it does not publish. Exported for tests only. */
+export function toSessionEvent(event, runId) {
     const at = Date.now();
     switch (event.type) {
         case "message_start":
@@ -26,8 +28,9 @@ function toSessionEvent(event, runId) {
         case "message_update": {
             const ev = event.assistantMessageEvent;
             if (ev.type === "text_delta" || ev.type === "thinking_delta") {
-                // Empty deltas must not spend the silent window in which a provider retry is safe.
-                return ev.delta === ""
+                // Empty deltas must not spend the silent window in which a provider retry is safe. A redacted block's
+                // placeholder is not reasoning, and its entry will not carry it either (turn-kit.ts answerThinking).
+                return ev.delta === "" || (ev.type === "thinking_delta" && !streamsThinkingDelta(ev))
                     ? null
                     : {
                         type: "message_delta",
@@ -78,6 +81,7 @@ function toSessionEvent(event, runId) {
                     isError: event.isError,
                     content: displayToolResult(event.result),
                     ...(event.parentToolCallId ? { parentToolCallId: event.parentToolCallId } : {}),
+                    ...(asksToEndRun(event) ? { terminate: true } : {}),
                 },
             };
         case "queue_update":
@@ -352,7 +356,9 @@ export function createPiAgentFromSession(options) {
                         retryable: true,
                         code: SESSION_BUSY_CODE,
                     }
-                    : errorToTerminal(error));
+                    : error instanceof MissingModel
+                        ? { type: "failed", details: error.message, retryable: false, code: MISSING_MODEL_CODE }
+                        : errorToTerminal(error));
             }));
             settled = true;
             Queue.offerUnsafe(queue, terminal.type === "failed" && (abortSucceeded || abortsInFlight > 0)

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

@@ -12,7 +12,7 @@
 import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
 /** pi's own shapes, taken from its loader rather than re-declared. */
 export type MachineSkill = ReturnType<DefaultResourceLoader["getSkills"]>["skills"][number];
-type MachinePrompt = ReturnType<DefaultResourceLoader["getPrompts"]>["prompts"][number];
+export type MachinePrompt = ReturnType<DefaultResourceLoader["getPrompts"]>["prompts"][number];
 /** The Pi built-in extensions a definition loads, each unless the machine's settings disable it. */
 export declare const BUILTIN_EXTENSIONS: readonly ["codemode", "tool-search"];
 /**
@@ -51,4 +51,3 @@ export declare function withMachine<Own extends {
 }, Lent extends {
     name: string;
 }>(own: readonly Own[], lent: readonly Lent[]): (Own | Lent)[];
-export {};

package/dist/engines/pi/machine.js

@@ -91,10 +91,19 @@ async function read(workspace, agentDir) {
             log.warn(`[fastagent] ${kind} ${diagnostic.type}: ${diagnostic.message}${diagnostic.path ? ` (${diagnostic.path})` : ""}`);
         }
     }
+    // A `/` in a skill's name names the context it comes from (definition.ts), and pi only warns about one. The
+    // machine's own skill spelled that way is left out rather than let collide with a context's.
+    const lent = skills.filter((skill) => {
+        if (!skill.name.includes("/"))
+            return true;
+        log.warn(`[fastagent] machine skill "${skill.name}" (${skill.filePath}) is not loaded: a skill's name may not contain "/", ` +
+            `which names the context a skill comes from`);
+        return false;
+    });
     const builtinExtensions = packages.extensions
         .filter((resource) => resource.enabled && resource.metadata.source === "builtin")
         .map((resource) => resource.path.slice("builtin:".length));
-    return { skills, prompts, builtinExtensions, settingsManager: () => scopedSettings(settings) };
+    return { skills: lent, prompts, builtinExtensions, settingsManager: () => scopedSettings(settings) };
 }
 /** A package's enabled resources; the loader discovers the top-level ones itself. */
 function fromPackages(resources) {

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

@@ -13,8 +13,8 @@ import type { ToolCollision, MountedTool } from "./tool.ts";
 import type { DeclaredSecret } from "../../declared-secrets.ts";
 import type { HttpSurface } from "../../service.ts";
 /**
- * The names a `/` composer completes: this agent's skills — the definition's, plus the ones its machine lends
- * (machine.ts) —, the commands its `extensions/` register, and the machine's prompt templates.
+ * The names a `/` composer completes: this agent's skills and prompt templates — the definition's, plus the ones its
+ * machine lends (machine.ts) — and the commands its `extensions/` register.
  *
  * `source` says how a name is INVOKED, which is the one thing a client needs from it: a `skill` is sent as
  * `/skill:<name>`, an `extension` command and a `prompt` as `/<name>` (docs/design/session-control.md §5.1.1).
@@ -62,8 +62,12 @@ export interface CreatePiAgentFromDirOptions {
 export interface AgentAssembly {
     config: FastagentConfig;
     configPath?: string;
-    /** The resolved "provider/modelId" spec in use. */
-    modelSpec: string;
+    /**
+     * The default "provider/modelId" spec (`--model` > `FASTAGENT_MODEL` > config), or undefined when the agent sets none:
+     * it still opens, a session that records its model runs on it, and one that records none is refused with
+     * `missing_model` at invoke.
+     */
+    modelSpec?: string;
     /** Absolute agent dir — definition + config + machinery live here (resolvePlacement().agentDir). */
     agentDir: string;
     /** Absolute workspace — the agent's cwd and the start of the ②-context walk. */
@@ -148,9 +152,9 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     definition: LoadedDefinition;
     config: FastagentConfig;
     configPath?: string;
-    /** The resolved "provider/modelId" spec actually in use. */
-    modelSpec: string;
-    /** Absolute agent dir in use — channels/tools/persona come from here. */
+    /** The default "provider/modelId" spec, or undefined when the agent sets none ({@link AgentAssembly.modelSpec}). */
+    modelSpec?: string;
+    /** Absolute agent dir in use — channels/tools/prompt come from here. */
     agentDir: string;
     /** Absolute workspace in use — the agent's cwd: ALWAYS the directory that was pointed at. */
     workspace: string;

package/dist/engines/pi/open.js

@@ -11,7 +11,7 @@ import { agentOf, assemblePiFromDefinition, resolveAgentTools } from "./create.j
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
 import { refuseBrokenDeclarations } from "../../loader.js";
-import { loadAgentSkills } from "./definition.js";
+import { loadAgentDefinition } from "./definition.js";
 import { servedExtensionCommands } from "./agent-session-factory.js";
 import { reportFindingsIfChanged } from "./report.js";
 import { readMachine, withMachine } from "./machine.js";
@@ -22,8 +22,8 @@ import { log } from "../../log.js";
 import { piSessionRecordStore } from "./session-store.js";
 import { gateSecrets } from "../../secrets-gate.js";
 /**
- * The names a `/` composer completes: this agent's skills — the definition's, plus the ones its machine lends
- * (machine.ts) —, the commands its `extensions/` register, and the machine's prompt templates.
+ * The names a `/` composer completes: this agent's skills and prompt templates — the definition's, plus the ones its
+ * machine lends (machine.ts) — and the commands its `extensions/` register.
  *
  * `source` says how a name is INVOKED, which is the one thing a client needs from it: a `skill` is sent as
  * `/skill:<name>`, an `extension` command and a `prompt` as `/<name>` (docs/design/session-control.md §5.1.1).
@@ -34,10 +34,13 @@ import { gateSecrets } from "../../secrets-gate.js";
  * on (asked only when there are extensions) — never a fresh scan of `extensions/`.
  */
 export async function agentCommands(agentDir, workspace, served) {
-    const own = await loadAgentSkills(agentDir, { cwd: workspace });
-    // A skill whose frontmatter broke simply is not in `skills` — it would vanish from the composer with no signal.
+    // The whole definition, read the way a turn reads it: a skill whose frontmatter broke simply is not in `skills`, and
+    // would vanish from the composer with no signal. The SAME findings a turn reports, so the per-directory memo sees
+    // one set from both readers instead of warning again after every menu request.
+    const own = await loadAgentDefinition(agentDir, { cwd: workspace });
     reportFindingsIfChanged(own.dir, own);
     const machine = await readMachine(workspace);
+    const prompts = withMachine(own.prompts, machine.prompts);
     const { extensionPaths } = served;
     const extensionCommands = await servedExtensionCommands({
         cwd: workspace,
@@ -57,7 +60,7 @@ export async function agentCommands(agentDir, workspace, served) {
             ...(command.description ? { description: command.description } : {}),
             source: "extension",
         })),
-        ...machine.prompts
+        ...prompts
             .filter((prompt) => !shadowed.has(prompt.name))
             .map((prompt) => ({
             name: prompt.name,
@@ -71,9 +74,6 @@ export async function resolveAgentAssembly(dir, options = {}) {
     const { agentDir, workspace } = resolvePlacement(dir);
     const { config, path: configPath } = await loadConfig(agentDir);
     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")`);
-    }
     const { tools, toolNames, indirectTools, toolCollisions, toolFailures, toolSecrets } = await resolveAgentTools(config, agentDir, workspace);
     // THE serving-path gate for tool declarations, in the order that costs the fewest round trips. A file that could
     // not be imported declares nothing, so its `secrets:` are missing from `toolSecrets` — gating secrets first would
@@ -94,7 +94,7 @@ export async function resolveAgentAssembly(dir, options = {}) {
     return {
         config,
         configPath,
-        modelSpec,
+        ...(modelSpec ? { modelSpec } : {}),
         agentDir,
         workspace,
         stateRoot,
@@ -114,7 +114,7 @@ export async function resolveAgentAssembly(dir, options = {}) {
  */
 export function assembleFront(front, extra = {}) {
     return assemblePiFromDefinition(front.agentDir, {
-        model: front.modelSpec,
+        ...(front.modelSpec ? { model: front.modelSpec } : {}),
         thinkingLevel: front.config.thinkingLevel,
         cwd: front.workspace,
         tools: extra.tools ?? front.tools,
@@ -221,7 +221,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
                 lease: assembly.lease,
                 models: modelRuntime,
                 sessionFactory: assembly.sessionFactory,
-                defaults: { model, thinkingLevel: assembly.thinkingLevel },
+                defaults: { ...(model ? { model } : {}), thinkingLevel: assembly.thinkingLevel },
             }))
             : undefined;
         hub = createPiSessionControl({
@@ -259,7 +259,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
         workspace,
         config,
         configPath,
-        modelSpec,
+        ...(modelSpec ? { modelSpec } : {}),
         stateRoot,
         sessionsDir,
         models,

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

@@ -1,18 +1,17 @@
-/**
- * Render assembly warnings to stderr — the one place both the CLI runners and the `chat` runtime show the non-fatal
- * definition/tool findings the loaders return as data.
- */
-import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
-import type { SkillCollision } from "./definition.ts";
+import type { DefinitionDiagnostic, DefinitionShadow, LoadedDefinition, SkillCollision } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
 import type { IndirectTool } from "./create.ts";
 type Findings = {
     collisions: SkillCollision[];
-    diagnostics: SkillDiagnostic[];
+    diagnostics: DefinitionDiagnostic[];
+    shadowed?: DefinitionShadow[];
+    ignored?: LoadedDefinition["ignored"];
 };
 /** THE door for definition findings: warns only when this dir's set CHANGED since the last report. */
 export declare function reportFindingsIfChanged(dir: string, def: Findings): void;
-export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
+export declare function reportDefinitionWarnings(def: Findings): void;
+/** What the agent's system prompt is made of, as a report line: pi's default or `SYSTEM.md`, plus an addendum. */
+export declare function describePrompt(def: Pick<LoadedDefinition, "dir" | "systemPrompt" | "appendSystemPrompt">): string;
 /** The report line for the mounted tools the model is not given up front: each name with its way in. */
 export declare function describeIndirectTools(tools: readonly IndirectTool[]): string;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;

package/dist/engines/pi/report.js

@@ -1,9 +1,16 @@
+/**
+ * Render assembly warnings to stderr — the one place both the CLI runners and the `chat` runtime show the non-fatal
+ * definition/tool findings the loaders return as data.
+ */
+import { relative } from "node:path";
 import { log } from "../../log.js";
 /** Stable identity of a definition's non-fatal findings — the dedup key below. */
 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");
+    const shadowed = (def.shadowed ?? []).map((s) => `s:${s.what}:${s.winnerPath}:${s.loserPath}`);
+    const ignored = (def.ignored ?? []).map((i) => `i:${i.path}`);
+    return [...collisions, ...diagnostics, ...shadowed, ...ignored].sort().join("\n");
 }
 /** The last reported finding set PER DEFINITION DIR. */
 const lastFindings = new Map();
@@ -13,16 +20,27 @@ export function reportFindingsIfChanged(dir, def) {
     if (lastFindings.get(dir) === sig)
         return;
     lastFindings.set(dir, sig);
-    reportDefinitionWarnings(def.collisions, def.diagnostics);
+    reportDefinitionWarnings(def);
 }
-export function reportDefinitionWarnings(collisions, diagnostics) {
-    for (const c of collisions) {
+export function reportDefinitionWarnings(def) {
+    for (const c of def.collisions) {
         log.warn(`[fastagent] skill "${c.name}" collision — using ${c.winnerPath}, ignoring ${c.loserPath}`);
     }
-    for (const d of diagnostics) {
+    for (const s of def.shadowed ?? []) {
+        log.warn(`[fastagent] ${s.what} is in two places — using ${s.winnerPath}, ignoring ${s.loserPath}`);
+    }
+    for (const i of def.ignored ?? []) {
+        log.warn(`[fastagent] ${i.path} is ${i.reason}`);
+    }
+    for (const d of def.diagnostics) {
         log.warn(`[fastagent] ${d.code}: ${d.message} (${d.path})`);
     }
 }
+/** What the agent's system prompt is made of, as a report line: pi's default or `SYSTEM.md`, plus an addendum. */
+export function describePrompt(def) {
+    const base = def.systemPrompt ? relative(def.dir, def.systemPrompt.path) : "pi's default";
+    return def.appendSystemPrompt ? `${base} + ${relative(def.dir, def.appendSystemPrompt.path)}` : base;
+}
 const REACH = {
     tool_search: "loaded via tool_search",
     codemode: "codemode scripts only",

package/dist/engines/pi/session-builder.js

@@ -6,7 +6,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { SessionManager, SettingsManager, createAgentSessionRuntime, getAgentDir, } from "@earendil-works/pi-coding-agent";
 import { bindPiSession, definitionServices } from "./agent-session-factory.js";
-import { resolveModel } from "./config.js";
+import { missingDefaultModel, resolveModel } from "./config.js";
 import { canonicalPath } from "./definition.js";
 import { reportToolCollisions } from "./report.js";
 import { assembleFront, resolveAgentAssembly } from "./open.js";
@@ -19,11 +19,15 @@ import { resolvePlacement } from "../../paths.js";
 export async function buildAgentSessionRuntime(dir, options = {}, sessionManager) {
     async function resolveAssembly() {
         const front = await resolveAgentAssembly(dir, options);
+        // chat's TUI always starts a conversation, so it needs the default the served agent can do without.
+        const modelSpec = front.modelSpec;
+        if (!modelSpec)
+            throw missingDefaultModel();
         reportToolCollisions(front.toolCollisions);
         const { assembly } = await assembleFront(front);
         // Read ONCE per runtime: a rebuild (/new, fork) keeps the startup snapshot, because config and tools stay in the
         // import cache and a half-refreshed agent is worse than a stale one. Restart chat to pick up edits.
-        return { modelSpec: front.modelSpec, assembly, definition: await assembly.readDefinition() };
+        return { modelSpec, assembly, definition: await assembly.readDefinition() };
     }
     // The workspace, like serving's: where tools run and what session records are keyed to. Canonical, because pi's
     // process.cwd() fallback is a realpath and a symlinked workspace would otherwise mismatch it.

package/dist/engines/pi/session-control.d.ts

@@ -35,9 +35,10 @@ export interface PiBoundaryWiring {
     /** The assembly's configured PAIR — what a session with no overrides runs on. One field because
      *  model and thinking level are one setting: which levels exist is a property of the model, so a
      *  wiring that could carry them apart could carry a pair no run uses. Must be what
-     *  {@link sessionFactory} was built with. */
+     *  {@link sessionFactory} was built with. No model when the agent sets no default: a session then runs on the model
+     *  it records, and `state()` of one that records none reports no model. */
     defaults: {
-        model: AnyModel;
+        model?: AnyModel;
         thinkingLevel: ThinkingLevel;
     };
 }

package/dist/engines/pi/session-control.js

@@ -8,14 +8,14 @@ import { PortFailure, port, portAbort, portCleanup, portError, portJoin } from "
 import { acquireSession, acquireSessionLease } from "./session-effects.js";
 import { calculateContextTokens, estimateTokens, getLastAssistantUsage, } from "@earendil-works/pi-coding-agent";
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
-import { SESSION_BUSY_CODE } from "../../agent.js";
+import { MISSING_MODEL_CODE, SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, isAddressableSession, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, PARTIAL_UPDATE_CODE, UPDATE_FIELDS, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
 import { forkProvenance, isConversationMessage, isNavigable, publishedLeaf } from "./session-markers.js";
 import { entryImages, imageAt } from "./entry-images.js";
-import { answerOutcome } from "./turn-kit.js";
+import { answerOutcome, answerThinking, endsRun, } from "./turn-kit.js";
 import { startCompaction } from "./agent-session-factory.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
-import { THINKING_LEVELS, activePath, describeModels, resolveSessionSettings } from "./session-settings.js";
+import { MissingModel, THINKING_LEVELS, activePath, describeModels, resolveSessionSettings, } from "./session-settings.js";
 import { log } from "../../log.js";
 // ── Usage (read from the record) ─────────────────────────────────────────────
 /**
@@ -92,6 +92,10 @@ function toSessionEntry(entry, parentId) {
             const data = { text: contentText(m.content, "") };
             if (toolCalls.length > 0)
                 data.toolCalls = toolCalls;
+            // The same text the live `message_delta { channel: "thinking" }` added up to (turn-kit.ts answerThinking).
+            const thinking = answerThinking(m);
+            if (thinking !== undefined)
+                data.thinking = thinking;
             const outcome = answerOutcome(m);
             if (outcome)
                 data.outcome = outcome;
@@ -107,6 +111,8 @@ function toSessionEntry(entry, parentId) {
                     isError: m.isError ?? false,
                     text: contentText(m.content, ""),
                     ...entryImages(entry.id, m),
+                    // Same flag as the live `tool_finished` (turn-kit.ts asksToEndRun).
+                    ...(endsRun(m) ? { terminate: true } : {}),
                 },
             };
         }
@@ -504,7 +510,11 @@ export function createPiSessionControl(options) {
     });
     const failed = (error) => ({
         ok: false,
-        error: { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(error), retryable: true },
+        // A command that binds the session (compaction is a model call) on a session with no model: the same code the
+        // invoke answers, since the same fix (`update({ model })`) applies.
+        error: error instanceof MissingModel
+            ? { code: MISSING_MODEL_CODE, message: error.message, retryable: false }
+            : { code: BOUNDARY_COMMAND_FAILED_CODE, message: String(error), retryable: true },
     });
     const runBoundary = (command) => Effect.runPromise(Effect.scoped(command).pipe(Effect.catchTag("SessionBusy", () => Effect.succeed(busy())), Effect.catchCause((cause) => Effect.succeed(failed(portError(cause))))));
     /** steer / follow_up / abort — the run actions. They reach the LIVE run through the controls
@@ -633,11 +643,15 @@ export function createPiSessionControl(options) {
                 return failed(error);
             }
             // An explicit model in the same patch wins over the one that path resolves to: it is applied
-            // after the move, so it is what the session ends up running.
-            const target = model ?? resolved.model;
-            const levels = model ? getSupportedThinkingLevels(model) : resolved.availableThinkingLevels;
-            if (!levels.includes(patch.thinkingLevel)) {
-                return invalid(`thinking level "${patch.thinkingLevel}" is not supported by ${target.provider}/${target.id} (allowed: ${levels.join(", ")})`);
+            // after the move, so it is what the session ends up running. With neither (no model recorded, no
+            // default), any level of the vocabulary is recorded, and clamped once the session has a model, like a
+            // recorded level after a model change.
+            const target = model ?? resolved?.model;
+            if (target) {
+                const levels = getSupportedThinkingLevels(target);
+                if (!levels.includes(patch.thinkingLevel)) {
+                    return invalid(`thinking level "${patch.thinkingLevel}" is not supported by ${target.provider}/${target.id} (allowed: ${levels.join(", ")})`);
+                }
             }
         }
         // Release before publishing state_changed: an observer may immediately issue another command.

package/dist/engines/pi/session-markers.d.ts

@@ -22,7 +22,7 @@ export declare function isPlaneMarker(entry: {
  * by "a message".
  *
  * The line it draws is the ENGINE's prompt state. Since pi 0.86 pi writes `system` messages into the same log the
- * conversation lives in, carrying the assembled prompt (persona, project context, skill and tool descriptions)
+ * conversation lives in, carrying the assembled prompt (system prompt, project context, skill and tool descriptions)
  * plus one more per prompt or tool-set change. They are bookkeeping, not something anyone said, and every reader
  * of the journal has to decide about them. Deciding once, here, is the point: the first reader that forgot cut
  * inheritance above every exchange and handed a new thread an empty history, with no diagnostic.