agentp 2.1.0 → 2.1.2

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.
@@ -59,6 +63,8 @@ Each instance records:
 - tmux socket and pane ID;
 - dedicated/shared mode;
 - last directory, server, and session;
+- the directory and session currently displayed (so routing can skip a
+  respawn that would change nothing);
 - foreground wrapper PID and current child PID (diagnostic only);
 - registration/update timestamps.
 
@@ -95,7 +101,9 @@ a different server, the same pane reconnects to that server.
 `ocmux tui [--shared] [directory]`:
 
 1. Requires `$TMUX` and `$TMUX_PANE`.
-2. Resolves `.ocmux.json`, server, directory, and session.
+2. Resolves `.ocmux.json`, server, directory, and session. A shared TUI may run
+   without a state file, in which case it uses the current directory and the
+   default server (`$OCMUX_SERVER` or `http://localhost:4096`).
 3. Health-checks the server and validates the session, creating one with a
    model when necessary.
 4. Marks and registers the current pane.
@@ -127,6 +135,10 @@ The new `ocmux tui` process re-registers the pane and hosts the new OpenCode
 child. Server-side session execution continues while the old client disconnects.
 Client-local state—draft prompt, scroll position, dialogs, and tabs—is lost.
 
+Routing is idempotent: the registry records the directory and session the pane
+currently displays, so a switch to the same project/session is skipped without
+respawning.
+
 Native TUI navigation is temporary inspection and is not observable through
 the OpenCode HTTP API. The next ocmux selection restores the canonical target.
 
@@ -142,7 +154,8 @@ or creating one with a model. It creates no tmux session, window, or pane.
 
 Registers and hosts a dedicated or shared TUI as described above. `--shared`
 is valid only for this command. `--server` overrides the project's recorded
-server for the launched wrapper. Management modes are:
+server for the launched wrapper; when `--shared` runs without a state file it
+falls back to the default server. Management modes are:
 
 - `ocmux tui --list` — prune stale entries and print every live registration;
 - `ocmux tui [dir] --status` — inspect the dedicated slot for that project;
@@ -156,9 +169,77 @@ destroy the pane. Management modes do not require running inside tmux.
 ### `ocmux`
 
 Opens the current project's session picker. Picking writes that project's
-session and refreshes its routed TUI. Session creation, rename/delete,
+session and refreshes its routed TUI. Merely opening the picker also routes the
+applicable TUI to the project's stored session (skipped when it already shows
+it), so starting `ocmux` in a project switches the display even without picking
+a row. When the recorded server is unreachable but the default server answers,
+`ocmux` offers on a TTY to repoint the project to the default and rewrites
+`server`. Session creation, rename/delete,
 annotations, agent/model choice, broadcast selection, search, and project
-inspection operate through OpenCode's API.
+inspection operate through OpenCode's API. Deleting the session currently
+selected adopts the session under the cursor as the new current (state write,
+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.
+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 `...`.
+
+**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]`
 
@@ -174,6 +255,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:

package/lib/ocmux.js

@@ -18,7 +18,15 @@ function tuiArgs(server, session, directory) {
 function switchTui(directory, server, session, executable) {
   const target = registry.resolve(directory);
   if (!target) return { ok: false, reason: 'none' };
-  const result = registry.respawn(target.instance, {
+  // Skip the respawn when the routed pane already shows this project/session,
+  // so merely opening ocmux does not restart a TUI that is already correct.
+  const instance = target.instance;
+  if (instance.activeDirectory
+    && path.resolve(instance.activeDirectory) === path.resolve(directory)
+    && String(instance.activeSession || '') === String(session || '')) {
+    return { ok: true, kind: target.kind, instance, unchanged: true };
+  }
+  const result = registry.respawn(instance, {
     executable: executable || path.resolve(__dirname, '..', 'bin', 'ocmux'),
     directory,
     server,
@@ -28,7 +36,7 @@ function switchTui(directory, server, session, executable) {
     registry.pruneDead();
     return { ok: false, reason: 'failed', kind: target.kind, error: result.error };
   }
-  return { ok: true, kind: target.kind, instance: target.instance };
+  return { ok: true, kind: target.kind, instance };
 }
 
 module.exports = {

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/lib/tui-registry.js

@@ -171,6 +171,10 @@ function register({ socket, pane, shared, directory, server, session, pid }) {
     directory: directory ? path.resolve(directory) : null,
     server: server || null,
     session: session || null,
+    // What the pane is currently displaying. `respawn()` refreshes these so a
+    // caller (ocmux) can skip restarting a TUI that already shows the target.
+    activeDirectory: directory ? path.resolve(directory) : null,
+    activeSession: session || null,
     pid: Number(pid) || process.pid,
     registeredAt: now,
     updatedAt: now,
@@ -276,6 +280,10 @@ function respawn(instance, { executable, directory, server, session }) {
   if (result.status !== 0) {
     return { ok: false, error: (result.stderr || '').trim() || `failed to respawn ${instance.pane}` };
   }
+  updateInstance(instance.id, instance.token, {
+    activeDirectory: directory ? path.resolve(directory) : null,
+    activeSession: session || null,
+  });
   return { ok: true };
 }
 

package/package.json

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