@fastagent-sh/fastagent 0.24.2 → 0.24.4

package/dist/agent.d.ts

@@ -91,6 +91,12 @@ export declare const SESSION_BUSY_CODE = "session_busy";
  * never replayed as a fresh turn on restart.
  */
 export declare const ABORTED_CODE = "aborted";
+/**
+ * The `failed.code` set when a turn has no model to run on: its session records none of its own, and the agent sets
+ * no default. Not retryable as is: giving the session a model (session control's `update({ model })`) or the agent a
+ * default is what changes the answer.
+ */
+export declare const MISSING_MODEL_CODE = "missing_model";
 /**
  * One turn = one invoke, returning a single async event stream. The stream MUST terminate with exactly one of
  * `completed` / `failed`, or be cancelled by the caller (no terminal event).

package/dist/agent.js

@@ -13,3 +13,9 @@ export const SESSION_BUSY_CODE = "session_busy";
  * never replayed as a fresh turn on restart.
  */
 export const ABORTED_CODE = "aborted";
+/**
+ * The `failed.code` set when a turn has no model to run on: its session records none of its own, and the agent sets
+ * no default. Not retryable as is: giving the session a model (session control's `update({ model })`) or the agent a
+ * default is what changes the answer.
+ */
+export const MISSING_MODEL_CODE = "missing_model";

package/dist/cli/commands/add.js

@@ -238,5 +238,5 @@ export async function runAddSkill(source, dirArg, opts) {
     if (hasScripts) {
         console.error(`  warn: this skill ships scripts/ (executable code that runs in your agent) — review it before deploying`);
     }
-    console.error(`  next: mention "${name}" in persona.md so the model knows when to use it; then \`fastagent dev\``);
+    console.error(`  next: mention "${name}" in APPEND_SYSTEM.md so the model knows when to use it; then \`fastagent dev\``);
 }

package/dist/cli/commands/chat.js

@@ -10,5 +10,5 @@ export async function runChat(dirArg, opts) {
     process.chdir(placement.workspace);
     // Lazy-import: chat pulls pi's interactive TUI module graph; headless start/dev never need it.
     const { runPiChat } = await import("../../engines/pi/chat.js");
-    await runPiChat(placement.agentDir, { model: opts.model }).catch(failStartup);
+    await runPiChat(placement.agentDir, { model: placement.modelSpec }).catch(failStartup);
 }

package/dist/cli/commands/deploy.js

@@ -1,7 +1,7 @@
 import { preflightDeploy } from "../../deploy/preflight.js";
 import { loadConfig } from "../../engines/pi/config.js";
 import { failStartup, failUsage } from "../fail.js";
-import { enterAgentCommand } from "../shared.js";
+import { enterAgentDirectory } from "../shared.js";
 import { agentcoreHost } from "./deploy/agentcore.js";
 import { dockerHost } from "./deploy/docker.js";
 import { flyHost } from "./deploy/fly.js";
@@ -56,7 +56,7 @@ export async function runDeploy(host, dirArg, opts) {
         failUsage(`deploy stopped: --tunnel is supported only by the local Docker target`);
     }
     // The picker's write-back lands the model in fastagent.config.ts.
-    const placement = await enterAgentCommand(dirArg, opts);
+    const placement = await enterAgentDirectory(dirArg, opts);
     // ONE deploy semantic: bake the WORKSPACE (WYSIWYG).
     const { agentDir, workspace } = placement;
     const { config } = await loadConfig(agentDir).catch(failStartup);

package/dist/cli/commands/dev.js

@@ -36,11 +36,11 @@ async function serveOnce(placement, opts) {
     const tunnel = opts.tunnel ?? false;
     assertTunnelBindable(host, tunnel);
     const a = await createPiAgentFromDir(placement.agentDir, {
-        model: opts.model,
+        model: placement.modelSpec,
         serving: true, // long-running serve: the scheduler poller runs (and the wake tool is mounted)
     }).catch(failStartup);
     // The same report `start` prints; `config:` is dev's own extra (see reportAssembly on the asymmetry).
-    await reportAssembly(a, { beforeModel: [["config", a.configPath ?? "(none)"]] });
+    await reportAssembly({ ...a, modelSpec: placement.modelSpec }, { beforeModel: [["config", a.configPath ?? "(none)"]] });
     // The SAME assembly an embedder gets from `createAgentService` — channels, control plane, schedules, long
     // connections.
     const service = await mountAgentService(withRunOverrides(a, opts), cliMountOptions(logAgentLoop)).catch(failStartup);

package/dist/cli/commands/info.js

@@ -8,7 +8,7 @@ import { agentModels } from "../../engines/pi/agent-models.js";
 import { resolveSessionsDir, resolveStateRoot } from "../../paths.js";
 import { CODING_TOOL_NAMES, resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
-import { describeIndirectTools, reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
+import { describeIndirectTools, describePrompt, reportFindingsIfChanged, reportToolCollisions, } from "../../engines/pi/report.js";
 import { allSecrets, describeSecrets, missingSecrets } from "../../declared-secrets.js";
 import { log } from "../../log.js";
 import { reportModuleLoadFailures } from "../../loader.js";
@@ -25,8 +25,10 @@ export async function runInfo(dirArg, opts) {
     // agentDir = where the agent lives (definition + config + machinery); workspace = what it works ON (its cwd, whose
     // AGENTS.md ancestors are ② context).
     const definition = await loadAgentDefinition(agentDir, { cwd: workspace }).catch(failStartup);
-    // What this agent HAS: the definition's skills plus the ones its machine lends (machine.ts).
-    const skills = withMachine(definition.skills, (await readMachine(workspace)).skills);
+    // What this agent HAS: the definition's skills and prompt templates plus the ones its machine lends (machine.ts).
+    const machineResources = await readMachine(workspace);
+    const skills = withMachine(definition.skills, machineResources.skills);
+    const prompts = withMachine(definition.prompts, machineResources.prompts);
     // A tool that fails to load, for any reason (a missing dep, a top-level throw, or just not being a tool), is
     // isolated the same way everywhere (G2).
     const tools = await resolveAgentTools(config, agentDir, workspace)
@@ -104,8 +106,10 @@ export async function runInfo(dirArg, opts) {
             thinkingLevel: config.thinkingLevel ?? null,
             codingTools: [...CODING_TOOL_NAMES],
             context: definition.contextFiles.map((f) => f.path),
-            persona: definition.persona !== undefined,
+            systemPrompt: definition.systemPrompt?.path ?? null,
+            appendSystemPrompt: definition.appendSystemPrompt?.path ?? null,
             skills: skills.map((skill) => ({ name: skill.name, description: skill.description })),
+            prompts: prompts.map((prompt) => ({ name: prompt.name, description: prompt.description ?? null })),
             tools: tools.names,
             indirectTools: tools.indirect,
             toolError: tools.error ?? null,
@@ -119,6 +123,8 @@ export async function runInfo(dirArg, opts) {
             fallbackAuthPath: auth.fallback ?? null,
             diagnostics: definition.diagnostics,
             skillCollisions: definition.collisions,
+            shadowed: definition.shadowed,
+            ignored: definition.ignored,
             toolCollisions: tools.collisions,
             toolFailures: tools.failures,
             declaredSecrets,
@@ -142,8 +148,9 @@ export async function runInfo(dirArg, opts) {
         line("thinking", config.thinkingLevel);
     line("codingTools", CODING_TOOL_NAMES.join(", "));
     line("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    line("persona", definition.persona ? "persona.md" : "(none)");
+    line("prompt", describePrompt(definition));
     line("skills", skills.map((skill) => skill.name).join(", ") || "(none)");
+    line("prompts", prompts.map((prompt) => prompt.name).join(", ") || "(none)");
     line("tools", tools.error ? "(could not load — see warning below)" : tools.names.join(", ") || "(none)");
     if (tools.indirect.length > 0)
         line("indirect", describeIndirectTools(tools.indirect));

package/dist/cli/commands/invoke.js

@@ -6,9 +6,8 @@ import { failStartup } from "../fail.js";
 import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runInvoke(message, dirArg, opts) {
     const placement = await enterAgentCommand(dirArg, opts);
-    const { agent, modelSpec, models } = await createPiAgentFromDir(placement.agentDir, {
-        model: opts.model,
-    }).catch(failStartup);
+    const { modelSpec } = placement;
+    const { agent, models } = await createPiAgentFromDir(placement.agentDir, { model: modelSpec }).catch(failStartup);
     // BOTH directories, like dev/start: which agent ran, and what it worked on.
     console.error(`[fastagent] invoke: ${placement.agentDir} (workspace ${placement.workspace}, ${modelSpec})`);
     await reportAuth(models, modelSpec);

package/dist/cli/commands/routine-run.js

@@ -10,9 +10,9 @@ import { runInvokeStream } from "../invoke-stream.js";
 import { loadRoutines } from "../../schedule/discover.js";
 import { routineSession } from "../../schedule/routine.js";
 import { failStartup, gateSecretsOrExit } from "../fail.js";
-import { enterAgentCommand, reportAuth } from "../shared.js";
+import { enterAgentDirectory, reportAuth, requireDefaultModel } from "../shared.js";
 export async function runRoutine(name, dirArg, opts) {
-    const placement = await enterAgentCommand(dirArg, opts);
+    const placement = await enterAgentDirectory(dirArg, opts);
     // Routines are agent surface — discovered where dev/start/`routine list` do (the agent dir), so this command
     // sees the same set the clock serves.
     const { routines, secrets, failures } = await loadRoutines(placement.agentDir).catch(failStartup);
@@ -36,9 +36,8 @@ export async function runRoutine(name, dirArg, opts) {
     // were printed above: its guarantee must not depend on this call site remembering (a repeated line
     // on the refusal path is the cheaper failure).
     gateSecretsOrExit({ declared: secrets, failures, owner: name });
-    const { agent, modelSpec, models } = await createPiAgentFromDir(placement.agentDir, {
-        model: opts.model,
-    }).catch(failStartup);
+    const { modelSpec } = requireDefaultModel(placement);
+    const { agent, models } = await createPiAgentFromDir(placement.agentDir, { model: modelSpec }).catch(failStartup);
     console.error(`[fastagent] routine run: ${name} (${modelSpec})`);
     await reportAuth(models, modelSpec);
     const exitCode = await runInvokeStream(agent.invoke({ session: routineSession(name) }, { text: routine.prompt }), (text) => process.stdout.write(text), (line) => console.error(line));

package/dist/cli/commands/start.js

@@ -125,11 +125,11 @@ export async function openStartService(dirArg, opts) {
 export async function openPreparedStartService(dirArg, opts) {
     const placement = await enterAgentCommand(dirArg, opts);
     const opened = await createPiAgentFromDir(placement.agentDir, {
-        model: opts.model,
+        model: placement.modelSpec,
         serving: true,
     });
     const { agent, agentDir, config, stateRoot, sessionsDir } = opened;
-    await reportAssembly(opened, {
+    await reportAssembly({ ...opened, modelSpec: placement.modelSpec }, {
         afterTools: [
             ["state", stateRoot],
             ["sessions", sessionsDir],

package/dist/cli/kernel.js

@@ -9,7 +9,7 @@ const specOf = new WeakMap();
 export function buildProgram(specs, options = {}) {
     const exit = options.exit ?? ((code) => process.exit(code));
     const program = new Command("fastagent");
-    program.description("Serve a file-defined agent — persona.md, skills/, tools/, channels/ — as a live service.");
+    program.description("Serve a file-defined agent — SYSTEM.md, skills/, tools/, channels/ — as a live service.");
     // The exit-code policy: commander throws only for parse-level events — help/version displays carry exitCode 0 (→
     // 0), everything else it rejects is a usage error (→ 2).
     program.exitOverride((err) => exit(err.exitCode === 0 ? 0 : 2));

package/dist/cli/program.js

@@ -44,7 +44,7 @@ const init = {
     description: "Scaffold a runnable agent and run npm install. The agent ALWAYS goes into a subdirectory of dir " +
         "(default .): ./fastagent/, or --agent-dir <name> — the rest of the directory gets zero writes, and " +
         "it is the WORKSPACE the agent works ON when you point fastagent there. Content is a " +
-        "self-iterating agent: persona.md (its identity), a writing-great-skills " +
+        "self-iterating agent: APPEND_SYSTEM.md (its standing instructions), a writing-great-skills " +
         "example skill, a fetch-url code tool, config, package.json, .gitignore. An existing AGENTS.md is " +
         "kept as project context.",
     args: [DIR_ARG],
@@ -70,7 +70,8 @@ const init = {
 const dev = {
     name: "dev",
     summary: "serve the agent locally, restarting on code edits",
-    description: "Assemble the agent in dir (default .) and serve a local HTTP channel. persona.md/AGENTS.md/skills " +
+    description: "Assemble the agent in dir (default .) and serve a local HTTP channel. SYSTEM.md/APPEND_SYSTEM.md/" +
+        "AGENTS.md/skills/prompts " +
         "are re-read every turn (edits go live next turn); edits to code inputs — tools/, channels/, " +
         "fastagent.config.ts, package.json, .secrets/.env — restart the worker. Files the agent writes as " +
         "work product never trigger a restart.",
@@ -112,7 +113,7 @@ const chat = {
 const info = {
     name: "info",
     summary: "print what the directory assembles into, without serving",
-    description: "Print what dir (default .) ASSEMBLES into — model, persona, context files (AGENTS.md), skills, " +
+    description: "Print what dir (default .) ASSEMBLES into — model, prompt, context files (AGENTS.md), skills, " +
         "tools (+ collisions), channels, schedules, sessions, load diagnostics — WITHOUT serving. " +
         "Read-only (never creates sessions / writes .gitignore); an unset model is reported, not fatal. " +
         "Run it first when something looks off.",

package/dist/cli/shared.d.ts

@@ -4,11 +4,37 @@ import { type IndirectTool } from "../engines/pi/create.ts";
 import type { LoadedDefinition } from "../engines/pi/definition.ts";
 import type { ToolCollision } from "../engines/pi/tool.ts";
 import { type ResolvedPlacement } from "../paths.ts";
-/** How every command that runs the model enters its agent directory, in the one order that works. */
+/**
+ * How a command enters its agent directory, in the one order that works: placement, the agent's environment, then the
+ * first-run model picker. Returns the default model that then resolves, if any. `deploy` uses this directly: it gates
+ * a missing model itself, by what will ship.
+ */
+export declare function enterAgentDirectory(dirArg: string, opts: {
+    model?: string;
+    input?: boolean;
+}): Promise<ResolvedPlacement & {
+    modelSpec?: string;
+}>;
+/**
+ * How every command that RUNS the agent on this machine enters it (dev, start, invoke, routine run, chat):
+ * {@link enterAgentDirectory}, plus a default model. The agent opens without one, but a process here would then fail
+ * every new conversation, so it stops at startup with {@link missingDefaultModel} instead.
+ */
 export declare function enterAgentCommand(dirArg: string, opts: {
     model?: string;
     input?: boolean;
-}): Promise<ResolvedPlacement>;
+}): Promise<ResolvedPlacement & {
+    modelSpec: string;
+}>;
+/**
+ * The startup half of {@link enterAgentCommand}, for the one command that checks something of its own in between:
+ * `routine run`, whose unknown name or unset secret is the more basic fault and is reported first.
+ */
+export declare function requireDefaultModel(placement: ResolvedPlacement & {
+    modelSpec?: string;
+}): ResolvedPlacement & {
+    modelSpec: string;
+};
 /** What the startup report reads off an opened directory. */
 export interface ReportableAssembly {
     agentDir: string;

package/dist/cli/shared.js

@@ -6,26 +6,48 @@ import { readFile, writeFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
-import { isValidPort, listModels, loadConfig, providerOf, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
+import { isValidPort, listModels, loadConfig, missingDefaultModel, providerOf, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
 import { readMachine, withMachine } from "../engines/pi/machine.js";
 import { providerAuthStatuses } from "../engines/pi/models.js";
 import { agentModels } from "../engines/pi/agent-models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
-import { describeIndirectTools, reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
+import { describeIndirectTools, describePrompt, reportFindingsIfChanged, reportToolCollisions, } from "../engines/pi/report.js";
 import { isDeployedWorkspace } from "../paths.js";
 import { log } from "../log.js";
 import { enterAgentEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
 import { bindAddress, isBindAddress } from "../bind.js";
 import { failStartup, failUsage, placementOrExit } from "./fail.js";
-/** How every command that runs the model enters its agent directory, in the one order that works. */
-export async function enterAgentCommand(dirArg, opts) {
+/**
+ * How a command enters its agent directory, in the one order that works: placement, the agent's environment, then the
+ * first-run model picker. Returns the default model that then resolves, if any. `deploy` uses this directly: it gates
+ * a missing model itself, by what will ship.
+ */
+export async function enterAgentDirectory(dirArg, opts) {
     const placement = placementOrExit(resolve(dirArg));
     enterAgentEnv(placement.agentDir);
-    await resolveFirstRunModel(placement, opts);
-    return placement;
+    const modelSpec = await resolveFirstRunModel(placement, opts);
+    return { ...placement, ...(modelSpec ? { modelSpec } : {}) };
+}
+/**
+ * How every command that RUNS the agent on this machine enters it (dev, start, invoke, routine run, chat):
+ * {@link enterAgentDirectory}, plus a default model. The agent opens without one, but a process here would then fail
+ * every new conversation, so it stops at startup with {@link missingDefaultModel} instead.
+ */
+export async function enterAgentCommand(dirArg, opts) {
+    return requireDefaultModel(await enterAgentDirectory(dirArg, opts));
+}
+/**
+ * The startup half of {@link enterAgentCommand}, for the one command that checks something of its own in between:
+ * `routine run`, whose unknown name or unset secret is the more basic fault and is reported first.
+ */
+export function requireDefaultModel(placement) {
+    const { modelSpec } = placement;
+    if (!modelSpec)
+        failStartup(missingDefaultModel());
+    return { ...placement, modelSpec };
 }
 /** The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). */
 function reportLine(label, value) {
@@ -40,8 +62,7 @@ export async function reportAssembly(a, extras = {}) {
     reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
     await reportAuth(a.models, a.modelSpec);
     reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    if (a.definition.persona)
-        reportLine("persona", "persona.md");
+    reportLine("prompt", describePrompt(a.definition));
     // What this agent HAS — the definition's skills and the ones its machine lends (machine.ts).
     const skills = withMachine(a.definition.skills, (await readMachine(a.workspace)).skills);
     reportLine("skills", skills.map((s) => s.name).join(", ") || "(none)");
@@ -108,21 +129,23 @@ export async function reportAuth(models, modelSpec) {
  */
 async function resolveFirstRunModel({ agentDir, workspace }, options = {}) {
     const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
-    if (resolveModelSpec(options.model, config))
-        return; // already set (flag > FASTAGENT_MODEL > config)
+    const configured = resolveModelSpec(options.model, config);
+    if (configured)
+        return configured; // already set (flag > FASTAGENT_MODEL > config)
     if (options.input === false)
-        return; // --no-input: never prompt (clig) — the opener raises the clear error
+        return undefined; // --no-input: never prompt (clig) — the caller decides what's missing
     if (!isInteractive())
-        return; // CI/deploy: the opener throws the actionable missing-model error
+        return undefined; // CI/deploy: the caller raises the actionable missing-model error
     const environment = agentModels(agentDir, {}, { cwd: workspace });
     // The picker lists the AGENT's surface: built-ins plus whatever its models.json declares, so a self-hosted endpoint
     // is pickable on first run instead of being invisible until hand-set.
     const models = await environment.runtime().catch(failStartup);
     const chosen = await pickWithCredentials(models, environment.auth.path, agentDir);
     if (chosen === undefined)
-        return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
+        return undefined; // cancelled (or auth probe failed): the caller raises its clear error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
     await persistModelChoice(agentDir, configPath, chosen);
+    return chosen;
 }
 /** The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy. */
 async function pickWithCredentials(models, authPath, agentDir) {

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.ts";
-export { ABORTED_CODE, SESSION_BUSY_CODE } from "./agent.ts";
+export { ABORTED_CODE, MISSING_MODEL_CODE, SESSION_BUSY_CODE } from "./agent.ts";
 export { collect, AgentFailure, type CollectResult } from "./collect.ts";
 export type { ModuleLoadFailure } from "./loader.ts";
 export { createInvokeHandler } from "./channels/http.ts";

package/dist/core.js

@@ -1,7 +1,8 @@
-// VALUES, not types: each caller does something DIFFERENT with these two codes (retry with backoff, skip the
-// occurrence, steer the live run instead of failing), which is why they are named at all. Without an export an
-// embedder copies the literal, and the copy is how the first-event rule goes silently wrong.
-export { ABORTED_CODE, SESSION_BUSY_CODE } from "./agent.js";
+// VALUES, not types: each caller does something DIFFERENT with these codes (busy: retry with backoff, skip the
+// occurrence, or steer the live run instead of failing; aborted: settle a deliberate stop, never replay it;
+// missing_model: do not retry, give the session a model or the agent a default), which is why they are named at all.
+// Without an export an embedder copies the literal, and the copy is how the first-event rule goes silently wrong.
+export { ABORTED_CODE, MISSING_MODEL_CODE, SESSION_BUSY_CODE } from "./agent.js";
 export { collect, AgentFailure } from "./collect.js";
 export { createInvokeHandler } from "./channels/http.js";
 export { ControlRequestError, connectAgent, connectSessionControl, } from "./session-remote.js";

package/dist/deploy/build-context.js

@@ -116,7 +116,7 @@ export async function checkKeptIgnoreFiles(ctx, report) {
         // Asked as a DIRECTORY (trailing slash), which is what it is.
         if (excluded(`${basename(agentDir)}/`)) {
             const text = `your ${rel} (kept) excludes \`${basename(agentDir)}\` — the build context would ship WITHOUT the ` +
-                `agent entirely (the deployed box has no persona/config and crash-loops). Remove that rule ` +
+                `agent entirely (the deployed box has no prompt/config and crash-loops). Remove that rule ` +
                 `before deploying.`;
             report.issue(text);
         }

package/dist/deploy/preflight.js

@@ -13,6 +13,7 @@ import { AGENT_MODEL_CATALOG_FILE, AGENT_MODELS_FILE, exists } from "../paths.js
 import { inspectChannels } from "../channels/discover.js";
 import { loadRoutines } from "../schedule/discover.js";
 import { resolveAgentTools } from "../engines/pi/create.js";
+import { loadAgentDefinition } from "../engines/pi/definition.js";
 import { agentModels } from "../engines/pi/agent-models.js";
 import { allSecrets } from "../declared-secrets.js";
 import { createPiModelRuntime, definitionKeyOf, environmentAuthSource, literalKeyProviders, isBuiltinProvider, machineModels, globalCatalogPath, inGlobalCatalog, interactiveLoginKind, loginProviders, } from "../engines/pi/models.js";
@@ -64,6 +65,13 @@ async function gatherFacts(input, report) {
             `makes it an agent, never its name)`);
     }
     const agentPrefix = `${basename(agentDir)}/`;
+    // The definition the box will load on every start, loaded here first: a refusal in it (a leftover persona.md, a
+    // skill named with a slash) builds a perfectly good image that crash-loops on fly/railway/docker and fails every
+    // invocation on AgentCore. This is the boundary that turns that refusal into a deploy finding, so the error is
+    // carried whole into the issue rather than rethrown.
+    await loadAgentDefinition(agentDir, { cwd: workspace }).catch((error) => {
+        report.issue(`the definition does not load, so the deployed agent would not start: ${error instanceof Error ? error.message : String(error)}`);
+    });
     // The model this deployment will run on, and where it came from. Resolved HERE so the plan side and the run side
     // cannot disagree about it.
     const valueFile = relative(workspace, dotEnvPath(agentDir));
@@ -232,7 +240,7 @@ async function gatherFacts(input, report) {
     }
     const paths = await buildContextPaths(workspace, agentDir, agentPrefix, authPath);
     await checkKeptIgnoreFiles({ workspace, agentDir, agentPrefix, force, paths }, report);
-    // Write-back mechanics are fastagent's (the policy is the persona's).
+    // Write-back mechanics are fastagent's (the policy is the agent's prompt's).
     const apt = shipsGit ? [...new Set(["git", ...(config.deploy?.apt ?? [])])] : config.deploy?.apt;
     const container = {
         releaseId: randomUUID(),

package/dist/dev-supervisor.js

@@ -119,7 +119,7 @@ export async function runDevSupervisor(placement, options = {}) {
         timer = setTimeout(triggerReload, 200);
     });
     watcher.on("error", (error) => log.warn(`[fastagent] file watching error (${error.message}); some edits may need a manual restart`));
-    log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); AGENTS.md/persona.md/skills edits go live next turn without a restart`);
+    log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); AGENTS.md/SYSTEM.md/APPEND_SYSTEM.md/skills/prompts edits go live next turn without a restart`);
     // FASTAGENT_SECRETS_DIR can move the `.env` OUT of the agent dir entirely.
     if (!isUnderDir(dotEnvPath(placement.agentDir), placement.agentDir)) {
         log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR → ${dotEnvPath(placement.agentDir)}) — it is NOT watched; restart dev after editing it`);

package/dist/engines/pi/agent-session-factory.d.ts

@@ -5,9 +5,23 @@ import type { PiAgentSessionFactory } from "./invoke-session.ts";
 import type { PiSessionRecordStore } from "./session-store.ts";
 import type { MountedTool } from "./tool.ts";
 import { type AnyModel } from "./models.ts";
-interface PiSessionDefinition {
+import type { DefinitionPrompt } from "./definition.ts";
+/** What one binding reads from the definition: the prompt pieces, skills and prompt templates pi is handed. */
+export interface PiSessionDefinition {
+    /** Replaces pi's default prompt when set (`SYSTEM.md`, L2's `base`, L1's `instructions`); absent → pi's default. */
     systemPrompt?: string;
+    /** Added after the prompt, whichever it is (`APPEND_SYSTEM.md`). */
+    appendSystemPrompt?: string;
+    /** Project instructions (AGENTS.md); pi renders them as its project context. */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** FastAgent's own named prompt sections: pi renders them after its own, whoever wrote the rest. */
+    sections?: Record<string, string>;
     skills: Skill[];
+    /** The definition's own prompt templates; the machine's are added behind them. */
+    prompts?: DefinitionPrompt[];
 }
 export interface PiAgentSessionFactoryOptions {
     /** Where conversations live. */
@@ -16,8 +30,11 @@ export interface PiAgentSessionFactoryOptions {
     engine: () => Promise<{
         modelRuntime: ModelRuntime;
     }>;
-    /** Resolved after extensions register their models. */
-    modelSpec: string;
+    /**
+     * The default model, resolved after extensions register their models. Optional: a session that records a model
+     * runs on it, and one that records none is refused with {@link MissingModel} when there is no default either.
+     */
+    modelSpec?: string;
     thinkingLevel?: ThinkingLevel;
     tools?: MountedTool[];
     /** Read once per binding; prompt and skills come from the same definition read. */
@@ -52,8 +69,7 @@ export declare function bindPiSession(options: BindPiSessionOptions): ReturnType
 type DefinitionLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
 /** The resource posture a fastagent definition asks pi for — ONE definition of it, for both assemblies. */
 export declare function definitionResourceLoaderOptions(source: {
-    systemPrompt: () => string | undefined;
-    skills: () => Skill[];
+    definition: PiSessionDefinition;
     /** {@link readMachine} for this workspace — resolved by the caller, because this function is synchronous. */
     machine: Machine;
     extensionPaths?: readonly string[];