@fastagent-sh/fastagent 0.14.0 → 0.16.0

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

@@ -1,10 +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";
-/** pi's thinking levels (types.d.ts `ThinkingLevel`), as a runtime list for config validation — pi
- *  exports only the type. A level the selected model does not support is clamped by pi per model. */
-export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+import { type AnyModel } from "./harness.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
@@ -12,14 +9,6 @@ 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;
-    /**
-     * The agent-definition subdirectory (persona.md, skills/, tools/, channels/), relative to the config
-     * file's directory. Default: the config directory itself (flat — today's behaviour). Point it at a
-     * sibling like `"./agent"` to serve an existing repo as a coding agent: the config dir stays the run
-     * root (cwd, whose AGENTS.md the agent reads as ② context), while the agent's own surface lives in the
-     * subdir and does not collide with the host's `tools/`/`src/` (core.md scenario grid).
-     */
-    agentDir?: string;
     /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
      *  plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
@@ -30,6 +19,15 @@ export interface FastagentConfig {
      *  Off by default — self-scheduling is an autonomy capability, opt in when you want it. Only takes
      *  effect on the serving path (`dev`/`start`, where the scheduler poller honors a wake-up). */
     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
+     * 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, so the routes are LAN-reachable with the token as the only protection —
+     * firewall the port, or wrap it for real exposure (design §14).
+     */
+    sessionControl?: boolean;
     /** Deploy-time declarations for what the agent needs on the box, so real agents don't hand-write a
      *  Dockerfile / hand-set variables. */
     deploy?: {
@@ -47,24 +45,17 @@ export interface FastagentConfig {
 export declare function defineConfig(config: FastagentConfig): FastagentConfig;
 export interface LoadedConfig {
     config: FastagentConfig;
-    /** Config file path; undefined when running zero-config. */
+    /** Config file path; undefined when the loader was pointed at a directory holding none. */
     path?: string;
 }
 /** A valid bindable port. */
 export declare function isValidPort(n: number): boolean;
-/** The config filenames that make a directory a fastagent workspace, in load precedence. ONE source: the
- *  loader (below) and `scaffoldWorkspace`'s already-a-workspace refusal both read this, so "is there a
- *  config?" can't diverge between them when the set changes. */
-export declare const WORKSPACE_CONFIG_NAMES: readonly ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = zero-config; a wrong-shape file throws. */
+/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
 export declare function loadConfig(dir: string): Promise<LoadedConfig>;
-/**
- * The agent-definition dir from config: `config.agentDir` resolved against `dir`, or `dir` itself when
- * unset (flat). The ONE place this is computed — every opener (`dev`/`start`/`info`/`tool`/`deploy`/`chat`)
- * calls it, so the "relative to the config dir, default `.`" rule can never diverge. loadConfig has
- * already validated that agentDir stays under `dir`.
- */
-export declare function resolveAgentDir(dir: string, config: FastagentConfig): string;
+/** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
+ *  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. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
@@ -72,7 +63,7 @@ export declare function listModels(models: Models): string[];
 /**
  * Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back.
  * Handles the scaffold's commented placeholder (`// model: "…"`) and an existing `model:` line; returns
- * null when neither is present (zero-config or a hand-shaped config) so the caller falls back to a
+ * null when neither is present (no config file, or a hand-shaped one) so the caller falls back to a
  * printed hint instead of guessing where to insert. Text-level (not AST) on purpose — it only ever
  * touches a line it recognizes, never reformats the author's file.
  */
@@ -85,35 +76,9 @@ export declare function resolveModelSpec(flag: string | undefined, config: Fasta
  * Resolved to absolute so the store and the startup report agree regardless of cwd.
  */
 export declare function resolveSessionsDirOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
- * falls back to {@link defaultAuthPath} under the {@link resolveStateRoot} root). Resolved to absolute
- * so the store and the startup report agree regardless of cwd. No implicit project↔global fallback (isolation
- * + fail-visibly; see auth.ts); to share one account across projects, point this at the global
- * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
- */
-export declare function resolveAuthPathOverride(flag: string | undefined, env?: NodeJS.ProcessEnv): string | undefined;
-/**
- * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
- * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
- */
-export declare function projectStateDir(dir: string): string;
-/**
- * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
- * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels
- * and the startup report agree regardless of cwd. Definition: single lifecycle (precious, survives
- * redeploy), single process — a container mounts ONE volume here. The finer knobs
- * (`FASTAGENT_SESSIONS_DIR`, `FASTAGENT_AUTH_PATH`) still override their specific path on top.
- *
- * `FASTAGENT_STATE_DIR` is an OPERATOR override, so a relative value resolves against `process.cwd()`
- * — the CLI convention its sibling knobs share (`resolveOverridePath`), NOT against `dir`. Only the
- * DEFAULT (`<dir>/.fastagent`) is dir-anchored. Deployments set an absolute path (a mounted volume);
- * a relative value is in-tree — hence self-ignored — only when run from the definition dir (cwd == dir).
- */
-export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
-/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
-export declare function defaultAuthPath(stateRoot: string): string;
-/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
+export declare function defaultAuthPath(secretsDir: string): string;
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
 export declare function resolveAuthPath(dir: string, flag: string | undefined, env?: NodeJS.ProcessEnv): string;
 /** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
 export declare function defaultSessionsDir(stateRoot: string): string;

package/dist/engines/pi/config.js

@@ -11,25 +11,18 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * (resolveModel, resolveModelSpec). One concern: everything about fastagent.config.ts.
  *
  * Red line: config describes deployment/runtime choices, never authored identity or expertise (those
- * live in persona.md + skills, with AGENTS.md as project context). Deleting the config still leaves a
- * zero-config agent runnable with a model supplied by --model / FASTAGENT_MODEL.
+ * live in persona.md + skills, with AGENTS.md as project context). It has no say in PLACEMENT either —
+ * that rule lives in the neutral src/paths.ts — but its FILE is what marks a directory as an agent, so a
+ * served agent always has one (its contents may be `export default {}`; a model can still come from
+ * --model / FASTAGENT_MODEL). The loader below stays tolerant of a missing file because it is a loader:
+ * callers that have not resolved a placement (deploy inspection, tests) may point it anywhere.
  */
-import { existsSync, lstatSync, realpathSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { THINKING_LEVELS } from "./harness.js";
 import { moduleLoadHint } from "../../loader.js";
-/** pi's thinking levels (types.d.ts `ThinkingLevel`), as a runtime list for config validation — pi
- *  exports only the type. A level the selected model does not support is clamped by pi per model. */
-export const THINKING_LEVELS = [
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max",
-];
+import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
@@ -51,13 +44,9 @@ function validateStringList(value, key, shape, desc, path) {
         }
     }
 }
-/** The config filenames that make a directory a fastagent workspace, in load precedence. ONE source: the
- *  loader (below) and `scaffoldWorkspace`'s already-a-workspace refusal both read this, so "is there a
- *  config?" can't diverge between them when the set changes. */
-export const WORKSPACE_CONFIG_NAMES = ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = zero-config; a wrong-shape file throws. */
+/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
 export async function loadConfig(dir) {
-    const found = WORKSPACE_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
+    const found = AGENT_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
     if (found.length === 0)
         return { config: {} };
     if (found.length > 1) {
@@ -67,7 +56,14 @@ export async function loadConfig(dir) {
     const path = found[0];
     let mod;
     try {
-        mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+        // Cache-bust on file change: ESM `import()` caches by URL, so a config REWRITTEN in this process
+        // (the first-run picker's write-back) would otherwise read back stale — deploy's model-travel gate
+        // then contradicts the "saved model" line it just printed. mtime keeps unchanged files cached;
+        // its resolution is the ceiling — a rewrite within the same timestamp tick reads stale (fine for
+        // the write-back: sub-tick only on coarse-mtime filesystems, and the next process starts fresh).
+        const url = pathToFileURL(path);
+        url.searchParams.set("v", String(statSync(path).mtimeMs));
+        mod = (await import(__rewriteRelativeImportExtension(url.href)));
     }
     catch (error) {
         throw new Error(`${path}: ${error.message}${moduleLoadHint(error)}`);
@@ -78,64 +74,26 @@ export async function loadConfig(dir) {
     }
     const c = config;
     // Unknown keys throw: defineConfig only type-protects .ts authors; a typo in a .js/.mjs config
-    // (`modle:`) must not silently degrade to zero-config.
+    // (`modle:`) must not silently degrade to defaults.
     for (const key of Object.keys(c)) {
         if (key !== "model" &&
             key !== "thinkingLevel" &&
-            key !== "agentDir" &&
             key !== "tools" &&
             key !== "http" &&
             key !== "deploy" &&
-            key !== "selfSchedule") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, agentDir, tools, http, deploy, selfSchedule)`);
+            key !== "selfSchedule" &&
+            key !== "sessionControl") {
+            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, tools, http, deploy, selfSchedule, sessionControl)`);
         }
     }
     if (c.model !== undefined && typeof c.model !== "string") {
         throw new Error(`${path}: "model" must be a "provider/modelId" string`);
     }
-    if (c.thinkingLevel !== undefined && !THINKING_LEVELS.includes(c.thinkingLevel)) {
-        throw new Error(`${path}: "thinkingLevel" must be one of ${THINKING_LEVELS.join(", ")}`);
+    if (c.sessionControl !== undefined && typeof c.sessionControl !== "boolean") {
+        throw new Error(`${path}: "sessionControl" must be a boolean`);
     }
-    if (c.agentDir !== undefined && typeof c.agentDir !== "string") {
-        throw new Error(`${path}: "agentDir" must be a string (a subdirectory relative to the config file)`);
-    }
-    if (typeof c.agentDir === "string") {
-        // Enforce the documented "subdirectory of the config dir" contract: an escaping agentDir (e.g.
-        // "../shared") would still resolve for tool/channel/persona discovery, but `dev`'s chokidar only
-        // watches the config dir subtree — edits outside it would silently never trigger a restart. Reject
-        // it here (fail visibly) rather than let hot-reload break without a signal.
-        const rel = relative(dir, resolve(dir, c.agentDir));
-        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") must be a subdirectory of the config directory, not escape it`);
-        }
-        // An explicitly declared agentDir that doesn't exist is a typo until proven otherwise ("./agnet"):
-        // without this check every opener would assemble an EMPTY agent (no persona, no skills, no tools)
-        // with zero errors — the worst silent failure this config can produce. Deliberately NOT auto-created:
-        // config load is read-only (no implicit operations), and a mkdir would turn the typo into a served
-        // empty agent plus a junk directory.
-        // lstat, not stat: a symlink would pass the literal containment check above while its TARGET lives
-        // outside the config dir — exactly what that check exists to prevent (dev's watch would silently
-        // never see edits). Same rule as init's parent preflight: reject, don't follow.
-        const agentDirAbs = resolve(dir, c.agentDir);
-        const st = lstatSync(agentDirAbs, { throwIfNoEntry: false });
-        if (!st) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") does not exist — create it, or fix the path`);
-        }
-        if (st.isSymbolicLink()) {
-            // Separate message: to its user a symlink LOOKS like a working directory — name the reason and the fix.
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is a symlink — not allowed (its target can live outside the ` +
-                `config directory, where dev's watch would never see edits); use a real directory, or point agentDir at the target's real path`);
-        }
-        if (!st.isDirectory()) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") is not a directory`);
-        }
-        // The leaf lstat can't see a symlinked INTERMEDIATE segment (agentDir "./a/b" with `a` → outside):
-        // realpath equality covers every segment under the config dir in one comparison. dir itself is
-        // realpath'd on both sides, so a symlinked config-dir path (macOS /tmp) stays legal.
-        if (realpathSync(agentDirAbs) !== resolve(realpathSync(dir), relative(dir, agentDirAbs))) {
-            throw new Error(`${path}: "agentDir" ("${c.agentDir}") resolves through a symlink — not allowed (the target can ` +
-                `live outside the config directory, where dev's watch would never see edits); use the real path`);
-        }
+    if (c.thinkingLevel !== undefined && !THINKING_LEVELS.has(c.thinkingLevel)) {
+        throw new Error(`${path}: "thinkingLevel" must be one of ${[...THINKING_LEVELS].join(", ")}`);
     }
     if (c.selfSchedule !== undefined && typeof c.selfSchedule !== "boolean") {
         throw new Error(`${path}: "selfSchedule" must be a boolean`);
@@ -180,14 +138,12 @@ export async function loadConfig(dir) {
     validateStringList(c.deploy?.apt, "deploy.apt", /^[a-z0-9][a-z0-9.+-]*$/, "a Debian package name", path);
     return { config: c, path };
 }
-/**
- * The agent-definition dir from config: `config.agentDir` resolved against `dir`, or `dir` itself when
- * unset (flat). The ONE place this is computed — every opener (`dev`/`start`/`info`/`tool`/`deploy`/`chat`)
- * calls it, so the "relative to the config dir, default `.`" rule can never diverge. loadConfig has
- * already validated that agentDir stays under `dir`.
- */
-export function resolveAgentDir(dir, config) {
-    return resolve(dir, config.agentDir ?? ".");
+/** The provider prefix of a "provider/modelId" spec. A spec without "/" returns whole — downstream
+ *  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 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. */
 export function resolveModel(models, spec) {
@@ -215,7 +171,7 @@ export function listModels(models) {
 /**
  * Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back.
  * Handles the scaffold's commented placeholder (`// model: "…"`) and an existing `model:` line; returns
- * null when neither is present (zero-config or a hand-shaped config) so the caller falls back to a
+ * null when neither is present (no config file, or a hand-shaped one) so the caller falls back to a
  * printed hint instead of guessing where to insert. Text-level (not AST) on purpose — it only ever
  * touches a line it recognizes, never reformats the author's file.
  */
@@ -227,25 +183,19 @@ export function rewriteConfigModel(src, spec) {
         return src.replace(commented, line);
     if (active.test(src))
         return src.replace(active, line);
+    // No model line at all — the natural state after "picked once, then hand-deleted the line to reset".
+    // Re-INSERT at the top of the default-export object while the config still has the scaffold's block
+    // shape; anything else (a wrapper call, a one-liner, a computed export) is hand-shaped — leave it
+    // untouched (the caller prints the set-it-yourself hint).
+    const opener = /^export default[ \t]*\{[ \t]*$/m;
+    if (opener.test(src))
+        return src.replace(opener, (open) => `${open}\n${line}`);
     return null;
 }
 /** Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. */
 export function resolveModelSpec(flag, config, env = process.env) {
     return flag ?? env.FASTAGENT_MODEL ?? config.model;
 }
-/**
- * Resolve a user-supplied path override (a CLI flag or an env var) to an absolute path, expanding a
- * leading `~`/`~/` to the home dir FIRST. Path-valued config from `.env` (or any non-shell source)
- * never gets the shell's `~` expansion, so a bare `resolve("~/x")` would silently create a literal `~`
- * directory — a fail-silently footgun for a secret/state path. Expanding here makes `~` mean home
- * everywhere these knobs are read.
- */
-function resolveOverridePath(raw) {
-    if (!raw)
-        return undefined;
-    const expanded = raw === "~" ? homedir() : raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw;
-    return resolve(expanded);
-}
 /**
  * `start`'s sessions-dir override: `--sessions-dir` flag > `FASTAGENT_SESSIONS_DIR` env > undefined
  * (the opener then falls back to {@link defaultSessionsDir} under the {@link resolveStateRoot} root).
@@ -256,43 +206,21 @@ export function resolveSessionsDirOverride(flag, env = process.env) {
 }
 /**
  * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
- * falls back to {@link defaultAuthPath} under the {@link resolveStateRoot} root). Resolved to absolute
+ * falls back to {@link defaultAuthPath} under the {@link resolveSecretsDir} dir). Resolved to absolute
  * so the store and the startup report agree regardless of cwd. No implicit project↔global fallback (isolation
  * + fail-visibly; see auth.ts); to share one account across projects, point this at the global
- * `~/.fastagent/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
+ * `~/.fastagent/.secrets/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
  */
-export function resolveAuthPathOverride(flag, env = process.env) {
+function resolveAuthPathOverride(flag, env = process.env) {
     return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
 }
-/**
- * The IN-TREE default state root, `<dir>/.fastagent` — what {@link resolveStateRoot} falls back to when
- * `FASTAGENT_STATE_DIR` moves state nowhere. THE single definition of that path segment.
- */
-export function projectStateDir(dir) {
-    return join(dir, ".fastagent");
-}
-/**
- * The resolved state root — the ONE durable machine-state home everything derives from (auth.json,
- * sessions/, channels/<kind>/): `FASTAGENT_STATE_DIR` env > `<dir>/.fastagent`. Absolute, so channels
- * and the startup report agree regardless of cwd. Definition: single lifecycle (precious, survives
- * redeploy), single process — a container mounts ONE volume here. The finer knobs
- * (`FASTAGENT_SESSIONS_DIR`, `FASTAGENT_AUTH_PATH`) still override their specific path on top.
- *
- * `FASTAGENT_STATE_DIR` is an OPERATOR override, so a relative value resolves against `process.cwd()`
- * — the CLI convention its sibling knobs share (`resolveOverridePath`), NOT against `dir`. Only the
- * DEFAULT (`<dir>/.fastagent`) is dir-anchored. Deployments set an absolute path (a mounted volume);
- * a relative value is in-tree — hence self-ignored — only when run from the definition dir (cwd == dir).
- */
-export function resolveStateRoot(dir, env = process.env) {
-    return resolveOverridePath(env.FASTAGENT_STATE_DIR) ?? resolve(projectStateDir(dir));
-}
-/** The default credentials file under a resolved state root ({@link resolveStateRoot}). */
-export function defaultAuthPath(stateRoot) {
-    return join(stateRoot, "auth.json");
+/** The default credentials file under a resolved secrets dir ({@link resolveSecretsDir}). */
+export function defaultAuthPath(secretsDir) {
+    return join(secretsDir, "auth.json");
 }
-/** The effective auth file for a workspace: override if present, else the project-level auth.json. */
+/** The effective auth file for an agent: override if present, else `<secrets dir>/auth.json`. */
 export function resolveAuthPath(dir, flag, env = process.env) {
-    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveStateRoot(dir, env));
+    return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveSecretsDir(dir, env));
 }
 /** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
 export function defaultSessionsDir(stateRoot) {

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

@@ -1,22 +1,23 @@
 import type { AgentTool, ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Provider } from "@earendil-works/pi-ai";
+import type { Models, 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 { piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type FastagentTool, type ToolCollision } from "./tool.ts";
-import { type Lease } from "./invoke.ts";
+import { type Lease, type SessionObserver } from "./invoke.ts";
 /** pi's core default toolset (read/bash/edit/write), rooted at cwd. */
 export declare function piDefaultTools(cwd: string): AgentTool[];
 /** `config.tools` semantics: extra tools APPENDED after pi's defaults, never replacing them. */
 export declare function resolveTools(config: FastagentConfig, cwd: string): AgentTool[];
 /**
- * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * 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
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export declare function resolveWorkspaceTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
+export declare function resolveAgentTools(config: FastagentConfig, agentDir: string, cwd?: string): Promise<{
     tools: AgentTool[];
     toolNames: string[];
     /** Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated
@@ -52,6 +53,17 @@ export interface AssembleSystemPromptOptions {
     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 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.
+ */
+type OnAssembly = (parts: {
+    models: Models;
+    harnessFactory: ReturnType<typeof piHarnessFactory>;
+    lease: Lease;
+}) => 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}. */
@@ -74,8 +86,8 @@ export interface CreatePiAgentOptions {
      */
     providers?: Provider[];
     /**
-     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/auth.json`; the
-     * directory opener passes the project-level `<dir>/.fastagent/auth.json` instead. Env vars are still
+     * Credentials file for stored OAuth/API-key auth. Defaults to `~/.fastagent/.secrets/auth.json`; the
+     * directory opener passes the project-level `<root>/.secrets/auth.json` instead. Env vars are still
      * consulted when a provider is absent from the file (resolution order is upstream-owned).
      */
     authPath?: string;
@@ -86,6 +98,9 @@ export interface CreatePiAgentOptions {
     env?: ExecutionEnv;
     /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
     lease?: Lease;
+    /** Observation-plane tap (session control): every rich session event of every run. Wire the one
+     *  returned by `createPiSessionControl` to serve `state`/`entries`/`events` for this agent. */
+    observer?: SessionObserver;
 }
 /** L1: assemble from typed parts. */
 export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
@@ -106,16 +121,16 @@ export interface CreatePiAgentFromDefinitionOptions {
     tools?: FastagentTool[];
     /**
      * The agent's working directory: where the default tools operate AND whose ancestors are walked for
-     * ② project context (AGENTS.md). Defaults to `dir` (flat: the definition dir is also the run root).
-     * 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).
+     * ② 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.
      */
     cwd?: string;
     /** Extra providers registered on top of the built-ins (your own gateway / self-hosted endpoint). */
     providers?: Provider[];
     /**
      * Credentials file (see {@link CreatePiAgentOptions.authPath}). Being dir-aware, this rung defaults
-     * to the PROJECT-level `<dir>/.fastagent/auth.json` (matching `fastagent dev`/`start` on the same
+     * to the PROJECT-level `<dir>/.secrets/auth.json` (matching `fastagent dev`/`start` on the same
      * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
      */
     authPath?: string;
@@ -124,6 +139,10 @@ export interface CreatePiAgentFromDefinitionOptions {
      *  context loader remain local today, so injecting this alone does not sandbox a directory agent. */
     env?: ExecutionEnv;
     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
@@ -133,3 +152,4 @@ export declare function createPiAgentFromDefinition(dir: string, options: Create
     agent: Agent;
     definition: LoadedDefinition;
 }>;
+export {};

package/dist/engines/pi/create.js

@@ -6,14 +6,15 @@
  *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
  *   L0  createPiAgentFromHarness({ harnessFactory }) — in invoke.ts (its body is the turn mechanism).
  *
- * Above L2 sits the workspace opener createPiAgentFromWorkspace (workspace.ts), which both `dev` and
+ * 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 { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { createCodingTools } from "@earendil-works/pi-coding-agent";
-import { defaultAuthPath, resolveModel, resolveStateRoot } from "./config.js";
+import { defaultAuthPath, resolveModel } from "./config.js";
+import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
 import { piHarnessFactory } from "./harness.js";
 import { createPiModels } from "./models.js";
@@ -21,7 +22,7 @@ import { reportDefinitionWarnings } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
-import { createPiAgentFromHarness } from "./invoke.js";
+import { createPiAgentFromHarness, inProcessLease } from "./invoke.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
 // The full pi toolset is the default for fidelity: authors vibe in local pi with it, so serving with
@@ -37,18 +38,18 @@ export function resolveTools(config, cwd) {
     return config.tools ? [...defaults, ...config.tools] : defaults;
 }
 /**
- * The full tool set a workspace mounts: pi defaults + `config.tools` + discovered `tools/` (deduped,
+ * 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
  * dev/start openers AND `fastagent tool`, so they all mount exactly the same set.
  */
-export async function resolveWorkspaceTools(config, agentDir, cwd = agentDir) {
-    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the run root the agent operates on);
-    // discovered `tools/` come from `agentDir` (the agent's own surface). They coincide in the flat case.
+export async function resolveAgentTools(config, agentDir, cwd = agentDir) {
+    // Default coding tools (read/bash/edit/write) are rooted at `cwd` (the workspace the agent operates
+    // on); discovered `tools/` come from `agentDir` (the agent's own surface).
     const discovered = await loadTools(agentDir);
     const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
-    // The built-in `search_tools` loader mounts here — the one place the workspace's full tool set is
-    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; a
-    // workspace-defined search_tools wins).
+    // The built-in `search_tools` loader mounts here — the one place the agent's full tool set is
+    // computed — so `dev`/`start`/`info`/`fastagent tool` all see the same surface (idempotent; an
+    // agent-defined search_tools wins).
     const tools = withSearchTool(merged.tools);
     // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire
     // on the deferred-authored-loader case, where withSearchTool returns a new array without adding one).
@@ -98,7 +99,7 @@ export function piBasePrompt(options = {}) {
     const deferredCount = mounted.length - tools.length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line
-    // (the standalone×code-repo cell's persona; core.md §11), keeping the tools list + guidelines below.
+    // (core.md §11), keeping the tools list + guidelines below.
     const identity = options.persona?.trim() ||
         "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.";
     const deferredNote = deferredCount > 0
@@ -141,20 +142,23 @@ export function assembleSystemPrompt(options) {
  */
 function buildPiAgent(opts) {
     const models = createPiModels({ providers: opts.providers, authPath: opts.authPath });
-    return createPiAgentFromHarness({
-        lease: opts.lease,
-        harnessFactory: piHarnessFactory({
-            sessions: opts.sessions ?? inMemorySessionStore(),
-            env: opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() }),
-            models,
-            model: resolveModel(models, opts.model),
-            thinkingLevel: opts.thinkingLevel,
-            systemPrompt: opts.systemPrompt,
-            tools: opts.tools,
-            skills: opts.skills,
-            live: opts.live,
-        }),
+    const env = opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() });
+    // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
+    // the SAME lease instance the agent runs under — boundary mutations must contend on it.
+    const lease = opts.lease ?? inProcessLease();
+    const harnessFactory = piHarnessFactory({
+        sessions: opts.sessions ?? inMemorySessionStore(),
+        env,
+        models,
+        model: resolveModel(models, opts.model),
+        thinkingLevel: opts.thinkingLevel,
+        systemPrompt: opts.systemPrompt,
+        tools: opts.tools,
+        skills: opts.skills,
+        live: opts.live,
     });
+    opts.onAssembly?.({ models, harnessFactory, lease });
+    return createPiAgentFromHarness({ lease, observer: opts.observer, cwd: env.cwd, harnessFactory });
 }
 /**
  * L1 system prompt: `instructions` ARE the prompt (no engine base, no wrapping); the skills listing
@@ -185,6 +189,7 @@ export function createPiAgent(options) {
         sessions: options.sessions,
         env: options.env,
         lease: options.lease,
+        observer: options.observer,
     });
 }
 /** Stable identity of a definition's non-fatal findings, for change-detection in `live` (dedup only). */
@@ -216,9 +221,9 @@ export async function createPiAgentFromDefinition(dir, options) {
         model: options.model,
         thinkingLevel: options.thinkingLevel,
         providers: options.providers,
-        // Dir-aware default: the same state-root-derived file the opener uses for this dir (the opener
+        // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
         // passes an explicit authPath, so this only affects direct L2 callers).
-        authPath: options.authPath ?? defaultAuthPath(resolveStateRoot(dir)),
+        authPath: options.authPath ?? defaultAuthPath(resolveSecretsDir(dir)),
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).
@@ -253,6 +258,8 @@ export async function createPiAgentFromDefinition(dir, options) {
         sessions: options.sessions,
         env,
         lease: options.lease,
+        observer: options.observer,
+        onAssembly: options.onAssembly,
     });
     return { agent, definition };
 }