@fastagent-sh/fastagent 0.24.3 → 0.25.0

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.3",
+  "version": "0.25.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 {};

package/dist/channels/control.js

@@ -1,329 +0,0 @@
-import { INVALID_COMMAND_CODE, SESSIONS_UNAVAILABLE_CODE, UNSUPPORTED_CAPABILITY_CODE, UPDATE_FIELDS, } from "../session.js";
-import { parseRouteKey, withoutBody } from "./serve.js";
-import { log } from "../log.js";
-import { readBodyCapped } from "./body.js";
-import { MAX_BODY_BYTES } from "./http.js";
-import { sseResponse } from "./sse.js";
-import { text } from "./respond.js";
-/** The prefix this plane OWNS: everything under it is the plane's to answer. */
-export const CONTROL_PREFIX = "/control";
-/** The one variable segment in this plane's paths: a percent-encoded session id. */
-const SESSION_SEGMENT = "{session}";
-/**
- * What `.../image` may answer under the image's own type. `mimeType` is whatever the prompt's sender wrote, and served
- * as-is a `text/html` or `image/svg+xml` "image" would run script on whatever origin fronts this plane.
- */
-const RASTER_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
-const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
-/** The plane as one mounted sub-application rather than routes sharing a prefix. */
-function planeApp(routes) {
-    /** A route key's path split into segments, with `{session}` marked. */
-    const compiled = Object.entries(routes).map(([key, handler]) => {
-        const { method, path } = parseRouteKey(key);
-        return { method, path, segments: path.split("/"), handler };
-    });
-    const match = (path) => {
-        const segments = path.split("/");
-        const hits = [];
-        for (const route of compiled) {
-            if (route.segments.length !== segments.length)
-                continue;
-            let session;
-            let ok = true;
-            for (const [i, expected] of route.segments.entries()) {
-                const actual = segments[i];
-                if (expected === SESSION_SEGMENT) {
-                    // The one place a path segment becomes a Caller id again.
-                    if (actual === "") {
-                        ok = false;
-                        break;
-                    }
-                    try {
-                        session = decodeURIComponent(actual);
-                    }
-                    catch {
-                        // `%zz` and friends: not an id any client could have produced, so this path matches nothing and falls
-                        // through to the plane's own 404.
-                        ok = false;
-                        break;
-                    }
-                }
-                else if (expected !== actual) {
-                    ok = false;
-                    break;
-                }
-            }
-            if (ok)
-                hits.push({ route, session });
-        }
-        return hits;
-    };
-    return async (req) => {
-        const url = new URL(req.url);
-        const path = url.pathname;
-        const hits = match(path);
-        const answer = async () => {
-            const hit = hits.find((h) => h.route.method === req.method) ??
-                (req.method === "HEAD" ? hits.find((h) => h.route.method === "GET") : undefined);
-            if (hit)
-                return await hit.route.handler(req, url, hit.session ?? "");
-            // 404 vs 405 as in the host router: a client reads 404 as "this serve predates the route".
-            if (hits.length > 0)
-                return text("method not allowed\n", 405);
-            return text("not found\n", 404);
-        };
-        let res;
-        try {
-            // HEAD carries no content, whichever branch answered — including this plane's own 404/405.
-            const answered = await answer();
-            res = req.method === "HEAD" ? withoutBody(answered) : answered;
-        }
-        catch (error) {
-            // The plane's own totality boundary: a rejecting handler (`commands()` on an unreadable definition) must still
-            // answer with the headers; the message stays internal.
-            log.error(`[control] ${req.method} ${path} failed: ${String(error)}`);
-            res = text("internal error\n", 500);
-        }
-        // CORS is NOT set here: the host router owns that verdict for every path it publishes, this prefix included
-        // (channels/serve.ts). A second writer of those headers is a second policy to keep in sync.
-        return res;
-    };
-}
-// ONE constant for every Prompt-bearing wire surface (imported from the invoke channel — the two caps cannot drift
-// apart).
-const ACTION_BODY_LIMIT = MAX_BODY_BYTES;
-/**
- * Parse-don't-validate at the wire: a remote client can send any JSON, and the hub's inner layers trust action shapes
- * (a malformed `steer` would surface as an ENGINE failure misclassified as `run_command_failed`).
- */
-function parseWireAction(raw) {
-    // COMPILE-TIME drift guard, variant level: this switch hand-mirrors the SessionAction union, and a new variant
-    // added in session.ts would otherwise compile clean while the wire answers it `invalid_command` — silently breaking
-    // local/remote isomorphism.
-    const _actionDriftGuard = {
-        steer: true,
-        follow_up: true,
-        abort: true,
-        compact: true,
-    };
-    void _actionDriftGuard;
-    if (typeof raw !== "object" || raw === null)
-        return undefined;
-    const c = raw;
-    const imageOk = (i) => typeof i === "object" &&
-        i !== null &&
-        typeof i.data === "string" &&
-        typeof i.mimeType === "string";
-    const promptOk = (p) => {
-        if (typeof p !== "object" || p === null)
-            return false;
-        if (typeof p.text !== "string")
-            return false;
-        const images = p.images;
-        // Element-level: `images: [42]` reaching the engine would resurface exactly the misclassified failure this parser
-        // exists to prevent (ImageRef shape from src/session.ts's Prompt).
-        return images === undefined || (Array.isArray(images) && images.every(imageOk));
-    };
-    // REBUILD, never pass raw through: "typed out" must be construction, not assertion — a passed-through object would
-    // carry arbitrary extra keys into the engine.
-    const rebuildPrompt = (p) => {
-        const images = p.images;
-        return {
-            text: p.text,
-            ...(images ? { images: images.map((i) => ({ data: i.data, mimeType: i.mimeType })) } : {}),
-        };
-    };
-    // COMPILE-TIME drift guard: whitelist reconstruction silently strips any field it does not know.
-    const _promptDriftGuard = {};
-    void _promptDriftGuard;
-    // Same guard one level down: the image whitelist ({data, mimeType}) must break when ImageRef grows a field.
-    const _imageDriftGuard = {};
-    void _imageDriftGuard;
-    switch (c.type) {
-        case "steer":
-        case "follow_up":
-            return promptOk(c.prompt) ? { type: c.type, prompt: rebuildPrompt(c.prompt) } : undefined;
-        case "abort":
-            return { type: "abort" };
-        case "compact":
-            return c.instructions === undefined || typeof c.instructions === "string"
-                ? { type: "compact", instructions: c.instructions }
-                : undefined;
-        default:
-            return undefined;
-    }
-}
-/**
- * Parse a PATCH body into a session update — or into the REASON it is not one, because the two reasons are different
- * answers to the client.
- */
-function parseWireUpdate(raw) {
-    if (typeof raw !== "object" || raw === null) {
-        return { code: INVALID_COMMAND_CODE, message: "expected an object of session properties" };
-    }
-    const c = raw;
-    const unknown = Object.keys(c).filter((key) => !UPDATE_FIELDS.includes(key));
-    if (unknown.length > 0) {
-        return {
-            code: UNSUPPORTED_CAPABILITY_CODE,
-            message: `update field(s) ${unknown.join(", ")} — capabilities().updatable lists what this serve sets`,
-        };
-    }
-    const patch = {};
-    // The field list is the CONTRACT's (`UPDATE_FIELDS`), not a copy: a field added to SessionUpdate travels here
-    // without anyone remembering to, and one removed cannot linger.
-    for (const field of UPDATE_FIELDS) {
-        const value = c[field];
-        if (value === undefined)
-            continue;
-        if (typeof value !== "string") {
-            return { code: INVALID_COMMAND_CODE, message: `${field} must be a string` };
-        }
-        patch[field] = value;
-    }
-    return { patch };
-}
-/** Create the control plane as a mountable prefix owner. */
-export function createControlPlane(control) {
-    return mountControlPlane(controlPlaneRoutes(control));
-}
-/**
- * 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 function mountControlPlane(routes) {
-    return { prefix: CONTROL_PREFIX, handler: planeApp(routes) };
-}
-export function controlPlaneRoutes(control) {
-    const epoch = crypto.randomUUID();
-    /**
-     * Read a JSON body under the shared cap.
-     *
-     * No content-type gate here: this plane only ever rides the host router, which applies it to every route that
-     * authenticates nobody — this whole prefix included (channels/serve.ts).
-     */
-    const readJson = async (req) => {
-        const body = await readBodyCapped(req, ACTION_BODY_LIMIT);
-        // The 413 names the ceiling: the docs promise images on this plane, and an unexplained rejection would send a
-        // client author hunting everywhere but the cap.
-        if ("tooLarge" in body) {
-            return {
-                error: text(`body too large (limit ${MAX_BODY_BYTES >> 20} MiB — images count base64-inflated)\n`, 413),
-            };
-        }
-        // An empty body is an empty object: `POST …/actions` always carries one, but `PATCH` with nothing to set is a
-        // legal no-op and a client should not have to send `{}` to say so.
-        if (body.text.trim() === "")
-            return { value: {} };
-        try {
-            return { value: JSON.parse(body.text) };
-        }
-        catch {
-            return { error: text("invalid JSON\n", 400) };
-        }
-    };
-    return {
-        "GET /control/capabilities": () => json(control.capabilities()),
-        "GET /control/commands": async () => json(await control.commands()),
-        // The DEPLOYMENT's conversation list — and the one read that may fail.
-        "GET /control/sessions": async () => {
-            try {
-                return json(await control.sessions.list());
-            }
-            catch (error) {
-                // ONLY a store fault becomes the retryable code.
-                const code = error?.code;
-                if (typeof code !== "string" || !/^E[A-Z]+$/.test(code))
-                    throw error;
-                // Logged as well as answered: the catch would otherwise be the one place a store fault is invisible on the
-                // server, since it preempts the boundary that does the logging.
-                log.error(`[control] GET /control/sessions failed: ${String(error)}`);
-                return json({ code: SESSIONS_UNAVAILABLE_CODE, message: String(error), retryable: true }, 503);
-            }
-        },
-        // PUT, because a fork is idempotent: this id, holding the history that was at `from`@`at`.
-        [`PUT /control/sessions/${SESSION_SEGMENT}`]: async (req, _url, session) => {
-            const read = await readJson(req);
-            if ("error" in read)
-                return read.error;
-            // `JSON.parse("null")` is null, and a body is whatever the client sent: reaching into it unguarded turns a
-            // malformed request into a 500 the client cannot act on.
-            const body = read.value;
-            if (typeof body?.from !== "string" || typeof body.at !== "string") {
-                return text("expected { from: string, at: string }\n", 400);
-            }
-            return json(await control.sessions.fork({ from: body.from, at: body.at, into: session }));
-        },
-        [`GET /control/sessions/${SESSION_SEGMENT}`]: async (_req, _url, session) => json(await control.sessions.get(session).state()),
-        // PATCH, because these are session PROPERTIES: last-wins, durable, applied by the next turn.
-        [`PATCH /control/sessions/${SESSION_SEGMENT}`]: async (req, _url, session) => {
-            const read = await readJson(req);
-            if ("error" in read)
-                return read.error;
-            const parsed = parseWireUpdate(read.value);
-            // A protocol-level answer carrying the SAME code the hub would have used.
-            if (!("patch" in parsed)) {
-                return json({ ok: false, error: { ...parsed, retryable: false } });
-            }
-            return json(await control.sessions.get(session).update(parsed.patch));
-        },
-        [`DELETE /control/sessions/${SESSION_SEGMENT}`]: async (_req, _url, session) => json(await control.sessions.get(session).delete()),
-        [`GET /control/sessions/${SESSION_SEGMENT}/entries`]: async (_req, url, session) => {
-            const since = url.searchParams.get("since") ?? undefined;
-            return json(await control.sessions.get(session).entries(since !== undefined ? { since } : undefined));
-        },
-        // Raw bytes, not JSON-wrapped base64: a client can hand the response straight to an <img>. The ref names a
-        // durable entry, so the answer never changes. `ref` rides the query because this router has one path variable.
-        [`GET /control/sessions/${SESSION_SEGMENT}/image`]: async (_req, url, session) => {
-            const ref = url.searchParams.get("ref");
-            if (ref === null)
-                return text("expected ?ref=, an images[].ref from entries()\n", 400);
-            const image = await control.sessions.get(session).image(ref);
-            // The local call RETURNS undefined, so this is a 2xx (§13); a 404 stays "this serve predates the route".
-            if (!image)
-                return new Response(null, { status: 204 });
-            return new Response(Buffer.from(image.data, "base64"), {
-                headers: {
-                    "content-type": RASTER_IMAGE_TYPES.has(image.mimeType) ? image.mimeType : "application/octet-stream",
-                    "x-content-type-options": "nosniff",
-                    "cache-control": "private, max-age=31536000, immutable",
-                },
-            });
-        },
-        // The run actions.
-        [`POST /control/sessions/${SESSION_SEGMENT}/actions`]: async (req, _url, session) => {
-            const read = await readJson(req);
-            if ("error" in read)
-                return read.error;
-            const action = parseWireAction(read.value);
-            if (!action) {
-                return json({
-                    ok: false,
-                    error: { code: INVALID_COMMAND_CODE, message: "malformed action", retryable: false },
-                });
-            }
-            const s = control.sessions.get(session);
-            // The result rides HTTP 200 either way: `ok: false` is a protocol-level answer (rejected before acceptance),
-            // not a transport failure.
-            switch (action.type) {
-                case "steer":
-                    return json(await s.steer(action.prompt));
-                case "follow_up":
-                    return json(await s.followUp(action.prompt));
-                case "abort":
-                    return json(await s.abort());
-                case "compact":
-                    return json(await s.compact(action.instructions !== undefined ? { instructions: action.instructions } : {}));
-            }
-        },
-        [`GET /control/sessions/${SESSION_SEGMENT}/events`]: (_req, _url, session) => {
-            let seq = 0;
-            return sseResponse(control.sessions.get(session).events(), (event) => ({
-                sessionId: session,
-                epoch,
-                seq: seq++,
-                event,
-            }));
-        },
-    };
-}

package/dist/channels/define-channel.d.ts

@@ -1,39 +0,0 @@
-/**
- * `defineChannel` — a channel file's authoring surface, and the third member of the `defineX` family
- * (with `defineTool` / `defineRoutine`). Its whole job is the secrets: a channel is the one code
- * input that is ALL credentials (a bot token, a signing secret), and before this it read them from
- * `process.env` at module scope, which meant a CUSTOM channel could not tell `deploy` what to carry —
- * the deploy could only guess from a table of first-party names.
- *
- * The declaration attaches to the module WITHOUT adding a third module form to the Channel contract
- * (channel.ts §7 fixes two: a function is a route channel, an object with `connect` is a long
- * connection). The builder runs at import and returns one of those two; the declared names ride along
- * as a property that the discovery reads and everything else ignores.
- *
- * Values are read at import, so a rotated credential needs a restart — the same lifetime an adapter
- * configured with a literal already has, and the reason there is no per-request accessor here.
- *
- * KNOWN GAP: every declared name is REQUIRED (the gate refuses an empty value), so an
- * OPTIONAL credential has no expression here — declare it and an agent that does not use it cannot
- * start; leave it out and `deploy` does not carry it. First-party channels have the third answer in
- * the scaffold table (`ChannelEnv.required`), which is why feishu/lark still read their optional
- * `*_ENCRYPT_KEY` from the environment. Closing it means a second entry shape here
- * (`{ name, required: false }`) carried through `DeclaredSecret`, `missingSecrets` and the deploy
- * runbook's required flag — a contract change, not a local one.
- */
-import type { ChannelModule, LongConnectionChannelModule } from "../channel.ts";
-/** A channel module carrying what it declared it needs. Read by discovery; ignored by the server. */
-type DeclaringChannelModule<M> = M & {
-    secrets?: readonly string[];
-};
-export interface DefineChannelOptions<S extends readonly string[], M> {
-    /**
-     * Env vars this channel needs (`["TELEGRAM_BOT_TOKEN"]`), typed into `channel`. `deploy` carries
-     * them to the host and `dev`/`start` refuse to serve while one is unset, naming this file.
-     */
-    secrets?: S;
-    /** Build the channel from those values — usually one call to an adapter (`telegramChannel({...})`). */
-    channel: (secrets: Record<S[number], string>) => M;
-}
-export declare function defineChannel<const S extends readonly string[] = readonly [], M extends ChannelModule | LongConnectionChannelModule = ChannelModule>(options: DefineChannelOptions<S, M>): DeclaringChannelModule<M>;
-export {};

package/dist/channels/define-channel.js

@@ -1,9 +0,0 @@
-import { secretValues } from "../declared-secrets.js";
-// `S` defaults to the EMPTY tuple for the same reason as `defineTool`: a channel that declares
-// nothing must not type-check `secrets.ANYTHING`.
-export function defineChannel(options) {
-    const built = options.channel(secretValues(options.secrets));
-    // Object.assign on a FUNCTION module keeps it a function (the route-channel form); on the
-    // long-connection object it adds one field. Either way the shape the server sees is unchanged.
-    return Object.assign(built, options.secrets ? { secrets: options.secrets } : {});
-}