@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/engines/pi/agent-session-factory.js

@@ -18,7 +18,7 @@ import { log } from "../../log.js";
 import { isDeferredTool } from "./tool.js";
 import { activePath, resolveSessionSettings } from "./session-settings.js";
 import { DEFAULT_THINKING_LEVEL } from "./models.js";
-import { additiveActivation, agentSessionManager, turnContext } from "./tool-context.js";
+import { agentSessionManager, sessionToolActivation, turnContext } from "./tool-context.js";
 /**
  * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
  * tools a loader activated in that call.
@@ -47,37 +47,6 @@ function recordedActivations(session) {
 /** Warned once per session+missing set: a fresh session is built per invoke and channel sessions run
  *  for weeks, so an un-deduped warn would repeat every turn and dilute its own signal. */
 const warnedDroppedActivations = new Set();
-/**
- * The turn's {@link ToolActivation} over a live session — the same bridge chat uses, so one
- * built-in `search_tools` serves both.
- *
- * Activations are PERSISTED as deltas, so a tool discovered in one turn stays callable in the next.
- * pi's own chat session does not do this (it has no place to put the record); a served session does,
- * because the alternative is an agent that re-discovers the same capability every single turn.
- */
-function sessionToolActivation(session) {
-    // Serialize activations: the read-modify-write below is only race-free while nothing awaits
-    // between read and write, and parallel tool calls in one batch would otherwise double-stamp.
-    let chain = Promise.resolve([]);
-    return {
-        active: () => session.getActiveToolNames(),
-        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
-        activate(names) {
-            const run = async () => {
-                const current = session.getActiveToolNames();
-                const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
-                if (added.length > 0) {
-                    session.setActiveToolsByName([...current, ...added]);
-                    session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
-                }
-                return added;
-            };
-            const result = chain.then(run, run);
-            chain = result.catch(() => []);
-            return result;
-        },
-    };
-}
 /**
  * fastagent's tools as pi tool definitions, bound to ONE session.
  *
@@ -86,26 +55,101 @@ function sessionToolActivation(session) {
  * throws rather than executing outside the turn: a broken lifecycle must not look like a normal
  * out-of-turn call.
  */
-function toolDefinitions(tools, cwd, env, sessionId, bound) {
+function toolDefinitions(tools, bound, sessionId) {
     return tools.map((tool) => ({
-        name: tool.name,
-        label: tool.name,
-        description: tool.description ?? "",
-        parameters: tool.parameters,
-        // An activating tool (the built-in loader) declares "sequential" so pi serializes its batch;
-        // without it pi's outer active-set diff double-stamps parallel calls.
-        executionMode: tool.executionMode,
-        execute: (id, params, signal) => {
-            const session = bound.session;
-            if (!session)
-                throw new Error("tool executed before its session was bound (lifecycle invariant broken)");
-            return turnContext.run({ cwd, sessionManager: agentSessionManager(session, sessionId), tools: sessionToolActivation(session) }, 
-            // Lower-level MountedTools may consume the fifth-argument env. Directory coding tools are
-            // cwd-bound and ignore it; authored tools read FastAgent's turnContext instead.
-            () => tool.execute(id, params, signal, undefined, { env }));
+        ...tool,
+        label: tool.label || tool.name,
+        execute: (id, params, signal, onUpdate, ctx) => {
+            const binding = bound.current;
+            if (!binding)
+                throw new Error("tool executed before its turn context was bound (lifecycle invariant broken)");
+            const { session, context } = binding;
+            // Expose the caller's id rather than Pi's filename encoding.
+            const sessionManager = Object.create(ctx.sessionManager, {
+                getSessionId: { value: () => sessionId },
+                getHeader: {
+                    value: () => {
+                        const header = ctx.sessionManager.getHeader();
+                        return header ? { ...header, id: sessionId } : header;
+                    },
+                },
+            });
+            // Pi's thinking getter uses a shared runtime; a restored cwd may be a symlink spelling.
+            const scoped = Object.create(ctx, {
+                sessionManager: { value: sessionManager },
+                cwd: { value: context.cwd },
+                thinkingLevel: { get: () => session.thinkingLevel },
+            });
+            return turnContext.run(context, () => tool.execute(id, params, signal, onUpdate, scoped));
         },
     }));
 }
+/**
+ * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context,
+ * pi's own tool copies kept off, and deferral applied. The per-invoke factory and the resident chat
+ * runtime both bind here — they differ in what they hand in (a shared vs a per-session `services`,
+ * record-resolved vs configured settings) and in whether a discovered activation has a record to
+ * land in, and in nothing else. Two copies of this drifted once (the tool adapter and the deferral
+ * narrowing each existed twice, identical but for those parameters).
+ */
+export async function bindPiSession(options) {
+    const { services, sessionManager, model, thinkingLevel, tools, cwd, recordActivations } = options;
+    const excludedToolNames = options.excludedToolNames ?? [];
+    const deferred = tools.filter(isDeferredTool).map((t) => t.name);
+    const bound = {};
+    const sessionId = options.sessionId ?? sessionManager.getSessionId();
+    const result = await createAgentSessionFromServices({
+        services,
+        sessionManager,
+        ...(options.sessionStartEvent ? { sessionStartEvent: options.sessionStartEvent } : {}),
+        model,
+        thinkingLevel,
+        // pi would otherwise mount its built-ins on top of fastagent's copies, offering duplicate names.
+        // Lower-level callers with an explicit list also rely on omitted built-ins staying omitted. And
+        // NO `tools` allowlist: it would freeze the set at bind time, while pi lets an extension register
+        // from `session_start` — `noTools: "builtin"` gives the guarantee the allowlist was there for.
+        noTools: "builtin",
+        ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
+        customTools: toolDefinitions(tools, bound, sessionId),
+    });
+    const { session } = result;
+    // One context for the whole session: it describes the SESSION, not the call. The activation
+    // bridge above all — a tool call has to see what the previous one activated.
+    bound.current = {
+        session,
+        context: {
+            cwd,
+            sessionManager: agentSessionManager(session, sessionId),
+            // Persist each discovery so a served session can restore it on its next turn.
+            tools: sessionToolActivation(session, recordActivations
+                ? (added) => session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added })
+                : undefined),
+        },
+    };
+    // Deferral, then restoration: pi starts every mounted tool active, so narrow by SUBTRACTING the
+    // deferred names (robust to pi mounting tools of its own, unlike an exact-set replacement), then
+    // add back what THIS session has already discovered.
+    if (deferred.length > 0) {
+        const active = session.getActiveToolNames();
+        const mounted = new Set(session.getAllTools().map((tool) => tool.name));
+        const recorded = recordActivations ? recordedActivations(session) : [];
+        // A recorded name that is no longer mounted is dropped rather than replayed: pi's setter
+        // THROWS on an unknown name, so replaying one would brick every future turn of this session.
+        const restored = recorded.filter((name) => mounted.has(name));
+        const dropped = recorded.filter((name) => !mounted.has(name));
+        if (dropped.length > 0) {
+            const key = `${sessionId}\u0000${[...new Set(dropped)].sort().join(",")}`;
+            const emit = warnedDroppedActivations.has(key) ? log.debug : log.warn;
+            warnedDroppedActivations.add(key);
+            emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${[...new Set(dropped)].join(", ")}`);
+        }
+        const next = [...new Set([...active.filter((name) => !deferred.includes(name)), ...restored])];
+        if (next.length !== active.length || next.some((name) => !active.includes(name))) {
+            session.setActiveToolsByName(next);
+        }
+    }
+    return result;
+}
 /**
  * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
  * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
@@ -148,7 +192,7 @@ export function definitionResourceLoaderOptions(source) {
         // and substitutes its own coding-assistant identity, which an L1 agent
         // (`createPiAgent({ model, tools })`) never asked for. pi appends its own working-directory line
         // either way — that is engine behaviour this binding does not fight.
-        systemPromptOverride: () => source.systemPrompt() ?? " ",
+        systemPromptOverride: () => source.systemPrompt() || " ",
         appendSystemPromptOverride: () => [],
         skillsOverride: (base) => ({
             skills: toPiSkills(source.skills()),
@@ -158,7 +202,7 @@ export function definitionResourceLoaderOptions(source) {
 }
 /** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
 export function piAgentSessionFactory(options) {
-    const { sessions, thinkingLevel, cwd, env } = options;
+    const { sessions, thinkingLevel, cwd } = options;
     const extensionPaths = options.extensionPaths ?? [];
     const excludedToolNames = options.excludedToolNames ?? [];
     if (extensionPaths.length > 0) {
@@ -167,10 +211,8 @@ export function piAgentSessionFactory(options) {
             "runs concurrent turns for different conversations. See docs/configuration.md#extensions.");
     }
     const tools = options.tools ?? [];
-    const deferred = tools.filter(isDeferredTool).map((t) => t.name);
     // What the shared ResourceLoader serves, refreshed per turn before the session is built.
-    let prompt = typeof options.systemPrompt === "function" ? options.systemPrompt() : options.systemPrompt;
-    let skills = options.skills ?? [];
+    let definition;
     let services;
     let engine;
     const buildServices = async (modelRuntime) => createAgentSessionServices({
@@ -182,23 +224,16 @@ export function piAgentSessionFactory(options) {
         // CURRENT prompt/skills — serving refreshes both per turn, so a snapshot taken here would
         // serve a stale definition after the first edit.
         resourceLoaderOptions: definitionResourceLoaderOptions({
-            systemPrompt: () => prompt,
-            skills: () => skills,
+            systemPrompt: () => definition.systemPrompt,
+            skills: () => definition.skills,
         }),
     });
     return async (sessionId, inherit) => {
-        const fresh = options.live ? await options.live() : undefined;
-        const nextPrompt = fresh
-            ? fresh.systemPrompt
-            : typeof options.systemPrompt === "function"
-                ? options.systemPrompt()
-                : prompt;
-        const nextSkills = fresh ? (fresh.skills ?? []) : skills;
+        const next = await options.readDefinition();
         engine ??= options.engine();
         const { modelRuntime, model } = await engine;
         if (services === undefined) {
-            prompt = nextPrompt;
-            skills = nextSkills;
+            definition = next;
             services = buildServices(modelRuntime); // assigned before any await: concurrent turns share it
         }
         else {
@@ -223,10 +258,10 @@ export function piAgentSessionFactory(options) {
             // for both. Pinning a snapshot per turn would cost either a loader per turn or a queue in
             // front of every bind, to buy a guarantee nothing asks for.
             const loader = (await services).resourceLoader;
-            const definitionChanged = loader.getSystemPrompt() !== nextPrompt || loadedSkillSet(loader.getSkills().skills) !== skillSet(nextSkills);
+            const definitionChanged = loader.getSystemPrompt() !== (next.systemPrompt || " ") ||
+                skillSet(loader.getSkills().skills) !== skillSet(next.skills);
             if (definitionChanged) {
-                prompt = nextPrompt;
-                skills = nextSkills;
+                definition = next;
                 await loader.reload();
             }
         }
@@ -242,55 +277,25 @@ export function piAgentSessionFactory(options) {
             model,
             thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
         });
-        const bound = {};
-        const { session } = await createAgentSessionFromServices({
+        const { session } = await bindPiSession({
             services: await services,
             sessionManager,
             model: settings.model,
             thinkingLevel: settings.thinkingLevel,
-            // pi would otherwise mount its built-ins on top of fastagent's copies, offering duplicate names.
-            // Lower-level callers with an explicit list also rely on omitted built-ins staying omitted.
-            noTools: "builtin",
-            ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
-            customTools: toolDefinitions(tools, cwd, env, sessionId, bound),
+            tools,
+            cwd,
+            excludedToolNames,
+            sessionId,
+            recordActivations: true,
         });
-        bound.session = session;
-        // An extension handler that throws is otherwise dropped: pi fans errors out to registered
-        // listeners and has none by default, which on a server means a broken extension looks like an
-        // extension that simply did nothing.
-        //
-        // Deferral, then restoration: pi starts every mounted tool active, so narrow by SUBTRACTING the
-        // deferred names (robust to pi mounting tools of its own, unlike an exact-set replacement), then
-        // add back what THIS session has already discovered.
-        if (deferred.length > 0) {
-            const active = session.getActiveToolNames();
-            const mounted = new Set(session.getAllTools().map((tool) => tool.name));
-            const recorded = recordedActivations(session);
-            // A recorded name that is no longer mounted is dropped rather than replayed: pi's setter
-            // THROWS on an unknown name, so replaying one would brick every future turn of this session.
-            const restored = recorded.filter((name) => mounted.has(name));
-            const dropped = recorded.filter((name) => !mounted.has(name));
-            if (dropped.length > 0) {
-                const key = `${sessionId}\u0000${[...new Set(dropped)].sort().join(",")}`;
-                const emit = warnedDroppedActivations.has(key) ? log.debug : log.warn;
-                warnedDroppedActivations.add(key);
-                emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${[...new Set(dropped)].join(", ")}`);
-            }
-            const next = [...new Set([...active.filter((name) => !deferred.includes(name)), ...restored])];
-            if (next.length !== active.length || next.some((name) => !active.includes(name))) {
-                session.setActiveToolsByName(next);
-            }
-        }
         return session;
     };
 }
 /** What a reload has to notice: the declared set, not the files behind it. */
 function skillSet(skills) {
-    return skills.map((s) => `${s.name}\u0000${s.filePath}\u0000${s.description}`).join("\u0001");
-}
-/** The same signature, read back off the loader. */
-function loadedSkillSet(skills) {
-    return skills.map((s) => `${s.name}\u0000${s.filePath ?? ""}\u0000${s.description}`).join("\u0001");
+    return skills
+        .map((s) => `${s.name}\u0000${s.filePath ?? ""}\u0000${s.description}\u0000${s.disableModelInvocation ?? false}`)
+        .join("\u0001");
 }
 /** fastagent's Skill (content inline) as pi's (read from filePath at invocation time). */
 function toPiSkills(skills) {

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

@@ -24,12 +24,12 @@ 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
      * protection — bind loopback (`--bind 127.0.0.1`; not `http.host`, which travels into a deployed
-     * image), firewall the port, or wrap it for real exposure (design §14).
+     * image), firewall the port, or wrap it for real exposure (docs/design/session-control.md §14).
      */
     sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a

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

@@ -1,4 +1,5 @@
 import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+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";
@@ -7,7 +8,6 @@ import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
 import { type PiAgentSessionFactory } from "./invoke-session.ts";
 import { type AnyModel } from "./models.ts";
-import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type PiSessionRecordStore } from "./session-store.ts";
 import { type Lease, type SessionObserver } from "./turn-kit.ts";
 /**
@@ -54,19 +54,14 @@ export interface AssembleSystemPromptOptions {
         path: string;
         content: string;
     }>;
-    /** ③ Skills for the <available_skills> listing. */
-    skills?: Skill[];
-    /** ④ Env context, caller-provided (keeps this function pure). Omitted = segment omitted. */
-    cwd?: string;
 }
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
 /**
- * INTERNAL seam (workspace ↔ assembly): hands the hub-wiring consumer the assembly's live parts —
- * 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.
+ * The assembly, as a value: what every rung builds and what the agent runs on. The opener hands it to
+ * the control plane too — boundary mutations contend on the SAME lease and validate against the SAME
+ * registry the runs use, which is only true if there is one of each to hand over.
  */
-export type PiAssemblyParts = {
+export interface PiAssembly {
     lease: Lease;
     sessionFactory: PiAgentSessionFactory;
     /** The registry and configured model, resolved on first use (a credential read is async). */
@@ -76,8 +71,9 @@ export type PiAssemblyParts = {
     }>;
     /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
     thinkingLevel: ThinkingLevel;
-};
-type OnAssembly = (parts: PiAssemblyParts) => void;
+}
+/** The agent an assembly runs as: the L0 over its lease and session factory. */
+export declare function agentOf(assembly: PiAssembly, observer?: SessionObserver): Agent;
 /** 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}. */
@@ -87,16 +83,15 @@ export interface CreatePiAgentOptions {
     /**
      * 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.
+     * a factory evaluated once per invoke, never during construction. Pi appends the skills listing
+     * when read is active.
      *
      * 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 — those bind their workspace at construction rather than reading a turn context. */
+    /** The tool set to mount: authored tools or pi's cwd-bound coding tools, both AgentTool. */
     tools?: MountedTool[];
     skills?: Skill[];
     /**
@@ -114,12 +109,9 @@ export interface CreatePiAgentOptions {
     /** 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. */
+    /** Supplies the working directory at L1 (default: process.cwd()), which loads no definition.
+     *  At L2 it also reads persona.md and skills/.
+     *  Tools and project-context discovery use the local process directly; this is not a sandbox. */
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
@@ -168,15 +160,18 @@ export interface CreatePiAgentFromDefinitionOptions {
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */
     observer?: SessionObserver;
-    /** INTERNAL seam for hub wiring; see {@link OnAssembly}. */
-    onAssembly?: OnAssembly;
 }
 /**
- * L2: "point at a directory → agent": load + assemble (base + AGENTS.md + skills + env) + L1 in one
- * call. Returns the definition so callers can surface diagnostics/collisions.
+ * L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. Returns the
+ * definition so callers can surface diagnostics/collisions. The opener consumes this form because
+ * the control plane needs the parts; {@link createPiAgentFromDefinition} is it plus the L0.
  */
+export declare function assemblePiFromDefinition(dir: string, options: Omit<CreatePiAgentFromDefinitionOptions, "observer">): Promise<{
+    assembly: PiAssembly;
+    definition: LoadedDefinition;
+}>;
+/** L2: "point at a directory → agent": {@link assemblePiFromDefinition} under the L0. */
 export declare function createPiAgentFromDefinition(dir: string, options: CreatePiAgentFromDefinitionOptions): Promise<{
     agent: Agent;
     definition: LoadedDefinition;
 }>;
-export {};