agentp 2.1.1 → 2.1.3

package/docs/specification_v2.md

@@ -34,7 +34,11 @@ is the durable source of truth:
 
 `directory`, `session`, and `server` route prompts. `annotations` stores optional
 per-session reminders. `broadcast` exists only with at least two selected main
-sessions. Writes use a temporary file plus atomic rename.
+sessions and is removed as soon as broadcast mode ends (`Enter`/`ESC`/`q`) or any
+session is picked in the normal switcher. On open it is validated against the
+live session list: a valid list starts the picker directly in broadcast mode,
+while a stale/invalid one is cleared and the normal state shown. Writes use a
+temporary file plus atomic rename.
 
 No tmux socket, pane ID, process ID, or TUI assignment belongs in project state.
 Those values are ephemeral and machine-local.
@@ -79,7 +83,8 @@ There is no `--global` alias.
 
 ## 4. TUI routing
 
-When `ocmux` selects or inspects a session, it resolves the display in order:
+When `ocmux` selects or inspects a session — or `agentp` sends a prompt or
+re-submits a deferred ticket (section 8) — the display is resolved in order:
 
 1. live TUI dedicated to the target directory;
 2. the one live shared TUI;
@@ -178,6 +183,14 @@ TUI refresh, and list highlight); deleting any other session leaves the current
 selection unchanged. In broadcast mode `d` deletes just the cursor session
 while `D` (Shift+d) deletes every selected session at once — after confirming,
 broadcast mode ends and the row under the cursor becomes the new current.
+In broadcast mode `Enter` switches to the cursor session and ends broadcast,
+while `ESC`/`q` cancel it; every exit clears the persisted `broadcast` list, as
+does picking any session in the normal switcher, so a stale selection never
+survives to keep `agentp` broadcasting. On start the picker adopts a stored
+`broadcast` only when at least two of its ids still name listed sessions; it then
+opens in broadcast mode (re-anchoring on a selected session when the stored
+`session` is not in the list), and otherwise clears the invalid list before
+showing the normal state.
 Interactive prompts (create/rename/reminder/delete/delete-all) take over the
 status bar and flip its background from brown to light yellow — the same color
 as the session-list pointer — so an active question is immediately visible.
@@ -185,6 +198,59 @@ The broadcast info line (`Broadcast to sessions: …`) never wraps: it holds up
 to 480 characters of names (or the terminal width, whichever is smaller), and
 an oversized selection is truncated from the beginning with a leading `...`.
 
+**Live activity.** Every listed session that is currently running (a foreground
+drain, per `GET /api/session/active`) shows an animated spinner in its row, and
+the info panel's status says `BUSY`. The picker's initial `runningIds` is a
+snapshot taken at open; while the picker stays open it re-polls that endpoint
+every second and updates the set, so sessions that start a turn after the menu
+opened begin spinning and sessions that finish stop — the animation timer starts
+and stops to match. Failures of the poll degrade silently: the previous set
+stays and the next poll retries.
+
+**Pending-answer awareness.** While the picker is open it re-polls the project
+every 2 seconds (`GET /api/form` and `GET /api/permission/request`, both
+location-scoped with the `location[directory]=…` deepObject parameter) and
+tracks which session ids currently await an agent question (a form) or a
+permission reply. Sessions carry two independent marker columns — ❓ (question)
+and 🔒 (permission) — each a fixed 2-column cell whose placeholder keeps rows
+aligned when a session has no marker. A single 🔔 leads the status bar (forced
+left-aligned) whenever any listed session is waiting, and the cursor session's
+marker columns are pinned to the info panel's top-right corner (the Title line
+is padded out to `cols - cells.length`).
+Failures of the poll degrade silently: the previous sets stay and the next poll
+retries.
+
+**Answer mode (`A`).** When the cursor session has a pending form, `A` fetches
+`GET /api/session/{id}/form` and switches to a dedicated answer screen. It
+renders each visible field as a header plus its option rows; multi-select
+fields toggle extra entries, boolean fields render Yes/No, choice fields with
+`custom` get a "Type your own answer" row, and option-less (free-text/numeric)
+fields open the status-bar input directly. Fields with `hidden` or `when`
+conditions are filtered live over the answers chosen so far (a gated group
+appears the moment its gate question is answered). The final `Submit answers
+(n/m answered)` row posts the keyed answer map
+(`POST /api/session/{id}/form/{formID}/reply`, `{answer: {fieldKey: value}}`).
+On success the remaining forms are re-fetched: the next pending form is
+answered in turn, or the picker returns to the session list with a
+`✔ Answers submitted.` notice. A 400 rejection shows the server's message
+(`message` or `error.message` from the body) in the status bar and stays in
+answer mode for correction; a 409 (already settled elsewhere) reports the
+server message and returns to the list. `h` toggles the answer-mode help,
+`q`/`ESC` cancels without answering, `Ctrl+C` exits.
+
+**Permission answering (`P`).** Permissions are answered from a dedicated
+screen opened with `P` on a session with a pending permission request (🔒
+marker). It re-reads the location-scoped `GET /api/permission/request` list
+(currently answered requests settle out of it) and filters to the cursor
+session. Each request is shown with its action, resources and optional message;
+one key answers it — `o`/`1` allow once, `a` allow always, `r` reject — posting
+`POST /api/session/{sessionID}/permission/{requestID}/reply` with
+`{decision: 'once' | 'always' | 'reject'}`. Success drops the request and
+advances to the next; after the last it returns to the session list with a
+`✔ Permission answered.` notice. A rejected reply (400) shows the server's
+message in the status bar and stays; `h` toggles a help screen, `q`/`ESC` leaves
+everything pending, `Ctrl+C` exits.
+
 ### `ocmux session <id|title> [dir]`
 
 Non-interactively writes the selected session and refreshes its routed TUI.
@@ -199,6 +265,12 @@ By default the switcher only inspects sessions through the routed TUI and never
 writes another project's state. `--all-projects` lets the outer session picker
 move to another project and subsequently update that project's state.
 
+The switcher shows the same pending-answer awareness as the session picker:
+session rows carry their own ❓/🔒 marker columns, and a folded project row
+shows them aggregated over all of its sessions' pending forms/permissions
+(fetched once per project when the switcher opens, from each project's recorded
+server).
+
 ### `ocmux list [-l]`
 
 Lists configured projects, selected sessions, and display status:
@@ -214,9 +286,17 @@ The old managed-window `kill` and `resurrect` commands do not exist.
 ## 8. `agentp`
 
 `agentp` resolves project/session/server from explicit options and the nearest
-state file, then sends directly to the session API. It does not focus, move, or
-refresh a TUI; TUI routing is an explicit consequence of ocmux session
-selection, not prompt submission.
+state file, then sends directly to the session API. Sending a prompt (normal or
+`--defer`) also routes the project's TUI to the target session, so the answer
+streams in view: the pane is respawned only when it does not already show that
+project/session. Re-submitting a deferred ticket does the same for the ticket's
+session, whose project directory is derived from the session's own location.
+
+Routing is best-effort and never fails the prompt. It resolves like section 4
+(dedicated → shared → headless, silent when no pane is registered), is skipped
+for broadcast prompts (no single session to show) and for the detached
+`--defer-child` worker, and routing always keys on `sessionId`/`sessionIds` —
+the human-readable session name on a ticket is display-only.
 
 ## 9. Failure behavior
 

package/lib/opencode.js

@@ -782,7 +782,9 @@ function isServerAlive(url) {
   }).catch(() => false);
 }
 
-// Respond to a question (choice) asked by the AI (v2 form reply).
+// Respond to a question (choice) asked by the AI (v2 form reply). The v2 reply
+// body takes a KEYED answer map (one reply settles the whole form), but the
+// legacy scalar shape still works for the single-question case.
 async function respondToQuestion(server, sessionId, questionId, answer) {
   const encodedS = encodeURIComponent(sessionId);
   const encodedQ = encodeURIComponent(questionId);
@@ -792,6 +794,92 @@ async function respondToQuestion(server, sessionId, questionId, answer) {
   if (status !== 200 && status !== 204) throw new Error(`Failed to respond to question: ${status}`);
 }
 
+// Pull the human-readable message out of a v2 error payload when possible
+// (e.g. `{ _tag: 'FormInvalidAnswerError', message, ... }`).
+function serverMessage(body) {
+  try {
+    const parsed = JSON.parse(body || '');
+    if (parsed && typeof parsed === 'object') {
+      if (typeof parsed.message === 'string' && parsed.message) return parsed.message;
+      if (parsed.error && typeof parsed.error.message === 'string' && parsed.error.message) return parsed.error.message;
+    }
+  } catch { /* not JSON */ }
+  return null;
+}
+
+// Pending forms (agent questions) across a location (project directory).
+// `location` is a deepObject query param ({ directory }): /api/form?location[directory]=…
+async function listPendingForms(server, directory) {
+  const base = await apiBase(server);
+  const params = new URLSearchParams();
+  if (directory) params.set('location[directory]', directory);
+  const { status, body } = await makeRequest(buildJsonRequest(`${base}/form?${params}`, 'GET'));
+  if (status !== 200) throw new Error(`Failed to list pending forms: ${status}`);
+  const parsed = parseBody(body);
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+// Pending forms for a single session (GET /api/session/:id/form). Each entry
+// carries its own `fields` array — enough to render an answer UI.
+async function listSessionForms(server, sessionId) {
+  const encoded = encodeURIComponent(sessionId);
+  const base = await apiBase(server);
+  const { status, body } = await makeRequest(buildJsonRequest(`${base}/session/${encoded}/form`, 'GET'));
+  if (status !== 200) throw new Error(`Failed to list session forms: ${status}`);
+  const parsed = parseBody(body);
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+// Submit answers to a pending form. `answers` maps field keys to values
+// (string | number | boolean | string[] for multiselect); one reply settles
+// the whole form. Throws with `err.status` (400 invalid answer, 409 already
+// answered) and the server's message when it provides one.
+async function replyToForm(server, sessionId, formId, answers) {
+  const encodedS = encodeURIComponent(sessionId);
+  const encodedF = encodeURIComponent(formId);
+  const base = await apiBase(server);
+  const body = JSON.stringify({ answer: answers });
+  const { status, body: resBody } = await makeRequest(
+    buildJsonRequest(`${base}/session/${encodedS}/form/${encodedF}/reply`, 'POST', body), body,
+  );
+  if (status !== 200 && status !== 204) {
+    const err = new Error(serverMessage(resBody) || `Failed to answer form: ${status}`);
+    err.status = status;
+    throw err;
+  }
+}
+
+// Pending permission requests across a location (GET /api/permission/request).
+// The server returns { location, data: Permission.Request[] }; parseBody
+// unwraps the data envelope.
+async function listPendingPermissions(server, directory) {
+  const base = await apiBase(server);
+  const params = new URLSearchParams();
+  if (directory) params.set('location[directory]', directory);
+  const { status, body } = await makeRequest(buildJsonRequest(`${base}/permission/request?${params}`, 'GET'));
+  if (status !== 200) throw new Error(`Failed to list pending permissions: ${status}`);
+  const parsed = parseBody(body);
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+// Reply to a pending permission request. `decision` is 'once' | 'always' |
+// 'reject'. Throws with `err.status` and the server's message when it provides
+// one.
+async function replyToPermission(server, sessionId, requestId, decision) {
+  const encodedS = encodeURIComponent(sessionId);
+  const encodedR = encodeURIComponent(requestId);
+  const base = await apiBase(server);
+  const body = JSON.stringify({ decision });
+  const { status, body: resBody } = await makeRequest(
+    buildJsonRequest(`${base}/session/${encodedS}/permission/${encodedR}/reply`, 'POST', body), body,
+  );
+  if (status !== 200 && status !== 204) {
+    const err = new Error(serverMessage(resBody) || `Failed to reply to permission: ${status}`);
+    err.status = status;
+    throw err;
+  }
+}
+
 // Sort sessions most-recently-viewed first (`time.viewed`), tie-broken by
 // `time.updated`, then `time.created`. Used for target selection so agentp and
 // ocmux line up with what the TUI last showed.
@@ -877,6 +965,12 @@ module.exports = {
   sendText,
   listenForFinalAnswer,
   respondToQuestion,
+  replyToForm,
+  listPendingForms,
+  listSessionForms,
+  listPendingPermissions,
+  replyToPermission,
+  serverMessage,
   listSessions,
   listProjects,
   getActiveSessions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentp",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Pipe prompts into a running OpenCode TUI session and stream the final answer",
   "bin": {
     "agentp": "bin/agentp",