@fastagent-sh/fastagent 0.14.0 → 0.16.0

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

@@ -1,15 +1,20 @@
 /**
- * The per-turn context a tool's `execute` can read (beyond its abort signal): the SESSION the current
- * turn runs in. A `defineTool` tool is built ONCE and reused across sessions, so the session can't be a
- * closure — it rides an AsyncLocalStorage set around the harness turn (invoke.ts) and read inside
- * `execute` (tool.ts). Undefined outside a turn (e.g. `fastagent tool`, which runs a tool with no
- * session). This is what lets a tool know which conversation it is in — the mechanism the agent's
- * self-scheduling `wake` tool needs to fire a later turn back into the SAME session.
- *
- * Only `session` lives here (a per-turn runtime value). Deploy-time ambients a tool closes over at
- * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
+ * Per-turn capabilities shared by every FastAgent-defined tool. A tool is built once and reused across
+ * turns, so current cwd/session/activation bindings ride AsyncLocalStorage rather than definition
+ * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { SessionTreeEntry } from "@earendil-works/pi-agent-core";
+/** FastAgent's read-only port over the current conversation manager. Serving and chat adapt their
+ * different concrete session implementations to this one tool-runtime contract. */
+export interface ReadonlySessionManager {
+    getSessionId(): string;
+    getHeader(): Promise<{
+        id: string;
+        timestamp: string;
+    }>;
+    getBranch(): Promise<SessionTreeEntry[]>;
+}
 /**
  * The turn's tool-activation bridge — narrow closures over the CURRENT harness (invoke.ts builds it
  * per turn), so a loader tool can activate deferred tools mid-turn without tool.ts importing the
@@ -31,8 +36,10 @@ export interface ToolActivation {
     activate(names: string[]): Promise<string[]>;
 }
 export interface TurnContext {
-    /** The session id of the current turn. */
-    session: string;
+    /** Working directory for this execution. Falls back to process.cwd() only for an unbound direct call. */
+    cwd?: string;
+    /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
+    sessionManager?: ReadonlySessionManager;
     /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
      *  serving harness; chat.ts bridges pi's AgentSession (chat emulates deferral — same loader, same
      *  semantics). Absent only outside any turn (a bare `fastagent tool` run). */

package/dist/engines/pi/tool-context.js

@@ -1,13 +1,7 @@
 /**
- * The per-turn context a tool's `execute` can read (beyond its abort signal): the SESSION the current
- * turn runs in. A `defineTool` tool is built ONCE and reused across sessions, so the session can't be a
- * closure — it rides an AsyncLocalStorage set around the harness turn (invoke.ts) and read inside
- * `execute` (tool.ts). Undefined outside a turn (e.g. `fastagent tool`, which runs a tool with no
- * session). This is what lets a tool know which conversation it is in — the mechanism the agent's
- * self-scheduling `wake` tool needs to fire a later turn back into the SAME session.
- *
- * Only `session` lives here (a per-turn runtime value). Deploy-time ambients a tool closes over at
- * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
+ * Per-turn capabilities shared by every FastAgent-defined tool. A tool is built once and reused across
+ * turns, so current cwd/session/activation bindings ride AsyncLocalStorage rather than definition
+ * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 export const turnContext = new AsyncLocalStorage();

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

@@ -1,16 +1,14 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
-import { type ToolActivation } from "./tool-context.ts";
+import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
 export interface ToolContext {
+    /** Working directory for this execution. */
+    cwd: string;
     /** Abort signal for the current turn — honor it to cancel in-flight work on cancellation. */
     signal?: AbortSignal;
-    /** The session id of the current turn — which conversation this tool is running in. A general tool
-     *  capability: partition per-conversation data, tag logs, scope state. Undefined outside a turn (a bare
-     *  `fastagent tool` run, or any call with no session). (The built-in `wake` tool is one consumer — it
-     *  fires a later turn back into this same session.) In a `fastagent chat` turn this is pi's LOCAL
-     *  chat session id, not a served session — serving-coupled consumers like wake are not mounted there. */
-    session?: string;
+    /** Current conversation manager. Present during serving/chat; absent for sessionless direct calls. */
+    sessionManager?: ReadonlySessionManager;
     /** Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred}
      *  tools with it — the built-in `search_tools` is one consumer). Provided by both the serving path
      *  (invoke.ts, over the harness) and chat (over pi's AgentSession); undefined only outside any turn
@@ -48,7 +46,7 @@ export declare function isDeferredTool(tool: AgentTool): 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 defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): AgentTool;
+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 {
     name: string;

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";
@@ -69,7 +70,12 @@ export function defineTool(options) {
                     },
                 }
                 : undefined;
-            const result = wrapResult(await options.execute(parsed.data, { signal, session: store?.session, tools }));
+            const result = wrapResult(await options.execute(parsed.data, {
+                cwd: store?.cwd ?? process.cwd(),
+                signal,
+                sessionManager: store?.sessionManager,
+                tools,
+            }));
             if (added.length > 0) {
                 // A copy, not a mutation: wrapResult passes a full AgentToolResult through by REFERENCE, and an
                 // author may legally return a shared/frozen result object — stamping in place would corrupt it
@@ -89,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

@@ -15,6 +15,3 @@ export declare function parseDelayMs(input: string | number): number | undefined
 export declare function withWakeTool(tools: AgentTool[], stateRoot: string, enabled: boolean): AgentTool[];
 /** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
 export declare function makeWakeTool(stateRoot: string, now?: () => Date): AgentTool;
-/** Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring
- *  that is no longer needed). Session-scoped — a conversation can never cancel another's. */
-export declare function makeUnwakeTool(stateRoot: string): AgentTool;

package/dist/engines/pi/wake-tool.js

@@ -2,7 +2,7 @@
  * The built-in `wake` tool: the agent's self-scheduling surface. Calling it records a one-shot wake-up
  * (wakeups.ts); the scheduler fires it back into the SAME session, so the agent resumes THIS
  * conversation after a delay ("check the deploy in 10 minutes"). The session comes from the turn
- * context (ToolContext.session, set around the harness turn); the state root is closed over at build
+ * context (ToolContext.sessionManager, set around the harness turn); the state root is closed over at build
  * time (where it is known — the workspace opener), never read from the turn.
  *
  * Mounted by the opener ONLY when `config.selfSchedule` is on AND on the serving path (`dev`/`start`, where
@@ -67,14 +67,15 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
             prompt: z.string().min(1).describe("the instruction for the woken turn (runs in this same conversation)"),
         }),
         execute(input, ctx) {
-            if (!ctx.session)
+            const session = ctx.sessionManager?.getSessionId();
+            if (!session)
                 return "wake is only available inside a conversation (there is no session to resume).";
             if ((input.in === undefined) === (input.cron === undefined)) {
                 return "pass exactly one of `in` (one-shot) or `cron` (recurring).";
             }
             if (input.cron !== undefined) {
                 // addWakeup validates the cron and DERIVES the first instant itself — one computation, one truth.
-                const r = addWakeup(stateRoot, { session: ctx.session, prompt: input.prompt, cron: input.cron, tz: input.tz }, now());
+                const r = addWakeup(stateRoot, { session, prompt: input.prompt, cron: input.cron, tz: input.tz }, now());
                 if (!r.ok)
                     return r.error; // guardrail message the model can act on
                 return `OK — recurring wake ${r.id} (cron "${input.cron}"${input.tz ? ` ${input.tz}` : ""}), first at ${r.fireAt}: ${input.prompt}. Use unwake({ id: "${r.id}" }) to stop it.`;
@@ -84,7 +85,7 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
                 return `couldn't parse "in" (${JSON.stringify(input.in)}) — use a unit like "30m" / "2h" / "1d", or a number of seconds (a bare number as text like "120" is rejected).`;
             }
             const at = new Date(now().getTime() + ms);
-            const r = addWakeup(stateRoot, { session: ctx.session, prompt: input.prompt, fireAt: at }, now());
+            const r = addWakeup(stateRoot, { session, prompt: input.prompt, fireAt: at }, now());
             if (!r.ok)
                 return r.error; // guardrail message the model can act on
             return `OK — I'll wake up at ${r.fireAt} (id ${r.id}) to: ${input.prompt}. Use unwake({ id: "${r.id}" }) if it becomes unnecessary.`;
@@ -93,16 +94,17 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
 }
 /** Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring
  *  that is no longer needed). Session-scoped — a conversation can never cancel another's. */
-export function makeUnwakeTool(stateRoot) {
+function makeUnwakeTool(stateRoot) {
     return defineTool({
         name: "unwake",
         description: "Cancel one of YOUR pending wake-ups (one-shot or recurring) by the id `wake` returned. Use it when " +
             "a scheduled follow-up is no longer needed — especially to stop a recurring wake once its job is done.",
         input: z.object({ id: z.string().min(1).describe("the wake-up id (returned by `wake`)") }),
         execute(input, ctx) {
-            if (!ctx.session)
+            const session = ctx.sessionManager?.getSessionId();
+            if (!session)
                 return "unwake is only available inside a conversation.";
-            return removeWakeup(stateRoot, input.id, ctx.session)
+            return removeWakeup(stateRoot, input.id, session)
                 ? `OK — wake-up ${input.id} cancelled.`
                 : `no pending wake-up ${input.id} in this conversation (already fired, or not yours).`;
         },

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/feishu.d.ts

@@ -1,2 +1,2 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";
+export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuWebSocketChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";

package/dist/feishu.js

@@ -1,2 +1,2 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";
+export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";

package/dist/host/node.d.ts

@@ -1,23 +1,39 @@
 import type { Agent } from "../agent.ts";
+import type { SessionControl } from "../session.ts";
 /** A mounted request handler (a channel's fetch, or a plain route like health). */
 export type ChannelHandler = (req: Request) => Response | Promise<Response>;
 /** This deployment's HTTP surface: route key → handler. Key is `"/path"` or `"METHOD /path"`. */
 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 {
     agent: Agent;
     stateRoot: string;
+    /** The serving session-control hub, when the serve wires one (`config.sessionControl`). Channels
+     *  use it for DISPATCH only (the user-facing stop command); observation stays on the data plane. */
+    control?: SessionControl;
 }
-/** A `channels/<name>.ts` default export: receives the mount context, returns the routes it mounts.
- *  Adapters (`telegramChannel(opts)`, `githubChannel(opts)`) RETURN one of these, so user glue holds
- *  only policy — the framework pipes `agent`/`stateRoot` to the adapter without transiting user code. */
+/** A `channels/<name>.ts` route channel: receives mount context and returns its HTTP routes. */
 export type ChannelModule = (ctx: ChannelContext) => Routes;
+/** One logical long connection's lifecycle. `ready` settles after its first usable connection — and
+ * when `signal` aborts before one exists it must still settle: resolution then means cancellation, not
+ * readiness (the server skips ready-side effects once the signal is aborted; it must never hang).
+ * `closed` resolves after abort-driven shutdown and rejects on a terminal connection failure. */
+export interface LongConnection {
+    ready: Promise<void>;
+    closed: Promise<void>;
+}
+/** A long-connection channel is an explicit module object rather than an HTTP-route factory.
+ * The adapter owns reconnects and treats `signal` as its sole shutdown command. */
+export interface LongConnectionChannelModule {
+    name: string;
+    connect(ctx: ChannelContext, signal: AbortSignal): LongConnection;
+}
 /** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
 export declare function parseRouteKey(key: string): {
     method?: string;
@@ -29,13 +45,14 @@ export declare function parseRouteKey(key: string): {
  */
 export declare function router(routes: Routes): ChannelHandler;
 /**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller close
- * it — no logging/signals/exit (the CLI owns those). `listening` resolves with the bound port (useful
- * for port 0) or rejects on a bind error.
+ * 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.
  */
 export declare function serveNode(handler: ChannelHandler, options: {
     port: number;
 }): {
     listening: Promise<number>;
     close: () => Promise<void>;
+    closeAllConnections: () => void;
 };

package/dist/host/node.js

@@ -32,9 +32,9 @@ export function router(routes) {
     };
 }
 /**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller close
- * it — no logging/signals/exit (the CLI owns those). `listening` resolves with the bound port (useful
- * for port 0) or rejects on a bind error.
+ * 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.
  */
 export function serveNode(handler, options) {
     const server = createServer(nodeListener(async (req) => handler(req)));
@@ -46,5 +46,6 @@ export function serveNode(handler, options) {
         });
     });
     const close = () => new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
-    return { listening, close };
+    const closeAllConnections = () => server.closeAllConnections();
+    return { listening, close, closeAllConnections };
 }

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./core.ts";
+export * from "./session.ts";
 export * from "./pi.ts";

package/dist/index.js

@@ -2,4 +2,5 @@
 // Contract/channel-only consumers should prefer `@fastagent-sh/fastagent/core`; pi-specific consumers
 // may use `@fastagent-sh/fastagent/pi`. The root remains the supported all-in-one surface.
 export * from "./core.js";
+export * from "./session.js";
 export * from "./pi.js";

package/dist/lark.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
  *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
-export { larkChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
+export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";

package/dist/lark.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
  *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
-export { larkChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
+export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";

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/observe.js

@@ -28,6 +28,9 @@ export function logAgentLoop(agent, sink = (line) => log.debug(line)) {
                 else if (e.type === "tool_ended") {
                     sink(`[agent]   tool ${e.isError ? "✗" : "✓"} ${toolName.get(e.id) ?? e.id} → ${preview(e.content)}`);
                 }
+                else if (e.type === "retrying") {
+                    sink(`[agent]   retrying (${e.attempt}/${e.maxAttempts} in ${e.delayMs}ms): ${oneLine(e.reason)}`);
+                }
                 else if (e.type === "completed") {
                     if (thinking.trim() !== "")
                         sink(`[agent]   thinking: ${oneLine(thinking)}`);

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>;