agentp 0.12.0 → 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

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)

package/bin/tgagentp

@@ -1017,20 +1017,38 @@ async function processTelegramCommands(text, server, token, chatState) {
   const filesSent = [];
   const dir = serverDir(server);
 
+  // Resolve a file path: absolute paths used directly, relative paths resolved
+  // against the server's working directory. Returns null and sends an error
+  // message if the resolved path is outside the server's working directory.
+  function resolveUploadPath(p, errPrefix) {
+    const absolute = path.isAbsolute(p) ? p : path.resolve(dir || '', p);
+    if (!dir) return absolute; // no server dir — trust the path
+    let realDir, realPath;
+    try { realDir = fs.realpathSync(dir); } catch { realDir = dir; }
+    try { realPath = fs.realpathSync(absolute); } catch { realPath = absolute; }
+    if (!realPath.startsWith(realDir + path.sep) && realPath !== realDir) {
+      sendLongMessage(token, chatState,
+        `❌ ${errPrefix}: path outside project directory.\n` +
+        `  Path: \`${p}\`\n` +
+        `  Project: \`${realDir}\`\n\n` +
+        `Use a full path (starting with /) or a path relative to the project root.`).catch(() => {});
+      return null;
+    }
+    return absolute;
+  }
+
   for (let i = 0; i < lines.length; i++) {
     const payload = parseTelegramLine(lines[i]);
     if (!payload) continue;
 
     if (payload.command === 'upload' && payload.path) {
       toStrip.add(i);
-      const resolved = dir ? path.resolve(dir, payload.path) : path.resolve(payload.path);
-      if (dir && !resolved.startsWith(dir + path.sep)) {
-        log.error(`processTelegramCommands: path outside project rejected: ${payload.path}`);
-        continue;
-      }
+      const resolved = resolveUploadPath(payload.path, 'Upload');
+      if (!resolved) continue;
       try {
         if (!fs.existsSync(resolved)) {
-          log.error(`processTelegramCommands: file not found: ${resolved}`);
+          await sendLongMessage(token, chatState,
+            `❌ File not found: \`${resolved}\``);
           continue;
         }
         const fileData = fs.readFileSync(resolved);
@@ -1039,22 +1057,21 @@ async function processTelegramCommands(text, server, token, chatState) {
         await sendTelegramDocument(token, chatState, fileData, fileName, caption);
         filesSent.push(fileName);
       } catch (err) {
-        log.error(`processTelegramCommands: failed to send file ${resolved}: ${err.message}`);
+        await sendLongMessage(token, chatState,
+          `❌ Failed to upload \`${resolved}\`: ${err.message}`);
       }
     } else if (payload.command === 'download' && payload.fileId && payload.path) {
       toStrip.add(i);
-      const resolved = dir ? path.resolve(dir, payload.path) : path.resolve(payload.path);
-      if (dir && !resolved.startsWith(dir + path.sep)) {
-        log.error(`processTelegramCommands: download path outside project rejected: ${payload.path}`);
-        continue;
-      }
+      const resolved = resolveUploadPath(payload.path, 'Download');
+      if (!resolved) continue;
       try {
         const fileData = await downloadTelegramFile(token, payload.fileId);
         fs.mkdirSync(path.dirname(resolved), { recursive: true });
         fs.writeFileSync(resolved, fileData);
         filesSent.push(path.basename(resolved));
       } catch (err) {
-        log.error(`processTelegramCommands: failed to download file: ${err.message}`);
+        await sendLongMessage(token, chatState,
+          `❌ Failed to download file to \`${resolved}\`: ${err.message}`);
       }
     } else if (payload.command === 'help') {
       toStrip.add(i);
@@ -2154,8 +2171,13 @@ async function main() {
     'Do NOT use CLI tools to generate them — just include them directly in your response:\n\n' +
     'To send a file to the user:\n' +
     '[Telegram]{"command":"upload","path":"<relative-path>","msg":"<optional caption>"}\n\n' +
+    '**Important:** `path` is relative to the project root (the OpenCode server\'s working directory).\n' +
+    'If the project uses a git worktree, the worktree directory IS the project root.\n' +
+    'Use CLI commands like `cat ./path/to/file` to verify the file exists before uploading.\n\n' +
     'To download a file the user sent:\n' +
     '[Telegram]{"command":"download","fileId":"<id>","path":"<relative-destination>"}\n\n' +
+    '**Important:** `path` is also relative to the project root (the OpenCode server\'s working directory).\n' +
+    'Use `ls` or `pwd` to confirm the current working directory before specifying download paths.\n\n' +
     'For more details about a command:\n' +
     '[Telegram]{"command":"help","topic":"<upload|download|help>"}';
 
@@ -2174,6 +2196,7 @@ async function main() {
     const monRef = { current: null };
     st._monitorRef = monRef;
     st._monitorStarted = true;
+    st._monitoredSessionId = sessionId;
 
     const notifiedPerms = new Set();
 
@@ -2239,6 +2262,7 @@ async function main() {
       if (getState(server)._monitorRef === monRef) {
         getState(server)._monitorRef = null;
         getState(server)._monitorStarted = false;
+        getState(server)._monitoredSessionId = null;
       }
     });
   }
@@ -2271,6 +2295,20 @@ async function main() {
 
   async function processMessageAsync(chatId, text, url, useSession, sessionId, myTaskId, replyTo, threadId) {
     const st = getState(url);
+    // Auto-discover active session if not set
+    if (!sessionId) {
+      try {
+        const discovered = await discoverActiveSession(url);
+        if (discovered) {
+          st.activeSessionId = discovered.id;
+          st.activeSessionName = discovered.name;
+          sessionId = discovered.id;
+          useSession = true;
+        }
+      } catch (err) {
+        log.debug(`processMessageAsync: auto-discover error: ${err.message}`);
+      }
+    }
     const isCancelled = () => getState(url).taskId !== myTaskId;
     const cancelRef = { current: null };
     const chatState = { chatId, threadId };
@@ -2281,11 +2319,12 @@ async function main() {
     st._cancelRef = cancelRef;
     st._sessionReq = sessionCancelRef;
 
-    // Ensure the persistent session monitor is running so question/permission
-    // events from any source (agentp, tgagentp, TUI) are caught, not just
-    // those triggered by this message's per-request SSE listener.
-    if (useSession && sessionId && !st._monitorStarted) {
-      startSessionMonitor(url, sessionId);
+    // Ensure the persistent session monitor is running and tracking the current session.
+    // Always restart when sessionId changes so TUI-initiated session switches are followed.
+    if (useSession && sessionId) {
+      if (!st._monitorStarted || st._monitoredSessionId !== sessionId) {
+        startSessionMonitor(url, sessionId);
+      }
     }
 
     try {

package/package.json

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