@pmndrs/pine 0.0.0-stage → 0.1.0

package/src/sources/telegram.js

@@ -0,0 +1,269 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Type } from "typebox";
+import { errText, sleep, truncate } from "../util.js";
+/**
+ * A Telegram bot: the owner writes to it from wherever they are, and the agent answers there.
+ *
+ * options: { token, allow?, approvals?, apiBase? }
+ *   token      the bot's token from @BotFather
+ *   allow      Telegram user ids that may talk to it. Without it the bot is paired: it sends a
+ *              code to the account that writes to it, and the owner types that code into pine
+ *   approvals  also send approval requests to that chat, with buttons (default true)
+ *   apiBase    a Bot API server of your own instead of api.telegram.org
+ *
+ * event "message": { text, name, username, chatId, messageId, images? }
+ * It can send: { text, chatId? } goes to the owner's chat.
+ *
+ * Messages are fetched by long polling: one request that Telegram answers the moment something
+ * arrives. Nothing listens on a port, so it works behind any router. Only accounts on `allow`, or
+ * the one that was paired, are heard. What anyone else writes reaches no agent; once an account
+ * is paired they get no answer at all, and nothing is ever sent to them.
+ */
+export const type = {
+    summary: "a Telegram bot: your owner writes to it from anywhere and you answer there; you can also message them through it. Needs the bot's token from @BotFather",
+    talks: true,
+    sends: 'a Telegram message to your owner: {"text": "..."}',
+    options: Type.Object({
+        token: Type.String({ description: "the bot's token, which @BotFather gives when a bot is made with /newbot (123456789:AA...)", secret: true }),
+        allow: Type.Optional(Type.Array(Type.Number(), { description: "Telegram user ids that may talk to the bot. Leave out unless your owner gave you their id: the bot is then paired, which means it sends a code to the account that writes to it and your owner types that code into pine" })),
+        approvals: Type.Optional(Type.Boolean({ description: "also send approval requests to the owner there, with buttons to answer them. Default true" })),
+        apiBase: Type.Optional(Type.String({ description: "address of a Bot API server of your own, instead of https://api.telegram.org" })),
+    }, { additionalProperties: false }),
+    plan(o) {
+        // Without a token yet (the owner is about to be asked for it) there is nothing to check.
+        if (o.token !== undefined && !/^\d{5,}:[A-Za-z0-9_-]{20,}$/.test(String(o.token)))
+            throw new Error("that is not a bot token. @BotFather gives one that looks like 123456789:AAH... when a bot is created with /newbot");
+        if (o.apiBase !== undefined) {
+            let url;
+            try {
+                url = new URL(o.apiBase);
+            }
+            catch {
+                throw new Error(`"${o.apiBase}" is not an address`);
+            }
+            if (url.protocol !== "https:" && !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))
+                throw new Error("a Bot API server of your own must be reached over https, or run on this machine");
+        }
+        const ids = o.allow ?? [];
+        return {
+            options: o,
+            opens: true,
+            owner: true,
+            does: [
+                "connect to Telegram as your bot and wait for messages",
+                ids.length ? `listen only to the Telegram user${ids.length === 1 ? "" : "s"} ${ids.join(", ")}` : "listen to nobody until you have paired your own account: the bot sends a code to the account that writes to it, and you type that code into pine",
+                "take what that account writes as coming from you, with everything your agents may do for you",
+                "send answers back to that chat, and nowhere else",
+                ...(o.approvals === false ? [] : ["send approval requests there too, with buttons"]),
+            ],
+            tell: ids.length ? "Your owner can write to the bot now." : "Tell your owner to open the bot in Telegram and write anything to it. The bot answers with a six-digit code, and pine asks for that code here. Once they have typed it, that account is the only one the bot listens to.",
+        };
+    },
+};
+const MAX_PHOTO = 10 * 1024 * 1024;
+export default async function telegram(source) {
+    const o = source.options;
+    const token = String(o.token ?? "");
+    if (!token)
+        throw new Error("the bot token is missing");
+    source.secret(token);
+    const base = String(o.apiBase ?? "https://api.telegram.org").replace(/\/+$/, "");
+    const stop = new AbortController();
+    source.onStop(() => stop.abort());
+    const api = async (method, body = {}, timeoutMs = 20_000) => {
+        const res = await fetch(`${base}/bot${token}/${method}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.any([stop.signal, AbortSignal.timeout(timeoutMs)]) });
+        const json = await res.json().catch(() => ({}));
+        if (!json.ok)
+            throw new Error(`Telegram refused ${method}: ${json.description ?? res.status}`);
+        return json.result;
+    };
+    // A wrong token is found out here, and shows as the reason the source is not running.
+    const me = await api("getMe");
+    const mediaDir = path.join(source.dataDir, "media");
+    fs.mkdirSync(mediaDir, { recursive: true });
+    source.media(mediaDir);
+    // ---- who is heard ------------------------------------------------------------------------------
+    const fixed = (Array.isArray(o.allow) ? o.allow : []).map(Number).filter(Number.isFinite);
+    const paired = () => source.kv.get("owner");
+    const heard = (userId) => fixed.includes(userId) || paired()?.id === userId;
+    /** The chat everything unasked goes to. A private chat has the id of its user. */
+    const ownerChat = () => fixed[0] ?? paired()?.id;
+    /** Who may talk to the bot, said where the sources are listed. */
+    const say = () => source.status(fixed.length
+        ? `@${me.username} listens only to the Telegram user${fixed.length === 1 ? "" : "s"} ${fixed.join(", ")}`
+        : paired()
+            ? `@${me.username} listens only to ${paired().name || "the paired account"} (Telegram id ${paired().id}), which you confirmed`
+            : `@${me.username} listens to nobody yet: write to it from your Telegram account, then type the code it sends you into pine`);
+    say();
+    const send = async (chatId, text, extra = {}) => {
+        if (!heard(chatId))
+            throw new Error("that chat is not your owner's");
+        const body = text.trim() || "(empty message)";
+        let last;
+        for (let i = 0; i < body.length; i += 4000)
+            last = await api("sendMessage", { chat_id: chatId, text: body.slice(i, i + 4000), ...(i + 4000 >= body.length ? extra : {}) });
+        return last;
+    };
+    // ---- out: answers, and what an agent sends on its own -------------------------------------------
+    source.onSend(async (message) => {
+        const chatId = Number(message.chatId ?? ownerChat());
+        if (!Number.isFinite(chatId))
+            throw new Error("nobody is connected yet: your owner has to write to the bot once, and confirm it in pine");
+        await send(chatId, String(message.text ?? ""));
+        return "sent to your owner on Telegram";
+    });
+    // "typing…" while an agent works on something that will be answered here.
+    const typing = new Map();
+    source.on("agent/+/started", (e) => {
+        const p = e.payload;
+        const chatId = Number(p?.reply?.payload?.chatId);
+        if (p?.reply?.topic !== `out/source/${source.key}` || !heard(chatId))
+            return;
+        const tick = () => void api("sendChatAction", { chat_id: chatId, action: "typing" }).catch(() => { });
+        tick();
+        const h = setInterval(tick, 4500);
+        h.unref?.();
+        typing.set(p.task, h);
+    });
+    source.on(["agent/+/done", "agent/+/failed"], (e) => {
+        const id = e.payload?.task;
+        clearInterval(typing.get(id));
+        typing.delete(id);
+    });
+    source.onStop(() => typing.forEach((h) => clearInterval(h)));
+    // ---- approval requests, to answer from the phone ---------------------------------------------------
+    if (o.approvals !== false) {
+        const asked = new Map();
+        source.on("approval/requested", async (e) => {
+            const r = e.payload;
+            const chat = ownerChat();
+            // A question the owner answers by typing a secret belongs on their own machine, not in a chat.
+            if (chat === undefined || r.inputs?.length)
+                return;
+            const always = r.remember ? [{ text: `Always: ${truncate(String(r.remember), 30)}`, callback_data: `ap:${r.id}:2` }] : [];
+            const msg = await send(chat, `Approval needed\nAgent: ${r.agent}${r.task ? ` (task #${r.task})` : ""}\nAction: ${truncate(String(r.summary), 1200)}\nWhy you are asked: ${r.why}`, { reply_markup: { inline_keyboard: [[{ text: "Allow", callback_data: `ap:${r.id}:1` }, ...always, { text: "Deny", callback_data: `ap:${r.id}:0` }]] } });
+            if (msg?.message_id)
+                asked.set(r.id, msg.message_id);
+        });
+        source.on("approval/decided", async (e) => {
+            const d = e.payload;
+            const messageId = asked.get(d.id);
+            asked.delete(d.id);
+            if (messageId)
+                await api("editMessageReplyMarkup", { chat_id: ownerChat(), message_id: messageId, reply_markup: { inline_keyboard: [[{ text: d.allow ? `Allowed (${d.by})` : `Denied (${d.by})`, callback_data: "noop" }]] } }).catch(() => { });
+        });
+    }
+    // ---- in ----------------------------------------------------------------------------------------
+    const photo = async (sizes) => {
+        const best = sizes.filter((s) => (s.file_size ?? 0) <= MAX_PHOTO).at(-1);
+        if (!best)
+            return undefined;
+        const file = await api("getFile", { file_id: best.file_id });
+        const res = await fetch(`${base}/file/bot${token}/${file.file_path}`, { signal: AbortSignal.timeout(30_000) });
+        if (!res.ok)
+            return undefined;
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > MAX_PHOTO)
+            return undefined;
+        const target = path.join(mediaDir, `${String(best.file_unique_id).replace(/[^A-Za-z0-9_-]/g, "")}.jpg`);
+        fs.writeFileSync(target, buf, { mode: 0o600 });
+        return { path: target, mimeType: "image/jpeg" };
+    };
+    /**
+     * An account nobody knows yet writes to a bot that has no owner. Whoever sits at pine has to
+     * show that this account is theirs: the bot sends the account a code, and pine asks for it.
+     * A press of a key cannot say yes to a stranger, and a stranger does not know what to type.
+     * One question at a time; an account the owner turned down is not asked about again.
+     */
+    let pairing = false;
+    const pair = async (m, userId, name) => {
+        const denied = source.kv.get("denied") ?? [];
+        if (fixed.length || paired() || pairing || denied.includes(userId))
+            return false;
+        pairing = true;
+        try {
+            const code = String(crypto.randomInt(0, 1_000_000)).padStart(6, "0");
+            const shown = `${code.slice(0, 3)} ${code.slice(3)}`;
+            await api("sendMessage", { chat_id: userId, text: `To connect this Telegram account to pine, type this code into the question pine is showing on your computer:\n\n${shown}\n\nIf you did not expect this message, ignore it.` });
+            const who = `${name || "somebody"} (${m.from?.username ? `@${m.from.username}, ` : ""}Telegram id ${userId})`;
+            const answer = await source.approvals.request(`let the Telegram account of ${who} talk to your agents as you through the bot @${me.username}\nIt just wrote: "${truncate(String(m.text ?? m.caption ?? "(a picture)"), 200)}"\nThe bot sent that account a code. If the account is yours, the code is on your phone now.`, "what this account writes will count as your own words, with everything your agents may do for you. Only the code proves that the account is yours; deny it if you did not just write to the bot", [{ name: "code", label: "code: the six digits the bot just sent to that account in Telegram", secret: false }]);
+            if (!answer.allow) {
+                // Turned down by the owner (not merely unanswered): that account is not put to them again.
+                if (answer.by !== "timeout" && answer.by !== "aborted")
+                    source.kv.set("denied", [...denied, userId].slice(-200));
+                return false;
+            }
+            if (String(answer.values?.code ?? "").replace(/\D/g, "") !== code) {
+                await api("sendMessage", { chat_id: userId, text: "That was not the code. Write again to get a new one." }).catch(() => { });
+                return false;
+            }
+            if (!paired())
+                source.kv.set("owner", { id: userId, name: `${name}${m.from?.username ? ` (@${m.from.username})` : ""}` });
+            say();
+            return paired()?.id === userId;
+        }
+        finally {
+            pairing = false;
+        }
+    };
+    const onMessage = async (m) => {
+        const userId = Number(m.from?.id);
+        const chatId = Number(m.chat?.id);
+        const name = [m.from?.first_name, m.from?.last_name].filter(Boolean).join(" ");
+        if (m.chat?.type !== "private")
+            return;
+        // Unknown senders get no answer at all: nothing to probe, nothing to flood the log with.
+        if (!heard(userId) && !(await pair(m, userId, name)))
+            return source.log.debug(`ignored a message from user ${userId}`);
+        const text = String(m.text || m.caption || "").trim();
+        const images = m.photo ? [await photo(m.photo).catch(() => undefined)].filter(Boolean) : [];
+        if (!text && !images.length)
+            return;
+        const verdict = text.match(/^\/(allow|deny)(?:\s+(\w+))?/);
+        if (verdict && o.approvals !== false) {
+            const pending = source.approvals.pending();
+            const id = verdict[2] ?? (pending.length === 1 ? pending[0].id : undefined);
+            const ok = id ? source.approvals.decide(id, verdict[1] === "allow", `telegram:${userId}`) : false;
+            return void send(chatId, ok ? "Noted." : "No such open request.").catch(() => { });
+        }
+        source.emit("message", { text: text || "(a picture)", name, username: m.from?.username, chatId, messageId: m.message_id, images: images.length ? images : undefined }, { reply: { chatId } });
+    };
+    const onCallback = async (c) => {
+        const userId = Number(c.from?.id);
+        const m = String(c.data ?? "").match(/^ap:(\w+):([012])$/);
+        if (!heard(userId) || !m)
+            return void api("answerCallbackQuery", { callback_query_id: c.id }).catch(() => { });
+        const ok = source.approvals.decide(m[1], m[2] !== "0", `telegram:${userId}`, m[2] === "2");
+        await api("answerCallbackQuery", { callback_query_id: c.id, text: ok ? (m[2] === "0" ? "Denied" : m[2] === "2" ? "Allowed for this conversation" : "Allowed") : "Already answered or expired" }).catch(() => { });
+    };
+    const poll = async () => {
+        const pollSec = 25;
+        let offset = source.kv.get("offset") ?? 0;
+        let backoff = 1000;
+        while (!stop.signal.aborted) {
+            try {
+                const updates = await api("getUpdates", { offset, timeout: pollSec, allowed_updates: ["message", "callback_query"] }, (pollSec + 10) * 1000);
+                backoff = 1000;
+                for (const u of updates) {
+                    offset = u.update_id + 1;
+                    source.kv.set("offset", offset);
+                    // Not awaited: a pairing question stays open until the owner answers, and messages keep coming meanwhile.
+                    if (u.message)
+                        void onMessage(u.message).catch((e) => source.log.warn("a message could not be handled", errText(e)));
+                    else if (u.callback_query)
+                        void onCallback(u.callback_query).catch((e) => source.log.warn("a button press could not be handled", errText(e)));
+                }
+            }
+            catch (e) {
+                if (stop.signal.aborted)
+                    break;
+                source.log.warn(`asking Telegram for messages failed, trying again in ${backoff} ms`, errText(e));
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, 60_000);
+            }
+        }
+    };
+    void poll();
+}

package/src/sources/webhook.d.ts

@@ -0,0 +1,4 @@
+import type { SourceType } from "../source-types.ts";
+import { type SourceApi } from "../sources.ts";
+export declare const type: SourceType;
+export default function webhook(source: SourceApi): void;

package/src/sources/webhook.js

@@ -0,0 +1,52 @@
+import crypto from "node:crypto";
+import { timingSafeEqual } from "../security.js";
+import { Type } from "typebox";
+import { refuse } from "../sources.js";
+/**
+ * A web address other services can call: POST http://<pine's control address>/hook/<name>.
+ * For GitHub, Home Assistant, a doorbell, a shortcut on your phone, anything that can send a request.
+ *
+ * options: { secret, open? }
+ *   secret  the caller proves itself with it, either as "Authorization: Bearer <secret>" or by
+ *           signing the body (HMAC SHA-256 in X-Hub-Signature-256 or X-Signature, as GitHub does)
+ *   open    true to accept anyone who can reach the port; only for a port nobody else can reach
+ *
+ * event "received": { body, headers }   body is parsed JSON, or { text } for anything else
+ */
+const KEPT = ["content-type", "user-agent", "x-github-event", "x-github-delivery", "x-event-type", "x-event-key", "x-request-id"];
+export const type = {
+    summary: "a web address other services can call (POST /hook/<name> on pine's control port; /hook/<name>@<agent> for an agent's own). For GitHub, Home Assistant, a doorbell, a shortcut on a phone",
+    options: Type.Object({
+        secret: Type.Optional(Type.String({ description: "what the caller proves itself with. Leave it out and pine makes one", secret: true })),
+        open: Type.Optional(Type.Boolean({ description: "true to accept anyone who can reach the port, without a secret. Only for a port nobody else can reach" })),
+    }, { additionalProperties: false }),
+    plan(o, setup) {
+        if (o.open === true)
+            return { options: { open: true }, does: [`accept web requests at /hook/${setup.key} on pine's control port from ANYONE who can reach it`], opens: true, tell: `Callers use POST /hook/${setup.key} on pine's control address.` };
+        const made = !o.secret;
+        return { options: { secret: o.secret ?? setup.random(24) }, does: [`accept web requests at /hook/${setup.key} on pine's control port from callers that present a secret${made ? " (made now)" : ""}`], opens: true, tell: `Callers use POST /hook/${setup.key} on pine's control address and present the secret, which your owner finds in pine's .env file as ${setup.envName("secret")}.` };
+    },
+};
+export default function webhook(source) {
+    const secret = typeof source.options.secret === "string" ? source.options.secret : "";
+    if (!secret && source.options.open !== true)
+        throw new Error(`needs a "secret" the caller has to present (or "open": true to accept anyone who can reach the port)`);
+    source.secret(secret || undefined);
+    source.http(({ headers, body }) => {
+        if (secret) {
+            const bearer = String(headers.authorization ?? "").replace(/^Bearer /, "");
+            const sig = String(headers["x-hub-signature-256"] ?? headers["x-signature"] ?? "").replace(/^sha256=/, "");
+            const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
+            if (!(bearer && timingSafeEqual(bearer, secret)) && !(sig && timingSafeEqual(sig, expected)))
+                throw refuse(401, "bad signature");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(body.toString("utf8"));
+        }
+        catch {
+            parsed = { text: body.toString("utf8") };
+        }
+        source.emit("received", { body: parsed, headers: Object.fromEntries(KEPT.filter((k) => headers[k] !== undefined).map((k) => [k, String(headers[k])])) });
+    });
+}

package/src/sources.d.ts

@@ -0,0 +1,339 @@
+import { type PineConfig, type SourceConfig, type SubscriptionConfig } from "./config.ts";
+import type { SourcePlan } from "./source-types.ts";
+import type { Router } from "./router.ts";
+import { type Approvals, type Redactor } from "./security.ts";
+import type { Bus, Kv } from "./store.ts";
+import type { PineEvent } from "./types.ts";
+import { type Logger } from "./util.ts";
+/**
+ * Event sources and the subscriptions to them.
+ *
+ * A source is to events what an MCP server is to tools: a named thing in the configuration, global
+ * (pine.json) or one agent's own (agent.json), that can report what happens somewhere else: a file
+ * arrives, a device says something, a web service calls, a clock strikes. Being configured does
+ * nothing. A source starts when the first conversation subscribes to it. A subscription belongs to
+ * one conversation of one agent: each event arrives there as a message and wakes the agent into a
+ * turn, and what it does with it is in its instructions and in the note it left when it subscribed.
+ * Another conversation of the same agent is not subscribed until it subscribes itself. When the
+ * last subscriber leaves, the source stops.
+ *
+ * Events are published as source/<name>/<event> (source/<name>@<agent>/<event> for an agent's own
+ * source), so the event log, routes and the UI see them like any other event.
+ */
+/** What a source module gets. A source is a module whose default export is `(source) => void | Promise<void>`. */
+export interface SourceApi {
+    /** The name it has in the configuration. */
+    name: string;
+    /** What it is called in events and addresses: its name, or name@agent for an agent's own source. */
+    key: string;
+    options: Record<string, any>;
+    /** Folder that relative paths in the options are meant from. */
+    base: string;
+    /** A folder of its own for whatever it has to keep (received files, for example). */
+    dataDir: string;
+    log: Logger;
+    /**
+     * Report that something happened. `event` is a short word such as "added" or "message".
+     * With `reply`, the answer of an agent that is woken by this event comes back to `onSend`, with
+     * the fields given here (a chat to answer in, for example) next to its `text`.
+     */
+    emit(event: string, payload?: Record<string, unknown>, opts?: {
+        persist?: boolean;
+        reply?: Record<string, unknown>;
+    }): PineEvent;
+    /**
+     * For a source that can also send: called with an agent's answer to one of its events, and with
+     * what an agent sends through it on its own. Return a short line on what was done; throw to
+     * refuse. The source decides where things may go: it never sends anywhere it was not set up for.
+     */
+    onSend(handler: (message: Record<string, any>) => void | string | Promise<void | string>): void;
+    /**
+     * Say in one line how things stand, for whoever lists the sources: who it is connected to,
+     * what it is waiting for. Call it again when that changes.
+     */
+    status(line: string): void;
+    /** Look at events of the system (read only): "agent/+/started", "approval/requested", ... */
+    on(pattern: string | string[], handler: (e: PineEvent) => void | Promise<void>): void;
+    /** Approval requests: put a question of its own to the owner, see the open ones, pass on the owner's answer. */
+    approvals: {
+        /** Ask the owner in pine's UI. Resolves with their answer; no answer in time counts as no. */
+        ask(summary: string, why: string): Promise<boolean>;
+        /**
+         * The same, with fields the owner has to fill in (`secret: false` for one that may be shown
+         * while it is typed). `by` says who answered: "timeout" when nobody did.
+         */
+        request(summary: string, why: string, inputs: Array<{
+            name: string;
+            label: string;
+            secret?: boolean;
+        }>): Promise<{
+            allow: boolean;
+            by: string;
+            values?: Record<string, string>;
+        }>;
+        pending(): Array<{
+            id: string;
+            agent: string;
+            tool: string;
+            summary: string;
+            why: string;
+            remember?: string;
+            task: number;
+        }>;
+        decide(id: string, allow: boolean, by: string, always?: boolean): boolean;
+    };
+    /**
+     * Look at something again and again, for what cannot report by itself: a web address, a
+     * command, a mailbox. `look` runs once right away and then every `every` ("30s", "5m"), never
+     * twice at the same time, a little earlier or later each round so that sources do not all fire
+     * together. A look that throws is a failed look: the pause grows with each one in a row, and
+     * whoever lists the sources sees since when it fails and why. One poll per source; it stops
+     * with the source, and `signal` is aborted then.
+     *
+     * A look that finds nothing new does nothing at all: no event, nothing stored, nobody woken.
+     */
+    poll(every: string | number, look: (signal: AbortSignal) => void | Promise<void>): void;
+    /**
+     * Compare a value with what was there at the last look, and remember it. Returns what it was
+     * before when it differs. The first look returns nothing: it is the starting point, not a
+     * change. `slot` keeps several values apart.
+     */
+    changed<T = unknown>(value: T, slot?: string): {
+        previous: T;
+    } | undefined;
+    /**
+     * Run a shell command with the rights of the agent this source belongs to (the main agent for
+     * a source of all agents): in that agent's sandbox, from its workspace, without its owner's
+     * environment. It can do nothing that agent's own shell could not. `output` is what it printed,
+     * errors included. Throws when it cannot be started or takes longer than `timeoutMs` (30 s).
+     */
+    exec(command: string, opts?: {
+        timeoutMs?: number;
+        maxBytes?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        code: number;
+        output: string;
+        truncated: boolean;
+    }>;
+    /** Private storage that survives restarts. */
+    kv: {
+        get<T = unknown>(key: string): T | undefined;
+        set(key: string, value: unknown): void;
+    };
+    /** Keep this value out of events and messages. */
+    secret(value: string | undefined): void;
+    /** Image files in this folder may be shown to a model when an event names them in `images`. */
+    media(dir: string): void;
+    /** Receive POST /hook/<name> on the control API's port. Throw `refuse(status, message)` to turn a request away. */
+    http(handler: (req: {
+        headers: Record<string, string | string[] | undefined>;
+        body: Buffer;
+    }) => void | Promise<void>): void;
+    onStop(fn: () => void | Promise<void>): void;
+}
+export type PineSource = (source: SourceApi) => void | Promise<void>;
+/** An error a webhook handler throws to answer with that HTTP status. */
+export declare function refuse(status: number, message: string): Error;
+export interface SourceInfo {
+    name: string;
+    /** "global", or the agent it belongs to. */
+    scope: string;
+    type: string;
+    description?: string;
+    trust: string;
+    running: boolean;
+    error?: string;
+    /** What the source says about itself while it runs: who it is connected to, what it waits for. */
+    status?: string;
+    /** Who listens: "agent" for its main conversation, "agent/conversation" for another. */
+    subscribers: string[];
+    /** Topic prefix of its events. */
+    topic: string;
+    last?: {
+        ts: number;
+        topic: string;
+    };
+    events: number;
+}
+export declare class SourceHost {
+    private cfg;
+    private bus;
+    private kv;
+    private redactor;
+    private router;
+    private log;
+    private httpEnabled;
+    private running;
+    private starting;
+    private errors;
+    private statuses;
+    private polls;
+    private seen;
+    private off?;
+    private offOut?;
+    private approvals?;
+    private globalRoutes;
+    mediaRoots: string[];
+    /** Every source type there is: pine's own and the ones pine.json registers. `type` is what the module says about itself. */
+    private types;
+    constructor(deps: {
+        cfg: PineConfig;
+        bus: Bus;
+        kv: Kv;
+        redactor: Redactor;
+        router: Router;
+        log: Logger;
+        http: boolean;
+        approvals?: Approvals;
+    });
+    /** Every configured source with its key: global ones by name, an agent's own as name@agent. */
+    private all;
+    private subscribersOf;
+    /** The agents a subscription for everyone reaches: those that can use the source and have no entry of their own for their main conversation. */
+    private reached;
+    /** (Re)build the routes of the subscriptions for everyone. Called whenever any subscription changes, since an agent's own entry takes the place of the general one. */
+    private wireGlobal;
+    /** Read what each source type says about itself. A type whose module does not load is left out, with a line in the log. */
+    private loadTypes;
+    /** The source types an agent can set up by tool call: name, what it is for, and the schema of its options. */
+    typeList(): Array<{
+        name: string;
+        summary: string;
+        options: any;
+    }>;
+    /** Where the source types that were registered while pine ran are kept: in pine's home, which no agent can write. */
+    private typeDir;
+    /** The registered source types that are not pine's own, with what uses each. */
+    ownTypes(): Array<{
+        name: string;
+        file: string;
+        summary?: string;
+        usedBy: string[];
+    }>;
+    /**
+     * Register a new source type from the text of its module. The text is copied into pine's home
+     * first, and it is that copy that is loaded and runs from then on: what an agent wrote and the
+     * owner confirmed cannot be changed afterwards. A module that does not load or does not describe
+     * itself is not registered, and nothing of it stays.
+     *
+     * This runs the module inside the daemon. Whoever calls it has the owner's yes for exactly this text.
+     */
+    addType(name: string, code: string): Promise<{
+        name: string;
+        summary: string;
+        options: string;
+        file: string;
+    }>;
+    /** Take a registered source type out again. Not while a source of that type exists. */
+    removeType(name: string): void;
+    /** The name a secret option of a source gets in .env. */
+    private envName;
+    /**
+     * Work out what setting up a source of a type with these options would mean. The options are
+     * checked against the schema the type exposes, then the type itself says what it would do.
+     * Nothing is written.
+     */
+    propose(agentId: string, name: string, typeName: string, raw: unknown, forAll?: boolean, ask?: string[]): SourcePlan & {
+        secrets: string[];
+        needs: Array<{
+            name: string;
+            label: string;
+        }>;
+    };
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private routeName;
+    /** What a subscription amounts to: this source's events become turns of that agent in that conversation. */
+    private route;
+    private ensure;
+    private launch;
+    /** A source's shell command, run the way the shell of the agent it belongs to would run it. */
+    private exec;
+    private halt;
+    /**
+     * The sources an agent can send through, with what sending does. A global one or its own;
+     * one that was set up for a single conversation only from there.
+     */
+    senders(agentId: string, session?: string): Array<{
+        name: string;
+        type: string;
+        sends: string;
+    }>;
+    /** Send something out through a source, started if it is not running. Throws with the source's own reason if it refuses. */
+    send(agentId: string, name: string, message: Record<string, any>, session?: string): Promise<string>;
+    /** The handler for POST /hook/<key>, if a running source takes web requests under that name. */
+    hookFor(key: string): ((req: {
+        headers: Record<string, string | string[] | undefined>;
+        body: Buffer;
+    }) => void | Promise<void>) | undefined;
+    /** What a running source says about itself; for one that polls, with when it last looked or since when that fails. */
+    private statusOf;
+    list(): SourceInfo[];
+    /**
+     * The sources an agent can subscribe to, as seen from one of its conversations, with everything
+     * that would wake it: `local` this conversation, `agent` its main conversation, `global` a
+     * subscription for all agents, `elsewhere` its other conversations.
+     */
+    available(agentId: string, session?: string): Array<{
+        name: string;
+        type: string;
+        description?: string;
+        local?: SubscriptionConfig;
+        agent?: SubscriptionConfig;
+        global?: SubscriptionConfig;
+        elsewhere: string[];
+    }>;
+    /**
+     * Add a source to the configuration while the daemon runs: to one agent's agent.json, or to
+     * pine.json for everyone. `entry` is what goes into the file. The file is written first and then
+     * read back through the normal loader, so a new source is checked exactly like one that was
+     * there at start; if it does not pass, the file is put back as it was.
+     * `read` also lets that agent read the folder (for a folder source outside its workspace).
+     */
+    add(agentId: string | undefined, name: string, entry: Record<string, unknown>, read?: string, secrets?: string[]): SourceConfig;
+    /**
+     * Take a source out of the configuration while the daemon runs: it stops, whoever was subscribed
+     * to it is unsubscribed, and its entry is deleted. For a watched folder outside the agent's
+     * workspace, the read access that came with it goes too, unless another source still needs it.
+     */
+    remove(agentId: string | undefined, name: string): Promise<{
+        removed: boolean;
+        unsubscribed: string[];
+    }>;
+    /** The sources that were set up for one conversation of an agent. */
+    boundTo(agentId: string, session: string): string[];
+    /** Agents were added or removed: who a subscription for everyone reaches has changed. */
+    agentsChanged(): void;
+    /** The keys of a subscription that are written to a file. */
+    private clean;
+    private same;
+    /**
+     * Subscribe one conversation of an agent to a source and keep that in its agent.json, so it
+     * holds across restarts. `raw` is what goes into the file: session (default "main", which is the
+     * agent as such), note, when, debounce, throttle, separate, prompt. Subscribing the same
+     * conversation again replaces its entry.
+     */
+    subscribe(agentId: string, name: string, raw?: Record<string, unknown>): Promise<SourceInfo & {
+        session: string;
+    }>;
+    /** Subscribe every agent that can use a source of pine.json: each is woken in its main conversation. Kept in pine.json. */
+    subscribeAll(name: string, raw?: Record<string, unknown>): Promise<SourceInfo & {
+        agents: string[];
+    }>;
+    private started;
+    /** End the subscription of one conversation, or with no `session` of all of that agent's conversations. Returns the conversations that were subscribed. */
+    unsubscribe(agentId: string, name: string, session?: string): Promise<string[]>;
+    unsubscribeAll(name: string): Promise<boolean>;
+    /**
+     * A conversation was closed or reset: what it was subscribed to on its own goes with it. An
+     * agent's main conversation is the agent as such and keeps its subscriptions.
+     */
+    closeSession(agentId: string, session: string): Promise<string[]>;
+    /** A conversation got another name: what it was subscribed to on its own follows it. */
+    renameSession(agentId: string, from: string, to: string): Promise<void>;
+    /** Stop a source that nobody listens to any more. */
+    private settle;
+}
+/** A type's options in one line, for a tool description or an error: name, whether it is needed, what it is. */
+export declare function describeOptions(schema: any): string;