agentp 0.9.0 → 0.11.0

package/CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing to agentp
+
+## Introduction
+
+agentp is a collection of three zero-dependency Node.js CLI tools that extend [OpenCode](https://opencode.ai) with per-project tmux server management (`ocmux`), a stdin-to-session pipe (`agentp`), and a Telegram bot bridge (`tgagentp`).
+
+The project aims to stay **zero npm dependencies** — all tools use only the Node.js 18+ stdlib (`http`, `https`, `readline`, `url`, `child_process`, `fs`, `path`, `crypto`, `os`). PRs introducing new dependencies will not be accepted unless there is an exceptional justification.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js >= 18
+- npm (ships with Node.js)
+- tmux (optional, only needed for `ocmux` and `tgagentp` features)
+
+### Local Install
+
+```bash
+git clone <your-fork>
+cd agentp
+npm link          # registers bin/agentp, bin/ocmux, bin/tgagentp globally
+# or
+npm install -g .  # alternative
+```
+
+After linking, all three binaries are available globally. Run `tgagentp --help` or refer to `README.md`.
+
+### Code Map
+
+```
+agentp/
+├── bin/
+│   ├── agentp        — Stdin-to-OpenCode pipe
+│   ├── ocmux         — Tmux server manager
+│   └── tgagentp      — Telegram bot bridge
+├── lib/
+│   ├── opencode.js   — HTTP session API client (shared by agentp + tgagentp)
+│   └── ocmux.js      — Tmux management (shared by ocmux + tgagentp)
+├── tests/
+│   ├── opencode.test.js  — Unit tests for lib/opencode.js
+│   └── ocmux.test.js     — Unit tests for lib/ocmux.js
+├── docs/
+│   └── specification.md  — Technical architecture reference
+├── AGENTS.md             — Development notes and TODO
+├── CONTRIBUTING.md       — This file
+└── package.json
+```
+
+## Coding Standards
+
+### Style
+
+- **CommonJS** (`require` / `module.exports`) — no ES modules
+- **No semicolons** — the project uses ASI (automatic semicolon insertion)
+- **No comments** in production code — let the code speak; use descriptive variable/function names
+- **2-space indentation**
+- Single quotes for strings
+- `const` over `let`; avoid `var`
+- Arrow functions for callbacks and closures
+
+### Conventions
+
+- Async functions: use `async/await`, avoid raw `.then()`
+- Error handling: use try-catch at call sites; log errors via `log.error()`
+- Logging: use the `log` helper (`log.info`, `log.error`, `log.debug`) — never `console.log`
+- HTTP: use `lib/opencode.js` request helpers instead of raw `http.request`
+- Tmux: use `lib/ocmux.js` helpers instead of raw `spawnSync`
+
+### Architecture Rules
+
+1. **Zero npm dependencies.** The `package.json` `"dependencies"` field must remain empty.
+2. **`bin/`** files are entry points — keep them thin. Business logic goes in `lib/`.
+3. **`bin/tgagentp`** is the largest file (~2000 lines). When adding new features, extract reusable logic into `lib/` when possible.
+4. **Shared state** (e.g., `chatStates`, `serverOwners`) is held in module-level variables in `bin/tgagentp` and `lib/ocmux.js`. Be mindful of mutation.
+5. **All external calls must be mockable.** `lib/opencode.js` tests mock `http.request`; `lib/ocmux.js` tests mock `child_process.spawnSync` and `fs.*`.
+
+## Running Tests
+
+Tests use Node.js built-in test runner (`node:test`) — zero additional dependencies.
+
+```bash
+# Run all tests
+npm test
+
+# Run a specific test file
+node --test tests/opencode.test.js
+node --test tests/ocmux.test.js
+
+# Run with verbose output
+node --test tests/opencode.test.js | bunyan  # or just grep for results
+```
+
+All external interfaces are mocked — tests run entirely in-process without touching the network, tmux, or the filesystem. They are safe to run alongside a live OpenCode instance.
+
+### Test Architecture
+
+Tests are structured in phases (see `AGENTS.md` for the full plan):
+
+| Phase | Module | Boundary Mocked |
+|-------|--------|----------------|
+| 1a | `lib/opencode.js` | `http.request` |
+| 1b | `lib/ocmux.js` | `child_process.spawnSync`, `child_process.execSync`, `fs.*` |
+
+Each test file uses `node:test`'s `mock` API in `before()`/`after()` hooks to install and tear down mocks. Tests within a describe block run serially (`concurrency: false`) when they share mocked state.
+
+### Adding Tests
+
+1. Place new tests in `tests/<module>.test.js`
+2. Use `describe`, `it`, `before`, `after` from `node:test`
+3. Use `node:assert` for assertions
+4. Mock all external boundaries (network, filesystem, subprocesses)
+5. Run the full suite before submitting a PR
+
+## Pull Request Process
+
+1. **Fork the repo** and create a feature branch from `main`.
+2. **Make your changes** following the coding standards above.
+3. **Run `npm test`** and ensure all tests pass.
+4. **Update documentation** if your change affects user-facing behavior:
+   - Help text in `bin/tgagentp` (the `cmdHelp` function)
+   - `docs/specification.md` for architecture changes
+   - Command table in `devto-article.md` (if adding/changing a slash command)
+   - `AGENTS.md` Done section (move items in/out as appropriate)
+5. **Commit with a descriptive message** following the existing style (e.g., `fix: ...`, `feat: ...`, `refactor: ...`, `docs: ...`).
+6. **Open a pull request** against `main`. Include a summary of the change and any testing instructions.
+
+### Review Process
+
+- Maintainers review within a few business days
+- Focus areas: mock correctness, zero-dependency rule, architectural consistency
+- Large changes may be asked to split into smaller PRs
+- All PRs must pass the test suite before merging
+
+## Getting Help
+
+- Open an issue on GitHub for bugs or feature requests
+- Tag questions with `question` label for general help
+- For OpenCode-specific questions, refer to [opencode.ai](https://opencode.ai)

package/README.md

@@ -55,10 +55,13 @@ Options:
 - `--qa`: print the original prompt and answer with labels (useful when used as a filter)
 - `--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
+- `--getLast <n>`: retrieve last n assistant answers from session history
 - `--version`: show version
 - `--help`: show help message
 
-By default, `--qa` implies `--tg`; standalone mode implies `--no-tg`.
+By default, `--qa` auto-detects tgagentp (silently degrades if unavailable); standalone mode implies `--no-tg`.
+With `--tg`, errors if tgagentp is unavailable.
 
 Arguments:
 
@@ -124,6 +127,25 @@ From Vim/Neovim, forward the answer to your Telegram:
 (Works as long as `tgagentp` is running. The answer appears both in the editor
 and in your Telegram chat.)
 
+From Vim/Neovim, flush the recorded buffer without prepending context:
+
+```vim
+:'<,'>!agentp --qa --flush
+```
+
+Useful when you've finished a conversation thread and want to reset the recorded
+context for a new topic.
+
+Retrieve the last 3 assistant answers from session history:
+
+```bash
+agentp --getLast 3
+```
+
+Useful to grab recent answers without sending a new prompt.
+
+## ocmux
+
 ## ocmux
 
 Manage OpenCode server + TUI in tmux for project directories.
@@ -141,6 +163,7 @@ Subcommands:
   - `--GIT` resolves `dir` to the nearest parent with a `.git` directory only; errors if none is found.
   - `--print-logs` passes `--print-logs` to `opencode serve`, which prints server logs to stderr in the server tmux pane.
 - **`kill [dir]`** — Kill the server found upward from `dir`. Removes its tmux window and state file.
+- **`resurrect [--print-logs] [dir]`** — Recover a dead/crashed server: reads `.ocmux.json`, kills old tmux window, removes state file, then creates a fresh server + TUI in the same directory. Works even if no tmux window exists (stale state file).
 - **`list`** — List all running servers with their directories, URLs, and status.
 
 Options:
@@ -174,6 +197,10 @@ Notes:
 5. With `--tg` (or by default when `--qa` is given), forwards the answer to Telegram
    via the agentp gateway. The answer appears in your Telegram chat as if tgagentp
    itself had processed the request.
+6. If tgagentp's [/record](#tgagentp) feature was active, the gateway response includes
+   the recorded conversation buffer. In `--qa` mode, agentp prepends this buffer (with
+   rulers) to its stdout so OpenCode receives the full Telegram context. Use `--flush`
+   to clear the buffer without prepending.
 
 The session API ensures the request is processed even when no TUI is attached, and returns the full answer in a single HTTP response.
 
@@ -201,7 +228,7 @@ Non-text Telegram updates (photos, stickers, etc.) are silently ignored.
 
 | Command | Action |
 |---|---|
-| `/help [topic]` | Show general help or help for a topic (`servers`, `sessions`, `agents`, `models`, `allow`, `think`) |
+| `/help [topic]` | Show general help or help for a topic (`servers`, `sessions`, `agents`, `models`, `allow`, `think`, `record`, `queue`) |
 | `/servers` | List all running ocmux-served projects with URL + status (✅ idle / ⏳ busy) |
 | `/servers switch <name>` | Switch active server; matches by full path, basename, or substring |
 | `/sessions` | List recent sessions for the current server (max 50, with date headings) |
@@ -212,10 +239,28 @@ Non-text Telegram updates (photos, stickers, etc.) are silently ignored.
 | `/status` | Show current server path, URL, busy status, and active session |
 | `/cancel` | Cancel the current AI response for the active server |
 | `/think [on\|off\|switch]` | Toggle forwarding of model thinking messages to the chat |
+| `/record [stop]` | Toggle recording of Telegram conversation for agentp context; `/record stop` clears and stops |
+| `/servers switch <name> [--force]` | Switch to a server; `--force` takes over from another chat |
+| `/sessions` | List recent sessions for the current server (max 50, with date headings) |
+| `/sessions switch <number\|name>` | Switch active session by position or partial name match |
+| `/agents` | List primary agents (▶ marker for the active one) |
+| `/agents switch <name>` | Switch active agent — persists on session and refreshes TUI |
+| `/models` | List connected providers with model counts, context limits, and costs |
+| `/status` | Show current server path, URL, busy status, and active session |
+| `/cancel` | Cancel the current AI response for the active server |
+| `/think [on\|off\|switch]` | Toggle forwarding of model thinking messages to the chat |
+| `/record [stop]` | Toggle recording of Telegram conversation for agentp context; `/record stop` clears and stops |
+| `/queue <message>` | Queue a message when the server is busy; auto-sent when current task finishes |
+| `/flush` | Clear all queued messages (manual and auto-queued) |
+| `/resurrect` | Recover a dead server — restart processes in the same directory, reconnect chat |
 | `/allow` | Approve a permission request once |
 | `/reject` | Deny a permission request |
 | `/always` | Approve and remember for the session |
-| `/shutdown [force]` | (requires `--dev`) Stop tgagentp; refuses if busy unless `force` is given |
+| `/shutdown [force\|clear]` | (requires `--dev`) Stop tgagentp; `clear` also wipes saved connections |
+
+### 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`).
 
 ### Per-server state
 
@@ -246,9 +291,10 @@ tgagentp starts a tiny HTTP server on `127.0.0.1` that accepts `POST /send` requ
 - Port is randomly assigned by default; overridable via `TGAGENTP_PORT`.
 - Port is written to `/tmp/tgagentp-port` for agentp discovery.
 - Authentication reuses `OPENCODE_SERVER_PASSWORD`.
-- Messages for the active server are delivered immediately.
-- Messages for non-active servers are queued and delivered on `/servers switch`.
-- Debounced Telegram notification on queue (configurable via `TGAGENTP_DEBOUNCE_MS`).
+- 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`.
+- 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.
 
 ### Logging
 
@@ -267,9 +313,9 @@ To capture everything (info + errors) to a log file:
 tgagentp 2>/var/log/tgagentp.log
 ```
 
-### Telemetry
+### State persistence
 
-A startup greeting is sent to the last known chat on boot — includes /status-style server info. The chat ID is persisted at `/tmp/tgagentp-startup-chat`.
+Chat-to-server directory mappings are saved to `/tmp/tgagentp-connections.json` on every connection. On restart, tgagentp reads this file, discovers the server URL from each directory's `.ocmux.json`, and reconnects automatically with a welcome message. Use `/shutdown clear` (requires `--dev`) to wipe the saved state for a clean start.
 
 ### Environment variables
 

package/bin/agentp

@@ -3,11 +3,13 @@
 const http = require('http');
 const fs = require('fs');
 const readline = require('readline');
+const child_process = require('child_process');
 const { version } = require('../package.json');
 const {
   sendToSession,
   listSessions,
   createSession,
+  getSession,
 } = require('../lib/opencode');
 
 const TGAGENTP_PORT_FILE = '/tmp/tgagentp-port';
@@ -35,8 +37,16 @@ function notifyAgentpGateway(port, server, text) {
       let data = '';
       res.on('data', (chunk) => { data += chunk; });
       res.on('end', () => {
-        if (res.statusCode === 200) resolve();
-        else reject(new Error(`status ${res.statusCode}: ${data}`));
+        if (res.statusCode === 200) {
+          try {
+            const result = JSON.parse(data);
+            resolve(result.buffered || []);
+          } catch {
+            resolve([]);
+          }
+        } else {
+          reject(new Error(`status ${res.statusCode}: ${data}`));
+        }
       });
     });
     req.setTimeout(5000, () => {
@@ -66,6 +76,7 @@ const FINAL_ROW = '    —————————————————\n';
 async function main() {
   let serverBase = 'http://localhost:4096';
   let qaMode = false;
+  let flushMode = false;
   // tgMode: false = disabled, 'auto' = auto-detect, true = explicit --tg
   let tgMode = null;
 
@@ -80,29 +91,138 @@ async function main() {
       console.error('Pipe prompt text to an OpenCode session and get the assistant response on stdout.');
       console.error('');
       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('  --tg       Forward the answer to Telegram via agentp gateway (error if unavailable)');
-      console.error('  --no-tg    Do not forward to Telegram');
-      console.error('  --help     Show this help message');
+      console.error('  --version   Show version');
+      console.error('  --qa        Print the original prompt and answer with labels (useful as a filter)');
+      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');
+      console.error('  --getLast   Retrieve last N assistant answers (or QA pairs with --qa) from session history');
+      console.error('  --help      Show this help message');
       console.error('');
       console.error('By default, --qa auto-detects tgagentp; standalone mode implies --no-tg.');
       console.error('--tg: error if tgagentp is unavailable; auto mode: silently degrade.');
       console.error('');
+      console.error('When --qa is combined with --getLast, the output includes full QA pairs');
+      console.error('(user prompt + assistant answer) with rulers, matching the recorded');
+      console.error('context replay format. Without --qa, only the assistant answers are shown.');
+      console.error('');
+      console.error('--flush clears the tgagentp recorded buffer and also prevents the prepended');
+      console.error('context from appearing in --qa output. Use it when you want fresh context.');
+      console.error('');
       console.error('Arguments:');
       console.error('  url        OpenCode server URL or port number (default: 4096)');
       console.error('             Examples: 4096, http://localhost:4096, http://192.168.1.50:4096');
+      console.error('             Use `ocmux` (with no args) to get the URL of the current project\'s server.');
       console.error('');
       console.error('See also: tgagentp -- Telegram bridge (tgagentp --help), ocmux -- manage OpenCode tmux sessions (ocmux --help)');
       console.error('');
       console.error('Examples:');
       console.error('  printf "Summarize this file" | agentp');
-      console.error('  cat prompt.txt | agentp 4096');
+      console.error('  cat prompt.txt | agentp $(ocmux)            # talk to current project\'s server');
       console.error('  # Vim/Neovim filter, preserving prompt + answer:');
-      console.error("  :'<,'>!agentp --qa");
+      console.error("  :'<,'>!agentp --qa $(ocmux)");
+      console.error('  # Retrieve last 3 assistant answers:');
+      console.error('  agentp --getLast 3');
+      console.error('  agentp --getLast 3 --qa                     # full QA pairs with rulers');
+      console.error('  agentp --getLast 1 4096');
       process.exit(0);
     } else if (args[i] === '--qa') {
       qaMode = true;
+    } else if (args[i] === '--flush') {
+      flushMode = true;
+    } else if (args[i] === '--getLast') {
+      i++;
+      const nStr = args[i];
+      if (!nStr || !/^\d+$/.test(nStr)) {
+        console.error('Error: --getLast requires a number (e.g. --getLast 5)');
+        process.exit(1);
+      }
+      const n = parseInt(nStr, 10);
+      try {
+        const sessions = await listSessions(serverBase);
+        if (!sessions || sessions.length === 0) {
+          console.error('No sessions found.');
+          process.exit(1);
+        }
+        const sorted = sessions
+          .filter(s => s.time && s.time.updated)
+          .sort((a, b) => b.time.updated - a.time.updated);
+        const sessionId = sorted[0].id;
+
+        function buildPairsFromMessages(messages) {
+          const pairs = [];
+          let cur = null;
+          for (const raw of messages) {
+            // Normalize: export gives {role, parts: [{type, text}]}, SQLite gives {role, text}
+            const m = raw.parts ? raw : { role: raw.role, parts: [{ type: 'text', text: raw.text }] };
+            const role = m.role;
+            const text = (m.parts || []).filter(p => p.type === 'text').map(p => p.text).join('').trim();
+            if (!text) continue;
+            if (role === 'user') {
+              if (cur) pairs.push(cur);
+              cur = { prompt: text, answer: '' };
+            } else if (role === 'assistant' && cur) {
+              if (cur.answer) cur.answer += '\n';
+              cur.answer += text;
+            }
+          }
+          // Don't push incomplete pair (no answer yet)
+          return pairs;
+        }
+
+        function formatPairs(pairs) {
+          return pairs.map(p =>
+            HUMAN_ROW + p.prompt + '\n' + AGENT_ROW + p.answer + '\n' + FINAL_ROW
+          ).join('\n');
+        }
+
+        const formatAsQa = qaMode || args.includes('--qa');
+        function extractAnswers(pairs) {
+          return pairs.map(p => p.answer);
+        }
+        let output = '';
+        try {
+          const raw = child_process.execFileSync('opencode', ['export', sessionId], { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 });
+          const jsonStart = raw.indexOf('{');
+          const body = jsonStart >= 0 ? raw.slice(jsonStart) : raw;
+          const exportData = JSON.parse(body);
+          const messages = exportData.messages || [];
+          const pairs = buildPairsFromMessages(messages);
+          const lastN = pairs.slice(-n);
+          output = formatAsQa ? formatPairs(lastN) : extractAnswers(lastN).join('\n');
+        } catch {
+          // export JSON is malformed (opencode bug);
+          // fall back to SQLite
+          const home = process.env.HOME || process.env.USERPROFILE || '';
+          const dbCandidates = [
+            `${home}/.local/share/opencode/opencode.db`,
+            `${home}/Library/Application Support/opencode/opencode.db`,
+            `${home}/.opencode/opencode.db`,
+          ];
+          let dbPath = null;
+          for (const p of dbCandidates) {
+            try { fs.accessSync(p); dbPath = p; break; } catch {}
+          }
+          if (dbPath) {
+            const sql = `SELECT m.data->>'role' as role, group_concat(p.data->>'text', '') as text FROM message m JOIN part p ON p.message_id = m.id WHERE m.session_id = '${sessionId.replace(/'/g, "''")}' AND p.data->>'type' = 'text' AND m.data->>'role' IN ('user','assistant') GROUP BY m.id ORDER BY m.time_created ASC`;
+            const out = child_process.execFileSync('sqlite3', ['-json', dbPath, sql], { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 });
+            const messages = JSON.parse(out);
+            const pairs = buildPairsFromMessages(messages);
+            const lastN = pairs.slice(-n);
+            output = formatAsQa ? formatPairs(lastN) : extractAnswers(lastN).join('\n');
+          }
+        }
+        if (!output) {
+          console.error(formatAsQa ? 'No complete prompt-answer pairs found in session history.' : 'No assistant answers found in session history.');
+          process.exit(1);
+        }
+        process.stdout.write(output);
+        if (!output.endsWith('\n')) process.stdout.write('\n');
+      } catch (err) {
+        console.error('Error retrieving session history:', err.message);
+        process.exit(1);
+      }
+      return;
     } else if (args[i] === '--tg') {
       tgMode = true;
     } else if (args[i] === '--no-tg') {
@@ -111,6 +231,14 @@ async function main() {
       serverBase = args[i].replace(/\/+$/, '');
     } else if (/^\d+$/.test(args[i])) {
       serverBase = 'http://localhost:' + args[i];
+    } else if (args[i].startsWith('--')) {
+      console.error(`Error: unknown option '${args[i]}'`);
+      console.error(`Usage: agentp [options] [url]`);
+      console.error(`Try 'agentp --help' for more information.`);
+      process.exit(1);
+    } else {
+      console.error(`Error: unexpected argument '${args[i]}'`);
+      process.exit(1);
     }
   }
 
@@ -172,28 +300,39 @@ async function main() {
     process.exit(1);
   }
 
-  // Build full --qa output and send to stdout
-  let tgText = answer;
+  // Build the message to send to Telegram (QA pair with rulers)
+  let tgMessage = answer;
   if (qaMode) {
-    tgText = HUMAN_ROW + promptText + AGENT_ROW + answer;
-    if (!answer.endsWith('\n')) tgText += '\n';
-    tgText += FINAL_ROW;
-    process.stdout.write(tgText);
-  } else {
-    process.stdout.write(answer);
-    if (!answer.endsWith('\n')) process.stdout.write('\n');
+    tgMessage = HUMAN_ROW + promptText + AGENT_ROW + answer;
+    if (!answer.endsWith('\n')) tgMessage += '\n';
+    tgMessage += FINAL_ROW;
   }
 
-  // Post-send: notify tgagentp if we have a port
+  // Post-send: notify tgagentp, get recorded context back
+  let buffered = [];
   let tgError = null;
   if (tgPort) {
     try {
-      await notifyAgentpGateway(tgPort, serverBase, tgText);
+      buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
     } 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');
+      }
+    }
+    process.stdout.write(tgMessage);
+  } else {
+    process.stdout.write(tgMessage);
+    if (!tgMessage.endsWith('\n')) process.stdout.write('\n');
+  }
+
   // Warnings at the end (stderr)
   if (tgError && tgMode === true) {
     process.stderr.write('\n');