pi-roundtable 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-10-21
+
+### Added
+
+- Worker sessions for plugins (`pi-roundtable`). A new built-in plugin, `worker-sessions` (after `modules`), provides `WORKER_SESSIONS`, a `WorkerSessions`: `run(request)` runs a `WorkerSessionRequest` (`task`, `signal`, `prompt`, `extensions`, `toolNames`, and optionally `model`, `thinking` and `aborted`) in a fresh, unsaved Pi session on the host's model login and resolves to the worker's final answer, rejecting with an `AgentRunError` when it ends without one and with the signal's reason when it is aborted; the session is disposed either way. The session has no built-in tool, skill, context file, memory or agent tool, and only the tools its `extensions` register and `toolNames` names are active, even if an extension activates another. `model` and `thinking` default to the host's `delegation` settings, shown as `WorkerSessions.delegation`. The delegation worker for web research now runs on the same code. It is a separate plugin, not part of `modules`, so a host that replaces `BACKGROUND_TURNS` and `DELEGATION` still replaces that plugin whole. The built-in plugin names gain `worker-sessions`, so a plugin of that name is now refused. See [Workers of your own](docs/plugins.md#workers-of-your-own).
+- `pi-roundtable-browser`, a new official workspace package published in lockstep (not yet on npm; see `.github/PACKAGE-RELEASES.md`): `browserAgent(options)` adds the owner-tier tool `browser_task({ task, url? })`, which runs a fresh worker session that drives a real browser through a `BrowserDriver` and returns its report, attaching the screenshots it kept to the agent's reply. The default driver runs agent-browser and Chromium in a Docker container started per task and removed after it, with no network but a unix socket to a host-side proxy that refuses every destination that is not a public address. See the package README and `site/src/content/docs/plugins/browser-package.mdx`.
+- Skills from an npm package (`pi-roundtable`, `pi-roundtable-web`). `skills: { packages: ["pi-workflow-skills"] }` (the new type `SkillsConfig`) names packages the host installed; at startup the registry reads each package's `pi.skills` folders and offers every skill found as a fourth kind, `package` (`SkillSource` gains `{ kind: "package"; package }`; `SkillCatalogEntry.source` and the web console's skill list show the package). A package skill is read-only, named by its frontmatter and resolved to the installed file on every read, so upgrading the package changes the skill with no database write. Agents carry package skills and groups include them exactly like linked or written ones (`agent_skills`, `agent_create`, `skill_group_set`, `repo_task`); `skill_unlink`, `skill_update` and `skill_delete` refuse a package skill with a message saying it comes from the package, and `skill_link` and `skill_create` refuse a name a package skill holds. A package that is not installed, a package without `pi.skills`, two packages offering one name, or a package skill named like a built-in, linked or written skill stops startup with a `PluginError` naming the fix. A carried package skill that an upgrade removed is reported missing and skipped, as a vanished linked skill is.
+
+## [0.21.0] - 2026-10-20
+
+### Added
+
+- A held call's approval card can be its speaker's alone (`pi-roundtable`). A hold answers `{ text, approval: "speaker" }` (`HoldDescription.approval`, beside `copy` and `supersede`; a tool's `hold` and a rule's `describeInTurn` both may) and the card reaches the surface as `ApprovalOptions.speakerOnly`. Only the speaker whose turn made the call answers it, on any of their identities the surface knows and at the call's tier, checked again when they press: in a shared conversation no owner does, and an owner's press or decline is refused with the card's own line while the card stays open for the speaker. A speaker below the tier, a turn with no speaker and a speaker with no Discord identity get `unavailable` at once, shown to no one, so the call stays held. With `approvers` the card is still the speaker's alone, and the runtime accepts their press only when the approvers name them or they are an owner. The option governs the card only; a message that confirms the held call is judged as before, so a tool that must act on the speaker's press alone checks `ToolTurn.approvedPrompt` and `ToolTurn.approvedBy` in `run`. Without it every card behaves as before. The Discord cards and the web chat honour it, and `SurfaceContractSubject.speakerOnly` makes `describeSurfaceContract` check, with an `owner`, that an owner's answer leaves such an approval open in a shared conversation; a subject that does not declare it skips the check.
+
 ## [0.20.0] - 2026-10-18
 
 ### Added

package/docs/plugins.md

@@ -50,6 +50,29 @@ Their exported names are grouped by area in the source, with one entry for each;
 The [changelog](../CHANGELOG.md) lists every exported name, including type-only contracts.
 Import fixtures and fake threads from `pi-roundtable/testing` for tests.
 
+#### Workers of your own
+
+A plugin that gives a model its own small set of tools, such as a worker that drives a browser, asks the host for a worker session instead of building one from Pi's parts:
+
+```ts
+const sessions = context.services.get(WORKER_SESSIONS);
+const report = await sessions.run({
+	task: "What the worker is asked to do.",
+	signal: turn.signal,
+	prompt: "You are a ... worker. Report in the task's language.",
+	extensions: [registersTheWorkersTools],
+	toolNames: ["my_tool"],
+});
+```
+
+`run` starts a fresh session that is never saved, on the host's model login (the same credentials and refreshes the agents use), with the `model` and `thinking` of the host's `delegation` settings unless the request names its own (`model` is `<provider>/<id>`; `sessions.delegation` shows the defaults).
+The session has no built-in tool, no skills, no context files, no memory and none of the agents' tools: only the tools the `extensions` register with `pi.registerTool` and `toolNames` lists are active, and an extension that activates another tool is undone.
+`prompt` is added to its system prompt, so the standing rules and any instructions the worker should follow, such as a tool's usage guide, go there.
+`run` resolves to the worker's final answer, rejects with an `AgentRunError` when it ends without one, and rejects when `signal` aborts (`aborted` is the message of that rejection, default "the worker ran out of time"); the session is disposed either way.
+The tools are the plugin's to bound: the worker has no tier, no hold and no conversation, so a tool checks what the worker asks for, limits its work, and cleans up in a `finally` around `run`.
+A file a tool produces reaches the person only through the tool that called `run`: collect it and call `turn.attachFile` after `run` returns, as the [browser package source][browser-source] does with screenshots.
+The `worker-sessions` plugin provides the service on every host.
+
 #### Helpers for a Pi session of your own
 
 Use the kit's building blocks for a plugin that runs Pi itself, such as a coding worker:
@@ -218,6 +241,7 @@ The built-in plugins provide these, from the main entry:
 | `MEMORY` | `MemoryStore` | `memory` (an addon) | `forSpeaker(principalId)` gives that principal's `SpeakerMemory`: `list`, `forPrompt`, `add`, `search`, `update`, `removeById`, `remove`; `MEMORY_KINDS` is `core`, `note`, `event` |
 | `BACKGROUND_TURNS` | `BackgroundTurns` | `modules` | Turns nobody wrote: `runScheduled`, `runDelegated`, `runErrorReport` |
 | `DELEGATION` | `Delegator` | `modules` | `start(request)` a background task, `runningChannels()`, `idle()` |
+| `WORKER_SESSIONS` | `WorkerSessions` | `worker-sessions` | Fresh Pi sessions for a plugin's own workers, on the host's model login: `delegation` is the host's delegation `model` and `thinking`, and `run({ task, signal, prompt, extensions, toolNames, model?, thinking?, aborted? })` runs the task in a session that has only the tools `extensions` register and `toolNames` names (no built-in tool, skill, context file, memory or agent tool) and returns the worker's final answer; see [Workers of your own](#workers-of-your-own) |
 
 The data types the ports use (`Schedule`, `NewSchedule`, `Agent`, `AgentGroup`, `TeamStatus`, `Memory`, `SkillSet`, `DelegationJob`, and so on) are in the main entry too.
 Your plugins run after the built-ins, so they can read every key above.
@@ -366,7 +390,16 @@ You can switch them off in the configuration.
 | Discord administration | `discord-admin` | `discord: { admin: false }` | The `discord_*` tools that read and manage the server, for the owner; they check what the primary owner may do on the server, whichever owner's turn calls them | No `discord_*` tools; the channel executor that remote MCP uses is the connection's, so it stays |
 
 Switching an addon off leaves its tables and rows unchanged, ready for when you turn it on again.
-`skills` also takes the two directories (`skills: { builtinDir, reposDir }`) when it is on.
+`skills` also takes the two directories and the skill packages (`skills: { builtinDir, reposDir, packages }`) when it is on.
+
+`skills.packages` lists npm packages the host installed, for example `["pi-workflow-skills"]`.
+At startup the registry reads each package's `pi.skills` folders (Pi's package manifest) and offers every skill it finds there as a fourth kind, `package`, beside the built-in, linked and written ones.
+A package skill is named by its frontmatter and resolved to the installed file on every read, so upgrading the package changes the skill and nothing is written to the database.
+Agents carry package skills and groups include them exactly like the others: `agent_skills`, `agent_create`'s `skills` field, `skill_group_set` and `repo_task` accept their names.
+`skill_unlink`, `skill_update` and `skill_delete` refuse a package skill, naming the package, and `skill_link` and `skill_create` refuse a name a package skill already holds.
+`SkillCatalogEntry.source` is `{ kind: "package", package }` for them, and the web console's skill list shows the package.
+A package that is not installed, a package with no `pi.skills` (or none that holds a `SKILL.md`), two packages offering one name, a package skill with the name of a built-in, linked or written skill: each stops startup with a `PluginError` naming the fix.
+A carried package skill that an upgrade removed is reported missing and skipped, as a linked skill whose file vanished is.
 
 Use `find` for an optional addon service; it returns `undefined` while the addon is off.
 Use `get` if your plugin needs the addon; it fails with a message naming the switch:
@@ -876,6 +909,21 @@ A rule whose verdict depends on the input, such as one that holds only a `delete
 It is asked when the input is not known yet, as for a [precheck script](#precheck-scripts-prechecks-the-agent-writes)'s call whose arguments are computed when it runs; a rule without it is judged by `describe` with an empty input.
 A rule whose held call stands for others can answer `approvalTier(tool, input, context)`: the lowest tier that may approve it when higher than the tool's own. The held call keeps it as `minTier`, and both its card and a confirming message require it. A card is answered, and a confirming message accepted, from the speaker whose turn held the call, when their tier is at least `minTier`, and from the owners where the conversation is shared ([who answers a prompt](#who-answers-a-prompt-promptscope)); nobody else in the channel may approve it. The held call records that speaker as `PendingConfirmation.speakerId` and their principal as `principalId`, so a confirming message from another identity of theirs counts after a restart too; a call held without them is the owners' to approve, and one held before 0.9, without a principal, is matched by `speakerId`.
 
+#### A hold that makes its card the speaker's alone
+
+By default the speaker whose turn made a held call may answer its card, and in a shared conversation so may every owner. A hold that wants only the speaker to press, such as one whose tool books something under the speaker's name, answers `{ text, approval: "speaker" }` (`HoldDescription.approval`, beside `copy` and `supersede`; a tool's `hold` and a rule's `describeInTurn` both may):
+
+```ts
+hold: async ({ draft }, turn) => ({ text: await summaryOf(draft, turn), approval: "speaker" }),
+```
+
+- Only the speaker answers the card: their principal, on any of their identities the surface knows, at the call's tier, checked again when they press. An owner's press is refused with the card's own line, the card stays open for the speaker, and the owner's decline is refused too. An owner who is the speaker answers as the speaker.
+- It holds for a late press as well: a card answered after the turn stopped waiting is still the speaker's alone, so the turn that follows is started by the speaker.
+- A speaker below the call's tier, a turn with no speaker, and a surface that cannot tell who the speaker is get `unavailable` at once, shown to no one, and the call stays held, as for any card nobody may answer. It never falls back to the owners.
+- Combined with [approvers](#a-hold-that-names-its-approvers) the card is still the speaker's alone, and the runtime accepts the press only when the approvers name the speaker (or they are an owner); otherwise the call stays held.
+- The option governs the card only. A message that confirms the held call is judged as for any call, so an owner's message can still release it. A tool that must act on the speaker's press alone checks in `run` that `turn.approvedPrompt` is set (a message sets none) and that `turn.approvedBy?.speakerId` is the speaker's.
+- Anything but `"speaker"` leaves the card as every card is. A surface implements this through `ApprovalOptions.speakerOnly`; the Discord cards and the web chat (whose prompts are its person's alone) honour it, and the contract checks it where a subject declares `speakerOnly`.
+
 #### A hold that names its approvers
 
 A held call is approved by the speaker whose turn made it, or by an owner where the conversation is shared. A tool whose call stands for someone else, such as a message sent under another person's name, can name who approves it instead:
@@ -2645,6 +2693,8 @@ A surface's prompts keep these rules:
 - Without a scope, as for a turn with no speaker, the prompts are the owners'.
 - An approval that names [approvers](#a-hold-that-names-its-approvers) (`ApprovalOptions.approvers`, which `confirm` receives beside the scope) is theirs **instead of the speaker's**, where the scope escalates to the owners: each named principal answers on any of their identities the surface knows, at the tier it needs, checked again when they answer; the speaker does not answer it unless named, and an owner still does. When none of the named has an identity on the surface, or none is named, it is the owners' alone. Where the scope escalates to no one, the person alone answers, and only when they are named or an owner: for anyone else the approval resolves `unavailable` at once, shown to no one. The runtime also refuses such a call before it asks, whatever the surface does.
 
+- An approval that is the [speaker's alone](#a-hold-that-makes-its-card-the-speakers-alone) (`ApprovalOptions.speakerOnly`) is theirs without the owner escalation, whatever the scope says: the speaker's principal answers on any of their identities the surface knows, at the tier it needs, checked again when they answer, and no owner does. Without a scope, or when the speaker is below the tier or has no identity on the surface, it resolves `unavailable` at once, shown to no one.
+
 On Discord a card for named approvers mentions every Discord identity of every named principal that has one, in a thread, and refuses anyone else with a line that says it is for the people it names and the owners.
 The web chat shows prompts to the conversation's person only. The runtime never asks it about a call that names approvers the person is neither among nor an owner of, and the person is the approver of one that names them.
 
@@ -2656,7 +2706,7 @@ The web chat shows prompts to the conversation's person only: its owners are not
 
 `confirm(title, message, signal?, minTier?, wait?, details?, options?)` takes the approval twice: `message` is the card as markdown text, and the optional `details` (`ApprovalDetails`: `{ action, tool, input, files? }`) is the same held call as data, with its whole input (the web chat cuts it only past 256 KiB and says so with `truncated`), and each file it sends by path as `{ path, bytes? }`.
 The confirmation gate and a coding worker's cards pass both.
-`options` (`ApprovalOptions`) says who else may approve the call and hears who did: `approvers`, the principal ids that approve it instead of the speaker (see [who answers a prompt](#who-answers-a-prompt-promptscope)), and `approvedBy(by)`, which a surface that knows who answered calls with `{ principalId, speakerId, name, owner? }` (`ApprovedBy`; `owner` when they approved as an owner) before `confirm` resolves `approved`. `approvedPrompt(prompt)` is called, likewise before `confirm` resolves `approved`, with the id of the card that approved the call, for `ToolTurn.approvedPrompt`; a surface whose cards have no stable id leaves it uncalled. A surface may ignore all three for a call that names no approvers. For one that does, the runtime accepts the approval only from a surface that calls `approvedBy` with a named principal or an `owner`, so a surface that cannot say who answered must not offer such a call to a shared conversation.
+`options` (`ApprovalOptions`) says who else may approve the call and hears who did: `approvers`, the principal ids that approve it instead of the speaker (see [who answers a prompt](#who-answers-a-prompt-promptscope)), `speakerOnly`, true when the card is the speaker's alone and no owner may answer it (see [a hold that makes its card the speaker's alone](#a-hold-that-makes-its-card-the-speakers-alone); a surface that cannot honour it resolves `unavailable` instead of showing the card to the owners), and `approvedBy(by)`, which a surface that knows who answered calls with `{ principalId, speakerId, name, owner? }` (`ApprovedBy`; `owner` when they approved as an owner) before `confirm` resolves `approved`. `approvedPrompt(prompt)` is called, likewise before `confirm` resolves `approved`, with the id of the card that approved the call, for `ToolTurn.approvedPrompt`; a surface whose cards have no stable id leaves it uncalled. A surface may ignore all three for a call that names no approvers. For one that does, the runtime accepts the approval only from a surface that calls `approvedBy` with a named principal or an `owner`, so a surface that cannot say who answered must not offer such a call to a shared conversation.
 A surface that shows text, such as Discord, uses `message` and reads only `details.copy` (below); the web chat sends `details` to the client as the prompt frame's `approval`, beside the unchanged `title` and `message`.
 A surface or a `Prompts` of your own may ignore it: nothing requires reading it.
 
@@ -3145,7 +3195,7 @@ The [pi-roundtable-mcp][mcp-package] workspace, published separately on npm, add
 The first lets the owner add MCP servers such as Notion or a calendar from Discord and gives your code the list; the second lets an agent outside Discord reach your agent.
 Install it with `bun add pi-roundtable-mcp`.
 
-Six official packages live in this repository as Bun workspaces and publish as separate npm packages, versioned in lockstep with the core.
+Seven official packages live in this repository as Bun workspaces and publish as separate npm packages, versioned in lockstep with the core.
 The [site guide source files][package-guides] describe installation, requirements, configuration, and security considerations:
 
 - [pi-roundtable-drawing][drawing-package]: [site guide source][drawing-guide] · local relationship maps, magic circles, sigils, sacred geometry, and card spreads.
@@ -3153,6 +3203,7 @@ The [site guide source files][package-guides] describe installation, requirement
 - [pi-roundtable-web][web-package]: [site guide source][web-guide] · an owner-only console for conversations, transcripts, and memory notes with live updates.
 - [pi-roundtable-sandbox][sandbox-package]: [site guide source][sandbox-guide] · sealed guest channels on native Linux Docker with a host-only credential broker and allow-listed tools.
 - [pi-roundtable-mcp][mcp-package]: [site guide source][mcp-guide] · MCP connectors through a gateway and remote MCP endpoints for agent turns and owner-granted Discord channel tools.
+- [pi-roundtable-browser][browser-package]: [site guide source][browser-guide] · `browser_task`, a worker that drives agent-browser in a Docker container with no route to the host's private networks, and a `BrowserDriver` for another browser.
 - [pi-roundtable-webchat][webchat-package]: [site guide source][webchat-guide] · a WebSocket chat for people an OpenID Connect provider signs in, with private conversations, live progress, and approval cards; see [web chat](#web-chat-pi-roundtable-webchat).
 
 [drawing-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/drawing/README.md
@@ -3160,17 +3211,20 @@ The [site guide source files][package-guides] describe installation, requirement
 [web-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/web/README.md
 [sandbox-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/sandbox/README.md
 [mcp-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/mcp/README.md
+[browser-package]: https://github.com/wayne930242/pi-roundtable/blob/master/packages/browser/README.md
 [package-guides]: https://github.com/wayne930242/pi-roundtable/tree/master/site/src/content/docs/plugins/
 [drawing-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/drawing-package.mdx
 [coding-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/coding-package.mdx
 [web-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/web-package.mdx
 [sandbox-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/sandbox-package.mdx
 [mcp-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/mcp-package.mdx
+[browser-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/browser-package.mdx
 [webchat-guide]: https://github.com/wayne930242/pi-roundtable/blob/master/site/src/content/docs/plugins/webchat-package.mdx
 [coding-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/coding
 [sandbox-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/sandbox
 [web-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/web
 [drawing-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/drawing
+[browser-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/browser
 [mcp-source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/mcp
 [codex-images-template]: https://github.com/wayne930242/pi-roundtable/blob/master/templates/official/codex-images/plugin.ts
 [dice-template]: https://github.com/wayne930242/pi-roundtable/blob/master/templates/official/dice/plugin.ts
@@ -3419,9 +3473,9 @@ test("the production configuration registers every plugin", async () => {
 ### `describeSurfaceContract`: what every chat surface keeps
 
 A plugin that contributes a `ChatSurface` can test it against the contract every surface keeps.
-`describeSurfaceContract(name, make)` registers one test per check, each on a fresh `SurfaceContractSubject` from `make`: the `surface`, a `channel` of it, and one person on its network, who can `write(text)`, whose `observations()` list what they have seen (`SurfaceObservation`: a reply's text and file names, typing and stop controls going on and off, progress, and prompts opening and closing), and who may `answer(prompt, approved)` an approval; `speaker` is who they are to `surface.prompts`, given as `promptScope(speaker, visibility)`, an owner by default, and every approval the contract asks for needs exactly their tier. `stranger`, when given, is someone else on the network, another principal and not an owner, who knows the id of the person's open approval and may `join()` and `answer(prompt, approved)` it; `owner`, when given, is an owner on the network, another principal than the person, who does the same in the person's private conversation. Both are `SurfaceContractAnswerer`s. `approver`, when given, is a third person on the network with a `principalId`, not an owner and at the person's tier, whom the contract names in `approvers`; `privateOnly` marks a surface that serves only conversations private to one person, such as the web chat.
+`describeSurfaceContract(name, make)` registers one test per check, each on a fresh `SurfaceContractSubject` from `make`: the `surface`, a `channel` of it, and one person on its network, who can `write(text)`, whose `observations()` list what they have seen (`SurfaceObservation`: a reply's text and file names, typing and stop controls going on and off, progress, and prompts opening and closing), and who may `answer(prompt, approved)` an approval; `speaker` is who they are to `surface.prompts`, given as `promptScope(speaker, visibility)`, an owner by default, and every approval the contract asks for needs exactly their tier. `stranger`, when given, is someone else on the network, another principal and not an owner, who knows the id of the person's open approval and may `join()` and `answer(prompt, approved)` it; `owner`, when given, is an owner on the network, another principal than the person, who does the same in the person's private conversation. Both are `SurfaceContractAnswerer`s. `approver`, when given, is a third person on the network with a `principalId`, not an owner and at the person's tier, whom the contract names in `approvers`; `speakerOnly` marks a surface that honours `ApprovalOptions.speakerOnly` in a shared conversation, which the contract then checks with the `owner`; `privateOnly` marks a surface that serves only conversations private to one person, such as the web chat.
 The contract starts the surface, calls the subject's `join()`, and stops the surface after the subject's `close()`.
-It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops or its plugin withdraws it (`ApprovalOptions.supersede`; one answered first stays answered), with a `stranger`, that the stranger's answer leaves the person's approval open, and with an `owner`, that an owner's answer leaves it open in a private conversation; with an `approver` and a `stranger`, that an approval naming the approver is answered by the approver and not by the person or the stranger, unless the surface is `privateOnly`, and, with an `approver`, that a private conversation ignores the names; and, for a speaker below the owner tier, that a private conversation's approval above their tier resolves `unavailable` (or `expired`, as older surfaces answer) at once and is not shown.
+It checks that the surface names a prefix and owns its channel, delivers what the person writes, and shows every chunk of a reply; and, for the parts the surface offers, that it delivers files when `supportsFiles` is set, ends typing and stop controls idempotently, shows progress, and resolves an approval as the person approves or declines it, or `cancelled` when the turn stops or its plugin withdraws it (`ApprovalOptions.supersede`; one answered first stays answered), with a `stranger`, that the stranger's answer leaves the person's approval open, and with an `owner`, that an owner's answer leaves it open in a private conversation; with an `approver` and a `stranger`, that an approval naming the approver is answered by the approver and not by the person or the stranger, unless the surface is `privateOnly`, and, with an `approver`, that a private conversation ignores the names; with a `speakerOnly` subject and an `owner`, that an owner's answer leaves an approval that is the speaker's alone open in a shared conversation, unless the surface is `privateOnly`; and, for a speaker below the owner tier, that a private conversation's approval above their tier resolves `unavailable` (or `expired`, as older surfaces answer) at once and is not shown.
 A check for a part the surface does not offer passes.
 The contract has no check for `ApprovalDetails.copy`: a surface that shows it keeps it informational, so using it never resolves, approves or declines the prompt, whoever uses it.
 A subject that gives `answerQuestionnaire` (and a `stranger` that gives its own) must declare `asks` and also keeps the questionnaire checks.
@@ -3438,7 +3492,7 @@ The host's `run()` handles startup:
    The runtime plugin builds the runtime later, in its own setup: from the `runtime` slot when a plugin fills it, else the Pi runtime.
 2. The database is opened and every plugin's migrations run, in plugin order.
 3. Every plugin's `setup` runs, in plugin order.
-   The order is the built-ins (`memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`; an addon that is switched off is not there, and without Discord neither are `discord`, `discord-admin`, `skills`, `agent-server`, or `seeds`), then yours in the order of `plugins` in `roundtable.config.ts`, then the built-in `schedules`, so a due schedule fires only once everything it can reach is running.
+   The order is the built-ins (`memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `worker-sessions`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`; an addon that is switched off is not there, and without Discord neither are `discord`, `discord-admin`, `skills`, `agent-server`, or `seeds`), then yours in the order of `plugins` in `roundtable.config.ts`, then the built-in `schedules`, so a due schedule fires only once everything it can reach is running.
 4. The contributions are linked: tool tiers, hold rules, the session plan, the channel router, and the events.
    From here `sessions()`, `conversations`, `surfaces`, `turns`, and `dashboard()` work.
 5. Every plugin's `preflight` runs, in plugin order.
@@ -3526,7 +3580,7 @@ These are the messages as the code writes them, with `<...>` where your names go
 | `no runtime provider is configured: the runtime plugin builds the Pi runtime when no plugin fills the runtime slot; read the running one from services.get(RUNTIME)` | Only a plugin that calls `providers.runtime` without `providers.filled.has("runtime")` sees it; read `services.get(RUNTIME)` instead |
 | `session tool <name> takes a core extension name. Rename it.` | Pick a name other than the core's |
 | `plugin <name>: setup failed: the database was queried during setup…` (from `Roundtable.check()`, `roundtable doctor` or `start`) | A plugin's `setup` ran a query. Take `database()` in setup and query from a service's `start` or from a handler |
-| `two plugins are named <name>.` (from `roundtable doctor`) | Rename yours; the built-in plugins are `memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`, and `schedules` |
+| `two plugins are named <name>.` (from `roundtable doctor`) | Rename yours; the built-in plugins are `memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `worker-sessions`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`, and `schedules` |
 | `migration <plugin>/<name> is declared twice` | A plugin declares two migrations with one name: rename one (the same name in two plugins is fine) |
 | `/<root> <name> is added twice`, `/<name> is registered twice` | Give each slash command and subcommand its own name |
 | `route <name> is registered twice`, `routes <a> and <b> overlap on listener <id>` | Give each route its own name and a path no other route can take |
@@ -3868,8 +3922,12 @@ Import from the entries listed below; source area files are internal.
 | `SessionToolSnapshot` | `pi-roundtable` | type |
 | `SkillCatalogEntry` | `pi-roundtable` | type |
 | `SkillRegistry` | `pi-roundtable` | type |
+| `WorkerSessions` | `pi-roundtable` | type |
+| `WorkerSessionRequest` | `pi-roundtable` | type |
+| `WORKER_SESSIONS` | `pi-roundtable` | value |
 | `SkillSet` | `pi-roundtable` | type |
 | `SkillSource` | `pi-roundtable` | type |
+| `SkillsConfig` | `pi-roundtable` | type |
 | `Speaker` | `pi-roundtable` | type |
 | `SpeakerMemory` | `pi-roundtable` | type |
 | `StoredAttachment` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/builtin/skills.ts

@@ -1,4 +1,5 @@
 import type { SQL } from "bun";
+import { discoverPackageSkills } from "../modules/skills/package-skills.ts";
 import { StoredSkillRegistry } from "../modules/skills/skill-registry.ts";
 import { SkillStore } from "../modules/skills/skill-store.ts";
 import {
@@ -19,6 +20,10 @@ export interface SkillsOptions {
 	reposDir: string;
 	writtenDir: string;
 	builtinDir: string;
+	/** npm packages whose `pi.skills` folders offer read-only skills; the host installed them. */
+	packages?: readonly string[];
+	/** Where a package is found; default the installed package's folder. */
+	packageDir?: (name: string) => string;
 }
 
 /** Admins manage skills; every speaker may look one up. */
@@ -47,11 +52,17 @@ export function skillsPlugin(
 		// The skills are read once every plugin is set up, so a plugin may still place some in setup.
 		preflight: () => registry?.init(),
 		setup: async ({ database, services, logger }) => {
+			// Read before the store opens, so a missing package stops startup at once.
+			const packageSkills = discoverPackageSkills(
+				options.packages ?? [],
+				options.packageDir,
+			);
 			const built = new StoredSkillRegistry({
 				store: await openStore(database(), options.guildId),
 				reposDir: options.reposDir,
 				writtenDir: options.writtenDir,
 				builtinDir: options.builtinDir,
+				packageSkills,
 				logger,
 			});
 			registry = built;

package/src/core/builtin/worker-sessions.ts

@@ -0,0 +1,44 @@
+import { join } from "node:path";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import {
+	formatModelRef,
+	type ModelRef,
+	type ThinkingLevel,
+} from "../models.ts";
+import { workerSessions } from "../modules/delegation/worker-session.ts";
+import type { RoundtablePlugin } from "../plugin.ts";
+import { WORKER_SESSIONS } from "../services.ts";
+
+export interface WorkerSessionsPluginOptions {
+	/** Shared with the rest of the host, so logins refresh in one place. */
+	modelRuntime: ModelRuntime;
+	agentDir: string;
+	dataDir: string;
+	/** The model and thinking level a worker session uses unless its request names its own. */
+	delegation: { model: ModelRef; thinking: ThinkingLevel };
+}
+
+/** Provides `WORKER_SESSIONS`: worker sessions on the host's model login, with its delegation settings as the defaults. */
+export function workerSessionsPlugin(
+	options: WorkerSessionsPluginOptions,
+): RoundtablePlugin {
+	return {
+		name: "worker-sessions",
+		provides: [WORKER_SESSIONS],
+		setup: ({ services }) => {
+			services.provide(
+				WORKER_SESSIONS,
+				workerSessions({
+					modelRuntime: options.modelRuntime,
+					agentDir: options.agentDir,
+					workDir: join(options.dataDir, "workers"),
+					delegation: {
+						model: formatModelRef(options.delegation.model),
+						thinking: options.delegation.thinking,
+					},
+				}),
+			);
+			return {};
+		},
+	};
+}

package/src/core/config/config.ts

@@ -36,11 +36,11 @@ import {
 	number,
 	oneOf,
 	optional,
-	orOff,
 	record,
 	shape,
 	text,
 } from "./schema.ts";
+import { type SkillsConfig, skillsField } from "./skills-config.ts";
 
 export type { DiscordConfig };
 
@@ -168,7 +168,7 @@ export interface RoundtableConfig {
 	 * the `skills` addon out: agents carry no skills, and no skill tools exist. Stored skills stay
 	 * in their tables. Without `discord` there are no agents, so the addon is off.
 	 */
-	skills?: false | { builtinDir?: string; reposDir?: string };
+	skills?: false | SkillsConfig;
 	/**
 	 * Whether each speaker's memory is kept and offered as tools; default true. `false` leaves the
 	 * `memory` addon out: no memory tools, no memory prompt block, and the table stays as it is.
@@ -284,9 +284,7 @@ const schema = shape({
 	avatar: optional(text),
 	workDir: optional(text),
 	scratchDir: optional(text),
-	skills: optional(
-		orOff(shape({ builtinDir: optional(text), reposDir: optional(text) })),
-	),
+	skills: optional(skillsField),
 	memory: optional(bool),
 	ops: optional(shape({ agent: optional(text), conversation: optional(text) })),
 	drainSeconds: optional(integer(1, 3_600)),
@@ -352,7 +350,7 @@ export interface ResolvedConfig {
 	workDir: string;
 	scratchDir: string;
 	/** `false` when the skills addon is off. */
-	skills: false | { builtinDir?: string; reposDir?: string };
+	skills: false | SkillsConfig;
 	memory: boolean;
 	ops?: { agent: string } | { conversation: ChannelKey };
 	drainMs: number;

package/src/core/config/skills-config.ts

@@ -0,0 +1,23 @@
+import { list, optional, orOff, shape, text } from "./schema.ts";
+
+/** The `skills` setting when the addon is on. */
+export interface SkillsConfig {
+	/** Where the registry reads the release's built-in skills. */
+	builtinDir?: string;
+	/** Where it keeps linked repositories; default `<dataDir>/repos`. */
+	reposDir?: string;
+	/**
+	 * npm packages the host installed. Every skill in their `pi.skills` folders is offered
+	 * read-only, and carried and grouped like any other. Startup fails, naming the fix, when a
+	 * package is not installed, ships no skills, or holds a skill whose name another skill has.
+	 */
+	packages?: string[];
+}
+
+export const skillsField = orOff(
+	shape({
+		builtinDir: optional(text),
+		reposDir: optional(text),
+		packages: optional(list(text)),
+	}),
+);

package/src/core/define-roundtable.ts

@@ -13,6 +13,7 @@ import {
 	precheckPlugin,
 	scheduleStorePlugin,
 } from "./builtin/stores.ts";
+import { workerSessionsPlugin } from "./builtin/worker-sessions.ts";
 import { warnDeprecations } from "./config/access.ts";
 import {
 	type ResolvedConfig,
@@ -187,6 +188,7 @@ function discordAssembly(
 						reposDir: config.skills.reposDir ?? join(config.dataDir, "repos"),
 						writtenDir: join(config.dataDir, "skills"),
 						builtinDir: config.skills.builtinDir ?? join(ASSETS, "skills"),
+						packages: config.skills.packages ?? [],
 					}),
 				]
 			: [],
@@ -321,6 +323,12 @@ export async function defineRoundtable(
 					? { errorReporter }
 					: {}),
 			}),
+			workerSessionsPlugin({
+				modelRuntime,
+				agentDir: config.agentDir,
+				dataDir: config.dataDir,
+				delegation: config.delegation,
+			}),
 			...(assembly?.admin ?? []),
 			...(assembly?.skills ?? []),
 			conversationsPlugin(),

package/src/core/discord/card-audience.ts

@@ -58,7 +58,9 @@ export class CardAudiences {
 		scope: PromptScope | undefined,
 		minTier: Tier,
 		named?: readonly string[],
+		speakerOnly = false,
 	): Promise<Audience | undefined> {
+		if (speakerOnly) return this.#speakers(scope, minTier);
 		let approvers = named;
 		// A private conversation's person is the only one who answers, so a call naming others is theirs only if named or an owner.
 		if (approvers && scope?.escalate === "none") {
@@ -78,6 +80,51 @@ export class CardAudiences {
 		);
 	}
 
+	/**
+	 * The card of a call that is its speaker's alone (`ApprovalOptions.speakerOnly`): the scope's
+	 * principal on any of their Discord identities still theirs when they press, at the tier the
+	 * call needs, checked again then, and no owner as such, whatever the scope escalates to. The
+	 * primary owner answers their own card, and where there is no identity service the primary owner
+	 * is the only speaker who has one. Undefined, so the call is unavailable at once, when there is
+	 * no scope, or the speaker is below the tier or has no Discord identity.
+	 */
+	async #speakers(
+		scope: PromptScope | undefined,
+		minTier: Tier,
+	): Promise<Audience | undefined> {
+		if (!scope) return undefined;
+		const { ownerId, identity } = this.#options;
+		if (!identity) {
+			// Without an identity service the primary owner is the only one who answers, and the only speaker who can.
+			if (scope.speakerId !== ownerId) return undefined;
+			return {
+				allows: async (user) => user.id === ownerId,
+				mentions: [ownerId],
+				note: "",
+				refusal: messages().cardOwnerOnly,
+				approver: (user) => this.#approver(user),
+			};
+		}
+		const own = await this.#ownIdentities(scope, minTier);
+		if (!own) return undefined;
+		const mentions = own.includes(scope.speakerId) ? [scope.speakerId] : own;
+		const primary = own.includes(ownerId);
+		return {
+			allows: async (user) =>
+				own.includes(user.id) &&
+				// Read the links again: one moved or unlinked since the card was posted is no longer theirs.
+				(await this.#stillOwn(scope.principalId, user.id)) &&
+				((primary && user.id === ownerId) ||
+					(await this.#owners.holds(user, minTier, scope.principalId))),
+			mentions,
+			note: primary ? "" : messages().cardApproversNote(...mentions),
+			refusal: primary
+				? messages().cardOwnerOnly
+				: messages().cardApproversRefusal,
+			approver: (user) => this.#approver(user),
+		};
+	}
+
 	/** Who may answer a question; undefined when no one may. */
 	question(scope: PromptScope | undefined): Promise<Audience | undefined> {
 		return this.#audience(scope, undefined, {

package/src/core/discord/owner-cards.ts

@@ -141,6 +141,7 @@ export class OwnerCards implements InteractionModule {
 					scope,
 					minTier,
 					options?.approvers,
+					options?.speakerOnly === true,
 				);
 				// A private conversation's call above its person's tier is no one's to approve.
 				if (!audience) return "unavailable";

package/src/core/holds.ts

@@ -19,8 +19,20 @@ export interface HoldContext {
 
 /**
  * What a hold that runs in a turn answers with: the description of the call, or the description
- * as `text` with a `copy` the owner's approval card offers beside it (see `ApprovalDetails.copy`)
- * and a `supersede` signal to withdraw the call by.
+ * as `text` with a `copy` the owner's approval card offers beside it (see `ApprovalDetails.copy`),
+ * a `supersede` signal to withdraw the call by, and `approval: "speaker"` to make the card the
+ * speaker's alone.
+ *
+ * With `approval: "speaker"` only the speaker whose turn made the call may answer its card, on
+ * any of their identities the surface knows and at the call's tier; no owner may answer it as an
+ * owner (an owner who is the speaker answers as the speaker). A speaker below the call's tier, a
+ * turn with no speaker, or a surface that cannot tell who the speaker is gets `unavailable` at
+ * once and the call stays held. Combined with approvers the card is still the speaker's alone,
+ * and the runtime accepts their press only when the approvers name them or they are an owner;
+ * otherwise the call stays held. It governs the card only: a message that confirms the held call
+ * is judged as for any call, so a tool that must act on the speaker's press alone checks
+ * `ToolTurn.approvedPrompt` and `ToolTurn.approvedBy` in `run`. Anything but `"speaker"` leaves
+ * the card as every card is.
  *
  * Aborting `supersede` withdraws the call the hold held, when the plugin no longer wants it
  * (a newer request replaced it, its subject is gone): its approval card is closed, also after
@@ -39,6 +51,7 @@ export type HoldDescription =
 			text: string;
 			copy?: NonNullable<ApprovalDetails["copy"]>;
 			supersede?: AbortSignal;
+			approval?: "speaker";
 	  };
 
 /**

package/src/core/interactions/prompts.ts

@@ -95,6 +95,16 @@ export interface ApprovalOptions {
 	 * conversation an approval it does not name is not accepted for a call that names approvers.
 	 */
 	approvers?: readonly string[];
+	/**
+	 * When true the card is the scope's speaker's alone: they answer it on any of their identities
+	 * the surface knows, at the call's `minTier` checked again when they answer, and the owners do
+	 * not, whatever the scope escalates to. Without a speaker, below the tier, or on a surface that
+	 * cannot tell, it resolves `unavailable` at once. With `approvers`, the speaker's press is
+	 * accepted only if they are named (the runtime refuses the rest). A surface that cannot honour
+	 * it must resolve `unavailable` rather than show the card to the owners. Absent or false leaves
+	 * the card as every card is.
+	 */
+	speakerOnly?: boolean;
 	/**
 	 * Called with who approved the call, before the approval resolves `approved`; not called for a
 	 * refusal, or by a surface that does not know who answered.

package/src/core/modules/delegation/web-research-worker.ts

@@ -1,20 +1,12 @@
-import { mkdirSync } from "node:fs";
-import {
-	createAgentSession,
-	DefaultResourceLoader,
-	type ModelRuntime,
-	SessionManager,
-	SettingsManager,
-} from "@earendil-works/pi-coding-agent";
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { PluginError } from "../../errors.ts";
 import {
 	formatModelRef,
 	type ModelRef,
 	type ThinkingLevel,
 } from "../../models.ts";
-import { runWorkerTask } from "../../runtime/worker-task.ts";
-import { activeToolsExtension } from "../../shared/active-tools.ts";
 import { packageDir } from "../../shared/package-dir.ts";
+import { runWorkerSession } from "./worker-session.ts";
 
 const WEB_TOOLS = ["web_search", "fetch_content", "get_search_content"];
 
@@ -50,39 +42,19 @@ export class WebResearchWorker {
 	constructor(options: WebResearchWorkerOptions) {
 		this.#options = options;
 		this.#webAccessPath = webAccessDir();
-		mkdirSync(options.workDir, { recursive: true });
 	}
 
-	async run(task: string, signal: AbortSignal): Promise<string> {
+	run(task: string, signal: AbortSignal): Promise<string> {
 		const { modelRuntime, agentDir, workDir, model, thinking } = this.#options;
-		const resourceLoader = new DefaultResourceLoader({
-			cwd: workDir,
-			agentDir,
-			noExtensions: true,
-			noSkills: true,
-			noPromptTemplates: true,
-			noThemes: true,
-			noContextFiles: true,
-			additionalExtensionPaths: [this.#webAccessPath],
-			extensionFactories: [
-				{ name: "web-only", factory: activeToolsExtension(() => WEB_TOOLS) },
-			],
-			appendSystemPrompt: [WORKER_PROMPT],
-		});
-		await resourceLoader.reload();
-		const { session } = await createAgentSession({
-			cwd: workDir,
-			agentDir,
-			thinkingLevel: thinking,
-			modelRuntime,
-			resourceLoader,
-			sessionManager: SessionManager.inMemory(workDir),
-			settingsManager: SettingsManager.inMemory({}),
-			noTools: "builtin",
-		});
-		return runWorkerTask(session, {
+		return runWorkerSession({
 			modelRuntime,
+			agentDir,
+			workDir,
 			model: formatModelRef(model),
+			thinking,
+			prompt: WORKER_PROMPT,
+			extensionPaths: [this.#webAccessPath],
+			toolNames: WEB_TOOLS,
 			task,
 			signal,
 			aborted: "the worker ran out of time",