@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,52 @@
1
+ import crypto from "node:crypto";
2
+ import { timingSafeEqual } from "../security.js";
3
+ import { Type } from "typebox";
4
+ import { refuse } from "../sources.js";
5
+ /**
6
+ * A web address other services can call: POST http://<pine's control address>/hook/<name>.
7
+ * For GitHub, Home Assistant, a doorbell, a shortcut on your phone, anything that can send a request.
8
+ *
9
+ * options: { secret, open? }
10
+ * secret the caller proves itself with it, either as "Authorization: Bearer <secret>" or by
11
+ * signing the body (HMAC SHA-256 in X-Hub-Signature-256 or X-Signature, as GitHub does)
12
+ * open true to accept anyone who can reach the port; only for a port nobody else can reach
13
+ *
14
+ * event "received": { body, headers } body is parsed JSON, or { text } for anything else
15
+ */
16
+ const KEPT = ["content-type", "user-agent", "x-github-event", "x-github-delivery", "x-event-type", "x-event-key", "x-request-id"];
17
+ export const type = {
18
+ summary: "a web address other services can call (POST /hook/<name> on pine's control port; /hook/<name>@<agent> for an agent's own). For GitHub, Home Assistant, a doorbell, a shortcut on a phone",
19
+ options: Type.Object({
20
+ secret: Type.Optional(Type.String({ description: "what the caller proves itself with. Leave it out and pine makes one", secret: true })),
21
+ open: Type.Optional(Type.Boolean({ description: "true to accept anyone who can reach the port, without a secret. Only for a port nobody else can reach" })),
22
+ }, { additionalProperties: false }),
23
+ plan(o, setup) {
24
+ if (o.open === true)
25
+ return { options: { open: true }, does: [`accept web requests at /hook/${setup.key} on pine's control port from ANYONE who can reach it`], opens: true, tell: `Callers use POST /hook/${setup.key} on pine's control address.` };
26
+ const made = !o.secret;
27
+ return { options: { secret: o.secret ?? setup.random(24) }, does: [`accept web requests at /hook/${setup.key} on pine's control port from callers that present a secret${made ? " (made now)" : ""}`], opens: true, tell: `Callers use POST /hook/${setup.key} on pine's control address and present the secret, which your owner finds in pine's .env file as ${setup.envName("secret")}.` };
28
+ },
29
+ };
30
+ export default function webhook(source) {
31
+ const secret = typeof source.options.secret === "string" ? source.options.secret : "";
32
+ if (!secret && source.options.open !== true)
33
+ throw new Error(`needs a "secret" the caller has to present (or "open": true to accept anyone who can reach the port)`);
34
+ source.secret(secret || undefined);
35
+ source.http(({ headers, body }) => {
36
+ if (secret) {
37
+ const bearer = String(headers.authorization ?? "").replace(/^Bearer /, "");
38
+ const sig = String(headers["x-hub-signature-256"] ?? headers["x-signature"] ?? "").replace(/^sha256=/, "");
39
+ const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
40
+ if (!(bearer && timingSafeEqual(bearer, secret)) && !(sig && timingSafeEqual(sig, expected)))
41
+ throw refuse(401, "bad signature");
42
+ }
43
+ let parsed;
44
+ try {
45
+ parsed = JSON.parse(body.toString("utf8"));
46
+ }
47
+ catch {
48
+ parsed = { text: body.toString("utf8") };
49
+ }
50
+ source.emit("received", { body: parsed, headers: Object.fromEntries(KEPT.filter((k) => headers[k] !== undefined).map((k) => [k, String(headers[k])])) });
51
+ });
52
+ }
@@ -0,0 +1,344 @@
1
+ import { type PineConfig, type SourceConfig, type SubscriptionConfig } from "./config.ts";
2
+ import type { SourcePlan } from "./source-types.ts";
3
+ import type { Router } from "./router.ts";
4
+ import { type Approvals, type Redactor } from "./security.ts";
5
+ import type { Bus, Kv } from "./store.ts";
6
+ import type { PineEvent } from "./types.ts";
7
+ import { type Logger } from "./util.ts";
8
+ /**
9
+ * Event sources and the subscriptions to them.
10
+ *
11
+ * A source is to events what an MCP server is to tools: a named thing in the configuration, global
12
+ * (pine.json) or one agent's own (agent.json), that can report what happens somewhere else: a file
13
+ * arrives, a device says something, a web service calls, a clock strikes. Being configured does
14
+ * nothing. A source starts when the first conversation subscribes to it. A subscription belongs to
15
+ * one conversation of one agent: each event arrives there as a message and wakes the agent into a
16
+ * turn, and what it does with it is in its instructions and in the note it left when it subscribed.
17
+ * Another conversation of the same agent is not subscribed until it subscribes itself. When the
18
+ * last subscriber leaves, the source stops.
19
+ *
20
+ * Events are published as source/<name>/<event> (source/<name>@<agent>/<event> for an agent's own
21
+ * source), so the event log, routes and the UI see them like any other event.
22
+ */
23
+ /** What a source module gets. A source is a module whose default export is `(source) => void | Promise<void>`. */
24
+ export interface SourceApi {
25
+ /** The name it has in the configuration. */
26
+ name: string;
27
+ /** What it is called in events and addresses: its name, or name@agent for an agent's own source. */
28
+ key: string;
29
+ options: Record<string, any>;
30
+ /** Folder that relative paths in the options are meant from. */
31
+ base: string;
32
+ /** A folder of its own for whatever it has to keep (received files, for example). */
33
+ dataDir: string;
34
+ log: Logger;
35
+ /**
36
+ * Report that something happened. `event` is a short word such as "added" or "message".
37
+ * With `reply`, the answer of an agent that is woken by this event comes back to `onSend`, with
38
+ * the fields given here (a chat to answer in, for example) next to its `text`.
39
+ */
40
+ emit(event: string, payload?: Record<string, unknown>, opts?: {
41
+ persist?: boolean;
42
+ reply?: Record<string, unknown>;
43
+ }): PineEvent;
44
+ /**
45
+ * For a source that can also send: called with an agent's answer to one of its events, and with
46
+ * what an agent sends through it on its own. Return a short line on what was done; throw to
47
+ * refuse. The source decides where things may go: it never sends anywhere it was not set up for.
48
+ */
49
+ onSend(handler: (message: Record<string, any>) => void | string | Promise<void | string>): void;
50
+ /**
51
+ * Say in one line how things stand, for whoever lists the sources: who it is connected to,
52
+ * what it is waiting for. Call it again when that changes.
53
+ */
54
+ status(line: string): void;
55
+ /** Look at events of the system (read only): "agent/+/started", "approval/requested", ... */
56
+ on(pattern: string | string[], handler: (e: PineEvent) => void | Promise<void>): void;
57
+ /** Approval requests: put a question of its own to the owner, see the open ones, pass on the owner's answer. */
58
+ approvals: {
59
+ /** Ask the owner in pine's UI. Resolves with their answer; no answer in time counts as no. */
60
+ ask(summary: string, why: string): Promise<boolean>;
61
+ /**
62
+ * The same, with fields the owner has to fill in (`secret: false` for one that may be shown
63
+ * while it is typed). `by` says who answered: "timeout" when nobody did.
64
+ */
65
+ request(summary: string, why: string, inputs: Array<{
66
+ name: string;
67
+ label: string;
68
+ secret?: boolean;
69
+ }>): Promise<{
70
+ allow: boolean;
71
+ by: string;
72
+ values?: Record<string, string>;
73
+ }>;
74
+ pending(): Array<{
75
+ id: string;
76
+ agent: string;
77
+ tool: string;
78
+ summary: string;
79
+ why: string;
80
+ remember?: string;
81
+ task: number;
82
+ choices?: string[];
83
+ }>;
84
+ decide(id: string, allow: boolean, by: string, always?: boolean): boolean;
85
+ /** Answer an agent's question with one of the answers it offered (by its place in `choices`). */
86
+ choose(id: string, choice: number, by: string): boolean;
87
+ };
88
+ /**
89
+ * Look at something again and again, for what cannot report by itself: a web address, a
90
+ * command, a mailbox. `look` runs once right away and then every `every` ("30s", "5m"), never
91
+ * twice at the same time, a little earlier or later each round so that sources do not all fire
92
+ * together. A look that throws is a failed look: the pause grows with each one in a row, and
93
+ * whoever lists the sources sees since when it fails and why. One poll per source; it stops
94
+ * with the source, and `signal` is aborted then.
95
+ *
96
+ * A look that finds nothing new does nothing at all: no event, nothing stored, nobody woken.
97
+ */
98
+ poll(every: string | number, look: (signal: AbortSignal) => void | Promise<void>): void;
99
+ /**
100
+ * Compare a value with what was there at the last look, and remember it. Returns what it was
101
+ * before when it differs. The first look returns nothing: it is the starting point, not a
102
+ * change. `slot` keeps several values apart.
103
+ */
104
+ changed<T = unknown>(value: T, slot?: string): {
105
+ previous: T;
106
+ } | undefined;
107
+ /**
108
+ * Run a shell command with the rights of the agent this source belongs to (the main agent for
109
+ * a source of all agents): in that agent's sandbox, from its workspace, without its owner's
110
+ * environment. It can do nothing that agent's own shell could not. `output` is what it printed,
111
+ * errors included. Throws when it cannot be started or takes longer than `timeoutMs` (30 s).
112
+ */
113
+ exec(command: string, opts?: {
114
+ timeoutMs?: number;
115
+ maxBytes?: number;
116
+ signal?: AbortSignal;
117
+ }): Promise<{
118
+ code: number;
119
+ output: string;
120
+ truncated: boolean;
121
+ }>;
122
+ /** Private storage that survives restarts. */
123
+ kv: {
124
+ get<T = unknown>(key: string): T | undefined;
125
+ set(key: string, value: unknown): void;
126
+ };
127
+ /** Keep this value out of events and messages. */
128
+ secret(value: string | undefined): void;
129
+ /** Image files in this folder may be shown to a model when an event names them in `images`. */
130
+ media(dir: string): void;
131
+ /** Receive POST /hook/<name> on the control API's port. Throw `refuse(status, message)` to turn a request away. */
132
+ http(handler: (req: {
133
+ headers: Record<string, string | string[] | undefined>;
134
+ body: Buffer;
135
+ }) => void | Promise<void>): void;
136
+ onStop(fn: () => void | Promise<void>): void;
137
+ }
138
+ export type PineSource = (source: SourceApi) => void | Promise<void>;
139
+ /** An error a webhook handler throws to answer with that HTTP status. */
140
+ export declare function refuse(status: number, message: string): Error;
141
+ export interface SourceInfo {
142
+ name: string;
143
+ /** "global", or the agent it belongs to. */
144
+ scope: string;
145
+ type: string;
146
+ description?: string;
147
+ trust: string;
148
+ running: boolean;
149
+ error?: string;
150
+ /** What the source says about itself while it runs: who it is connected to, what it waits for. */
151
+ status?: string;
152
+ /** Who listens: "agent" for its main conversation, "agent/conversation" for another. */
153
+ subscribers: string[];
154
+ /** Topic prefix of its events. */
155
+ topic: string;
156
+ last?: {
157
+ ts: number;
158
+ topic: string;
159
+ };
160
+ events: number;
161
+ }
162
+ export declare class SourceHost {
163
+ private cfg;
164
+ private bus;
165
+ private kv;
166
+ private redactor;
167
+ private router;
168
+ private log;
169
+ private httpEnabled;
170
+ private running;
171
+ private starting;
172
+ private errors;
173
+ private statuses;
174
+ private polls;
175
+ private seen;
176
+ private off?;
177
+ private offOut?;
178
+ private approvals?;
179
+ private globalRoutes;
180
+ mediaRoots: string[];
181
+ /** Every source type there is: pine's own and the ones pine.json registers. `type` is what the module says about itself. */
182
+ private types;
183
+ constructor(deps: {
184
+ cfg: PineConfig;
185
+ bus: Bus;
186
+ kv: Kv;
187
+ redactor: Redactor;
188
+ router: Router;
189
+ log: Logger;
190
+ http: boolean;
191
+ approvals?: Approvals;
192
+ });
193
+ /** Every configured source with its key: global ones by name, an agent's own as name@agent. */
194
+ private all;
195
+ private subscribersOf;
196
+ /** The agents a subscription for everyone reaches: those that can use the source and have no entry of their own for their main conversation. */
197
+ private reached;
198
+ /** (Re)build the routes of the subscriptions for everyone. Called whenever any subscription changes, since an agent's own entry takes the place of the general one. */
199
+ private wireGlobal;
200
+ /** Read what each source type says about itself. A type whose module does not load is left out, with a line in the log. */
201
+ private loadTypes;
202
+ /** The source types an agent can set up by tool call: name, what it is for, and the schema of its options. */
203
+ typeList(): Array<{
204
+ name: string;
205
+ summary: string;
206
+ options: any;
207
+ }>;
208
+ /** Where the source types that were registered while pine ran are kept: in pine's home, which no agent can write. */
209
+ private typeDir;
210
+ /** The registered source types that are not pine's own, with what uses each. */
211
+ ownTypes(): Array<{
212
+ name: string;
213
+ file: string;
214
+ summary?: string;
215
+ usedBy: string[];
216
+ }>;
217
+ /**
218
+ * Register a new source type from the text of its module. The text is copied into pine's home
219
+ * first, and it is that copy that is loaded and runs from then on: what an agent wrote and the
220
+ * owner confirmed cannot be changed afterwards. A module that does not load or does not describe
221
+ * itself is not registered, and nothing of it stays.
222
+ *
223
+ * This runs the module inside the daemon. Whoever calls it has the owner's yes for exactly this text.
224
+ */
225
+ addType(name: string, code: string): Promise<{
226
+ name: string;
227
+ summary: string;
228
+ options: string;
229
+ file: string;
230
+ }>;
231
+ /** Take a registered source type out again. Not while a source of that type exists. */
232
+ removeType(name: string): void;
233
+ /** The name a secret option of a source gets in .env. */
234
+ /** A value the owner typed into a dialog is a secret from here on: kept out of events and logs. */
235
+ keepOut(values: string[]): void;
236
+ private envName;
237
+ /**
238
+ * Work out what setting up a source of a type with these options would mean. The options are
239
+ * checked against the schema the type exposes, then the type itself says what it would do.
240
+ * Nothing is written.
241
+ */
242
+ propose(agentId: string, name: string, typeName: string, raw: unknown, forAll?: boolean, ask?: string[]): SourcePlan & {
243
+ secrets: string[];
244
+ needs: Array<{
245
+ name: string;
246
+ label: string;
247
+ }>;
248
+ };
249
+ start(): Promise<void>;
250
+ stop(): Promise<void>;
251
+ private routeName;
252
+ /** What a subscription amounts to: this source's events become turns of that agent in that conversation. */
253
+ private route;
254
+ private ensure;
255
+ private launch;
256
+ /** A source's shell command, run the way the shell of the agent it belongs to would run it. */
257
+ private exec;
258
+ private halt;
259
+ /**
260
+ * The sources an agent can send through, with what sending does. A global one or its own;
261
+ * one that was set up for a single conversation only from there.
262
+ */
263
+ senders(agentId: string, session?: string): Array<{
264
+ name: string;
265
+ type: string;
266
+ sends: string;
267
+ }>;
268
+ /** Send something out through a source, started if it is not running. Throws with the source's own reason if it refuses. */
269
+ send(agentId: string, name: string, message: Record<string, any>, session?: string): Promise<string>;
270
+ /** The handler for POST /hook/<key>, if a running source takes web requests under that name. */
271
+ hookFor(key: string): ((req: {
272
+ headers: Record<string, string | string[] | undefined>;
273
+ body: Buffer;
274
+ }) => void | Promise<void>) | undefined;
275
+ /** What a running source says about itself; for one that polls, with when it last looked or since when that fails. */
276
+ private statusOf;
277
+ list(): SourceInfo[];
278
+ /**
279
+ * The sources an agent can subscribe to, as seen from one of its conversations, with everything
280
+ * that would wake it: `local` this conversation, `agent` its main conversation, `global` a
281
+ * subscription for all agents, `elsewhere` its other conversations.
282
+ */
283
+ available(agentId: string, session?: string): Array<{
284
+ name: string;
285
+ type: string;
286
+ description?: string;
287
+ local?: SubscriptionConfig;
288
+ agent?: SubscriptionConfig;
289
+ global?: SubscriptionConfig;
290
+ elsewhere: string[];
291
+ }>;
292
+ /**
293
+ * Add a source to the configuration while the daemon runs: to one agent's agent.json, or to
294
+ * pine.json for everyone. `entry` is what goes into the file. The file is written first and then
295
+ * read back through the normal loader, so a new source is checked exactly like one that was
296
+ * there at start; if it does not pass, the file is put back as it was.
297
+ * `read` also lets that agent read the folder (for a folder source outside its workspace).
298
+ */
299
+ add(agentId: string | undefined, name: string, entry: Record<string, unknown>, read?: string, secrets?: string[]): SourceConfig;
300
+ /**
301
+ * Take a source out of the configuration while the daemon runs: it stops, whoever was subscribed
302
+ * to it is unsubscribed, and its entry is deleted. For a watched folder outside the agent's
303
+ * workspace, the read access that came with it goes too, unless another source still needs it.
304
+ */
305
+ remove(agentId: string | undefined, name: string): Promise<{
306
+ removed: boolean;
307
+ unsubscribed: string[];
308
+ }>;
309
+ /** The sources that were set up for one conversation of an agent. */
310
+ boundTo(agentId: string, session: string): string[];
311
+ /** Agents were added or removed: who a subscription for everyone reaches has changed. */
312
+ agentsChanged(): void;
313
+ /** The keys of a subscription that are written to a file. */
314
+ private clean;
315
+ private same;
316
+ /**
317
+ * Subscribe one conversation of an agent to a source and keep that in its agent.json, so it
318
+ * holds across restarts. `raw` is what goes into the file: session (default "main", which is the
319
+ * agent as such), note, when, debounce, throttle, separate, prompt. Subscribing the same
320
+ * conversation again replaces its entry.
321
+ */
322
+ subscribe(agentId: string, name: string, raw?: Record<string, unknown>): Promise<SourceInfo & {
323
+ session: string;
324
+ }>;
325
+ /** Subscribe every agent that can use a source of pine.json: each is woken in its main conversation. Kept in pine.json. */
326
+ subscribeAll(name: string, raw?: Record<string, unknown>): Promise<SourceInfo & {
327
+ agents: string[];
328
+ }>;
329
+ private started;
330
+ /** End the subscription of one conversation, or with no `session` of all of that agent's conversations. Returns the conversations that were subscribed. */
331
+ unsubscribe(agentId: string, name: string, session?: string): Promise<string[]>;
332
+ unsubscribeAll(name: string): Promise<boolean>;
333
+ /**
334
+ * A conversation was closed or reset: what it was subscribed to on its own goes with it. An
335
+ * agent's main conversation is the agent as such and keeps its subscriptions.
336
+ */
337
+ closeSession(agentId: string, session: string): Promise<string[]>;
338
+ /** A conversation got another name: what it was subscribed to on its own follows it. */
339
+ renameSession(agentId: string, from: string, to: string): Promise<void>;
340
+ /** Stop a source that nobody listens to any more. */
341
+ private settle;
342
+ }
343
+ /** A type's options in one line, for a tool description or an error: name, whether it is needed, what it is. */
344
+ export declare function describeOptions(schema: any): string;