@pmndrs/pine 0.0.0-stage → 0.1.0

package/src/config.js

@@ -0,0 +1,514 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseEnv } from "node:util";
+import { expandHome, parseDuration, resolvePath } from "./util.js";
+export const SOURCE_TYPES = ["folder", "mqtt", "webhook", "ftp", "telegram", "http", "command"];
+export const MODES = ["manual", "auto", "bypass"];
+export class ConfigError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Invalid pine configuration:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+        this.problems = problems;
+    }
+}
+/** The pine checkout: bundled MCP servers and source types live here. */
+export const PINE_ROOT = path.resolve(import.meta.dirname, "..");
+/**
+ * How pine's own module files end: ".ts" in a checkout, where Node runs the sources as they are,
+ * ".js" in the published package, which holds them compiled (Node does not run TypeScript from
+ * inside node_modules). Used wherever pine names one of its own files at run time.
+ */
+export const EXT = import.meta.filename.endsWith(".ts") ? ".ts" : ".js";
+export const defaultHome = () => path.resolve(expandHome(process.env.PINE_HOME ?? "~/.pine"));
+const readJson = (file, problems) => {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        problems.push(`${file}: ${e.message}`);
+        return {};
+    }
+};
+/** Replace ${VAR} and ${VAR:-fallback} in every string of a JSON value. */
+function interpolate(value, where, problems, env) {
+    if (typeof value === "string") {
+        return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, fallback) => {
+            const v = env[name] ?? fallback;
+            if (v === undefined)
+                problems.push(`${where}: environment variable ${name} is not set`);
+            return v ?? "";
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v, i) => interpolate(v, `${where}[${i}]`, problems, env));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolate(v, `${where}.${k}`, problems, env)]));
+    return value;
+}
+/**
+ * pine had plugins once: modules listed under "plugins". What they did is done by event sources
+ * now, which agents set up themselves. An empty list in an older file is ignored; one that still
+ * names something is a problem to fix, with a pointer to what took its place.
+ */
+const noPlugins = (list, where, problems) => {
+    if (Array.isArray(list) && list.length)
+        problems.push(`${where}: plugins are gone. Telegram, MQTT and watched folders are event sources now, which an agent sets up when you ask it to ("watch telegram", "watch ~/Scans"); see docs/references/sources.md. Take the "plugins" entry out`);
+};
+const strings = (v, fallback) => (Array.isArray(v) ? v.map(String) : fallback);
+const paths = (v, base) => strings(v, []).map((p) => resolvePath(p, base));
+function loadAgent(id, dir, raw, cfg, problems) {
+    const where = `agents/${id}/agent.json`;
+    noPlugins(raw.plugins, `${where}: plugins`, problems);
+    const workspace = raw.workspace ? resolvePath(raw.workspace, dir) : path.join(dir, "workspace");
+    if (!raw.workspace)
+        fs.mkdirSync(workspace, { recursive: true });
+    else if (!fs.existsSync(workspace))
+        problems.push(`${where}: workspace ${workspace} does not exist`);
+    const sub = raw.subagents === false ? { enabled: false } : raw.subagents === true || raw.subagents === undefined ? {} : raw.subagents;
+    const state = raw.state ?? {};
+    return {
+        id,
+        dir,
+        description: raw.description ?? "",
+        workspace,
+        model: raw.model,
+        thinking: raw.thinking ?? cfg.defaults.thinking,
+        tools: Array.isArray(raw.tools) ? raw.tools.map(String) : undefined,
+        mcp: raw.mcp ?? {},
+        globalMcp: raw.globalMcp ?? true,
+        sources: loadSources(raw.sources, dir, `${where}: sources`, problems, Object.keys(cfg.sourceTypes)),
+        subscribe: loadSubscriptions(raw.subscribe, `${where}: subscribe`, problems),
+        schedules: loadSchedules(raw.schedules, problems, where, id),
+        extensions: paths(raw.extensions, dir),
+        skills: paths(raw.skills, dir),
+        context: paths(raw.context, dir),
+        delegates: strings(raw.delegates, id === cfg.main ? ["*"] : []),
+        subagents: { enabled: sub.enabled ?? true, maxParallel: sub.maxParallel ?? 4, tools: sub.tools, mcp: sub.mcp ?? true },
+        publish: strings(raw.publish, []),
+        state: { read: strings(state.read, ["#"]), write: strings(state.write, [`agent/${id}/#`]), inject: strings(state.inject, []) },
+        trustWorkspace: raw.trustWorkspace === true,
+        mode: raw.mode ?? cfg.defaults.mode,
+        sandbox: {
+            enabled: raw.sandbox !== false && raw.sandbox?.enabled !== false,
+            network: raw.sandbox?.network === true,
+            read: paths(raw.sandbox?.read, dir),
+            write: paths(raw.sandbox?.write, dir),
+            sharedTmp: raw.sandbox?.sharedTmp !== false,
+            env: raw.sandbox?.env ?? {},
+        },
+        approve: strings(raw.approve, []),
+        approveWhenTainted: strings(raw.approveWhenTainted, ["publish_event", "send"]),
+        untrusted: raw.untrusted === false
+            ? false
+            : {
+                tools: strings(raw.untrusted?.tools, ["read", "grep", "find", "ls"]),
+                mcp: strings(raw.untrusted?.mcp, []),
+                delegates: strings(raw.untrusted?.delegates, []),
+                publish: strings(raw.untrusted?.publish, []),
+                stateWrite: raw.untrusted?.stateWrite === true,
+                subagents: raw.untrusted?.subagents === true,
+            },
+        bashTimeoutSec: raw.bashTimeoutSec ?? cfg.defaults.bashTimeoutSec,
+        bashDeny: strings(raw.bashDeny, []),
+        taskTimeoutSec: raw.taskTimeoutSec ?? cfg.defaults.taskTimeoutSec,
+        idleMs: raw.idleMs !== undefined ? parseDuration(raw.idleMs) : cfg.defaults.idleMs,
+        settings: { ...cfg.defaults.settings, ...(raw.settings ?? {}) },
+    };
+}
+function loadRoutes(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push("pine.json: routes must be an array");
+        return [];
+    }
+    return raw.flatMap((r, i) => {
+        const where = `pine.json: routes[${i}]`;
+        if (!r || (typeof r.on !== "string" && !Array.isArray(r.on))) {
+            problems.push(`${where}: needs "on" (topic pattern)`);
+            return [];
+        }
+        if (!r.agent && !r.call && !r.publish && !r.set)
+            problems.push(`${where}: needs one of agent, call, publish, set`);
+        if (r.agent && r.call)
+            problems.push(`${where}: use either agent or call, not both`);
+        if (r.call && typeof r.call.prompt !== "string")
+            problems.push(`${where}: call needs "prompt"`);
+        if (r.publish && typeof r.publish.topic !== "string")
+            problems.push(`${where}: publish needs "topic"`);
+        return [
+            {
+                ...r,
+                name: r.name ?? `route${i}`,
+                on: Array.isArray(r.on) ? r.on : [r.on],
+                debounceMs: r.debounceMs !== undefined ? parseDuration(r.debounceMs) : undefined,
+                throttleMs: r.throttleMs !== undefined ? parseDuration(r.throttleMs) : undefined,
+            },
+        ];
+    });
+}
+/** `file`: where the list stands. `agent`: the agent it belongs to, whose schedules need a task and are published under its name. */
+function loadSchedules(raw, problems, file = "pine.json", agent) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        problems.push(`${file}: schedules must be an array`);
+        return [];
+    }
+    return raw.flatMap((s, i) => {
+        const where = `${file}: schedules[${i}]`;
+        if (!s?.name) {
+            problems.push(`${where}: needs "name"`);
+            return [];
+        }
+        if (!/^[a-z][a-z0-9_-]{0,39}$/.test(s.name))
+            problems.push(`${where}: a schedule's name is lowercase letters, digits, - and _`);
+        if ([s.cron, s.every, s.at].filter((x) => x !== undefined).length !== 1)
+            problems.push(`${where}: needs exactly one of cron, every, at`);
+        const task = typeof s.task === "string" && s.task.trim() ? s.task.trim() : undefined;
+        if (agent && !task)
+            problems.push(`${where}: needs "task": what the agent is to do when it fires`);
+        let every;
+        let at;
+        try {
+            every = s.every !== undefined ? parseDuration(s.every) : undefined;
+            if (s.at !== undefined) {
+                at = typeof s.at === "number" ? s.at : Date.parse(String(s.at));
+                if (!Number.isFinite(at))
+                    throw new Error(`"${s.at}" is not a time. Write it as 2026-12-24T17:00`);
+            }
+        }
+        catch (e) {
+            problems.push(`${where}: ${e.message}`);
+        }
+        const key = agent ? `${s.name}@${agent}` : s.name;
+        // A task that was due while pine was not running is still worth doing; an event for a route is not repeated unless asked.
+        return [{ name: s.name, cron: s.cron, every, at, task, session: typeof s.session === "string" && s.session ? s.session : undefined, topic: s.topic ?? `timer/${key}`, payload: s.payload, catchUp: s.catchUp === undefined ? Boolean(task) : s.catchUp === true }];
+    });
+}
+/** Read `<home>/pine.json`, `<home>/.env` and every `<home>/agents/<id>/agent.json`. Throws ConfigError. */
+export function loadConfig(home = defaultHome()) {
+    const problems = [];
+    home = path.resolve(expandHome(home));
+    const file = path.join(home, "pine.json");
+    if (!fs.existsSync(file))
+        throw new ConfigError([`${file} not found. Run "pine init ${home}" to create a home directory.`]);
+    // Secrets from .env are used to fill in the configuration only. They are not exported to the
+    // process environment, so agent shells and MCP servers do not inherit them.
+    const envFile = path.join(home, ".env");
+    const fileEnv = fs.existsSync(envFile) ? parseEnv(fs.readFileSync(envFile, "utf8")) : {};
+    const env = { ...process.env, PINE_HOME: home, PINE_ROOT, ...fileEnv };
+    const raw = interpolate(readJson(file, problems), "pine.json", problems, env);
+    noPlugins(raw?.plugins, "pine.json: plugins", problems);
+    const d = raw.defaults ?? {};
+    // Source types of the owner's own: a name and the module behind it.
+    const sourceTypes = {};
+    for (const [name, file] of Object.entries(raw.sourceTypes && typeof raw.sourceTypes === "object" ? raw.sourceTypes : {})) {
+        if (!/^[a-z][a-z0-9_-]{0,39}$/.test(name) || SOURCE_TYPES.includes(name))
+            problems.push(`pine.json: sourceTypes.${name}: a type name is lowercase letters, digits, - and _, and not one of the built-in types`);
+        else if (typeof file !== "string" || !file)
+            problems.push(`pine.json: sourceTypes.${name} must be the path of a module`);
+        else
+            sourceTypes[name] = resolvePath(file, home);
+    }
+    const l = raw.limits ?? {};
+    const cfg = {
+        home,
+        dataDir: resolvePath(raw.dataDir ?? "data", home),
+        logLevel: raw.logLevel ?? "info",
+        main: raw.main,
+        defaults: {
+            model: d.model,
+            thinking: d.thinking ?? "off",
+            mode: d.mode ?? "auto",
+            bashTimeoutSec: d.bashTimeoutSec ?? 300,
+            taskTimeoutSec: d.taskTimeoutSec ?? 1800,
+            idleMs: parseDuration(d.idleMs ?? "15m"),
+            settings: d.settings ?? {},
+        },
+        limits: {
+            maxConcurrentRuns: l.maxConcurrentRuns ?? 2,
+            maxDelegationDepth: l.maxDelegationDepth ?? 3,
+            maxDownloadMb: l.maxDownloadMb ?? 200,
+            maxEventHops: l.maxEventHops ?? 8,
+            modelHeadersTimeoutMs: parseDuration(l.modelHeadersTimeoutMs ?? "10m"),
+            modelStreamIdleMs: parseDuration(l.modelStreamIdleMs ?? "5m"),
+            eventRetentionDays: l.eventRetentionDays ?? 30,
+            conversationDays: l.conversationDays ?? 7,
+            maxQueuedPerAgent: l.maxQueuedPerAgent ?? 50,
+            maxEventChars: l.maxEventChars ?? 20_000,
+        },
+        security: {
+            approvalTimeoutMs: parseDuration(raw.security?.approvalTimeout ?? "5m"),
+            taint: raw.security?.taint ?? "session",
+            taintTools: strings(raw.security?.taintTools, []),
+            bypassWhenTainted: raw.security?.bypassWhenTainted === true,
+        },
+        secrets: Object.values(fileEnv).filter((v) => v.length >= 8),
+        mcp: raw.mcp ?? {},
+        sources: loadSources(raw.sources, home, "pine.json: sources", problems, Object.keys(sourceTypes)),
+        sourceTypes,
+        subscribe: loadSubscriptions(raw.subscribe, "pine.json: subscribe", problems),
+        extensions: paths(raw.extensions, home),
+        skills: paths(raw.skills, home),
+        routes: loadRoutes(raw.routes, problems),
+        schedules: loadSchedules(raw.schedules, problems),
+        http: raw.http === false ? undefined : { host: raw.http?.host ?? "127.0.0.1", port: raw.http?.port ?? 7463, token: raw.http?.token, hooks: {} },
+        agents: {},
+    };
+    if (cfg.http) {
+        for (const [name, h] of Object.entries(raw.http?.hooks ?? {})) {
+            if (!/^[A-Za-z0-9_-]+$/.test(name))
+                problems.push(`pine.json: invalid hook name "${name}"`);
+            if (!h?.secret && h?.open !== true)
+                problems.push(`pine.json: http.hooks.${name} needs a "secret" (or "open": true to accept anyone who can reach the port)`);
+            cfg.http.hooks[name] = { topic: h?.topic ?? `hook/${name}`, secret: h?.secret || undefined };
+        }
+        if (cfg.http.token)
+            cfg.secrets.push(cfg.http.token);
+    }
+    const agentsDir = path.join(home, "agents");
+    for (const entry of fs.existsSync(agentsDir) ? fs.readdirSync(agentsDir, { withFileTypes: true }) : []) {
+        const dir = path.join(agentsDir, entry.name);
+        const agentFile = path.join(dir, "agent.json");
+        if (!entry.isDirectory() || !fs.existsSync(agentFile))
+            continue;
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(entry.name)) {
+            problems.push(`agents/${entry.name}: agent ids are lowercase letters, digits, "-" and "_"`);
+            continue;
+        }
+        const rawAgent = interpolate(readJson(agentFile, problems), `agents/${entry.name}/agent.json`, problems, env);
+        cfg.agents[entry.name] = loadAgent(entry.name, dir, rawAgent, cfg, problems);
+    }
+    const ids = Object.keys(cfg.agents);
+    if (ids.length === 0)
+        problems.push(`no agents found in ${agentsDir} (each agent is a folder with an agent.json)`);
+    if (cfg.main && !cfg.agents[cfg.main])
+        problems.push(`pine.json: main agent "${cfg.main}" does not exist`);
+    for (const a of Object.values(cfg.agents)) {
+        if (!MODES.includes(a.mode))
+            problems.push(`agents/${a.id}/agent.json: mode must be one of ${MODES.join(", ")} (got "${a.mode}")`);
+        if (!(a.model ?? cfg.defaults.model))
+            problems.push(`agents/${a.id}/agent.json: no model (set "model" or defaults.model in pine.json)`);
+        for (const t of a.delegates)
+            if (t !== "*" && !cfg.agents[t])
+                problems.push(`agents/${a.id}/agent.json: delegates names unknown agent "${t}"`);
+        if (Array.isArray(a.globalMcp))
+            for (const n of a.globalMcp)
+                if (!cfg.mcp[n])
+                    problems.push(`agents/${a.id}/agent.json: globalMcp names unknown server "${n}"`);
+        for (const n of Object.keys(a.mcp))
+            if (!/^[A-Za-z0-9_-]+$/.test(n))
+                problems.push(`agents/${a.id}/agent.json: invalid MCP server name "${n}"`);
+        for (const p of [...a.extensions, ...a.skills, ...a.context])
+            if (!fs.existsSync(p))
+                problems.push(`agents/${a.id}/agent.json: ${p} does not exist`);
+        for (const sub of a.subscribe)
+            if (!sourceFor(cfg, a.id, sub.source))
+                problems.push(`agents/${a.id}/agent.json: subscribe names "${sub.source}", which is not a source this agent can use`);
+    }
+    for (const sub of cfg.subscribe)
+        if (!cfg.sources[sub.source])
+            problems.push(`pine.json: subscribe names "${sub.source}", which is not a source in pine.json (a subscription for all agents needs a source all agents can use)`);
+    for (const [name, src] of Object.entries(cfg.sources))
+        for (const a of src.agents ?? [])
+            if (a !== "*" && !cfg.agents[a])
+                problems.push(`pine.json: sources.${name}.agents names unknown agent "${a}"`);
+    for (const [name, s] of Object.entries(cfg.mcp)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(name))
+            problems.push(`pine.json: invalid MCP server name "${name}"`);
+        for (const a of s.agents ?? [])
+            if (a !== "*" && !cfg.agents[a])
+                problems.push(`pine.json: mcp.${name}.agents names unknown agent "${a}"`);
+    }
+    for (const p of [...cfg.extensions, ...cfg.skills])
+        if (!fs.existsSync(p))
+            problems.push(`pine.json: ${p} does not exist`);
+    for (const r of cfg.routes)
+        if (r.agent && !cfg.agents[r.agent])
+            problems.push(`pine.json: route "${r.name}" names unknown agent "${r.agent}"`);
+    for (const [where, servers] of [["pine.json", cfg.mcp], ...Object.values(cfg.agents).map((a) => [`agents/${a.id}/agent.json`, a.mcp])]) {
+        for (const [name, s] of Object.entries(servers)) {
+            if (s.pine && !BUNDLED[s.pine])
+                problems.push(`${where}: mcp.${name}.pine "${s.pine}" is not a bundled server (have: ${Object.keys(BUNDLED).join(", ")})`);
+            if (!s.pine && !s.command && !s.url)
+                problems.push(`${where}: mcp.${name} needs "command", "url" or "pine"`);
+        }
+    }
+    if (problems.length)
+        throw new ConfigError(problems);
+    return cfg;
+}
+/** MCP servers an agent ends up with: its own, plus the global ones that include it. Own entries win. */
+/** The main agent: the one pine.json names; without that entry the one called "main", else the first one. */
+/**
+ * The files in an agent's workspace that are part of its prompt, in the order they enter it. They
+ * are the agent's own: it reads them as its instructions and keeps them up to date itself.
+ * AGENTS.md is how it works, SOUL.md who it is, MEMORY.md what should outlive a conversation.
+ */
+export const WORKSPACE_FILES = ["AGENTS.md", "SOUL.md", "MEMORY.md"];
+/** What all agents know about the owner: one file in pine's home, in every agent's prompt, kept by the main agent. */
+export const userFile = (cfg) => path.join(cfg.home, "USER.md");
+/**
+ * Where skills lie that were set up by tool call. The place says whom a skill is for: all agents,
+ * one agent, or one conversation of an agent. All of it is inside pine's home, which agents read
+ * but do not write.
+ */
+export const globalSkillsDir = (cfg) => path.join(cfg.home, "skills");
+export const agentSkillsDir = (agent) => path.join(agent.dir, "skills");
+export const conversationsDir = (agent) => path.join(agent.dir, "conversations");
+export function mainAgentId(cfg) {
+    return cfg.main ?? (cfg.agents.main ? "main" : Object.keys(cfg.agents)[0]);
+}
+/**
+ * The MCP servers an agent has. `session`: the conversation asked for, which also gets the servers
+ * that were added for it alone; without it, every server the agent has in any conversation.
+ */
+export function effectiveMcp(cfg, agent, session) {
+    const out = {};
+    for (const [name, server] of Object.entries(cfg.mcp)) {
+        const scope = server.agents ?? ["*"];
+        const listed = scope.includes("*") || scope.includes(agent.id);
+        const wanted = agent.globalMcp === true ? listed : Array.isArray(agent.globalMcp) ? agent.globalMcp.includes(name) : false;
+        if (wanted && server.enabled !== false)
+            out[name] = server;
+    }
+    for (const [name, server] of Object.entries(agent.mcp))
+        if (server.enabled !== false && (!server.session || session === undefined || server.session === session))
+            out[name] = server;
+    return out;
+}
+const BUNDLED = {
+    web: { file: `mcp/web${EXT}`, taints: true },
+    browser: { file: `mcp/browser${EXT}`, taints: true },
+    commands: { file: `mcp/commands${EXT}`, taints: false },
+};
+/** Turn a pine MCP entry into what pi's registerMcpServer() accepts. */
+export function toPiMcp(name, server, extraOptions = {}) {
+    const { agents: _a, pine, options, taints: _t, approve: _ap, session: _s, ...rest } = server;
+    if (!pine)
+        return { exposure: "direct", ...rest };
+    const bundled = BUNDLED[pine];
+    if (!bundled)
+        throw new Error(`mcp.${name}: unknown bundled server "${pine}" (have: ${Object.keys(BUNDLED).join(", ")})`);
+    return {
+        exposure: "direct",
+        ...rest,
+        command: process.execPath,
+        args: [path.join(PINE_ROOT, bundled.file)],
+        env: { ...(rest.env ?? {}), PINE_MCP_OPTIONS: JSON.stringify({ ...(options ?? {}), ...extraOptions }) },
+    };
+}
+const SOURCE_KEYS = ["type", "use", "description", "agents", "trust", "start", "enabled", "session"];
+function loadSources(raw, base, where, problems, own = []) {
+    const types = [...SOURCE_TYPES, ...own];
+    const out = {};
+    if (raw === undefined || raw === null)
+        return out;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        problems.push(`${where} must be an object of named sources`);
+        return out;
+    }
+    for (const [name, v] of Object.entries(raw)) {
+        if (!/^[a-z][a-z0-9_-]{0,39}$/.test(name))
+            problems.push(`${where}.${name}: a source name is lowercase letters, digits, - and _`);
+        if (!v || typeof v !== "object") {
+            problems.push(`${where}.${name} must be an object`);
+            continue;
+        }
+        if (!v.type === !v.use)
+            problems.push(`${where}.${name} needs either "type" (${types.join(", ")}) or "use" (a module of your own)`);
+        // Times are not a source any more: a schedule does what a timer source and a subscription did together.
+        if (v.type === "timer")
+            problems.push(`${where}.${name}: there is no "timer" source any more. Something that happens at a time is a schedule: ask the agent ("every morning at seven, ..."), or write { "name": "${name}", ${v.cron ? `"cron": "${v.cron}"` : `"every": "${v.every ?? "1h"}"`}, "task": "what to do" } under "schedules" and remove this source and its subscriptions`);
+        else if (v.type && !types.includes(v.type))
+            problems.push(`${where}.${name}: unknown type "${v.type}" (have: ${types.join(", ")})`);
+        if (v.trust !== undefined && v.trust !== "owner" && v.trust !== "untrusted")
+            problems.push(`${where}.${name}: trust is "owner" or "untrusted"`);
+        if (v.start !== undefined && v.start !== "subscribed" && v.start !== "always")
+            problems.push(`${where}.${name}: start is "subscribed" or "always"`);
+        out[name] = {
+            type: v.type,
+            use: v.use,
+            base,
+            description: typeof v.description === "string" ? v.description : undefined,
+            agents: Array.isArray(v.agents) ? v.agents.map(String) : undefined,
+            session: typeof v.session === "string" && v.session ? v.session : undefined,
+            // What a source reports was produced by someone or something else, unless the owner says it is theirs.
+            trust: v.trust ?? "untrusted",
+            start: v.start ?? "subscribed",
+            enabled: v.enabled !== false,
+            options: Object.fromEntries(Object.entries(v).filter(([k]) => !SOURCE_KEYS.includes(k))),
+        };
+    }
+    return out;
+}
+/**
+ * The forms "subscribe" may have in a file, as a plain list of entries:
+ * `["camera", "printer"]`, `{ "camera": { "note": ... } }`, or the form pine itself writes,
+ * `[{ "source": "camera", "session": "main", "note": ... }]`, which is the only one that can
+ * say that two conversations listen to the same source.
+ */
+export function rawSubscriptions(raw) {
+    if (Array.isArray(raw))
+        return raw.map((item) => (typeof item === "string" ? { source: item } : item && typeof item === "object" ? { ...item } : { source: String(item) }));
+    if (raw && typeof raw === "object")
+        return Object.entries(raw).map(([name, v]) => ({ ...(v && typeof v === "object" ? v : {}), source: name }));
+    return [];
+}
+function loadSubscriptions(raw, where, problems) {
+    const out = [];
+    if (raw === undefined || raw === null)
+        return out;
+    if (typeof raw !== "object") {
+        problems.push(`${where} must be a list of source names, a list of entries, or an object`);
+        return out;
+    }
+    for (const entry of rawSubscriptions(raw)) {
+        try {
+            const sub = subscriptionFrom(entry);
+            if (out.some((x) => x.source === sub.source && x.session === sub.session))
+                problems.push(`${where}: "${sub.source}" is listed twice for the conversation "${sub.session}"`);
+            else
+                out.push(sub);
+        }
+        catch (e) {
+            problems.push(`${where}.${entry.source ?? "?"}: ${e.message}`);
+        }
+    }
+    return out;
+}
+export function subscriptionFrom(v) {
+    if (typeof v.source !== "string" || !v.source)
+        throw new Error(`an entry needs "source": the name of the source`);
+    if (v.when !== undefined && (typeof v.when !== "object" || v.when === null || Array.isArray(v.when)))
+        throw new Error(`"when" must be an object of conditions`);
+    const separate = v.separate === true;
+    return {
+        source: v.source,
+        session: typeof v.session === "string" && v.session ? v.session : separate ? `on-${v.source}` : "main",
+        note: typeof v.note === "string" && v.note.trim() ? v.note.trim().slice(0, 2000) : undefined,
+        when: v.when,
+        debounceMs: v.debounce !== undefined ? parseDuration(v.debounce) : undefined,
+        throttleMs: parseDuration(v.throttle ?? "10s"),
+        throttleDefault: v.throttle === undefined ? true : undefined,
+        separate,
+        prompt: typeof v.prompt === "string" ? v.prompt : undefined,
+    };
+}
+/** The source an agent means by a name: its own first, then a global one it is allowed to use. */
+export function sourceFor(cfg, agentId, name) {
+    const agent = cfg.agents[agentId];
+    if (agent?.sources[name])
+        return { source: agent.sources[name], key: `${name}@${agentId}`, scope: agentId };
+    const global = cfg.sources[name];
+    if (global && (!global.agents || global.agents.includes("*") || global.agents.includes(agentId)))
+        return { source: global, key: name, scope: "global" };
+    return undefined;
+}
+export const mcpTaints = (server) => server.taints ?? (server.pine ? (BUNDLED[server.pine]?.taints ?? false) : false);
+/** Agents `from` may delegate to. */
+export function delegateTargets(cfg, from) {
+    const all = from.delegates.includes("*");
+    return Object.values(cfg.agents).filter((a) => a.id !== from.id && (all || from.delegates.includes(a.id)));
+}

package/src/dev/claude-model.d.ts

@@ -0,0 +1,28 @@
+/** The model's reply is one JSON object; tolerate a code fence or stray text around it. */
+export declare function parseReply(raw: string): {
+    text: string;
+    tool_calls: Array<{
+        name: string;
+        arguments: unknown;
+    }>;
+};
+export declare function buildPrompt(body: any): string;
+export interface ClaudeModelOptions {
+    port?: number;
+    host?: string;
+    /** Model alias passed to `claude --model`. Default "haiku". */
+    model?: string;
+    /** How many `claude` processes may run at once. Default 3. */
+    concurrency?: number;
+    claudePath?: string;
+    log?: (line: string) => void;
+}
+export declare function startClaudeModel(opts?: ClaudeModelOptions): Promise<{
+    port: any;
+    baseUrl: string;
+    stats: {
+        requests: number;
+        failures: number;
+    };
+    close: () => Promise<void>;
+}>;