agentp 0.11.11 → 1.12.1

package/README.md

@@ -22,6 +22,8 @@ It is designed for prompt-driven workflows where you want to do things like:
 
 These tools are built for my own daily workflow. They are heavily AI-assisted — including the tests — and I review things before shipping, but the real test is using them every day. Bugs happen; I value a working feature more than a flawless one. MIT license, no warranty. Issues, suggestions, and PRs are welcome.
 
+**Stability note:** `agentp` and `ocmux` are stable and used daily. `tgagentp` is still in a highly experimental stage — expect breaking changes and occasional bugs.
+
 ## Install
 
 From npm:
@@ -57,6 +59,7 @@ agentp [options] [url]
 Options:
 
 - `--qa`: print the original prompt and answer with labels (useful when used as a filter)
+- `--defer`: deferred execution — submit prompt, get immediate ticket, retrieve result later
 - `--tg`: forward the answer to Telegram via tgagentp gateway (error if unreachable)
 - `--no-tg`: do not forward to Telegram
 - `--flush`: flush tgagentp's recorded buffer without prepending it to output
@@ -142,6 +145,39 @@ From Vim/Neovim, flush the recorded buffer without prepending context:
 Useful when you've finished a conversation thread and want to reset the recorded
 context for a new topic.
 
+Deferred execution with `--defer`:
+
+Submit a prompt and get an immediate ticket to retrieve the result later:
+
+```bash
+# Submit a prompt and get a deferred reference
+DEFERRED=$(printf "Refactor the authentication module" | agentp --defer)
+# Output: <agentp-deferred>/tmp/agentp_deferred_20260803_1430_a1b2.tmp</agentp-deferred>
+
+# Continue working... retrieve the result when ready
+printf '%s\n' "$DEFERRED" | agentp --defer
+# Output: (the agent's response)
+```
+
+Works as a Vim/Neovim filter with deferred execution:
+
+```vim
+" Submit selection, get ticket immediately, continue editing
+:'<,'>!agentp --defer --qa
+
+" Later, retrieve the result
+:r !printf '%s\n' "<agentp-deferred>/tmp/agentp_deferred_...tmp</agentp-deferred>" | agentp --defer
+```
+
+The deferred workflow:
+1. Submit prompt with `--defer` → get immediate ticket (`<agentp-deferred>...</agentp-deferred>`)
+2. Continue working (the agent processes in background)
+3. When ready, pipe the ticket back to `agentp --defer` to retrieve the result
+4. If the agent is still processing, you get your input back (identity filter)
+4. If complete, you get the agent's response and the temp file is cleaned up
+
+Useful for long-running tasks where you don't want to block your editor.
+
 Retrieve the last 3 assistant answers from session history:
 
 ```bash
@@ -231,21 +267,28 @@ Non-text Telegram updates (photos, stickers, etc.) are silently ignored.
 ### Slash commands
 
 | Command | Action |
-|---|---|
+|---|---|---|
 | `/help [topic]` | Show general help or help for a topic (`servers`, `sessions`, `agents`, `models`, `allow`, `think`, `record`, `queue`) |
 | `/servers` | List all ocmux-served projects (▶ active, 🔌 disconnected, 💀 dead) |
-| `/servers switch <name> [--force]` | Switch active server; matches by full path, basename, or substring; `--force` takes over from another chat |
+| `/server <name>` | Switch active server; matches by full path, basename, or substring |
+| `/server --force <name>` | Take over a server from another chat |
 | `/resurrect [path]` | Restart a crashed server from its `.ocmux.json`; accepts optional directory path |
+| `/sessions` | List sessions (numbered, newest first) |
+| `/session <name-or-number>` | Switch to a session by name or position |
+| `/session new [name]` | Create a new session |
+| `/session rename <name>` | Rename the active session |
+| `/agents` | List available agents/models |
+| `/agent <name>` | Switch the active agent for subsequent messages (synced to server via API) |
+| `/models` | List providers and models (▶ marks current) |
+| `/model <providerID/modelID>` | Switch session model |
 | `/allow` | Approve a permission request once |
 | `/reject` | Deny a permission request |
 | `/always` | Approve and remember for the session |
 | `/answer <number>` | Respond to a question asked by the AI (structured multiple-choice) |
 | `/markdown` | Send the original markdown of the last response as a `.md` file; reply to a message to get that specific response |
-| `/agents list` | List available agents/models |
-| `/agents switch <name>` | Switch the active agent for subsequent messages (synced to server via API) |
 | `/shutdown [force\|clear]` | (requires `--dev`) Stop tgagentp; `clear` also wipes saved connections |
 
-> **Note on model/agent switching:** Changing the model in the OpenCode TUI's prompt dropdown is a **local UI action** — it only takes effect server-side after a message is sent *through the TUI*. If you change the model in the TUI and then send a prompt via `agentp` or Telegram, the old model will still be used. Use `/agents switch <name>` from Telegram (or `tgagentp`) to change models — this explicitly calls the API and syncs correctly.
+> **Note on model/agent switching:** Changing the model in the OpenCode TUI's prompt dropdown is a **local UI action** — it only takes effect server-side after a message is sent *through the TUI*. If you change the model in the TUI and then send a prompt via `agentp` or Telegram, the old model will still be used. Use `/agent <name>` or `/model <providerID/modelID>` from Telegram (or `tgagentp`) to change models — this explicitly calls the API and syncs correctly.
 
 #### TUI Command Passthrough
 
@@ -255,7 +298,7 @@ Messages starting with `//` are forwarded to the OpenCode TUI as raw keystrokes
 
 ### Chat-server ownership
 
-Each server can be owned by at most one chat at a time. New chats start disconnected. Use `/servers switch <name>` to connect; `--force` takes over and notifies the previous owner. Connections are persisted to `/tmp/tgagentp-connections.json` and restored automatically on restart (server URL is re-discovered from `.ocmux.json`).
+Each server can be owned by at most one chat at a time. New chats start disconnected. Use `/server <name>` to connect; `--force` takes over and notifies the previous owner. Connections are persisted to `/tmp/tgagentp-connections.json` and restored automatically on restart (server URL is re-discovered from `.ocmux.json`).
 
 ### Per-server state
 
@@ -287,7 +330,7 @@ tgagentp starts a tiny HTTP server on `127.0.0.1` that accepts `POST /send` requ
 - Port is written to `/tmp/tgagentp-port` for agentp discovery.
 - Authentication reuses `OPENCODE_SERVER_PASSWORD`.
 - Messages for the owning chat's active server are delivered immediately.
-- Messages for non-active servers are queued per-server with debounced notifications (configurable via `TGAGENTP_DEBOUNCE_MS`); delivered on `/servers switch`.
+- Messages for non-active servers are queued per-server with debounced notifications (configurable via `TGAGENTP_DEBOUNCE_MS`); delivered on `/server <name>`.
 - Server health detection pre-sends: if a server is unreachable, messages are auto-queued and delivered when it comes back. `/flush` clears all queues.
 - When [/record](#tgagentp) is active, the gateway response includes the recorded conversation buffer. `agentp --qa` prepends this buffer (with rulers) to its stdout so the full Telegram context is available to OpenCode. Use `agentp --qa --flush` to flush the buffer without prepending.
 

package/bin/agentp

@@ -2,6 +2,9 @@
 
 const http = require('http');
 const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
 const readline = require('readline');
 const child_process = require('child_process');
 const { version } = require('../package.json');
@@ -60,6 +63,51 @@ function notifyAgentpGateway(port, server, text) {
   });
 }
 
+function isFileLocked(filePath) {
+  const lockPath = filePath + '.lock';
+  try {
+    if (!fs.existsSync(lockPath)) return false;
+    const pid = parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
+    if (isNaN(pid)) return false;
+    // Check if process is still alive
+    try {
+      process.kill(pid, 0);
+      return true; // Process exists, file is locked
+    } catch (err) {
+      // Process doesn't exist, lock is stale
+      fs.unlinkSync(lockPath);
+      return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+function lockFile(filePath) {
+  const lockPath = filePath + '.lock';
+  fs.writeFileSync(lockPath, String(process.pid));
+}
+
+function unlockFile(filePath) {
+  const lockPath = filePath + '.lock';
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    // Ignore errors
+  }
+}
+
+function generateTempFilename() {
+  const now = new Date();
+  const timestamp = now.getFullYear().toString() +
+    String(now.getMonth() + 1).padStart(2, '0') +
+    String(now.getDate()).padStart(2, '0') + '_' +
+    String(now.getHours()).padStart(2, '0') +
+    String(now.getMinutes()).padStart(2, '0');
+  const hash = crypto.randomBytes(2).toString('hex').slice(0, 4);
+  return path.join(os.tmpdir(), `agentp_deferred_${timestamp}_${hash}.tmp`);
+}
+
 async function readAllStdin() {
   let text = '';
   const rl = readline.createInterface({ input: process.stdin });
@@ -78,6 +126,10 @@ async function main() {
   let serverBase = 'http://localhost:4096';
   let qaMode = false;
   let flushMode = false;
+  let deferMode = false;
+  let deferChildMode = false;
+  let promptFile = null;
+  let outputFile = null;
   let sessionName = null;
   let newSession = false;
   // tgMode: false = disabled, 'auto' = auto-detect, true = explicit --tg
@@ -96,6 +148,7 @@ async function main() {
       console.error('Options:');
       console.error('  --version   Show version');
       console.error('  --qa        Print the original prompt and answer with labels (useful as a filter)');
+      console.error('  --defer     Deferred execution: write prompt to temp file, return path immediately');
       console.error('  --tg        Forward the answer to Telegram via agentp gateway (error if unavailable)');
       console.error('  --no-tg     Do not forward to Telegram');
       console.error('  --flush     Flush tgagentp\'s recorded buffer without prepending it to output');
@@ -139,6 +192,16 @@ async function main() {
       process.exit(0);
     } else if (args[i] === '--qa') {
       qaMode = true;
+    } else if (args[i] === '--defer') {
+      deferMode = true;
+    } else if (args[i] === '--defer-child') {
+      deferChildMode = true;
+    } else if (args[i] === '--prompt-file') {
+      i++;
+      promptFile = args[i];
+    } else if (args[i] === '--output-file') {
+      i++;
+      outputFile = args[i];
     } else if (args[i] === '--flush') {
       flushMode = true;
     } else if (args[i] === '--session') {
@@ -289,113 +352,239 @@ async function main() {
 
   const promptText = await readAllStdin();
 
-  // Find most recent session or create one
-  let sessions;
-  try {
-    sessions = await listSessions(serverBase);
-  } catch (err) {
-    console.error('Error connecting to server:', err.message);
-    process.exit(1);
+  // Handle --defer mode
+  if (deferMode) {
+    // Check if stdin is a deferred reference
+    const deferredMatch = promptText.match(/<agentp-deferred>(.*?)<\/agentp-deferred>/);
+    
+    if (deferredMatch) {
+      // This is a deferred reference - retrieve the result
+      const deferredPath = deferredMatch[1].trim();
+      
+      if (!fs.existsSync(deferredPath)) {
+        // File doesn't exist - error
+        process.stdout.write(`Error: deferred file not found: ${deferredPath}\n`);
+        process.exit(1);
+      }
+      
+      // Check if file is locked (still processing) or empty (not ready yet)
+      const isLocked = isFileLocked(deferredPath);
+      let content = '';
+      try {
+        content = fs.readFileSync(deferredPath, 'utf8');
+      } catch {
+        content = '';
+      }
+      
+      if (isLocked || content === '') {
+        // File is locked (still processing) or empty (not ready yet) - identity filter
+        process.stdout.write(promptText);
+        process.exit(0);
+      }
+      
+      // File exists, not locked, and has content - read and delete
+      try {
+        fs.unlinkSync(deferredPath);
+        process.stdout.write(content);
+        process.exit(0);
+      } catch (err) {
+        process.stdout.write(`Error reading deferred file: ${err.message}\n`);
+        process.exit(1);
+      }
+    } else {
+      // This is a regular prompt - create deferred execution
+      const tempPath = generateTempFilename();
+      const promptTempPath = tempPath + '.prompt';
+      
+      // Write prompt to temp file for child process
+      fs.writeFileSync(promptTempPath, promptText);
+      
+      // Create and lock the output file
+      fs.writeFileSync(tempPath, '');
+      lockFile(tempPath);
+      
+      // Output the deferred reference
+      process.stdout.write(`<agentp-deferred>${tempPath}</agentp-deferred>\n`);
+      
+      // Spawn detached child process
+      const childArgs = [
+        __filename,
+        '--defer-child',
+        '--prompt-file', promptTempPath,
+        '--output-file', tempPath,
+      ];
+      
+      // Pass through other flags
+      if (qaMode) childArgs.push('--qa');
+      if (tgMode === true) childArgs.push('--tg');
+      if (tgMode === false) childArgs.push('--no-tg');
+      if (flushMode) childArgs.push('--flush');
+      if (sessionName) {
+        childArgs.push('--session', sessionName);
+        if (newSession) childArgs.push('--new');
+      }
+      childArgs.push(serverBase);
+      
+      const child = child_process.spawn(process.execPath, childArgs, {
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+      
+      process.exit(0);
+    }
   }
 
-  let sessionId = null;
+  // Handle --defer-child mode (child process)
+  let actualPromptText = promptText;
+  if (deferChildMode && promptFile) {
+    try {
+      actualPromptText = fs.readFileSync(promptFile, 'utf8');
+      fs.unlinkSync(promptFile);
+    } catch (err) {
+      const errMsg = `Error reading prompt file: ${err.message}\n`;
+      if (outputFile) { fs.writeFileSync(outputFile, errMsg); unlockFile(outputFile); }
+      process.stdout.write(errMsg);
+      process.exit(1);
+    }
+  }
 
-  if (sessionName) {
-    // Find session by name
-    const matches = sessions.filter(s => {
-      const title = s.title || s.slug || s.id;
-      return title.toLowerCase() === sessionName.toLowerCase();
-    });
-    if (matches.length === 0) {
-      // Try partial match
-      const partial = sessions.filter(s => {
+  // Wrap main processing in try-catch for deferChildMode to write errors to output file
+  async function runMain() {
+    // Find most recent session or create one
+    let sessions;
+    try {
+      sessions = await listSessions(serverBase);
+    } catch (err) {
+      throw new Error(`Error connecting to server: ${err.message}`);
+    }
+
+    let sessionId = null;
+
+    if (sessionName) {
+      // Find session by name
+      const matches = sessions.filter(s => {
         const title = s.title || s.slug || s.id;
-        return title.toLowerCase().includes(sessionName.toLowerCase());
+        return title.toLowerCase() === sessionName.toLowerCase();
       });
-      if (partial.length === 1) {
-        sessionId = partial[0].id;
-      } else if (partial.length > 1) {
-        console.error(`Error: multiple sessions match "${sessionName}":`);
-        partial.forEach(s => console.error(`  - ${s.title || s.slug || s.id}`));
-        process.exit(1);
-      } else if (newSession) {
-        // Create new session
-        try {
-          const session = await createSession(serverBase, sessionName);
-          sessionId = session.id;
-          await selectSession(serverBase, sessionId);
-        } catch (err) {
-          console.error('Error creating session:', err.message);
-          process.exit(1);
+      if (matches.length === 0) {
+        // Try partial match
+        const partial = sessions.filter(s => {
+          const title = s.title || s.slug || s.id;
+          return title.toLowerCase().includes(sessionName.toLowerCase());
+        });
+        if (partial.length === 1) {
+          sessionId = partial[0].id;
+        } else if (partial.length > 1) {
+          throw new Error(`Error: multiple sessions match "${sessionName}"`);
+        } else if (newSession) {
+          // Create new session
+          try {
+            const session = await createSession(serverBase, sessionName);
+            sessionId = session.id;
+            await selectSession(serverBase, sessionId);
+          } catch (err) {
+            throw new Error(`Error creating session: ${err.message}`);
+          }
+        } else {
+          throw new Error(`Error: no session found matching "${sessionName}"`);
         }
       } else {
-        console.error(`Error: no session found matching "${sessionName}"`);
-        console.error('Use --new to create a new session with this name');
-        process.exit(1);
+        sessionId = matches[0].id;
+      }
+    } else if (sessions && sessions.length > 0) {
+      const sorted = sessions
+        .filter(s => s.time && (s.time.updated || s.time.created))
+        .sort((a, b) => {
+          const aTime = (a.time && a.time.updated) || (a.time && a.time.created) || 0;
+          const bTime = (b.time && b.time.updated) || (b.time && b.time.created) || 0;
+          return bTime - aTime;
+        });
+      if (sorted.length > 0) sessionId = sorted[0].id;
+    }
+
+    if (!sessionId) {
+      try {
+        const session = await createSession(serverBase, 'agentp');
+        sessionId = session.id;
+      } catch (err) {
+        throw new Error(`Error creating session: ${err.message}`);
       }
-    } else {
-      sessionId = matches[0].id;
     }
-  } else if (sessions && sessions.length > 0) {
-    const sorted = sessions
-      .filter(s => s.time && (s.time.updated || s.time.created))
-      .sort((a, b) => {
-        const aTime = (a.time && a.time.updated) || (a.time && a.time.created) || 0;
-        const bTime = (b.time && b.time.updated) || (b.time && b.time.created) || 0;
-        return bTime - aTime;
-      });
-    if (sorted.length > 0) sessionId = sorted[0].id;
-  }
 
-  if (!sessionId) {
+    let answer;
     try {
-      const session = await createSession(serverBase, 'agentp');
-      sessionId = session.id;
+      answer = await sendToSession(serverBase, sessionId, actualPromptText);
     } catch (err) {
-      console.error('Error creating session:', err.message);
-      process.exit(1);
+      throw new Error(`Error sending prompt: ${err.message}`);
+    }
+
+    // Build the message to send to Telegram (QA pair with rulers)
+    let tgMessage = answer;
+    if (qaMode) {
+      tgMessage = HUMAN_ROW + actualPromptText + AGENT_ROW + answer;
+      if (!answer.endsWith('\n')) tgMessage += '\n';
+      tgMessage += FINAL_ROW;
     }
+
+    // Post-send: notify tgagentp, get recorded context back
+    let buffered = [];
+    let tgError = null;
+    if (tgPort) {
+      try {
+        buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
+      } catch (err) {
+        tgError = err;
+      }
+    }
+
+    // Build output (prepend recorded context if any, unless --flush)
+    let output = '';
+    if (qaMode) {
+      if (!flushMode && buffered.length > 0) {
+        for (const msg of buffered) {
+          const row = msg.role === 'user' ? HUMAN_ROW : AGENT_ROW;
+          output += row + msg.text + '\n';
+        }
+      }
+      output += tgMessage;
+    } else {
+      output = tgMessage;
+      if (!tgMessage.endsWith('\n')) output += '\n';
+    }
+
+    return output;
   }
 
-  let answer;
+  // Execute main processing with error handling for child mode
+  let output = '';
   try {
-    answer = await sendToSession(serverBase, sessionId, promptText);
+    output = await runMain();
   } catch (err) {
-    console.error('Error sending prompt:', err.message);
+    const errMsg = err.message + '\n';
+    if (deferChildMode && outputFile) {
+      fs.writeFileSync(outputFile, errMsg);
+      unlockFile(outputFile);
+    } else {
+      process.stdout.write(errMsg);
+    }
     process.exit(1);
   }
 
-  // Build the message to send to Telegram (QA pair with rulers)
-  let tgMessage = answer;
-  if (qaMode) {
-    tgMessage = HUMAN_ROW + promptText + AGENT_ROW + answer;
-    if (!answer.endsWith('\n')) tgMessage += '\n';
-    tgMessage += FINAL_ROW;
-  }
-
-  // Post-send: notify tgagentp, get recorded context back
-  let buffered = [];
-  let tgError = null;
-  if (tgPort) {
+  // Write output to file (child mode) or stdout (normal mode)
+  let finalOutput = output;
+  if (deferChildMode && outputFile) {
     try {
-      buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
+      fs.writeFileSync(outputFile, output);
+      unlockFile(outputFile);
     } catch (err) {
-      tgError = err;
-    }
-  }
-
-  // Build stdout output (prepend recorded context if any, unless --flush)
-  if (qaMode) {
-    if (!flushMode && buffered.length > 0) {
-      for (const msg of buffered) {
-        const row = msg.role === 'user' ? HUMAN_ROW : AGENT_ROW;
-        process.stdout.write(row + msg.text + '\n');
-      }
+      const errMsg = `Error writing output file: ${err.message}\n`;
+      try { fs.writeFileSync(outputFile, errMsg); } catch {}
+      unlockFile(outputFile);
+      process.exit(1);
     }
-    process.stdout.write(tgMessage);
   } else {
-    process.stdout.write(tgMessage);
-    if (!tgMessage.endsWith('\n')) process.stdout.write('\n');
+    process.stdout.write(output);
   }
 
   // Warnings at the end (stderr)