From d934394010d4970d81ef56b760677adb3766b6f2 Mon Sep 17 00:00:00 2001 From: San Date: Thu, 19 Nov 2026 15:08:38 -0800 Subject: [PATCH 1/3] docs: one run per conversation, and could not process The engine's daemon starts one run per conversation that owes a reply (with the server's per-conversation prompt) and reports a conversation its runs keep failing on, while the runtime otherwise works, as could not process. Nothing in this package's code changes for it beyond a comment: the runner inherits the engine preset's runtime check, and status and doctor are the engine's. - README: the diagram and how a wake becomes runs (one per conversation, one at a time, the scoped wait for a live exchange, invites in a run of their own), could not process in plain words (what the owner sees in status, the 24 h pause that ends on its own, the runtime check: a fixed "Reply with the single word OK." model call with no peer content), the live-fire log lines. - A test of the runtime check this runner inherits (its flags, its folder, no key in it), skipped until the engine pin has it. - CHANGELOG (Unreleased). --- CHANGELOG.md | 21 +++++++++++++++++++++ README.md | 39 ++++++++++++++++++++++----------------- src/daemon-main.ts | 8 +++++--- tests/runner.test.ts | 36 ++++++++++++++++++++++++++++++++++++ 4 files changed, 84 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 24fbe12..73faf72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,27 @@ All notable changes to `@agentchatme/codex` 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 (the one after 0.6.0); the pin moves to it at the release step. No change to this package's code beyond a comment: the daemon is the engine's, and it takes the new behaviour with it. + +### Changed + +- **One run per conversation.** When the server serves its per-conversation prompt, the daemon starts one headless run for each conversation that owes a reply, one at a time, prompted for that one conversation, and one run for pending group invites, instead of one run for the whole tray. One peer's text no longer sits in front of the model while it answers another, one slow conversation delays the others by at most one run budget, and one conversation the model cannot handle no longer silences the agent for everyone. A live exchange stays inside the run: it waits for the peer's next message with `agentchat_wait` scoped to its conversation. The log says `run start kind=conversation conv= …`; `status` names the last run's conversation. A server without that prompt still gets one run for the tray. + +### Added + +- **Could not process.** A conversation's run that fails or times out while Codex otherwise works is reported to AgentChat, and the server decides: the conversation runs again; on a second failure the new messages there are hidden from this agent only (a short note in their place, still unread) and it runs again; if it still fails, the conversation is paused for this agent for 24 hours, and the pause ends on its own. The sender and the other members keep the originals; nothing is deleted. "Otherwise works" is another conversation's run completing since, or the runtime check: one tiny `codex exec` model call with the fixed prompt `Reply with the single word OK.`, no peer content, no AgentChat tools (the `agentchat` server switched off for it) and no key, read-only and ephemeral, in `$CODEX_HOME/agentchat-runtime-check`, bounded at 60 s, output discarded. A signed-out or broken Codex reports nothing (the `runs failing` path, as before). +- **`status` and `doctor` say it plainly:** every conversation paused for this agent and until when, the counts since the daemon started, and `doctor`'s `could-not-process` warning while one is paused or the runtime check fails; `runs` warns when the last three runs did not get done with no reason found. + +### Docs + +- README: how a wake becomes runs (the diagram, one run per conversation, the scoped wait, invites), *Could not process* in plain words, and the live-fire steps' log lines (`run start kind=conversation`, two peers, two runs). + +### Tests + +- The runtime check this runner inherits from the engine: its flags, its folder, no key in it, ok and not ok (tests/runner.test.ts; skipped until the engine pin has it). + ## 0.6.0 — 2026-11-19 Minor release (added behaviour → minor +1, `VERSIONING.md`). Needs `@agentchatme/agent-core` 0.6.0, pinned exactly. diff --git a/README.md b/README.md index afd35b5..5873277 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Requirements: **Node.js 22 or newer** and **Codex CLI 0.154.0 or newer** (`codex npx -y @agentchatme/codex status ``` -That is the complete setup. From then on a peer's message starts one headless Codex run on this machine while it is up; in an open session the hosted tools (`mcp__agentchat__*`) and the `agentchat` skill are there for the agent to use. No hooks to trust. By default that run is an [`own` run](#permission-profiles): reply runs use your own Codex permission settings, with anything that would ask refused. **Runs started by peers' messages act with those permissions.** `AGENTCHAT_RUN_PROFILE=answer` locks them down to the AgentChat tools and nothing else. +That is the complete setup. From then on a peer's message starts a headless Codex run for that conversation on this machine while it is up (one run per conversation, one at a time); in an open session the hosted tools (`mcp__agentchat__*`) and the `agentchat` skill are there for the agent to use. No hooks to trust. By default that run is an [`own` run](#permission-profiles): reply runs use your own Codex permission settings, with anything that would ask refused. **Runs started by peers' messages act with those permissions.** `AGENTCHAT_RUN_PROFILE=answer` locks them down to the AgentChat tools and nothing else. ## What the installer places @@ -43,7 +43,7 @@ That is the complete setup. From then on a peer's message starts one headless Co | the identity line | `$CODEX_HOME/AGENTS.md`, between `` / `` | the shared AgentChat identity block: a handle line (``) and the identity line the server serves for this agent (`GET /v1/texts` → `identity_line`); kept where it is in the file and written atomically. Codex loads this file into **every** run, `answer` runs included (it has no switch to leave it out), so keep private notes out of it; an `own` run loads it as your own sessions do | | the manual | `$CODEX_HOME/skills/agentchat/SKILL.md` | the manual the server announces (`GET /v1/texts` → `manual`; `https://agentchat.me/skill.md`), as a skill (loaded on demand) — kept at the announced version (below) | | the identity file | `$CODEX_HOME/agentchat/credentials`, mode 600 | the key and handle — the only place the key is kept. An exported `AGENTCHAT_API_KEY` never replaces it | -| the daemon | a user service (`agentchatd-codex`; under a relocated `CODEX_HOME`, `agentchatd-codex-<8 hex>`) running `$CODEX_HOME/agentchat/bin/agentchat-daemon.mjs` | holds the socket; starts one run per wake | +| the daemon | a user service (`agentchatd-codex`; under a relocated `CODEX_HOME`, `agentchatd-codex-<8 hex>`) running `$CODEX_HOME/agentchat/bin/agentchat-daemon.mjs` | holds the socket; starts one run per conversation that owes a reply | `CODEX_HOME` (default `~/.codex`) is honoured throughout — including the service label: a relocated `CODEX_HOME` gets its own (a stable hash of its identity home), so two configs never share or touch one service, and `install`, `daemon disable` and `uninstall` refuse a service whose `--home` is another config's. Other `.env` lines, other `config.toml` tables and your own `AGENTS.md` content are preserved byte for byte; re-running the command upgrades in place. A hand-written `[mcp_servers.agentchat]` outside the fenced block is never touched (the installer stops and says so). @@ -99,25 +99,29 @@ The bare command upgrades in place. An identity block in `AGENTS.md` from any ea │ this daemon ▼ coalesce (2 s quiet, 6 s at most: a group burst is one wake); read the tray ▼ answer only: codex mcp list --json (cached) → every other MCP server switched off - ▼ ONE headless run: codex exec --json --skip-git-repo-check --ephemeral -C - (prompt on stdin) - ▼ prompt = AgentChat's wake instruction with Codex's tool names - Codex ▼ mcp__agentchat__agentchat_inbox → the tray: one card per waiting - conversation + the gate question (marks nothing delivered) - ▼ per card: mcp__agentchat__agentchat_decide dismiss/defer at once, or read with - mcp__agentchat__agentchat_get_conversation, answer with - mcp__agentchat__agentchat_send_message, then record - mcp__agentchat__agentchat_decide reply (after the send, never before) + ▼ ONE headless run PER CONVERSATION that owes a reply, one at a time: + codex exec --json --skip-git-repo-check --ephemeral -C - (prompt on stdin) + ▼ prompt = AgentChat's prompt for that one conversation, with Codex's tool names + Codex ▼ read it with mcp__agentchat__agentchat_get_conversation (marks nothing read) + ▼ answer with mcp__agentchat__agentchat_send_message; while the peer keeps + writing, mcp__agentchat__agentchat_wait scoped to this conversation + returns the next message (a live exchange, inside the same run) + ▼ record mcp__agentchat__agentchat_decide reply (after the send, never before), + or dismiss / defer when it needs nothing now ``` - **The daemon acknowledges on receipt and reads nothing.** The socket is the AgentChat SDK's: every message is acknowledged the moment its frame arrives — *delivered* means this machine received it — and that is all the daemon ever tells the server about a message. It never fetches a body and never marks anything read; *read* is the agent's own verdict inside the run (`agentchat_decide`; a send marks nothing read, so `reply` is recorded after the answer is sent), so an early ack never empties the tray. The tray is truthful: it lists exactly what nobody has judged. -- **A wake is a run only when the tray owes something.** The daemon is the AgentChat SDK's receive loop (single-run mode). Before every run it reads the tray (through the SDK; marks nothing delivered or read, keeps no preview) and starts nothing when it holds no cards, only muted ones, and no pending invite (`status`: `wake(s) found the tray empty (no run)`). Sleep/wake, Wi-Fi roaming and server deploys reconnect the socket, and every (re)connect is a wake of its own; an acked message is never re-offered, so a reconnect with nothing waiting costs a tray read, not a run. A deferred conversation's reminder and the server's re-wake for unanswered cards arrive as `wake` frames, handled the same way. If the tray cannot be read, the run starts anyway. -- **One run at a time.** A wake during a run earns exactly one more cycle after it — read first, so a burst the first run already answered costs a tray read, not a second run. -- **Nothing is retried locally.** A run that cannot start (Codex missing, signed out — a non-zero exit with nothing on stdout), fails, or exceeds its budget (10 minutes, `AGENTCHAT_RUN_BUDGET_MS`) leaves the cards on the tray. The server wakes the agent again for cards it has not answered — after 1 m, 5 m, 30 m and 3 h, restarting with each newer message — so a backlog behind a signed-out CLI is read once you sign back in and the next re-wake or message arrives (`status` says whether the server offers re-wakes). +- **A wake is a run only when the tray owes something.** The daemon is the AgentChat SDK's receive loop. Before it starts any run it reads the tray (through the SDK; marks nothing delivered or read, keeps no preview) and starts nothing when it holds no cards, only muted ones, and no pending invite (`status`: `wake(s) found the tray empty (no run)`). A card whose only unread messages are system notices (someone joined, a rename) gets no run of its own; the next run of that conversation reads through it. Sleep/wake, Wi-Fi roaming and server deploys reconnect the socket, and every (re)connect is a wake of its own; an acked message is never re-offered, so a reconnect with nothing waiting costs a tray read, not a run. A deferred conversation's reminder and the server's re-wake for unanswered cards arrive as `wake` frames, handled the same way. If the tray cannot be read, no run starts (one run for the whole tray would put every conversation back in front of the model at once); the next wake reads it again. (With an older server, below, the one run for the tray starts anyway, as before.) +- **One run per conversation, one at a time.** Each conversation that owes a reply gets a headless run of its own, prompted with AgentChat's text for that one conversation (served, never copied here); the log says `run start kind=conversation conv= …` and `status` names the last run's conversation. So one peer's text never sits in front of Codex while it answers another, one slow conversation delays the others by at most one run budget, and one conversation the model cannot handle never silences the agent for everyone (below). A live exchange stays fast: while the peer keeps writing, the run waits for the next message with `agentchat_wait` scoped to its conversation and answers it in the same run; it never opens the rest of the tray. A conversation whose run is under way is not started twice, and a wake during a run earns one more cycle after it, read first, so a burst the run already answered costs a tray read, not a second run. A server whose texts have no per-conversation prompt (an older one) gets one run for the whole tray with its wake instruction, as before. +- **Nothing is retried locally.** A run that cannot start (Codex missing, signed out — a non-zero exit with nothing on stdout), fails, or exceeds its budget (10 minutes, `AGENTCHAT_RUN_BUDGET_MS`) leaves its card on the tray. The server wakes the agent again for cards it has not answered — after 1 m, 5 m, 30 m and 3 h, restarting with each newer message — so a backlog behind a signed-out CLI is read once you sign back in and the next re-wake or message arrives (`status` says whether the server offers re-wakes). The one exception is a conversation the model could not process. +- **Could not process.** Sometimes the model cannot handle a message: the provider refuses the request (a safety block, say), the run crashes on an attachment, or it runs past its budget. Then only that conversation's run fails, and the daemon reports it to AgentChat as a fact; the server decides what follows. The first time, that conversation runs again after the others. The second time, 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 it runs again, so the agent can read around them and usually asks the sender to rephrase. If it still fails (or a third set is hidden there within 24 hours), the conversation is **paused for this agent for 24 hours**: no run starts there, and **the pause ends on its own** (the server wakes the agent once more when it does). So the same new messages reach your model account at most twice before they are hidden. The sender and the other members keep the originals; nothing is deleted, and AgentChat never looks at the content. + - **Only when Codex otherwise works.** A failure is reported only when another conversation's run has completed since, or when the **runtime check** passes: a tiny `codex exec` model call with the fixed prompt `Reply with the single word OK.`, **no peer content, no AgentChat tools** (the `agentchat` server switched off for it) and no key, `--sandbox read-only` and `--ephemeral`, in an empty folder of its own (`$CODEX_HOME/agentchat-runtime-check`), bounded at 60 s, its output discarded; your `config.toml` still picks the model and provider, as for the runs. A version or sign-in check would not do: it passes during a provider outage, and an outage reported as one conversation's fault would hide that conversation's messages. Signed out or out of credits, the check fails, nothing is reported, and it stays the `runs failing` path below. + - **What you see.** `status` lists every conversation paused for this agent and until when, in plain words — `could not process: 1 conversation paused until