@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/engines/pi/auth.js

@@ -20,16 +20,20 @@
  * Locking is vendored here on `proper-lockfile`, with the same parameters pi's file backend used
  * before pi 0.80.8 stopped exporting it (upstream's stated migration path for SDK consumers is a
  * custom pi-ai `CredentialStore`, which this file is). The lock guards the WRITE path only. `read`
- * is pi-ai's per-request hot path, so it stays UNLOCKED; the in-place locked write opens only a
- * sub-millisecond torn-read window, which `read` absorbs by re-reading. The write path refuses to
- * overwrite a corrupt file (never clobbering other providers' credentials).
+ * is pi-ai's per-request hot path, so it stays UNLOCKED — safe because every write that carries a
+ * CREDENTIAL publishes by rename ({@link writeFileAtomic}): a reader sees one whole version of the
+ * file or another, never a partial one, so a rotation has no torn-read window for an unlocked read
+ * to absorb. The one in-place write left is the `{}` bootstrap below, whose window an unlocked read
+ * observes as an empty file — reported as corrupt, which for a zero-byte auth.json is the right
+ * answer either way. The write path refuses to overwrite a corrupt file (never clobbering other
+ * providers' credentials).
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { GLOBAL_HOME_DIR, SECRETS_DIRNAME } from "../../paths.js";
+import { GLOBAL_HOME_DIR, SECRETS_DIRNAME, SECRET_FILE_MODE, ensureSecretsDir } from "../../paths.js";
+import { writeFileAtomic } from "../../atomic-write.js";
 import { log } from "../../log.js";
-import { setTimeout as sleep } from "node:timers/promises";
 import lockfile from "proper-lockfile";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery
@@ -46,7 +50,7 @@ function pick(creds, providerId) {
     const cred = creds[providerId];
     return cred && (cred.type === "oauth" || cred.type === "api_key") ? cred : undefined;
 }
-const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: 0o600 };
+const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: SECRET_FILE_MODE };
 /**
  * Serialized cross-process read-modify-write of the credentials file: exponential-backoff retries,
  * 30s staleness, and compromise detection (the parameters pi's `FileAuthStorageBackend` used).
@@ -56,13 +60,15 @@ const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: 0o600 };
  * failed unlock after a successful operation rejects instead of leaving a stale lock silently.
  */
 async function withLockedAuthFile(authPath, fn) {
-    const dir = dirname(authPath);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // 0700 unconditionally, including on a directory an operator named with `--auth-path`: pointing a
+    // credential file somewhere is asking for that somewhere to hold a credential. Where the process
+    // cannot chmod (a mount it does not own), this raises — the write fails visibly instead of
+    // quietly leaving the directory readable, which is the trade this repo takes everywhere else.
+    await ensureSecretsDir(dirname(authPath));
     if (!existsSync(authPath)) {
         try {
             writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
-            chmodSync(authPath, 0o600);
+            chmodSync(authPath, SECRET_FILE_MODE);
         }
         catch (error) {
             // EEXIST: another process created the file between the existence check and this exclusive
@@ -89,10 +95,12 @@ async function withLockedAuthFile(authPath, fn) {
         const current = existsSync(authPath) ? readFileSync(authPath, "utf8") : undefined;
         const out = await fn(current);
         throwIfCompromised();
-        if (out.next !== undefined) {
-            writeFileSync(authPath, out.next, AUTH_FILE_WRITE_OPTIONS);
-            chmodSync(authPath, 0o600);
-        }
+        // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only
+        // spelling that applies the mode before the content is reachable — `writeFileSync`'s `mode` is
+        // a no-op on an existing file, so a chmod after it leaves the new credential briefly readable
+        // at whatever mode the old file carried.
+        if (out.next !== undefined)
+            writeFileAtomic(authPath, out.next, SECRET_FILE_MODE);
         throwIfCompromised();
         result = out.result;
     }
@@ -139,34 +147,26 @@ function decodeCreds(raw) {
     return parsed;
 }
 /**
- * Tolerant UNLOCKED read of the whole credentials file, shared by `read` and `list`. The only race
- * is a sub-millisecond in-place write during an OAuth rotation, which can yield an empty/partial
- * file; re-read a few times before concluding it is corrupt. A missing file reads as undefined
- * silently (normal not-configured); a valid file returns immediately, so the common case costs one
- * read.
+ * UNLOCKED read of the whole credentials file, shared by `read` and `list`. ONE read: the write
+ * publishes by rename, so this observes one whole version or another and has nothing to absorb by
+ * re-reading. A missing file reads as undefined silently (normal not-configured); anything that
+ * does not decode is a real corruption — a hand-edit — and says so immediately, rather than after
+ * retrying a race that cannot happen.
  */
-async function readCreds(authPath, warn) {
-    for (let attempt = 0; attempt < 3; attempt++) {
-        let raw;
-        try {
-            raw = readFileSync(authPath, "utf8");
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return undefined; // missing/deleted
-            warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
-            return undefined;
-        }
-        if (raw !== "") {
-            const creds = decodeCreds(raw);
-            if (creds !== undefined)
-                return creds;
-            // A partial read mid-write parses as garbage; fall through and retry. A structurally invalid
-            // root lands here too and is reported as corrupt below.
-        }
-        if (attempt < 2)
-            await sleep(2);
+function readCreds(authPath, warn) {
+    let raw;
+    try {
+        raw = readFileSync(authPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined; // missing/deleted
+        warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
+        return undefined;
     }
+    const creds = raw === "" ? undefined : decodeCreds(raw);
+    if (creds !== undefined)
+        return creds;
     warn(`[fastagent] corrupt auth file ${authPath}: fix or remove it`);
     return undefined;
 }
@@ -190,13 +190,13 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
     const warn = options.warn ?? ((message) => log.warn(message));
     return {
         async read(providerId) {
-            const creds = await readCreds(authPath, warn);
+            const creds = readCreds(authPath, warn);
             return creds ? pick(creds, providerId) : undefined;
         },
         async list() {
             // Metadata only, never secrets (the pi-ai `list` contract). Foreign/old entries are filtered
             // with the same validation as `read`, so both surfaces agree on what "configured" means.
-            const creds = await readCreds(authPath, warn);
+            const creds = readCreds(authPath, warn);
             if (!creds)
                 return [];
             const infos = [];

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

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import type { AnyModel } from "./harness.ts";
+import type { AnyModel } from "./models.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
@@ -9,8 +9,8 @@ export interface FastagentConfig {
      *  "xhigh" | "max"). Unset = pi's default. Authors tune thinking in the pi TUI while vibing — this
      *  is the serving-side counterpart (fidelity). Levels a model doesn't support are clamped by pi. */
     thinkingLevel?: ThinkingLevel;
-    /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
-     *  plus the optional `deferred` marker (see defineTool). */
+    /** Extra custom tools, appended after the pi coding tools — never replaces them. `FastagentTool`
+     *  = AgentTool plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
     /** `host` is the bind address: unset (or `0.0.0.0`) binds all interfaces — what containers need;
      *  `127.0.0.1` keeps the serve (including `/control/*`) off the LAN. Precedence: `--bind` > this. */
@@ -24,7 +24,7 @@ export interface FastagentConfig {
     selfSchedule?: boolean;
     /**
      * Serve the session control plane over HTTP (`/control/*`: state/entries/events + dispatch —
-     * steer/abort/compact/set_model…) for remote consumers: a Web panel, a desktop app, `fastagent
+     * steer/abort/compact + session properties and lifecycle) for remote consumers: a Web panel, a desktop app, `fastagent
      * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
      * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
      * binds all interfaces by default, so the routes are LAN-reachable with the token as the only
@@ -60,7 +60,7 @@ export declare function loadConfig(dir: string): Promise<LoadedConfig>;
  *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
  *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
 export declare function providerOf(spec: string): string;
-/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
 export declare function listModels(models: Models): string[];

package/dist/engines/pi/config.js

@@ -151,7 +151,7 @@ export function providerOf(spec) {
     const slash = spec.indexOf("/");
     return slash > 0 ? spec.slice(0, slash) : spec;
 }
-/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export function resolveModel(models, spec) {
     const slash = spec.indexOf("/");
     if (slash < 1 || slash === spec.length - 1) {

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

@@ -1,25 +1,42 @@
+/**
+ * Agent assembly (configuration-time): the engine assets (tools, prompt) plus the reusable ladder
+ * that puts a pi agent together.
+ *
+ *   L2  createPiAgentFromDefinition(dir, options)   — load a definition directory, assemble, then L1.
+ *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
+ *   L0  createPiAgentFromSession({ sessionFactory }) — in invoke-session.ts (the turn mechanism).
+ *
+ * Above L2 sits the agent opener createPiAgentFromDir (open.ts), which both `dev` and
+ * `start` drive. Each rung calls the one below; options narrow as you go up (L2 owns systemPrompt/skills —
+ * they come from the definition; the openers own model/tools — from config resolution).
+ */
 import { type ExecutionEnv, type Skill, type ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Models, Provider } from "@earendil-works/pi-ai";
+import { type ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
 import { type LoadedDefinition } from "./definition.ts";
-import { type AnyModel, piHarnessFactory } from "./harness.ts";
-import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
-import { type SessionObserver } from "./invoke.ts";
-import { type Lease } from "./turn-kit.ts";
-/** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
- *  turn as the harness tool context — hence no argument here. */
-export declare function piDefaultTools(): MountedTool[];
-/** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
-export declare function resolveTools(config: FastagentConfig): MountedTool[];
+import { type PiAgentSessionFactory } from "./invoke-session.ts";
+import { type AnyModel } from "./models.ts";
+import { type PiSessionRecordStore } from "./session-store.ts";
+import { type Lease, type SessionObserver } from "./turn-kit.ts";
 /**
- * The full tool set an agent mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
- * existing win), plus the non-default tool names and collisions to report. One source for the
+ * Every pi coding tool, in canonical order, rooted at the workspace it operates in.
+ *
+ * pi ships two overlapping groupings and neither is the whole set: `createCodingTools` is the four it
+ * ACTIVATES for a terminal (read/bash/edit/write, no searching), `createReadOnlyTools` is
+ * read/grep/find/ls. `read` is in both; a directory agent mounts their union.
+ */
+export declare const CODING_TOOL_NAMES: readonly ["read", "grep", "find", "ls", "bash", "edit", "write"];
+export declare function piAllCodingTools(cwd: string): MountedTool[];
+/**
+ * The full directory-agent tool set: all pi coding tools + `config.tools` + discovered `tools/`
+ * (deduped, existing win), plus the authored names and collisions to report. One source for the
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export declare function resolveAgentTools(config: FastagentConfig, agentDir: string): Promise<{
+export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd: string): Promise<{
     tools: MountedTool[];
     toolNames: string[];
     /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
@@ -57,20 +74,22 @@ export interface AssembleSystemPromptOptions {
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
 /**
  * INTERNAL seam (workspace ↔ assembly): hands the hub-wiring consumer the assembly's live parts —
- * the SAME models collection, harness factory, and lease the agent runs with — so boundary
- * mutations (session-control.ts) contend on the real lease and validate against the real registry.
- * Called synchronously, exactly once, before the agent is returned. Not part of the public surface.
+ * the SAME session factory and lease the agent runs with, plus the model registry behind a thunk —
+ * so boundary mutations (session-control.ts) contend on the real lease and validate against the real
+ * registry. Called synchronously, exactly once, before the agent is returned. Not public surface.
  */
-type OnAssembly = (parts: {
-    models: Models;
-    harnessFactory: ReturnType<typeof piHarnessFactory>;
+export type PiAssemblyParts = {
     lease: Lease;
-    /** The resolved configured pair — what a session without overrides runs on. */
-    defaults: {
+    sessionFactory: PiAgentSessionFactory;
+    /** The registry and configured model, resolved on first use (a credential read is async). */
+    engine: () => Promise<{
+        modelRuntime: ModelRuntime;
         model: AnyModel;
-        thinkingLevel: ThinkingLevel;
-    };
-}) => void;
+    }>;
+    /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
+    thinkingLevel: ThinkingLevel;
+};
+type OnAssembly = (parts: PiAssemblyParts) => void;
 /** L1 options. Tier 1: model (spec) + instructions + tools. Tier 2: the injectable ports. */
 export interface CreatePiAgentOptions {
     /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
@@ -78,14 +97,18 @@ export interface CreatePiAgentOptions {
     /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
     thinkingLevel?: ThinkingLevel;
     /**
-     * The system prompt itself — verbatim, no engine base and no wrapping (unlike the directory path,
-     * which assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string
-     * or a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
+     * The system prompt itself — no engine base and no wrapping (unlike the directory path, which
+     * assembles the engine base + AGENTS.md as segment ② + persona.md as segment ①). A plain string or
+     * a factory re-evaluated per invoke. When {@link skills} are mounted their listing is appended.
+     *
+     * Not byte-for-byte verbatim: pi appends its own `Current working directory:` line to whatever
+     * prompt it is given. What this rung guarantees is that no engine IDENTITY is imposed — a
+     * hand-built agent is not told it is a coding assistant.
      */
     instructions?: string | (() => string);
     /** The tool set to mount. `FastagentTool` (AgentTool plus the optional `deferred` marker, see
      *  {@link DefineToolOptions}) widens into {@link MountedTool}, which additionally admits pi's default
-     *  coding tools — they read the turn's ExecutionEnv as a fifth `execute` parameter. */
+     *  coding tools — those bind their workspace at construction rather than reading a turn context. */
     tools?: MountedTool[];
     skills?: Skill[];
     /**
@@ -100,12 +123,15 @@ export interface CreatePiAgentOptions {
      * consulted when a provider is absent from the file (resolution order is upstream-owned).
      */
     authPath?: string;
-    /** Session persistence. Defaults to in-memory; inject jsonlSessionStore for restart-surviving continuity. */
-    sessions?: PiSessionStore;
-    /** Filesystem/process environment. Defaults to a local NodeExecutionEnv at `process.cwd()`, and its
-     *  cwd is the agent's. The default coding tools (read/bash/edit/write) take it as the turn's tool
-     *  context, so injecting a constrained one narrows where the agent reads, writes and shells. It does
-     *  NOT constrain author-written `tools/`, which are code and can import anything. */
+    /** Session persistence. Defaults to in-memory; inject piSessionRecordStore for restart-surviving
+     *  continuity. */
+    sessions?: PiSessionRecordStore;
+    /** Filesystem/process environment, handed to tools that read one as the turn's context. Defaults to
+     *  a local NodeExecutionEnv at `process.cwd()`. At THIS rung nothing else consumes it: L1 loads no
+     *  definition. It does NOT constrain the coding tools (pi's own, rooted at the workspace they were
+     *  built for) or author-written `tools/`, which are code and can import anything. Not a
+     *  sandbox — see {@link createPiAgentFromDefinition} for the rung where it also reads the
+     *  definition. */
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
@@ -127,11 +153,11 @@ export interface CreatePiAgentFromDefinitionOptions {
     /** Override the engine base prompt (segment ①). Defaults to piBasePrompt({ tools, persona }) using the
      *  live-read persona.md; pass base to fully opt out of persona.md. */
     base?: string;
-    /** Override tools. Defaults to {@link piDefaultTools} (lock down with a custom list). An authored
+    /** Override tools. Defaults to {@link piAllCodingTools} (lock down with a custom list). An authored
      *  `FastagentTool[]` (AgentTool plus the optional `deferred` marker) widens into {@link MountedTool}. */
     tools?: MountedTool[];
     /**
-     * The agent's working directory: where the default tools operate AND whose ancestors are walked for
+     * The agent's working directory: where the coding tools operate AND whose ancestors are walked for
      * ② project context (AGENTS.md). Defaults to `dir`. Set it to the enclosing repo so a coding agent
      * whose definition lives in `dir` operates on — and reads the AGENTS.md of — that repo (core.md
      * scenario grid); that is what the CLI's opener does with the workspace.
@@ -145,12 +171,11 @@ export interface CreatePiAgentFromDefinitionOptions {
      * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
      */
     authPath?: string;
-    sessions?: PiSessionStore;
-    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. At THIS rung it does more
-     *  than root the default tools: persona.md and skills/ are read through it too. Two surfaces stay
-     *  OUTSIDE it — ② project context (pi's loadProjectContextFiles uses node fs directly; see
-     *  definition.ts) and author-written `tools/`, which are code and can import anything. Injecting an
-     *  env narrows the blast radius rather than closing it. */
+    sessions?: PiSessionRecordStore;
+    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. At THIS rung it reads
+     *  persona.md and skills/. The seven coding tools, ② project context (pi's
+     *  loadProjectContextFiles uses node fs directly), and author-written `tools/` stay outside it.
+     *  Injecting an env narrows the blast radius rather than closing it. */
     env?: ExecutionEnv;
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */