@fastagent-sh/fastagent 0.24.1 → 0.24.3

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

@@ -17,7 +17,7 @@ export 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.

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

@@ -47,10 +47,21 @@ export interface SessionSettings {
         };
     };
 }
-/** `defaults` is the assembly's configured pair — what a session with no overrides runs on. */
+/**
+ * `defaults` is the assembly's configured pair — what a session with no overrides runs on. An agent may set no default
+ * model, so a session runs on the model it records, else the default, else none: undefined then, and the session
+ * cannot run until it is given one ({@link MissingModel}).
+ */
 export declare function resolveSessionSettings(entries: OverrideEntryLike[], models: Models, defaults: {
-    model: AnyModel;
+    model?: AnyModel;
     thinkingLevel: ThinkingLevel;
-}): SessionSettings;
+}): SessionSettings | undefined;
+/**
+ * A turn has no model to run on: its session records none this registry knows, and the agent sets no default. Its own
+ * class so the invoke answers it with `missing_model` instead of a prose failure.
+ */
+export declare class MissingModel extends Error {
+    constructor(session: string, entries: OverrideEntryLike[]);
+}
 /** The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks. */
 export declare function activePath(record: SessionManager, from?: string): OverrideEntryLike[];

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

@@ -51,7 +51,11 @@ export function lastOverrideEntries(entries) {
     }
     return { model, thinkingLevel };
 }
-/** `defaults` is the assembly's configured pair — what a session with no overrides runs on. */
+/**
+ * `defaults` is the assembly's configured pair — what a session with no overrides runs on. An agent may set no default
+ * model, so a session runs on the model it records, else the default, else none: undefined then, and the session
+ * cannot run until it is given one ({@link MissingModel}).
+ */
 export function resolveSessionSettings(entries, models, defaults) {
     const recorded = lastOverrideEntries(entries);
     const dropped = {};
@@ -64,6 +68,8 @@ export function resolveSessionSettings(entries, models, defaults) {
         else
             dropped.model = `${recorded.model.provider}/${recorded.model.modelId}`;
     }
+    if (!model)
+        return undefined;
     const availableThinkingLevels = getSupportedThinkingLevels(model);
     let thinkingLevel = clampThinkingLevel(model, defaults.thinkingLevel);
     if (recorded.thinkingLevel !== undefined) {
@@ -87,6 +93,19 @@ export function resolveSessionSettings(entries, models, defaults) {
         ...(dropped.model || dropped.thinkingLevel ? { dropped } : {}),
     };
 }
+/**
+ * A turn has no model to run on: its session records none this registry knows, and the agent sets no default. Its own
+ * class so the invoke answers it with `missing_model` instead of a prose failure.
+ */
+export class MissingModel extends Error {
+    constructor(session, entries) {
+        const recorded = lastOverrideEntries(entries).model;
+        super(`session "${session}" has no model: ${recorded
+            ? `the model it records, ${recorded.provider}/${recorded.modelId}, is not one this agent knows,`
+            : "it records none,"} and the agent sets no default — give the session one (session control's update({ model })), or the agent ` +
+            `a default ("model" in fastagent.config.ts, or FASTAGENT_MODEL)`);
+    }
+}
 /** The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks. */
 export function activePath(record, from) {
     // `from` asks a different question: the path a leaf move is ABOUT to make active, which a caller validating a patch

package/dist/engines/pi/turn-kit.d.ts

@@ -1,4 +1,4 @@
-import { type AssistantMessage, type ImageContent } from "@earendil-works/pi-ai";
+import { type AssistantMessage, type ImageContent, type ToolResultMessage } from "@earendil-works/pi-ai";
 import { type AgentEvent, type Prompt } from "../../agent.ts";
 import type { AnswerOutcome, PromptDisposition, SessionEvent } from "../../session.ts";
 export type Release = () => void;
@@ -18,6 +18,36 @@ export declare function classifyRetryable(details: string, signal: {
  * the recorded one cannot disagree.
  */
 export declare function answerOutcome(message: AssistantMessage): AnswerOutcome | undefined;
+/**
+ * An answer's recorded thinking: its published thinking blocks, in order, joined with nothing between them, exactly as
+ * their live deltas add up (the stream marks no block boundary, and the answer's `text` is joined the same way).
+ * Undefined when it has none.
+ */
+export declare function answerThinking(message: AssistantMessage): string | undefined;
+/** Whether a live thinking delta is streamed: the block it extends is one {@link answerThinking} will publish. */
+export declare function streamsThinkingDelta(event: {
+    contentIndex: number;
+    partial: AssistantMessage;
+}): boolean;
+/**
+ * Whether a finished tool call asked to end its run (pi's `terminate`: returned by the tool, or set by a `tool_call`
+ * hook that blocks it; pi 0.99.2's `tool_result` hook cannot set it). After a batch whose EVERY result asks it, pi
+ * makes no further model call for that batch, so unless a queued steer or follow-up continues the run, it completes on
+ * `tool` entries with no answer after them: the same shape a process killed after its tools leaves. A call made from
+ * inside another tool (`parentToolCallId`, a codemode script) is not in the batch and does not count.
+ * The ONE reading: the live `tool_finished` and the flag {@link markEndsRun} records both come from it.
+ */
+export declare function asksToEndRun(event: {
+    result?: unknown;
+    parentToolCallId?: string;
+}): boolean;
+/**
+ * The tool result message as pi then records it, carrying the request: pi's `createToolResultMessage` drops
+ * `terminate` (as of pi 0.99.2), so without this nothing in the record says the run ended on purpose.
+ */
+export declare function markEndsRun(message: ToolResultMessage): ToolResultMessage;
+/** Whether a recorded tool result carries {@link markEndsRun}'s flag. */
+export declare function endsRun(message: ToolResultMessage): boolean;
 /**
  * Terminal mapping, decided by the resolved message's outcome: pi's `prompt()` RESOLVES a message with stopReason
  * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate

package/dist/engines/pi/turn-kit.js

@@ -1,6 +1,6 @@
 /** The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. */
 import { stripVTControlCharacters } from "node:util";
-import { contentText } from "@earendil-works/pi-ai";
+import { contentText, } from "@earendil-works/pi-ai";
 import { ABORTED_CODE } from "../../agent.js";
 import { log } from "../../log.js";
 export function inProcessLease() {
@@ -91,6 +91,59 @@ export function answerOutcome(message) {
             return undefined;
     }
 }
+/**
+ * Whether a thinking block is PUBLISHED: readable reasoning. A redacted one holds a provider's opaque payload and a
+ * placeholder (pi writes "[Reasoning redacted]" for it), not reasoning anyone can read, so it is neither streamed nor
+ * read back. The ONE rule: the live `message_delta { channel: "thinking" }` ({@link streamsThinkingDelta}) and the
+ * `assistant` entry's `thinking` ({@link answerThinking}) both apply it, so a client reads the same text either way.
+ *
+ * One exception, by when the flag is read: live reads it as each delta arrives, the record as the answer ended. pi's
+ * Bedrock path flags a block redacted when its first encrypted chunk arrives, and its readable text and its encrypted
+ * chunks are separate fields, so a block that streamed readable text BEFORE turning redacted had that text streamed
+ * and is then not read back. Not separable after the fact: the record keeps one flag and one string per block, with
+ * pi's placeholder appended. Whether a Bedrock model sends both in one block is unverified.
+ */
+function isPublishedThinking(block) {
+    return block?.type === "thinking" && block.redacted !== true;
+}
+/**
+ * An answer's recorded thinking: its published thinking blocks, in order, joined with nothing between them, exactly as
+ * their live deltas add up (the stream marks no block boundary, and the answer's `text` is joined the same way).
+ * Undefined when it has none.
+ */
+export function answerThinking(message) {
+    const text = message.content
+        .filter(isPublishedThinking)
+        .map((block) => block.thinking)
+        .join("");
+    return text === "" ? undefined : text;
+}
+/** Whether a live thinking delta is streamed: the block it extends is one {@link answerThinking} will publish. */
+export function streamsThinkingDelta(event) {
+    return isPublishedThinking(event.partial.content[event.contentIndex]);
+}
+/**
+ * Whether a finished tool call asked to end its run (pi's `terminate`: returned by the tool, or set by a `tool_call`
+ * hook that blocks it; pi 0.99.2's `tool_result` hook cannot set it). After a batch whose EVERY result asks it, pi
+ * makes no further model call for that batch, so unless a queued steer or follow-up continues the run, it completes on
+ * `tool` entries with no answer after them: the same shape a process killed after its tools leaves. A call made from
+ * inside another tool (`parentToolCallId`, a codemode script) is not in the batch and does not count.
+ * The ONE reading: the live `tool_finished` and the flag {@link markEndsRun} records both come from it.
+ */
+export function asksToEndRun(event) {
+    return !event.parentToolCallId && event.result?.terminate === true;
+}
+/**
+ * The tool result message as pi then records it, carrying the request: pi's `createToolResultMessage` drops
+ * `terminate` (as of pi 0.99.2), so without this nothing in the record says the run ended on purpose.
+ */
+export function markEndsRun(message) {
+    return { ...message, terminate: true };
+}
+/** Whether a recorded tool result carries {@link markEndsRun}'s flag. */
+export function endsRun(message) {
+    return message.terminate === true;
+}
 /**
  * Terminal mapping, decided by the resolved message's outcome: pi's `prompt()` RESOLVES a message with stopReason
  * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate

package/dist/paths.d.ts

@@ -23,7 +23,7 @@ export declare const AGENT_MODELS_FILE = "models.json";
 export declare const AGENT_MODEL_CATALOG_FILE = "models-store.json";
 export interface ResolvedPlacement {
     /**
-     * The AGENT directory — where the definition (persona.md/skills/tools/channels/routines), the config, and the
+     * The AGENT directory — where the definition (SYSTEM.md/skills/tools/channels/routines), the config, and the
      * machinery dirs (`.secrets/`, `.state/`) live.
      */
     agentDir: string;

package/dist/paths.js

@@ -35,7 +35,18 @@ export const AGENT_MODEL_CATALOG_FILE = "models-store.json";
  * The definition paths an agent LOADS content from — the surface a second agent must not be scaffolded inside
  * ({@link agentDefinitionOwner}), because the outer agent would read it as its own skills/tools.
  */
-const LOADED_SURFACE = ["persona.md", "skills", "tools", "channels", "routines"];
+const LOADED_SURFACE = [
+    "SYSTEM.md",
+    "APPEND_SYSTEM.md",
+    "skills",
+    "prompts",
+    "tools",
+    "channels",
+    "routines",
+    // pi's and the standard spellings the definition also reads: `.pi/skills`, `.pi/prompts`, `.agents/skills`.
+    ".pi",
+    ".agents",
+];
 /**
  * "Not there" and "could not look" are different answers, and only the first may read as an absence: an agent
  * directory the caller cannot enter (EACCES) reported as no-agent-here ends in `run \`fastagent init\` to

package/dist/pi.d.ts

@@ -6,7 +6,7 @@ export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-
 /** A conversation record, as the tool runtime and the control plane hold it. */
 export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
 export { availableModelsFromDir, createPiAgentFromDir, type CreatePiAgentFromDirOptions, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.ts";
-export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
+export type { DefinitionDiagnostic, DefinitionFile, DefinitionPrompt, DefinitionShadow, LoadedDefinition, SkillCollision, } from "./engines/pi/definition.ts";
 export { defineConfig, listModels, resolveModel, type FastagentConfig, } from "./engines/pi/config.ts";
 export type { SessionObserver } from "./engines/pi/turn-kit.ts";
 export { inProcessLease, type Lease, type Release } from "./engines/pi/turn-kit.ts";

package/dist/scaffold/init.js

@@ -35,8 +35,8 @@ export async function scaffoldAgent(dir, options = {}) {
         content: baseTemplate(`skills/writing-great-skills/${name}`),
     });
     const files = [
-        // ① identity.
-        { rel: join(root, "persona.md"), content: baseTemplate("persona.md") },
+        // Standing instructions, added to pi's default prompt (SYSTEM.md would replace it).
+        { rel: join(root, "APPEND_SYSTEM.md"), content: baseTemplate("APPEND_SYSTEM.md") },
         // The example skill: how to author skills well — the core of self-iteration.
         skill("SKILL.md"),
         skill("GLOSSARY.md"),

package/dist/scaffold/templates/APPEND_SYSTEM.md

@@ -0,0 +1,12 @@
+# Standing instructions
+
+These instructions are added to your system prompt on every turn. This file, `APPEND_SYSTEM.md`, is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `prompts/` — prompt templates; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart.
+
+Your definition is this directory: `APPEND_SYSTEM.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on. It may be this same directory, or the one containing it; `fastagent info` prints both. Use only the tools actually listed in your system prompt. If the workspace has an `AGENTS.md`, it is project context — follow it without assuming a file tool is available.
+
+When your mounted tools allow it, you can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
+
+- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
+- A standing instruction or fact → edit this file.
+
+Keep both lean: include only what changes your behavior, and delete what no longer earns its place.

package/dist/scaffold/templates/fastagent.config.ts

@@ -1,5 +1,5 @@
 // fastagent.config.ts — deployment choices only (model / http; code tools auto-discover from tools/).
-// Your agent's identity lives in persona.md; its capabilities in skills/ + tools/ — never here.
+// Your agent's prompt lives in SYSTEM.md / APPEND_SYSTEM.md; its capabilities in skills/ + tools/ — never here.
 // An AGENTS.md in the WORKSPACE (the directory the agent is started in) is read as project context.
 // Model precedence: `--model` flag > FASTAGENT_MODEL env > this default.
 // No model is preset: `fastagent dev` shows the full model catalog (models you already have

package/dist/session.d.ts

@@ -347,6 +347,10 @@ export type UserMessageEvent = SessionEvent<"user_message", {
 }> & {
     runId: string;
 };
+/**
+ * A piece of the answer being written. The `thinking` deltas of one answer add up to its `assistant` entry's
+ * `thinking`, as its `text` deltas add up to its `text`; redacted reasoning is streamed in neither.
+ */
 export type MessageDeltaEvent = SessionEvent<"message_delta", {
     channel: "text" | "thinking";
     delta: string;
@@ -388,11 +392,17 @@ export type ToolProgressEvent = SessionEvent<"tool_progress", {
 }> & {
     runId: string;
 };
+/**
+ * `terminate: true` when the call asked to end its run. Once every call answering one assistant message asks it, the
+ * model is not called again for them, and the run ends there with no answer after its `tool` entries (which carry the
+ * same flag) unless a queued steer or follow-up continues it. Whether the run ended is `run_settled`'s to say.
+ */
 export type ToolFinishedEvent = SessionEvent<"tool_finished", {
     id: string;
     isError: boolean;
     content: Json;
     parentToolCallId?: string;
+    terminate?: true;
 }> & {
     runId: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.24.1",
+  "version": "0.24.3",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",

package/dist/scaffold/templates/persona.md

@@ -1,12 +0,0 @@
-# Persona
-
-You are this workspace's agent. This file is your identity — it overrides the engine's default identity line, and it is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart.
-
-Your definition is this directory: `persona.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on. It may be this same directory, or the one containing it; `fastagent info` prints both. Use only the tools actually listed in your system prompt. If the workspace has an `AGENTS.md`, it is project context — follow it without assuming a file tool is available.
-
-When your mounted tools allow it, you can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
-
-- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Only the `skills/` next to this file is scanned. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
-- A standing instruction or fact → edit this file.
-
-Keep both lean: include only what changes your behavior, and delete what no longer earns its place.