@pmndre/pine 0.0.0-stage → 0.22.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -2
  3. package/bin/pine.js +27 -0
  4. package/docs/SKILL.md +234 -0
  5. package/docs/references/agents.md +454 -0
  6. package/docs/references/coding.md +311 -0
  7. package/docs/references/computer.md +212 -0
  8. package/docs/references/configuration.md +310 -0
  9. package/docs/references/events.md +267 -0
  10. package/docs/references/mcp.md +420 -0
  11. package/docs/references/operations.md +394 -0
  12. package/docs/references/overview.md +195 -0
  13. package/docs/references/security.md +896 -0
  14. package/docs/references/setup.md +385 -0
  15. package/docs/references/sources.md +772 -0
  16. package/docs/references/stack.md +121 -0
  17. package/docs/references/tui.md +575 -0
  18. package/examples/home/.env.example +7 -0
  19. package/examples/home/USER.md +4 -0
  20. package/examples/home/agents/main/agent.json +4 -0
  21. package/examples/home/agents/main/workspace/AGENTS.md +14 -0
  22. package/examples/home/agents/main/workspace/MEMORY.md +4 -0
  23. package/examples/home/agents/main/workspace/SOUL.md +4 -0
  24. package/examples/home/models.json +62 -0
  25. package/examples/home/pine.json +34 -0
  26. package/examples/home/skills/README.txt +7 -0
  27. package/examples/launchd/com.pine.daemon.plist +32 -0
  28. package/examples/systemd/pine.service +22 -0
  29. package/mcp/browser.d.ts +99 -0
  30. package/mcp/browser.js +496 -0
  31. package/mcp/commands.d.ts +20 -0
  32. package/mcp/commands.js +88 -0
  33. package/mcp/computer.d.ts +139 -0
  34. package/mcp/computer.js +698 -0
  35. package/mcp/computer.swift +989 -0
  36. package/mcp/lib.d.ts +23 -0
  37. package/mcp/lib.js +52 -0
  38. package/mcp/web.d.ts +6 -0
  39. package/mcp/web.js +140 -0
  40. package/package.json +32 -4
  41. package/src/access.d.ts +112 -0
  42. package/src/access.js +438 -0
  43. package/src/actions.d.ts +75 -0
  44. package/src/actions.js +167 -0
  45. package/src/admin.d.ts +167 -0
  46. package/src/admin.js +625 -0
  47. package/src/agent-admin.d.ts +24 -0
  48. package/src/agent-admin.js +55 -0
  49. package/src/agents.d.ts +540 -0
  50. package/src/agents.js +2776 -0
  51. package/src/background.d.ts +29 -0
  52. package/src/background.js +100 -0
  53. package/src/cli.d.ts +2 -0
  54. package/src/cli.js +777 -0
  55. package/src/computer.d.ts +30 -0
  56. package/src/computer.js +32 -0
  57. package/src/config.d.ts +396 -0
  58. package/src/config.js +549 -0
  59. package/src/dev/claude-model.d.ts +37 -0
  60. package/src/dev/claude-model.js +204 -0
  61. package/src/env-file.d.ts +4 -0
  62. package/src/env-file.js +40 -0
  63. package/src/goals.d.ts +133 -0
  64. package/src/goals.js +316 -0
  65. package/src/http.d.ts +46 -0
  66. package/src/http.js +509 -0
  67. package/src/limiter.d.ts +32 -0
  68. package/src/limiter.js +84 -0
  69. package/src/login.d.ts +23 -0
  70. package/src/login.js +130 -0
  71. package/src/manual.d.ts +61 -0
  72. package/src/manual.js +443 -0
  73. package/src/mcp-config.d.ts +49 -0
  74. package/src/mcp-config.js +182 -0
  75. package/src/models.d.ts +90 -0
  76. package/src/models.js +274 -0
  77. package/src/net.d.ts +50 -0
  78. package/src/net.js +150 -0
  79. package/src/pine.d.ts +32 -0
  80. package/src/pine.js +134 -0
  81. package/src/programs.d.ts +123 -0
  82. package/src/programs.js +412 -0
  83. package/src/router.d.ts +56 -0
  84. package/src/router.js +164 -0
  85. package/src/sandbox-fs.d.ts +34 -0
  86. package/src/sandbox-fs.js +186 -0
  87. package/src/sandbox-linux.d.ts +96 -0
  88. package/src/sandbox-linux.js +297 -0
  89. package/src/sandbox-setup.d.ts +70 -0
  90. package/src/sandbox-setup.js +216 -0
  91. package/src/security.d.ts +238 -0
  92. package/src/security.js +660 -0
  93. package/src/skills.d.ts +67 -0
  94. package/src/skills.js +163 -0
  95. package/src/snapshots.d.ts +68 -0
  96. package/src/snapshots.js +306 -0
  97. package/src/source-types.d.ts +61 -0
  98. package/src/source-types.js +1 -0
  99. package/src/sources/command.d.ts +4 -0
  100. package/src/sources/command.js +77 -0
  101. package/src/sources/folder.d.ts +6 -0
  102. package/src/sources/folder.js +116 -0
  103. package/src/sources/ftp.d.ts +4 -0
  104. package/src/sources/ftp.js +307 -0
  105. package/src/sources/http.d.ts +4 -0
  106. package/src/sources/http.js +201 -0
  107. package/src/sources/mqtt.d.ts +18 -0
  108. package/src/sources/mqtt.js +97 -0
  109. package/src/sources/telegram.d.ts +22 -0
  110. package/src/sources/telegram.js +283 -0
  111. package/src/sources/webhook.d.ts +4 -0
  112. package/src/sources/webhook.js +52 -0
  113. package/src/sources.d.ts +344 -0
  114. package/src/sources.js +966 -0
  115. package/src/store.d.ts +99 -0
  116. package/src/store.js +277 -0
  117. package/src/timers.d.ts +83 -0
  118. package/src/timers.js +318 -0
  119. package/src/tools.d.ts +11 -0
  120. package/src/tools.js +1297 -0
  121. package/src/tui/app.d.ts +305 -0
  122. package/src/tui/app.js +3195 -0
  123. package/src/tui/client.d.ts +236 -0
  124. package/src/tui/client.js +131 -0
  125. package/src/tui/code-pane.d.ts +68 -0
  126. package/src/tui/code-pane.js +535 -0
  127. package/src/tui/highlight.d.ts +8 -0
  128. package/src/tui/highlight.js +86 -0
  129. package/src/tui/picture.d.ts +206 -0
  130. package/src/tui/picture.js +801 -0
  131. package/src/tui/run.d.ts +8 -0
  132. package/src/tui/run.js +97 -0
  133. package/src/tui/theme.d.ts +32 -0
  134. package/src/tui/theme.js +128 -0
  135. package/src/tui/undo.d.ts +5 -0
  136. package/src/tui/undo.js +50 -0
  137. package/src/tui/voice.d.ts +49 -0
  138. package/src/tui/voice.js +155 -0
  139. package/src/tui/voice.swift +223 -0
  140. package/src/types.d.ts +139 -0
  141. package/src/types.js +1 -0
  142. package/src/undo.d.ts +224 -0
  143. package/src/undo.js +465 -0
  144. package/src/update.d.ts +35 -0
  145. package/src/update.js +130 -0
  146. package/src/util.d.ts +65 -0
  147. package/src/util.js +171 -0
  148. package/src/watching.d.ts +20 -0
  149. package/src/watching.js +68 -0
  150. package/src/workspace-view.d.ts +72 -0
  151. package/src/workspace-view.js +221 -0
@@ -0,0 +1,55 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+ import { loadConfig, PINE_ROOT, WORKSPACE_FILES } from "./config.js";
4
+ import { errText } from "./util.js";
5
+ /** The built-in tools an agent can be given. */
6
+ export const AGENT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
7
+ /**
8
+ * Create an agent while the daemon runs: its folder with agent.json, and a workspace with its
9
+ * 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
10
+ * agent is checked exactly like one that was there at start; if it does not pass, the folder is
11
+ * taken away again. Nothing but these few lines goes into its agent.json.
12
+ */
13
+ /** What is wrong with a proposed agent, as an error; nothing is written. Returns the cleaned-up values. */
14
+ export function checkNewAgent(cfg, spec) {
15
+ if (!/^[a-z][a-z0-9_-]{1,30}$/.test(spec.id))
16
+ throw new Error(`"${spec.id}" is not a usable agent id: lowercase letters, digits, - and _, starting with a letter, at least two characters`);
17
+ if (cfg.agents[spec.id])
18
+ throw new Error(`an agent called ${spec.id} exists already`);
19
+ const description = spec.description.replace(/\s+/g, " ").trim();
20
+ if (!description)
21
+ throw new Error("an agent needs a description: one line on what it is for");
22
+ if (!spec.instructions.trim())
23
+ throw new Error("an agent needs instructions: who it is and how it works");
24
+ const tools = spec.tools ?? AGENT_TOOLS;
25
+ const unknown = tools.filter((t) => !AGENT_TOOLS.includes(t));
26
+ if (unknown.length)
27
+ throw new Error(`unknown tool${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}. An agent can have: ${AGENT_TOOLS.join(", ")}`);
28
+ if (fs.existsSync(path.join(cfg.home, "agents", spec.id)))
29
+ throw new Error(`the folder agents/${spec.id} exists already`);
30
+ return { description, tools };
31
+ }
32
+ export function createAgent(cfg, spec) {
33
+ const { description, tools } = checkNewAgent(cfg, spec);
34
+ const dir = path.join(cfg.home, "agents", spec.id);
35
+ fs.mkdirSync(path.join(dir, "workspace"), { recursive: true, mode: 0o700 });
36
+ try {
37
+ fs.writeFileSync(path.join(dir, "agent.json"), `${JSON.stringify({ description, ...(spec.model ? { model: spec.model } : {}), tools }, null, 2)}\n`, { mode: 0o600 });
38
+ fs.writeFileSync(path.join(dir, "workspace", "AGENTS.md"), `${spec.instructions.trim()}\n`, { mode: 0o600 });
39
+ // The rest starts as the stubs a new home has.
40
+ for (const name of WORKSPACE_FILES.slice(1)) {
41
+ const stub = path.join(PINE_ROOT, "examples", "home", "agents", "main", "workspace", name);
42
+ if (fs.existsSync(stub))
43
+ fs.copyFileSync(stub, path.join(dir, "workspace", name)), fs.chmodSync(path.join(dir, "workspace", name), 0o600);
44
+ }
45
+ const made = loadConfig(cfg.home).agents[spec.id];
46
+ if (!made)
47
+ throw new Error("the new agent was not found after writing it");
48
+ cfg.agents[spec.id] = made;
49
+ return made;
50
+ }
51
+ catch (e) {
52
+ fs.rmSync(dir, { recursive: true, force: true });
53
+ throw new Error(`the agent could not be created: ${errText(e)}`);
54
+ }
55
+ }
@@ -0,0 +1,540 @@
1
+ import { type ModelRuntime } from "@earendil-works/pi-coding-agent";
2
+ import { type AgentConfig, type Level, type McpServerConfig, type Mode, type PineConfig } from "./config.ts";
3
+ import { Limiter, type Slot } from "./limiter.ts";
4
+ import { type Approvals, type SandboxVariant } from "./security.ts";
5
+ import { type AgentChange } from "./admin.ts";
6
+ import { type NewAgent } from "./agent-admin.ts";
7
+ import type { Router } from "./router.ts";
8
+ import { Denials } from "./access.ts";
9
+ import type { Bus, Kv, State, TaskStore } from "./store.ts";
10
+ import type { SourceHost } from "./sources.ts";
11
+ import type { Scheduler } from "./timers.ts";
12
+ import { type Program, Programs } from "./programs.ts";
13
+ import { Goals } from "./goals.ts";
14
+ import { Turns, type TurnView, type UndoResult } from "./undo.ts";
15
+ import type { ContextUse, ImageRef, PineEvent, ReplyTarget, Task, TaskKind, TaskResult, Todo, TranscriptEntry, Trust } from "./types.ts";
16
+ import { type Logger } from "./util.ts";
17
+ /**
18
+ * What pine tells the bundled browser about the conversation it serves, over whatever the options
19
+ * say. Only an owner's conversation has local addresses the owner allowed, and only there may the
20
+ * browser be put on the owner's screen.
21
+ */
22
+ export declare const browserSession: (owner: boolean, localFile: string) => Record<string, unknown>;
23
+ export declare const THINKING_LEVELS: string[];
24
+ export interface SubmitOptions {
25
+ agent: string;
26
+ prompt: string;
27
+ /** Session key. Default "main". "new" runs in a fresh session that is closed afterwards. */
28
+ session?: string;
29
+ kind?: TaskKind;
30
+ priority?: number;
31
+ event?: PineEvent;
32
+ reply?: ReplyTarget;
33
+ parent?: Task;
34
+ images?: ImageRef[];
35
+ /** Files the owner hands over with the message. They are saved to inbox/ in the workspace. */
36
+ attachments?: Array<{
37
+ name: string;
38
+ data: string;
39
+ }>;
40
+ notify?: {
41
+ agent: string;
42
+ session: string;
43
+ };
44
+ whenBusy?: "queue" | "steer";
45
+ /** See TaskMeta.requeued. */
46
+ requeued?: boolean;
47
+ /** Files of the conversation's folder that the owner pointed at in the message ("src/a.ts", "src/a.ts#20-45"). */
48
+ mentions?: string[];
49
+ /** See TaskMeta.compact. */
50
+ compact?: boolean;
51
+ trust?: Trust;
52
+ tainted?: string;
53
+ leaf?: boolean;
54
+ tools?: string[];
55
+ label?: string;
56
+ /** The folder of the conversation that hands this task on (delegation). */
57
+ folder?: string;
58
+ }
59
+ /** Capabilities of one run, decided by who started it. */
60
+ export interface Profile {
61
+ tools: string[];
62
+ mcp: Record<string, McpServerConfig>;
63
+ delegates: string[];
64
+ subagents: boolean;
65
+ publish: string[];
66
+ stateWrite: boolean;
67
+ /** A sub-agent: a copy doing one job. */
68
+ leaf: boolean;
69
+ }
70
+ export interface RunContext {
71
+ task: Task;
72
+ slot: Slot;
73
+ cancelled?: boolean;
74
+ timedOut?: boolean;
75
+ }
76
+ export interface Live {
77
+ agent: AgentConfig;
78
+ key: string;
79
+ ephemeral: boolean;
80
+ trust: Trust;
81
+ runtime: any;
82
+ session: any;
83
+ current?: RunContext;
84
+ tainted?: string;
85
+ taint(reason: string): void;
86
+ /** True when the run must not change instructions or act without checks: untrusted start or tainted session. */
87
+ restricted(): boolean;
88
+ /** The mode in force for the call that is about to run (see effectiveMode). */
89
+ mode(): Mode;
90
+ /** Which sandbox the next shell or file call runs in. */
91
+ variant(): SandboxVariant;
92
+ /** Whether the next shell or file call reaches the owner's whole account: bypass mode, or an agent whose scope is the account in a conversation that may use it. */
93
+ wide(): boolean;
94
+ /**
95
+ * The conversation whose permissions apply here ("agent:session"). A sub-agent is a copy of its
96
+ * conversation doing part of that conversation's job, so it has that conversation's key: what the
97
+ * owner allowed there (access, "always" answers) holds for it, and what it is allowed holds there.
98
+ */
99
+ perm: string;
100
+ /** Access the owner granted to this conversation beyond the agent's own folders. Holds until the conversation is reset or the daemon restarts. */
101
+ grant(kind: "read" | "write" | "network", target?: string): string | undefined;
102
+ /** Take over what the conversation has been granted since this session's sandbox was written. */
103
+ syncGrants(): void;
104
+ /** Whether this session's shell can use the network right now. */
105
+ network(): boolean;
106
+ /** The folder the owner opened for this conversation, if any: where its tools start, and readable and writable for it. */
107
+ folder?: string;
108
+ sandboxed: boolean;
109
+ idleTimer?: NodeJS.Timeout;
110
+ /**
111
+ * Messages given to the running work that the model has not answered to yet (see `whenBusy:
112
+ * "steer"`). `read`: it is in the conversation; it counts as dealt with once a reply of the
113
+ * model's has come after that.
114
+ */
115
+ steering: Array<{
116
+ text: string;
117
+ read: boolean;
118
+ }>;
119
+ /** Whether the conversation's browser is a window on the owner's screen right now. Unset: as the configuration says. */
120
+ window?: boolean;
121
+ /** The mode the agent was last told it is in, to say when planning is over. */
122
+ lastMode?: Mode;
123
+ /** The last "[pine]" note this session was sent, without its time. A new one goes out when this changes. */
124
+ noteKey?: string;
125
+ /** The configuration changed under this session; close it when it is idle so the next task starts it anew. */
126
+ stale?: boolean;
127
+ contextStamp: string;
128
+ lastUsed: number;
129
+ }
130
+ export interface AgentManagerDeps {
131
+ cfg: PineConfig;
132
+ bus: Bus;
133
+ state: State;
134
+ kv: Kv;
135
+ tasks: TaskStore;
136
+ approvals: Approvals;
137
+ log: Logger;
138
+ }
139
+ export declare class AgentManager {
140
+ cfg: PineConfig;
141
+ bus: Bus;
142
+ state: State;
143
+ kv: Kv;
144
+ tasks: TaskStore;
145
+ approvals: Approvals;
146
+ limiter: Limiter;
147
+ private log;
148
+ /** Event sources and subscriptions. Set by the daemon once both exist. */
149
+ sources?: SourceHost;
150
+ /** Set by pine.ts. Routes of pine.json that are added or removed while the daemon runs go through it. */
151
+ router?: Router;
152
+ /** Set by the daemon once the scheduler exists. */
153
+ schedules?: Scheduler;
154
+ private modelRuntime;
155
+ private lives;
156
+ private creating;
157
+ private lanes;
158
+ private running;
159
+ private waiters;
160
+ private taints;
161
+ private stopping;
162
+ private warnedNoSandbox;
163
+ /** Conversations ("agent:session") where the owner chose bypass although they have read outside content. */
164
+ private bypassAnyway;
165
+ /**
166
+ * What the owner allowed "always" in a conversation ("agent:session" -> "server:<name>" or
167
+ * "tool:<name>"), with the state the conversation was in. A yes given before the conversation
168
+ * read outside content does not cover it afterwards. Gone with a reset or a restart.
169
+ */
170
+ private allowed;
171
+ /**
172
+ * Access granted to a conversation with request_access, by the same key. Its sub-agents share it.
173
+ * `local` is what the owner allowed the bundled browser to open on this computer or the local
174
+ * network ("host:port"), `apps` the apps it allowed the agent to operate (see appTarget).
175
+ */
176
+ private grants;
177
+ /**
178
+ * Download links that a conversation was given by its own remote MCP servers: address, and the
179
+ * server whose tool returned it. Only such a link is fetched with that server's headers (its
180
+ * key), see the download tool. Kept by the conversation's key, so its sub-agents share it.
181
+ */
182
+ private handed;
183
+ /**
184
+ * What the owner said no to when a conversation needed something beyond its sandbox
185
+ * ("read:/path", "network:"): it is not asked again there. Gone with a reset or a restart.
186
+ */
187
+ private refused;
188
+ /** The mode each conversation was last told it is in, so that leaving plan mode is said also by a session that was made anew. */
189
+ private toldMode;
190
+ /** Folders of the owner's home that a conversation was told its shell's ~ does not mean. Written with ~ again, its own home is meant. */
191
+ private toldHome;
192
+ /** The system's reports of what a sandbox refused a command (src/access.ts). A test puts a stand-in here. */
193
+ denials: Denials;
194
+ /** What the commands of each conversation left running. */
195
+ readonly programs: Programs;
196
+ /** Goal mode: what the owner wants a conversation to reach, and the rounds until a judge says it is (src/goals.ts). */
197
+ readonly goals: Goals;
198
+ /** Conversations that are being told right now that background commands have ended. */
199
+ private tellingEnded;
200
+ /** The states of the folders conversations work in, and the owner's messages they belong to: what undo goes back to. */
201
+ private snapshots;
202
+ readonly turns: Turns;
203
+ /** Questions about a conversation that are open right now, by what they are about. */
204
+ private asking;
205
+ /**
206
+ * One question at a time about one thing. A model issues tool calls side by side; the ones
207
+ * that arrive while the question is open wait for its answer instead of asking it again.
208
+ */
209
+ private askOnce;
210
+ constructor(deps: AgentManagerDeps);
211
+ /** The programs a conversation's commands left running (a development server, a watcher). */
212
+ programsOf(agentId: string, session: string): Program[];
213
+ /** Stop one of them. Only the owner's side calls this (the control API), and the agent for its own conversation. */
214
+ stopProgram(agentId: string, session: string, id: number): boolean;
215
+ /**
216
+ * Start a shell command of a conversation in the background: in the sandbox that its other
217
+ * commands run in (`prefix`), with its output in a file in the agent's own temp folder. The
218
+ * conversation is told when it has ended (`tellEnded`).
219
+ */
220
+ private startBackground;
221
+ /**
222
+ * Tell a conversation that background commands of its own have ended: one message for all
223
+ * that ended until now, and only while it is not at work (it is called again when the
224
+ * conversation has nothing left to do). The message is pine's and says so. What the commands
225
+ * printed is quoted in it as output, and it is no message of the owner's.
226
+ */
227
+ private tellEnded;
228
+ init(): Promise<void>;
229
+ /** Read models.json again: a model server was added or removed. Conversations use it from their next start, which a change of model is. */
230
+ reloadModels(): Promise<void>;
231
+ get models(): ModelRuntime;
232
+ modelFor(agent: AgentConfig): any;
233
+ resolveModel(ref: string): any;
234
+ /** Models that have credentials (or need none), as "provider/id". */
235
+ availableModels(): Promise<string[]>;
236
+ /**
237
+ * Switch an agent to another model and save the choice in its agent.json, so it is still the
238
+ * agent's model after a restart. Sessions pick it up with their next task and keep their history.
239
+ */
240
+ setModel(agentId: string, ref: string): Promise<void>;
241
+ submit(o: SubmitOptions): Task;
242
+ /** Write attached files into <workspace>/inbox and say which of them are images. */
243
+ private saveAttachments;
244
+ wait(id: number): Promise<TaskResult>;
245
+ /** Submit and wait. */
246
+ run(o: SubmitOptions): Promise<TaskResult>;
247
+ /** Wait for child tasks while lending this run's model slot to them. Aborting cancels the children. */
248
+ awaitChildren(run: RunContext, ids: number[], signal?: AbortSignal): Promise<TaskResult[]>;
249
+ cancel(id: number): boolean;
250
+ /**
251
+ * What a task did, step by step, read from the session file pi keeps for it: the text it was
252
+ * given, what it wrote and thought, and every tool call with the start of its result. This is how
253
+ * a sub-agent's work can be looked at, during the run and afterwards; its session folder
254
+ * (sessions/_tasks/<task id>) stays on disk. For a task in a named session, only that task's part
255
+ * of the conversation is returned.
256
+ */
257
+ /** The folder a UI shows beside a conversation: the one opened for it, else the agent's workspace. */
258
+ viewRoot(agentId: string, session: string): string | undefined;
259
+ /** What a task did, step by step. `full` keeps each tool's whole output (for reading it), not just its start. */
260
+ transcript(id: number, full?: boolean): {
261
+ task: Task;
262
+ entries: TranscriptEntry[];
263
+ } | undefined;
264
+ /** Save the pictures in a tool result under data/media/tool, so a UI can fetch them by id. */
265
+ private keepToolImages;
266
+ /** A picture a tool returned (see keepToolImages). */
267
+ toolImage(id: string): Picture | undefined;
268
+ /** The n-th picture that came with a task: an attachment, or an image an adapter passed along. */
269
+ taskImage(taskId: number, n: number): Picture | undefined;
270
+ /**
271
+ * A picture, video or sound in an agent's workspace, which the agent refers to in an answer. Only real
272
+ * image, video and sound files inside the workspace are served: the path comes from model output, and this endpoint
273
+ * must not become a way to read other files.
274
+ */
275
+ workspaceImage(agentId: string, file: string, session?: string): Picture | undefined;
276
+ /** A picture at a web address, fetched because the owner asked for it. Https and public addresses only. */
277
+ fetchImage(url: string): Promise<Picture | undefined>;
278
+ /** Remove kept tool pictures that are older than the event log reaches back. */
279
+ pruneMedia(olderThanMs: number): void;
280
+ status(): {
281
+ limiter: {
282
+ active: number;
283
+ waiting: number;
284
+ max: number;
285
+ };
286
+ running: {
287
+ task: number;
288
+ agent: string;
289
+ session: string;
290
+ kind: TaskKind;
291
+ }[];
292
+ sessions: {
293
+ agent: string;
294
+ session: string;
295
+ busy: boolean;
296
+ tainted: string | undefined;
297
+ trust: Trust;
298
+ mode: Mode;
299
+ context: ContextUse | undefined;
300
+ }[];
301
+ modes: {
302
+ [k: string]: Mode;
303
+ };
304
+ };
305
+ /** Forget a session's history (and its taint). The next task with this key starts fresh. */
306
+ resetSession(agentId: string, session?: string): Promise<boolean>;
307
+ undo(agentId: string, session?: string): Promise<UndoResult>;
308
+ /** Bring back what the last undo took, as long as nothing new was said in the conversation. */
309
+ redo(agentId: string, session?: string): Promise<UndoResult>;
310
+ /** What the owner's last message in a conversation changed in its folder, for a UI to show. */
311
+ lastTurn(agentId: string, session: string): Promise<TurnView>;
312
+ lastTurnDiff(agentId: string, session: string, file: string): Promise<{
313
+ diff: string;
314
+ truncated: boolean;
315
+ } | undefined>;
316
+ private undoHost;
317
+ /**
318
+ * Do something to a conversation while nothing runs in it: after what is running there now,
319
+ * before anything that is sent later, and with its session closed, so that the session file
320
+ * can be changed and is read anew by the next message.
321
+ */
322
+ private quiet;
323
+ /**
324
+ * What a conversation may do without asking, as far as this process holds it: a copy. Taken
325
+ * before each message of the owner's; when the message is taken back, what the owner allowed
326
+ * while it was worked on is taken back with it (`setRights`), as a reset takes back all of it.
327
+ */
328
+ private rightsOf;
329
+ /** Put back what `rightsOf` returned. Without it (the daemon was restarted since): as after a restart, nothing. */
330
+ private setRights;
331
+ folderOf(agentId: string, session: string): string | undefined;
332
+ /** Every conversation of an agent that has a folder, also one nothing was said in yet. */
333
+ folders(agentId: string): Array<{
334
+ session: string;
335
+ folder: string;
336
+ }>;
337
+ /** Why a folder cannot be opened for an agent, or undefined when it can. */
338
+ private folderProblem;
339
+ /** Open a folder for a conversation, or with `null` go back to the agent's own workspace. Takes effect with its next message. */
340
+ setFolder(agentId: string, session: string, wanted: string | null): Promise<{
341
+ folder?: string;
342
+ }>;
343
+ /** The session keys a conversation's name stands for: its own and the one outside content is handled in. */
344
+ private keysOf;
345
+ private pinned;
346
+ /** The tabs a UI had open, to open them again, and so that an open conversation is not removed. */
347
+ uiTabs(): {
348
+ tabs: Array<{
349
+ agent: string;
350
+ session: string;
351
+ }>;
352
+ active: number;
353
+ code: boolean;
354
+ notify: boolean;
355
+ };
356
+ /** `code`: whether the pane beside the conversation was open. `notify`: whether the UI calls for attention. Left as they were when not given. */
357
+ saveUiTabs(tabs: unknown, active: unknown, code?: unknown, notify?: unknown): void;
358
+ /**
359
+ * An agent's conversations: pinned ones first, then the most recently used. `expires` is when
360
+ * one is removed by itself if nothing more is said in it; one without it stays.
361
+ */
362
+ conversations(agentId: string): Array<{
363
+ session: string;
364
+ tasks: number;
365
+ last: number;
366
+ pinned: boolean;
367
+ open: boolean;
368
+ expires?: number;
369
+ folder?: string;
370
+ }>;
371
+ /** Pin a conversation, so that it stays however long it is not used, or take the pin off. */
372
+ pinSession(agentId: string, session: string, on: boolean): boolean;
373
+ /** Remove a conversation for good: what was said in it, what it may do without asking, what it listens to. */
374
+ removeSession(agentId: string, session: string): Promise<{
375
+ removed: boolean;
376
+ unsubscribed: string[];
377
+ sources: string[];
378
+ servers: string[];
379
+ }>;
380
+ /** Make an agent while the daemon runs (the create_agent tool and `pine agent add` both end here). */
381
+ addAgent(spec: NewAgent): Promise<AgentConfig>;
382
+ /**
383
+ * Change an agent's settings (`pine agent update`, as the update_agent tool does it): the change
384
+ * is checked, written, and the configuration is read back; if it does not load, the file is as it
385
+ * was. Sessions take it on with their next task. When the delegates change, every agent's roster
386
+ * is refreshed, not just this one's.
387
+ */
388
+ updateAgent(agentId: string, change: AgentChange): Promise<{
389
+ lines: string[];
390
+ warnings: string[];
391
+ }>;
392
+ /** What an agent has, for telling the owner what goes with it. */
393
+ holdings(agentId: string): {
394
+ conversations: string[];
395
+ sources: string[];
396
+ servers: string[];
397
+ schedules: string[];
398
+ skills: string[];
399
+ files: number;
400
+ outside: boolean;
401
+ working: boolean;
402
+ };
403
+ /**
404
+ * Take an agent out of pine: its work is stopped, each of its conversations goes the way a
405
+ * conversation goes, what it watched and had scheduled ends, and then everything that is left
406
+ * of it is erased (`eraseAgent`): the routes that wake it, its name in the lists of others,
407
+ * what is stored under its name, its private home and its folder (or, with `keepFiles`, the
408
+ * folder is moved to `removed/` in pine's home, where nothing reads it). Only the owner's yes
409
+ * leads here: the tool and the command ask first.
410
+ */
411
+ removeAgent(agentId: string, keepFiles?: boolean): Promise<{
412
+ unsubscribed: string[];
413
+ routes: string[];
414
+ kept?: string;
415
+ workspaceLeft?: string;
416
+ problem?: string;
417
+ }>;
418
+ /** Give a conversation another name. Everything stays with it: its history, its pin, what it listens to. */
419
+ renameSession(agentId: string, from: string, wanted: string): Promise<{
420
+ session: string;
421
+ }>;
422
+ /**
423
+ * The daily tidying: conversations that have reached their time, and the copies kept of reset
424
+ * conversations once they are older than the event log reaches back.
425
+ */
426
+ pruneConversations(): Promise<number>;
427
+ stop(): Promise<void>;
428
+ private enqueue;
429
+ private execute;
430
+ private causeOf;
431
+ private resultOf;
432
+ private finish;
433
+ profileFor(agent: AgentConfig, trust: Trust, task?: Task): Profile;
434
+ /** What pine tells the app control server of a session, or undefined where the session does not get it (see computerSession). */
435
+ private computerFor;
436
+ private live;
437
+ private createLive;
438
+ /** The session whose permissions a task runs under: its own, or for a sub-agent the one that started it. */
439
+ private permSession;
440
+ /** Everything pine itself adds to a session: MCP servers, the sandboxed shell, the policy gate, and context. */
441
+ /**
442
+ * The level that applies right now: what decides the sandbox and how much is asked. A run
443
+ * started by an outside event is held to "safe" (in the sandbox, never asked, never bypass),
444
+ * and bypass is suspended in a session that has read outside content unless the configuration
445
+ * says otherwise: those are the two situations in which someone else may be steering.
446
+ */
447
+ effectiveLevel(agent: AgentConfig, live: Pick<Live, "trust" | "tainted" | "key"> & {
448
+ perm?: string;
449
+ }): Level;
450
+ /** The mode that applies right now: "plan" where the agent plans (also in a run from outside), else its level. */
451
+ effectiveMode(agent: AgentConfig, live: Pick<Live, "trust" | "tainted" | "key"> & {
452
+ perm?: string;
453
+ }): Mode;
454
+ /**
455
+ * Set how much an agent's model reasons before it answers, and save it in agent.json. Applies
456
+ * from the next model call. A model that cannot reason ignores it; pi lowers a level the model
457
+ * does not offer to the nearest one it does.
458
+ */
459
+ setThinking(agentId: string, level: string): void;
460
+ /**
461
+ * Tools or servers of some agents changed. Idle sessions are closed now and busy ones when their
462
+ * task ends; each continues from its history with the new set when it is next used.
463
+ */
464
+ refreshSessions(agentIds?: string[]): Promise<void>;
465
+ /**
466
+ * Change an agent's mode. Takes effect on its next tool call. "auto", "safe" and "manual"
467
+ * are written into its agent.json and are there after a restart. "bypass" and "plan" hold
468
+ * until the daemon restarts: an agent does not come back up asking nothing, or doing nothing,
469
+ * because of a click a week ago. `anyway` names a conversation in which the owner, knowing
470
+ * it has read outside content, wants bypass to apply all the same.
471
+ */
472
+ setMode(agentId: string, mode: Mode, anyway?: string): void;
473
+ /**
474
+ * Where the guard of the bundled browser reads which local addresses a conversation may open.
475
+ * The guard is another process, so a yes reaches it through this file. It lies in pine's home,
476
+ * which no agent can write.
477
+ */
478
+ private localFile;
479
+ /** The owner allowed the browser of a conversation to open one local address ("host:port"). */
480
+ private allowLocal;
481
+ /** The owner allowed a conversation to operate one app (or to look at the whole screen). */
482
+ private allowApp;
483
+ /** The list an agent keeps of the steps of what it is doing in a conversation. */
484
+ todosOf(agentId: string, session: string): Todo[];
485
+ private todos;
486
+ /** The agent's `todo` tool: the whole list each time. The owner's UI is told. */
487
+ setTodos(live: Live, task: Task, items: Todo[]): Todo[];
488
+ /** The owner said no to this for a conversation: it is not asked again there. */
489
+ private refuse;
490
+ /** Forget what a conversation was granted. */
491
+ private dropGrants;
492
+ private coreExtension;
493
+ /**
494
+ * Can this agent move information out of the machine: web or remote MCP tools, or a shell with
495
+ * network? A tainted session that hands such an agent a task could be leaking through it.
496
+ */
497
+ canSendOut(agentId: string): boolean;
498
+ /**
499
+ * The part of the system prompt that pine adds. Everything here is fixed for the life of a
500
+ * session. A model server reuses its work only for a prompt whose beginning is unchanged, and
501
+ * the system prompt is the very beginning: one changing word here would make a local model
502
+ * read the whole conversation again on every turn. What changes goes into contextNote().
503
+ */
504
+ private contextBlock;
505
+ /**
506
+ * What is true right now: the time, the mode, trust, shared state. It is put in front of the
507
+ * incoming message, at the end of the conversation, and only when something other than the
508
+ * clock has changed since the last note, so the conversation so far stays byte for byte what
509
+ * the model server has already seen. `key` is the note without the time.
510
+ */
511
+ private contextNote;
512
+ /**
513
+ * An agent's model as its owner knows it: "provider/id", and the name models.json gives it.
514
+ * A name can come from what a model server said about itself, so only plain characters of it
515
+ * reach the note.
516
+ */
517
+ private modelName;
518
+ /** The MCP servers of the conversation a session belongs to. */
519
+ private serversOf;
520
+ /** Shorten a conversation: its earlier part becomes a summary. Queued like a message; the owner's to ask for. */
521
+ compact(agentId: string, session?: string): Task;
522
+ /** The name a tool has in pine's bundled browser ("browser_show"), whatever the server is called in the configuration. */
523
+ private browserTool;
524
+ private sizeOf;
525
+ /**
526
+ * The files that make up an agent's instructions, in the order they enter its prompt; those
527
+ * that exist. First what the owner alone can change, then what the agent keeps itself, the
528
+ * one that changes most often last.
529
+ */
530
+ private instructionFiles;
531
+ private stamp;
532
+ /** pi reads instruction files once per session; pick up edits made since. */
533
+ private refresh;
534
+ private armIdle;
535
+ private dispose;
536
+ }
537
+ export interface Picture {
538
+ mime: string;
539
+ bytes: Buffer;
540
+ }