@fastagent-sh/fastagent 0.12.0

package/dist/log.js

@@ -0,0 +1,51 @@
+/**
+ * Leveled logging. Runtime logs (lifecycle, warnings, errors, the debug turn trace) flow through ONE
+ * process-level logger, gated by a single level. It is a module singleton — not an injected dependency —
+ * because most runtime logs originate inside author-constructed channels (`channels/*.ts` call the
+ * channel factory themselves) and deep engine code, which the CLI cannot thread a logger into. The CLI
+ * sets the level by posture (dev → debug, start → info); `FASTAGENT_LOG_LEVEL` overrides it.
+ *
+ * This is NOT the CLI's user-facing output (help text, command results): that is the program talking to
+ * its operator and stays on plain `console`. Everything here is operational logging to stderr.
+ */
+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. */
+export function createLogger(opts) {
+    const sink = opts.sink ?? ((line) => console.error(line));
+    const make = (level) => (msg) => {
+        if (ORDER[level] >= ORDER[opts.level])
+            sink(format(level, msg));
+    };
+    return { debug: make("debug"), info: make("info"), warn: make("warn"), error: make("error") };
+}
+/**
+ * `FASTAGENT_LOG_LEVEL` parsed to three states: a valid value locks the level (overrides posture); a
+ * present-but-invalid value warns and is treated as absent, so a typo (meant to make logs louder) can
+ * never silently pin the level to info nor kill the posture default; absent returns undefined. The
+ * warning is raw — the singleton below is not built yet — but reuses `format` for the same shape.
+ */
+function parseEnvOverride() {
+    const raw = process.env.FASTAGENT_LOG_LEVEL;
+    if (raw === undefined)
+        return undefined;
+    const value = raw.toLowerCase();
+    if (isLevel(value))
+        return value;
+    console.error(format("warn", `[fastagent] unknown FASTAGENT_LOG_LEVEL "${raw}"; using the posture default`));
+    return undefined;
+}
+const override = parseEnvOverride();
+let currentLevel = override ?? "info";
+/** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` override, if present, wins and is not changed. */
+export function setLogLevel(level) {
+    if (override === undefined)
+        currentLevel = level;
+}
+const emit = (level) => (msg) => {
+    if (ORDER[level] >= ORDER[currentLevel])
+        console.error(format(level, msg));
+};
+/** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
+export const log = { debug: emit("debug"), info: emit("info"), warn: emit("warn"), error: emit("error") };

package/dist/observe.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The turn trace: wrap an Agent to tee each turn's loop — prompt, reasoning, tool calls (name + args)
+ * with results, reply, terminal — to the log at DEBUG level. Pass-through: events are forwarded
+ * untouched; this only adds a readable line per step. Engine-neutral (the contract only).
+ *
+ * It is wired in BOTH `dev` and `start`; the level decides visibility. dev runs at debug, so the trace
+ * (including end-user content — prompt, tool args/results, reply) shows; start runs at info, so the
+ * trace is gated out entirely, keeping that content and its volume out of production logs. That gating
+ * is why the trace is debug-level rather than a switch soldered to the command path.
+ */
+import type { Agent } from "./agent.ts";
+export declare function logAgentLoop(agent: Agent, sink?: (line: string) => void): Agent;

package/dist/observe.js

@@ -0,0 +1,44 @@
+import { log } from "./log.js";
+const PREVIEW = 200;
+/** One line, whitespace-collapsed, truncated — a log stays scannable. */
+function oneLine(s) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > PREVIEW ? `${t.slice(0, PREVIEW - 1)}…` : t;
+}
+const preview = (v) => oneLine(typeof v === "string" ? v : JSON.stringify(v));
+export function logAgentLoop(agent, sink = (line) => log.debug(line)) {
+    return {
+        async *invoke(scope, prompt) {
+            const s = scope.session;
+            sink(`[agent] ▶ turn session=${s} ← ${oneLine(prompt.text)}`);
+            const toolName = new Map(); // tool_ended carries no name — remember it from tool_started
+            let thinking = "";
+            let reply = "";
+            for await (const e of agent.invoke(scope, prompt)) {
+                if (e.type === "text") {
+                    reply += e.delta;
+                }
+                else if (e.type === "thinking") {
+                    thinking += e.delta;
+                }
+                else if (e.type === "tool_started") {
+                    toolName.set(e.id, e.name);
+                    sink(`[agent]   tool → ${e.name}(${preview(e.args)})`);
+                }
+                else if (e.type === "tool_ended") {
+                    sink(`[agent]   tool ${e.isError ? "✗" : "✓"} ${toolName.get(e.id) ?? e.id} → ${preview(e.content)}`);
+                }
+                else if (e.type === "completed") {
+                    if (thinking.trim() !== "")
+                        sink(`[agent]   thinking: ${oneLine(thinking)}`);
+                    sink(`[agent]   reply: ${oneLine(reply) || "(empty)"}`);
+                    sink(`[agent] ■ completed session=${s}`);
+                }
+                else if (e.type === "failed") {
+                    sink(`[agent] ■ failed session=${s}: ${e.details} (retryable=${e.retryable})`);
+                }
+                yield e;
+            }
+        },
+    };
+}

package/dist/pi.d.ts

@@ -0,0 +1,16 @@
+export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
+export { defineTool, loadTools, type DefineToolOptions, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export { z } from "zod";
+export type { AgentTool, ExecutionEnv, Session, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";
+export { createPiAgentFromWorkspace, type CreatePiAgentFromWorkspaceOptions, } from "./engines/pi/workspace.ts";
+export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
+export { defineConfig, listModels, resolveModel, type FastagentConfig } from "./engines/pi/config.ts";
+export { inProcessLease, type Lease, type Release } from "./engines/pi/invoke.ts";
+export type { AnyModel } from "./engines/pi/harness.ts";
+export { inMemorySessionStore, jsonlSessionStore, type PiSessionStore } from "./engines/pi/sessions.ts";
+export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
+export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
+export type { Models } from "@earendil-works/pi-ai";
+export { createProvider, type Provider, type ProviderAuth } from "@earendil-works/pi-ai";
+export type { Model } from "@earendil-works/pi-ai";

package/dist/pi.js

@@ -0,0 +1,12 @@
+// The pi reference implementation: assembly, workspace discovery, tools, config, models, auth, and state ports.
+export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
+export { defineTool, loadTools, } from "./engines/pi/tool.js";
+export { z } from "zod";
+export { loadChannels } from "./engines/pi/channel.js";
+export { createPiAgentFromWorkspace, } from "./engines/pi/workspace.js";
+export { defineConfig, listModels, resolveModel } from "./engines/pi/config.js";
+export { inProcessLease } from "./engines/pi/invoke.js";
+export { inMemorySessionStore, jsonlSessionStore } from "./engines/pi/sessions.js";
+export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
+export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
+export { createProvider } from "@earendil-works/pi-ai";

package/dist/proxy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Route fetch through HTTPS_PROXY and keep fetch + dispatcher on the SAME undici implementation. Any
+ * process that hits a provider or a channel API needs this UNDER NODE: Node's fetch does not honor
+ * HTTPS_PROXY by itself (so login's OAuth token exchange, model calls, and a webhook setWebhook would go
+ * direct, bypassing a region proxy), and Node 26's bundled fetch skips gzip decompression without
+ * install() (empty stopReason:"stop"). A process-global side effect — call it once at a command/entry
+ * start. No-op under Bun, whose native fetch already does both (and lacks the undici entry points).
+ */
+export declare function installProxyFetch(): void;

package/dist/proxy.js

@@ -0,0 +1,23 @@
+// Namespace import (not `import { install }`): Bun's `undici` is a native shim that omits `install`, and
+// a STATIC NAMED import of a missing export fails at link time — crashing `fastagent start` under Bun
+// before any code runs. A namespace import binds whatever exports exist; the Bun guard below then never
+// touches the Node-only members.
+import * as undici from "undici";
+/** The Bun runtime (`process.versions.bun` is set only there). Bun's native fetch already honors the
+ *  proxy env vars and decompresses gzip, and its `undici` shim has no `install()` — so the Node-only
+ *  undici wiring below is both unnecessary and unavailable there. */
+const isBun = typeof process.versions.bun === "string";
+/**
+ * Route fetch through HTTPS_PROXY and keep fetch + dispatcher on the SAME undici implementation. Any
+ * process that hits a provider or a channel API needs this UNDER NODE: Node's fetch does not honor
+ * HTTPS_PROXY by itself (so login's OAuth token exchange, model calls, and a webhook setWebhook would go
+ * direct, bypassing a region proxy), and Node 26's bundled fetch skips gzip decompression without
+ * install() (empty stopReason:"stop"). A process-global side effect — call it once at a command/entry
+ * start. No-op under Bun, whose native fetch already does both (and lacks the undici entry points).
+ */
+export function installProxyFetch() {
+    if (isBun)
+        return;
+    undici.setGlobalDispatcher(new undici.EnvHttpProxyAgent());
+    undici.install();
+}

package/dist/runtime.d.ts

@@ -0,0 +1,26 @@
+export interface WorkspaceRuntime {
+    /** The JS runtime the workspace targets — drives the generated Dockerfile base + install/run commands
+     *  and the package-manager hints in `init`/`add`. */
+    runtime: "node" | "bun";
+    /** For `runtime: "bun"`, the version from package.json's `packageManager: "bun@x"` (undefined if a bun
+     *  lockfile made it bun but no version is pinned). */
+    bunVersion?: string;
+    /** Whether the runtime's lockfile is present (package-lock.json for node, bun.lock/bun.lockb for bun). */
+    hasLockfile: boolean;
+}
+/**
+ * Detect which JS runtime a workspace targets: `bun` when package.json's `packageManager` is `bun@…` OR a
+ * bun lockfile (bun.lock/bun.lockb) is present, else `node`. `pkg` is the already-parsed package.json (or
+ * `{}` when there is none / it is malformed). One source for the deploy Dockerfile and the CLI hints, so
+ * they agree on what the workspace is.
+ */
+export declare function detectRuntime(dir: string, pkg: {
+    packageManager?: unknown;
+}): WorkspaceRuntime;
+/** Parse `<dir>/package.json`, or `{}` when absent/malformed (a real build surfaces the actual error).
+ *  The already-parsed input to {@link detectRuntime} and the deploy dep/lockfile checks. */
+export declare function readPackageJson(dir: string): Promise<{
+    packageManager?: unknown;
+    dependencies?: Record<string, unknown>;
+    devDependencies?: Record<string, unknown>;
+}>;

package/dist/runtime.js

@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Detect which JS runtime a workspace targets: `bun` when package.json's `packageManager` is `bun@…` OR a
+ * bun lockfile (bun.lock/bun.lockb) is present, else `node`. `pkg` is the already-parsed package.json (or
+ * `{}` when there is none / it is malformed). One source for the deploy Dockerfile and the CLI hints, so
+ * they agree on what the workspace is.
+ */
+export function detectRuntime(dir, pkg) {
+    const pm = typeof pkg.packageManager === "string" ? pkg.packageManager : "";
+    const bunLock = existsSync(join(dir, "bun.lock")) || existsSync(join(dir, "bun.lockb"));
+    if (pm.startsWith("bun@") || bunLock) {
+        // corepack pins as `bun@1.3.13+sha256.<hash>`; the version (a Docker tag for oven/bun) is the part
+        // BEFORE `+` — keeping the hash would build an invalid `FROM oven/bun:1.3.13+sha256…` tag.
+        return { runtime: "bun", bunVersion: pm.match(/^bun@([^+]+)/)?.[1], hasLockfile: bunLock };
+    }
+    return { runtime: "node", hasLockfile: existsSync(join(dir, "package-lock.json")) };
+}
+/** Parse `<dir>/package.json`, or `{}` when absent/malformed (a real build surfaces the actual error).
+ *  The already-parsed input to {@link detectRuntime} and the deploy dep/lockfile checks. */
+export async function readPackageJson(dir) {
+    try {
+        return JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/scaffold/add-channel.d.ts

@@ -0,0 +1,46 @@
+export type ChannelKind = "github" | "telegram";
+/** An env var a scaffolded channel reads. `generate` = a random-string secret the CLI can pre-fill. */
+export interface ChannelEnv {
+    name: string;
+    hint: string;
+    generate?: boolean;
+}
+/** The channel kinds `fastagent add <kind>` can scaffold. */
+export declare const CHANNEL_KINDS: ChannelKind[];
+/** The env vars + next-step lines a scaffolded channel needs (for the CLI to print). */
+export declare function channelSetup(kind: ChannelKind): {
+    env: ChannelEnv[];
+    steps: string[];
+};
+/**
+ * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who
+ * copies it to `.env` finds the vars already there. No-op when there is no `.env.example` or the block
+ * is already present. Placeholders only — no real secret lands in the committable template.
+ */
+export declare function appendChannelEnv(dir: string, kind: ChannelKind): Promise<boolean>;
+export interface DotEnvWriteResult {
+    /** Generated secret vars written as active `KEY=value` lines. */
+    written: string[];
+    /** Vars already present with a non-empty active value; left untouched and omitted from next steps. */
+    alreadySet: string[];
+}
+/**
+ * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
+ * verified that `.env` is gitignored. Existing non-empty values are kept. Manual values (e.g.
+ * TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is ready to
+ * edit while no fake secret is committed to the user's mental model.
+ */
+export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>): Promise<DotEnvWriteResult>;
+/** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
+export declare function channelExists(dir: string, kind: ChannelKind): Promise<boolean>;
+/**
+ * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
+ * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
+ */
+export declare function scaffoldChannel(dir: string, kind: ChannelKind): Promise<string>;
+/**
+ * Verify the workspace is ready to host a channel: an ESM package.json that declares
+ * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that
+ * is `init`'s job.
+ */
+export declare function assertChannelReady(dir: string): Promise<void>;

package/dist/scaffold/add-channel.js

@@ -0,0 +1,227 @@
+/**
+ * `fastagent add <channel>`: drop a `channels/<kind>.ts` adapter-glue file (+ any companion tool, +
+ * `.env.example` vars) into an existing workspace. `add` checks and guides; it never bootstraps a
+ * workspace (that is `init`'s job). Each channel's template files live in its own bundle at
+ * src/channels/<kind>/scaffold/, read here at scaffold time.
+ */
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectRuntime } from "../runtime.js";
+import { assertInsideWorkspace } from "../workspace.js";
+import { channelBundleFiles, channelTemplate } from "./templates.js";
+import { exists } from "./init.js";
+import { parseEnvContent } from "../env.js";
+const CHANNEL_SCAFFOLDS = {
+    github: {
+        env: [
+            {
+                name: "GITHUB_WEBHOOK_SECRET",
+                hint: "any random string; set the same value in the GitHub webhook",
+                generate: true,
+            },
+        ],
+        // `{channel}` / `{tools}` are path placeholders the CLI resolves to the real workspace-relative
+        // location (agentDir-aware) — the CLI holds no channel-private filenames.
+        steps: [
+            "edit {channel} — map events to intents in on()",
+            "add the webhook in your repo (Settings → Webhooks): Payload URL = <public-url>/webhook, content type application/json",
+        ],
+    },
+    telegram: {
+        env: [
+            { name: "TELEGRAM_BOT_TOKEN", hint: "from @BotFather → /newbot" },
+            { name: "TELEGRAM_SECRET_TOKEN", hint: "any random string; verifies inbound updates", generate: true },
+        ],
+        steps: [
+            "edit {channel} — customise routing with route() (optional; the defaults already work)",
+            "the agent can send messages or files back by calling the scaffolded {tools}/telegram-send.ts tool",
+        ],
+    },
+};
+/** The channel kinds `fastagent add <kind>` can scaffold. */
+export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
+/** The env vars + next-step lines a scaffolded channel needs (for the CLI to print). */
+export function channelSetup(kind) {
+    const { env, steps } = CHANNEL_SCAFFOLDS[kind];
+    return { env, steps };
+}
+/**
+ * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who
+ * copies it to `.env` finds the vars already there. No-op when there is no `.env.example` or the block
+ * is already present. Placeholders only — no real secret lands in the committable template.
+ */
+export async function appendChannelEnv(dir, kind) {
+    const file = join(dir, ".env.example");
+    let current;
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return false;
+        throw e;
+    }
+    const marker = `# --- ${kind} channel ---`;
+    if (current.includes(marker))
+        return false;
+    // Hint on its OWN line above the placeholder (like the base env.example template) — never inline
+    // after `=`: loadEnvFile does not strip trailing comments, so an uncommented `KEY=   # hint` (or a
+    // value pasted before the `#`) would carry the hint text into the parsed value.
+    const block = `\n${marker}\n${CHANNEL_SCAFFOLDS[kind].env.map((e) => `# ${e.hint}\n# ${e.name}=`).join("\n")}\n`;
+    await appendFile(file, block);
+    return true;
+}
+/** Whether `.env` content carries a non-empty ACTIVE value for `name` — decided by THE .env parser
+ *  ({@link parseEnvContent}), not a re-implementation, so this check can never disagree with what
+ *  `loadEnvFile` will actually read (a missed match here would append a second assignment that
+ *  last-wins over the user's working secret). */
+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));
+}
+/**
+ * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
+ * verified that `.env` is gitignored. Existing non-empty values are kept. Manual values (e.g.
+ * TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is ready to
+ * edit while no fake secret is committed to the user's mental model.
+ */
+export async function appendChannelDotEnv(dir, kind, generated) {
+    const file = join(dir, ".env");
+    let current = "";
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const alreadySet = CHANNEL_SCAFFOLDS[kind].env.filter((e) => hasActiveEnvValue(current, e.name)).map((e) => e.name);
+    const lines = [];
+    const written = [];
+    const contentLines = current.split("\n");
+    let replacedInPlace = false;
+    for (const e of CHANNEL_SCAFFOLDS[kind].env) {
+        if (alreadySet.includes(e.name))
+            continue;
+        const value = generated[e.name];
+        if (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: a new line written anywhere else either loses
+            // to it or wins by position under last-wins — both silently. Replace the LAST occurrence (the one
+            // the parser would honor). Line-level match uses THE parser, never a hand regex.
+            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}=${value}`;
+                replacedInPlace = true;
+            }
+            else {
+                lines.push(`${e.name}=${value}`);
+            }
+            written.push(e.name);
+        }
+        else if (!mentionsEnvName(current, e.name)) {
+            // Hint above, never inline after `=` — see appendChannelEnv (this IS the file loadEnvFile reads).
+            lines.push(`# ${e.hint}`, `# ${e.name}=`);
+        }
+    }
+    if (replacedInPlace) {
+        current = contentLines.join("\n");
+        await writeFile(file, current);
+    }
+    if (lines.length > 0) {
+        const marker = `# --- ${kind} channel ---`;
+        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")}`));
+        }
+        else {
+            const prefix = current === "" ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+            await appendFile(file, `${prefix}${marker}\n${lines.join("\n")}\n`);
+        }
+    }
+    return { written, alreadySet };
+}
+/** The path `add <kind>` scaffolds to. */
+function channelPath(dir, kind) {
+    return join(dir, "channels", `${kind}.ts`);
+}
+/** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
+export async function channelExists(dir, kind) {
+    return exists(channelPath(dir, kind));
+}
+/**
+ * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
+ * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
+ */
+export async function scaffoldChannel(dir, kind) {
+    const channelsDir = join(dir, "channels");
+    // Don't write through a channels/ symlink that escapes the workspace; an in-workspace one is fine.
+    await assertInsideWorkspace(dir, "channels");
+    const file = channelPath(dir, kind);
+    if (await exists(file)) {
+        throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
+    }
+    await mkdir(channelsDir, { recursive: true });
+    // `channel.ts` is THE adapter (→ channels/<kind>.ts); any other .ts in the bundle is a companion tool
+    // (→ tools/<name>, never clobbering an authored one).
+    for (const name of channelBundleFiles(kind)) {
+        const content = channelTemplate(kind, name);
+        if (name === "channel.ts") {
+            await writeFile(file, content, { flag: "wx" });
+            continue;
+        }
+        const toolFile = join(dir, "tools", name);
+        if (!(await exists(toolFile))) {
+            await mkdir(join(dir, "tools"), { recursive: true });
+            await writeFile(toolFile, content, { flag: "wx" });
+        }
+    }
+    return file;
+}
+/**
+ * Verify the workspace is ready to host a channel: an ESM package.json that declares
+ * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that
+ * is `init`'s job.
+ */
+export async function assertChannelReady(dir) {
+    const pkgPath = join(dir, "package.json");
+    let raw;
+    try {
+        raw = await readFile(pkgPath, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            // `dir` is where the kit lives (agentDir when set) — "run init" is only the right advice when no
+            // workspace exists yet; a kit missing its manifest (e.g. a --minimal init) needs the manifest, not init.
+            throw new Error(`${dir}: no package.json — a channel adapter is code and needs the kit's own manifest. ` +
+                `Run \`fastagent init\` for a fresh workspace, or add a package.json with @fastagent-sh/fastagent there ` +
+                `(a --minimal init has none)`);
+        }
+        throw e;
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${pkgPath}: invalid JSON`);
+    }
+    if (pkg.type !== "module") {
+        throw new Error(`${pkgPath}: fastagent channels are ESM — set "type": "module"`);
+    }
+    if (typeof pkg.dependencies?.["@fastagent-sh/fastagent"] !== "string") {
+        const add = detectRuntime(dir, pkg).runtime === "bun"
+            ? "bun add @fastagent-sh/fastagent"
+            : "npm install @fastagent-sh/fastagent";
+        throw new Error(`${pkgPath}: @fastagent-sh/fastagent is not a dependency — run \`${add}\` (the channel file imports it)`);
+    }
+}

package/dist/scaffold/init.d.ts

@@ -0,0 +1,54 @@
+export interface ScaffoldOptions {
+    /** Scaffold the markdown-only unit (no package.json, no tool, no install) instead of a complete agent. */
+    minimal?: boolean;
+    /**
+     * Place the agent kit (persona.md/skills/tools/package.json) in this subdirectory (e.g. "./agent")
+     * instead of flat in `dir`; the config is written at the root with `agentDir` pointing there.
+     * Undefined = flat. The CLI decides (jurisdiction detection + flags); this stays mechanical.
+     */
+    agentDir?: string;
+}
+export interface ScaffoldResult {
+    dir: string;
+    /** Whether a complete (code-tool) agent was scaffolded (false for --minimal). */
+    complete: boolean;
+    /** The kit subdirectory in effect (relative, e.g. "./agent"); undefined = flat. */
+    agentDir?: string;
+    /** Files written by this run (relative paths). */
+    created: string[];
+    /** Files that already existed and were kept untouched (e.g. a pre-existing .gitignore). */
+    skipped: string[];
+    /** Kept ignore files appended with missing fastagent excludes (root .gitignore: .env/.fastagent, plus
+     *  node_modules/ in the flat layout; kit .gitignore in the agentDir layout: node_modules/). */
+    patched: string[];
+    /** True if the target already had content before this run (init into an existing/non-empty dir). */
+    intoNonEmpty: boolean;
+    /** Non-fatal advisories the caller MUST surface. */
+    warnings: string[];
+}
+/**
+ * Jurisdiction signals: evidence that an existing system already claims this tree, so a flat agent kit
+ * would put each side's files under the other's jurisdiction (host tsc sweeps agent .ts; fastagent
+ * scans host tools/). Three classes, derived from the actual failure modes — a toolchain config, a
+ * deploy manifest, or fastagent's convention names already occupied. Any hit → the kit defaults into
+ * `./agent`. Deliberately NOT signals: "dir is non-empty", "has package.json", "has src/" — markdown
+ * and loose scripts are claimed by nobody, and "a directory is an agent" stays the default. Known
+ * tradeoff, decided for visibility: a HAND-BUILT agent dir (skills//tools/ authored for the agent, no
+ * config yet) also hits the occupation signal and defaults to ./agent — wrong for that case, but the
+ * reason is printed and `--flat` overrides; the reverse default would silently mis-scan a host's dirs.
+ */
+export declare function detectHostSignals(dir: string): Promise<string[]>;
+/** The `cd` target to show in `init`'s next-steps: the relative path when the target is inside `cwd`,
+ *  the absolute path when it climbs out (a `../../..` is noise), or undefined when already in `cwd`. */
+export declare function nextStepCd(cwd: string, dir: string): string | undefined;
+/** Does a path exist? (async; shared with the sibling scaffold modules). */
+export declare function exists(p: string): Promise<boolean>;
+/**
+ * Scaffold a runnable workspace into {@link dir} (created if missing). Default is a complete agent
+ * (persona.md + the writing-great-skills skill + a code tool + package.json); `--minimal` drops the
+ * code tool and package.json. The kit goes flat into `dir`, or into {@link ScaffoldOptions.agentDir}
+ * (config at the root pointing there). Refuses only an existing fastagent.config.* (the ownership
+ * marker — already a workspace); every other pre-existing file (AGENTS.md, .gitignore, package.json)
+ * is kept, never overwritten — an existing AGENTS.md is the project's context, adopted as-is.
+ */
+export declare function scaffoldWorkspace(dir: string, options?: ScaffoldOptions): Promise<ScaffoldResult>;