pi-roundtable 0.9.3 → 0.9.6

package/CHANGELOG.md

@@ -5,6 +5,38 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.6] - 2026-10-10
+
+### Fixed
+
+- The compaction tiers measure the context a compaction left as a request sends it, system prompt and tool definitions included: the first request after the compaction reports it, and until then the conversation's estimate gets the fixed part the last request before it carried (what it sent less the estimate of its messages). They measured the conversation alone, so a session with a large fixed part (over 100k of tools) that compacted to about 270k kept its next compaction at 300k and compacted again every few tool results. `LatestCompaction` adds `measured`, and the `conversation compacted` log adds `contextAfter`, the measure the tiers use, beside `tokensAfter`.
+
+## [0.9.5] - 2026-10-10
+
+0.9.4 was tagged but never published (its release checks failed on the recorded prompt texts); everything listed under it is released in 0.9.5.
+
+### Added
+
+- `attach_file({ path, filename? })`: a core tool, in sessions with a workspace (an agent's), that attaches a file from the workspace or the scratch dir to the turn's reply with `attachReplyFile`, under `REPLY_FILE_LIMITS`. Its tier defaults to the owner.
+- `discord_send_message` and `discord_edit_message` take each file as exactly one of `path` or `dataBase64`: a path names a local file inside the session's workspace or scratch dir (resolved through symlinks), read when the call runs, with `filename` defaulting to its base name; the 8 MiB total still applies. A session without a workspace, and remote MCP, take only `dataBase64`. The descriptions tell the model to prefer `path` and keep base64 for small generated data.
+- `SessionContext.workspace` and `ToolTurn.workspace` (`{ workspace, scratchDir? }`): the roots a session's tools may read and save files by path in; `testPlugin`'s `runTool` takes a `workspace` option to set it.
+- `approvalCard(call, workspace?)` lists each file a held call sends by path with its size.
+- `ThreadHost.send(threadId, text)` (optional) posts one editable message in a dispatch thread, and a `DispatchThread` whose host has it carries `interim`, the thread's `InterimPosts`; the Discord thread host and `FakeThreadHost` (which records edits in `edits`) implement it. The kit exports `InterimPoster` and `InterimPosterOptions`, so a worker of a plugin's own posts its interim text as the host's turns do.
+
+- `PromptWait` and `LateAnswer`: `Prompts.confirm` and `Prompts.ask` take an optional last `wait`, whose `late(answer)` returns the text of a turn for an answer given after the turn stopped waiting. With it a prompt may resolve the new `Approval` `pending`, or `"pending"` from `ask`, and stay open. Prompts without it, such as a coding worker's, wait for their answer or their turn's stop.
+- `discord.cardGraceSeconds` (default 120): how long a turn waits on its owner card before it goes on without the answer.
+- `HostEnv.scratchDir`: the host's scratch dir, when it has one, so a plugin that runs a shell of its own gives it the same TMPDIR and hold roots as the agents' (`HostEnvironment.scratchDir`; `defineRoundtable` sets it from `scratchDir`).
+
+### Changed
+
+- The agents' prompt tells them to show a file with `attach_file` or a `discord_send_message` file `path`, and never to read an image or base64 a file to send it.
+- Owner cards no longer expire after 30 minutes, and say nothing of a countdown. A turn waits on its approval or `ask_user` card for the grace period; answered within it, the turn goes on as before. After it, `ask_user` returns that the person has not answered yet and the model ends its turn saying it is waiting, and a held action is blocked as awaiting approval (not held for a text confirmation). The card stays open for the life of the process, and answering it later starts a turn in the same conversation, as a message from whoever answered: a question's turn carries the question and the answer; an approval lets exactly the call shown on the card run once, under the same gate and tier rules, in the turn that tells the model to make it and report the result; a refusal's turn says so. A late card is edited and disabled as before, and a second press does nothing. A stopped turn cancels only a card it still waits on. A coding worker's cards keep the worker waiting, with no deadline. After a restart a card's press says it is no longer valid and to ask again. The `ask_user` description says so instead of "30 minutes".
+
+### Fixed
+
+- An approval card in an owner conversation sizes a file sent by a relative path from the session's own directory, as the send reads it, instead of showing it as not found.
+- The webchat OIDC test of expired and not-yet-valid tokens no longer fails when the clock crosses a second between signing and verifying.
+
 ## [0.9.3] - 2026-10-10
 
 ### Fixed

package/README.md

@@ -194,6 +194,10 @@ When a conversation is started over in a server channel or thread, the assistant
 | text | `─── new conversation ───` | The divider's text |
 | `false` | | Post no divider |
 
+An approval card or an `ask_user` question holds its turn for `discord.cardGraceSeconds` (default `120`).
+Answered within it, the turn goes on with the answer; otherwise the turn ends saying it is waiting, the card stays open with no deadline, and answering it later starts a new turn in that conversation with the answer, or with the result of the approved action.
+A coding worker's cards keep the worker waiting instead.
+
 ## Threat model
 
 pi-roundtable runs one assistant for one owner.

package/README.zh-TW.md

@@ -182,6 +182,10 @@ export default {
 | `messageChars` | `500` | 訊息截斷的長度 |
 | `botMessageChars` | `80` | 其他 bot 訊息截斷的長度 |
 
+核准卡和 `ask_user` 問題會讓這一輪等 `discord.cardGraceSeconds` 秒（預設 `120`）。
+在這段時間內回答，這一輪就帶著答案繼續；沒回答的話，這一輪會說它在等你，然後結束，卡片繼續開著、沒有期限，之後再回答就會在同一個對話開新的一輪，帶上你的答案，或核准後那個動作的結果。
+coding worker 的卡片則會讓 worker 一直等下去。
+
 ## 威脅模型
 
 pi-roundtable 為一位擁有者執行一個助理。

package/docs/plugins.md

@@ -61,13 +61,14 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
   Ordinary 48 MP images and thin 9000×1 images remain admitted.
   This helper is not a downloader or filesystem validator.
 - Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard` and `canonicalJson` for the cards of held actions.
+  `InterimPoster(posts, { logger, channel, primaryChars?, editMs? })` posts a run's [interim text](#interim-text-what-a-turn-writes-before-its-final-answer) to an `InterimPosts`, such as a dispatch thread's `interim`: feed it `messageEnd(message)` and `toolStart(name)` from the session's events, bind `() => poster.flush()` as the slot's `beforeCard`, and `await poster.flush()` before the final report.
 - Diagnostics: `scrubDiagnostic(text, max = 600)` masks credentials (URL userinfo, token shapes, secret-named assignments and JSON fields, `Authorization`/`Cookie`/`x-api-key` headers, JWTs, PEM blocks), turns control characters other than tab and newline into spaces, and cuts the result at `max` characters.
   It scans only the first `max * 4` characters (at least 4,096), in linear time, so pass it git, gh or provider error text before showing that text to a user.
 - Shell: `SHELL_TOOLS`, and `shellHoldRule` and `shellHoldRuleFor(policy)`, the hold rule that keeps risky host-shell commands behind the owner's approval; see [the shell rule](#the-shell-rule).
 - Tools: `textToolsExtension`, `requiredString`, `stringList` (with `toolText` and `toolError`) for tools that return text.
 - Mirroring a built-in tool in a worker that cannot reach the host: `SCHEDULE_TOOLS`, `scheduleToolSpecs({ locale, timeZone })`, `isScheduleTool`, `callScheduleTool`, `DELEGATE_TOOL` and `DELEGATE_TOOL_SPEC`.
   The specs take the locale and time zone for their descriptions, so the worker needs no process-wide setting.
-- Compaction: `CompactionTiers` gives a session the core's compaction tiers (`settings()` for Pi's `SettingsManager`, `wrapCompactor(factory, onBypass, prepare?)` to hold a compaction extension back past the ceiling and change what it is given first, `latest()`), with `SOFT_COMPACT_TOKENS` (300,000), `HARD_COMPACT_TOKENS` (500,000), `COMPACT_HEADROOM_TOKENS` (50,000), `compactionEngine(details, engine)` and the types `CompactionEngine`, `CompactionHistory` and `LatestCompaction`. `summaryProjection(messages, history?)` is what a shared conversation's compaction may summarize, without anyone's private memory, prompt states, or reasoning, and `privateCompaction(preparation, additionalMessages?)` sets a `session_before_compact` preparation to it. Optional surrounding history pairs calls/results split across summary, prefix and kept context. Independent shared sessions use `memoryProjection(messages, view)` on requests and `hidesPrivateExchange(messages, view)` for raw replay guards (`MemoryView`: `shared` and `reader`; legacy attribution is internal to the bridge guard, not a projection option). `recordMemoryTurn(manager, reader, privateMemory)` appends `MEMORY_TURN_ENTRY` (`roundtable-memory-turn`) before prompting and returns a marker for memory first used later in that turn; `carriesMemory(message)` recognizes built-in memory calls/results and custom `privateTo` results, including immediate failures and unanswered calls. `bridgeHistoryHidesMemory(rawBranch, reader)` checks those records and raw exchanges across compaction; SYSTEM is a reader of its own there, and the core's SYSTEM-as-primary-owner attribution and its pre-scope legacy attribution stay inside the core.
+- Compaction: `CompactionTiers` gives a session the core's compaction tiers (`settings()` for Pi's `SettingsManager`, `wrapCompactor(factory, onBypass, prepare?)` to hold a compaction extension back past the ceiling and change what it is given first, `latest()`: the latest compaction's `contextTokens`, the context it left as a request sends it, system prompt and tools included, `measured` once a request after it reported its usage), with `SOFT_COMPACT_TOKENS` (300,000), `HARD_COMPACT_TOKENS` (500,000), `COMPACT_HEADROOM_TOKENS` (50,000), `compactionEngine(details, engine)` and the types `CompactionEngine`, `CompactionHistory` and `LatestCompaction`. `summaryProjection(messages, history?)` is what a shared conversation's compaction may summarize, without anyone's private memory, prompt states, or reasoning, and `privateCompaction(preparation, additionalMessages?)` sets a `session_before_compact` preparation to it. Optional surrounding history pairs calls/results split across summary, prefix and kept context. Independent shared sessions use `memoryProjection(messages, view)` on requests and `hidesPrivateExchange(messages, view)` for raw replay guards (`MemoryView`: `shared` and `reader`; legacy attribution is internal to the bridge guard, not a projection option). `recordMemoryTurn(manager, reader, privateMemory)` appends `MEMORY_TURN_ENTRY` (`roundtable-memory-turn`) before prompting and returns a marker for memory first used later in that turn; `carriesMemory(message)` recognizes built-in memory calls/results and custom `privateTo` results, including immediate failures and unanswered calls. `bridgeHistoryHidesMemory(rawBranch, reader)` checks those records and raw exchanges across compaction; SYSTEM is a reader of its own there, and the core's SYSTEM-as-primary-owner attribution and its pre-scope legacy attribution stay inside the core.
 - Jev compaction: `jevCompact(input, options)` compacts through Jev (pi-jev-compaction 1.0.0) and returns `{ compaction }` or `{ skipped, detail? }` (a `JevSkipReason`: pi-jev-compaction's fallbacks `no_key`, `aborted`, `nothing_to_compact`, `no_candidates`, `cannot_fit`, `jev_error`, `reduction_too_small`, or `previous_summary_too_large`), for Pi's own summary to run instead.
   Its summary carries the previous summary once, as the transcript's `[previous compaction]` message, with `estimatedTokensAfter` measured on the final text; a previous summary over `previousSummaryLimitTokens` (default `JEV_PREVIOUS_SUMMARY_LIMIT_TOKENS`, 60,000) skips without calling Jev, so Pi's summary condenses the chain.
   Jev judges with `goal` (default `JEV_GOAL`: keep the tool results that set rules still in force, drop stale lookups, listings and finished edits), and the summary ends with a `## Rules loaded before this compaction` section naming each rule load among the summarized messages (tool name and JSON arguments cut at 200 characters) for the agent to load again; `ruleLoad(tool, args)` picks them (default `isRuleLoad`: tools ending in `invoke-skill` or `get-system-prompt`, and tools ending in `read` whose `path` is a `SKILL.md`, an `AGENTS.md` or under `.agents/skills/`).
@@ -127,7 +128,7 @@ A plugin that replaces `IDENTITY` replaces this too: the declarations are the bu
 | Field | What it is |
 |---|---|
 | `logger` | The host's logger with `plugin: <your name>` on every line; each line is JSON on stdout. Its type is `Logger` (`debug`, `info`, `warn`, `error`, `fatal`, `child(fields)`), which a pino logger satisfies |
-| `env` | The host's own environment for the run: `locale`, `timeZone` (an IANA zone), and `now()`; read the zone from here rather than from the process |
+| `env` | The host's own environment for the run: `locale`, `timeZone` (an IANA zone), `now()`, and `scratchDir` when the host has one; read the zone from here rather than from the process, and give `scratchDir` to a shell the plugin runs itself |
 | `database()` | The host's one PostgreSQL connection (a Bun `SQL`), already migrated |
 | `toolTiers` | What each tool needs; ask it when a tool is used, not during setup |
 | `events` | Where the core reports turns and team changes to every plugin's handlers |
@@ -556,7 +557,8 @@ Once a turn has used a file, the model reads it with `read_attachment`, and a to
 ### `tools`: what agents can call
 
 `defineTool` takes a name (lowercase words joined by underscores), a description the model reads to decide when to call it, a Typebox parameter schema, the lowest tier that may call it, and the function.
-`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, `attachFile`, and `attachment`.
+`run` receives the arguments, already typed, and the turn: the speaker, the channel, the agent, an abort signal, `workspace`, `attachFile`, and `attachment`.
+`turn.workspace` is `{ workspace, scratchDir? }` in a session with a shared workspace (an agent's), the same roots as `SessionContext.workspace`, and undefined elsewhere: a tool that makes a file can save it there, under the scratch dir when there is one, and name its path, so the model sends it on with `attach_file` or a `discord_send_message` file `path` instead of carrying its bytes.
 It returns the text the model reads.
 `turn.attachment(file)` opens a file someone attached to the conversation, by the name the turn's `## Attachments` block lists, and returns `{ file, name, contentType, size, bytes() }`: a tool passes a user's file on without the model carrying its bytes.
 Only the conversation's own files open; a path, a hidden name, or a missing file throws a `ToolRefusal` the model reads.
@@ -644,6 +646,9 @@ Raw `sessionTools` and Pi package tools may import and call `attachReplyFile` du
 It uses the current asynchronous turn, not a global channel queue, so simultaneous turns and nested conversation turns keep separate files.
 A Pi package should use the host's peer dependency on `pi-roundtable`, not bundle another copy of it.
 Transient `SessionContext.runTask` tasks return only text and cannot attach to their parent's reply.
+
+The model attaches a file it already has on disk with the core's `attach_file({ path, filename? })`. A session with a workspace (`SessionContext.workspace`, an agent's) registers it; the path must resolve, symlinks followed, inside the workspace or the scratch dir, a relative path resolves in the workspace, and `filename` defaults to the path's base name. It queues the file with `attachReplyFile`, so `REPLY_FILE_LIMITS` apply and a surface without reply files refuses it as a tool error; its result tells the model the file will appear with its reply. It holds nothing, since it only posts in the channel the turn answers in, and its tier defaults to the owner, like any tool the core's table does not name.
+The Discord tools that upload, `discord_send_message` and `discord_edit_message`, take each file as exactly one of `path` (a local file, read when the call runs, with the same roots; `filename` defaults to its base name) or `dataBase64` with a `filename`, at most 8 MiB in all. A session without a workspace takes only `dataBase64`, and so does remote MCP, whose schemas stay inline only. A path outside the roots, a missing file, or a directory is a tool error naming the path. A held call's card (`approvalCard(call, workspace?)`) lists each file it sends by path with the file's size now, never its bytes.
 Calling the helper outside `context.turns.run` or an agent-team turn, or after that turn finishes, throws `ReplyFileError`; direct standalone runtime calls have no reply collector.
 Await work that produces files before returning from the tool.
 A standalone isolated worker may wrap its complete awaited turn in `withReplyFiles(supported, run)` from the main entry.
@@ -718,7 +723,7 @@ A rule whose held call stands for others can answer `approvalTier(tool, input, c
 `shellHoldRule` in `pi-roundtable/kit` judges the agents' `bash`, `write` and `edit` calls; the agent server links it, and a session without a workspace has no shell.
 Its scratch roots are the shared workspace (`HoldContext.workspace`) and the scratch dir (`HoldContext.scratchDir`).
 The scratch dir is the config's `scratchDir`, by default `<os temp dir>/<discord.rootCommand>-scratch` (such as `/tmp/roundtable-scratch`); the agent server creates it with mode 0700 at startup and refuses one that is a symlink or another user's, and the agents' `bash` runs with `TMPDIR` pointing to it, so `mktemp` and tools write there.
-`AgentSessions.scratchDir` carries it to a runtime, and the agents' prompt tells them to write temporary files there.
+`AgentSessions.scratchDir` carries it to a runtime, and the agents' prompt tells them to write temporary files there, and to show a file with `attach_file` or a `discord_send_message` file `path` rather than reading an image or base64-encoding it.
 
 - A `>`, `>>` or `tee` target, and a `write` or `edit` path, inside a scratch root run; anything else, the rest of `/tmp` included, is held.
 - An `rm` runs when every operand resolves inside a scratch root and none is a root itself or `/`. Operands resolve after the variables assigned earlier in the same command line (`NAME=value` and `export NAME=value` with literal values; `$TMPDIR` is the scratch dir and `$HOME` the service user's home), from the directory of the last `cd`, through `..` and, for paths that exist, symlinks, so a link out of a root is held. A glob is judged by its directory part. A command substitution, an unknown variable, `~user`, an `rm` without operands, and `xargs rm` are held.
@@ -2391,6 +2396,22 @@ On Discord the owners are every owner with a Discord identity, and the primary o
 A principal with no Discord identity, such as the reporter of a background report, answers nothing there, so their card goes to the owners; so does an owner-tier call of a turn whose tier defaulted to owner when its principal is not an owner.
 The web chat shows prompts to the conversation's person only: its owners are not on it, so an approval above that person's tier expires at once whatever the scope says.
 
+#### A prompt that outlives its turn: `PromptWait`
+
+`confirm(title, message, signal?, minTier?, wait?)` and `ask(title, question, signal?, wait?)` take an optional `PromptWait`, whose `late(answer)` hears a `LateAnswer` (`{ kind: "approval", approved, by }` or `{ kind: "question", answer, by }`, `by` naming who answered) and returns the text of the turn that tells the conversation, or undefined for none.
+Given one, a surface may stop the turn's wait after a grace period: `confirm` then resolves `pending` and `ask` resolves `"pending"`, the prompt stays open, and when it is answered later the surface starts a turn in the prompt's conversation with that text, as a message from whoever answered, so the conversation's claim answers it as theirs.
+Without one, a prompt waits for its answer, or for its turn's stop; a surface that cannot start a turn ignores `wait` and waits too.
+A stop cancels a prompt only while its turn still waits on it; after that the prompt belongs to the conversation.
+
+The runtime gives both of its prompts a `wait`.
+`ask_user` then tells the model the person has not answered yet and to end its turn saying it is waiting, without asking again, and the late answer's turn carries the question and the answer.
+A held action's call is blocked as awaiting the approval, and is not held for a later message; a late approval lets that exact call (same tool, same canonical input) run once in whichever turn makes it next, and its turn tells the model to make it now and report the result, so the call runs under the gate and tier rules every call does; a late refusal starts a turn that says so.
+A coding worker's cards give no `wait`, since nothing could resume a worker: it waits for the answer, and the waiting does not count against its time.
+
+On Discord the grace period is `discord.cardGraceSeconds` (default 120), and the cards carry no countdown.
+A card answered late is edited to show the answer with its controls disabled, as one answered in time is; a second press finds it answered.
+Open cards live in memory: after a restart, pressing one replies, to the presser alone, that it is no longer valid and to ask again.
+
 #### Interim text: what a turn writes before its final answer
 
 A model often writes text in an assistant message that then calls tools, such as a proposal before it asks `ask_user` "go with this version?".
@@ -2402,7 +2423,8 @@ On a surface that gives `interim`, and in the agent server's channels through th
 Before any card, an `ask_user` question or an approval, the host posts the pending text and brings the progress message up to date, so what the model wrote before the card shows above it.
 The final reply is posted at the end as before, with its thinking line; an intermediate message is never the final one, so nothing is posted twice, and a steered run keeps its final text.
 A failed interim post or edit is logged and never fails the turn.
-Turns with nowhere to post, such as transient tasks, coding workers, and turns of a claim that passes its own `reply` to `context.turns.run`, post only their final reply.
+Turns with nowhere to post, such as transient tasks and turns of a claim that passes its own `reply` to `context.turns.run`, post only their final reply.
+A coding worker posts the same way into its dispatch thread, under the name its report uses, when the thread's host can edit its posts (`ThreadHost.send`, which the Discord thread host has; a `DispatchThread` then carries `interim`): its approval cards come after the text it wrote before them, and its report is posted once, at the end.
 A runtime that fills [the `runtime` slot](#the-runtime-slot-replace-pi) receives the place to post as `TurnRequest.interim` and may use it or not.
 
 The config's `interimText: "off"` posts only the final reply (default `"on"`), and `interimPrimaryChars` sets the length of primary text (default 400).
@@ -2864,7 +2886,7 @@ It returns:
 | `contribution` | What the plugin added, as the host would collect it: `tools`, `prompt`, `seeds`, `events`, `services`, `http`, and the rest |
 | `tools`, `tiers` | The tool names, and the table that says what tier each needs |
 | `holds` | The plugin's `holdRules` chained as the host links them (`holdChain`): `holds(tool, input, { workspace?, scratchDir? })` returns the description of a call that must be approved first, or `undefined` |
-| `runTool(name, args, { speaker, channel }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads |
+| `runTool(name, args, { speaker, channel, workspace }?)` | Runs a tool the way an agent's turn would, in the channel (default `test:1`) for the speaker, and returns the text the model reads; `workspace` (`{ workspace, scratchDir? }`) is the session's `turn.workspace` |
 | `files` | Accepted files from `runTool`, recorded as `{ channel, file: ReplyFile }`; inject a surface with `supportsFiles: true` and pass its channel to test attachment tools |
 | `events` | The events the plugin itself reported through `context.events`, and those of `context.turns` |
 | `conversations`, `turns`, `surfaces` | What the plugin sees as `context.conversations`, `context.turns`, and `context.surfaces`, for a test to drive its claims |
@@ -3314,6 +3336,7 @@ Import from the entries listed below; source area files are internal.
 | `Judge` | `pi-roundtable` | type |
 | `JudgeError` | `pi-roundtable` | value |
 | `JudgeModel` | `pi-roundtable` | type |
+| `LateAnswer` | `pi-roundtable` | type |
 | `LinkedSessions` | `pi-roundtable` | type |
 | `LinkSource` | `pi-roundtable` | type |
 | `ListenerAddress` | `pi-roundtable` | type |
@@ -3353,6 +3376,7 @@ Import from the entries listed below; source area files are internal.
 | `PromptScope` | `pi-roundtable` | type |
 | `PromptSection` | `pi-roundtable` | type |
 | `PromptTurn` | `pi-roundtable` | type |
+| `PromptWait` | `pi-roundtable` | type |
 | `Prompts` | `pi-roundtable` | type |
 | `Pronouns` | `pi-roundtable` | type |
 | `ProviderError` | `pi-roundtable` | value |
@@ -3587,6 +3611,8 @@ Import from the entries listed below; source area files are internal.
 | `CompactionHistory` | `pi-roundtable/kit` | type |
 | `LatestCompaction` | `pi-roundtable/kit` | type |
 | `isRuleLoad` | `pi-roundtable/kit` | value |
+| `InterimPoster` | `pi-roundtable/kit` | value |
+| `InterimPosterOptions` | `pi-roundtable/kit` | type |
 | `JEV_COMPACTION_ENGINE` | `pi-roundtable/kit` | value |
 | `JEV_GOAL` | `pi-roundtable/kit` | value |
 | `JEV_PREVIOUS_SUMMARY_LIMIT_TOKENS` | `pi-roundtable/kit` | value |

package/package.json

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

package/src/core/agents/agent-prompt.ts

@@ -37,7 +37,7 @@ export function agentSystemPrompt(input: {
 		`You are "${agent.displayName}" (agent name \`${agent.name}\`), one of ${o.name}'s agents in ${o.his} Discord agent server. Each agent owns one channel and one conversation; you all share ${o.his} tools and ${o.his} memory.`,
 		roleText(agent, coordinator, who),
 		`The team: agent_list shows every agent and group; agent_get and agent_update read and improve any agent's prompt, display name, model, and thinking level, yours included; agent_create adds an agent with its own channel; ${input.avatars === false ? "" : "agent_avatar redraws an avatar; "}schedule_list with agent reads another agent's schedules. A message marked as coming from another agent is that agent speaking, not ${w.name}; only ${w.name} approves held actions.`,
-		`Your shell and file tools run on ${o.his} VPS as the user ${shellUser}, in the shared workspace ${workDir}.${input.scratchDir ? ` Write temporary files under the scratch dir ${input.scratchDir} ($TMPDIR), not elsewhere in /tmp.` : ""} Commands that are destructive or change the system, and writes outside the workspace${input.scratchDir ? " and the scratch dir" : ""}, are held for ${w.his} confirmation: tell ${w.him} exactly what will run and ask ${w.him} to confirm.`,
+		`Your shell and file tools run on ${o.his} VPS as the user ${shellUser}, in the shared workspace ${workDir}.${input.scratchDir ? ` Write temporary files under the scratch dir ${input.scratchDir} ($TMPDIR), not elsewhere in /tmp.` : ""} Commands that are destructive or change the system, and writes outside the workspace${input.scratchDir ? " and the scratch dir" : ""}, are held for ${w.his} confirmation: tell ${w.him} exactly what will run and ask ${w.him} to confirm. To show a file you have, attach it to your reply with attach_file or give its path to discord_send_message; never read an image or base64 a file to send it.`,
 	];
 	if (group) {
 		const others = group.members

package/src/core/builtin/discord-admin.ts

@@ -30,8 +30,12 @@ export function discordAdminPlugin(
 			const { connection } = services.get(DISCORD);
 			return {
 				sessionTools: [
-					fixed("discord-admin", () =>
-						discordAdminExtension(connection.ownerOperations(), owner),
+					fixed("discord-admin", (session) =>
+						discordAdminExtension(
+							connection.ownerOperations(),
+							owner,
+							session.workspace,
+						),
 					),
 				],
 				// Administering the server stays with the owner until an operator lowers a tool.

package/src/core/builtin/discord.ts

@@ -67,6 +67,11 @@ export interface DiscordOptions {
 	channelContext?: ChannelContextOptions | false;
 	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: a short English divider. */
 	freshMarker?: string | false;
+	/**
+	 * How long a turn waits on its owner card before it goes on without the answer, leaving the
+	 * card open; a later answer starts a new turn. Default `CARD_GRACE_MS`, two minutes.
+	 */
+	cardGraceMs?: number;
 }
 
 /**
@@ -96,6 +101,10 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 				...(identity ? { identity } : {}),
 				channel: (channelId) => connected.cardChannel(channelId),
 				logger,
+				...(options.cardGraceMs === undefined
+					? {}
+					: { graceMs: options.cardGraceMs }),
+				resume: (turn) => connected.resume(turn),
 			});
 			const connected = new DiscordSurface({
 				token: options.token,
@@ -124,6 +133,7 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 					open: (parentId, name, line) =>
 						connected.threadHost().open(parentId, name, line),
 					post: (threadId, text) => connected.threadHost().post(threadId, text),
+					send: (threadId, text) => connected.threadHost().send(threadId, text),
 					close: (threadId) => connected.threadHost().close(threadId),
 				},
 				ledgerPath: join(options.dataDir, "dispatch-threads.json"),

package/src/core/config/adapters.ts

@@ -50,6 +50,52 @@ export interface DiscordConfig {
 	 * never in a direct message. Default `─── new conversation ───`; `false` posts none.
 	 */
 	freshMarker?: string | false;
+	/**
+	 * Seconds a turn waits on an owner card (an approval or an `ask_user` question) before it goes
+	 * on without the answer; the card stays open, and answering it later starts a new turn with
+	 * the answer. Default 120.
+	 */
+	cardGraceSeconds?: number;
+}
+
+/** The Discord settings with every default filled in. */
+export interface ResolvedDiscord {
+	token: string;
+	guild: string;
+	entryChannel: string;
+	rootCommand: string;
+	admin: boolean;
+	refusalHint?: string;
+	agentMemory?: "everyone" | "owners";
+	/** As configured: `{}` when left out, so the defaults apply, or `false`. */
+	channelContext: NonNullable<DiscordConfig["channelContext"]>;
+	freshMarker?: string | false;
+	cardGraceSeconds: number;
+}
+
+/** The configured Discord settings, defaults filled in; `rootCommand` is the host's slug. */
+export function resolvedDiscord(
+	discord: DiscordConfig,
+	rootCommand: string,
+): ResolvedDiscord {
+	return {
+		token: discord.token,
+		guild: discord.guild,
+		entryChannel: discord.entryChannel,
+		rootCommand,
+		admin: discord.admin ?? true,
+		...(discord.refusalHint === undefined
+			? {}
+			: { refusalHint: discord.refusalHint }),
+		...(discord.agentMemory === undefined
+			? {}
+			: { agentMemory: discord.agentMemory }),
+		channelContext: discord.channelContext ?? {},
+		...(discord.freshMarker === undefined
+			? {}
+			: { freshMarker: discord.freshMarker }),
+		cardGraceSeconds: discord.cardGraceSeconds ?? 120,
+	};
 }
 
 /** What `discord.channelContext` takes besides `false`. */
@@ -72,6 +118,7 @@ export const discordShape = shape({
 	agentMemory: optional(oneOf<"everyone" | "owners">("everyone", "owners")),
 	channelContext: optional(orOff(channelContextShape)),
 	freshMarker: optional(orOff(text)),
+	cardGraceSeconds: optional(integer(1, 86_400)),
 });
 
 /** The adapters `adapters` takes, by the name their factory gives them. */

package/src/core/config/config.ts

@@ -19,7 +19,13 @@ import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
 import type { ChannelKey } from "../sessions.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
 import { type AccessConfig, accessOf, accessShape } from "./access.ts";
-import { type DiscordConfig, discordShape, liftAdapters } from "./adapters.ts";
+import {
+	type DiscordConfig,
+	discordShape,
+	liftAdapters,
+	type ResolvedDiscord,
+	resolvedDiscord,
+} from "./adapters.ts";
 import {
 	bool,
 	guarded,
@@ -297,18 +303,7 @@ export interface ResolvedConfig {
 	/** What the configuration wrote in a deprecated form, which the host logs once. */
 	deprecations: string[];
 	/** Undefined on a host without Discord. */
-	discord?: {
-		token: string;
-		guild: string;
-		entryChannel: string;
-		rootCommand: string;
-		admin: boolean;
-		refusalHint?: string;
-		agentMemory?: "everyone" | "owners";
-		/** As configured: `{}` when left out, so the defaults apply, or `false`. */
-		channelContext: NonNullable<DiscordConfig["channelContext"]>;
-		freshMarker?: string | false;
-	};
+	discord?: ResolvedDiscord;
 	databaseUrl: string;
 	dataDir: string;
 	agentDir: string;
@@ -423,27 +418,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 			name: primaryOwner.name,
 			pronouns: primaryOwner.pronouns,
 		},
-		...(discord
-			? {
-					discord: {
-						token: discord.token,
-						guild: discord.guild,
-						entryChannel: discord.entryChannel,
-						rootCommand: slug,
-						admin: discord.admin ?? true,
-						...(discord.refusalHint === undefined
-							? {}
-							: { refusalHint: discord.refusalHint }),
-						...(discord.agentMemory === undefined
-							? {}
-							: { agentMemory: discord.agentMemory }),
-						channelContext: discord.channelContext ?? {},
-						...(discord.freshMarker === undefined
-							? {}
-							: { freshMarker: discord.freshMarker }),
-					},
-				}
-			: {}),
+		...(discord ? { discord: resolvedDiscord(discord, slug) } : {}),
 		databaseUrl: config.database.url,
 		dataDir: config.dataDir,
 		agentDir: config.agentDir ?? `${config.dataDir}/pi`,

package/src/core/define-roundtable.ts

@@ -172,6 +172,7 @@ function discordAssembly(
 			...(discord.freshMarker === undefined
 				? {}
 				: { freshMarker: discord.freshMarker }),
+			cardGraceMs: discord.cardGraceSeconds * 1_000,
 		}),
 		admin: discord.admin ? [discordAdminPlugin({ owner })] : [],
 		skills: config.skills
@@ -274,6 +275,7 @@ export async function defineRoundtable(
 				assistant: name,
 				rootCommand: config.slug,
 				agentDir: config.agentDir,
+				scratchDir: config.scratchDir,
 			},
 			database: { url: config.databaseUrl },
 			dataDir: config.dataDir,

package/src/core/define.ts

@@ -29,6 +29,11 @@ export interface ToolTurn {
 	/** The agent whose turn it is. */
 	agent: AgentTurnScope | undefined;
 	signal: AbortSignal | undefined;
+	/**
+	 * The session's shared workspace and scratch dir, where a tool may save a file for the model to
+	 * pass on by path; undefined for a session without a workspace.
+	 */
+	workspace?: { workspace: string; scratchDir?: string };
 	/** Queues a file for this turn's successful reply; throws ReplyFileError when refused. */
 	attachFile(file: ReplyFile): void;
 	/**
@@ -124,6 +129,9 @@ export function defineTool<Schema extends TObject>(
 									channel: context.turnChannel,
 									agent: context.agent,
 									signal,
+									...(context.workspace
+										? { workspace: context.workspace }
+										: {}),
 									attachFile: attachReplyFile,
 									attachment: async (file) => {
 										if (context.attachmentDir === undefined)

package/src/core/discord/channel-files.ts

@@ -0,0 +1,107 @@
+import {
+	findWorkspaceFile,
+	readWorkspaceFile,
+	type WorkspaceFile,
+	WorkspaceFileError,
+	type WorkspaceRoots,
+} from "../shared/workspace-files.ts";
+import {
+	CHANNEL_UPLOAD_MAX_BYTES,
+	ChannelToolError,
+	FILE_CHANNEL_TOOLS,
+} from "./channel-operations.ts";
+
+interface SessionFile {
+	path?: string;
+	filename?: string;
+	dataBase64?: string;
+	description?: string;
+}
+
+const refuse = (code: string, detail: string) =>
+	new ChannelToolError(`${code}: ${detail}`);
+
+/** The bytes a base64 string carries, before it is checked; `parseChannelTool` checks it. */
+const base64Bytes = (data: string) =>
+	Math.floor((data.length * 3) / 4) -
+	(data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0);
+
+/**
+ * A session's call to a file tool in the inline form `parseChannelTool` takes: each file names
+ * exactly one of `path` or `dataBase64`, and a path is read from the session's workspace or scratch
+ * dir. Without `roots` only inline files are accepted. Other tools' arguments pass unchanged.
+ */
+export async function resolveChannelFiles(
+	tool: string,
+	args: Record<string, unknown>,
+	roots: WorkspaceRoots | undefined,
+): Promise<Record<string, unknown>> {
+	if (!FILE_CHANNEL_TOOLS.includes(tool) || !Array.isArray(args.files))
+		return args;
+	const entries = args.files as SessionFile[];
+	const found: (WorkspaceFile | undefined)[] = [];
+	let bytes = 0;
+	for (const entry of entries) {
+		const hasPath = typeof entry?.path === "string";
+		const hasData = typeof entry?.dataBase64 === "string";
+		if (hasPath === hasData)
+			throw refuse(
+				"INVALID_CHANNEL_FILE",
+				"give each file exactly one of path or dataBase64",
+			);
+		if (hasData) {
+			if (typeof entry.filename !== "string")
+				throw refuse(
+					"INVALID_CHANNEL_FILE",
+					"a file given as dataBase64 needs a filename",
+				);
+			bytes += base64Bytes(entry.dataBase64 as string);
+			found.push(undefined);
+			continue;
+		}
+		if (!roots)
+			throw refuse(
+				"INVALID_CHANNEL_FILE_PATH",
+				"this session has no workspace, so it can send files only as dataBase64",
+			);
+		const file = await find(entry.path as string, roots);
+		bytes += file.size;
+		found.push(file);
+	}
+	if (bytes > CHANNEL_UPLOAD_MAX_BYTES)
+		throw new ChannelToolError("INVALID_CHANNEL_UPLOAD_SIZE");
+	const files = await Promise.all(
+		entries.map(async (entry, index) => {
+			const file = found[index];
+			if (!file) return entry;
+			const data = await read(file);
+			const { path: _path, ...rest } = entry;
+			return {
+				...rest,
+				filename: entry.filename ?? file.name,
+				dataBase64: Buffer.from(data).toString("base64"),
+			};
+		}),
+	);
+	return { ...args, files };
+}
+
+async function find(path: string, roots: WorkspaceRoots) {
+	try {
+		return await findWorkspaceFile(path, roots);
+	} catch (error) {
+		if (error instanceof WorkspaceFileError)
+			throw refuse("INVALID_CHANNEL_FILE_PATH", error.message);
+		throw error;
+	}
+}
+
+async function read(file: WorkspaceFile) {
+	try {
+		return await readWorkspaceFile(file, CHANNEL_UPLOAD_MAX_BYTES);
+	} catch (error) {
+		if (error instanceof WorkspaceFileError)
+			throw new ChannelToolError("INVALID_CHANNEL_UPLOAD_SIZE");
+		throw error;
+	}
+}