@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/config.js

@@ -7,33 +7,26 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 /**
- * The config subsystem: schema (defineConfig), loading (loadConfig), and value interpretation
- * (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). 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.
+ * The config subsystem: schema (defineConfig), loading (loadConfig), and value interpretation (resolveModel,
+ * resolveModelSpec).
  */
 import { existsSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
+import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { THINKING_LEVELS } from "./session-settings.js";
-import { isBindAddress } from "../../bind.js";
+import { GLOBAL_AUTH_PATH } from "./auth.js";
+import { readSecretDeclaration } from "../../declared-secrets.js";
+import { assertCorsOrigins } from "../../channels/serve.js";
 import { moduleLoadHint } from "../../loader.js";
-import { AGENT_CONFIG_NAMES, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
+import { AGENT_CONFIG_FILE, resolveOverridePath, resolveSecretsDir } from "../../paths.js";
 /** Identity function for typing and IDE completion (vite/next-style). */
 export function defineConfig(config) {
     return config;
 }
-/** A valid bindable port. */
 export function isValidPort(n) {
     return Number.isInteger(n) && n >= 0 && n <= 65535;
 }
-/** Validate an optional `string[]` config field where each entry must match `shape` — used for
- *  deploy.secrets (env-var names) and deploy.apt (package names); undefined is fine (field omitted). */
+/** Validate an optional `string[]` config field where each entry must match `shape`. */
 function validateStringList(value, key, shape, desc, path) {
     if (value === undefined)
         return;
@@ -45,25 +38,28 @@ function validateStringList(value, key, shape, desc, path) {
         }
     }
 }
-/** Load `<dir>/fastagent.config.ts|.js|.mjs`. No file = defaults; a wrong-shape file throws. */
+/** Refuse a key `level` does not have, naming the keys it does (the ONE list both the check and the message read). */
+function refuseUnknownKeys(level, valid, prefix, path) {
+    for (const key of Object.keys(level)) {
+        if (!valid.includes(key)) {
+            throw new Error(`${path}: unknown key "${prefix}${key}" (valid keys: ${valid.join(", ")})`);
+        }
+    }
+}
+/** Load `<dir>/fastagent.config.ts`. */
 export async function loadConfig(dir) {
-    const found = AGENT_CONFIG_NAMES.map((name) => join(dir, name)).filter((path) => existsSync(path));
-    if (found.length === 0)
+    const path = join(dir, AGENT_CONFIG_FILE);
+    if (!existsSync(path))
         return { config: {} };
-    if (found.length > 1) {
-        throw new Error(`${dir}: multiple fastagent config files found; keep exactly one (${found.map((p) => basename(p)).join(", ")})`);
-    }
-    // biome-ignore lint/style/noNonNullAssertion: length checked above — exactly one element here
-    const path = found[0];
     let mod;
     try {
-        // 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).
+        // 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. An INTEGER stamp (mtimeNs), because `mtimeMs` carries a
+        // fraction and a loader that decides how to transform a module by looking at the last dot in the URL reads
+        // `…config.ts?v=1789701227227.251` as extension `251` and parses the file as JavaScript — which the scaffold's
+        // `import type` + `satisfies` (what makes an editor complete these keys) does not survive.
         const url = pathToFileURL(path);
-        url.searchParams.set("v", String(statSync(path).mtimeMs));
+        url.searchParams.set("v", String(statSync(path, { bigint: true }).mtimeNs));
         mod = (await import(__rewriteRelativeImportExtension(url.href)));
     }
     catch (error) {
@@ -74,19 +70,10 @@ export async function loadConfig(dir) {
         throw new Error(`${path}: must default-export defineConfig({...})`);
     }
     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 defaults.
-    for (const key of Object.keys(c)) {
-        if (key !== "model" &&
-            key !== "thinkingLevel" &&
-            key !== "tools" &&
-            key !== "http" &&
-            key !== "deploy" &&
-            key !== "selfSchedule" &&
-            key !== "sessionControl") {
-            throw new Error(`${path}: unknown key "${key}" (valid keys: model, thinkingLevel, tools, http, deploy, selfSchedule, sessionControl)`);
-        }
-    }
+    // Unknown keys throw. This is NOT redundant with `defineConfig`'s types: Node strips types without checking them,
+    // so `modle:` reaches here whatever the editor said, and silently degrading to defaults is the failure it would
+    // otherwise cause.
+    refuseUnknownKeys(c, ["model", "thinkingLevel", "tools", "http", "deploy", "sessionControl"], "", path);
     if (c.model !== undefined && typeof c.model !== "string") {
         throw new Error(`${path}: "model" must be a "provider/modelId" string`);
     }
@@ -96,9 +83,6 @@ export async function loadConfig(dir) {
     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`);
-    }
     if (c.tools !== undefined && !Array.isArray(c.tools)) {
         throw new Error(`${path}: "tools" must be an array of AgentTool`);
     }
@@ -111,42 +95,49 @@ export async function loadConfig(dir) {
             if (typeof candidate.name !== "string" || typeof candidate.execute !== "function") {
                 throw new Error(`${path}: "tools[${i}]" must have string "name" and function "execute"`);
             }
+            // The declaration's SHAPE, checked with the same read the code-input loaders use. Here rather
+            // than at tool resolution because this is the author's own config file: a wrong shape in it is
+            // a config error like any other (it stops the command with one line naming the entry), while a
+            // wrong shape in `tools/x.ts` is that one file's load failure and the agent serves without it.
+            const declaration = readSecretDeclaration(candidate, `${path}: "tools[${i}]"`);
+            if (declaration.error !== undefined)
+                throw new Error(declaration.error);
         }
     }
     if (c.http !== undefined && (typeof c.http !== "object" || c.http === null)) {
         throw new Error(`${path}: "http" must be an object`);
     }
-    for (const key of Object.keys(c.http ?? {})) {
-        if (key !== "port" && key !== "host") {
-            throw new Error(`${path}: unknown key "http.${key}" (valid keys: port, host)`);
-        }
+    refuseUnknownKeys(c.http ?? {}, ["port", "cors", "invoke", "run"], "http.", path);
+    if (c.http?.invoke !== undefined && typeof c.http.invoke !== "boolean") {
+        throw new Error(`${path}: "http.invoke" must be a boolean`);
     }
+    if (c.http?.run !== undefined && typeof c.http.run !== "boolean") {
+        throw new Error(`${path}: "http.run" must be a boolean`);
+    }
+    if (c.http?.cors !== undefined)
+        assertCorsOrigins(c.http.cors, `${path}: "http.cors"`);
     if (c.http?.port !== undefined && (typeof c.http.port !== "number" || !isValidPort(c.http.port))) {
         throw new Error(`${path}: "http.port" must be an integer 0-65535`);
     }
-    // Validated as strictly as http.port: an unbindable string ("banana") must fail HERE, not surface
-    // later as a topology diagnostic about "the interface you bound".
-    if (c.http?.host !== undefined && (typeof c.http.host !== "string" || !isBindAddress(c.http.host))) {
-        throw new Error(`${path}: "http.host" must be an IP address or "localhost" (e.g. "127.0.0.1", "0.0.0.0")`);
-    }
     if (c.deploy !== undefined && (typeof c.deploy !== "object" || c.deploy === null)) {
         throw new Error(`${path}: "deploy" must be an object`);
     }
-    for (const key of Object.keys(c.deploy ?? {})) {
-        if (key !== "secrets" && key !== "apt") {
-            throw new Error(`${path}: unknown key "deploy.${key}" (valid keys: secrets, apt)`);
-        }
+    refuseUnknownKeys(c.deploy ?? {}, ["apt", "agentcore"], "deploy.", path);
+    if (c.deploy?.agentcore !== undefined && (typeof c.deploy.agentcore !== "object" || c.deploy.agentcore === null)) {
+        throw new Error(`${path}: "deploy.agentcore" must be an object`);
+    }
+    refuseUnknownKeys(c.deploy?.agentcore ?? {}, ["idleTimeoutSeconds"], "deploy.agentcore.", path);
+    // AWS's own bounds for idleRuntimeSessionTimeout: a value outside them is rejected by CloudFormation minutes into
+    // `deploy agentcore --run`, after the image build.
+    const idle = c.deploy?.agentcore?.idleTimeoutSeconds;
+    if (idle !== undefined && (!Number.isInteger(idle) || idle < 60 || idle > 1209600)) {
+        throw new Error(`${path}: "deploy.agentcore.idleTimeoutSeconds" must be an integer 60-1209600 (seconds)`);
     }
-    // secrets are UPPER_SNAKE env-var names (deploy reads their VALUES from the local env); apt entries are
-    // Debian package names. Both go into a shell/env context on the host, so shape-validate them — catches a
-    // typo and refuses an injection-shaped value from an otherwise-trusted config.
-    validateStringList(c.deploy?.secrets, "deploy.secrets", /^[A-Z_][A-Z0-9_]*$/, "an UPPER_SNAKE env-var name", path);
+    // apt entries are Debian package names.
     validateStringList(c.deploy?.apt, "deploy.apt", /^[a-z0-9][a-z0-9.+-]*$/, "a Debian package name", path);
     return { config: c, path };
 }
-/** 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). */
+/** The provider prefix of a "provider/modelId" spec. */
 export function providerOf(spec) {
     const slash = spec.indexOf("/");
     return slash > 0 ? spec.slice(0, slash) : spec;
@@ -174,13 +165,7 @@ export function listModels(models) {
     }
     return specs.sort();
 }
-/**
- * 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 (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.
- */
+/** Rewrite the `model` in a config file's SOURCE TEXT to `spec`, for the first-run picker's write-back. */
 export function rewriteConfigModel(src, spec) {
     const line = `  model: ${JSON.stringify(spec)},`;
     const commented = /^[ \t]*\/\/[ \t]*model:.*$/m;
@@ -190,32 +175,24 @@ export function rewriteConfigModel(src, spec) {
     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;
-}
 /**
- * `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).
- * Resolved to absolute so the store and the startup report agree regardless of cwd.
+ * Model selection precedence: CLI flag > FASTAGENT_MODEL env > config default. An EMPTY `FASTAGENT_MODEL` is
+ * "unset", not "no model": `export FASTAGENT_MODEL=` in a shell or CI job, and an `environment:`/`env` entry that
+ * interpolates a missing variable, both arrive as `""` — and a set-but-empty value that shadowed `config.model`
+ * would refuse to start an agent whose config names a model.
  */
-export function resolveSessionsDirOverride(flag, env = process.env) {
-    return resolveOverridePath(flag ?? env.FASTAGENT_SESSIONS_DIR);
+export function resolveModelSpec(flag, config, env = process.env) {
+    return flag ?? (env.FASTAGENT_MODEL || config.model);
 }
 /**
- * The auth-file override: `--auth-path` flag > `FASTAGENT_AUTH_PATH` env > undefined (the opener then
- * 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/.secrets/auth.json` — sharing ONE file is safe under the store's cross-process refresh lock.
+ * The auth-file override: the SDK's `authPath` option > `FASTAGENT_AUTH_PATH` env > undefined (the opener then falls
+ * back to {@link defaultAuthPath} under the {@link resolveSecretsDir} dir). The CLI has no flag for it: a second
+ * spelling of one environment variable buys nothing, and the variable is what a deployed container reads anyway.
  */
 function resolveAuthPathOverride(flag, env = process.env) {
     return resolveOverridePath(flag ?? env.FASTAGENT_AUTH_PATH);
@@ -228,7 +205,21 @@ export function defaultAuthPath(secretsDir) {
 export function resolveAuthPath(dir, flag, env = process.env) {
     return resolveAuthPathOverride(flag, env) ?? defaultAuthPath(resolveSecretsDir(dir, env));
 }
-/** The default sessions dir under a resolved state root ({@link resolveStateRoot}). */
-export function defaultSessionsDir(stateRoot) {
-    return join(stateRoot, "sessions");
+/** The {@link AuthLayers} an agent directory reads: `authPath` option > `FASTAGENT_AUTH_PATH` > its own file. */
+export function resolveAuthLayers(agentDir, authPath, env = process.env) {
+    const fallback = resolveAuthFallback(authPath, env);
+    return { path: resolveAuthPath(agentDir, authPath, env), ...(fallback !== undefined ? { fallback } : {}) };
+}
+/**
+ * Where a credential the project does not have is read from instead: the user-global store, because a login is a
+ * PERSON on a machine and not a project — one `login -g` then serves every agent here. Undefined when an explicit
+ * path was named: "use this file" is an instruction, not a preference, so it gets no second layer.
+ *
+ * BOTH knobs {@link resolveAuthPath} reads count as that instruction, `FASTAGENT_SECRETS_DIR` included — it is what
+ * the Fly/Railway/AgentCore artifacts set, and a deployed container must read its mounted credentials and nothing
+ * else (the artifact is the truth).
+ */
+export function resolveAuthFallback(flag, env = process.env) {
+    const explicit = resolveAuthPathOverride(flag, env) ?? resolveOverridePath(env.FASTAGENT_SECRETS_DIR);
+    return explicit === undefined ? GLOBAL_AUTH_PATH : undefined;
 }

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

@@ -2,65 +2,66 @@ import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agen
 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 AuthLayers, type FastagentConfig } from "./config.ts";
+import type { FastagentAuthOptions } from "./auth.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
+import { type DeclaredSecret } from "../../declared-secrets.ts";
 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";
 /**
- * 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.
+ * 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.
  */
 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.
+ * 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.
  */
 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
-     *  via the built-in `search_tools` loader. Surfaced so the operator can see deferral took effect. */
+    /**
+     * Tools registered but not initially active (defineTool `deferred: true`) — discovered/activated via the built-in
+     * `search_tools` loader.
+     */
     deferredToolNames: string[];
     toolCollisions: ToolCollision[];
     toolFailures: ModuleLoadFailure[];
+    /** Env vars the MOUNTED tools declared they need, BY TOOL NAME — a discovered tool shadowed by a
+     *  coding tool or `config.tools` never executes, so its declaration is dropped here rather than
+     *  gating a start. Per tool because a caller that runs exactly ONE of them (`fastagent tool`) must
+     *  not be stopped by a sibling's credential; the serving paths flatten it (they mount all of
+     *  them). DATA: `info` reports it and the deploy pre-flight carries it, while the serving opener
+     *  asserts it (open.ts) — this function must stay reportable. */
+    toolSecrets: Map<string, DeclaredSecret[]>;
 }>;
-/**
- * The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two
- * deviations: the pi-TUI docs section is dropped (those paths don't exist in deployments), and the
- * tool list is generated from the actually-mounted tools (base and toolset must agree). An authored
- * `persona` (from persona.md) replaces the default identity line, keeping the tools list + guidelines.
- */
+/** The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two deviations. */
 export declare function piBasePrompt(options?: {
     tools?: MountedTool[];
     persona?: string;
 }): string;
 export interface AssembleSystemPromptOptions {
     /**
-     * Base prompt (①), REQUIRED — no default: a defaulted piBasePrompt() would render
-     * "Available tools: (none)" even when tools are mounted. Pass piBasePrompt({ tools }) for pi.
+     * Base prompt (①), REQUIRED — no default: a defaulted piBasePrompt() would render "Available tools: (none)" even
+     * when tools are mounted.
      */
     base: string;
-    /** ② project-context files (AGENTS.md et al. from loadProjectContextFiles); each wrapped `<project_instructions path=…>`. */
+    /**
+     * ② project-context files (AGENTS.md et al. from loadProjectContextFiles); each wrapped `<project_instructions
+     * path=…>`.
+     */
     contextFiles?: Array<{
         path: string;
         content: string;
     }>;
 }
 export declare function assembleSystemPrompt(options: AssembleSystemPromptOptions): string;
-/**
- * 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.
- */
+/** The assembly, as a value: what every rung builds and what the agent runs on. */
 export interface PiAssembly {
     lease: Lease;
     sessionFactory: PiAgentSessionFactory;
@@ -71,102 +72,86 @@ export interface PiAssembly {
     }>;
     /** The configured reasoning effort — the other half of the pair a session without overrides runs on. */
     thinkingLevel: ThinkingLevel;
+    /** The extension entry points every session loads, discovered once with the assembly. */
+    extensionPaths: readonly string[];
 }
 /** 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. */
+/** L1 options. */
 export interface CreatePiAgentOptions {
     /** Model spec "provider/modelId" (e.g. "openai-codex/gpt-5.5"), resolved against {@link models}. */
     model: string;
-    /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
+    /** Reasoning effort (pi's scale). */
     thinkingLevel?: ThinkingLevel;
     /**
-     * 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 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.
+     * 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 ①).
      */
     instructions?: string | (() => string);
     /** The tool set to mount: authored tools or pi's cwd-bound coding tools, both AgentTool. */
     tools?: MountedTool[];
     skills?: Skill[];
     /**
-     * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint /
-     * test fake — selected by the `model` spec's provider id. Built-ins cover the rest; static keys
-     * still come from the {@link authPath} credentials file (fastagent login) or env, not from here.
+     * Extra providers registered on top of the built-ins — your own gateway / self-hosted endpoint / test fake —
+     * selected by the `model` spec's provider id.
      */
     providers?: Provider[];
-    /**
-     * 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).
-     */
+    /** Credentials file for stored OAuth/API-key auth (default `GLOBAL_AUTH_PATH`). */
     authPath?: string;
-    /** Session persistence. Defaults to in-memory; inject piSessionRecordStore for restart-surviving
-     *  continuity. */
     sessions?: PiSessionRecordStore;
-    /** 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. */
+    /** Supplies the working directory at L1 (default: process.cwd()), which loads no definition. */
     env?: ExecutionEnv;
-    /** Single-writer lease. Defaults to in-process fail-fast inProcessLease(). */
+    /** Single-writer lease. */
     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. */
+    /** Observation-plane tap (session control): every rich session event of every run. */
     observer?: SessionObserver;
 }
 /** L1: assemble from typed parts. */
 export declare function createPiAgent(options: CreatePiAgentOptions): Agent;
-/**
- * L2 options. `instructions`/`skills` are absent by design — they come from the definition directory
- * (AGENTS.md + skills/), which is the whole point of L2.
- */
+/** L2 options. */
 export interface CreatePiAgentFromDefinitionOptions {
     /** Model spec "provider/modelId", resolved against {@link models}. */
     model: string;
-    /** Reasoning effort (pi's scale). Unset = pi's default; unsupported levels are clamped per model. */
+    /** Reasoning effort (pi's scale). */
     thinkingLevel?: ThinkingLevel;
-    /** 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. */
+    /** Override the engine base prompt (segment ①). */
     base?: string;
-    /** 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 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.
+     * The agent's working directory: where the coding tools operate AND whose ancestors are walked for ② project context
+     * (AGENTS.md).
      */
     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>/.secrets/auth.json` (matching `fastagent dev`/`start` on the same
-     * dir) — unlike the dir-less {@link createPiAgent}/{@link createPiModels}, which default global.
+     * Credentials file. Unset reads the directory's own layers (`resolveAuthLayers`); a named file is an instruction and
+     * gets no second layer.
      */
     authPath?: string;
     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. */
+    /** Filesystem/process environment; see {@link CreatePiAgentOptions.env}. */
     env?: ExecutionEnv;
     lease?: Lease;
     /** Observation-plane tap; see {@link CreatePiAgentOptions.observer}. */
     observer?: SessionObserver;
 }
 /**
- * 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.
+ * THE model registry an agent directory runs on: pi's built-ins, the directory's own `models.json` (custom endpoints
+ * are definition data and travel with the artifact) layered over the machine's `~/.fastagent/models.json` (environment,
+ * which does not travel), and any injected Provider instance, over the given credentials.
+ * The directory rung assembles from it and `availableModelsFromDir` lists from it, so a layer added here reaches both.
  */
-export declare function assemblePiFromDefinition(dir: string, options: Omit<CreatePiAgentFromDefinitionOptions, "observer">): Promise<{
+export declare function definitionModelRuntime(dir: string, options: FastagentAuthOptions & {
+    auth: AuthLayers;
+    providers?: Provider[];
+}): Promise<ModelRuntime>;
+/** L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. */
+export declare function assemblePiFromDefinition(dir: string, 
+/** `auth` is the opener's already-resolved layers, which take the place of `authPath`. */
+options: Omit<CreatePiAgentFromDefinitionOptions, "observer"> & {
+    auth?: AuthLayers;
+}): Promise<{
     assembly: PiAssembly;
     definition: LoadedDefinition;
 }>;