@pmndrs/pine 0.0.0-stage → 0.1.1

package/src/agent-admin.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig, PINE_ROOT, WORKSPACE_FILES } from "./config.js";
+import { errText } from "./util.js";
+/** The built-in tools an agent can be given. */
+export const AGENT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * Create an agent while the daemon runs: its folder with agent.json, and a workspace with its
+ * instructions (AGENTS.md) and the other files it keeps itself, as they come with a new home. The files are written first and then read back through the normal loader, so a new
+ * agent is checked exactly like one that was there at start; if it does not pass, the folder is
+ * taken away again. Nothing but these few lines goes into its agent.json.
+ */
+/** What is wrong with a proposed agent, as an error; nothing is written. Returns the cleaned-up values. */
+export function checkNewAgent(cfg, spec) {
+    if (!/^[a-z][a-z0-9_-]{1,30}$/.test(spec.id))
+        throw new Error(`"${spec.id}" is not a usable agent id: lowercase letters, digits, - and _, starting with a letter, at least two characters`);
+    if (cfg.agents[spec.id])
+        throw new Error(`an agent called ${spec.id} exists already`);
+    const description = spec.description.replace(/\s+/g, " ").trim();
+    if (!description)
+        throw new Error("an agent needs a description: one line on what it is for");
+    if (!spec.instructions.trim())
+        throw new Error("an agent needs instructions: who it is and how it works");
+    const tools = spec.tools ?? AGENT_TOOLS;
+    const unknown = tools.filter((t) => !AGENT_TOOLS.includes(t));
+    if (unknown.length)
+        throw new Error(`unknown tool${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}. An agent can have: ${AGENT_TOOLS.join(", ")}`);
+    if (fs.existsSync(path.join(cfg.home, "agents", spec.id)))
+        throw new Error(`the folder agents/${spec.id} exists already`);
+    return { description, tools };
+}
+export function createAgent(cfg, spec) {
+    const { description, tools } = checkNewAgent(cfg, spec);
+    const dir = path.join(cfg.home, "agents", spec.id);
+    fs.mkdirSync(path.join(dir, "workspace"), { recursive: true, mode: 0o700 });
+    try {
+        fs.writeFileSync(path.join(dir, "agent.json"), `${JSON.stringify({ description, ...(spec.model ? { model: spec.model } : {}), tools }, null, 2)}\n`, { mode: 0o600 });
+        fs.writeFileSync(path.join(dir, "workspace", "AGENTS.md"), `${spec.instructions.trim()}\n`, { mode: 0o600 });
+        // The rest starts as the stubs a new home has.
+        for (const name of WORKSPACE_FILES.slice(1)) {
+            const stub = path.join(PINE_ROOT, "examples", "home", "agents", "main", "workspace", name);
+            if (fs.existsSync(stub))
+                fs.copyFileSync(stub, path.join(dir, "workspace", name)), fs.chmodSync(path.join(dir, "workspace", name), 0o600);
+        }
+        const made = loadConfig(cfg.home).agents[spec.id];
+        if (!made)
+            throw new Error("the new agent was not found after writing it");
+        cfg.agents[spec.id] = made;
+        return made;
+    }
+    catch (e) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw new Error(`the agent could not be created: ${errText(e)}`);
+    }
+}

package/src/agents.d.ts

@@ -0,0 +1,343 @@
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type AgentConfig, type McpServerConfig, type Mode, type PineConfig } from "./config.ts";
+import { Limiter, type Slot } from "./limiter.ts";
+import { type Approvals, type SandboxVariant } from "./security.ts";
+import type { Bus, Kv, State, TaskStore } from "./store.ts";
+import type { SourceHost } from "./sources.ts";
+import type { Scheduler } from "./timers.ts";
+import type { ContextUse, ImageRef, PineEvent, ReplyTarget, Task, TaskKind, TaskResult, TranscriptEntry, Trust } from "./types.ts";
+import { type Logger } from "./util.ts";
+export declare const THINKING_LEVELS: string[];
+export interface SubmitOptions {
+    agent: string;
+    prompt: string;
+    /** Session key. Default "main". "new" runs in a fresh session that is closed afterwards. */
+    session?: string;
+    kind?: TaskKind;
+    priority?: number;
+    event?: PineEvent;
+    reply?: ReplyTarget;
+    parent?: Task;
+    images?: ImageRef[];
+    /** Files the owner hands over with the message. They are saved to inbox/ in the workspace. */
+    attachments?: Array<{
+        name: string;
+        data: string;
+    }>;
+    notify?: {
+        agent: string;
+        session: string;
+    };
+    whenBusy?: "queue" | "steer";
+    trust?: Trust;
+    tainted?: string;
+    leaf?: boolean;
+    tools?: string[];
+    label?: string;
+}
+/** Capabilities of one run, decided by who started it. */
+export interface Profile {
+    tools: string[];
+    mcp: Record<string, McpServerConfig>;
+    delegates: string[];
+    subagents: boolean;
+    publish: string[];
+    stateWrite: boolean;
+    /** A sub-agent: a copy doing one job. */
+    leaf: boolean;
+}
+export interface RunContext {
+    task: Task;
+    slot: Slot;
+    cancelled?: boolean;
+    timedOut?: boolean;
+}
+export interface Live {
+    agent: AgentConfig;
+    key: string;
+    ephemeral: boolean;
+    trust: Trust;
+    runtime: any;
+    session: any;
+    current?: RunContext;
+    tainted?: string;
+    taint(reason: string): void;
+    /** True when the run must not change instructions or act without checks: untrusted start or tainted session. */
+    restricted(): boolean;
+    /** The mode in force for the call that is about to run (see effectiveMode). */
+    mode(): Mode;
+    /** Which sandbox the next shell or file call runs in. */
+    variant(): SandboxVariant;
+    /**
+     * The conversation whose permissions apply here ("agent:session"). A sub-agent is a copy of its
+     * conversation doing part of that conversation's job, so it has that conversation's key: what the
+     * owner allowed there (access, "always" answers) holds for it, and what it is allowed holds there.
+     */
+    perm: string;
+    /** Access the owner granted to this conversation beyond the agent's own folders. Holds until the conversation is reset or the daemon restarts. */
+    grant(kind: "read" | "write" | "network", target?: string): string | undefined;
+    /** Take over what the conversation has been granted since this session's sandbox was written. */
+    syncGrants(): void;
+    /** Whether this session's shell can use the network right now. */
+    network(): boolean;
+    /** The folder the owner opened for this conversation, if any: where its tools start, and readable and writable for it. */
+    folder?: string;
+    sandboxed: boolean;
+    idleTimer?: NodeJS.Timeout;
+    /** The last "[pine]" note this session was sent, without its time. A new one goes out when this changes. */
+    noteKey?: string;
+    /** The configuration changed under this session; close it when it is idle so the next task starts it anew. */
+    stale?: boolean;
+    contextStamp: string;
+    lastUsed: number;
+}
+export interface AgentManagerDeps {
+    cfg: PineConfig;
+    bus: Bus;
+    state: State;
+    kv: Kv;
+    tasks: TaskStore;
+    approvals: Approvals;
+    log: Logger;
+}
+export declare class AgentManager {
+    cfg: PineConfig;
+    bus: Bus;
+    state: State;
+    kv: Kv;
+    tasks: TaskStore;
+    approvals: Approvals;
+    limiter: Limiter;
+    private log;
+    /** Event sources and subscriptions. Set by the daemon once both exist. */
+    sources?: SourceHost;
+    /** Set by the daemon once the scheduler exists. */
+    schedules?: Scheduler;
+    private modelRuntime;
+    private lives;
+    private creating;
+    private lanes;
+    private running;
+    private waiters;
+    private taints;
+    private stopping;
+    private warnedNoSandbox;
+    /** Conversations ("agent:session") where the owner chose bypass although they have read outside content. */
+    private bypassAnyway;
+    /**
+     * What the owner allowed "always" in a conversation ("agent:session" -> "server:<name>" or
+     * "tool:<name>"), with the state the conversation was in. A yes given before the conversation
+     * read outside content does not cover it afterwards. Gone with a reset or a restart.
+     */
+    private allowed;
+    /** Access granted to a conversation with request_access, by the same key. Its sub-agents share it. */
+    private grants;
+    constructor(deps: AgentManagerDeps);
+    init(): Promise<void>;
+    get models(): ModelRuntime;
+    modelFor(agent: AgentConfig): any;
+    resolveModel(ref: string): any;
+    /** Models that have credentials (or need none), as "provider/id". */
+    availableModels(): Promise<string[]>;
+    /**
+     * Switch an agent to another model and save the choice in its agent.json, so it is still the
+     * agent's model after a restart. Sessions pick it up with their next task and keep their history.
+     */
+    setModel(agentId: string, ref: string): Promise<void>;
+    submit(o: SubmitOptions): Task;
+    /** Write attached files into <workspace>/inbox and say which of them are images. */
+    private saveAttachments;
+    wait(id: number): Promise<TaskResult>;
+    /** Submit and wait. */
+    run(o: SubmitOptions): Promise<TaskResult>;
+    /** Wait for child tasks while lending this run's model slot to them. Aborting cancels the children. */
+    awaitChildren(run: RunContext, ids: number[], signal?: AbortSignal): Promise<TaskResult[]>;
+    cancel(id: number): boolean;
+    /**
+     * What a task did, step by step, read from the session file pi keeps for it: the text it was
+     * given, what it wrote and thought, and every tool call with the start of its result. This is how
+     * a sub-agent's work can be looked at, during the run and afterwards; its session folder
+     * (sessions/_tasks/<task id>) stays on disk. For a task in a named session, only that task's part
+     * of the conversation is returned.
+     */
+    /** The folder a UI shows beside a conversation: the one opened for it, else the agent's workspace. */
+    viewRoot(agentId: string, session: string): string | undefined;
+    /** What a task did, step by step. `full` keeps each tool's whole output (for reading it), not just its start. */
+    transcript(id: number, full?: boolean): {
+        task: Task;
+        entries: TranscriptEntry[];
+    } | undefined;
+    /** Save the pictures in a tool result under data/media/tool, so a UI can fetch them by id. */
+    private keepToolImages;
+    /** A picture a tool returned (see keepToolImages). */
+    toolImage(id: string): Picture | undefined;
+    /** The n-th picture that came with a task: an attachment, or an image an adapter passed along. */
+    taskImage(taskId: number, n: number): Picture | undefined;
+    /**
+     * A picture or video in an agent's workspace, which the agent refers to in an answer. Only real
+     * image and video files inside the workspace are served: the path comes from model output, and this endpoint
+     * must not become a way to read other files.
+     */
+    workspaceImage(agentId: string, file: string, session?: string): Picture | undefined;
+    /** A picture at a web address, fetched because the owner asked for it. Https and public addresses only. */
+    fetchImage(url: string): Promise<Picture | undefined>;
+    /** Remove kept tool pictures that are older than the event log reaches back. */
+    pruneMedia(olderThanMs: number): void;
+    status(): {
+        limiter: {
+            active: number;
+            waiting: number;
+            max: number;
+        };
+        running: {
+            task: number;
+            agent: string;
+            session: string;
+            kind: TaskKind;
+        }[];
+        sessions: {
+            agent: string;
+            session: string;
+            busy: boolean;
+            tainted: string | undefined;
+            trust: Trust;
+            mode: Mode;
+            context: ContextUse | undefined;
+        }[];
+        modes: {
+            [k: string]: Mode;
+        };
+    };
+    /** Forget a session's history (and its taint). The next task with this key starts fresh. */
+    resetSession(agentId: string, session?: string): Promise<boolean>;
+    folderOf(agentId: string, session: string): string | undefined;
+    /** Every conversation of an agent that has a folder, also one nothing was said in yet. */
+    folders(agentId: string): Array<{
+        session: string;
+        folder: string;
+    }>;
+    /** Why a folder cannot be opened for an agent, or undefined when it can. */
+    private folderProblem;
+    /** Open a folder for a conversation, or with `null` go back to the agent's own workspace. Takes effect with its next message. */
+    setFolder(agentId: string, session: string, wanted: string | null): Promise<{
+        folder?: string;
+    }>;
+    /** The session keys a conversation's name stands for: its own and the one outside content is handled in. */
+    private keysOf;
+    private pinned;
+    /** The tabs a UI had open, to open them again, and so that an open conversation is not removed. */
+    uiTabs(): {
+        tabs: Array<{
+            agent: string;
+            session: string;
+        }>;
+        active: number;
+        code: boolean;
+    };
+    /** `code`: whether the pane beside the conversation was open. Left as it was when not given. */
+    saveUiTabs(tabs: unknown, active: unknown, code?: unknown): void;
+    /**
+     * An agent's conversations: pinned ones first, then the most recently used. `expires` is when
+     * one is removed by itself if nothing more is said in it; one without it stays.
+     */
+    conversations(agentId: string): Array<{
+        session: string;
+        tasks: number;
+        last: number;
+        pinned: boolean;
+        open: boolean;
+        expires?: number;
+        folder?: string;
+    }>;
+    /** Pin a conversation, so that it stays however long it is not used, or take the pin off. */
+    pinSession(agentId: string, session: string, on: boolean): boolean;
+    /** Remove a conversation for good: what was said in it, what it may do without asking, what it listens to. */
+    removeSession(agentId: string, session: string): Promise<{
+        removed: boolean;
+        unsubscribed: string[];
+        sources: string[];
+        servers: string[];
+    }>;
+    /** Give a conversation another name. Everything stays with it: its history, its pin, what it listens to. */
+    renameSession(agentId: string, from: string, wanted: string): Promise<{
+        session: string;
+    }>;
+    /**
+     * The daily tidying: conversations that have reached their time, and the copies kept of reset
+     * conversations once they are older than the event log reaches back.
+     */
+    pruneConversations(): Promise<number>;
+    stop(): Promise<void>;
+    private enqueue;
+    private execute;
+    private causeOf;
+    private resultOf;
+    private finish;
+    profileFor(agent: AgentConfig, trust: Trust, task?: Task): Profile;
+    private live;
+    private createLive;
+    /** The session whose permissions a task runs under: its own, or for a sub-agent the one that started it. */
+    private permSession;
+    /** Everything pine itself adds to a session: MCP servers, the sandboxed shell, the policy gate, and context. */
+    /**
+     * The mode that applies right now. A run started by an outside event never gets more than
+     * "auto", and bypass is suspended in a session that has read outside content unless the
+     * configuration says otherwise: those are the two situations in which someone else may be steering.
+     */
+    effectiveMode(agent: AgentConfig, live: Pick<Live, "trust" | "tainted" | "key"> & {
+        perm?: string;
+    }): Mode;
+    /**
+     * Set how much an agent's model reasons before it answers, and save it in agent.json. Applies
+     * from the next model call. A model that cannot reason ignores it; pi lowers a level the model
+     * does not offer to the nearest one it does.
+     */
+    setThinking(agentId: string, level: string): void;
+    /**
+     * Tools or servers of some agents changed. Idle sessions are closed now and busy ones when their
+     * task ends; each continues from its history with the new set when it is next used.
+     */
+    refreshSessions(agentIds?: string[]): Promise<void>;
+    /**
+     * Change an agent's mode until the daemon restarts. Takes effect on its next tool call.
+     * `anyway` names a conversation in which the owner, knowing it has read outside content,
+     * wants bypass to apply all the same.
+     */
+    setMode(agentId: string, mode: Mode, anyway?: string): void;
+    private coreExtension;
+    /**
+     * Can this agent move information out of the machine: web or remote MCP tools, or a shell with
+     * network? A tainted session that hands such an agent a task could be leaking through it.
+     */
+    canSendOut(agentId: string): boolean;
+    /**
+     * The part of the system prompt that pine adds. Everything here is fixed for the life of a
+     * session. A model server reuses its work only for a prompt whose beginning is unchanged, and
+     * the system prompt is the very beginning: one changing word here would make a local model
+     * read the whole conversation again on every turn. What changes goes into contextNote().
+     */
+    private contextBlock;
+    /**
+     * What is true right now: the time, the mode, trust, shared state. It is put in front of the
+     * incoming message, at the end of the conversation, and only when something other than the
+     * clock has changed since the last note, so the conversation so far stays byte for byte what
+     * the model server has already seen. `key` is the note without the time.
+     */
+    private contextNote;
+    private sizeOf;
+    /**
+     * The files that make up an agent's instructions, in the order they enter its prompt; those
+     * that exist. First what the owner alone can change, then what the agent keeps itself, the
+     * one that changes most often last.
+     */
+    private instructionFiles;
+    private stamp;
+    /** pi reads instruction files once per session; pick up edits made since. */
+    private refresh;
+    private armIdle;
+    private dispose;
+}
+export interface Picture {
+    mime: string;
+    bytes: Buffer;
+}