@fastagent-sh/fastagent 0.15.0 → 0.16.1

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

@@ -1,4 +1,4 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { AgentHarnessTool, ExecutionToolContext, AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
 import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
@@ -34,6 +34,14 @@ export interface DefineToolOptions<I extends z.ZodType> {
     executionMode?: "sequential" | "parallel";
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
+/**
+ * A tool as MOUNTED: what the harness actually runs. Wider than the authored {@link AgentTool} on
+ * purpose — pi's default coding tools read the turn's tool context (its ExecutionEnv) as a fifth
+ * `execute` parameter, while fastagent's own tools take four and are assignable to it unchanged.
+ * Naming the wider type is what lets `defineTool` stay context-free for authors while both families
+ * live in one array; every helper that only inspects or reorders tools is typed on THIS.
+ */
+export type MountedTool = AgentHarnessTool<ExecutionToolContext>;
 /** An AgentTool with fastagent's deferral marker — the type for raw tools handed to fastagent
  *  (`config.tools`, L1/L2 `tools`): plain `AgentTool` has no `deferred`, so an object literal with the
  *  marker would fail excess-property checking against upstream's type. `defineTool` produces it. */
@@ -42,10 +50,10 @@ export type FastagentTool = AgentTool & {
 };
 /** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
  *  AgentTool object — pi ignores it). */
-export declare function isDeferredTool(tool: AgentTool): boolean;
+export declare function isDeferredTool(tool: MountedTool): boolean;
 /** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
  *  could never be activated and would strand every deferred tool). */
-export declare function stripDeferredMarker(tool: AgentTool): AgentTool;
+export declare function stripDeferredMarker(tool: MountedTool): MountedTool;
 export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): FastagentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
 export interface ToolCollision {
@@ -68,7 +76,7 @@ export declare function loadTools(dir: string): Promise<{
  * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
-export declare function mergeDiscoveredTools(existing: AgentTool[], discovered: AgentTool[]): {
-    tools: AgentTool[];
+export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {
+    tools: MountedTool[];
     collisions: ToolCollision[];
 };

package/dist/engines/pi/tool.js

@@ -11,6 +11,7 @@
  *   });
  */
 import { join } from "node:path";
+import { assertInsideAgentDir } from "../../paths.js";
 import { z } from "zod";
 import { loadModuleDir } from "../../loader.js";
 import { turnContext } from "./tool-context.js";
@@ -94,6 +95,9 @@ export function defineTool(options) {
  * `tools/` dir of its OWN scripts, which is exactly this case.
  */
 export async function loadTools(dir) {
+    // The same containment guard channels/schedules/skills get — and `tools/` is the one that gets
+    // IMPORTED AND EXECUTED, so a symlink escaping the agent dir is exactly what it must refuse.
+    await assertInsideAgentDir(dir, "tools");
     const { modules, failures } = await loadModuleDir(join(dir, "tools"));
     const byName = new Map();
     const collisions = [];

package/dist/engines/pi/wake-tool.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type MountedTool } from "./tool.ts";
 /**
  * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"`
  * ("30m", "2h", "1d"). Undefined for anything else, INCLUDING a bare numeric string like "120": one
@@ -12,6 +12,6 @@ export declare function parseDelayMs(input: string | number): number | undefined
  * scheduler poller honors a wake-up) and only when the workspace hasn't defined its own `wake` (that
  * wins, like any tool collision). The single place the mount decision + collision rule run.
  */
-export declare function withWakeTool(tools: AgentTool[], stateRoot: string, enabled: boolean): AgentTool[];
+export declare function withWakeTool(tools: MountedTool[], stateRoot: string, enabled: boolean): MountedTool[];
 /** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
-export declare function makeWakeTool(stateRoot: string, now?: () => Date): AgentTool;
+export declare function makeWakeTool(stateRoot: string, now?: () => Date): MountedTool;

package/dist/env.d.ts

@@ -16,9 +16,21 @@ export declare function loadEnvFile(file: string): void;
  *  anything else reading/deciding on .env content (e.g. `add`'s secret pre-fill) must use this, never a
  *  private re-implementation: two parsers of one dialect diverge silently. */
 export declare function parseEnvContent(content: string): Map<string, string>;
+/** The agent's `.env` file: `<resolved secrets dir>/.env` — default `<agentDir>/.secrets/.env`,
+ *  moved together with auth.json by `FASTAGENT_SECRETS_DIR` ({@link resolveSecretsDir} in the neutral
+ *  paths.ts). THE path every reader/writer of the agent's .env must use, so "where do secrets
+ *  live" cannot diverge across commands. The file's OWN location resolves from the REAL environment:
+ *  commands locate + load `.env` first, so a `FASTAGENT_SECRETS_DIR` set INSIDE it still relocates
+ *  auth.json but cannot move the file it is read from. */
+export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
+/** The committable template: `<agentDir>/.secrets/.env.example` — deliberately NOT moved by
+ *  `FASTAGENT_SECRETS_DIR`: it is authored agent surface that travels with the directory (the
+ *  scaffolded `.secrets/.gitignore` un-ignores exactly it), while the real values follow the override. */
+export declare function envExamplePath(agentDir: string): string;
 /**
- * Load `<dir>/.env` into `process.env` ({@link loadEnvFile}), treating a MISSING file as normal (no .env)
- * — the workspace-facing entry every command + the tunnel use. Only ENOENT is swallowed; any other read
- * error (a corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
+ * Load the agent's `.env` ({@link dotEnvPath}) into `process.env` ({@link loadEnvFile}), treating a
+ * MISSING file as normal (no .env) — the agent-facing entry every command + the tunnel use. `agentDir`
+ * is the AGENT DIR (resolvePlacement().agentDir). Only ENOENT is swallowed; any other read error (a
+ * corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
  */
-export declare function loadDotEnv(dir: string): void;
+export declare function loadDotEnv(agentDir: string): void;

package/dist/env.js

@@ -1,5 +1,8 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { log } from "./log.js";
+import { SECRETS_DIRNAME, resolveSecretsDir } from "./paths.js";
 /**
  * Load a `.env` file into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence
  * on BOTH axes (verified against Node): a real env var wins over the file (an already-set key is kept),
@@ -41,17 +44,52 @@ export function parseEnvContent(content) {
     }
     return parsed;
 }
+/** The agent's `.env` file: `<resolved secrets dir>/.env` — default `<agentDir>/.secrets/.env`,
+ *  moved together with auth.json by `FASTAGENT_SECRETS_DIR` ({@link resolveSecretsDir} in the neutral
+ *  paths.ts). THE path every reader/writer of the agent's .env must use, so "where do secrets
+ *  live" cannot diverge across commands. The file's OWN location resolves from the REAL environment:
+ *  commands locate + load `.env` first, so a `FASTAGENT_SECRETS_DIR` set INSIDE it still relocates
+ *  auth.json but cannot move the file it is read from. */
+export function dotEnvPath(agentDir, env = process.env) {
+    return join(resolveSecretsDir(agentDir, env), ".env");
+}
+/** The committable template: `<agentDir>/.secrets/.env.example` — deliberately NOT moved by
+ *  `FASTAGENT_SECRETS_DIR`: it is authored agent surface that travels with the directory (the
+ *  scaffolded `.secrets/.gitignore` un-ignores exactly it), while the real values follow the override. */
+export function envExamplePath(agentDir) {
+    return join(agentDir, SECRETS_DIRNAME, ".env.example");
+}
 /**
- * Load `<dir>/.env` into `process.env` ({@link loadEnvFile}), treating a MISSING file as normal (no .env)
- * — the workspace-facing entry every command + the tunnel use. Only ENOENT is swallowed; any other read
- * error (a corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
+ * Load the agent's `.env` ({@link dotEnvPath}) into `process.env` ({@link loadEnvFile}), treating a
+ * MISSING file as normal (no .env) — the agent-facing entry every command + the tunnel use. `agentDir`
+ * is the AGENT DIR (resolvePlacement().agentDir). Only ENOENT is swallowed; any other read error (a
+ * corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
  */
-export function loadDotEnv(dir) {
+export function loadDotEnv(agentDir) {
+    const path = dotEnvPath(agentDir);
     try {
-        loadEnvFile(join(dir, ".env"));
+        loadEnvFile(path);
     }
     catch (error) {
         if (error.code !== "ENOENT")
             throw error;
     }
+    // A `.env` at the agent's root is the file habit puts there, and nothing reads it. Left silent, the
+    // symptom is a setting that appears configured and is not.
+    //
+    // Scoped to keys FASTAGENT itself reads, because that is the only case we can be sure about: an agent
+    // directory can be the author's repository too (the shape `--agent-dir .` exists for), where a root
+    // `.env` is their APPLICATION's — and "move the values" would break it. Nothing here can tell those
+    // apart, so the broader guess (warn whenever the agent has no env of its own) was a warning on every
+    // boot, with destructive advice, aimed at the population that never had the problem. Channel
+    // credentials are deliberately out of scope: a channel that cannot find its token reports that itself,
+    // and it is the one that knows the name.
+    const stray = join(agentDir, ".env");
+    if (stray === path || !existsSync(stray))
+        return;
+    const misplaced = [...parseEnvContent(readFileSync(stray, "utf8")).keys()].filter((k) => k.startsWith("FASTAGENT_"));
+    if (misplaced.length > 0) {
+        log.warn(`[fastagent] ${stray} is NOT read — it sets ${misplaced.join(", ")}, and this agent's env lives at ` +
+            `${path}; move those values there`);
+    }
 }

package/dist/host/node.d.ts

@@ -6,9 +6,9 @@ export type ChannelHandler = (req: Request) => Response | Promise<Response>;
 export type Routes = Record<string, ChannelHandler>;
 /**
  * What the framework hands a channel at mount time: the assembled agent plus the resolved state ROOT
- * (absolute; `FASTAGENT_STATE_DIR` > `<dir>/.fastagent`). Channels derive their OWN durable home from
+ * (absolute; `FASTAGENT_STATE_DIR` > `<root>/.state`). Channels derive their OWN durable home from
  * it (`<stateRoot>/channels/<kind>/`) — they never anchor on `process.cwd()`. env is the OPERATOR
- * input plane; this context is how the resolved result reaches code (embedders without the workspace
+ * input plane; this context is how the resolved result reaches code (embedders without the agent
  * opener construct it explicitly).
  */
 export interface ChannelContext {
@@ -48,9 +48,11 @@ export declare function router(routes: Routes): ChannelHandler;
  * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
  * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
  * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
+ * `host` is the bind address; unset means all interfaces (what containers need).
  */
 export declare function serveNode(handler: ChannelHandler, options: {
     port: number;
+    host?: string;
 }): {
     listening: Promise<number>;
     close: () => Promise<void>;

package/dist/host/node.js

@@ -35,12 +35,13 @@ export function router(routes) {
  * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
  * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
  * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
+ * `host` is the bind address; unset means all interfaces (what containers need).
  */
 export function serveNode(handler, options) {
     const server = createServer(nodeListener(async (req) => handler(req)));
     const listening = new Promise((resolve, reject) => {
         server.once("error", reject); // a bind failure surfaces here, before "listening"
-        server.listen(options.port, () => {
+        server.listen({ port: options.port, host: options.host }, () => {
             server.off("error", reject);
             resolve(server.address().port);
         });

package/dist/loader.d.ts

@@ -1,4 +1,4 @@
-/** Whether `name` is an importable workspace module (a discovery candidate, not a type declaration). */
+/** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
 export declare function isModuleFile(name: string): boolean;
 export interface DiscoveredModule {
     /** Basename without extension — the authoritative name for tools/channels. */
@@ -10,7 +10,7 @@ export interface DiscoveredModule {
         default?: unknown;
     };
 }
-/** A workspace module that failed to load, surfaced as data so its caller can report the exact file.
+/** An agent module that failed to load, surfaced as data so its caller can report the exact file.
  *  `loadModuleDir` fills it for import failures; domain loaders add validation failures. The caller owns
  *  policy: tools/schedules may skip one bad file, while serving treats a broken declared channel as fatal. */
 export interface ModuleLoadFailure {

package/dist/loader.js

@@ -10,7 +10,7 @@ import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 const MODULE_EXTS = new Set([".ts", ".js", ".mjs"]);
-/** Whether `name` is an importable workspace module (a discovery candidate, not a type declaration). */
+/** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
 export function isModuleFile(name) {
     return MODULE_EXTS.has(extname(name)) && !name.endsWith(".d.ts");
 }
@@ -60,10 +60,10 @@ export async function loadModuleDir(subDir) {
  */
 export function moduleLoadHint(error) {
     if (error.code === "ERR_MODULE_NOT_FOUND" || /Cannot find (package|module)/.test(error.message)) {
-        return "\n  (a dependency is not installed — run `npm install` in the workspace)";
+        return "\n  (a dependency is not installed — run `npm install` in the agent dir)";
     }
     if (/import statement outside a module|Unexpected token 'export'|ERR_REQUIRE_ESM/.test(error.message)) {
-        return '\n  (this workspace must be ESM — set "type": "module" in package.json)';
+        return '\n  (the agent dir must be ESM — set "type": "module" in package.json)';
     }
     return "";
 }

package/dist/log.d.ts

@@ -15,7 +15,7 @@ export interface Logger {
     warn(msg: string): void;
     error(msg: string): void;
 }
-/** A standalone logger over an explicit sink — used in tests to assert level gating without the singleton. */
+/** An embedded logger over an explicit sink — used in tests to assert level gating without the singleton. */
 export declare function createLogger(opts: {
     level: LogLevel;
     sink?: (line: string) => void;

package/dist/log.js

@@ -11,7 +11,7 @@
 const ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
 const isLevel = (s) => s in ORDER;
 const format = (level, msg) => `${level.toUpperCase().padEnd(5)} ${msg}`;
-/** A standalone logger over an explicit sink — used in tests to assert level gating without the singleton. */
+/** An embedded logger over an explicit sink — used in tests to assert level gating without the singleton. */
 export function createLogger(opts) {
     const sink = opts.sink ?? ((line) => console.error(line));
     const make = (level) => (msg) => {

package/dist/paths.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The directory name `init` gives a nested agent (`<workspace>/fastagent/`) unless `--agent-dir` names
+ * another. A DEFAULT, not a rule: resolution reads the config marker and never a name, so renaming an
+ * agent directory changes nothing about how it resolves. Visible on purpose — the agent directory holds
+ * the AUTHOR's content (persona, skills, tool code: code, not tool configuration), so it follows the
+ * repo convention for code (a plain directory), while fastagent's own machinery inside it (`.secrets/`,
+ * `.state/`) keeps the dot prefix.
+ */
+export declare const DEFAULT_AGENT_DIRNAME = "fastagent";
+/** The user-global machinery home under `$HOME` — hidden, per the dotfile convention for per-user
+ *  tool homes (`~/.cargo`, `~/.docker`); unrelated to {@link DEFAULT_AGENT_DIRNAME}, which only names
+ *  what `init` creates.
+ *  It carries the same shape inside it as an agent dir does (`~/.fastagent/.secrets/auth.json`), so the
+ *  resolvers below need no special case: `login` outside any agent simply hands them this directory. */
+export declare const GLOBAL_HOME_DIR = ".fastagent";
+/** The secrets segment inside an agent dir (or the global home): every PATH fastagent resolves —
+ *  `.env`, `.env.example`, auth.json, the scaffold's write — derives from it, so they cannot drift
+ *  apart. `FASTAGENT_SECRETS_DIR` relocates the RESOLVED dir ({@link resolveSecretsDir}), never this
+ *  name. The scaffold's ignore templates are real files the author owns from `init` on, so they spell
+ *  their rules out as literal text — renaming this constant means editing them too. */
+export declare const SECRETS_DIRNAME = ".secrets";
+/** The state segment inside an agent dir — same rule and same template caveat as {@link SECRETS_DIRNAME}. */
+export declare const STATE_DIRNAME = ".state";
+/** The config filenames, in load precedence. ONE source: the loader (below) and `scaffoldAgent`'s
+ *  already-an-agent refusal both read this, so "is there a config?" can't diverge between them. */
+export declare const AGENT_CONFIG_NAMES: readonly ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+export interface ResolvedPlacement {
+    /** The AGENT directory — where the definition (persona.md/skills/tools/channels/schedules), the
+     *  config, and the machinery dirs (`.secrets/`, `.state/`) live. Absolute. */
+    agentDir: string;
+    /** The WORKSPACE — what the agent works ON: its cwd, and the start of the ② context walk. ALWAYS the
+     *  directory fastagent was pointed at, which makes it the agent dir's PARENT when the agent was found
+     *  one level down, and the agent dir ITSELF when you aimed straight at it. Absolute.
+     *  `agentDir === workspace` is the only discriminant — there is no mode field, because there are no
+     *  two placements to distinguish: there is one lookup and the directory you gave it. The naming
+     *  follows git: the repository sits at the root of its working tree, and WORK belongs to the tree. */
+    workspace: string;
+}
+/**
+ * The agents `dir` resolves over: ITSELF when it holds a config, else the ones directly inside it —
+ * never both, because aiming at an agent can only mean that agent. Exported for `init`, which asks the
+ * same question this lookup asks: which agents would `dir` resolve over, before and after scaffolding.
+ */
+export declare function agentsAt(dir: string): string[];
+/**
+ * The one-line hint for "you pointed at the agent, but the project around it is what you meant" — or
+ * undefined. The workspace being whatever you aimed at is deliberate (a deployed box may hold nothing
+ * but the agent), and the cost is that `cd my-agent && fastagent dev` legitimately narrows the agent's
+ * WORKSPACE to its own directory: its cwd, its coding tools' root, and deploy's build context. (②
+ * context is not affected — that walk climbs ancestors either way.) Resolution must not guess which you
+ * wanted, so this is a HINT — and a hint may use the heuristic ("the parent carries an AGENTS.md or a
+ * .git") that a rule may not.
+ *
+ * It suggests a command only after RUNNING the lookup that command would run, because a hint that dead-ends
+ * is worse than none: with several agents beside this one, `..` refuses and names them — sending the
+ * reader to a refusal whose own advice points back here.
+ */
+export declare function workspaceHint({ agentDir, workspace }: ResolvedPlacement, env?: NodeJS.ProcessEnv): string | undefined;
+/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair,
+ *  and without the throw. `login` is the caller: it is the one command allowed to run outside an agent,
+ *  so it needs the answer as a value rather than as a refusal. */
+export declare function findAgentDir(dir: string): string | undefined;
+/**
+ * The agent whose DEFINITION contains `dir` — scaffolding there would make the new agent part of the
+ * outer one's loaded surface rather than an agent of its own. Narrower than {@link enclosingAgentDir} on
+ * purpose: an agent owns only what it LOADS ({@link LOADED_SURFACE}); the rest of its directory is the
+ * author's tree, where a second agent (a monorepo package, say) is a legitimate thing to create.
+ * `enclosingAgentDir` answers a different question ("where do I `cd` to?"), and for that an agent's
+ * `src/` genuinely IS inside it.
+ */
+export declare function agentDefinitionOwner(dir: string): string | undefined;
+/**
+ * Why `dir` is not an agent, when it has its OWN way out — or undefined when it is simply not near one.
+ * Two positions qualify: standing INSIDE an agent (its `tools/`, its `src/`), and standing on a
+ * directory whose several agents nothing selects between. Both matter because the generic advice ("run
+ * `fastagent init`") would not help — the agent already exists, one step away.
+ *
+ * Exported because `login` is the one command allowed to run outside an agent, and it must tell "truly
+ * outside" (→ the global credential) from "a dead end" (→ refuse, like every other command).
+ */
+export declare function placementDeadEnd(dir: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Resolve a directory into its placement — the ONE owner of the rule ({@link findPlacement}): `dir` is
+ * the workspace, and the agent is the single `fastagent.config.*` holder at it or one level inside.
+ * Placement is never configured and never detected from surroundings; it is that lookup and the
+ * directory you pointed at.
+ *
+ * Anything else throws (fail visibly). Resolution never walks UP — an agent must not be claimed from
+ * arbitrarily deep inside it — but the MESSAGE reads the path, so each dead end gets the exit that fits
+ * it ({@link placementDeadEnd}).
+ */
+export declare function resolvePlacement(dir: string, env?: NodeJS.ProcessEnv): ResolvedPlacement;
+/** How to WRITE a path for someone standing in `cwd`: relative when it is inside `cwd`, absolute when
+ *  it climbs out (a `../../..` is noise), and undefined when it IS `cwd` (nothing to say). ONE policy,
+ *  shared by `init`'s `cd` step, `add`'s next-steps paths and `fire`'s "looked in" hint — they all answer
+ *  the same question, which is a placement-PRESENTATION question, not a scaffolding one. */
+export declare function displayPath(cwd: string, dir: string): string | undefined;
+/** Does a path exist? Plain fs, no placement in it — it lives here because `paths.ts` is where the
+ *  neutral path helpers are, and the scaffolder is not a utility home for the CLI and deploy. */
+export declare function exists(p: string): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function resolveOverridePath(raw: string | undefined): string | undefined;
+/**
+ * The resolved state root — the durable machine-state home (sessions/, channels/<kind>/, schedule/,
+ * control.json): `FASTAGENT_STATE_DIR` env > `<agentDir>/.state`. Absolute, so channels and the
+ * startup report agree regardless of cwd. Definition: mutable runtime state — single lifecycle
+ * (precious, survives redeploy), single process; a container points this at its mounted volume.
+ * Secrets are NOT here — they live under {@link resolveSecretsDir} (a different deploy lifecycle:
+ * secret store vs volume). The finer knob (`FASTAGENT_SESSIONS_DIR`) still overrides its 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 (`<root>/.state`) is dir-anchored.
+ */
+export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The resolved secrets dir — everything fastagent manages that must NEVER leave the machine (the
+ * agent's `.env` + auth.json): `FASTAGENT_SECRETS_DIR` env > `<agentDir>/.secrets`. Split from
+ * the state root on deploy lifecycle: secrets travel through the host's secret store (env vars / the
+ * auth seed), state through a volume. A deployed box sets both env knobs at its volume (e.g.
+ * `/data/.secrets`, `/data/.state`) so a seeded-then-ROTATED OAuth credential persists across
+ * restarts. The `.env`'s OWN location resolves from the REAL environment — commands locate and load
+ * `.env` before anything else, so a `FASTAGENT_SECRETS_DIR` set INSIDE `.env` still relocates
+ * auth.json but cannot move the file it is read from (env.ts dotEnvPath).
+ */
+export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
+ * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.
+ * A missing target is fine (nothing to guard yet).
+ */
+export declare function assertInsideAgentDir(agentDir: string, name: string): Promise<void>;