pi-pocket 0.29.0-beta.3 → 0.29.0-beta.5

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 (55) hide show
  1. package/docs/architecture.md +10 -4
  2. package/docs/extensions/inbox.md +145 -0
  3. package/docs/extensions/policies/api-stability.md +1 -1
  4. package/docs/extensions/reference/host.md +34 -0
  5. package/docs/extensions/reference/names.md +1 -1
  6. package/docs/extensions/relay.md +449 -0
  7. package/docs/extensions.md +2 -0
  8. package/docs/features.md +9 -7
  9. package/docs/map.md +5 -2
  10. package/npm-shrinkwrap.json +2 -2
  11. package/package.json +1 -1
  12. package/src/server/alerts.ts +24 -0
  13. package/src/server/app.ts +33 -1
  14. package/src/server/background.ts +83 -6
  15. package/src/server/commands.ts +22 -0
  16. package/src/server/deadline.ts +93 -0
  17. package/src/server/docs.ts +20 -5
  18. package/src/server/extensions/agent-teams.ts +321 -3
  19. package/src/server/extensions/background.ts +63 -4
  20. package/src/server/extensions/memory.ts +36 -14
  21. package/src/server/extensions/pocket-relay/connectors/discord.ts +961 -0
  22. package/src/server/extensions/pocket-relay/connectors/http.ts +570 -0
  23. package/src/server/extensions/pocket-relay/connectors/matrix.ts +215 -0
  24. package/src/server/extensions/pocket-relay/connectors/rss.ts +497 -0
  25. package/src/server/extensions/pocket-relay/connectors/slack.ts +304 -0
  26. package/src/server/extensions/pocket-relay/connectors/telegram.ts +245 -0
  27. package/src/server/extensions/pocket-relay/index.js +981 -0
  28. package/src/server/extensions/pocket-relay/runtime.ts +1320 -0
  29. package/src/server/extensions/pocket-relay/style.css +294 -0
  30. package/src/server/extensions/pocket-relay/types.ts +154 -0
  31. package/src/server/extensions/pocket-relay.ts +506 -0
  32. package/src/server/extensions/subagents.ts +797 -82
  33. package/src/server/hooks.ts +37 -57
  34. package/src/server/host.ts +80 -0
  35. package/src/server/http/conversation-routes.ts +4 -1
  36. package/src/server/inbox.ts +235 -0
  37. package/src/server/linked-sessions.ts +118 -1
  38. package/src/server/memory.ts +163 -32
  39. package/src/server/push.ts +3 -0
  40. package/src/server/reload.ts +4 -0
  41. package/src/server/room.ts +4 -2
  42. package/src/server/running.ts +15 -2
  43. package/src/server/schedules.ts +34 -3
  44. package/src/server/stall-facts.ts +98 -0
  45. package/src/server/when.ts +214 -41
  46. package/types/pocket.d.ts +49 -0
  47. package/web/composer.js +135 -0
  48. package/web/notify.js +5 -0
  49. package/web/running-board.js +7 -2
  50. package/web/sheets/file.js +14 -1
  51. package/web/sheets/memory.js +71 -20
  52. package/web/sheets/schedules.js +193 -63
  53. package/web/style.css +110 -15
  54. package/web/transcript.js +9 -6
  55. package/web/ui.js +5 -0
@@ -86,10 +86,14 @@ PiP's header model chip opens the existing picker with its own conversation ID a
86
86
 
87
87
  ## Work from outside the app
88
88
 
89
- A PR watch (`watches.ts`) is a `WatchDoc` in its session and a durable task there, which sleeps until its next look, looks with `gh` (`watches.gh`, which tests replace), and puts what to tell Pi in its checkpoint before sending it: the send's request id is the watch's task and count, so a restart sends it once. Comment ids told, and the commits whose failures and conflicts were told, stay in the watch. Webhooks (`hooks.ts`) are app-wide (`HooksDoc`); `/hook/…` is outside `/api` and its sign-in, and lets a post in only by its hook's secret. Both send through `Commands.submit` as their person, with a `via` that marks the message (`[via PR watch]`, `[via webhook NAME]`), so that person's checks and spend limit apply, and what came from outside is fenced (`fence.ts`, as PiP's session text is): no closing tag survives inside, in any case or spacing. A hook's address and secret are checked before its body is read. A signed hook (`signed`, for GitHub) lets a post in only by GitHub's signature: its secret is never in its address, so the address GitHub shows a repository's admins cannot post. Pi's `watch_pr` names a PR by number, which `gh` finds in the session's own repository, or one elsewhere by address only where `gh`'s account can push (`requirePush` in `github.ts`); what follows `--` is never an option.
89
+ A PR watch (`watches.ts`) is a `WatchDoc` in its session and a durable task there, which sleeps until its next look, looks with `gh` (`watches.gh`, which tests replace), and puts what to tell Pi in its checkpoint before sending it: the send's request id is the watch's task and count, so a restart sends it once. Comment ids told, and the commits whose failures and conflicts were told, stay in the watch. Webhooks (`hooks.ts`) are app-wide (`HooksDoc`); `/hook/…` is outside `/api` and its sign-in, and lets a post in only by its hook's secret. A watch sends through `Commands.submit`, and a webhook through the inbox (below), each as their person, with a `via` that marks the message (`[via PR watch]`, `[via webhook NAME]`), so that person's checks and spend limit apply, and what came from outside is fenced (`fence.ts`, as PiP's session text is): no closing tag survives inside, in any case or spacing. A hook's address and secret are checked before its body is read. A signed hook (`signed`, for GitHub) lets a post in only by GitHub's signature: its secret is never in its address, so the address GitHub shows a repository's admins cannot post. Pi's `watch_pr` names a PR by number, which `gh` finds in the session's own repository, or one elsewhere by address only where `gh`'s account can push (`requirePush` in `github.ts`); what follows `--` is never an option.
90
90
 
91
91
  Webhook edits require steering rights. `Hooks.update` checks creator-or-owner access in the same transaction that changes the instructions, leaving the hook's other fields unchanged. Deliveries already in progress keep their original instructions.
92
92
 
93
+ The inbox (`inbox.ts`, offered to extensions as `host.inbox`) is the one way outside data reaches a session. `Inbox.deliver` checks the delivery (400), then that `by` is a person who is not a viewer and can see the session (410) and that PiP is on for a PiP conversation (503). It looks up the key's request id in Pi Durable's record with `submissionByRequest`, which is why a key delivers once, also after a restart (`{ sent: false }`). It then applies the bucket's limit, kept in memory (429), and sends through `Commands.submit` with that request id and a `via` label. The text (`inboxText`) is the instructions, then a line outside the fence that says only whether the sender's id is one the owner marked as trusted, then the payload fenced (the sender's name and id are the tag's `from` and `from-id`) with the delivery's tag and made safe by `fence.ts`, then a line that says it is data. A failed send gives its place in the hour back, logs the reason, and answers 409 with no reason. Webhooks use it with the bucket `hook:<id>`.
94
+
95
+ The relay (`extensions/pocket-relay.ts` and `pocket-relay/`) is built on the inbox. Its `Relay` keeps the owner's connectors and each one's state in `x.pocket-relay/connectors.json` and `state.json` (mode 0600, each written whole through a rename, one write at a time), and hides their secret values with `host.hide`; Lancet Guard blocks Pi's tools from the `x.*` folders. Each connector that is on has a `Runner`: one loop that polls or keeps a stream, with backoff and `RelayError`, and one that delivers. `emit` goes through `Relay.take`, which filters (bots, mention only, the limit for each author, a queue of 200) and writes the events to the connector's `pending` queue on disk before it resolves. The delivery loop sends the first one through `inbox.deliver` with the key `relay-<connector id>-<event id>` and the bucket `relay:<connector id>`: a success, a 400, or a 429 takes it off the queue, and any other error leaves it there for a later try. So an event is delivered once across restarts, and one that the session could not take waits. `relay_reply` is a deferred, replay-safe tool. The module writes it into `modelTools.add` of each session a connector delivers to, when a connector is saved, edited, or removed, so no other session is offered it. A reply is kept under `${taskId}:${callId}` in the state, so a call that runs again sends once. The module provides a service (`api: 1`, `register`, `RelayError`) for drop-in connectors, and its runners stop when it loads again (`web.onDispose`).
96
+
93
97
  A repository watch (`repo-watches.ts`) is an item of the app-wide `RepoWatchesDoc` and a durable task in the conversation it messages (PiP's, or a session's), with the same wait, look, and send phases as a PR watch: a look puts the message in the task's checkpoint, and the send's request id is the task's and its count's, so it goes once. It reads the repository's issues, pulls, workflow runs, releases, and comments through `gh api`, and keeps the ids it told. PiP's tools (`repo_watch`, `session_watch_pr`, `session_start` with `repo`) act through `Pip` as its person; a repository is worked on or watched only where `gh`'s account can push, and `Pip.checkout` finds a session's checkout whose `origin` is the repository, or clones it once into `repos/`.
94
98
 
95
99
  ## Who chooses models
@@ -98,6 +102,7 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
98
102
 
99
103
  - **Sessions** run on the model someone picked, or on what a new session starts with (`Commands.#defaultModel`): the owner's default, even when it is not signed in now, else a trusted project's model/thinking default, else the last model picked, else Pi's global default, else none. `project-model.ts` reads only the final session folder's `.pi/settings.json` at creation, without a cache; a fresh creation-local global-only settings reader supplies defaults and trust policy without changing `app.settings`. It checks Pi's trust store and global trust policy, validates a complete provider/model pair, and keeps known unsigned models rather than silently substituting one. Invalid trusted settings stop creation with a contained error. Thinking-only settings cannot change another source's model/thinking pair. Owner defaults bypass project settings. Imported sessions, forks, subagents, manual choices, and PiP's own conversation retain their previous selection behavior. A model the person explicitly named to PiP bypasses project defaults before its manual configuration step. Trust gained after creation applies only to later new sessions; existing choices never track file or folder changes. Extra project skill/prompt paths and per-project run policy are not supported yet; the shared app settings and older host APIs are unchanged.
100
104
  - **Subagents** run at their session's thinking level unless the spawn names another, of any height (`extensions/subagents.ts`), on their session's model while the owner's list is empty, and only on a listed model once it is not: the session's model when listed and none is named, else the model named, which is required when the session's is not listed (the refusal lists the allowed models; the prompt section lists them too, each with the facts from `host.modelInfo` that help choose: thinking, context window, price; `model-facts.ts`). The owner may allow models (`subagentModels` in `config.json`: `PocketApp.setSubagentModels` replaces the list, and `allowSubagentModel`, behind `POST /api/subagent-models` that the Providers sheet sends, adds or takes off one model, reading and writing the list with no wait between, so changes that come together all count); with none allowed the tool has no model parameter, and the app rebuilds the module when the list changes. Each call checks the list as it is then: a model not on it (the session's own included) is refused, and so is work for a subagent already on one; a subagent has no `subagent` or `team` tool, so none starts a nested one; a person may raise a subagent's thinking by hand, and work sent to it leaves that level. Before an allowed model is used its sign-in is asked afresh, so a stale mark neither refuses it nor lets it through. An explicit tool list also gets tools marked `subagents: "always"` by its selected extensions, never one removed for subagents or absent from a fixed extension list; marked deferred tools are offered at once, and script-only tools bring codemode. A report of a subagent its model or provider failed (by the provider's words: a sign-in, a missing or refused model, a quota) carries the model and tells Pi to stop and tell its person.
105
+ - **Stalls and deadlines** (since 0.29.0). Core keeps two generic deadlines: `withQuietLimit` (`deadline.ts`) wraps each conversation's environment (`app.ts` `#wrapped`) and stops a command that prints nothing for `background.limits.commandQuietMs`, unless its call gives `timeout`; a background task has its own `quietMs`, and a person's stop (`BackgroundTasks.stop(…, "person")`) starts a new watch that tells Pi. `host.stopToolCall` aborts one tool call's task, so its run goes on. Policy is in the extensions: `extensions/subagents.ts` keeps a stall watch per parent (`pocket.subagent-stall-watch`, in `SubagentsDoc.stallWatch`), a durable task that sleeps a minute between looks and never calls a model. It compares each working subagent's live state (`progressOf` in `stall-facts.ts`) with the last look, and marks the quiet spell in its `SubagentRecord.stall`. Past `stalledMinutes` it adds one report per spell to the outbox, so the courier sends one message for all. Past `stopMinutes` it stops the running call, or the run with `stoppedBy: "deadline"`, at most `MAX_STOPS` times until it answers (`stops`), past a call's own `timeout` (`hardLimitOf`), never while it waits for approval or a provider's limit (`host.waitsForLimit`), and tells the owner (`host.alertOwner`, push kind `stalled`). `extensions/agent-teams.ts` does the same for linked sessions through `linkedSessions.activity` and `stopCall`, with its marks in `x.agent-teams.stalls`. A reporter whose message a Stop held (`commands.ts` `#hold` or an interrupt, which send it again as `<request>~<submission>`) follows that request (`follow` phase) until it is answered or dropped, and tells the parent at once when it is held; `stoppedBy` says who stopped a run, so a stop is not reported as a failure.
101
106
  - **Linked sessions** (Agent Teams) start on a model the owner allows for subagents (their session's model when it is listed and none is named, else the model named, which is required when the session's is not listed; with no list, their session's model), and get messages from Pi only while they run on one, at their session's thinking level unless the start names another (`linked-sessions.ts`); a model that cannot be used now is refused before the session is made.
102
107
  - **Titles, compaction, and PiP's summaries** use the conversation's own model.
103
108
  - **PiP** passes a model, or names one in what it sends, only when its person named it in their own words (`pip.ts`, with `model-names.ts`): their own messages (`u:` request ids, from the authors document) since PiP's last new context (with those its last compaction kept), and the standing instructions of the watches and webhooks to PiP that they set up; never a watch PiP set up, what was posted, or what GitHub said.
@@ -132,10 +137,11 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
132
137
 
133
138
  ## Memory
134
139
 
135
- Lessons Pi keeps across sessions are one document for the whole app, `MemoryDoc` (`pocket.memory`), by id. Each is for a project or for everywhere. A project is keyed by the real path of its git common folder (`git rev-parse --git-common-dir`), so a repository and all its worktrees share lessons; outside a repository, by the folder itself. `Memory` (`memory.ts`) works out a folder's project (kept a minute per folder) and keeps the rules:
140
+ Lessons Pi keeps across sessions are one document for the whole app, `MemoryDoc` (`pocket.memory`), by id. Each is for a project, for everywhere, or for one session. A project is keyed by the real path of its git common folder (`git rev-parse --git-common-dir`), so a repository and all its worktrees share lessons; outside a repository, by the folder itself. `Memory` (`memory.ts`) works out a folder's project (kept a minute per folder) and keeps the rules:
136
141
 
137
- - The memory extension's section renders, before each request, the lessons in force for the conversation's folder: its project's and everywhere's, not pending, oldest first. It reads committed state only, so it renders the same text until a lesson changes. PiP has no project: it gets everywhere's.
138
- - Pi proposes, the owner approves. Every lesson Pi saves, and every one a person who is not the owner saves, is pending, and no prompt has it until the owner approves it: what Pi read anywhere in its context could have talked it into one. Pi's (or a guest's) new text for a lesson in force, and Pi's forgetting one, are a `proposal` on the lesson, which stays as it was until the owner approves or discards it. The tool's result names the lesson (`details.lesson`), so the transcript offers Approve and Discard under the call. An approval names what it saw (`POST …/memory/:id/approve` with `{ text }` or `{ forget: true }`); when what waits differs, `change` answers 409, so text or a proposal swapped after the owner looked is not approved with it. Pi proposing the text in force withdraws its own waiting proposal. Pending lessons do not count toward a project's or everywhere's cap; approving one does. Only the owner, or whoever saved a lesson, changes or removes it, Pi included (as the person it works for).
142
+ - The memory extension's section renders, before each request, the lessons in force for the conversation's folder: its project's, everywhere's, and its session's own, not pending, oldest first. It reads committed state only, so it renders the same text until a lesson changes. PiP has no project: it gets everywhere's and its own.
143
+ - **Session lessons** (since 0.29.0) are stored as a project whose key no folder has: `project` is `pocket-session:<root id>` (`sessionKey`, `sessionOf`, `scopeOf`), and `projectName` is `session “<title>”`. A project key is always an absolute path or a `scheme://` workspace address, so it never matches one. A server from before them (0.29.0-beta.3 and older) reads such a lesson as some other project's: it puts it in no prompt and no session's sheet, never everywhere, and lists one that waits in the owner's pending queue under that name (checked by opening a data folder written by this code with beta 3's). The key is the session's root (`rootOf`), so its subagents share them; a linked session is a root of its own. Because the lessons are in the prompt's section, not the transcript, they last through compaction and restarts. Each session keeps `MAX_SESSION_LESSONS` (20) approved ones in a room of its own, and a person's waiting session lessons count against `MAX_PENDING` in that session only, and against `MAX_PENDING_SESSIONS` (40) in all sessions. A fork (`commands.ts` `#fork`, in the fork's own commit) copies the parent's session lessons in force as its own, with new ids and no call key; pending ones and proposals stay with the parent. Pi Pocket never deletes a session, only archives it: an archived session keeps its lessons, which apply nowhere else. The memory extension offers `scope: "session"` only when the running `Memory` lists it in `scopes`, so a newer extension on an older server refuses it rather than saving a lesson for everywhere.
144
+ - Pi proposes, the owner approves. Every lesson Pi saves, and every one a person who is not the owner saves, is pending, and no prompt has it until the owner approves it: what Pi read anywhere in its context could have talked it into one. Pi's (or a guest's) new text for a lesson in force, and Pi's forgetting one, are a `proposal` on the lesson, which stays as it was until the owner approves or discards it. The tool's result names the lesson (`details.lesson`), so the transcript offers Approve and Discard under the call. An approval names what it saw (`POST …/memory/:id/approve` with `{ text }` or `{ forget: true }`); when what waits differs, `change` answers 409, so text or a proposal swapped after the owner looked is not approved with it. Pi proposing the text in force withdraws its own waiting proposal. Pending lessons do not count toward a project's, everywhere's, or a session's cap; approving one does. Only the owner, or whoever saved a lesson, changes or removes it, Pi included (as the person it works for).
139
145
  - Pi's adds carry the tool call's key, so a replayed call finds its lesson. A subagent's lesson comes from its session (`rootOf`).
140
146
  - Every write adds an activity line to the session's chat in the same commit. `#committed` tells `Memory` when the document changed; it sends tabs a `memory` event, and the Memory sheet and menu fetch the lessons again (`GET /api/c/:id/memory`).
141
147
 
@@ -0,0 +1,145 @@
1
+ # Delivering outside data
2
+
3
+ An extension can give data from outside the app to a session. Examples are a chat message, an item of a feed, and an event from a service. Use `host.inbox.deliver`. Its shape is in [the host reference](reference/host.md#inbox).
4
+
5
+ **Experimental, since 0.29.0.** It can change in a minor release, but never in a patch release ([API stability](policies/api-stability.md#experimental)). A module for an older server checks that `host.inbox?.deliver` is there, and a gallery entry that needs it sets `minPocket` to `0.29.0`.
6
+
7
+ ## When to use it
8
+
9
+ Use `host.inbox` when text that people you do not know wrote must reach Pi. It does the safe work for you: it fences the text as data, checks who Pi works for, delivers once, and caps the rate.
10
+
11
+ - Do not use it for a message that a person of this app wrote. Use [`host.sessions.start`](sessions.md) or [`host.linkedSessions`](linked-sessions.md).
12
+ - Do not use it to let a service connect to a chat or a feed. The [relay](relay.md) does that, and it delivers through this same call.
13
+ - Webhooks (Menu → **Webhooks and watches**) use this call too. A post to a hook and an event from the relay reach Pi the same way.
14
+
15
+ ## An example
16
+
17
+ This module adds a route. The owner (or a script) posts a session, an id, and a text, and the text reaches that session as outside data.
18
+
19
+ ```typescript title="tell.ts"
20
+ /**
21
+ * Tell: a route that gives a text to a session as outside data, once for each id.
22
+ */
23
+ import type { ConversationId } from "@earendil-works/pi-durable";
24
+ import type { Host, Web } from "./_pocket.d.ts";
25
+
26
+ export default function createTell(host: Host, web: Web) {
27
+ const inbox = host.inbox;
28
+
29
+ // A server older than 0.29.0 has no inbox: do nothing there.
30
+ if (typeof inbox?.deliver !== "function") {
31
+ return;
32
+ }
33
+
34
+ web.route(
35
+ "POST",
36
+ "tell",
37
+ async (request) => {
38
+ const session = request
39
+ .sessions()
40
+ .find((each) => each.id === Number(request.body.session));
41
+ const id = typeof request.body.id === "string" ? request.body.id : "";
42
+ const text = typeof request.body.text === "string" ? request.body.text : "";
43
+
44
+ if (session === undefined || id === "" || text === "") {
45
+ throw web.error(400, "Give a session, an id, and a text.");
46
+ }
47
+
48
+ try {
49
+ const { sent } = await inbox.deliver(session.id as unknown as ConversationId, {
50
+ by: request.user.id,
51
+ via: "tell",
52
+ key: `tell-${id}`,
53
+ instructions: "Say in one line what this is, and whether it needs doing.",
54
+ tag: "tell-message",
55
+ sender: { name: request.user.name, id: request.user.id },
56
+ payload: text,
57
+ limit: { bucket: "tell", perHour: 30 },
58
+ });
59
+
60
+ return { sent };
61
+ } catch (error) {
62
+ const status = (error as { status?: unknown }).status;
63
+
64
+ throw web.error(
65
+ typeof status === "number" ? status : 500,
66
+ error instanceof Error ? error.message : String(error),
67
+ );
68
+ }
69
+ },
70
+ { access: "owner" },
71
+ );
72
+ }
73
+ ```
74
+
75
+ Pi reads the instructions first, then who sent it, then the text between `<tell-message>` tags, then a line that says it is data. The message shows in the session as `[via tell]`.
76
+
77
+ ## What the call checks
78
+
79
+ `deliver` checks the delivery before it does anything. A delivery that cannot be right throws an error with `status` 400, whatever the session.
80
+
81
+ - `by` is the id of a person of this app. The person must be able to see the session and steer in it, and must not be a viewer. Pi works for that person on the message, and that person's checks apply. Give the id of the owner or of the person who set the source up, never an id from the outside.
82
+ - `via` is a short label. Core removes brackets and control characters and cuts it to 80 characters.
83
+ - `payload` is text. Core makes it safe between the tags (no closing tag survives) and cuts it to 8,000 characters.
84
+ - `key` is 1 to 512 characters.
85
+ - `instructions`, when given, are text of 4,000 characters at most.
86
+ - `tag` is a lowercase word with `-`. `attributes` are up to 8 pairs: the name is a lowercase word with `-`, and the value is text.
87
+ - `limit.perHour` is a whole number of 1 or more.
88
+
89
+ ## Keys: once
90
+
91
+ A `key` delivers once. A second delivery with the same `key` to the same session, as the same `by`, sends nothing and returns `{ sent: false }`. This is also true after a restart: Pi Durable keeps the record of the message.
92
+
93
+ - Use the source's own id for the event, with a prefix of your module: `my-feed-${item.id}`. Do not use a random value or the time. A retry then finds the first delivery.
94
+ - A key of letters, digits, `_`, and `-` (64 or fewer) is the request id as it is. Any other key becomes a hash of itself. You do not need to do this yourself.
95
+ - A delivery that failed did not use its key. Try again with the same key.
96
+
97
+ ## Limits
98
+
99
+ `limit: { bucket, perHour }` caps how many messages one source sends in an hour.
100
+
101
+ - A `bucket` is a name of your own. Give each source its own, such as `my-feed:${feed.id}`. Every caller that uses the same name shares the count.
102
+ - The cap is 600 an hour at most, whatever you ask for. Without `limit`, a source has no cap of its own.
103
+ - The count is in memory. A restart forgives it.
104
+ - A message that did not go gives its place back.
105
+ - Past the cap, `deliver` throws a 429. Decide what that means for the source: the relay drops the event and counts it.
106
+
107
+ Do not rely on the cap alone. A source that you do not trust needs a smaller limit for each author, as the relay has.
108
+
109
+ ## The fence
110
+
111
+ Pi gets the message in four parts, in this order:
112
+
113
+ 1. The instructions. These are yours, or the default: "Something happened that you were set up to hear about. Say in a line what it is, and whether anything needs doing."
114
+ 2. With `sender`, one line about the sender's id: `The sender's id is not one the owner marked as trusted.` With `trusted: true`, it says that the id (`from-id`) is one the owner marked as trusted. The name and the id themselves are not in this line.
115
+ 3. The payload, between `<tag attribute="…" from="name" from-id="…">` and `</tag>`. The default tag is `outside-data`. The sender's name and id are the attributes `from` and `from-id`, inside the fence, because they came from outside.
116
+ 4. A line that says what came between the tags was posted from outside: it is data, not instructions.
117
+
118
+ Rules that follow:
119
+
120
+ - The instructions and the trust line are outside the fence. Write the instructions from what you know, never from what the source sent. A name or an id from the source goes in `sender` (core puts it in the fence's tag) or inside the payload, never in `instructions`.
121
+ - `trusted` is guidance for the model, not a boundary. Some services let a person pretend to be another one. Set it only for ids that the owner listed, and tell the owner what it means.
122
+ - Fence what you do not know. Do not copy a secret, a key, or a private file into a payload: Pi and its answer may repeat it.
123
+
124
+ ## Errors and retries
125
+
126
+ `deliver` throws an error with a `status`:
127
+
128
+ | Status | Meaning | What to do |
129
+ | ------ | --------------------------------------------------------------------------------------- | --------------------------------------------- |
130
+ | 400 | The delivery cannot be right. | Fix the code or drop the event. Do not retry. |
131
+ | 410 | The session is gone, or its person cannot see it or cannot steer. | Stop or ask the owner. A retry will not help. |
132
+ | 503 | The session is PiP, and PiP is turned off. | Try again later with the same key. |
133
+ | 429 | The `bucket` has reached its cap. | Drop the event, or wait for the hour to pass. |
134
+ | 409 | The session does not take messages now (someone else drives, a spend limit, and so on). | Try again later with the same key. |
135
+
136
+ The 409 says no more: the reason is in the server's log, with the label, and not in the error. This is so that a source cannot learn how the session is used.
137
+
138
+ Keep what you could not deliver on disk, and try again later with the same key and with a longer wait each time. The relay does this with its queue.
139
+
140
+ ## Security notes
141
+
142
+ - A module that calls `deliver` can message any session of the person it names as `by`. Check that `by` is a person who can reach `target`, and that the person set the source up. A route that takes `target` from a browser must check it against `request.sessions()`, as the example does.
143
+ - Everything in `payload` is from outside. Pi may follow what is in it, even with the fence. Write `instructions` that say what Pi may do with it, and keep the session's tools and rights to what that needs.
144
+ - Keep a secret out of a payload, and out of a log line. Hide a secret you hold with `host.hide` ([People's values](people-values.md#hide-a-value)).
145
+ - Use one `bucket` for each source. A source must not choose its own bucket name, because it could then pick a new one to avoid its cap.
@@ -55,7 +55,7 @@ These members are public:
55
55
  - `ask(request, context)`, `hide(value)`, `commandEnv(provider)`, `browser(conversationId, options)` (experimental, since 0.22.0: [People's values and the browser](../people-values.md))
56
56
  - `on(event, listener)` and the events of `AppEvents` (experimental, since 0.22.0: [Events, services, and settings](../services-settings.md))
57
57
 
58
- These members are on `host` for Pi Pocket's own built-in extensions: `guard`, `approvals`, `schedules`, `goals`, `browsers`, `memory`, `watches`, `repoWatches`, `gallery`, `updates`, `pip`, and `pipCompaction`. They are **internal**. A drop-in can read them, but their shapes can change in any release. One of them becomes public only through a request for an extension point ([core-or-extension.md](core-or-extension.md#ask-for-a-new-extension-point)).
58
+ These members are on `host` for Pi Pocket's own built-in extensions: `guard`, `approvals`, `schedules`, `goals`, `browsers`, `memory`, `watches`, `repoWatches`, `gallery`, `updates`, `pip`, `pipCompaction`, `toolNames`, `stopToolCall`, `waitsForLimit`, and `alertOwner`, and `linkedSessions.activity`, `linkedSessions.stopCall`, and `linkedSessions.onLedRun`. They are **internal**. A drop-in can read them, but their shapes can change in any release. One of them becomes public only through a request for an extension point ([core-or-extension.md](core-or-extension.md#ask-for-a-new-extension-point)).
59
59
 
60
60
  The host's members do not change while modules reload. A new member comes only after a restart, so a module that uses a new member must check that it is there ([Using the host](../host.md)).
61
61
 
@@ -438,6 +438,37 @@ Makes a top-level session and, when `message` is given, sends that text as its f
438
438
  - A source past its spend limit, a person invited to one session, and a PiP source are refused, and nothing is made.
439
439
  - A blank `message` is refused, and nothing is made. A `message` is also refused when the session gets no model: no `model` and no default model.
440
440
 
441
+ ## Outside data
442
+
443
+ ### `inbox`
444
+
445
+ ```ts
446
+ readonly inbox?: InboxApi;
447
+ ```
448
+
449
+ Since 0.29.0 · Experimental
450
+
451
+ Gives data from outside the app (a chat message, a feed's item, a service's event) to a session that exists, or to PiP, as a message from one person. Webhooks use the same path. It is `undefined` on a server older than 0.29.0: check `host.inbox?.deliver` first. [Delivering outside data](../inbox.md) tells how to use it.
452
+
453
+ #### `inbox.deliver`
454
+
455
+ ```ts
456
+ deliver(target: ConversationId, delivery: InboxDelivery): Promise<{ sent: boolean }>;
457
+ ```
458
+
459
+ Since 0.29.0 · Experimental
460
+
461
+ Sends one message to `target`, as `[via <via>]`. Pi reads the person's `instructions` first, then whether the sender is trusted, then the payload between `<tag>` tags, then a line that says the payload is data.
462
+
463
+ - `by`: the id of the person Pi works for on it. The person must be able to see and steer the session, and not be a viewer.
464
+ - `payload`: the text that came. Core makes it safe between the tags (no closing tag survives) and cuts it to 8,000 characters.
465
+ - `key`: delivers once. A second delivery with the same key sends nothing and returns `{ sent: false }`, also after a restart. Use the source's own id for the event.
466
+ - `tag` and `attributes`: the fence's tag (default `outside-data`) and up to 8 attributes, each made one line without quotes.
467
+ - `sender`: who sent it. The name and the id go in the fence's tag, as `from` and `from-id`, because they came from outside. Outside the fence, one line says only whether the owner marked the id as trusted (`trusted: true`). This is guidance to the model, not a boundary: an id can be spoofed on some services.
468
+ - `limit`: a cap of messages in an hour for one `bucket`, kept in memory. A restart resets it. The cap is 600 at most.
469
+
470
+ It throws an error with a `status`: 400 for a delivery that cannot be right, 410 when the session is gone or its person cannot see it, 503 when PiP is off, 429 when the bucket's limit is reached, and 409 when the session does not take messages now. Try again later after a 409 or a 503, with the same key.
471
+
441
472
  ## Linked sessions
442
473
 
443
474
  ### `linkedSessions`
@@ -824,4 +855,7 @@ The host has more members, for Pi Pocket's built-in modules only. They are not i
824
855
  - `pip`: what the tools of PiP, the owner's assistant, do.
825
856
  - `pipCompaction`: PiP's own summaries when its context is compacted.
826
857
  - `gallery`: the extension gallery, for its own routes.
858
+ - `toolNames`: the names of the tools that the modules that are on give now (built-in and drop-in), for codemode's Only mode.
859
+ - `stopToolCall`, `waitsForLimit`, `alertOwner` (since 0.29.0): for the stall watches of Subagents and Agent Teams. They stop one running call, say whether a run waits for a provider's limit, and tell the owner (a notice and a push).
860
+ - `linkedSessions.activity`, `linkedSessions.stopCall`, `linkedSessions.onLedRun` (since 0.29.0): for the stall watch of Agent Teams. They give the led sessions at work, stop a stuck call of a led session, and call back when a led session starts a run.
827
861
  - `updates`: updates of Pi Pocket itself, for the Updates module's routes. Its status says how the copy was installed (`installKind`: `git`, `npm-global`, `npm-local`, `npx`, or `unknown`) and what stands in the way of an update from the app.
@@ -7,7 +7,7 @@ The rules for the names that a module gives. These are the names of its file, ex
7
7
  To install an extension with the name of an installed extension replaces that extension. A tool with the name of another tool replaces it in all sessions. Thus Pi Pocket refuses a drop-in that would take a name that Pi Pocket keeps, or a name that another module has. Menu → Extensions says why.
8
8
 
9
9
  - **Extension names that Pi Pocket keeps:** `coding-tools`, and all names that start with `pocket-`, such as `pocket-core`, `pocket-prompt`, and `pocket-guard`. This is true also when that built-in module is off.
10
- - **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact` (and `artifact_inline`, a name still kept: it was a tool until 0.28.0, and old sessions hold its calls), `browser`, `subagent`, `team`, `schedule`, `background`, `codemode`, `tool_search`, `memory`, `ask`, and `ask_someone`. PiP's tools: `sessions`, `session_read`, `session_start`, `session_send`, `session_follow`, `session_stop`, `session_archive`, `session_schedule`, `approvals`, `repo_watch`, and `session_watch_pr`. The triggers' tool: `watch_pr`. Design's tools: `design_preview`, `design_export`, and `design_system`.
10
+ - **Built-in tools:** `read`, `write`, `edit`, `bash`, `artifact` (and `artifact_inline`, a name still kept: it was a tool until 0.28.0, and old sessions hold its calls), `browser`, `subagent`, `team`, `schedule`, `background`, `codemode`, `tool_search`, `memory`, `ask`, and `ask_someone`. PiP's tools: `sessions`, `session_read`, `session_start`, `session_send`, `session_follow`, `session_stop`, `session_archive`, `session_schedule`, `approvals`, `repo_watch`, and `session_watch_pr`. The triggers' tool: `watch_pr`. Design's tools: `design_preview`, `design_export`, and `design_system`. The relay's tool: `relay_reply` (reserved also when the relay is off).
11
11
  - **Names that another module has:** the first module to install an extension or tool keeps its name.
12
12
 
13
13
  Give each extension and tool a name of your own, with a prefix: `example-clock`, `acme_lookup`. To change how a built-in tool works, do not replace it. Wrap it (`wrapTool` in Pi Durable's README), or check its calls with a hook.