@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/setup-page.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function setupRequestUrl(request: IncomingMessage, response: ServerResponse): URL | undefined;
+/** `1  Title`: the number and the title on one line, so the step's content below shares the card's one left edge. */
+export declare function step(number: number, title: string, content: string, options?: {
+    bare?: boolean;
+}): string;
+/** A sentence under a step's title. `html` is trusted markup: use `<b>` for a name the person must find on another site. */
+export declare const prose: (html: string) => string;
+/** A button that opens another site in a new tab (secondary: the step's real action is the primary button below). */
+export declare function openButton(label: string, href: string): string;
+/**
+ * A labelled input. `label` is the name the other site gives the value, so the person never has to map one to the other.
+ * A secret gets a Show/Hide toggle; nothing is ever put back in a secret field after a refusal.
+ */
+export declare function field(input: {
+    id: string;
+    label: string;
+    placeholder?: string;
+    secret?: boolean;
+    value?: string;
+    invalid?: boolean;
+    autofocus?: boolean;
+}): string;
+/**
+ * What was refused, in bold, and what to do about it. Sits above the field it is about. `why` is the other side's own
+ * words, for someone who has to look it up: small and set apart, so the sentence the person reads stays one they can act on.
+ */
+export declare function refusal(headline: string, detail?: string, why?: string): string;
+export declare const submit: (label: string) => string;
+/** The promise about where a pasted value goes. Said once, the same way, on every page that asks for one. */
+export declare const privacy: () => string;
+/** A page that asks for something: a heading, then the steps, in one form posting back to this address. */
+export declare function formCard(heading: string, steps: string): string;
+/** A page that says where things stand: working (it moves on by itself), done, or stopped. */
+export declare function statusCard(input: {
+    state: "working" | "done" | "failed";
+    heading: string;
+    lede?: string;
+    /** What the person does now, set apart under the status. */
+    next?: string;
+}): string;
+/**
+ * Send a page. The headers are those of a page that takes a secret: nothing cached, nothing framed, nothing loaded from
+ * elsewhere (a nonce admits only this page's own style and script). No `form-action`: browsers apply it to the redirects a
+ * submission is answered with, and Slack's page answers one by sending the browser on to Slack.
+ */
+export declare function sendPage(response: ServerResponse, status: number, page: {
+    title: string;
+    card: string;
+    head?: string;
+}): void;

package/dist/setup-page.js

@@ -0,0 +1,149 @@
+/**
+ * The pages a person sees while FastAgent sets an app up with them: where they paste a credential, and what happens next.
+ * One design for every channel (Slack's tokens, Lark's credentials), so a second page is a repetition of the first.
+ *
+ * The page is self-contained: no font, script or image comes from anywhere else, and it follows the system's light or
+ * dark. It is served to a browser on this machine (or through a tunnel), so a secret pasted into it goes from the browser
+ * to this process and nowhere else — never through a coding agent's conversation or a file the person writes.
+ *
+ * Design rules it keeps, so a page added later keeps them too: one left edge; one primary button per page; a label is the
+ * name the other site uses for the value; an error sits above the field it is about; red is for an error and green for
+ * success only; every text is at least 4.5:1 against its background and an input's edge 3:1.
+ */
+import { randomBytes } from "node:crypto";
+export function setupRequestUrl(request, response) {
+    const url = URL.parse(request.url ?? "/", "http://127.0.0.1");
+    if (url === null) {
+        response.writeHead(400).end("invalid request URL\n");
+        return undefined;
+    }
+    return url;
+}
+const escapeHtml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+const CSS = `
+:root{color-scheme:light dark;--bg:#f4f5f7;--card:#fff;--ink:#11151a;--muted:#4f5a67;--line:#d7dce2;--field:#fff;--edge:#727c88;
+--accent:#0a6a7d;--accent-hover:#085666;--on-accent:#fff;--accent-tint:#e2f2f5;--ok:#17713f;--ok-tint:#e2f4ea;--bad:#b3261e;--bad-tint:#fdecea}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1014;--card:#161a20;--ink:#f2f4f7;--muted:#a3adba;--line:#2c333d;--field:#0d1014;--edge:#6b7684;
+--accent:#46bfd4;--accent-hover:#6bd0e1;--on-accent:#06222a;--accent-tint:#123039;--ok:#5ccd91;--ok-tint:#11301f;--bad:#ff948b;--bad-tint:#3a1815}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.5 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
+-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}
+h1,h2{text-wrap:balance}p{text-wrap:pretty}
+main{max-width:520px;margin:48px auto;padding:0 16px}
+.brand{margin:0 0 16px;font-weight:700;letter-spacing:-.01em}
+.card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:32px}
+h1{font-size:28px;line-height:1.2;font-weight:700;letter-spacing:-.011em;margin:0 0 32px}
+.step+.step{margin-top:40px}
+.step header{display:flex;align-items:center;gap:12px;margin:0 0 8px}
+.step header.bare{margin-bottom:16px}
+.num{flex:none;width:28px;height:28px;border-radius:50%;display:grid;place-items:center;background:var(--accent-tint);color:var(--accent);font-weight:700;font-size:14px}
+.step h2{font-size:18px;line-height:28px;font-weight:700;margin:0}
+.step p{margin:0 0 16px;color:var(--muted)}
+.step p b{color:var(--ink);font-weight:600;white-space:nowrap}
+label{display:block;font-weight:600;font-size:14px;margin:0 0 4px}
+.field{position:relative;margin-bottom:16px}
+input{width:100%;height:48px;padding:0 72px 0 16px;font:15px ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink);background:var(--field);border:1px solid var(--edge);border-radius:8px}
+input.plain{padding-right:16px}
+input[aria-invalid=true]{border-color:var(--bad)}
+input:focus-visible,button:focus-visible,a:focus-visible{outline:3px solid var(--accent);outline-offset:2px}
+.toggle{position:absolute;right:4px;bottom:4px;height:40px;padding:0 12px;border:0;border-radius:6px;background:none;color:var(--accent);font:inherit;font-size:14px;font-weight:600;cursor:pointer}
+.btn{display:inline-flex;align-items:center;justify-content:center;gap:8px;height:48px;padding:0 24px;border-radius:8px;font:inherit;font-size:16px;font-weight:700;line-height:1;text-decoration:none;cursor:pointer;border:2px solid var(--accent)}
+.btn.primary{background:var(--accent);color:var(--on-accent)}
+.btn.primary:hover{background:var(--accent-hover);border-color:var(--accent-hover)}
+.btn.secondary{background:transparent;color:var(--accent)}
+.btn.secondary:hover{background:var(--accent-tint)}
+.btn[disabled]{opacity:.65;cursor:progress}
+.btn.block{width:100%;margin-top:8px}
+.step .privacy{display:flex;align-items:flex-start;gap:8px;margin:12px 0 0;color:var(--muted);font-size:14px;line-height:20px}
+.privacy svg{flex:none;margin-top:2px}
+.error{margin:0 0 16px;padding:12px 16px;border-left:4px solid var(--bad);background:var(--bad-tint);border-radius:0 8px 8px 0;font-size:15px}
+.error b{display:block}
+.error .why{display:block;margin-top:4px;font-size:13px;color:var(--muted);overflow-wrap:anywhere}
+.state{display:flex;align-items:center;gap:16px;margin:0 0 16px}
+.state h1{margin:0}
+.glyph{flex:none;width:40px;height:40px;border-radius:50%;display:grid;place-items:center}
+.glyph.ok{background:var(--ok-tint);color:var(--ok)}
+.glyph.bad{background:var(--bad-tint);color:var(--bad)}
+.glyph.wait{border:4px solid var(--accent-tint);border-top-color:var(--accent);animation:r 1s linear infinite}
+@keyframes r{to{transform:rotate(360deg)}}
+@media (prefers-reduced-motion:reduce){.glyph.wait{animation:none}}
+.lede{margin:0;color:var(--muted)}
+.next{margin:32px 0 0;padding-top:24px;border-top:1px solid var(--line);font-weight:600}
+@media (max-width:480px){.card{padding:24px 20px}h1{font-size:24px}}
+`;
+/** Show/hide for a secret, and a busy button so a second click cannot submit twice. */
+const SCRIPT = `
+document.querySelectorAll(".toggle").forEach(function(b){b.addEventListener("click",function(){
+var i=document.getElementById(b.dataset.for),s=i.type==="password";i.type=s?"text":"password";b.textContent=s?"Hide":"Show"})});
+document.querySelectorAll("form").forEach(function(f){f.addEventListener("submit",function(){
+var g=f.querySelector(".btn.primary");if(g){g.disabled=true;g.textContent="Checking\\u2026"}})});
+`;
+const LOCK = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg>`;
+const OUT = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 4h6v6M20 4l-9 9M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5"/></svg>`;
+const TICK = `<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12.5l4.5 4.5L19 7.5"/></svg>`;
+const CROSS = `<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18"/></svg>`;
+/** `1  Title`: the number and the title on one line, so the step's content below shares the card's one left edge. */
+export function step(number, title, content, options = {}) {
+    return (`<section class="step"><header${options.bare ? ' class="bare"' : ""}><span class="num" aria-hidden="true">${number}</span>` +
+        `<h2>${escapeHtml(title)}</h2></header>${content}</section>`);
+}
+/** A sentence under a step's title. `html` is trusted markup: use `<b>` for a name the person must find on another site. */
+export const prose = (html) => `<p>${html}</p>`;
+/** A button that opens another site in a new tab (secondary: the step's real action is the primary button below). */
+export function openButton(label, href) {
+    return `<a class="btn secondary" href="${escapeHtml(href)}" target="_blank" rel="noopener noreferrer">${escapeHtml(label)} ${OUT}</a>`;
+}
+/**
+ * A labelled input. `label` is the name the other site gives the value, so the person never has to map one to the other.
+ * A secret gets a Show/Hide toggle; nothing is ever put back in a secret field after a refusal.
+ */
+export function field(input) {
+    const { id, label, placeholder, secret, value, invalid, autofocus } = input;
+    return (`<div class="field"><label for="${id}">${escapeHtml(label)}</label>` +
+        `<input id="${id}" name="${id}" class="${secret ? "" : "plain"}" type="${secret ? "password" : "text"}" ` +
+        `${placeholder ? `placeholder="${escapeHtml(placeholder)}" ` : ""}${value ? `value="${escapeHtml(value)}" ` : ""}` +
+        `${invalid ? 'aria-invalid="true" ' : ""}${autofocus ? "autofocus " : ""}` +
+        `autocomplete="off" autocapitalize="off" spellcheck="false" required>` +
+        `${secret ? `<button class="toggle" type="button" data-for="${id}">Show</button>` : ""}</div>`);
+}
+/**
+ * What was refused, in bold, and what to do about it. Sits above the field it is about. `why` is the other side's own
+ * words, for someone who has to look it up: small and set apart, so the sentence the person reads stays one they can act on.
+ */
+export function refusal(headline, detail, why) {
+    return (`<div class="error" role="alert"><b>${escapeHtml(headline)}</b>${detail ? escapeHtml(detail) : ""}` +
+        `${why ? `<span class="why">${escapeHtml(why)}</span>` : ""}</div>`);
+}
+export const submit = (label) => `<button class="btn primary block" type="submit">${escapeHtml(label)}</button>`;
+/** The promise about where a pasted value goes. Said once, the same way, on every page that asks for one. */
+export const privacy = () => `<p class="privacy">${LOCK}<span>Stays on this computer. Never shared with your coding agent.</span></p>`;
+/** A page that asks for something: a heading, then the steps, in one form posting back to this address. */
+export function formCard(heading, steps) {
+    return `<form class="card" method="post"><h1>${escapeHtml(heading)}</h1>${steps}</form>`;
+}
+/** A page that says where things stand: working (it moves on by itself), done, or stopped. */
+export function statusCard(input) {
+    const glyph = input.state === "working"
+        ? `<span class="glyph wait" role="status" aria-label="Working"></span>`
+        : `<span class="glyph ${input.state === "done" ? "ok" : "bad"}">${input.state === "done" ? TICK : CROSS}</span>`;
+    return (`<div class="card"><div class="state">${glyph}<h1>${escapeHtml(input.heading)}</h1></div>` +
+        `${input.lede ? `<p class="lede">${escapeHtml(input.lede)}</p>` : ""}` +
+        `${input.next ? `<p class="next">${escapeHtml(input.next)}</p>` : ""}</div>`);
+}
+/**
+ * Send a page. The headers are those of a page that takes a secret: nothing cached, nothing framed, nothing loaded from
+ * elsewhere (a nonce admits only this page's own style and script). No `form-action`: browsers apply it to the redirects a
+ * submission is answered with, and Slack's page answers one by sending the browser on to Slack.
+ */
+export function sendPage(response, status, page) {
+    const nonce = randomBytes(16).toString("base64");
+    response.statusCode = status;
+    response.setHeader("content-type", "text/html; charset=utf-8");
+    response.setHeader("cache-control", "no-store");
+    response.setHeader("referrer-policy", "no-referrer");
+    response.setHeader("x-content-type-options", "nosniff");
+    response.setHeader("content-security-policy", `default-src 'none'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; base-uri 'none'; frame-ancestors 'none'`);
+    response.end(`<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">` +
+        `${page.head ?? ""}<title>${escapeHtml(page.title)}</title><style nonce="${nonce}">${CSS}</style>` +
+        `<main><p class="brand">FastAgent</p>${page.card}</main><script nonce="${nonce}">${SCRIPT}</script>`);
+}

package/dist/slack.d.ts

@@ -1,4 +1,4 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
-export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
+export { slackChannel, slackSocketChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackSocketChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
 export { slackThreads, slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
 export type { SentSlackMessage, SlackTarget, UploadedSlackFile } from "./channels/slack/slack-api.ts";

package/dist/slack.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
-export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
+export { slackChannel, slackSocketChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
 export { slackThreads, slackTransport } from "./channels/slack/shared-api.js";

package/dist/strip-edges.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Text without the characters at its ends that `isEdge` names, found by index. A regex for it (`/^-+|-+$/`, `/\/+$/`)
+ * backtracks quadratically on a long run that is not at the end, and what is trimmed here is often a name or a URL
+ * somebody else wrote.
+ */
+export declare function stripEdges(text: string, isEdge: (char: string) => boolean): string;
+/** `text` without the characters at its end that `isEdge` names. */
+export declare function stripEnd(text: string, isEdge: (char: string) => boolean): string;
+/** A URL or path without the `/` that ends it. */
+export declare function stripTrailingSlashes(text: string): string;

package/dist/strip-edges.js

@@ -0,0 +1,22 @@
+/**
+ * Text without the characters at its ends that `isEdge` names, found by index. A regex for it (`/^-+|-+$/`, `/\/+$/`)
+ * backtracks quadratically on a long run that is not at the end, and what is trimmed here is often a name or a URL
+ * somebody else wrote.
+ */
+export function stripEdges(text, isEdge) {
+    let start = 0;
+    while (start < text.length && isEdge(text[start]))
+        start++;
+    return stripEnd(text.slice(start), isEdge);
+}
+/** `text` without the characters at its end that `isEdge` names. */
+export function stripEnd(text, isEdge) {
+    let end = text.length;
+    while (end > 0 && isEdge(text[end - 1]))
+        end--;
+    return text.slice(0, end);
+}
+/** A URL or path without the `/` that ends it. */
+export function stripTrailingSlashes(text) {
+    return stripEnd(text, (char) => char === "/");
+}

package/dist/telegram.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
-export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
+export { telegramChannel, telegramPollingChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramPollingChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
 export { telegramTransport, type TelegramSendTarget, type TelegramSent, type TelegramTransport, } from "./channels/telegram/shared-api.ts";

package/dist/telegram.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
-export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";
+export { telegramChannel, telegramPollingChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";
 export { telegramTransport, } from "./channels/telegram/shared-api.js";

package/dist/tunnel.d.ts

@@ -26,7 +26,6 @@ export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloud
 /** Print the public URL and wire up first-party webhook channels found under `dir` (the agent ROOT). */
 export declare function announceWebhooks(dir: string, baseUrl: string, channels: readonly DeclaredChannel[], opts?: {
     openUrl?: (url: string) => void;
-    stateRoot?: string;
     env?: NodeJS.ProcessEnv;
     /** {@link Registrars.leave}. */
     leave?: (step: string) => void;

package/dist/tunnel.js

@@ -5,13 +5,12 @@
  */
 import { spawn } from "node:child_process";
 import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
-import { registerSlackWebhook } from "./channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
-import { pointChannelsAt, webhookKinds } from "./deploy/channel-ingress.js";
+import { pointChannelsAt } from "./deploy/channel-ingress.js";
+import { webhookKinds } from "./channels/webhooks.js";
 import { loadDotEnv } from "./env.js";
 import { dotEnvPath } from "./value-file.js";
 import { installProxyFetch } from "./proxy.js";
-import { AGENT_ENVIRONMENT_ENV, resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";
 // `(?!api\.)`: cloudflared's ERROR lines mention its request endpoint (`https://api.trycloudflare.com/tunnel`, e.g.
 // "failed to request quick Tunnel: Post ... timeout" under a flaky proxy) — without the exclusion a transient error
@@ -157,11 +156,6 @@ export async function announceWebhooks(dir, baseUrl, channels, opts = {}) {
         registrars: {
             ...(opts.leave === undefined ? {} : { leave: opts.leave }),
             telegram: (url) => registerTelegramWebhook(url, { env: opts.env }),
-            slack: (url) => registerSlackWebhook(url, {
-                stateRoot: opts.stateRoot ?? resolveStateRoot(dir),
-                environment: process.env[AGENT_ENVIRONMENT_ENV] === "production" ? "production" : "dev",
-                log: (message) => log.info(message),
-            }),
             feishu: (url, kind) => registerFeishuWebhook(url, kind, feishuOptions),
         },
     });

package/dist/value-file.d.ts

@@ -7,7 +7,9 @@ export declare function parseEnvContent(content: string): Map<string, string>;
  * is no values, which is normal.
  */
 export declare function loadEnvValues(file: string): Map<string, string>;
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+/** Use `path` as the agent's value file from here on, or the default again. */
+export declare function useValueFile(path: string | undefined): void;
+/** The agent's `.env` file: the one `--env-file` named, else `<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;
@@ -31,10 +33,14 @@ export interface ValueWriteResult {
     /** 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.
+ * What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track; `chosenBy`
+ * is what put the secrets there (the operator's `FASTAGENT_SECRETS_DIR`, unless the caller knows better).
  */
-export declare function writeValues(dir: string, section: string, entries: readonly ValueEntry[], overwrite?: readonly string[]): Promise<ValueWriteResult>;
+export declare function unprotectedSecretsNote(dir: string, chosenBy?: string): string;
+export declare function prepareSecretsDirectory(dir: string, secretsDir: string): Promise<string | undefined>;
+/**
+ * Write `entries` into `file` (default: 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[], file?: string): Promise<ValueWriteResult>;

package/dist/value-file.js

@@ -44,9 +44,19 @@ export function loadEnvValues(file) {
         throw error;
     }
 }
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+/**
+ * The value file this process's command was told to use (`--env-file`). Process state set at the command's entry, not
+ * an environment variable: a variable would be read from a shell, by commands that never took the flag, and by what
+ * the agent runs. A `dev` worker is spawned with its supervisor's arguments and takes the flag itself.
+ */
+let selectedValueFile;
+/** Use `path` as the agent's value file from here on, or the default again. */
+export function useValueFile(path) {
+    selectedValueFile = path;
+}
+/** The agent's `.env` file: the one `--env-file` named, else `<resolved secrets dir>/.env`. */
 export function dotEnvPath(agentDir, env = process.env) {
-    return join(resolveSecretsDir(agentDir, env), ".env");
+    return selectedValueFile ?? join(resolveSecretsDir(agentDir, env), ".env");
 }
 /** The committable template: `<agentDir>/.secrets/.env.example`. */
 export function envExamplePath(agentDir) {
@@ -64,11 +74,28 @@ export function agentValues(agentDir) {
             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 ` +
+/**
+ * What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track; `chosenBy`
+ * is what put the secrets there (the operator's `FASTAGENT_SECRETS_DIR`, unless the caller knows better).
+ */
+export function unprotectedSecretsNote(dir, chosenBy = "FASTAGENT_SECRETS_DIR") {
+    return (`${dir} (${chosenBy}) 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.");
 }
+export async function prepareSecretsDirectory(dir, secretsDir) {
+    await mkdir(secretsDir, { recursive: true });
+    const owned = secretsDir === join(dir, SECRETS_DIRNAME) || secretsDir === join(dir, SECRETS_DIRNAME, "production");
+    if (owned) {
+        // EEXIST preserves an existing ignore file, including one created by a concurrent writer.
+        await writeFile(join(secretsDir, ".gitignore"), baseTemplate("secrets.gitignore"), { flag: "wx" }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+    }
+    else if (!(await exists(join(secretsDir, ".gitignore")))) {
+        return secretsDir;
+    }
+}
 /** Whether `.env` content carries a non-empty ACTIVE value for `name`. */
 function hasActiveEnvValue(content, name) {
     return (parseEnvContent(content).get(name)?.trim() ?? "") !== "";
@@ -77,27 +104,11 @@ 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.
+ * Write `entries` into `file` (default: 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;
-    }
+export async function writeValues(dir, section, entries, overwrite = [], file = dotEnvPath(dir)) {
+    const unprotectedSecretsDir = await prepareSecretsDirectory(dir, dirname(file));
     let current = "";
     try {
         current = await readFile(file, "utf8");

package/dist/version.d.ts

@@ -3,8 +3,14 @@
  * 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. */
+/** The packages an agent's code imports besides fastagent: the harness its tools and providers are written for. */
+export declare const HARNESS_PACKAGES: string[];
+/**
+ * This build's version, the exact versions of the harness packages it runs, and the TypeScript `fastagent build`
+ * compiles with (FastAgent's own), for a new agent to depend on.
+ */
 export declare function fastagentBuild(): Promise<{
     version: string;
     harness: Record<string, string>;
+    typescript: string;
 }>;

package/dist/version.js

@@ -8,8 +8,11 @@ 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 const HARNESS_PACKAGES = ["@earendil-works/pi-durable", "@earendil-works/pi-ai", "@earendil-works/pi-schema"];
+/**
+ * This build's version, the exact versions of the harness packages it runs, and the TypeScript `fastagent build`
+ * compiles with (FastAgent's own), 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"));
@@ -22,5 +25,8 @@ export async function fastagentBuild() {
             throw new Error(`${pkgPath} does not depend on ${name}`);
         harness[name] = range;
     }
-    return { version: pkg.version, harness };
+    const typescript = pkg.devDependencies?.typescript;
+    if (typescript === undefined)
+        throw new Error(`${pkgPath} does not develop with typescript`);
+    return { version: pkg.version, harness, typescript };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.28.0",
+  "version": "0.30.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",
@@ -77,7 +77,6 @@
     "build": "tsc -p tsconfig.build.json",
     "prepack": "npm run build",
     "test": "vitest --run",
-    "test:live": "vitest --run --config vitest.live.config.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src test && node scripts/check-doc-links.mjs && knip",
     "format": "biome check --write src test",
@@ -89,12 +88,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/chord": "1.4.0",
-    "@earendil-works/pi-ai": "1.4.0",
-    "@earendil-works/pi-durable": "1.4.0",
+    "@earendil-works/chord": "1.5.0",
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-durable": "1.5.0",
+    "@earendil-works/pi-schema": "1.5.0",
     "@effect/platform-bun": "^4.0.7",
     "@effect/platform-node": "^4.0.7",
     "@larksuiteoapi/node-sdk": "^1.76.0",
+    "@modelcontextprotocol/client": "2.4.0",
     "@smithy/signature-v4": "^5.7.4",
     "chokidar": "^6.0.0",
     "commander": "^15.0.0",
@@ -108,8 +109,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.6.4",
-    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
     "@hono/node-server": "^2.1.5",
+    "@modelcontextprotocol/server": "2.4.0",
     "@types/express": "^5.0.6",
     "@types/proper-lockfile": "^4.1.4",
     "express": "^5.3.0",

package/dist/channels/lark/onboard.d.ts

@@ -1,36 +0,0 @@
-import type { FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
-/** Guided Lark-international onboarding. */
-export declare const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
-/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
-export declare function larkEventSecurityUrl(appId: string): string;
-export interface LarkOnboardIO {
-    /** A page for the person, and what they do there. */
-    openUrl(url: string, action: string): void;
-    note(message: string): void;
-    prompt(message: string, opts?: {
-        hidden?: boolean;
-    }): Promise<string | undefined>;
-}
-interface LarkBootstrapResult {
-    /** Challenge-captured token: the PATCH also switched Subscription mode to webhook. */
-    token?: string;
-    /** Present only for a definitive config-route 404; tells the user why the manual path is active. */
-    manualReason?: string;
-}
-export interface LarkOnboardOptions {
-    /** Existing active .env values. */
-    existing?: Readonly<Record<string, string | undefined>>;
-    ingress?: FeishuSubscriptionMode;
-    verifyCredentials(appId: string, appSecret: string): Promise<void>;
-    bootstrapWebhook?(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
-    /** The command that continues an interrupted setup: the one that started it (`add lark`, `deploy <host> --run`). */
-    rerun?: string;
-}
-export interface LarkOnboardCredentials {
-    LARK_APP_ID: string;
-    LARK_APP_SECRET: string;
-    LARK_VERIFICATION_TOKEN?: string;
-}
-/** Open the stable app console and collect everything the runtime needs. */
-export declare function onboardLarkApp(io: LarkOnboardIO, opts: LarkOnboardOptions): Promise<LarkOnboardCredentials>;
-export {};

package/dist/channels/lark/onboard.js

@@ -1,56 +0,0 @@
-/** Guided Lark-international onboarding. */
-export const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
-/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
-export function larkEventSecurityUrl(appId) {
-    return `https://open.larksuite.com/app/${encodeURIComponent(appId)}/event?tab=safe`;
-}
-function required(value, name, rerun) {
-    const trimmed = value?.trim();
-    if (!trimmed)
-        throw new Error(`${name} is required — re-run \`${rerun}\` to continue setup`);
-    return trimmed;
-}
-/** Open the stable app console and collect everything the runtime needs. */
-export async function onboardLarkApp(io, opts) {
-    const rerun = opts.rerun ?? "fastagent add lark";
-    const existingId = opts.existing?.LARK_APP_ID?.trim();
-    const existingSecret = opts.existing?.LARK_APP_SECRET?.trim();
-    const reuseExistingApp = Boolean(existingId && existingSecret);
-    // Credentials are one App-scoped set.
-    if (reuseExistingApp) {
-        io.note(`Reusing Lark app ${existingId}.`);
-    }
-    else {
-        io.openUrl(LARK_CONSOLE_URL, "create the app on Lark's one-click launcher; LARK_APP_ID and LARK_APP_SECRET are under Credentials & Basic Info");
-    }
-    const appId = required(reuseExistingApp ? existingId : await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID", rerun);
-    const appSecret = required(reuseExistingApp ? existingSecret : await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET", rerun);
-    await opts.verifyCredentials(appId, appSecret);
-    const eventSecurityUrl = larkEventSecurityUrl(appId);
-    io.note("App ID / Secret verified.");
-    if (opts.ingress === "websocket") {
-        io.openUrl(eventSecurityUrl, "in Events & Callbacks, choose long connection and subscribe im.message.receive_v1, but do not publish yet: " +
-            "the permission check follows (no Verification Token or Request URL is needed)");
-        return { LARK_APP_ID: appId, LARK_APP_SECRET: appSecret };
-    }
-    io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
-    if (!opts.bootstrapWebhook)
-        throw new Error("Lark webhook onboarding requires bootstrapWebhook");
-    const bootstrap = await opts.bootstrapWebhook(appId, appSecret);
-    if (bootstrap.token) {
-        io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");
-    }
-    else {
-        io.note(bootstrap.manualReason ?? "Automatic bootstrap unavailable.");
-        io.openUrl(eventSecurityUrl, "in Events & Callbacks → Encryption Strategy, copy the Verification Token, and switch Subscription mode to " +
-            "webhook when setting the Request URL");
-    }
-    const verificationToken = required(bootstrap.token ||
-        (reuseExistingApp ? opts.existing?.LARK_VERIFICATION_TOKEN?.trim() : undefined) ||
-        (await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN", rerun);
-    return {
-        LARK_APP_ID: appId,
-        LARK_APP_SECRET: appSecret,
-        LARK_VERIFICATION_TOKEN: verificationToken,
-    };
-}