@fastagent-sh/fastagent 0.14.0 → 0.16.0

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

@@ -32,9 +32,9 @@ export interface LoadedDefinition {
 }
 export interface LoadAgentDefinitionOptions {
     /**
-     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`
-     * (flat: the agent dir is also the run root). The opener passes the run root so a coding agent that
-     * lives in `agentDir` picks up the host repo's AGENTS.md up the tree (core.md scenario grid).
+     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`.
+     * The opener passes the workspace instead, so an agent that lives in `agentDir` picks up the
+     * project's AGENTS.md up the tree (core.md scenario grid).
      */
     cwd?: string;
     env?: ExecutionEnv;
@@ -42,31 +42,12 @@ export interface LoadAgentDefinitionOptions {
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
 export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
 /**
- * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
- * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
- * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
- * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
- * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
  */
 export declare function isUnderDir(targetPath: string, baseDir: string): boolean;
-/**
- * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
- * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
- * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
- * write a `.gitignore` bypassing this.
- *
- * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
- * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
- * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
- * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
- * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
- * `.gitignore` into it (it may be a directory the operator deliberately tracks).
- *
- * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
- * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
- * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
- */
-export declare function ensureStateRootSelfIgnored(dir: string, stateRoot: string): Promise<void>;
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export declare function canonicalPath(p: string): string;

package/dist/engines/pi/definition.js

@@ -14,12 +14,11 @@
  * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
  */
 import { realpathSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { 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 { assertInsideAgentDir } from "../../paths.js";
 /** Read an agent definition. persona.md/skills come from `agentDir`; ② context = 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
@@ -44,7 +43,9 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     }
     const persona = personaRead.ok ? personaRead.value : undefined;
     // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
-    // definition loads the same skills on every machine.
+    // definition loads the same skills on every machine — and, like tools/channels/schedules, a symlink
+    // that escapes the agent dir is refused rather than followed (the fourth of four surfaces).
+    await assertInsideAgentDir(root, "skills");
     const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")]);
     const byName = new Map();
     const collisions = [];
@@ -60,62 +61,15 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     return { contextFiles, persona, skills: [...byName.values()], diagnostics, collisions, dir: root };
 }
 /**
- * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
- * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
- * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
- * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
- * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
  */
 export function isUnderDir(targetPath, baseDir) {
     const rel = relative(baseDir, targetPath);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-/**
- * Self-ignore a state dir: create it if missing, then write `<stateDir>/.gitignore` = "*" (idempotent
- * — an existing one is kept), so a workspace that runs dev/start never shows machine state as
- * untracked. Creates the dir because a caller may self-ignore it before anything else populates it
- * (e.g. `login` writing auth.json into a not-yet-created root).
- *
- * Module-PRIVATE on purpose: the only entry to the leak guard is {@link ensureStateRootSelfIgnored}
- * (home exclusion + containment). Keeping this unexported makes that single-owner claim hold at the
- * type level — a sibling command can't bypass those checks by writing a `.gitignore` directly.
- */
-async function ensureStateDirSelfIgnored(stateDir) {
-    await mkdir(stateDir, { recursive: true });
-    await writeFile(join(stateDir, ".gitignore"), "*\n", { flag: "wx" }).catch((e) => {
-        if (e.code !== "EEXIST")
-            throw e;
-    });
-}
-/**
- * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
- * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
- * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
- * write a `.gitignore` bypassing this.
- *
- * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
- * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
- * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
- * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
- * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
- * `.gitignore` into it (it may be a directory the operator deliberately tracks).
- *
- * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
- * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
- * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
- */
-export async function ensureStateRootSelfIgnored(dir, stateRoot) {
-    // Compare CANONICAL paths for the home check: `dir` arrives realpath-resolved (it is `process.cwd()`
-    // or `resolve(".")`) but `homedir()` returns the raw `$HOME`, so a symlinked home would slip past raw
-    // equality and we'd write a `.gitignore` into the real `~/.fastagent` — the very thing the doc forbids
-    // (chat.ts canonicalizes for the same reason).
-    if (canonicalPath(dir) === canonicalPath(homedir()))
-        return;
-    // Containment on RAW paths: stateRoot is resolve()'d (config.ts) and `dir` is absolute, so it is exact
-    // by construction. An external-volume root resolves outside the tree → skip (not ours to ignore).
-    if (isUnderDir(stateRoot, dir))
-        await ensureStateDirSelfIgnored(stateRoot);
-}
 /** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
  *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
 export function canonicalPath(p) {

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

@@ -60,6 +60,55 @@ export interface PiHarnessFactoryOptions {
         skills?: Skill[];
     }>;
 }
+/**
+ * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
+ * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
+ * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
+ * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
+ */
+export declare const SUMMARIZATION_RETRY_POLICY: {
+    readonly enabled: true;
+    readonly maxRetries: 3;
+    readonly baseDelayMs: 2000;
+};
+export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
+/** The shape both override consumers walk — a session entry, structurally. */
+export interface OverrideEntryLike {
+    type: string;
+    provider?: string;
+    modelId?: string;
+    thinkingLevel?: string;
+}
+/**
+ * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
+ * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
+ * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
+ * skipped over to an earlier record: the reporting surface and the execution surface must agree on
+ * which record is "the" override.
+ */
+export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    thinkingLevel?: string;
+};
+/**
+ * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
+ * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
+ * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
+ * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
+ * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
+ * back to the default with a deduped warn (fail visibly without bricking the session — the
+ * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ */
+export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel;
+}, sessionId: string): {
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel;
+};
 export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: AgentTool[], sessionId: string): string[] | undefined;
 /** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
 export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;

package/dist/engines/pi/harness.js

@@ -38,6 +38,13 @@ export function harnessSession(harness) {
  * so a mid-stream failure surfaces as a `failed` event.
  */
 const PROVIDER_MAX_RETRIES = 2;
+/**
+ * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
+ * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
+ * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
+ * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
+ */
+export const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDelayMs: 2000 };
 /**
  * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
  * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
@@ -69,6 +76,84 @@ const DEFAULT_THINKING_LEVEL = "medium";
  * (like L2's findings memo), not session state — the resolve stays derived from the session.
  */
 const warnedRestores = new Set();
+/** pi's ThinkingLevel scale as a checkable set — THE single source for fastagent (session entries
+ *  store plain strings; session-control's dispatch validation and capabilities derive from this).
+ *  The `satisfies Record<ThinkingLevel, …>` anchor makes it EXHAUSTIVE against pi's union: pi
+ *  adding a level turns this into a type error instead of a silent drift where `set_thinking`
+ *  rejects a value pi supports. */
+const ALL_THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
+/**
+ * The session's durable override FACTS — the ONE walk both surfaces consume (`state()` reports the
+ * recorded truth; `resolveHarnessOverrides` below applies registry/scale fallbacks on top). The
+ * LAST entry of each kind wins, and a malformed record reads as ABSENT for that kind — never
+ * skipped over to an earlier record: the reporting surface and the execution surface must agree on
+ * which record is "the" override.
+ */
+export function lastOverrideEntries(entries) {
+    let model;
+    let modelSeen = false;
+    let thinkingLevel;
+    let thinkingSeen = false;
+    for (let i = entries.length - 1; i >= 0 && !(modelSeen && thinkingSeen); i--) {
+        const e = entries[i];
+        if (!modelSeen && e?.type === "model_change") {
+            modelSeen = true;
+            if (e.provider !== undefined && e.modelId !== undefined)
+                model = { provider: e.provider, modelId: e.modelId };
+        }
+        if (!thinkingSeen && e?.type === "thinking_level_change") {
+            thinkingSeen = true;
+            if (e.thinkingLevel !== undefined)
+                thinkingLevel = e.thinkingLevel;
+        }
+    }
+    return { model, thinkingLevel };
+}
+/**
+ * Resolve the session's model/thinking OVERRIDES for a fresh harness — same shape as the
+ * active-tools resolve above: pi writes `model_change`/`thinking_level_change` entries on explicit
+ * setModel/setThinkingLevel (the control plane's `set_model`/`set_thinking` append them directly)
+ * but a fresh harness never reads them back. Override facts come from {@link lastOverrideEntries};
+ * this adds the EXECUTION fallbacks: a recorded model no longer in this deployment's registry falls
+ * back to the default with a deduped warn (fail visibly without bricking the session — the
+ * conversation must survive a registry change across deploys); an unknown thinking level likewise.
+ */
+export function resolveHarnessOverrides(entries, models, defaults, sessionId) {
+    let model = defaults.model;
+    let thinkingLevel = defaults.thinkingLevel;
+    const warnOnce = (key, message) => {
+        const emit = warnedRestores.has(key) ? log.debug : log.warn;
+        warnedRestores.add(key);
+        emit(message);
+    };
+    const recorded = lastOverrideEntries(entries);
+    if (recorded.model) {
+        const found = models.getModel(recorded.model.provider, recorded.model.modelId);
+        if (found)
+            model = found;
+        else {
+            warnOnce(`${sessionId}\u0000model\u0000${recorded.model.provider}/${recorded.model.modelId}`, `[fastagent] session ${sessionId}: recorded model override ${recorded.model.provider}/${recorded.model.modelId} is not in this deployment's registry — using the configured default`);
+        }
+    }
+    if (recorded.thinkingLevel !== undefined) {
+        if (THINKING_LEVELS.has(recorded.thinkingLevel)) {
+            thinkingLevel = recorded.thinkingLevel;
+        }
+        else {
+            warnOnce(`${sessionId}\u0000thinking\u0000${recorded.thinkingLevel}`, `[fastagent] session ${sessionId}: recorded thinking level "${recorded.thinkingLevel}" is unknown — using the configured default`);
+        }
+    }
+    return { model, thinkingLevel };
+}
 export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     const anyDeferred = tools.some(isDeferredTool);
     const initial = tools.filter((t) => !isDeferredTool(t)).map((t) => t.name);
@@ -99,17 +184,20 @@ export function piHarnessFactory(options) {
         const { systemPrompt } = options;
         const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
         const skills = fresh ? fresh.skills : options.skills;
+        // Session overrides (set_model / set_thinking) win over the assembly defaults — same entry walk.
+        const overrides = resolveHarnessOverrides(entries, options.models, { model: options.model, thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL }, sessionId);
         const harness = new AgentHarness({
             env: options.env,
             session,
             models: options.models,
-            model: options.model,
-            thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+            model: overrides.model,
+            thinkingLevel: overrides.thinkingLevel,
             tools: options.tools,
             activeToolNames: resolveHarnessActiveToolNames(activated.length > 0 ? activated : null, options.tools ?? [], sessionId),
             systemPrompt: prompt,
             resources: skills ? { skills } : undefined,
             streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
+            retry: SUMMARIZATION_RETRY_POLICY,
         });
         harnessSessions.set(harness, session);
         return harness;

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

@@ -1,5 +1,20 @@
+/**
+ * The turn mechanism (request-time): fan pi AgentHarness's two ports (subscribe event side-channel
+ * + prompt final value) into SPEC's single event stream, under a single-writer-per-session lease.
+ *
+ *   §1 Lease       — single-writer concurrency floor (injectable port + in-process default)
+ *   §2 translate   — the single pi↔SPEC translation point (both directions)
+ *   §3 EventQueue  — push→pull plumbing for pi's two-port shape
+ *   §4 createPiAgentFromHarness — composes §1–§3 into Agent.invoke
+ *
+ * Concurrency: at most one in-flight turn per session; a second invoke fails fast with
+ * `failed{retryable}` ("session busy"), leaving dedupe/queueing/steering to the channel. Each
+ * invoke builds a fresh harness bound to the session and discards it (stateless multi-session).
+ */
+import type { AgentHarnessEvent } from "@earendil-works/pi-agent-core";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import { type Agent, type AgentEvent } from "../../agent.ts";
+import { type Agent, type AgentEvent, type Prompt } from "../../agent.ts";
+import type { SessionEvent } from "../../session.ts";
 import { type PiHarnessFactory } from "./harness.ts";
 export type Release = () => void;
 export interface Lease {
@@ -12,17 +27,55 @@ export declare function classifyRetryable(details: string, signal: {
     status?: number;
     code?: unknown;
 }): boolean;
+/**
+ * In-stream event mapping — pi events are translated ONCE into the rich `SessionEvent` vocabulary;
+ * the SPEC `AgentEvent` stream is a narrow {@link projectAgentEvent} of it (design §6: one
+ * translation plus one projection, never two parallel translations). pi events with no session
+ * vocabulary yet (turn_start, agent_start, …) are dropped.
+ */
+export declare function toSessionEvent(pe: AgentHarnessEvent, runId: string): SessionEvent | null;
+/** The SPEC projection of the rich stream. Events with no `AgentEvent` counterpart (progress,
+ *  message boundaries, run boundaries) project to null — the invoke terminal is produced from the
+ *  resolved message ({@link toTerminal}), not from `run_settled`. */
+export declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
+/** Live modulation handles for one active run — what the control plane's `dispatch` routes to.
+ *  Built inside the invoke closure (it owns the harness); registered with the observer at
+ *  run_started, gone after run_settled. RACE WINDOW (all three commands, symmetric): the run may
+ *  resolve between the settled-check and the engine call landing — an accepted `abort` can still
+ *  settle `completed`, and an accepted `steer`/`followUp` can settle without the prompt ever being
+ *  consumed. Acceptance is not outcome; the settlement is the truth. */
+export interface RunControls {
+    steer(prompt: Prompt): Promise<void>;
+    followUp(prompt: Prompt): Promise<void>;
+    abort(): Promise<void>;
+}
+/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. `run`
+ *  carries the live {@link RunControls}, attached to the `run_started` event only. A hub
+ *  (session-control.ts) implements this to serve `events()`/`state()`/`dispatch`; absent = zero
+ *  overhead. Scope: RUN events only — the hub's own boundary-mutation events (`state_changed`,
+ *  `compaction_*`) originate in the hub and reach full-vocabulary taps via the hub's `tap` option,
+ *  not this seam. TRUST BOUNDARY: since Phase 2a this seam hands every wired observer the run's
+ *  modulation handles — it is the trusted hub seam, not a public fan-out point. Do not wire
+ *  untrusted taps here; give third parties the read-only `events()` stream instead. */
+export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
 /**
  * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
  * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
  * entire failure class (violating SPEC MUST 1).
  */
 export declare function toTerminal(message: AssistantMessage): AgentEvent;
-export declare function errorToTerminal(error: unknown): AgentEvent;
+export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
+    type: "failed";
+}>;
 export interface CreatePiAgentFromHarnessOptions {
     harnessFactory: PiHarnessFactory;
     /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
     lease?: Lease;
+    /** Observation-plane tap (see {@link SessionObserver}). Optional; invoke behavior is identical
+     *  with or without it — the SPEC stream is a projection of what the observer sees. */
+    observer?: SessionObserver;
+    /** Working directory exposed to FastAgent-defined tools. Defaults to process.cwd(). */
+    cwd?: string;
 }
 /** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
 export declare function createPiAgentFromHarness(options: CreatePiAgentFromHarnessOptions): Agent;