@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/engines/pi/definition.js

@@ -1,18 +1,4 @@
-/**
- * Definition domain: read an agent definition directory (AGENTS.md + skills/) into memory. Produces
- * data; create.ts consumes it.
- *
- * IO policy: persona.md + skills load through ExecutionEnv (portable across local/sandbox/remote); the
- * invoke path never touches disk. EXCEPTION — ② project context comes from pi's loadProjectContextFiles,
- * which reads via node fs DIRECTLY (not the injected `env`) and, on failure, at best warns to stderr and
- * at worst is fully silent (its `existsSync` probe swallows a permission error) — no structured signal. So under a
- * non-local ExecutionEnv the ② files still resolve against THIS process's filesystem, not the target env
- * — a known break in the portability contract, deferred with the sandbox work (core.md §6). config/auth/
- * sessions and this module's Node helpers are composition-root code and may use node fs.
- *
- * Errors: a broken persona.md / unresolvable dir throws (fail loudly at startup); non-fatal findings
- * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
- */
+/** Definition domain: read an agent definition directory (AGENTS.md + skills/) into memory. */
 import { realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { BACKGROUND_CONTEXT, loadSkills, } from "@earendil-works/pi-agent-core";
@@ -20,10 +6,13 @@ import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
 import { log } from "../../log.js";
 import { assertInsideAgentDir } from "../../paths.js";
-/** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
+/**
+ * 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
-    // never diverge if a caller passes a relative agentDir.
+    // One resolved default for the working directory (env cwd AND the context-walk start), so they can never diverge if
+    // a caller passes a relative agentDir.
     const cwd = options.cwd ?? agentDir;
     const e = options.env ?? new NodeExecutionEnv({ cwd });
     const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
@@ -31,12 +20,10 @@ export async function loadAgentDefinition(agentDir, options = {}) {
         throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
     }
     const root = rootResult.value;
-    // ② project context, following pi: the agentDir's own AGENTS.md + every AGENTS.md walking cwd up to
-    // root (loadProjectContextFiles). It reads via node fs directly (mirrors pi), NOT the ExecutionEnv —
-    // a deliberate, deferred deviation from this module's portable-IO policy (revisit with the sandbox; core.md §6).
+    // ② project context, following pi: the agentDir's own AGENTS.md + every AGENTS.md walking cwd up to root
+    // (loadProjectContextFiles).
     const contextFiles = loadProjectContextFiles({ cwd, agentDir: root });
-    // persona.md → segment ① persona (overrides the identity line). Same error policy as AGENTS.md:
-    // only not_found means "absent"; any other read error surfaces rather than silently dropping the persona.
+    // persona.md → segment ① persona (overrides the identity line).
     const personaPath = join(root, "persona.md");
     const personaRead = await e.readTextFile(personaPath, BACKGROUND_CONTEXT);
     if (!personaRead.ok && personaRead.error.code !== "not_found") {
@@ -46,43 +33,7 @@ export async function loadAgentDefinition(agentDir, options = {}) {
     const { skills, diagnostics, collisions } = await readSkills(e, root);
     return { contextFiles, persona, skills, diagnostics, collisions, dir: root };
 }
-/**
- * Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none.
- *
- * Paths, not loaded objects — unlike skills (data: content inline, serializable), an extension is
- * CODE that pi loads with jiti and binds to its own eventBus/runtime, so loading it here would
- * reimplement pi's loader. The engine binding hands these to pi as `additionalExtensionPaths`, which
- * survives `noExtensions: true` — that flag suppresses MACHINE-GLOBAL discovery (`~/.pi`), and the
- * definition's own extensions were only ever collateral to it. FILES, not the directory: pi's paths
- * are module specifiers, and a directory fails as `Cannot find module` into a
- * `LoadExtensionsResult.errors` entry nothing reads.
- *
- * SEPARATE from {@link loadAgentDefinition} on purpose. Prompt and skills are re-read every invoke
- * ("the directory is the agent, LIVE"); scanning for extension entry points is not, since the set
- * cannot change without a restart. Called once per assembly, like `tools/`.
- *
- * Discovery runs on BOTH paths; loading does not. `chat` hands these to pi and runs them fully.
- * Serving only announces them — pi's extension runtime is shared across sessions, and serving has
- * concurrent turns for unrelated conversations (see `PiAgentSessionFactoryOptions.extensionPaths`).
- * The refusals below are therefore about what the ARTIFACT may contain, and hold for both.
- *
- * Discovery follows pi's own rules, so an extension that works in pi works here:
- *
- * 1. a direct `*.ts` / `*.js` file;
- * 2. a subdirectory with `index.ts` / `index.js`.
- *
- * pi has a third rule — a subdirectory whose `package.json` declares a `pi` field — which is NOT
- * implemented here. That shape is reported rather than skipped: a definition whose extension silently
- * fails to load is the failure mode this whole path exists to remove.
- *
- * Containment matches skills/tools/channels/schedules (the fifth of five surfaces): a symlinked
- * `extensions/` escaping the agent dir is refused, and — like `loadModuleDir`, whose `entry.isFile()`
- * excludes them — a symlinked ENTRY is not loaded either. pi's own discovery does follow those, but
- * an extension reached through a link out of the definition is code the artifact does not carry: it
- * resolves on the authoring machine and is missing in the container. Refused loudly, never silently.
- *
- * Absent is normal and silent; a FILE at that path is not — that is an author who meant something.
- */
+/** Extension entry-point FILES under `<agentDir>/extensions/`, empty when there are none. */
 export async function loadExtensionPaths(agentDir, options = {}) {
     const cwd = options.cwd ?? agentDir;
     const e = options.env ?? new NodeExecutionEnv({ cwd });
@@ -101,12 +52,7 @@ export async function loadExtensionPaths(agentDir, options = {}) {
     const paths = [];
     for (const entry of listed.value) {
         if (entry.kind === "symlink") {
-            // EVERY symlink here is announced, without guessing whether it meant to be an extension. The
-            // two mistakes are not equal: a needless line about a symlinked README costs a glance, while
-            // staying quiet about a symlinked extension loses a feature silently and only shows up in the
-            // container. A name-based guess also cannot see through the link — `audit.ext -> some/dir` is
-            // a directory candidate to pi and a mystery here — so the warning says what it knows and
-            // tells the author when to ignore it.
+            // EVERY symlink here is announced, without guessing whether it meant to be an extension.
             warnSymlinkRefused(entry.path);
             continue;
         }
@@ -122,19 +68,14 @@ export async function loadExtensionPaths(agentDir, options = {}) {
             paths.push(index.path);
         }
         else if (!index.refused) {
-            // Silent when the index WAS found and refused for being a symlink: that warning already named
-            // the real problem, and "expected index.ts" on top of it describes a directory that has one.
+            // Silent when the index WAS found and refused for being a symlink.
             log.warn(`[fastagent] ${entry.path} is not a loadable extension: expected index.ts or index.js ` +
                 `(pi's package.json "pi" manifest form is not supported here) — it will not be loaded`);
         }
     }
     return paths.sort();
 }
-/**
- * The first candidate that is a REAL file, and whether one was found but REFUSED as a symlink.
- * `exists` would follow the link, which is how a subdirectory's `index.ts` could otherwise point
- * outside the definition and slip past the rule the top-level entries already follow.
- */
+/** The first candidate that is a REAL file, and whether one was found but REFUSED as a symlink. */
 async function firstRealFile(e, candidates) {
     let refused = false;
     for (const candidate of candidates) {
@@ -158,11 +99,10 @@ function warnSymlinkRefused(path) {
         `the definition so it travels with the artifact — move it in. (If it is not an extension, ` +
         `keep it outside extensions/ to silence this.)`);
 }
-/** The skills half, shared by the full load and {@link loadAgentSkills}. `root` is already resolved. */
+/** The skills half, shared by the full load and {@link loadAgentSkills}. */
 async function readSkills(e, root) {
-    // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
-    // 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).
+    // The definition's OWN skills/ — its half of the answer. The machine's half is machine.ts's, and `withMachine`
+    // decides a name collision in this half's favour.
     await assertInsideAgentDir(root, "skills");
     const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")], BACKGROUND_CONTEXT);
     const byName = new Map();
@@ -179,10 +119,8 @@ async function readSkills(e, root) {
     return { skills: [...byName.values()], diagnostics, collisions };
 }
 /**
- * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same
- * loader, same containment guard, same first-wins collision rule) — for readers that need only the
- * names and must not pay the full load's ② context walk (every AGENTS.md from cwd to root) for them.
- * The control plane's `commands()` is that reader, called when a composer opens its completion list.
+ * The definition's skills ALONE, resolved the same way `loadAgentDefinition` resolves them (same loader, same
+ * containment guard, same first-wins collision rule).
  */
 export async function loadAgentSkills(agentDir, options = {}) {
     const cwd = options.cwd ?? agentDir;
@@ -190,12 +128,10 @@ export async function loadAgentSkills(agentDir, options = {}) {
     const rootResult = await e.absolutePath(agentDir, BACKGROUND_CONTEXT);
     if (!rootResult.ok)
         throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
-    // `dir` is the RESOLVED root, like {@link LoadedDefinition.dir}: readers key per-definition state
-    // (the findings memo) on it, and "./agent" vs an absolute path must not become two definitions.
+    // `dir` is the RESOLVED root, like {@link LoadedDefinition.dir}.
     return { ...(await readSkills(e, rootResult.value)), dir: rootResult.value };
 }
-/** 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. */
+/** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath. */
 export function canonicalPath(p) {
     const resolved = resolve(p);
     try {

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

@@ -1,35 +1,15 @@
-/**
- * THE L0: pi's `AgentSession`, one per invoke, over the same durable record —
- * [conformance-levels.md](../../../docs/design/conformance-levels.md) §2's `per-invoke` posture.
- * Build a session, run one turn, dispose; continuity lives in the record, never in this process.
- *
- * Why this class: pi 0.84 replaced `AgentHarness` with an unimplemented lane-based skeleton, and pi
- * does not consume that class itself — its TUI, RPC and SDK all run on `AgentSession`. Being the
- * sole consumer of a surface nobody dogfoods is a position, not an architecture.
- *
- * Events are translated ONCE, into the rich `SessionEvent` vocabulary the observation plane speaks;
- * the SPEC stream is a projection of that (`docs/design/session-control.md` §6 — one translation
- * plus one projection, never two parallel ones).
- *
- * Two disciplines this file exists to hold:
- * - the turn's outcome comes from the EVENT STREAM, never from an index into session state, which
- *   compaction and overflow recovery both rewrite mid-turn;
- * - `run_started` is published BEFORE the session is bound, so a dispatch racing the build queues on
- *   the run's controls instead of finding no run.
- */
+/** Pi's per-invoke binding over a durable session record. */
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
-import type { SessionInheritance } from "./session-inheritance.ts";
 import { type Agent } from "../../agent.ts";
+import type { SessionInheritance } from "./session-inheritance.ts";
 import { type Lease, type SessionObserver } from "./turn-kit.ts";
-/** Open-or-create the session behind `sessionId` and bind an `AgentSession` to it, per invoke.
- *  `inherit` reaches the CREATE path only — an existing session ignores it. */
+/** Open or create a record and bind a session. */
 export type PiAgentSessionFactory = (sessionId: string, inherit?: SessionInheritance) => Promise<AgentSession>;
 export interface CreatePiAgentFromSessionOptions {
     sessionFactory: PiAgentSessionFactory;
-    /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
+    /** Shared with control-plane writes; admission is synchronous and fail-fast. */
     lease?: Lease;
-    /** Observation-plane tap: every rich event of every run, plus the run's live {@link RunControls}
-     *  on `run_started`. Optional; the SPEC stream is identical with or without it. */
+    /** Trusted observation tap; controls arrive with run_started, before session binding. */
     observer?: SessionObserver;
 }
 export declare function createPiAgentFromSession(options: CreatePiAgentFromSessionOptions): Agent;