pi-roundtable 0.9.2 → 0.9.5

package/CHANGELOG.md

@@ -5,6 +5,51 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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
+
+- A long non-ASCII upload name no longer fails with `ENAMETOOLONG` on Linux: a stored file name is cut by UTF-8 bytes (150 at most, on a code point, keeping the end so the extension stays) instead of by UTF-16 units, so the file name and its `.json` record fit the 255 bytes a file system takes. A leading dot left by the cut is replaced too. The Discord download path shares the fix. `AttachmentPort.save` removes the data file when the record write fails, so a half-saved file no longer counts as waiting.
+- Calls on one principal's attachments run one after another, so two messages that name overlapping files no longer leave the refused one's other files moved into the conversation: `turnAttachments` moves the whole set or none, rolls back a partial move, and answers a file a sweep or a message took meanwhile with `AttachmentRefusal` (`unknown_file`) instead of a raw `ENOENT`.
+- The `## Attachments` block prints a name and a content type a prompt can trust: control characters, line and paragraph separators and bidi controls in a name become underscores and quotes become apostrophes, and a content type that is not a plain `type/subtype` prints as `application/octet-stream`.
+- `ToolTurn.attachment()` and `read_attachment` refuse a name with a NUL byte as "not an attachment name"; a NUL name no longer surfaces a runtime error that quoted the host's attachment directory, and a file that cannot be read reports its name, not its path.
+- `discardPending` removes the staging directories it emptied, so a conversation's uploads leave no empty directories behind.
+- `deleteConversation` of the Pi runtime removes the conversation's attachment directory, the files saved for it that no turn used, and its share of the used-bytes tally, so a deleted conversation keeps no files (a conversation deleted in the instant a message is taking its files can leave that message's share of the tally behind).
+
+### Added
+
+- `TurnAttachmentOptions` and `AttachmentPort.turnAttachments(channel, principalId, files, options?)`: `options.usedBytesLimit` caps the bytes one principal's turns keep across all their conversations. A call that would pass it moves nothing and is refused with the new `AttachmentRefusalCode` `quota_exceeded`; without it the core sets no limit. The core tallies the bytes per principal and conversation, and deleting a conversation gives its bytes back.
+
+### Documented
+
+- The guide says what the port checks (a private conversation's record) and what it does not: a channel with no record, or any channel on a host with no conversation registry, is admitted for every principal, so the plugin that owns a channel checks that the caller may use it before every call.
+
 ## [0.9.2] - 2026-10-10
 
 ### Added

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,6 +61,7 @@ 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).
@@ -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 |
@@ -538,14 +539,16 @@ A plugin whose clients upload a file themselves, over HTTP for instance, has the
 | Call | What it does |
 |---|---|
 | `save(channel, principalId, { name, contentType, data })` | Keeps the file for that principal in that conversation and returns a `StoredAttachment`; its `file` is the name to hand back to the client. Refuses a file over 25 MiB (`too_large`) |
-| `turnAttachments(channel, principalId, files)` | Takes the `file` names `save` returned and returns the turn's `TurnAttachments`; pass it as `attachments` to [`turns.run`](#personas-and-contextturns-conversations-of-a-kind-of-your-own). Each file moves into the conversation's attachment directory, up to four images are prepared for the model, and the turn's prompt lists every file under `## Attachments`. Refuses the whole set when one name is unknown or already used (`unknown_file`); then none moves |
+| `turnAttachments(channel, principalId, files, options?)` | Takes the `file` names `save` returned and returns the turn's `TurnAttachments`; pass it as `attachments` to [`turns.run`](#personas-and-contextturns-conversations-of-a-kind-of-your-own). Each file moves into the conversation's attachment directory, up to four images are prepared for the model, and the turn's prompt lists every file under `## Attachments`. Refuses the whole set when one name is unknown or already used (`unknown_file`), or when `options.usedBytesLimit` would be passed (`quota_exceeded`); then none moves, even when other calls for the same principal run at once |
 | `remove(channel, principalId, file)` | Discards a saved file no turn used; `false` when there is none |
 | `discardPending(olderThan)` | Discards every saved file no turn used that was saved before the date, and returns how many; call it from a service's timer so abandoned uploads do not pile up |
 | `pendingBytes(principalId)` | The bytes the principal has saved that no turn used yet, for a quota of your own |
 
 A saved file waits for its owner: only the principal that saved it can use it, and only in the conversation it was saved for.
 The conversation's record decides who may save into it: a private conversation refuses every principal but its own with an `AttachmentRefusal` whose `code` is `forbidden`, and a shared one lets each principal save and use their own files.
-A channel with no record yet, such as a conversation opened but not written in, is not checked; the plugin that owns the channel checks it, as the web chat does before it saves.
+**The plugin that owns a channel checks that the caller may use it, before every call.** The port knows only the conversation's record: a channel with no record yet, such as a conversation opened but not written in, is admitted for every principal, and so is every channel on a host with no conversation registry. A plugin that takes the channel key from a person (a URL, a frame) and passes it on unchecked lets that person stage files into, and move files into the attachment directory of, a conversation that is not theirs. Check first that the channel is the person's, as the web chat does before it saves or uses a file.
+`usedBytesLimit` caps what one principal's turns keep, across all their conversations; the core sets no limit of its own, and a deleted conversation gives its bytes back.
+Deleting a conversation (`runtime.deleteConversation`) also removes its attachment directory, the files saved for it that no turn used, and its share of the tally.
 The calls reject with `AttachmentRefusal`, and throw a `PluginError` when the host has no `dataDir` (a host built by `defineRoundtable` always has one).
 The core limits only the size; the types a plugin accepts, the number of files, and the rate are its own to limit.
 
@@ -554,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.
@@ -642,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.
@@ -716,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.
@@ -2389,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?".
@@ -2400,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).
@@ -2862,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 |
@@ -3312,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 |
@@ -3351,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 |
@@ -3429,6 +3455,7 @@ Import from the entries listed below; source area files are internal.
 | `ToolTurn` | `pi-roundtable` | type |
 | `TranscriptEntry` | `pi-roundtable` | type |
 | `TransientTask` | `pi-roundtable` | type |
+| `TurnAttachmentOptions` | `pi-roundtable` | type |
 | `TurnAttachments` | `pi-roundtable` | type |
 | `TurnConversation` | `pi-roundtable` | type |
 | `TurnEndEvent` | `pi-roundtable` | type |
@@ -3584,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.2",
+	"version": "0.9.5",
 	"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/attachments/attachment-dir.ts

@@ -1,6 +1,12 @@
+import { readdir, rm, rmdir } from "node:fs/promises";
 import { join } from "node:path";
 import type { ChannelKey } from "../domain/conversation.ts";
 
+/** Where saved files wait for a turn, beside the conversations' attachment directories. */
+export const STAGING = "attachments-pending";
+/** Where each principal's tally of used bytes per conversation is kept. */
+export const USAGE = "attachments-used";
+
 /** A channel key as a single path segment. */
 export function channelSegment(channel: ChannelKey): string {
 	return channel.replace(/[^A-Za-z0-9_-]/g, "_");
@@ -13,3 +19,48 @@ export function ownerAttachmentDir(
 ): string {
 	return join(dataDir, "attachments", channelSegment(channel));
 }
+
+/** The entries of `dir`; none when it is not there. */
+export async function listDir(dir: string): Promise<string[]> {
+	try {
+		return await readdir(dir);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/** Removes `dir` when it is empty; a directory that has entries, or is gone, stays as it is. */
+export async function removeIfEmpty(dir: string): Promise<void> {
+	try {
+		await rmdir(dir);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code !== "ENOTEMPTY" && code !== "EEXIST" && code !== "ENOENT")
+			throw error;
+	}
+}
+
+/**
+ * Removes everything the core keeps for a deleted conversation: the files its turns used, the
+ * files people saved for it and no turn used, and the tally of what each principal used in it.
+ */
+export async function discardConversationFiles(
+	dataDir: string,
+	channel: ChannelKey,
+): Promise<void> {
+	const segment = channelSegment(channel);
+	await rm(ownerAttachmentDir(dataDir, channel), {
+		recursive: true,
+		force: true,
+	});
+	for (const area of [STAGING, USAGE]) {
+		const root = join(dataDir, area);
+		for (const principal of await listDir(root)) {
+			const dir = join(root, principal);
+			await rm(join(dir, segment), { recursive: true, force: true });
+			await rm(join(dir, `${segment}.tmp`), { force: true });
+			await removeIfEmpty(dir);
+		}
+	}
+}

package/src/core/attachments/attachment-fetcher.ts

@@ -5,6 +5,7 @@ import type {
 	AttachmentRef,
 	StoredAttachment,
 } from "../domain/attachment.ts";
+import { plainText } from "./attachment-name.ts";
 
 export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 
@@ -22,13 +23,36 @@ export interface FetchResult {
 	failures: AttachmentFailure[];
 }
 
-/** Keeps a file name readable while removing path separators and control characters. */
+/** The most UTF-8 bytes a stored name keeps; a file system takes 255 bytes for the whole file name. */
+const MAX_NAME_BYTES = 150;
+
+const utf8Length = (codePoint: number): number =>
+	codePoint < 0x80 ? 1 : codePoint < 0x800 ? 2 : codePoint < 0x10000 ? 3 : 4;
+
+/** The end of `text` that fits `max` UTF-8 bytes, cut on a code point. */
+function lastBytes(text: string, max: number): string {
+	const points = [...text];
+	let bytes = 0;
+	let start = points.length;
+	while (start > 0) {
+		const size = utf8Length(points[start - 1]?.codePointAt(0) ?? 0);
+		if (bytes + size > max) break;
+		bytes += size;
+		start -= 1;
+	}
+	return points.slice(start).join("");
+}
+
+/**
+ * Keeps a file name readable while removing path separators and control characters, and keeps the
+ * end of a long name (its extension) within 150 UTF-8 bytes so a prefix and a record suffix still
+ * fit the 255 bytes a file system takes.
+ */
 export function safeFileName(name: string): string {
-	const cleaned = name
-		.normalize("NFC")
-		.replace(/[/\\\p{Cc}]/gu, "_")
-		.replace(/^\.+/, "_")
-		.slice(-120);
+	const cleaned = lastBytes(
+		plainText(name.toWellFormed().normalize("NFC").replace(/[/\\]/g, "_")),
+		MAX_NAME_BYTES,
+	).replace(/^\.+/, "_");
 	return cleaned || "file";
 }
 

package/src/core/attachments/attachment-name.ts

@@ -0,0 +1,34 @@
+import { basename } from "node:path";
+
+/**
+ * Characters that must not reach a prompt or a file name as they are: controls, the line and
+ * paragraph separators, and the bidi controls that reorder or hide the text around them.
+ */
+const UNSAFE_CHARS =
+	/[\p{Cc}\p{Zl}\p{Zp}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
+
+/** `value` with each unsafe character replaced by an underscore. */
+export function plainText(value: string): string {
+	return value.replace(UNSAFE_CHARS, "_");
+}
+
+/** Whether `file` could be a name the attachment stores give out: one path segment, not hidden, no NUL. */
+export function isAttachmentName(file: string): boolean {
+	return (
+		file !== "" &&
+		basename(file) === file &&
+		!file.startsWith(".") &&
+		!file.includes("\0")
+	);
+}
+
+const TYPE_GRAMMAR = /^[a-z0-9.+-]+\/[a-z0-9.+-]+$/i;
+
+/**
+ * The type a prompt may print: `type` without its parameters (`text/plain; charset=utf-8` is
+ * `text/plain`) when that is a plain type/subtype, else the generic binary type.
+ */
+export function plainContentType(type: string): string {
+	const base = type.split(";")[0]?.trim().toLowerCase() ?? "";
+	return TYPE_GRAMMAR.test(base) ? base : "application/octet-stream";
+}