pum-agent 0.1.0-beta.3 → 0.1.2-beta.1

package/README.md

@@ -13,8 +13,17 @@ Plan, edit, run commands, review Markdown, and coordinate parallel Git worktrees
 
 </div>
 
+## Quick Start
+
+```bash
+bun i -g pum-agent@beta
+pum
+```
+
+PUM opens the login panel automatically on the first start.
+
 > [!WARNING]
-> PUM can read, write, and delete files. PUM can also run shell commands without approval. Start PUM only inside a workspace where these actions are acceptable. Check mode adds a verifier, but it is not a sandbox.
+> PUM can read, write, and delete files. PUM can also run commands and supervised trigger processes. Check mode can verify or ask about these operations, but it is not a sandbox. Start PUM only inside a workspace where these actions are acceptable.
 
 ## See PUM in action
 
@@ -33,10 +42,11 @@ The following screens are real OpenTUI renders captured through `tmux`. A local
 
 - **Compact terminal UI:** Streaming Markdown, syntax highlighting, thinking traces, tool rows, usage, cost, and Git status.
 - **Full coding loop:** Built-in `read`, `write`, `edit`, `bash`, and atomic `apply_patch` tools.
-- **Parallel subagents:** Persistent agents work in isolated Git worktrees and report to the main agent.
-- **Prompt control:** Steer active work, stash prompt batches, attach clipboard images, cancel turns, and resume sessions.
+- **Parallel subagents:** Persistent agents work in isolated Git worktrees, communicate durably, and report lifecycle transitions to their direct spawners.
+- **Prompt control:** Steer active work, answer model questionnaires, use an ownership-aware message cache, attach clipboard images, and resume sessions with metadata-rich history.
+- **External triggers:** Supervise background commands such as `gh run watch` and automatically wake the exact target agent when they exit.
 - **Provider choice:** Use the login methods exposed by pi, or add an OpenAI-compatible custom endpoint.
-- **Optional safeguards:** Enable fail-closed Check mode for `bash`, `edit`, and `apply_patch` calls.
+- **Optional safeguards:** Use strict, balanced, or ask Check mode for `bash`, `edit`, `apply_patch`, and external-trigger process proposals.
 - **Terminal-first appearance:** Nine themes, semantic color overrides, Unicode glyphs, and optional animation.
 
 PUM uses [pi](https://github.com/earendil-works/pi) for the agent loop and [OpenTUI](https://github.com/anomalyco/opentui) for rendering.
@@ -95,36 +105,71 @@ The package is named `pum-agent` because the bare `pum` name is already owned. T
 | `Shift+Tab` / `Ctrl+Shift+Tab` | Cycle through agent transcripts |
 | `Ctrl+H` | Open session history when the terminal reports the key distinctly |
 | `Ctrl+P` | Open settings |
+| `Ctrl+T` | Open supervised external triggers |
 | `Esc` twice | Cancel the selected working agent |
-| `Ctrl+C` twice | Quit |
+| `Ctrl+C` | Clear the selected non-empty draft; on an empty draft, press twice to quit |
 | `?` | Show all controls when the prompt is empty |
 
-Useful commands include `/login`, `/history`, `/clear`, `/compress`, and `/worktree`.
+Useful commands include `/login`, `/history`, `/triggers`, `/clear`, `/compress`, and `/worktree`.
 
 ## Parallel subagents
 
-PUM can run up to five active subagents. Each subagent has these resources:
+PUM runs up to 10 active subagents by default. Configure a limit from 1 through 25 in Settings. Only starting and running agents count toward the limit. Each subagent has these resources:
 
 - A persistent pi session
 - An isolated branch and worktree under `.pum/worktrees`
 - Its own transcript, draft, usage data, and cancellation state
 - Tools for progress messages and a single final completion report
 
-Select a range of stashed prompts and press `Enter`. The main agent can group related work and run independent groups in parallel. Successful managed merges remove the completed worktree and branch.
+Select a range of stashed prompts and press `Enter`. The main agent can group related work and run independent groups in parallel. Successful managed merges remove the completed worktree and branch. A parent cannot finish, merge, or be removed until every retained descendant closes deepest-first.
 
 Use `Ctrl+L` to select an agent transcript. Input then goes to that agent. Finished or interrupted agents remain available until PUM merges or removes them.
 
+Idle notices report settled work cycles to the direct spawner. They are not completion notices. PUM persists completion intent and delivery state so interrupted notification delivery can resume without duplicate completion messages.
+
 ## Tools and safeguards
 
+### Interactive questionnaires
+
+The `questionnaire` tool asks one or more questions inside PUM's OpenTUI interface. Each question provides selectable options and a custom-answer field. Use arrow keys or `Tab` to move, `Enter` to select, and `Esc` to cancel.
+
+PUM returns structured answers to the requesting main agent or managed child agent. Custom text stays outside React labels and session data until the user explicitly submits the answer.
+
+### Agent message cache
+
+Main and managed child agents can list and read the current workspace message cache. Agent-created entries include exact ownership metadata.
+
+Agents can add entries. An agent can delete only entries created by that exact agent. User-created and legacy entries remain user-owned.
+
+The `message_cache_send` tool accepts stable entry IDs. Single entries use the selected agent delivery path. Multiple entries use main-agent worktree orchestration.
+
+### External triggers
+
+The trigger tools create process-local supervised commands with an executable and argument array. Trigger definitions can be listed, inspected, paused, resumed, cancelled, run manually, or fired synthetically. Definitions disappear when PUM exits.
+
+Use `Ctrl+T` or `/triggers` to inspect active definitions. PUM limits definitions, pending deliveries, output size, fire counts, repeat frequency, and lifetime. Output goes to a private temporary file and is removed after the triggered turn settles.
+
+Trigger events target one exact main or retained child session. A missing session or child cancels its definitions instead of redirecting them. Check mode evaluates each process proposal without flattening its argument boundaries into shell text.
+
 ### Atomic `apply_patch`
 
 `apply_patch` supports add, update, delete, move, multiple files, and multiple hunks. PUM validates the full patch before changing files. It rejects traversal, absolute paths, escaping symlinks, path conflicts, and ambiguous context. A failed commit restores all touched files.
 
 ### Check mode
 
-Enable Check mode in `Ctrl+P`. PUM sends each proposed `bash`, `edit`, or `apply_patch` call to a separate verifier model. The verifier must return a clear `SAFE` decision. Errors, timeouts, unclear replies, and explicit rejections block the tool.
+Select a Check mode profile in `Ctrl+P`. It applies to `bash`, `edit`, `apply_patch`, and external-trigger process execution:
 
-PUM caches only a narrow set of accepted read-only Git inspection commands. It never caches mutation checks. Check mode is off by default and does not replace isolation, backups, or code review.
+- **Strict:** Run deterministic hard rules, then require a clear verifier approval.
+- **Balanced:** Permit only narrow, recognized project-local operations after hard rules. Send all other calls to the verifier.
+- **Ask:** Send ambiguous calls to the verifier. If the result stays unclear or the verifier fails, ask the user.
+
+Every active profile hard-blocks project escape, escaping links, credential access, privilege escalation, persistence, remote-script execution, destructive Git operations, and broad deletion. These hard blocks cannot be overridden. An explicit verifier `UNSAFE` verdict also cannot be overridden.
+
+For `edit` and `apply_patch`, PUM validates the proposed change and sends a unified diff, changed paths, line counts, sensitivity flags, and project containment. PUM does not mutate files before the decision. Invalid or stale edit context blocks the call.
+
+Ask mode can allow an exact call once, for the current session, or for the current project. Project approvals match the tool, verifier model, project, and canonical complete input. Use **Clear approvals** in Settings to remove project approvals.
+
+The verifier uses a structured decision schema. One unclear response can receive one adjudication under the shared 15-second watchdog. Strict and balanced block malformed replies, errors, aborts, and timeouts. Ask can present unresolved results to the user. Check mode is off by default and is not a sandbox.
 
 ### Hosted web search
 
@@ -167,6 +212,11 @@ Set `PUM_DIR` to override the complete PUM data directory.
 | `sessions/` | Main conversation sessions |
 | `subagents/` | Persistent subagent sessions |
 | `check-mode-cache.json` | Accepted checks for eligible read-only Git commands |
+| `check-mode-approvals.json` | Exact project approvals created in Ask mode |
+
+PUM preserves all stashed prompt occurrences. PUM also keeps the 100 most recent additional sent-history occurrences for each working directory.
+
+Session history shows the latest sent user-message time, on-disk JSONL size, and known outgoing, incoming, and cache-read token counts. Corrupt or partially written session lines do not prevent the history popup from opening.
 
 PUM keeps this directory separate from pi's default configuration directory.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.2-beta.1",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",

package/src/agent-usage.ts

@@ -82,7 +82,8 @@ export function usageFromEntries(
 ): AgentUsage {
   let result = emptyAgentUsage();
   for (const entry of entries) {
-    const usage = entry?.type === "message" && entry.message?.role === "assistant"
+    const usage = entry?.type === "message"
+      && (entry.message?.role === "assistant" || entry.message?.role === "toolResult")
       ? entry.message.usage
       : (entry?.type === "compaction" || entry?.type === "branch_summary")
         ? entry.usage

package/src/animation.tsx

@@ -318,11 +318,16 @@ export function markdownCaretContent(text: string, visible: boolean): string {
   return text + (visible ? CARET : CARET_PLACEHOLDER);
 }
 
+export type MarkdownCaretBinding = {
+  ref: RefObject<MarkdownRenderable | null>;
+  content: string;
+};
+
 /** Keep a blinking caret at the end of incrementally rendered Markdown. */
 export function useMarkdownCaret(
   text: string,
   active: boolean,
-): RefObject<MarkdownRenderable | null> {
+): MarkdownCaretBinding {
   const ref = useRef<MarkdownRenderable>(null);
   const { subscribe, enabled } = useClock();
   const latest = useRef(text);
@@ -359,7 +364,12 @@ export function useMarkdownCaret(
     if (active) paint();
   }, [text, active, paint]);
 
-  return ref;
+  // React applies this value in the same commit as each transcript delta.
+  // The direct frame writes only change the width-stable caret glyph.
+  return {
+    ref,
+    content: active ? markdownCaretContent(text, caretVisible.current) : text,
+  };
 }
 
 function ruleText(width: number, base: RGBA, hi: RGBA, head: number): StyledText {