@pmndrs/pine 0.0.0-stage → 0.1.1

package/src/config.d.ts

@@ -0,0 +1,351 @@
+import type { ReplyTarget } from "./types.ts";
+import { type LogLevel } from "./util.ts";
+/** One MCP server, in the shape of an `mcpServers` entry of pi's mcp.json, plus `agents` for global servers. */
+export interface McpServerConfig {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    exposure?: "direct" | "codemode" | "deferred" | "hidden";
+    toolExposure?: Record<string, string>;
+    description?: string;
+    enabled?: boolean;
+    timeout?: number;
+    /** Global servers only: which agents get it. Default ["*"]. */
+    agents?: string[];
+    /** Use a server that ships with pine ("web", "browser", "commands") instead of command/url. */
+    pine?: string;
+    options?: Record<string, unknown>;
+    /** Its results are outside content: a session that calls it counts as tainted. */
+    taints?: boolean;
+    /** When calls need the owner's approval. Default "never" ("tainted" for servers flagged sensitive by the docs). */
+    approve?: "never" | "tainted" | "always";
+    /** An agent's own servers only: the one conversation that gets it. Written by add_mcp_server for a server added for a conversation; it is removed with that conversation. */
+    session?: string;
+    [key: string]: unknown;
+}
+/**
+ * A source of outside events: a watched folder, an MQTT broker, a webhook, an FTP drop, a web
+ * address, or your own module. Like an MCP server it only is there; nothing happens until an agent
+ * subscribes to it. The remaining keys are the options of its type.
+ */
+export interface SourceConfig {
+    /** A built-in type (see SOURCE_TYPES) ... */
+    type?: string;
+    /** ... or the path of a module whose default export is `(source) => void`. */
+    use?: string;
+    /** Where relative paths in the entry are resolved from. */
+    base: string;
+    /** One line for agents and people: what this source reports. */
+    description?: string;
+    /** Global sources only: the agents that may subscribe. Default: all. */
+    agents?: string[];
+    /** An agent's own sources only: the one conversation it was set up for. Other conversations do not see it, and it is removed with that conversation. */
+    session?: string;
+    /** Who its events speak for. "untrusted" (default): outside content, the subscriber wakes with its reduced tool set. "owner": your own device or schedule. */
+    trust: "owner" | "untrusted";
+    /** "subscribed" (default): runs only while an agent is subscribed. "always": runs from start, for routes that use its events. */
+    start: "subscribed" | "always";
+    enabled: boolean;
+    options: Record<string, any>;
+}
+export declare const SOURCE_TYPES: string[];
+/**
+ * A subscription: one conversation of an agent listens to one source, and each event of the source
+ * arrives there as a message and wakes the agent into a turn. Several conversations of the same
+ * agent can listen to the same source, each with its own note.
+ */
+export interface SubscriptionConfig {
+    source: string;
+    /** What the agent wants to do when it is woken, in its own or your words. Given to it with every event. */
+    note?: string;
+    /** Only events that match (same filter as routes; keys such as "event" and "payload.x"). */
+    when?: Record<string, unknown>;
+    /** Wait for quiet, then handle only the last event. */
+    debounceMs?: number;
+    /** Handle one event, then ignore the source for this long. Default 10 s, so a chatty device cannot keep a model busy. */
+    throttleMs: number;
+    /** Whether that is the default, as opposed to something the subscription said. A source somebody writes through is not held back by the default: every message counts. */
+    throttleDefault?: boolean;
+    /** The conversation that listens: the one the agent subscribed in. "main" unless said otherwise ("on-<source>" with `separate`). */
+    session: string;
+    /**
+     * true: wake it in a conversation of its own ("on-<source>", or `session`) instead, and for a
+     * source that is not yours with the reduced tool set. For sources that carry strangers' text.
+     */
+    separate: boolean;
+    /** Replaces the standard text the agent is woken with. Templates as in routes. */
+    prompt?: string;
+}
+export interface RouteConfig {
+    name: string;
+    on: string[];
+    when?: Record<string, unknown>;
+    /** Wait for this long without a new matching event, then handle only the last one. */
+    debounceMs?: number;
+    /** Handle the first event, then ignore matching events for this long. */
+    throttleMs?: number;
+    /** Template for the debounce/throttle bucket. Default: the event topic. */
+    key?: string;
+    /** Write world state: key template -> value template. */
+    set?: Record<string, unknown>;
+    /** Publish another event. With `call`, `{{result}}` holds the model's answer. */
+    publish?: {
+        topic: string;
+        payload?: unknown;
+    };
+    /** One model call without tools or history. */
+    call?: {
+        model?: string;
+        system?: string;
+        prompt: string;
+    };
+    /** Full agent turn. */
+    agent?: string;
+    prompt?: string;
+    session?: string;
+    whenBusy?: "queue" | "steer";
+    priority?: number;
+    /** Where the agent's final answer goes. Default: the event's own reply target. false: nowhere. */
+    reply?: ReplyTarget | false;
+    /** Override the event's trust. "owner" gives events on this route the agent's full tool set. */
+    trust?: "owner" | "untrusted";
+    /** Text put in front of the event for the agent, outside the "this is data" frame. Set by subscriptions, not in pine.json. */
+    preface?: string;
+    /**
+     * Set by subscriptions: the event is delivered into the subscriber's own conversation, with its
+     * usual tools, as outside content. The conversation is marked with this reason, as it would be
+     * after reading a web page.
+     */
+    taint?: string;
+    /** Short line for listings and the UI. Template. */
+    label?: string;
+}
+/**
+ * Something that happens at a time: every so often, at set times, or once. With a `task` it wakes
+ * an agent to do that task; without one it only publishes an event for a route to pick up.
+ *
+ * Like sources, servers and skills, a schedule is for all agents (pine.json), for one agent
+ * (agent.json) or for one conversation of an agent (agent.json, with `session`).
+ */
+export interface ScheduleConfig {
+    name: string;
+    /** Five-field cron expression in local time. */
+    cron?: string;
+    /** Fixed interval such as "15m", in milliseconds. */
+    every?: number;
+    /** Once, at this moment (milliseconds since 1970). The schedule is removed when it has fired. */
+    at?: number;
+    /** What the agent is to do when it fires, written to the agent. */
+    task?: string;
+    /** The conversation that is woken. Leaving it out is the agent as such: its main conversation. */
+    session?: string;
+    topic: string;
+    payload?: unknown;
+    /** Fire once at startup when a cron time passed while the daemon was down. */
+    catchUp: boolean;
+}
+export interface HookConfig {
+    topic: string;
+    /** Shared secret: accepted as `Authorization: Bearer <secret>` or as an HMAC-SHA256 of the body in `X-Hub-Signature-256` / `X-Signature`. */
+    secret?: string;
+}
+/**
+ * How much an agent may do without asking.
+ * manual: every action that changes or sends something waits for approval.
+ * auto:   works freely inside its sandbox; asks for what the rules single out, and for access beyond it.
+ * bypass: never asks, and its shell and file tools reach the whole user account (pine's own home and code stay closed).
+ */
+export type Mode = "manual" | "auto" | "bypass";
+export declare const MODES: Mode[];
+export interface SandboxConfig {
+    enabled: boolean;
+    /** Shell commands may open network connections. */
+    network: boolean;
+    /** Extra paths the agent may read / write, besides its workspace. */
+    read: string[];
+    write: string[];
+    /** Allow the shared temp directories (/tmp and the user's temp dir). */
+    sharedTmp: boolean;
+    env: Record<string, string>;
+}
+/** What a run triggered by an untrusted event may use. */
+export interface UntrustedProfile {
+    tools: string[];
+    mcp: string[];
+    delegates: string[];
+    publish: string[];
+    stateWrite: boolean;
+    subagents: boolean;
+}
+export interface AgentConfig {
+    id: string;
+    /** pi agent dir of this agent: AGENTS.md, skills/, extensions/, settings.json, sessions/. */
+    dir: string;
+    description: string;
+    workspace: string;
+    model?: string;
+    thinking: string;
+    /** Allowlist of pi built-in tools. Undefined keeps pi's default set. */
+    tools?: string[];
+    mcp: Record<string, McpServerConfig>;
+    /** Which global MCP servers this agent gets: all that list it (true), none (false), or these names. */
+    globalMcp: boolean | string[];
+    /** Event sources only this agent can subscribe to. */
+    sources: Record<string, SourceConfig>;
+    /** What this agent's conversations are subscribed to: its own sources or global ones. */
+    subscribe: SubscriptionConfig[];
+    /** What this agent does at set times: for the agent as such, or (with `session`) for one conversation. */
+    schedules: ScheduleConfig[];
+    extensions: string[];
+    skills: string[];
+    /** Extra instruction files loaded into the system prompt, besides AGENTS.md in the agent dir and the workspace. */
+    context: string[];
+    /** Agents this one may hand tasks to. "*" means every other agent. */
+    delegates: string[];
+    subagents: {
+        enabled: boolean;
+        maxParallel: number;
+        tools?: string[];
+        mcp: boolean;
+    };
+    /** Topics the publish_event tool may publish to. */
+    publish: string[];
+    state: {
+        read: string[];
+        write: string[];
+        inject: string[];
+    };
+    trustWorkspace: boolean;
+    mode: Mode;
+    sandbox: SandboxConfig;
+    /** Tool calls that always need the owner's approval: "tool" or "tool:argument-glob". */
+    approve: string[];
+    /** Tool calls that need approval once the session has seen outside content. */
+    approveWhenTainted: string[];
+    /** Profile for runs triggered by untrusted events; false refuses such runs. */
+    untrusted: UntrustedProfile | false;
+    bashTimeoutSec: number;
+    bashDeny: string[];
+    taskTimeoutSec: number;
+    idleMs: number;
+    settings: Record<string, unknown>;
+}
+export interface PineConfig {
+    home: string;
+    dataDir: string;
+    logLevel: LogLevel;
+    main?: string;
+    defaults: {
+        model?: string;
+        thinking: string;
+        mode: Mode;
+        bashTimeoutSec: number;
+        taskTimeoutSec: number;
+        idleMs: number;
+        settings: Record<string, unknown>;
+    };
+    limits: {
+        maxConcurrentRuns: number;
+        maxDelegationDepth: number;
+        /** Largest file the download tool fetches. */
+        maxDownloadMb: number;
+        maxEventHops: number;
+        modelHeadersTimeoutMs: number;
+        modelStreamIdleMs: number;
+        eventRetentionDays: number;
+        /** A conversation that is not pinned, not open in a tab, not subscribed to anything and without a schedule of its own is removed after this many days without a message. 0: never. */
+        conversationDays: number;
+        maxQueuedPerAgent: number;
+        maxEventChars: number;
+    };
+    security: {
+        approvalTimeoutMs: number;
+        /** How long a session stays tainted after it saw outside content. */
+        taint: "session" | "run" | "off";
+        /** Tool name globs whose results are outside content, besides MCP servers marked `taints`. */
+        taintTools: string[];
+        /** Keep bypass mode in force after a session has seen outside content. Off: such a session asks again. */
+        bypassWhenTainted: boolean;
+    };
+    /** Values that must never leave the daemon in events or messages. */
+    secrets: string[];
+    mcp: Record<string, McpServerConfig>;
+    /** Event sources every agent can subscribe to (or the agents an entry lists). */
+    sources: Record<string, SourceConfig>;
+    /** Source types of your own, besides the built-in ones: type name -> the module that implements it. */
+    sourceTypes: Record<string, string>;
+    /** Subscriptions for everyone: each agent that can use the source is woken in its main conversation. */
+    subscribe: SubscriptionConfig[];
+    extensions: string[];
+    skills: string[];
+    routes: RouteConfig[];
+    schedules: ScheduleConfig[];
+    http?: {
+        host: string;
+        port: number;
+        token?: string;
+        hooks: Record<string, HookConfig>;
+    };
+    agents: Record<string, AgentConfig>;
+}
+export declare class ConfigError extends Error {
+    problems: string[];
+    constructor(problems: string[]);
+}
+/** The pine checkout: bundled MCP servers and source types live here. */
+export declare const PINE_ROOT: string;
+/**
+ * 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 declare const EXT: string;
+export declare const defaultHome: () => string;
+/** Read `<home>/pine.json`, `<home>/.env` and every `<home>/agents/<id>/agent.json`. Throws ConfigError. */
+export declare function loadConfig(home?: string): PineConfig;
+/** 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 declare const WORKSPACE_FILES: string[];
+/** What all agents know about the owner: one file in pine's home, in every agent's prompt, kept by the main agent. */
+export declare const userFile: (cfg: PineConfig) => string;
+/**
+ * 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 declare const globalSkillsDir: (cfg: Pick<PineConfig, "home">) => string;
+export declare const agentSkillsDir: (agent: Pick<AgentConfig, "dir">) => string;
+export declare const conversationsDir: (agent: Pick<AgentConfig, "dir">) => string;
+export declare function mainAgentId(cfg: PineConfig): string;
+/**
+ * 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 declare function effectiveMcp(cfg: PineConfig, agent: AgentConfig, session?: string): Record<string, McpServerConfig>;
+/** Turn a pine MCP entry into what pi's registerMcpServer() accepts. */
+export declare function toPiMcp(name: string, server: McpServerConfig, extraOptions?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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 declare function rawSubscriptions(raw: unknown): Array<Record<string, any>>;
+export declare function subscriptionFrom(v: Record<string, any>): SubscriptionConfig;
+/** The source an agent means by a name: its own first, then a global one it is allowed to use. */
+export declare function sourceFor(cfg: PineConfig, agentId: string, name: string): {
+    source: SourceConfig;
+    key: string;
+    scope: string;
+} | undefined;
+export declare const mcpTaints: (server: McpServerConfig) => boolean;
+/** Agents `from` may delegate to. */
+export declare function delegateTargets(cfg: PineConfig, from: AgentConfig): AgentConfig[];