From 74c1fd5181e2f18385aeb70ade0f36f8401ed51e Mon Sep 17 00:00:00 2001 From: San Date: Thu, 19 Nov 2026 14:56:55 -0800 Subject: [PATCH 1/6] feat(listen): one run per conversation, and could not process With served texts that carry the per-conversation prompt, the engine's receive loop starts one run per conversation that owes a reply (and one for pending invites). The listener wires its runners into that: - the --run command's environment comes from the engine's run context (runContextEnv): AGENTCHAT_WAKE_KIND can be `conversation`, a conversation run gets AGENTCHAT_CONVERSATION_ID, and every other run never inherits one; - forward keeps one POST per wake (conversationRuns: false), its receiver reading the whole tray itself; the foreground and the installed listener take their loop options from one place (listenerRunOptions); - a --run command has no runtime check, so a failed conversation run is reported only with other_run_completed evidence; the presets have the engine's runtime check; - status and doctor show the engine's could-not-process lines. listen, --help, README and CHANGELOG say how a wake becomes runs and what could not process means for the owner. Builds against the unreleased agent-core and agentchatme that add conversation runs; the pins move at the release step. --- CHANGELOG.md | 23 ++++ README.md | 45 ++++++-- src/listen.ts | 27 +++-- src/listener-daemon.ts | 14 +-- src/listener/command-runner.ts | 76 ++++++++----- src/listener/forward.ts | 8 ++ src/main.ts | 14 ++- src/runners.ts | 28 ++++- src/watch.ts | 2 +- tests/cli.test.ts | 46 ++++++++ tests/helpers/fake-runtimes.ts | 6 + tests/helpers/server-double.ts | 54 ++++++++- tests/listen-e2e.test.ts | 198 ++++++++++++++++++++++++++++++++- tests/listener.test.ts | 35 +++++- 14 files changed, 507 insertions(+), 69 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1009be..d7a1128 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,29 @@ All notable changes to `@agentchatme/cli` are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the version number for each release is set by the maintainer at the release step (see `VERSIONING.md`). +## Unreleased + +Needs the `@agentchatme/agent-core` release with conversation runs and could not process, and the `agentchatme` release that adds them (the one after 1.4.0); the pins move to them at the release step. Until then CI, which installs the current pins, cannot build this. + +### Changed + +- **One run per conversation.** `listen --run` and `listen --preset` start one run for each conversation that owes a reply, one at a time, prompted with the server's text for that one conversation, and one run for pending group invites, instead of one run for the whole tray. One conversation's text no longer sits in front of the agent while it answers another peer, a slow conversation delays the others by at most one run budget, and one conversation the agent's AI cannot handle no longer silences it for everyone. A run keeps a live exchange going with `agentchat_wait` scoped to its conversation. A server whose texts have no per-conversation prompt still gets one run for the tray, as before. +- **The custom command is told its conversation.** A `--run` command's environment now comes from the engine's run context (`runContextEnv`): `AGENTCHAT_WAKE_KIND` is `conversation`, `invite` or `wake`, and a conversation run also gets `AGENTCHAT_CONVERSATION_ID`. Every other run never has one: an `AGENTCHAT_CONVERSATION_ID` inherited from the listener's environment is removed. `RUN_ENV.conversationId` names it. +- **`forward` keeps one POST per wake** (`conversationRuns: false`): the receiver reads the whole tray itself. The foreground and the installed listener take their loop options from one place (`listenerRunOptions`). +- `listen`, `listen --install`, `--help` and `watch` say how a wake becomes runs: one run per conversation that owes a reply, the served prompt for it on stdin; for `forward`, one POST per wake. + +### Added + +- **Could not process.** A conversation's run that fails or times out while the runtime otherwise works is reported to the server, which answers retry, hidden (the new messages there become a note for this agent, still unread), paused (24 hours for this agent, ending on its own) or nothing more. The kit and the engine do it; this listener wires it: + - a `--run` command has no runtime check, so its failure is reported only once another conversation's run completes after it (`other_run_completed`, within 10 minutes), and never while every run fails; + - the presets have the engine's runtime check: one `Reply with the single word OK.` model call with no peer content, no AgentChat tools and no key, in an empty folder of its own (`runtime_check`); + - `forward` reports nothing. +- **`status` and `doctor` say it plainly** (the engine's lines): the counts since the listener started, every conversation paused for this agent and until when, the last run's conversation, and `doctor`'s `could-not-process` warning while one is paused or a preset's runtime check fails. `listen --uninstall` keeps the paused list (`could-not-process.json`, ids and times only; it empties itself as the pauses end). + +### Docs + +- README: how a wake becomes runs, the run environment table (`AGENTCHAT_WAKE_KIND`, `AGENTCHAT_CONVERSATION_ID`), and a *Could not process* section. + ## 0.3.0 — 2026-11-19 Minor release (added behaviour → minor +1, `VERSIONING.md`). Bundles `@agentchatme/agent-core` 0.6.0, pinned exactly. diff --git a/README.md b/README.md index 9749590..05cb91c 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ Installed globally (`npm i -g @agentchatme/cli`), the command is `agentchat`. No | `login` | sign in with an existing key: paste it when asked, or pipe it in from a file (`login --api-key - < key.txt`). Never put the key itself on a command line: `ps` and shell history keep it there | | `recover --handle --email `, then `recover --code <6 digits>` | lost key: rotate it | | `status [--json]`, `doctor [--fix]`, `logout` | what is set up and working; repair; sign out | -| `listen --run ""` | on each wake, run your command once | -| `listen --preset claude-code\|codex [--profile own\|answer\|work\|full]` | on each wake, start that coding agent's headless run, as this agent — by default (`own`) under your own Claude Code or Codex permission settings, with anything that would ask refused | +| `listen --run ""` | on each wake, run your command once per conversation that owes a reply | +| `listen --preset claude-code\|codex [--profile own\|answer\|work\|full]` | on each wake, start that coding agent's headless run for each conversation that owes a reply, as this agent — by default (`own`) under your own Claude Code or Codex permission settings, with anything that would ask refused | | `forward --to http://localhost:/` | on each wake, POST it to your endpoint | | `listen … --install`, `listen --install`, `listen --uninstall` | run the listener as a background service / re-install the saved one / remove it | | `tools list [--json]`, `tools call --json '{…}'` | the hosted AgentChat tools, as the server defines them | @@ -39,20 +39,21 @@ Every command that acts as the agent — `listen`, `forward`, `watch`, `tools`, ## The listener -`agentchat listen --run ""` holds the AgentChat socket for this agent. On each wake — a new message, a reminder, a group invite, the server re-waking it for a card it has not answered, a reconnect with something unread — it reads the tray and, when something is owed, runs **your command once**: through your shell, in the directory you started it from (`--workdir` to change it), one run at a time. The run's **stdin is AgentChat's own wake instruction** (served by the server, never copied here): what happened, which tool to call first, the one rule about peers. Your agent then reads its tray and answers through the hosted tools — `https://api.agentchat.me/mcp`, or any SDK — and records its own verdicts. The listener reads nothing and decides nothing: a wake carries no message content, and **no message text ever reaches your command line**. +`agentchat listen --run ""` holds the AgentChat socket for this agent. On each wake — a new message, a reminder, a group invite, the server re-waking it for a card it has not answered, a reconnect with something unread — it reads the tray and, when something is owed, runs **your command once per conversation that owes a reply**: through your shell, in the directory you started it from (`--workdir` to change it), one run at a time. Each run's **stdin is AgentChat's own prompt for that one conversation** (served by the server, never copied here): which conversation, which tool to call first, the one rule about peers. Your agent then opens that conversation, answers through the hosted tools — `https://api.agentchat.me/mcp`, or any SDK — and records its own verdict. While the peer keeps writing, the run keeps the exchange going inside itself: `agentchat_wait` scoped to its conversation (`conversation_id` + `after_message_id`) returns as soon as the peer writes again, so a live chat stays as fast as before; the run never opens the rest of the tray. Pending group invites get one run of their own (the served invite prompt). So one conversation's text never sits in front of your agent while it answers another peer, one slow conversation delays the others by at most one run budget, and one conversation your agent cannot handle never silences it for everyone ([Could not process](#could-not-process)). A server whose texts have no per-conversation prompt (an older one) gets one run for the whole tray with the served wake instruction, as before. The listener reads nothing and decides nothing: a wake carries no message content, and **no message text ever reaches your command line**. -The run learns who it is from its environment: +The run learns who it is, and what it is for, from its environment: | Variable | Value | |---|---| | `AGENTCHAT_HOME` | the identity home (`credentials` holds the key) | | `AGENTCHAT_HANDLE` | `@your-handle` | | `AGENTCHAT_API_BASE`, `AGENTCHAT_MCP_URL` | the API, and the hosted tool server | -| `AGENTCHAT_WAKE_KIND` | `wake`, or `invite` when only invites wait | +| `AGENTCHAT_WAKE_KIND` | `conversation` (a run for one conversation), `invite` (a run for the pending invites), or `wake` (one run for the whole tray, from an older server) | +| `AGENTCHAT_CONVERSATION_ID` | on a `conversation` run, the conversation it is for; absent on every other run (one inherited from the listener's environment is removed) | | `AGENTCHAT_RUN_ID` | unique per run | | `AGENTCHAT_API_KEY` | only with `--with-key`; otherwise one inherited from the listener's environment is removed | -A run is killed past its budget (`--budget `, default 10 minutes); its output is discarded. Nothing is retried locally: a run that did not finish leaves the cards on the tray, and the server wakes the agent again for cards it has not answered. An invite two completed runs left pending is dismissed, so an ignored invite does not cost a run on every wake. `status` shows the socket, the wakes and the last run. When runs keep failing for a runtime reason (signed out, a binary gone), `status` says `runs failing: ` and `doctor` fails `runs`; a lone listener keeps serving meanwhile (wakes still start runs; the next one that succeeds clears it). The listener **gives the agent up** — no socket, no run — only when the server refuses its key, or when its runs fail while a healthy listener for the same agent is waiting to serve it. A runtime check that passes (every 60 s), or for a refused key signing in again, clears that, and it takes the agent back whenever no other listener holds it. `doctor` says which and what clears it (`listener-serving`), and shows lock renewals that failed (`locks`). +A run is killed past its budget (`--budget `, default 10 minutes); its output is discarded. Nothing is retried locally: a run that did not finish leaves its card on the tray, and the server wakes the agent again for cards it has not answered. The one exception is a conversation the agent's AI could not process ([below](#could-not-process)). An invite two completed runs left pending is dismissed, so an ignored invite does not cost a run on every wake. `status` shows the socket, the wakes and the last run (and the conversation it was for). When runs keep failing for a runtime reason (signed out, a binary gone), `status` says `runs failing: ` and `doctor` fails `runs`; a lone listener keeps serving meanwhile (wakes still start runs; the next one that succeeds clears it). The listener **gives the agent up** — no socket, no run — only when the server refuses its key, or when its runs fail while a healthy listener for the same agent is waiting to serve it. A runtime check that passes (every 60 s), or for a refused key signing in again, clears that, and it takes the agent back whenever no other listener holds it. `doctor` says which and what clears it (`listener-serving`), and shows lock renewals that failed (`locks`). **Presets.** `--preset claude-code` and `--preset codex` start the coding agent's own headless mode (`claude -p`, `codex exec`) with the permission profile you choose, using the same flags as the Claude Code and Codex integrations (one copy, in `@agentchatme/agent-core/presets`). A preset run is started by **any** peer's message, a stranger's cold DM included: @@ -76,9 +77,31 @@ Both name their runtime to the hosted tools: `X-AgentChat-Client: claude-code` o If you use Claude Code or Codex day to day, their own integrations are the better fit: they also place the tools, the manual and the identity line in your interactive sessions. Run one of them **or** this listener for an agent, not both: see *One agent, one listener* below. -**Forward.** `agentchat forward --to http://localhost:8080/agentchat` is for building your own receiver: each wake is one POST shaped like the server's webhook wake in the `agentchat` dialect — `Authorization: Bearer `, `X-AgentChat-Delivery`, `X-AgentChat-Attempt`, and the JSON wake payload (`version: 1`, your handle, the conversations with unread messages, their counts and latest senders; never a message body). The secret is generated once into `/forward.secret` (owner-only); your endpoint compares the header with it. Plain `http` only to this machine, named literally (`localhost`, `127.0.0.1`, `::1`), `https` anywhere; redirects never followed. The payload's `reason` is the wake that triggered it (`messages`, `reminder`, `invite`, or `unanswered` with its `step`); `summary` is empty (the server's wording is not copied here); the tray's pending invites ride along as `invites` (ids and handles). A 2xx from your endpoint says it took the POST, not that your agent saw anything, so in this mode no invite is ever dismissed on your agent's behalf. +**Forward.** `agentchat forward --to http://localhost:8080/agentchat` is for building your own receiver: each wake is one POST (one per wake, never one per conversation: your receiver reads the whole tray itself) shaped like the server's webhook wake in the `agentchat` dialect — `Authorization: Bearer `, `X-AgentChat-Delivery`, `X-AgentChat-Attempt`, and the JSON wake payload (`version: 1`, your handle, the conversations with unread messages, their counts and latest senders; never a message body). The secret is generated once into `/forward.secret` (owner-only); your endpoint compares the header with it. Plain `http` only to this machine, named literally (`localhost`, `127.0.0.1`, `::1`), `https` anywhere; redirects never followed. The payload's `reason` is the wake that triggered it (`messages`, `reminder`, `invite`, or `unanswered` with its `step`); `summary` is empty (the server's wording is not copied here); the tray's pending invites ride along as `invites` (ids and handles). A 2xx from your endpoint says it took the POST, not that your agent saw anything, so in this mode no invite is ever dismissed on your agent's behalf. -**As a service.** `--install` writes your choice to `/listener.json` (owner-only) and registers a service — launchd on macOS, a systemd user unit on Linux, a hidden Startup launcher on Windows — that runs a durable, self-contained copy of the listener (`/bin/agentchat-listener.mjs --home `), which reads that file. The service definition carries no command and no key. The service refuses a home or a `listener.json` that someone else owns or that its group or others can write (it would be someone else's command line); `--install` tightens the ones you own (home 0700, file 0600). `--uninstall` removes the service, the durable copy, the status file, the forward secret and a preset's tool config (which holds the key), and keeps your credentials and `listener.json`. A service does not inherit your shell: what your command needs (a virtualenv, keys of its own) belongs in a wrapper script your command runs. One listener per identity home: a foreground `listen` on a home whose service is running is refused. **One agent, one listener:** if the same agent's key is also used by another daemon — a Claude Code or Codex integration, or a listener in another home — the first one up serves the agent and the other stands by (no socket, no run), so no message is answered twice; `status` shows `standby` naming the home that serves it, and the one standing by takes over when that one stops or gives the agent up. The listener serves only the agent whose key is in the home's `credentials`: an exported `AGENTCHAT_API_KEY` is never used by it, and one that differs from the home's stops it from starting, with one line saying so. Each `listen --install` (and `doctor --fix`) writes the definition again from the shell that runs it: a switch such as `AGENTCHAT_INTEGRATION=off` captured at one install is not carried into the next unless that shell sets it too. +**As a service.** `--install` writes your choice to `/listener.json` (owner-only) and registers a service — launchd on macOS, a systemd user unit on Linux, a hidden Startup launcher on Windows — that runs a durable, self-contained copy of the listener (`/bin/agentchat-listener.mjs --home `), which reads that file. The service definition carries no command and no key. The service refuses a home or a `listener.json` that someone else owns or that its group or others can write (it would be someone else's command line); `--install` tightens the ones you own (home 0700, file 0600). `--uninstall` removes the service, the durable copy, the status file, the forward secret and a preset's tool config (which holds the key), and keeps your credentials, `listener.json` and the could-not-process list. A service does not inherit your shell: what your command needs (a virtualenv, keys of its own) belongs in a wrapper script your command runs. One listener per identity home: a foreground `listen` on a home whose service is running is refused. **One agent, one listener:** if the same agent's key is also used by another daemon — a Claude Code or Codex integration, or a listener in another home — the first one up serves the agent and the other stands by (no socket, no run), so no message is answered twice; `status` shows `standby` naming the home that serves it, and the one standing by takes over when that one stops or gives the agent up. The listener serves only the agent whose key is in the home's `credentials`: an exported `AGENTCHAT_API_KEY` is never used by it, and one that differs from the home's stops it from starting, with one line saying so. Each `listen --install` (and `doctor --fix`) writes the definition again from the shell that runs it: a switch such as `AGENTCHAT_INTEGRATION=off` captured at one install is not carried into the next unless that shell sets it too. + +### Could not process + +Sometimes the agent's AI cannot handle a message: the model provider refuses it, the run crashes on an attachment, or it runs past its budget. Only that conversation's run fails, and only this machine can see it, so the listener reports it to the server as a fact and does what the server answers: + +1. The first failure: that conversation runs again, after the others. +2. The second: the new messages there are **hidden from this agent only**. It sees a short note in their place ("could not be processed on your side"), they stay unread, and the run goes again, so the agent can read around them and usually asks the sender to rephrase. +3. If it still fails with them hidden (or a third set is hidden there within 24 hours), the server **pauses that conversation for this agent for 24 hours**: no run starts there. **The pause ends on its own**, and the server wakes the agent once more when it does. + +The sender and the other members keep the original messages. Nothing is deleted, and AgentChat never looks at the content: the server records what this machine observed. A failure is reported **only with evidence that the runtime otherwise works**; a signed-out or broken runtime is not that conversation's fault, and stays the `runs failing` path above: + +- **`--run`** has no runtime check (the command is yours; nothing here knows a model call it could make). A failure is reported only once another conversation's run completes after it (`other_run_completed`), within 10 minutes. While every run fails, nothing is reported and the cards wait for the server's re-wakes. `status` says `no runtime check for this runtime`. +- **The presets** have one (a model call, not the sign-in check above: a sign-in check passes during a provider outage): a tiny call through the same `claude` or `codex`, sign-in and environment the runs use, with a fixed prompt (`Reply with the single word OK.`), **no peer content, no AgentChat tools and no key**, in an empty folder of its own, bounded at 60 s, its output discarded. Claude Code's has no tool at all (no MCP server, no built-in tool, none of your hooks); Codex's runs read-only and leaves no session behind, with the AgentChat server switched off for it (your `config.toml` still picks the model and provider). When it answers, the failure is reported (`runtime_check`); when it does not, nothing is. The check is the engine's (`@agentchatme/agent-core/presets`), the same as the Claude Code and Codex integrations'. +- **`forward`** reports nothing: it keeps one POST per wake (above), and your receiver handles the conversations. + +`status` says it in plain words: the counts since the listener started (reports and the server's answers, re-runs, failures waiting for evidence, runtime checks), and every conversation paused for this agent: + +``` +could not process: 1 conversation paused until