@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/value-file.d.ts

@@ -0,0 +1,40 @@
+/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
+export declare function parseEnvContent(content: string): Map<string, string>;
+/**
+ * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
+ * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
+ * file declares, and merging it into the running process would put the two environments in one bag. A missing file
+ * is no values, which is normal.
+ */
+export declare function loadEnvValues(file: string): Map<string, string>;
+/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
+/** The committable template: `<agentDir>/.secrets/.env.example`. */
+export declare function envExamplePath(agentDir: string): string;
+/**
+ * What the agent's value file ({@link dotEnvPath}) adds to this process's environment, read and not entered: each
+ * variable the process does not hold, as entering the file would set it. An agent opened in a process that runs
+ * others too reads its own values through this; one that a command entered (`dev`, `start`) adds nothing here.
+ */
+export declare function agentValues(agentDir: string): Record<string, string>;
+/** One variable to write: with a `value`, an active line; without one, a placeholder under its `hint`. */
+export interface ValueEntry {
+    name: string;
+    value?: string;
+    hint?: string;
+}
+export interface ValueWriteResult {
+    /** Generated values written as active `NAME=value` lines. */
+    written: string[];
+    /** Vars already present with a non-empty active value; left untouched and omitted from next steps. */
+    alreadySet: string[];
+    /** Set when the secrets dir is an operator-chosen one (`FASTAGENT_SECRETS_DIR`) carrying no `.gitignore`. */
+    unprotectedSecretsDir?: string;
+}
+/** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
+export declare function unprotectedSecretsNote(dir: string): string;
+/**
+ * Write `entries` into the selected environment's value file, under a `# --- <section> ---` line. A name with a
+ * non-empty active value is kept unless `overwrite` names it.
+ */
+export declare function writeValues(dir: string, section: string, entries: readonly ValueEntry[], overwrite?: readonly string[]): Promise<ValueWriteResult>;

package/dist/value-file.js

@@ -0,0 +1,164 @@
+/**
+ * The selected environment's value file (`.secrets/.env`, or `.secrets/production/.env` for a deployment), read and
+ * written; entering it into `process.env` is env.ts's. Read as data: what it declares, and what it adds to an agent's
+ * environment. Written: what a command generates (a channel's secret, the Agent API's key) goes in as an active
+ * `NAME=value` line, a value already set stays, and the secrets directory fastagent made carries its own `.gitignore`.
+ */
+import { readFileSync } from "node:fs";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { SECRETS_DIRNAME, SECRET_FILE_MODE, exists, resolveSecretsDir } from "./paths.js";
+import { baseTemplate } from "./scaffold/templates.js";
+/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
+export function parseEnvContent(content) {
+    const parsed = new Map();
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq < 1)
+            continue; // no `=`, or an empty key
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.at(-1) === quote)
+            value = value.slice(1, -1);
+        parsed.set(key, value); // in-file: last occurrence wins (Map overwrite)
+    }
+    return parsed;
+}
+/**
+ * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
+ * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
+ * file declares, and merging it into the running process would put the two environments in one bag. A missing file
+ * is no values, which is normal.
+ */
+export function loadEnvValues(file) {
+    try {
+        return parseEnvContent(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return new Map();
+        throw error;
+    }
+}
+/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+export function dotEnvPath(agentDir, env = process.env) {
+    return join(resolveSecretsDir(agentDir, env), ".env");
+}
+/** The committable template: `<agentDir>/.secrets/.env.example`. */
+export function envExamplePath(agentDir) {
+    return join(agentDir, SECRETS_DIRNAME, ".env.example");
+}
+/**
+ * What the agent's value file ({@link dotEnvPath}) adds to this process's environment, read and not entered: each
+ * variable the process does not hold, as entering the file would set it. An agent opened in a process that runs
+ * others too reads its own values through this; one that a command entered (`dev`, `start`) adds nothing here.
+ */
+export function agentValues(agentDir) {
+    const values = {};
+    for (const [key, value] of loadEnvValues(dotEnvPath(agentDir)))
+        if (!(key in process.env))
+            values[key] = value;
+    return values;
+}
+/** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
+export function unprotectedSecretsNote(dir) {
+    return (`${dir} (FASTAGENT_SECRETS_DIR) now holds a secret and has no .gitignore — that directory is yours, so ` +
+        "fastagent will not write one into it. Make sure git does not track what is in there.");
+}
+/** Whether `.env` content carries a non-empty ACTIVE value for `name`. */
+function hasActiveEnvValue(content, name) {
+    return (parseEnvContent(content).get(name)?.trim() ?? "") !== "";
+}
+function mentionsEnvName(content, name) {
+    return content.split("\n").some((line) => new RegExp(`^\\s*#?\\s*${name}\\s*=`).test(line));
+}
+/**
+ * Write `entries` into the selected environment's value file, under a `# --- <section> ---` line. A name with a
+ * non-empty active value is kept unless `overwrite` names it.
+ */
+export async function writeValues(dir, section, entries, overwrite = []) {
+    const file = dotEnvPath(dir);
+    const secretsDir = dirname(file);
+    await mkdir(secretsDir, { recursive: true });
+    // THE one exception to "fastagent has no opinion about git": the directory it writes secrets into carries its own
+    // `.gitignore`.
+    const owned = secretsDir === join(dir, SECRETS_DIRNAME) || secretsDir === join(dir, SECRETS_DIRNAME, "production");
+    let unprotectedSecretsDir;
+    if (owned) {
+        // Only EEXIST is tolerable (already protected, or a concurrent writer).
+        await writeFile(join(secretsDir, ".gitignore"), baseTemplate("secrets.gitignore"), { flag: "wx" }).catch((e) => {
+            if (e.code !== "EEXIST")
+                throw e;
+        });
+    }
+    else if (!(await exists(join(secretsDir, ".gitignore")))) {
+        unprotectedSecretsDir = secretsDir;
+    }
+    let current = "";
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const alreadySet = entries
+        .filter((e) => !overwrite.includes(e.name) && hasActiveEnvValue(current, e.name))
+        .map((e) => e.name);
+    const lines = [];
+    const written = [];
+    const contentLines = current.split("\n");
+    let replacedInPlace = false;
+    for (const e of entries) {
+        if (alreadySet.includes(e.name))
+            continue;
+        if (e.value !== undefined) {
+            // An ACTIVE but EMPTY assignment already in the file (an uncommented, unfilled placeholder from `cp
+            // .env.example .env`) must be replaced IN PLACE.
+            let idx = -1;
+            for (let i = contentLines.length - 1; i >= 0; i--) {
+                if (parseEnvContent(contentLines[i]).has(e.name)) {
+                    idx = i;
+                    break;
+                }
+            }
+            if (idx >= 0) {
+                contentLines[idx] = `${e.name}=${e.value}`;
+                replacedInPlace = true;
+            }
+            else {
+                lines.push(`${e.name}=${e.value}`);
+            }
+            written.push(e.name);
+        }
+        else if (!mentionsEnvName(current, e.name)) {
+            // Hint above, never inline after `=` (this IS the file loadDotEnv reads).
+            lines.push(...(e.hint === undefined ? [] : [`# ${e.hint}`]), `# ${e.name}=`);
+        }
+    }
+    // 0600 on the file this call CREATES, and nothing at all about one it did not: a `.env` the operator made with
+    // `cp .secrets/.env.example .secrets/.env` carries the mode that command gave it, and re-deciding it would be
+    // fastagent changing the permissions of a file it does not own.
+    const secret = { mode: SECRET_FILE_MODE };
+    if (replacedInPlace) {
+        current = contentLines.join("\n");
+        await writeFile(file, current, secret);
+    }
+    if (lines.length > 0) {
+        const marker = `# --- ${section} ---`;
+        if (current.includes(marker)) {
+            // A marker already present (e.g. a .env copied from .env.example) — slot the new lines under it instead of
+            // orphaning them at the end of the file.
+            await writeFile(file, current.replace(marker, `${marker}\n${lines.join("\n")}`), secret);
+        }
+        else {
+            const prefix = current === "" ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+            await appendFile(file, `${prefix}${marker}\n${lines.join("\n")}\n`, secret);
+        }
+    }
+    return { written, alreadySet, ...(unprotectedSecretsDir === undefined ? {} : { unprotectedSecretsDir }) };
+}

package/dist/version.d.ts

@@ -3,3 +3,8 @@
  * scaffolded dependency range (`^${version}`), so `init` must never fall back and scaffold an uninstallable `^0.0.0`.
  */
 export declare function fastagentVersion(): Promise<string>;
+/** This build's version, and the exact versions of the harness packages it runs, for a new agent to depend on. */
+export declare function fastagentBuild(): Promise<{
+    version: string;
+    harness: Record<string, string>;
+}>;

package/dist/version.js

@@ -5,9 +5,22 @@ import { fileURLToPath } from "node:url";
  * scaffolded dependency range (`^${version}`), so `init` must never fall back and scaffold an uninstallable `^0.0.0`.
  */
 export async function fastagentVersion() {
+    return (await fastagentBuild()).version;
+}
+/** The packages an agent's code imports besides fastagent: the harness its tools and providers are written for. */
+const HARNESS_PACKAGES = ["@earendil-works/pi-durable", "@earendil-works/pi-ai"];
+/** This build's version, and the exact versions of the harness packages it runs, for a new agent to depend on. */
+export async function fastagentBuild() {
     const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
     const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
     if (typeof pkg.version !== "string" || pkg.version === "")
         throw new Error(`no version in ${pkgPath}`);
-    return pkg.version;
+    const harness = {};
+    for (const name of HARNESS_PACKAGES) {
+        const range = pkg.dependencies?.[name];
+        if (range === undefined)
+            throw new Error(`${pkgPath} does not depend on ${name}`);
+        harness[name] = range;
+    }
+    return { version: pkg.version, harness };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.24.4",
+  "version": "0.26.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",
@@ -29,7 +29,7 @@
   "type": "module",
   "sideEffects": false,
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.15.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -38,21 +38,9 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./core": {
-      "types": "./dist/core.d.ts",
-      "default": "./dist/core.js"
-    },
-    "./node": {
-      "types": "./dist/node.d.ts",
-      "default": "./dist/node.js"
-    },
-    "./session": {
-      "types": "./dist/session.d.ts",
-      "default": "./dist/session.js"
-    },
-    "./pi": {
-      "types": "./dist/pi.d.ts",
-      "default": "./dist/pi.js"
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
     },
     "./telegram": {
       "types": "./dist/telegram.d.ts",
@@ -101,31 +89,33 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.99.2",
-    "@earendil-works/pi-ai": "^0.99.2",
-    "@earendil-works/pi-coding-agent": "^0.99.2",
-    "@hono/node-server": "^2.1.1",
+    "@earendil-works/chord": "1.3.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-durable": "1.3.0",
+    "@effect/platform-bun": "^4.0.7",
+    "@effect/platform-node": "^4.0.7",
     "@larksuiteoapi/node-sdk": "^1.71.1",
     "@smithy/signature-v4": "^5.7.4",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
     "croner": "^10.0.1",
-    "effect": "4.0.0-rc.118",
+    "effect": "^4.0.7",
     "giget": "^3.3.0",
-    "ignore": "^7.0.5",
+    "ignore": "^7.0.12",
     "proper-lockfile": "^4.1.2",
     "undici": "^8.6.0",
-    "zod": "^4.4.3"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.14",
+    "@biomejs/biome": "^2.5.15",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@hono/node-server": "^2.1.4",
     "@types/express": "^5.0.6",
     "@types/proper-lockfile": "^4.1.4",
     "express": "^5.2.1",
     "fastify": "^5.12.5",
-    "knip": "^6.37.0",
+    "knip": "^6.41.0",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.1",
-    "yaml": "^2.9.0"
+    "vitest": "^5.0.3"
   }
 }

package/dist/agent.d.ts

@@ -1,106 +0,0 @@
-/**
- * Agent Handler protocol v0.1 — the engine-neutral contract (docs/SPEC.md). Pure types: importing an engine here is
- * forbidden (`@earendil-works/pi-*` may only appear under engines/).
- */
-export type Json = null | boolean | number | string | Json[] | {
-    [k: string]: Json;
-};
-/** Base64-encoded image reference. */
-export interface ImageRef {
-    mimeType: string;
-    data: string;
-}
-export interface Prompt {
-    text: string;
-    images?: ImageRef[];
-}
-export interface Scope {
-    /** Opaque session anchor: turns of the same logical conversation MUST reuse the same value. */
-    session: string;
-    /**
-     * EXTENSION (SPEC §8): the session this one branched from — a channel sets it when the place it is invoking for was
-     * born out of another place (a thread opened in a room).
-     */
-    parentSession?: string;
-    /**
-     * EXTENSION (SPEC §8): opaque markers that MAY locate the branch point inside `parentSession` — e.g. platform
-     * message ids its transcript embeds.
-     */
-    branchHints?: string[];
-}
-export type AgentEvent = {
-    type: "text";
-    delta: string;
-}
-/** Model reasoning, streamed live. */
- | {
-    type: "thinking";
-    delta: string;
-} | {
-    type: "tool_started";
-    id: string;
-    name: string;
-    args: Json;
-} | {
-    type: "tool_ended";
-    id: string;
-    isError: boolean;
-    content: Json;
-}
-/**
- * Advisory, non-terminal (engines MAY emit it): the running tool `id`'s current status, one line, replacing the last.
- * It may be a line of the tool's output so far (trust it like `tool_ended.content`), never the whole output;
- * untruncated, so a consumer that shows it clips it.
- */
- | {
-    type: "tool_progress";
-    id: string;
-    text: string;
-}
-/**
- * Advisory, non-terminal (engines MAY emit it): a transient internal failure scheduled a retry with backoff — the
- * turn is still alive.
- */
- | {
-    type: "retrying";
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-    reason: string;
-}
-/** Terminal: success. */
- | {
-    type: "completed";
-    data?: Json;
-}
-/** Terminal: failure. */
- | {
-    type: "failed";
-    details: string;
-    retryable: boolean;
-    code?: string;
-};
-/**
- * The `failed.code` (SPEC §8 failure subdivision) the reference engine sets when a turn is rejected because the
- * session is BUSY.
- */
-export declare const SESSION_BUSY_CODE = "session_busy";
-/**
- * The `failed.code` set when a run was DELIBERATELY stopped. A channel MAY render cancellation distinctly from an
- * error, and MUST treat it as a settled outcome — durable turn-intent cleanup included — so a deliberate stop is
- * never replayed as a fresh turn on restart.
- */
-export declare const ABORTED_CODE = "aborted";
-/**
- * The `failed.code` set when a turn has no model to run on: its session records none of its own, and the agent sets
- * no default. Not retryable as is: giving the session a model (session control's `update({ model })`) or the agent a
- * default is what changes the answer.
- */
-export declare const MISSING_MODEL_CODE = "missing_model";
-/**
- * One turn = one invoke, returning a single async event stream. The stream MUST terminate with exactly one of
- * `completed` / `failed`, or be cancelled by the caller (no terminal event).
- */
-export interface Agent {
-    invoke(scope: Scope, prompt: Prompt): AsyncIterable<AgentEvent>;
-}

package/dist/agent.js

@@ -1,21 +0,0 @@
-/**
- * Agent Handler protocol v0.1 — the engine-neutral contract (docs/SPEC.md). Pure types: importing an engine here is
- * forbidden (`@earendil-works/pi-*` may only appear under engines/).
- */
-/**
- * The `failed.code` (SPEC §8 failure subdivision) the reference engine sets when a turn is rejected because the
- * session is BUSY.
- */
-export const SESSION_BUSY_CODE = "session_busy";
-/**
- * The `failed.code` set when a run was DELIBERATELY stopped. A channel MAY render cancellation distinctly from an
- * error, and MUST treat it as a settled outcome — durable turn-intent cleanup included — so a deliberate stop is
- * never replayed as a fresh turn on restart.
- */
-export const ABORTED_CODE = "aborted";
-/**
- * The `failed.code` set when a turn has no model to run on: its session records none of its own, and the agent sets
- * no default. Not retryable as is: giving the session a model (session control's `update({ model })`) or the agent a
- * default is what changes the answer.
- */
-export const MISSING_MODEL_CODE = "missing_model";

package/dist/channels/control.d.ts

@@ -1,31 +0,0 @@
-import { type SessionControl, type SessionEvent } from "../session.ts";
-import { type PrefixMount } from "./serve.ts";
-/** The prefix this plane OWNS: everything under it is the plane's to answer. */
-export declare const CONTROL_PREFIX = "/control";
-/**
- * A plane handler: the request, its URL (for query parameters), and the session id the path named (`""` where the
- * path has none).
- */
-type PlaneHandler = (req: Request, url: URL, session: string) => Response | Promise<Response>;
-/**
- * The plane's route table: `"<METHOD> <path>"` → handler, where at most one path segment is {@link SESSION_SEGMENT}.
- */
-export type PlaneRoutes = Record<string, PlaneHandler>;
-/** The SSE payload: one control-plane event in its transport envelope. */
-export interface WireEvent {
-    sessionId: string;
-    /** Serving-process incarnation (per `createControlPlane` call). */
-    epoch: string;
-    /** Per-connection monotonic counter. */
-    seq: number;
-    event: SessionEvent;
-}
-/** Create the control plane as a mountable prefix owner. */
-export declare function createControlPlane(control: SessionControl): PrefixMount;
-/**
- * Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route table is a set of paths,
- * at most one segment of which is a session id.
- */
-export declare function mountControlPlane(routes: PlaneRoutes): PrefixMount;
-export declare function controlPlaneRoutes(control: SessionControl): PlaneRoutes;
-export {};