pi-roundtable 0.7.15 → 0.7.17

package/CHANGELOG.md

@@ -5,6 +5,42 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.17] - 2026-10-04
+
+### Added
+
+- A turn posts the text it writes before its final answer as it goes, so a proposal written before `ask_user` shows above its card instead of never reaching the channel. Primary text (400 characters or more, or with a Markdown heading, list, table or code fence) of a tool-calling assistant message is posted as ordinary messages when the message ends; shorter narration and the tools called (`-# bash ×3 · read`, names only) share one small-text progress message per run of tool calls, edited at most every 1.5 s, bounded to 2000 characters by dropping its oldest lines. Before any card the pending text is posted first. The final reply, its thinking line, and steered runs are unchanged; a failed interim post is logged and never fails the turn. See [interim text](docs/plugins.md#interim-text-what-a-turn-writes-before-its-final-answer).
+  - Config `interimText: "on" | "off"` (default `"on"`) and `interimPrimaryChars` (default 400), also on `PiAgentRuntimeOptions` and the agent server's options.
+  - `TurnRequest.interim`, `ChatSurface.interim(channel)` and `SurfacePort.interim(channel)` (Discord's surface implements it), optional `AgentChannels.interim(channelId, as)` (the agents' webhooks), and `PromptSlot.bind`'s optional `beforeCard`.
+  - Types: `InterimMessage`, `InterimPosts`, `InterimTextMode`.
+
+### Changed
+
+- `ask_user`'s description asks for a question that reads on its own, with the context it needs.
+
+## [0.7.16] - 2026-10-04
+
+### Added
+
+- `pi-roundtable/kit` owns a Jev compaction engine on pi-jev-compaction 1.0.0 (now a dependency, pinned exactly): `jevCompact(input, options)` and two adapters, `jevCompactionExtension({ logger })` for the `compaction` session tool (placed through `session.compaction.wrap`, engine `JEV_COMPACTION_ENGINE`, `pi-jev-compaction`) and `jevCompactor({ logger })` for pi-roundtable-sandbox's `compaction` option. Both log each fallback to Pi's summary with its reason and `tokensBefore`, except a missing API key, which they log once (`Jev is not configured, so compaction uses Pi's summary`) and then compact through Pi's summary quietly: the key is optional.
+  - Values: `jevCompact`, `jevCompactionExtension`, `jevCompactor`, `isRuleLoad`, `JEV_COMPACTION_ENGINE`, `JEV_GOAL`, `JEV_PREVIOUS_SUMMARY_LIMIT_TOKENS`; types: `JevCompactInput`, `JevCompactOptions`, `JevCompactOutcome`, `JevCompactor`, `JevCompactRequest`, `JevExtensionOptions`, `JevSkipReason`.
+  - Unlike pi-jev-compaction's own `compactPiSession`, a summary carries the previous summary once, not twice, so a chain of compactions no longer doubles (one session's grew from 8k to 303k characters over five compactions).
+  - A previous summary over 60,000 tokens (`previousSummaryLimitTokens`) skips Jev, so Pi's summary condenses the chain.
+  - Jev judges with a goal (`JEV_GOAL`, option `goal`) that keeps the tool results that set rules still in force, which it dropped without one, and the summary ends with the rule loads it summarized (skills, notebook system prompts, reads of SKILL.md, AGENTS.md and `.agents/skills/`; option `ruleLoad`, default `isRuleLoad`) for the agent to load again.
+
+### Changed
+
+- The shell hold rule lets more of the agents' own work run.
+  - The agents get a scratch dir, the config's new `scratchDir` (default `<os temp dir>/<discord.rootCommand>-scratch`, created with mode 0700 at startup; a symlink or another user's dir is refused), and their `bash` runs with `TMPDIR` pointing to it. Redirects, `tee`, and `write` and `edit` inside it run as inside the workspace; the rest of `/tmp` stays held. `AgentSessions.scratchDir` and `HoldContext.scratchDir` carry it, and the agents' prompt names it.
+  - `rm` is no longer always held: it runs when every operand resolves, after the line's literal variable assignments, `cd`, `..` and symlinks, inside the workspace or the scratch dir without being one of them. A command substitution, an unknown variable, a root itself, `/`, or no operand keeps it held.
+  - `git push` stays held by `shellHoldRule`; the new `shellHoldRuleFor({ ownPushOwners, heldPushRepos })` (type `PushPolicy`) lets a plain push to a GitHub repository of a listed owner run, unless it forces, deletes, pushes tags or a mirror, or the repository is in `heldPushRepos` or its remote cannot be read.
+  - A relative write target or `rm` operand resolves from the line's last `cd`, not always from the workspace.
+  - Value: `shellHoldRuleFor`; type: `PushPolicy`.
+
+### Fixed
+
+- pi-roundtable-coding frees a finished job's repository before delivering its report, so the turn that receives the report can ship it or start the next worker there instead of being refused with "still using".
+
 ## [0.7.15] - 2026-10-03
 
 ### Changed

package/docs/plugins.md

@@ -63,11 +63,19 @@ Use the kit's building blocks for a plugin that runs Pi itself, such as a coding
 - 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.
 - 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`, the hold rule that keeps risky host-shell commands behind the owner's approval.
+- 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)` to hold a compaction extension back past the ceiling, `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`.
+- 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/`).
+  `config` passes pi-jev-compaction's settings (`apiKey`, `model`, thresholds) over its config file and environment; `asker` replaces Jev's service, for tests.
+  The API key is optional: without one, `jevCompact` skips with `no_key` without calling Jev, and compaction is Pi's own summary.
+  Two adapters log each skip as `Jev leaves the compaction to Pi's summary` with `reason`, `detail` and `tokensBefore` through the `logger` they take: `jevCompactionExtension({ logger, ...options })`, the `compaction` session tool's extension, placed as `session.compaction.wrap(jevCompactionExtension({ logger }))` under the engine `JEV_COMPACTION_ENGINE` (`pi-jev-compaction`), and `jevCompactor({ logger, ...options })`, a `JevCompactor` for pi-roundtable-sandbox's `compaction` option that returns the compaction or `undefined` and logs with the `channel`.
+  A `no_key` skip is logged once per adapter, as `Jev is not configured, so compaction uses Pi's summary`, and then not again; every other skip is logged each time.
+  The types are `JevCompactInput`, `JevCompactOptions`, `JevCompactOutcome`, `JevCompactor`, `JevCompactRequest`, `JevExtensionOptions` and `JevSkipReason`.
 - Effort: `effortJudge` picks a turn's thinking level from a message with your own brief (`EffortBrief`, `JUDGE_WORK`).
 - Presentation and small helpers: `thinkingLine`, `zonedStamp(date, timeZone)`, `channelQueue()` (a queue of your own, so work does not wait behind a running turn), `checkRepoName` and `SKILL_LIST_TOOL` with `skillListExtension` for repositories and skills, and `searchTerms` for memory search.
 
@@ -505,6 +513,36 @@ 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.
 
+#### The shell rule
+
+`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.
+
+- 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.
+- `sudo`, `kill`, `dd`, `mkfs` and the other programs held whatever their arguments stay held, as do service, container, firewall and package changes, `git reset --hard`, and `gh` writes.
+- `git push` is held, `force-pushes` for a force push and otherwise as a push to GitHub.
+
+`shellHoldRuleFor({ ownPushOwners?, heldPushRepos? })` (its options are the type `PushPolicy`) is the same rule with plain pushes to the owner's own repositories let through; `shellHoldRule` is `shellHoldRuleFor()`, which holds every push.
+A push runs without a hold when all of these hold:
+
+- it does not force (`-f`, `--force*`, a `+` refspec), delete (`--delete`, `-d`, a `:ref` refspec), or push tags or more than its refs (`--tags`, `--follow-tags`, `--mirror`, `--all`, `--prune`), takes no other option than `-u`, `-q`, `-v`, `-n`, `--no-verify`, `--atomic`, `--porcelain`, `--progress` and `-o`, and names no `refs/tags/…` ref or local tag;
+- the repository directory is known: `git -C <dir>`, else the last `cd` in the command line, else the workspace; a line with a subshell or `||` does not follow its `cd`;
+- every push URL of the remote (the named one, default `origin`, read with `git remote get-url --push --all` with a short timeout and no shell; or a URL given in its place) is a GitHub repository, https or ssh, whose owner is in `ownPushOwners` and whose `owner/repo` is not in `heldPushRepos`.
+
+Git's `-c`, `--git-dir` and `--work-tree`, a `GIT_*` variable before `git`, and any failure to read the remote keep the push held.
+
+```ts
+import { shellHoldRuleFor } from "pi-roundtable/kit";
+
+const shell = shellHoldRuleFor({
+	ownPushOwners: ["octocat"],
+	heldPushRepos: ["octocat/deployed-app"],
+});
+```
+
 ### `prompt`: text added to every agent turn
 
 Each section's `build` gets the agent, the speaker (undefined between turns), and the turn's scope.
@@ -1001,7 +1039,7 @@ The slot is a `RuntimeFactory`: `(deps: RuntimeDeps) => AgentRuntime`, called on
 `deps` provides `logger`, `env`, `owner`, `toolTiers`, and the host's `judge`.
 Its `sessions()` gives you linked hold rules, packages, session tools, and personas from preflight onwards; call it in a turn, when those parts are available.
 `prompts(conversation, speaker)` gives you the owner's approval and question cards on the conversation's surface, or `undefined`.
-`agents` holds the agent server's per-agent settings: `workDir`, `skills(name)`, `modelOf(name)`, and `turnChannel(scope)`.
+`agents` holds the agent server's per-agent settings: `workDir`, `scratchDir` (the agents' shell's `TMPDIR`), `skills(name)`, `modelOf(name)`, and `turnChannel(scope)`.
 `confirmations` stores held actions across restarts.
 
 An `AgentRuntime` has these methods:
@@ -1018,7 +1056,7 @@ An `AgentRuntime` has these methods:
 | `preflight?()` | Runs in the host's preflight, before anything starts; a throw stops the boot |
 | `dispose?()` | Runs when the host stops the agent server's runtime service |
 
-A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker`, and flags (`steerable`, `interactive`, `confirmed`).
+A request has the turn's `channel`, `selection` (its tools), `text`, `attachments`, `speaker`, flags (`steerable`, `interactive`, `confirmed`), and `interim`, where the turn may post the text it writes before its final answer ([interim text](#interim-text-what-a-turn-writes-before-its-final-answer)).
 An agent's turn also has `agent`, the agent's scope, whose `session` is the conversation's key.
 Other turns use `kind` to name the conversation's persona, defaulting to `"owner"` when absent.
 
@@ -1489,6 +1527,22 @@ Use it for tools that `defineTool` cannot express, such as a set that changes wh
 Each extension needs a unique name; the core reserves `read-attachment`, `confirmation-gate`, `ask-user`, `self-compact-guard`, and `active-tools`.
 A runtime of your own pins the active tools the way the core does: `activeToolsExtension(() => tools)` from `pi-roundtable/kit` is the extension the core places last, so its handler runs after every other extension's.
 At most one plugin may add a `compaction` extension, and it must name the `engine` its compactions record.
+The core's Jev compactor is one such extension:
+
+```ts
+sessionTools: [
+	{
+		name: "jev-compaction",
+		phase: "compaction",
+		engine: JEV_COMPACTION_ENGINE,
+		snapshot: () => ({
+			revision: 0,
+			factory: (session) =>
+				session.compaction.wrap(jevCompactionExtension({ logger })),
+		}),
+	},
+],
+```
 
 <!-- example: examples/session-tools.ts -->
 ```ts
@@ -1828,6 +1882,7 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `showStop(channel)` | Shows the owner a stop control until the returned function is called; using it calls `conversations.stop(channel)` | none is shown |
 | `react`, `unreact` | Adds or removes the bot's reaction on a message | no marks on queued or steered messages |
 | `prompts(channel, speaker?)` | The owner's way to approve a held action or answer `ask_user` inside a running turn, as `OwnerPrompts`: `confirm` and `ask` | the action is held until the owner's next message |
+| `interim(channel)` | Where a running turn posts the text it writes before its final answer, as `InterimPosts`: `post(text)` sends one message of at most 2000 characters and resolves to an `InterimMessage` whose `edit(text)` changes it in place | only the final reply is posted |
 
 The host starts each surface as `surface:<prefix>` at the contributing plugin's place in the order, before that plugin's own services.
 It stops surfaces in reverse order, like other services.
@@ -1839,6 +1894,22 @@ If `prompts` is unavailable, it returns `undefined` and held actions wait for th
 `of(channel)` returns the surface, or `undefined`.
 The agent server asks the owner for approvals through `context.surfaces.prompts`, so a surface that gives `prompts` gets them in its own channels.
 
+#### 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?".
+On a surface that gives `interim`, and in the agent server's channels through the agents' webhooks, the host posts that text as the turn goes, sorted in two:
+
+- **Primary** text is posted as ordinary messages as soon as its assistant message ends: text of 400 characters or more, or written with a Markdown heading, list, table or code fence.
+- **Secondary** text, short narration between tool calls, goes to one progress message per run of tool-calling messages, in Discord's small text (`-# ` per line): each text as a line, then the tools called in the run, such as `-# bash ×3 · read · web_search` (names only). It is edited in place at most every 1.5 seconds, its last state always lands, and it stays inside 2000 characters by dropping its oldest lines behind `-# …`. A primary post or a card starts a new progress message.
+
+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.
+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).
+
 The Discord plugin collects [slash commands](#slash-commands-commandsadd); the host doesn't compose them or pass them to surfaces on other networks.
 
 This in-memory chat surface records everything the host asks of it.
@@ -2075,7 +2146,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? })` returns the description of a call that must be approved first, or `undefined` |
+| `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 |
 | `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` |
@@ -2471,6 +2542,9 @@ Import from the entries listed below; source area files are internal.
 | `HttpRoute` | `pi-roundtable` | type |
 | `ImageDrawer` | `pi-roundtable` | type |
 | `InboundMessage` | `pi-roundtable` | type |
+| `InterimMessage` | `pi-roundtable` | type |
+| `InterimPosts` | `pi-roundtable` | type |
+| `InterimTextMode` | `pi-roundtable` | type |
 | `Judge` | `pi-roundtable` | type |
 | `JudgeError` | `pi-roundtable` | value |
 | `JudgeModel` | `pi-roundtable` | type |
@@ -2666,6 +2740,7 @@ Import from the entries listed below; source area files are internal.
 | `OwnerNotifier` | `pi-roundtable/kit` | type |
 | `PreviousTurn` | `pi-roundtable/kit` | type |
 | `PromptSlot` | `pi-roundtable/kit` | type |
+| `PushPolicy` | `pi-roundtable/kit` | type |
 | `SCHEDULE_TOOLS` | `pi-roundtable/kit` | value |
 | `SHELL_TOOLS` | `pi-roundtable/kit` | value |
 | `SKILL_LIST_TOOL` | `pi-roundtable/kit` | value |
@@ -2707,6 +2782,20 @@ Import from the entries listed below; source area files are internal.
 | `CompactionEngine` | `pi-roundtable/kit` | type |
 | `CompactionHistory` | `pi-roundtable/kit` | type |
 | `LatestCompaction` | `pi-roundtable/kit` | type |
+| `isRuleLoad` | `pi-roundtable/kit` | value |
+| `JEV_COMPACTION_ENGINE` | `pi-roundtable/kit` | value |
+| `JEV_GOAL` | `pi-roundtable/kit` | value |
+| `JEV_PREVIOUS_SUMMARY_LIMIT_TOKENS` | `pi-roundtable/kit` | value |
+| `jevCompact` | `pi-roundtable/kit` | value |
+| `jevCompactionExtension` | `pi-roundtable/kit` | value |
+| `jevCompactor` | `pi-roundtable/kit` | value |
+| `JevCompactInput` | `pi-roundtable/kit` | type |
+| `JevCompactOptions` | `pi-roundtable/kit` | type |
+| `JevCompactOutcome` | `pi-roundtable/kit` | type |
+| `JevCompactor` | `pi-roundtable/kit` | type |
+| `JevCompactRequest` | `pi-roundtable/kit` | type |
+| `JevExtensionOptions` | `pi-roundtable/kit` | type |
+| `JevSkipReason` | `pi-roundtable/kit` | type |
 | `isScheduleTool` | `pi-roundtable/kit` | value |
 | `lastAssistant` | `pi-roundtable/kit` | value |
 | `mcpAdapterExtension` | `pi-roundtable/kit` | value |
@@ -2723,6 +2812,7 @@ Import from the entries listed below; source area files are internal.
 | `searchTerms` | `pi-roundtable/kit` | value |
 | `settleTurn` | `pi-roundtable/kit` | value |
 | `shellHoldRule` | `pi-roundtable/kit` | value |
+| `shellHoldRuleFor` | `pi-roundtable/kit` | value |
 | `skillListExtension` | `pi-roundtable/kit` | value |
 | `splitReply` | `pi-roundtable/kit` | value |
 | `stringList` | `pi-roundtable/kit` | value |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.15",
+	"version": "0.7.17",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",
@@ -61,6 +61,7 @@
 		"@earendil-works/pi-coding-agent": ">=0.99.2 <2",
 		"canvas": "3.2.3",
 		"discord.js": "14.27.0",
+		"pi-jev-compaction": "1.0.0",
 		"pi-mcp-adapter": "5.0.0",
 		"pino": "10.3.1",
 		"typebox": "1.3.34",

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

@@ -1,4 +1,5 @@
 import type { AgentRuntime, ContextUse } from "../contract/runtime.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { ThinkingSetting } from "../models.ts";
 
 export type { ContextUse };
@@ -47,6 +48,14 @@ export interface ChannelMessage {
 /** The agent server's channels as the agent team needs them. */
 export interface AgentChannels {
 	post(channelId: string, post: AgentPost): Promise<void>;
+	/**
+	 * Where a running turn posts the text it writes before its final answer, under the same name
+	 * and avatar as `post`; absent = only the final reply is posted.
+	 */
+	interim?(
+		channelId: string,
+		as: Omit<AgentPost, "thinking" | "chunks" | "files">,
+	): InterimPosts;
 	/** Creates a text channel under the category, made when missing; returns its id. */
 	createChannel(
 		name: string,

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

@@ -18,6 +18,8 @@ export function agentSystemPrompt(input: {
 	owner: OwnerIdentity;
 	/** The host account the shell and file tools run as. */
 	shellUser: string;
+	/** The scratch dir the shell's TMPDIR points to, for temporary files. */
+	scratchDir?: string;
 	group?: { group: AgentGroup; members: readonly Agent[] };
 	/** Who the turn is for; without one, or the owner, the prompt speaks to the owner. */
 	speaker?: Speaker;
@@ -35,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}. Commands that are destructive or change the system, and writes outside the workspace, 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.`,
 	];
 	if (group) {
 		const others = group.members

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

@@ -131,6 +131,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			entryChannelId,
 			owner,
 			shellUser,
+			scratchDir,
 		} = this.#options;
 		const agent = store.agent(scope.name);
 		if (!agent) throw new AgentError(`no agent ${scope.name}`);
@@ -146,6 +147,7 @@ export class DiscordAgentTeam implements AgentOps, AgentTeam {
 			workDir,
 			owner,
 			shellUser,
+			...(scratchDir ? { scratchDir } : {}),
 			avatars: this.#avatars(),
 			...(group
 				? {

package/src/core/agents/team-options.ts

@@ -35,6 +35,8 @@ export interface AgentTeamOptions
 	workDir: string;
 	/** The host account the agents' shell and file tools run as. */
 	shellUser: string;
+	/** The scratch dir the agents' shell writes temporary files to. */
+	scratchDir?: string;
 	/** The prompt every persona shares, the assistant's included; each agent's starts with it. */
 	sharedPrompt: string;
 	/** The shared prompt for speakers other than the owner, when `sharedPrompt` speaks to the owner. */

package/src/core/agents/team-turn-types.ts

@@ -44,7 +44,7 @@ export interface TeamTurnsOptions {
 	/** Who the agents work for, as their prompts and group history name them. */
 	owner: OwnerIdentity;
 	store: PgAgentStore;
-	channels: Pick<AgentChannels, "post">;
+	channels: Pick<AgentChannels, "post" | "interim">;
 	studio: Pick<AvatarStudio, "url">;
 	/** Set once the runtime exists, which itself needs the team's tools. */
 	runtime: () => AgentTurnRunner;

package/src/core/agents/team-turns.ts

@@ -6,6 +6,7 @@ import type {
 	TurnResult,
 } from "../domain/conversation.ts";
 import { AgentError } from "../domain/errors.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { AgentTurnScope } from "../domain/ports.ts";
 import { messages } from "../i18n/index.ts";
 import { splitReply } from "../presentation/reply-splitter.ts";
@@ -185,6 +186,7 @@ export class TeamTurns {
 			...(scope.group ? { group: scope.group } : {}),
 		};
 		this.#options.events?.turnStarted(turn);
+		const interim = this.#interim(postTo, agent);
 		let result: TurnResult;
 		try {
 			result = await settleTurn(
@@ -200,6 +202,7 @@ export class TeamTurns {
 							...(extra.interactive ? { interactive: true } : {}),
 							agent: scope,
 							speaker: chain.speaker,
+							...(interim ? { interim } : {}),
 						}),
 					),
 				"agent turn",
@@ -250,6 +253,27 @@ export class TeamTurns {
 		return this.#options.store.agent(agent.name) ?? agent;
 	}
 
+	/**
+	 * The turn's interim posts under the agent's name, read as each goes out so a name changed
+	 * during the turn shows; none in a channel no agent or group owns any more.
+	 */
+	#interim(channel: ChannelKey, agent: Agent): InterimPosts | undefined {
+		const { store, channels, studio } = this.#options;
+		if (!channels.interim) return undefined;
+		const interim = channels.interim.bind(channels);
+		return {
+			post: async (text) => {
+				if (!channelOwner(store, channel))
+					throw new AgentError(`${channel} is archived`);
+				const as = this.#current(agent);
+				return interim(channelIdOf(channel), {
+					name: as.displayName,
+					avatarUrl: studio.url(as.avatarHash),
+				}).post(text);
+			},
+		};
+	}
+
 	/**
 	 * Posts under the agent's name. A channel no agent or group owns any more, archived while a
 	 * turn ran, gets nothing, so its webhook is not made again.

package/src/core/builtin/agent-server.ts

@@ -1,3 +1,4 @@
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { SQL } from "bun";
@@ -12,6 +13,8 @@ import { discordKey } from "../agents/team-keys.ts";
 import { ownerAttachmentDir } from "../attachments/attachment-dir.ts";
 import type { AgentRuntime, AgentSessions } from "../contract/runtime.ts";
 import type { ChannelKey } from "../domain/conversation.ts";
+import { ConfigError } from "../domain/errors.ts";
+import type { InterimTextMode } from "../domain/interim.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import { ConfirmationJudge } from "../judging/confirmation-judge.ts";
 import { AGENT_BRIEF, EffortJudge } from "../judging/effort-judge.ts";
@@ -53,6 +56,11 @@ export interface AgentServerOptions {
 	judgeThreshold: number;
 	/** The shell's shared working directory. */
 	workDir: string;
+	/**
+	 * The agents' scratch dir, created with mode 0700 when the agent server starts: their shell's
+	 * TMPDIR, where writes and removals run without a hold.
+	 */
+	scratchDir?: string;
 	/** The host account the agents' shell and file tools run as. */
 	shellUser: string;
 	/** The prompt every agent starts with, and the one for speakers other than the owner. */
@@ -65,6 +73,10 @@ export interface AgentServerOptions {
 	avatarReference: string;
 	/** Reports the process's own errors to an agent; without one nothing is reported. */
 	errorReporter?: ErrorReporter;
+	/** Whether turns post the text they write before their final answer as they go; default "on". */
+	interimText?: InterimTextMode;
+	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
+	interimPrimaryChars?: number;
 }
 
 /** The name of the agent server's plugin, as `serviceStarted` events name it. */
@@ -178,6 +190,7 @@ export function agentServerPlugin(
 				owner: options.owner,
 				toolTiers: context.toolTiers,
 				shellUser: options.shellUser,
+				...(options.scratchDir ? { scratchDir: options.scratchDir } : {}),
 				store,
 				channels: connection.agentChannels(options.guildId),
 				studio,
@@ -227,6 +240,9 @@ export function agentServerPlugin(
 			});
 			const agentSessions: AgentSessions = {
 				workDir: options.workDir,
+				...(options.scratchDir
+					? { scratchDir: ensureScratchDir(options.scratchDir) }
+					: {}),
 				modelOf: (name) => built.modelOf(name),
 				skills: (name) => built.skillsOf(name),
 				turnChannel: (scope) => built.turnChannel(scope),
@@ -267,6 +283,12 @@ export function agentServerPlugin(
 						agents: agentSessions,
 						prompts,
 						logger,
+						...(options.interimText
+							? { interimText: options.interimText }
+							: {}),
+						...(options.interimPrimaryChars
+							? { interimPrimaryChars: options.interimPrimaryChars }
+							: {}),
 					});
 			runtime = running;
 			context.services.provide(AGENTS, {
@@ -339,3 +361,18 @@ export function agentServerPlugin(
 		},
 	};
 }
+
+/**
+ * Creates the scratch dir for the service user alone. A shared temp dir lets anyone create the
+ * path first, so a symlink or a dir the service user does not own is refused.
+ */
+export function ensureScratchDir(dir: string): string {
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const stat = lstatSync(dir);
+	if (!stat.isDirectory() || stat.uid !== process.getuid?.())
+		throw new ConfigError(
+			`the scratch dir ${dir} is not a directory of this service's user. Remove it or set scratchDir to another path.`,
+		);
+	chmodSync(dir, 0o700);
+	return dir;
+}

package/src/core/config/config.ts

@@ -1,5 +1,8 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { AgentSeed } from "../agents/agent-rules.ts";
 import { ConfigError } from "../domain/errors.ts";
+import type { InterimTextMode } from "../domain/interim.ts";
 import { isLocale, type Locale } from "../i18n/index.ts";
 import type { OwnerIdentity } from "../identity.ts";
 import {
@@ -9,6 +12,7 @@ import {
 	type ThinkingLevel,
 } from "../models.ts";
 import type { RoundtablePlugin } from "../plugin.ts";
+import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
 import {
 	bool,
@@ -103,6 +107,11 @@ export interface RoundtableConfig {
 	avatar?: string;
 	/** The agents' shared working directory; default `<dataDir>/work`. */
 	workDir?: string;
+	/**
+	 * The agents' scratch dir: their shell runs with TMPDIR pointing to it, and writes and removals
+	 * inside it run without a hold. Default `<os temp dir>/<discord.rootCommand>-scratch`.
+	 */
+	scratchDir?: string;
 	/**
 	 * Where the skill registry reads built-in skills and keeps linked repositories. `false` leaves
 	 * the `skills` addon out: agents carry no skills, and no skill tools exist. Stored skills stay
@@ -116,6 +125,14 @@ export interface RoundtableConfig {
 	memory?: boolean;
 	/** The agent that investigates the process's own errors, by name. */
 	ops?: { agent: string };
+	/**
+	 * Whether a turn posts the text it writes before its final answer as it goes: long or
+	 * structured text as ordinary messages, short narration and the tools called in one small
+	 * progress message. Default "on"; "off" posts only the final reply.
+	 */
+	interimText?: InterimTextMode;
+	/** An intermediate text this long or longer is posted as an ordinary message; default 400. */
+	interimPrimaryChars?: number;
 	plugins?: RoundtablePlugin[];
 }
 
@@ -191,11 +208,14 @@ const schema = shape({
 	}),
 	avatar: optional(text),
 	workDir: optional(text),
+	scratchDir: optional(text),
 	skills: optional(
 		orOff(shape({ builtinDir: optional(text), reposDir: optional(text) })),
 	),
 	memory: optional(bool),
 	ops: optional(shape({ agent: text })),
+	interimText: optional(oneOf<InterimTextMode>("on", "off")),
+	interimPrimaryChars: optional(integer(1, 100_000)),
 	plugins: optional(
 		list(
 			guarded("a plugin, an object with a name and a setup function", isPlugin),
@@ -243,10 +263,13 @@ export interface ResolvedConfig {
 	};
 	avatar?: string;
 	workDir: string;
+	scratchDir: string;
 	/** `false` when the skills addon is off. */
 	skills: false | { builtinDir?: string; reposDir?: string };
 	memory: boolean;
 	ops?: { agent: string };
+	interimText: InterimTextMode;
+	interimPrimaryChars: number;
 	plugins: RoundtablePlugin[];
 }
 
@@ -265,6 +288,9 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 	const name = config.name ?? "Roundtable";
 	const model = modelOf(config.model, "model");
 	const thinking = config.thinking ?? "medium";
+	const rootCommand =
+		config.discord.rootCommand ??
+		name.toLowerCase().replace(/[^a-z0-9-]+/g, "-");
 	return {
 		name,
 		owner: {
@@ -276,9 +302,7 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 			token: config.discord.token,
 			guild: config.discord.guild,
 			entryChannel: config.discord.entryChannel,
-			rootCommand:
-				config.discord.rootCommand ??
-				name.toLowerCase().replace(/[^a-z0-9-]+/g, "-"),
+			rootCommand,
 			admin: config.discord.admin ?? true,
 			...(config.discord.refusalHint === undefined
 				? {}
@@ -321,9 +345,12 @@ export function resolveConfig(input: unknown): ResolvedConfig {
 		},
 		...(config.avatar ? { avatar: config.avatar } : {}),
 		workDir: config.workDir ?? `${config.dataDir}/work`,
+		scratchDir: config.scratchDir ?? join(tmpdir(), `${rootCommand}-scratch`),
 		skills: config.skills ?? {},
 		memory: config.memory ?? true,
 		...(config.ops ? { ops: config.ops } : {}),
+		interimText: config.interimText ?? "on",
+		interimPrimaryChars: config.interimPrimaryChars ?? PRIMARY_CHARS,
 		plugins: config.plugins ?? [],
 	};
 }

package/src/core/contract/runtime.ts

@@ -82,6 +82,11 @@ export interface LoadedSkill {
 export interface AgentSessions {
 	/** The shell's working directory, shared by every agent; writes outside it are held. */
 	workDir: string;
+	/**
+	 * The host's scratch dir: the agents' shell runs with TMPDIR pointing to it, and writes and
+	 * removals inside it run without a hold, like the workspace's.
+	 */
+	scratchDir?: string;
 	/**
 	 * The skills the agent carries, read at the start of every run; a change rebuilds its
 	 * sessions, keeping their history.

package/src/core/contract/surface.ts

@@ -1,4 +1,5 @@
 import type { OutboundReply } from "../domain/conversation.ts";
+import type { InterimPosts } from "../domain/interim.ts";
 import type { OwnerPrompts } from "../domain/owner-prompts.ts";
 import { PluginError } from "../errors.ts";
 import type { ChannelKey } from "../sessions.ts";
@@ -68,6 +69,11 @@ export interface ChatSurface {
 	 * absent, = the action is held until the owner's next message.
 	 */
 	prompts?(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+	/**
+	 * Where a running turn posts the text it writes before its final answer: ordinary messages it
+	 * may edit in place. Absent, or undefined, = only the final reply is posted.
+	 */
+	interim?(channel: ChannelKey): InterimPosts | undefined;
 }
 
 /**
@@ -87,4 +93,6 @@ export interface SurfacePort {
 	unreact(channel: ChannelKey, messageId: string, emoji: string): Promise<void>;
 	/** The owner's prompts in the channel; undefined when its surface has none. */
 	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined;
+	/** The channel's interim posts; undefined when its surface has none. */
+	interim(channel: ChannelKey): InterimPosts | undefined;
 }

package/src/core/define-roundtable.ts

@@ -211,11 +211,14 @@ export async function defineRoundtable(
 				thinking: config.thinking,
 				judgeThreshold: config.judge.threshold,
 				workDir: config.workDir,
+				scratchDir: config.scratchDir,
 				shellUser: userInfo().username,
 				prompts: { shared, guest },
 				avatarListener: "public",
 				avatarUrl: config.http.publicUrl,
 				avatarReference: config.avatar ?? join(ASSETS, "neutral.png"),
+				interimText: config.interimText,
+				interimPrimaryChars: config.interimPrimaryChars,
 				...(errorReporter ? { errorReporter } : {}),
 			}),
 			seedsPlugin(config.agents),