@pmndre/pine 0.22.0 → 0.33.0

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 (99) hide show
  1. package/README.md +2 -1
  2. package/changes.json +265 -0
  3. package/docs/SKILL.md +31 -7
  4. package/docs/references/agents.md +245 -21
  5. package/docs/references/coding.md +1 -1
  6. package/docs/references/computer.md +1 -1
  7. package/docs/references/configuration.md +14 -5
  8. package/docs/references/mcp.md +9 -0
  9. package/docs/references/operations.md +20 -9
  10. package/docs/references/overview.md +3 -1
  11. package/docs/references/security.md +83 -24
  12. package/docs/references/setup.md +55 -9
  13. package/docs/references/source-types.md +1418 -0
  14. package/docs/references/sources.md +333 -19
  15. package/docs/references/stack.md +1 -0
  16. package/docs/references/tui.md +86 -12
  17. package/examples/home/AGENTS.md +4 -0
  18. package/examples/home/TOOLS.md +5 -0
  19. package/examples/home/agents/main/workspace/AGENTS.md +1 -1
  20. package/examples/home/agents/main/workspace/TOOLS.md +5 -0
  21. package/mcp/browser.d.ts +6 -0
  22. package/mcp/browser.js +19 -0
  23. package/mcp/render.d.ts +1 -0
  24. package/mcp/render.js +237 -0
  25. package/package.json +3 -1
  26. package/src/actions.d.ts +6 -1
  27. package/src/actions.js +17 -4
  28. package/src/admin.d.ts +4 -0
  29. package/src/admin.js +25 -6
  30. package/src/agents.d.ts +167 -2
  31. package/src/agents.js +912 -45
  32. package/src/catalogue.d.ts +60 -0
  33. package/src/catalogue.js +791 -0
  34. package/src/cli.js +10 -7
  35. package/src/config.d.ts +53 -4
  36. package/src/config.js +30 -5
  37. package/src/goals.d.ts +1 -1
  38. package/src/goals.js +14 -1
  39. package/src/manual.js +24 -2
  40. package/src/mime.d.ts +78 -0
  41. package/src/mime.js +342 -0
  42. package/src/net.d.ts +11 -0
  43. package/src/net.js +29 -2
  44. package/src/pine.js +10 -1
  45. package/src/router.js +3 -3
  46. package/src/sandbox-linux.d.ts +3 -1
  47. package/src/sandbox-linux.js +5 -0
  48. package/src/security.d.ts +22 -6
  49. package/src/security.js +44 -13
  50. package/src/slots.d.ts +106 -0
  51. package/src/slots.js +250 -0
  52. package/src/source-types.d.ts +20 -0
  53. package/src/sources/calendar.d.ts +24 -0
  54. package/src/sources/calendar.js +265 -0
  55. package/src/sources/command.js +109 -4
  56. package/src/sources/discord.d.ts +4 -0
  57. package/src/sources/discord.js +298 -0
  58. package/src/sources/feed.d.ts +19 -0
  59. package/src/sources/feed.js +257 -0
  60. package/src/sources/http.js +154 -103
  61. package/src/sources/mail.d.ts +51 -0
  62. package/src/sources/mail.js +1013 -0
  63. package/src/sources/matrix.d.ts +4 -0
  64. package/src/sources/matrix.js +232 -0
  65. package/src/sources/modbus.d.ts +15 -0
  66. package/src/sources/modbus.js +240 -0
  67. package/src/sources/onvif.d.ts +35 -0
  68. package/src/sources/onvif.js +326 -0
  69. package/src/sources/presence.d.ts +80 -0
  70. package/src/sources/presence.js +480 -0
  71. package/src/sources/serial.d.ts +21 -0
  72. package/src/sources/serial.js +220 -0
  73. package/src/sources/slack.d.ts +16 -0
  74. package/src/sources/slack.js +1062 -0
  75. package/src/sources/smtp.d.ts +4 -0
  76. package/src/sources/smtp.js +360 -0
  77. package/src/sources/stream.d.ts +68 -0
  78. package/src/sources/stream.js +534 -0
  79. package/src/sources/syslog.d.ts +32 -0
  80. package/src/sources/syslog.js +243 -0
  81. package/src/sources/system.d.ts +14 -0
  82. package/src/sources/system.js +236 -0
  83. package/src/sources/system.swift +102 -0
  84. package/src/sources/telegram.js +34 -1
  85. package/src/sources.d.ts +41 -1
  86. package/src/sources.js +147 -24
  87. package/src/tools.d.ts +1 -1
  88. package/src/tools.js +304 -23
  89. package/src/tui/app.d.ts +35 -2
  90. package/src/tui/app.js +306 -43
  91. package/src/tui/levels.d.ts +68 -0
  92. package/src/tui/levels.js +273 -0
  93. package/src/tui/picture.d.ts +17 -1
  94. package/src/tui/picture.js +72 -5
  95. package/src/types.d.ts +3 -0
  96. package/src/update.d.ts +9 -1
  97. package/src/update.js +75 -3
  98. package/src/watching.d.ts +156 -0
  99. package/src/watching.js +609 -4
package/src/admin.js CHANGED
@@ -7,7 +7,7 @@ import fs from "node:fs";
7
7
  import os from "node:os";
8
8
  import path from "node:path";
9
9
  import { AGENT_TOOLS } from "./agent-admin.js";
10
- import { loadConfig, mainAgentId, MODES, PINE_ROOT, RESERVED_TOPICS, unsandboxed } from "./config.js";
10
+ import { loadConfig, mainAgentId, MODES, PINE_ROOT, RESERVED_TOPICS, unsandboxed, CATALOGUES } from "./config.js";
11
11
  import { unsetEnv } from "./env-file.js";
12
12
  import { editJson } from "./mcp-config.js";
13
13
  import { isInside, realish } from "./security.js";
@@ -150,9 +150,13 @@ export function checkAgentChange(cfg, agent, change, models) {
150
150
  throw new Error("soul cannot be empty: it is who the agent is, its character and tone");
151
151
  lines.push(`character and tone (its SOUL.md) replaced by:\n${soul.length > 1200 ? `${soul.slice(0, 1200)}...` : soul}`);
152
152
  }
153
+ // Its own tooling can be empty: then only what holds for all agents holds for it.
154
+ const tooling = change.tooling?.trim();
155
+ if (tooling !== undefined)
156
+ lines.push(tooling ? `its own defaults and preferences for tools (its TOOLS.md) replaced by:\n${tooling.length > 1200 ? `${tooling.slice(0, 1200)}...` : tooling}` : "its own defaults and preferences for tools (its TOOLS.md) taken back: the file is emptied");
153
157
  if (!lines.length)
154
- throw new Error("nothing to change: give at least one of description, instructions, soul, model, thinking, mode, tools, delegates, network, read, write, forget");
155
- return { lines, warnings, json: (raw) => steps.forEach((s) => s(raw)), instructions, soul };
158
+ throw new Error("nothing to change: give at least one of description, instructions, soul, tooling, model, thinking, mode, tools, delegates, network, read, write, forget");
159
+ return { lines, warnings, json: (raw) => steps.forEach((s) => s(raw)), instructions, soul, tooling };
156
160
  }
157
161
  /**
158
162
  * Write a checked change and take it over. The agent's file is read back through the loader
@@ -176,12 +180,12 @@ export function applyAgentChange(cfg, agent, checked) {
176
180
  }
177
181
  // The workspace is the agent's to write. A file of that name is taken away and a new one
178
182
  // made, never written through: what lies there could be a link to somewhere else.
179
- for (const [name, text] of [["AGENTS.md", checked.instructions], ["SOUL.md", checked.soul]]) {
183
+ for (const [name, text] of [["AGENTS.md", checked.instructions], ["SOUL.md", checked.soul], ["TOOLS.md", checked.tooling]]) {
180
184
  if (text === undefined)
181
185
  continue;
182
186
  const target = path.join(agent.workspace, name);
183
187
  fs.rmSync(target, { force: true });
184
- fs.writeFileSync(target, `${text}\n`, { mode: 0o600, flag: "wx" });
188
+ fs.writeFileSync(target, text ? `${text}\n` : "", { mode: 0o600, flag: "wx" });
185
189
  }
186
190
  }
187
191
  /** The parts of the configuration that name an agent and stand in the way of removing it, or are corrected when it goes. */
@@ -250,8 +254,15 @@ export function eraseAgent(cfg, store, id, keepFiles = false) {
250
254
  for (const name of routes)
251
255
  dropRoute(cfg, name);
252
256
  unname(cfg, id);
253
- for (const prefix of ["taint", "keep", "folder", "todos", "turns", "undone"])
257
+ for (const prefix of ["taint", "keep", "folder", "todos", "turns", "undone", "prefix", "note"])
254
258
  store.kv.forget(`${prefix}:${id}:`);
259
+ // Which slot of a model server held one of its conversations (src/slots.ts).
260
+ const slots = store.kv.get("slots");
261
+ if (slots)
262
+ store.kv.set("slots", Object.fromEntries(Object.entries(slots).map(([server, held]) => [server, held.map((o) => (o && String(o.who).startsWith(`${id}:`) ? null : o))])));
263
+ const pages = store.kv.get("slot-pages");
264
+ if (pages)
265
+ store.kv.set("slot-pages", Object.fromEntries(Object.entries(pages).map(([server, kept]) => [server, kept.map((o) => (o && String(o.who).startsWith(`${id}:`) ? null : o))])));
255
266
  for (const key of store.kv.keys("timer:"))
256
267
  if (key.endsWith(`@${id}`))
257
268
  store.kv.set(key, null);
@@ -504,6 +515,12 @@ const ms = (n) => (n % 60_000 === 0 ? `${n / 60_000}m` : n % 1000 === 0 ? `${n /
504
515
  export const SETTINGS = {
505
516
  "defaults.model": { about: "The model of every agent that has none of its own, as provider/model.", kind: "model", now: (c) => String(c.defaults.model ?? "none"), live: true },
506
517
  "defaults.thinking": { about: "How much an agent reasons before it answers, unless it says otherwise.", kind: { one: THINKING }, now: (c) => c.defaults.thinking, live: true },
518
+ "defaults.catalogue": {
519
+ about: "How an agent's tools are declared to the model, unless the agent says otherwise: families (a group of tools is one declared tool, requests are short and a model server keeps what it has read) or full (every tool by itself with its whole description, as before).",
520
+ kind: { one: [...CATALOGUES] },
521
+ now: (c) => c.defaults.catalogue,
522
+ live: false,
523
+ },
507
524
  "defaults.mode": {
508
525
  about: "The mode of every agent that names none: auto (no sandbox: your whole account and the network; critical actions are checked), safe (in the sandbox: its own folders), manual (in the sandbox, every action waits), bypass (no sandbox, nothing waits), plan (nothing is done). Not set: auto for the main agent, safe for the others.",
509
526
  kind: { one: [...MODES] },
@@ -517,6 +534,8 @@ export const SETTINGS = {
517
534
  "limits.maxDelegationDepth": { about: "How many times a task can be handed on from agent to agent.", kind: { from: 0, to: 10 }, now: (c) => String(c.limits.maxDelegationDepth), live: true },
518
535
  "limits.maxDownloadMb": { about: "The largest file the download tool fetches, in megabytes.", kind: { from: 1, to: 100_000 }, now: (c) => String(c.limits.maxDownloadMb), live: true },
519
536
  "defaults.judge": { about: "The model that judges whether a goal is met, as provider/model. Not set: the agent's own.", kind: "model", now: (c) => c.defaults.judge ?? "not set (the agent's own model)", live: true },
537
+ "limits.slotPages": { about: "How many conversations that had to leave their slot on a llama.cpp model server are kept in files there and read back when they come again, instead of being read from their first word. Needs a server started with --slot-save-path. 0 turns it off.", kind: { from: 0, to: 64 }, now: (c) => String(c.limits.slotPages), live: true },
538
+ "limits.warmSlots": { about: "Whether pine has the idle slots of a llama.cpp model server read the beginning that all conversations of an agent share, in the background after you have used the model, so that a new conversation or a sub-agent starts at once.", kind: "boolean", now: (c) => String(c.limits.warmSlots), live: true },
520
539
  "security.askAccess": { about: "Whether pine asks your owner itself when a call of an agent needs a file or folder outside its sandbox, or the network.", kind: "boolean", now: (c) => String(c.security.askAccess), live: true },
521
540
  "security.approvalTimeout": { about: "How long a question to your owner waits before it counts as not answered, for example 5m.", kind: "duration", now: (c) => ms(c.security.approvalTimeoutMs), live: false },
522
541
  "security.taint": {
package/src/agents.d.ts CHANGED
@@ -52,6 +52,9 @@ export interface SubmitOptions {
52
52
  tainted?: string;
53
53
  leaf?: boolean;
54
54
  tools?: string[];
55
+ /** See TaskMeta.model: for a sub-agent only. */
56
+ model?: string;
57
+ thinking?: string;
55
58
  label?: string;
56
59
  /** The folder of the conversation that hands this task on (delegation). */
57
60
  folder?: string;
@@ -122,6 +125,26 @@ export interface Live {
122
125
  lastMode?: Mode;
123
126
  /** The last "[pine]" note this session was sent, without its time. A new one goes out when this changes. */
124
127
  noteKey?: string;
128
+ /** The llama.cpp slot the model call that is under way was given (src/slots.ts). */
129
+ slot?: {
130
+ server: string;
131
+ slot: number;
132
+ who: string;
133
+ held: number;
134
+ };
135
+ /** The model server this session's requests go to ("origin|model"), once one has gone out. */
136
+ server?: string;
137
+ /** Tokens of this session's last request, when it went out without a slot named: where the server put it is found by this. */
138
+ loose?: number;
139
+ /** A name for a session that is no conversation (a sub-agent), for the slot book. */
140
+ uid?: string;
141
+ /** The session is a sub-agent's. */
142
+ leaf?: boolean;
143
+ /** A sub-agent's own model ("provider/id") and reasoning level, where the conversation that started it chose them. Not set: the agent's. */
144
+ model?: string;
145
+ thinking?: string;
146
+ /** Tools this session answers for although it does not declare them: the families, and what a sub-agent has in name only. */
147
+ answers?: Set<string>;
125
148
  /** The configuration changed under this session; close it when it is idle so the next task starts it anew. */
126
149
  stale?: boolean;
127
150
  contextStamp: string;
@@ -144,6 +167,22 @@ export declare class AgentManager {
144
167
  tasks: TaskStore;
145
168
  approvals: Approvals;
146
169
  limiter: Limiter;
170
+ /** Which slot of a llama.cpp server each conversation's requests go to. */
171
+ private slots;
172
+ private askingSlots;
173
+ /** What a conversation declares to the model and tells it first, by conversation ("agent:conversation"): what its sub-agents are given too (steady()). */
174
+ private declared;
175
+ private askedSlots;
176
+ /** What a conversation of the agent that used a model server last begins with: what its idle slots are filled with. By server. */
177
+ private warmWith;
178
+ private warmTimers;
179
+ /** Whether a model server writes slots to files and reads them back: not known until it was tried. By server. */
180
+ private paging;
181
+ /** When a model server was last asked what its slots hold, and whether it answers that at all. By server. */
182
+ private slotsSeenAt;
183
+ private slotsTold;
184
+ /** How the key of a model server is had, from the session that used it last. By server. */
185
+ private serverKeys;
147
186
  private log;
148
187
  /** Event sources and subscriptions. Set by the daemon once both exist. */
149
188
  sources?: SourceHost;
@@ -230,6 +269,8 @@ export declare class AgentManager {
230
269
  reloadModels(): Promise<void>;
231
270
  get models(): ModelRuntime;
232
271
  modelFor(agent: AgentConfig): any;
272
+ /** The model a session runs on: its agent's, or the one a sub-agent was given. */
273
+ private modelOf;
233
274
  resolveModel(ref: string): any;
234
275
  /** Models that have credentials (or need none), as "provider/id". */
235
276
  availableModels(): Promise<string[]>;
@@ -365,11 +406,49 @@ export declare class AgentManager {
365
406
  last: number;
366
407
  pinned: boolean;
367
408
  open: boolean;
409
+ working: boolean;
410
+ outside?: string;
368
411
  expires?: number;
369
412
  folder?: string;
370
413
  }>;
371
414
  /** Pin a conversation, so that it stays however long it is not used, or take the pin off. */
372
415
  pinSession(agentId: string, session: string, on: boolean): boolean;
416
+ /** A conversation's name as pine keeps it ("My notes" is "My_notes"; the one outside content is handled in ends in "~u"). */
417
+ conversationKey(name: string): string;
418
+ /** Why a conversation counts as holding outside content, if it does. */
419
+ outsideMark(agentId: string, session: string): string | undefined;
420
+ /**
421
+ * What was said in a conversation, for the main agent's read_conversation: each message it was
422
+ * given and each answer, numbered from the first, the last ones returned. Of an answer's tool
423
+ * calls only which tool and on what: what a tool returned is the other agent's own (its files,
424
+ * the pages it read) and is not handed on by this road.
425
+ */
426
+ said(agentId: string, name: string, last?: number, before?: number): {
427
+ session: string;
428
+ total: number;
429
+ entries: Array<{
430
+ n: number;
431
+ kind: "message" | "answer";
432
+ text: string;
433
+ tools: string[];
434
+ }>;
435
+ outside?: string;
436
+ };
437
+ /**
438
+ * Tell a UI that is running that a conversation was changed by another hand than its own (the
439
+ * main agent's tools), so that its tabs follow. Nothing is kept of it: what is kept is the list
440
+ * of tabs, which a UI that starts later opens.
441
+ */
442
+ conversationChanged(change: "open" | "close" | "rename" | "remove" | "pin", agentId: string, session: string, to?: string): void;
443
+ /**
444
+ * Open a tab on a conversation, or close its tab, for the main agent's set_conversation: the
445
+ * list of tabs a UI opens with is changed, and a UI that is running follows. Closing does what
446
+ * closing it in the UI does: what the conversation was subscribed to on its own ends.
447
+ */
448
+ showTab(agentId: string, name: string, open: boolean): Promise<{
449
+ changed: boolean;
450
+ unsubscribed: string[];
451
+ }>;
373
452
  /** Remove a conversation for good: what was said in it, what it may do without asking, what it listens to. */
374
453
  removeSession(agentId: string, session: string): Promise<{
375
454
  removed: boolean;
@@ -509,6 +588,91 @@ export declare class AgentManager {
509
588
  * the model server has already seen. `key` is the note without the time.
510
589
  */
511
590
  private contextNote;
591
+ /**
592
+ * The request as a model server can keep the most of.
593
+ *
594
+ * A server keeps what it has read only while a request begins with the same text, and many
595
+ * local models can only be taken back to a point the server saved: the start of a user message.
596
+ * So everything before the first message is the same for every conversation of an agent, at
597
+ * any time: the tools and pine's own instructions. What belongs to one conversation comes
598
+ * after it: the instruction files (the agent's own and those for all agents) and the working
599
+ * folder open the conversation, as a first message of their own, as they were when it began.
600
+ * A line added to MEMORY.md later is said in the note in front of the next message
601
+ * (changedFiles), at the end; a file that lost lines is taken anew, which costs reading the
602
+ * conversation again but not the tools and instructions before it.
603
+ *
604
+ * And the request names its slot on a llama.cpp server (src/slots.ts), so that a second
605
+ * conversation does not take the place of the one the owner is in the middle of.
606
+ */
607
+ private steady;
608
+ /** A request as it is, with its slot on a llama.cpp server named. */
609
+ private slotted;
610
+ /** The model server of this request, and the llama.cpp slot for it if the server is one and a slot is free (src/slots.ts). */
611
+ private takeSlot;
612
+ /**
613
+ * A slot for a model call of pine's own, outside any session (the judge of goal mode): named
614
+ * like a conversation's, so that the call does not land in the slot of the conversation it is
615
+ * about and push it out. It takes what a new conversation would take, and gives it back for
616
+ * good when it is over. Nothing is named for a server pine knows no slots of.
617
+ */
618
+ callSlot(model: any, who: string): Promise<{
619
+ slot?: number;
620
+ done: () => void;
621
+ }>;
622
+ /**
623
+ * More conversations than the model server has slots (src/slots.ts): the conversation whose place
624
+ * is taken is written into a file of the server first, and the one that takes it is read back
625
+ * from its file if it was written out before. Returns how much of this conversation the slot
626
+ * holds after that, when it was read back.
627
+ *
628
+ * Only a llama.cpp server that was started with a folder for it can do this; the first refusal
629
+ * is remembered and it is not tried again. A sub-agent's conversation is not kept: it ends with
630
+ * its task. And nothing is asked of a server whose loaded model is another one.
631
+ */
632
+ private page;
633
+ /**
634
+ * Ask a llama.cpp server what its slots hold (GET /slots: tokens per slot), so that pine's notes
635
+ * know of conversations that are not pine's: another pine, another program on the same server.
636
+ * At most every two seconds (and in time for the filling of idle slots, which waits longer than
637
+ * that), only for a server pine knows the slots of, and only when it is this model that answers.
638
+ * A server that does not tell is not asked again.
639
+ */
640
+ private lookAtSlots;
641
+ /** Whether what a server says about itself (/props) is about this model: llama.cpp names the model it has loaded. */
642
+ private sameModel;
643
+ /** Fill the idle slots of a model server once pine has left it alone for a moment. */
644
+ private warmLater;
645
+ /**
646
+ * Have one idle slot of a llama.cpp server read what a conversation of the agent that used it
647
+ * last begins with: its tools, pine's instructions, its instruction files. The next
648
+ * conversation of that agent, or a sub-agent, is given that slot (SlotBook.takeFrom) and has
649
+ * only its own message to be read. One slot at a time, and only while no request of pine's is
650
+ * under way: a model that is answering somebody is not given more to do.
651
+ *
652
+ * Nothing is asked of a server whose model is not loaded (a scheduler in front of it answers
653
+ * /props with an error then): filling a slot must never be what loads a model.
654
+ */
655
+ private warm;
656
+ private giveSlot;
657
+ /** Ask a model server how many slots it has. Only llama.cpp answers; any other server gets no slot named, ever. */
658
+ private askSlots;
659
+ private wroteOwn;
660
+ private readOr;
661
+ /** How many lines of a text are no longer in what the file says now (a file that is gone has lost all of them). */
662
+ /**
663
+ * Whether a conversation is given its instruction files anew because of what happened to this one: it lost or
664
+ * changed lines, and it is a file of rules (AGENTS.md, SOUL.md, TOOLS.md, and the files for all agents), where what was taken back must not stay
665
+ * in front of the model, or a memory too long to be said again in a note. A memory that was tidied is told in the
666
+ * note instead: it is the file that is rewritten most, by every conversation of the agent, and what an old line
667
+ * of it says is a fact that no longer holds, not a rule.
668
+ */
669
+ private retakes;
670
+ private linesGone;
671
+ private fileTexts;
672
+ /** The conversation has been told what its instruction files gained: from here on, only what comes after that is news. */
673
+ private toldFiles;
674
+ /** What the instruction files say now that the conversation has not been told: for the note. */
675
+ private changedFiles;
512
676
  /**
513
677
  * An agent's model as its owner knows it: "provider/id", and the name models.json gives it.
514
678
  * A name can come from what a model server said about itself, so only plain characters of it
@@ -524,8 +688,9 @@ export declare class AgentManager {
524
688
  private sizeOf;
525
689
  /**
526
690
  * 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.
691
+ * that exist. First the rules for all agents, then what the owner alone can change, then what
692
+ * the agent keeps itself, with what else is the same for all agents among it (the tooling for
693
+ * all agents before the agent's own, then the owner), and the one that changes most often last.
529
694
  */
530
695
  private instructionFiles;
531
696
  private stamp;