mirror of
https://github.com/simplex-chat/simplex-chat.git
synced 2026-11-22 10:07:31 +00:00
mcp: one-line notes of Claude Code's own prompts (#8157)
* plan: mcp-harness-notes * mcp: tests for one-line notes of Claude Code's own prompts * mcp: one-line notes of Claude Code's own prompts in the session group * mcp: classify a repeated typed prompt by its own entry * mcp: document the notes of Claude Code's own prompts * plan: mcp-harness-notes as implemented * mcp: notes of teammate messages and of prompts in long turns * mcp: document teammate notes and the record rules of review round 1 * mcp: teammate note emoji, repeated events and idle notifications * mcp: one-line sender names in notes, and docs that match the code * mcp: docs state which prompts end tool-use cards and add turn records * plan: mcp-harness-notes example lines from Claude Code 2.1.281
This commit is contained in:
1 parent
9d3241b06c
commit
97bbbd9ac4
14 files changed
+1031
-178
No files matched your search
@@ -33,7 +33,7 @@ You need Node.js 22 or later, Claude Code, and the [SimpleX Chat app](https://si
|
||||
|
||||
3. Each Claude Code session gets its own group, such as "1 · my-project". Join it from the invitation in "SimpleX MCP".
|
||||
|
||||
4. Send prompts in the session's group, and Claude answers there. Prompts you type in the terminal appear there too. Before Claude acts in other chats or uses a tool such as Bash, it asks in the group, and one tap approves.
|
||||
4. Send prompts in the session's group, and Claude answers there. Prompts you type in the terminal appear there too, and Claude Code's own prompts, such as a finished background task, appear as one line each. Before Claude acts in other chats or uses a tool such as Bash, it asks in the group, and one tap approves.
|
||||
|
||||
## Safety
|
||||
|
||||
|
||||
@@ -609,9 +609,19 @@ With the channel, a message from a member of a session's group, other than `User
|
||||
- Every message from a member who can send is a prompt, including one that starts with `!`. Only one-line messages that start with `/` are not prompts, see below. Claude Code runs no command from a prompt. Claude gets the text, and runs shell commands only as tool use, such as Bash, under Claude Code's permissions, see [Tool use](#tool-use).
|
||||
- A one-line message that starts with `/` is a command of the group, such as `/approve 5` or `/list`. From an admin or owner, an unknown command gets `Unknown command.` From a moderator, member or author, any such message gets `Only admins and owners of this group can send / commands.`, and it reaches neither the commands nor Claude.
|
||||
- While the service runs and the session's Claude Code doesn't, Claude replies `Session N is not running.` It also replies so when Claude Code ends while a prompt's file arrives. For 30 seconds after the service starts, a prompt waits for its session to attach again, so a prompt sent while the service was stopped still arrives.
|
||||
- Claude posts its final answer of each turn in the group. When the turn's prompt came from the group, the answer replies to it, even when the next prompt arrives while Claude answers.
|
||||
- Claude posts its final answer of each turn in the group. When the turn's prompt came from the group, the answer replies to it, even when the next prompt arrives while Claude answers. Claude Code can add a prompt that arrives during a turn to that turn. Then the answer replies to the turn's prompt, or to the last message from the group added to the turn.
|
||||
- Claude's replies to a prompt, its answer included, are posted without the quote when the prompt was deleted or the quote makes the message too large. An answer is also posted without the quote when the quote leaves no room for its first character.
|
||||
- `User` posts only the prompts a person typed. Claude Code's own prompts, such as notifications of background tasks, are not posted. `User` also skips commands such as `/compact`, empty prompts such as one with images only, and prompts made only of the plugin's `<channel source="plugin:simplex:simplex" ...>` tags. `User`'s posts are never commands of the group, even a part that starts with `/`.
|
||||
- `User` posts only the prompts a person typed, also one typed while Claude works. `User` skips commands such as `/compact`, empty prompts such as one with images only, and prompts made only of the plugin's `<channel source="plugin:simplex:simplex" ...>` tags. `User`'s posts are never commands of the group, even a part that starts with `/`.
|
||||
- Claude posts one line for each of Claude Code's own prompts, without a quote. The line starts with an emoji for the prompt's kind:
|
||||
- a notification of a background task, a subagent, a workflow or a monitor: its summary, such as `✅ Background command "Build" completed (exit code 0)`, and the first line of its event, when it has one, such as `📡 Monitor event: "Builds": serverpg exit 0`. The emoji is ✅ for a task that completed, ❌ for one that failed and ⏹️ for one that was stopped or killed. A notification without a status gets 📡 when it has an event, as a monitor event or the end of an artifact watch, and 🔔 otherwise. A notification in plain text, such as `3 background agents were stopped by the user: ...`, gets 🔔 and its first line;
|
||||
- a message of another Claude session: `✉️ Message from NAME: ` and its first line;
|
||||
- a message of a teammate in an agent team: `✉️ Message from NAME: ` and its summary, or its first line without one. A prompt with several teammate messages gets the line of the first one that is not an idle notification, and a prompt of idle notifications only gets no line;
|
||||
- the report of a subagent: `📋 Report from subagent NAME: ` and its first line;
|
||||
- a scheduled prompt: `⏰ Scheduled prompt: ` and its first line;
|
||||
- an automatic prompt, such as the one after a usage limit resets: `🔄 Automatic prompt: ` and its first line;
|
||||
- another kind: `⚙️ Claude Code: ` and its first line.
|
||||
|
||||
A line over 200 characters is cut there and ends with `…`. Prompts typed in the terminal and channel prompts get no line. When one of Claude Code's own prompts starts a turn, Claude's answer to it is posted without a quote.
|
||||
- A text too long for one message is posted as several messages, each as long as a message can be, measured as for `send`. The first part of an answer carries the quote. A part without a quote holds up to 14,962 Latin, 7,481 Cyrillic or 4,987 CJK characters. A prompt or an answer over 250,000 characters is cut there and ends with `…`.
|
||||
- The `reply` tool sends a file to the group at once, without approval, with its text as the caption, under the file rules of `send`. It returns the file's message as `item`. A caption too long for a message with the file's preview is refused with `text: too long for a message with this TYPE; shorten it.`
|
||||
|
||||
@@ -622,6 +632,7 @@ Owners set the group's preferences in the app, and SimpleX enforces them. Claude
|
||||
- While "Files and media" is off, `reply` returns `Files and media are off in the group of this session; its owners can turn them on in the group's preferences.` The cards of sends and downloads of images and videos are posted as text, without the preview, and the sends and downloads still work. `/forward` gets `Action N: Files and media are off in the group of this session; its owners can turn them on in the group's preferences.`
|
||||
- When another preference refuses one of Claude's posts, Claude posts a text that names it instead:
|
||||
- For an answer with a SimpleX link: `Claude's answer was not posted: SimpleX links are off in the group of this session; its owners can turn them on in the group's preferences.`
|
||||
- For the line of one of Claude Code's own prompts: `A note on Claude Code's prompt was not posted: ...`
|
||||
- For a terminal prompt: `User's prompt was not posted: SimpleX links are not allowed for User in the group of this session; its owners can allow them in the group's preferences.` This also happens while the preference allows SimpleX links only for roles above `User`'s role, which is member unless the owners change it.
|
||||
- For a card that waits for approval, or for `/forward` of a voice message: `Action N: ...`. The action then fails.
|
||||
- `reply` returns the same text without the prefix `Claude's answer was not posted: `.
|
||||
@@ -640,7 +651,7 @@ Claude: I want to use `Bash`: `List files`
|
||||
/approve 5 or /reject 5
|
||||
```
|
||||
|
||||
`/approve 5` allows the tool use, and `/reject 5` denies it. The dialog in the terminal stays open, and the first answer, in the terminal or in the group, applies. A card that is still pending when its turn ends, when the next prompt arrives or when the session ends gets `Ended.` The preview of the tool's input is shortened to fit the card.
|
||||
`/approve 5` allows the tool use, and `/reject 5` denies it. The dialog in the terminal stays open, and the first answer, in the terminal or in the group, applies. A card that is still pending gets `Ended.` when its turn ends, when a prompt starts the next turn, or when the session ends. A prompt that Claude Code adds to the running turn leaves the card pending. The preview of the tool's input is shortened to fit the card.
|
||||
|
||||
### Model and effort
|
||||
|
||||
|
||||
@@ -153,7 +153,7 @@ The MCP server and the SessionStart, UserPromptSubmit, Stop and PostModelSwitch
|
||||
- the hooks;
|
||||
- the plugin files.
|
||||
|
||||
In these tests, the Stop hook reads the model of its answer from the end of a sparse 3 GiB transcript. It finds the model even when the answer's entry is written after the hook started. The UserPromptSubmit hook marks a prompt as typed only when its entry has the origin `human`. Task notifications, messages of other sessions and channel prompts are not marked. A typed prompt is marked also when the transcript is created with its entry 30 reads after the hook started, as after a user's own prompt hook of 3 s. The hooks, the session server and the service are tested with the environments of two `claude -p` runs, recorded with Claude Code 2.1.319 in `test/unit/claude-p-runs.jsonl`. One run has the entrypoint `claude-vscode` of a VS Code session, and the other is a plain `claude -p` run. The session server must answer `server/discover` with `Method not found` and negotiate the revision 2025-11-25. Claude Code 2.1.319 registers no channel for a server in the modern MCP era, 2026-07-28, so this test fails after an SDK upgrade that turns that era on.
|
||||
In these tests, the Stop hook reads the model of its answer from the end of a sparse 3 GiB transcript. It finds the model even when the answer's entry is written after the hook started. The UserPromptSubmit hook marks a prompt as typed only when its record has the origin `human`. Task notifications, messages of other sessions and channel prompts are not marked. A typed prompt is marked also when the transcript is created with its entry 30 reads after the hook started, as after a user's own prompt hook of 3 s. The hook sends the one-line note of each kind of Claude Code's own prompt, a teammate's message included, also when idle notifications precede it in its prompt, and none for a typed or a channel prompt or idle notifications only. A note stays on one line when the sender's name has a line break or a control character. A prompt that reaches a running turn is found by its queued command or its own later entry, and it is marked mid-turn, also when the turn's first entry is out of the tail and only its tool results are in it. Its record is taken by its text, past a meta entry with the same prompt ID; a prompt with the text of the turn's own prompt waits while it is queued. A typed prompt still queued after the reads is typed and mid-turn. The hook sends the note of Claude Code's own prompt also when a later prompt with its text is still queued after the reads, as a repeated monitor event. The hub posts the note as Claude, without a quote. A mid-turn prompt ends no tool-use card and keeps the turn's quote; an owner's prompt added to the turn adds a turn record, and the answer quotes it. The records follow sessions recorded with Claude Code 2.1.322 on 2026-11-12. The hooks, the session server and the service are tested with the environments of two `claude -p` runs, recorded with Claude Code 2.1.319 in `test/unit/claude-p-runs.jsonl`. One run has the entrypoint `claude-vscode` of a VS Code session, and the other is a plain `claude -p` run. The session server must answer `server/discover` with `Method not found` and negotiate the revision 2025-11-25. Claude Code 2.1.319 registers no channel for a server in the modern MCP era, 2026-07-28, so this test fails after an SDK upgrade that turns that era on.
|
||||
- `npm run test:e2e`, file `test/e2e/launch.test.ts`, installs a copy of the package with `npm ci` and packs it, as `build.yml` publishes it. The test checks these facts:
|
||||
- The tarball has no lockfile.
|
||||
- Its top-level entries are the build, `node_modules` and the plugin files.
|
||||
@@ -170,7 +170,7 @@ The MCP server and the SessionStart, UserPromptSubmit, Stop and PostModelSwitch
|
||||
- A `send` with a preset server's SimpleX link under a standing approval reaches the bot and returns `done`. In place of its card, Claude posts `Action 2 was performed; its card was not posted: SimpleX links are off in the group of this session; its owners can turn them on in the group's preferences.`
|
||||
- A bot's welcome message has a preset server's SimpleX link, which has no query. The `connect` card of that bot is not posted, and neither is a `send` card with that link. Claude posts `Action 2: SimpleX links are off in the group of this session; its owners can turn them on in the group's preferences.` and `Action 3: ...` instead. Both calls return `failed` with the text after `Action N: `.
|
||||
- While SimpleX links are on for admins only in a session's group, Claude's answer with a SimpleX link is posted. `User` is a member and can't post the terminal prompt with that link, so Claude posts `User's prompt was not posted: SimpleX links are not allowed for User in the group of this session; its owners can allow them in the group's preferences.`
|
||||
- The hooks post a prompt typed in the terminal as `User` and the answer as Claude. The session's first prompt is posted also when its hook starts before the transcript file is created. A task notification is not posted. The group's short description shows the model of the first answer, read from the transcript. Claude replies `Session 1 is not running.` to an owner's message to a session without Claude Code. The reply has no quote when the message is as long as the member's core sends. With the session attached, the service passes the owner's message to the session's channel stream. `User` does not post it again, raw or in the channel tag, and Claude quotes it in the answer.
|
||||
- The hooks post a prompt typed in the terminal as `User` and the answer as Claude. The session's first prompt is posted also when its hook starts before the transcript file is created. A task notification is not posted by `User`. Claude posts its line, `✅ Background command "Build" completed (exit code 0)`. For a failed task added to the running turn as a queued command, Claude posts `❌ Background command "Lint" failed with exit code 1`. The group's short description shows the model of the first answer, read from the transcript. Claude replies `Session 1 is not running.` to an owner's message to a session without Claude Code. The reply has no quote when the message is as long as the member's core sends. With the session attached, the service passes the owner's message to the session's channel stream. `User` does not post it again, raw or in the channel tag, and Claude quotes it in the answer.
|
||||
- Hooks with a new session ID, from the process of an attached session, post in that session's group. After the owner approves a tool-use card, the service sends `allow` on the session's stream. A contact and a group that accept after `connect` returned `connected: false` are in the session's `list`. Mode `host` applies after the owner approves its card, and no mode is written to session.json. After a service restart, a prompt sent before the session attached again is passed to the session, without `Session 1 is not running.`
|
||||
- A member joins the Main group with an owner's link:
|
||||
- The member sees the Main group's short description and welcome message of trust, and Claude posts the join there.
|
||||
@@ -195,7 +195,7 @@ In a session started as in step 2 above:
|
||||
1. At the session start, Claude Code shows `SimpleX MCP: scan this QR code with the SimpleX app and tap Join to supervise your agents in "SimpleX MCP":`, a QR code and the link. Ask Claude which link was shown at the session start. Claude doesn't know it. If Claude Code refuses `plugin:simplex@inline` with the development flag, checks 3, 5, 6 and 7 wait for the published plugin and `plugin:simplex@simplex-chat`.
|
||||
2. Scan the QR code in the SimpleX app and tap Join. In "SimpleX MCP", tap the invitation to "1 · <folder>" and join it.
|
||||
3. Send `Reply with the word ready.` in "1 · <folder>". The answer comes from Claude, as a reply to your message.
|
||||
4. Type a prompt in the terminal. It appears in the group from `User`, and the answer appears from Claude. Record whether a prompt from the group also appears from `User`, because Claude Code's documentation does not say whether a channel prompt runs the UserPromptSubmit hook. Ask Claude to run `sleep 5` with Bash in the background. When the task ends, its notification does not appear from `User`.
|
||||
4. Type a prompt in the terminal. It appears in the group from `User`, and the answer appears from Claude. Record whether a prompt from the group also appears from `User`, because Claude Code's documentation does not say whether a channel prompt runs the UserPromptSubmit hook. Ask Claude to run `sleep 5` with Bash in the background. When the task ends, its notification does not appear from `User`; Claude posts a line that starts with ✅ instead. Ask Claude to start a background agent that replies with one word, and to schedule a one-time prompt with CronCreate two minutes ahead. Each appears as one line from Claude. While Claude runs a foreground command, type a prompt in the terminal: it appears from `User`.
|
||||
5. Send `Count from 1 to 300, one number per line.` in the group, and at once send `Reply with the word two.` The second prompt waits in Claude Code's queue. Claude quotes the first message in the answer with the numbers, and the second message in the answer `two`. Neither prompt appears from `User`. The hub chooses the quote of each answer by the start times of the Stop and UserPromptSubmit hooks, and this check confirms that.
|
||||
6. Send `//help` in the group. A one-line message that starts with `/` is a command of the group, so Claude replies `Unknown command.`, and the session gets nothing. Send `!git status`. The session gets it as a prompt, and Claude answers it. Claude Code never runs a command from a channel prompt. Claude Code 2.1.319 was checked on 2026-11-08 with a test channel. It ran neither a command nor a shell command from a channel prompt that started with `/` or `!`, and it passed the text to Claude in the `<channel>` tag. After `/model sonnet`, the model was unchanged, and after `!echo`, no file was written. In the code of Claude Code 2.1.322, a channel message is queued as a prompt with `skipSlashCommands` set. Claude may act on such a text with its tools, such as Bash, under the tool-use approval of check 7.
|
||||
7. Send `Run ls with Bash.` in the group. The terminal shows the permission dialog, and Claude posts the card ``I want to use `Bash`: ...`` with `/approve N or /reject N` in the group. Tap `/approve N`, and `ls` runs. Ask again and tap `/reject N`, and Claude reports the refusal. Answer a third request in the terminal. When the turn ends, Claude ends its card with `Ended.`
|
||||
|
||||
@@ -26,7 +26,7 @@ A tool call is held open by the server until the owner decides and, for `connect
|
||||
The server keeps actions and downloads in memory, and they are lost when the process exits. The action counter and the standing approvals are stored as custom data in the chat database. The token, the headers file for the host, the server record and the lock are files in the data folder; downloaded files are in its `files` folder, one folder per chat.
|
||||
|
||||
The package is also a Claude Code plugin. Each Claude Code session runs `simplex-mcp session`, a stdio MCP server. The session server forwards tool calls over a local socket to `simplex-mcp service`, one service per data root. Requests on the socket are HTTP/1.1 with a bearer token. The service runs two cores:
|
||||
- `Claude` is the profile that peers see. It holds the Main group, one group per session and the chats with peers.
|
||||
- `Claude` is the profile that peers see. It holds the Main group, one group per session and the chats with peers. In a session's group it posts the answers and one line for each of Claude Code's own prompts.
|
||||
- `User` is a member of every session group. It posts the prompts typed in the terminal.
|
||||
|
||||
Each session has the six tools and `reply`, and its group has its own `Actions` and `Control`. A chat belongs to the session that connected it. Admins and owners of the session group move a chat to another session with `/give`.
|
||||
@@ -234,11 +234,11 @@ Claude Code uses these files of the plugin, described in [API 4.8](api.md#48-plu
|
||||
| Service start by a client | [`src/client.ts`](../src/client.ts#L35) | `ServiceClient.ensureService` | [35](../src/client.ts#L35) |
|
||||
| Service process | [`src/service.ts`](../src/service.ts#L430) | `runService` | [430](../src/service.ts#L430) |
|
||||
| Service routes | [`src/service.ts`](../src/service.ts#L137) | `Service.routes` | [137](../src/service.ts#L137) |
|
||||
| Hub | [`src/hub.ts`](../src/hub.ts#L367) | `Hub.open` | [367](../src/hub.ts#L367) |
|
||||
| Hub | [`src/hub.ts`](../src/hub.ts#L368) | `Hub.open` | [368](../src/hub.ts#L368) |
|
||||
| Session and its group | [`src/hub.ts`](../src/hub.ts#L43) | `Session` | [43](../src/hub.ts#L43) |
|
||||
| Main group | [`src/main-group.ts`](../src/main-group.ts#L26) | `MainGroup` | [26](../src/main-group.ts#L26) |
|
||||
| Profile `User` | [`src/user.ts`](../src/user.ts#L13) | `User` | [13](../src/user.ts#L13) |
|
||||
| Hooks | [`src/hook.ts`](../src/hook.ts#L58) | `sessionStart`, `turn` | [58](../src/hook.ts#L58), [91](../src/hook.ts#L91) |
|
||||
| Hooks | [`src/hook.ts`](../src/hook.ts#L81) | `sessionStart`, `turn` | [81](../src/hook.ts#L81), [114](../src/hook.ts#L114) |
|
||||
| `link`, `reset-owners` | [`src/owner.ts`](../src/owner.ts#L22) | `showLink`, `resetOwners` | [22](../src/owner.ts#L22), [28](../src/owner.ts#L28) |
|
||||
| SimpleX core | [`src/core.ts`](../src/core.ts#L19) | `openCore` | [19](../src/core.ts#L19) |
|
||||
| Package manifest | [`package.json`](../package.json) | `bin.simplex-mcp` | [6](../package.json#L6) |
|
||||
@@ -658,8 +658,8 @@ stderr: `CONTEXT: ERROR` from `logError` ([log.ts:41-43](../src/log.ts#L41-L43))
|
||||
| At `connect`, a known chat without an owner becomes the session's chat. `connect` to a chat of another session returns the tool error `The chat of TARGET belongs to another session; an admin or owner of that session's group can give it to this session with /give.` | [tools.ts:750-755](../src/tools.ts#L750-L755) |
|
||||
| Actions are numbered from 1 in each session group. The session number is part of the action key, see [1.1](#11-common-rules) | [hub.ts:75](../src/hub.ts#L75), [tools.ts:1705-1707](../src/tools.ts#L1705-L1707) |
|
||||
| Downloads are saved under `ROOT/_sessions/ID/files/` | [hub.ts:90](../src/hub.ts#L90), [messages.ts:225-227](../src/messages.ts#L225-L227) |
|
||||
| A run is not interactive when `CLAUDE_CODE_SESSION_ATTENDED` is `0`, which Claude Code sets for the hooks of a run nobody attends, or when `CLAUDE_CODE_ENTRYPOINT` is `sdk-cli`, which Claude Code sets for `claude -p`, or `sdk-ts` or `sdk-py`, for the Agent SDK. Such a run has no session. Its session process does not connect to the service, and every tool returns `This Claude Code run is not interactive, so it has no SimpleX group; the SimpleX tools work in interactive sessions.`, even when an option is invalid. Its hooks return `{}`, and the turn hooks send no request | [config.ts:22-32](../src/config.ts#L22-L32), [session.ts:15](../src/session.ts#L15), [:45-51](../src/session.ts#L45-L51), [:66](../src/session.ts#L66), [hook.ts:59-62](../src/hook.ts#L59-L62), [:92](../src/hook.ts#L92) |
|
||||
| A run with `CLAUDE_CODE_SESSION_ATTENDED` `0` and an entrypoint other than those three is, for example, a `claude -p` run started by a command of a VS Code or desktop-app session. Its SessionStart hook starts the service and sends `/title` with `unattended` for its `CLAUDE_PID`. The session server of that run gets the values of the attended session, `1` and its entrypoint. The service refuses it with status 403 when it registers from that process within 10 s of the mark. The refused server then answers every call with the same text, relays no permission request and registers no more | [hook.ts:79-89](../src/hook.ts#L79-L89), [service.ts:237-248](../src/service.ts#L237-L248), [session.ts:79-80](../src/session.ts#L79-L80), [:92](../src/session.ts#L92), [:115](../src/session.ts#L115), [:127](../src/session.ts#L127), [:162-165](../src/session.ts#L162-L165) |
|
||||
| A run is not interactive when `CLAUDE_CODE_SESSION_ATTENDED` is `0`, which Claude Code sets for the hooks of a run nobody attends, or when `CLAUDE_CODE_ENTRYPOINT` is `sdk-cli`, which Claude Code sets for `claude -p`, or `sdk-ts` or `sdk-py`, for the Agent SDK. Such a run has no session. Its session process does not connect to the service, and every tool returns `This Claude Code run is not interactive, so it has no SimpleX group; the SimpleX tools work in interactive sessions.`, even when an option is invalid. Its hooks return `{}`, and the turn hooks send no request | [config.ts:22-32](../src/config.ts#L22-L32), [session.ts:15](../src/session.ts#L15), [:45-51](../src/session.ts#L45-L51), [:66](../src/session.ts#L66), [hook.ts:82-85](../src/hook.ts#L82-L85), [:115](../src/hook.ts#L115) |
|
||||
| A run with `CLAUDE_CODE_SESSION_ATTENDED` `0` and an entrypoint other than those three is, for example, a `claude -p` run started by a command of a VS Code or desktop-app session. Its SessionStart hook starts the service and sends `/title` with `unattended` for its `CLAUDE_PID`. The session server of that run gets the values of the attended session, `1` and its entrypoint. The service refuses it with status 403 when it registers from that process within 10 s of the mark. The refused server then answers every call with the same text, relays no permission request and registers no more | [hook.ts:102-112](../src/hook.ts#L102-L112), [service.ts:237-248](../src/service.ts#L237-L248), [session.ts:79-80](../src/session.ts#L79-L80), [:92](../src/session.ts#L92), [:115](../src/session.ts#L115), [:127](../src/session.ts#L127), [:162-165](../src/session.ts#L162-L165) |
|
||||
|
||||
`reply` ([`replyTool`](../src/tools.ts#L462-L483), [`AgentTools.reply`](../src/tools.ts#L713-L730)):
|
||||
|
||||
@@ -690,11 +690,11 @@ Commands from any member, one line `/KEYWORD PARAMS` as in [2.1](#21-commands-an
|
||||
|
||||
| Request | Condition | Reply | Code |
|
||||
|---|---|---|---|
|
||||
| `/sessions` | no session | `No sessions.` | [hub.ts:430-433](../src/hub.ts#L430-L433) |
|
||||
| `/sessions` | otherwise | one line per session of the hub: `N · NAME`, with `, closed` when the service has no entry for it | [hub.ts:430-433](../src/hub.ts#L430-L433) |
|
||||
| `/join N` | no session N | `No session N. /sessions lists the sessions.` | [hub.ts:437](../src/hub.ts#L437) |
|
||||
| `/join N` | the sender is a member of its group | `You are a member of "N · NAME".` | [hub.ts:438-443](../src/hub.ts#L438-L443) |
|
||||
| `/join N` | otherwise: the sender is invited through the Main group, as `owner` when the sender is an owner of the Main group, else as `admin` | `Sent you an invitation to "N · NAME".` | [hub.ts:439](../src/hub.ts#L439), [:216-218](../src/hub.ts#L216-L218) |
|
||||
| `/sessions` | no session | `No sessions.` | [hub.ts:431-434](../src/hub.ts#L431-L434) |
|
||||
| `/sessions` | otherwise | one line per session of the hub: `N · NAME`, with `, closed` when the service has no entry for it | [hub.ts:431-434](../src/hub.ts#L431-L434) |
|
||||
| `/join N` | no session N | `No session N. /sessions lists the sessions.` | [hub.ts:438](../src/hub.ts#L438) |
|
||||
| `/join N` | the sender is a member of its group | `You are a member of "N · NAME".` | [hub.ts:439-444](../src/hub.ts#L439-L444) |
|
||||
| `/join N` | otherwise: the sender is invited through the Main group, as `owner` when the sender is an owner of the Main group, else as `admin` | `Sent you an invitation to "N · NAME".` | [hub.ts:440](../src/hub.ts#L440), [:217-219](../src/hub.ts#L217-L219) |
|
||||
| other one-line `/` text | | `Unknown command.` | [main-group.ts:14](../src/main-group.ts#L14), [:114](../src/main-group.ts#L114) |
|
||||
|
||||
Posts:
|
||||
@@ -704,7 +704,7 @@ Posts:
|
||||
| the first owner joined | `I'm Claude. Each Claude Code session has its own group, and you get its invitation here. /sessions lists the sessions; /join N joins the group of session N.` | [main-group.ts:13](../src/main-group.ts#L13), [:138](../src/main-group.ts#L138) |
|
||||
| each `joinedGroupMember` or `connectedToGroupMember` of a human who is found among the members read again. For the first owner, it is posted after the greeting | `NAME joined. They can join the group of any Claude Code session here, prompt Claude and approve its actions.` | [main-group.ts:17](../src/main-group.ts#L17), [:127-128](../src/main-group.ts#L127-L128) |
|
||||
|
||||
The session groups stay as they are when the membership or a role in the Main group is changed, and when the Main group is replaced by a reset of the owners. Members invited through the old Main group keep their roles in the session groups, with the rights of those roles ([main-group.ts:117-132](../src/main-group.ts#L117-L132), [:99-109](../src/main-group.ts#L99-L109), [hub.ts:311-313](../src/hub.ts#L311-L313)).
|
||||
The session groups stay as they are when the membership or a role in the Main group is changed, and when the Main group is replaced by a reset of the owners. Members invited through the old Main group keep their roles in the session groups, with the rights of those roles ([main-group.ts:117-132](../src/main-group.ts#L117-L132), [:99-109](../src/main-group.ts#L99-L109), [hub.ts:312-314](../src/hub.ts#L312-L314)).
|
||||
|
||||
Group profile ([`createMainGroup`](../src/main-group.ts#L195-L205), [`load`](../src/main-group.ts#L57-L66)):
|
||||
|
||||
@@ -740,11 +740,11 @@ Commands and replies are those of [2.1](#21-commands-and-replies), from approver
|
||||
| `/observer #G ID` | the sender's role is below admin or below the member's role, as SimpleX requires for a role change | `Your role does not let you change the role of NAME.` | [control.ts:383](../src/control.ts#L383), [:880-882](../src/control.ts#L880-L882) |
|
||||
| `/observer #G ID` | accepted: the member's role is set to `observer`, and the members are read again. The standing approvals that this member gave are kept in the chat's custom data, and are ignored until the member is an admin or owner again | `NAME is an observer and can't send messages.` | [control.ts:384-386](../src/control.ts#L384-L386), [:888-891](../src/control.ts#L888-L891), [:167-170](../src/control.ts#L167-L170) |
|
||||
| one-line `/` text outside the requests | an admin or owner | `Unknown command.` | [control.ts:20](../src/control.ts#L20), [:249](../src/control.ts#L249) |
|
||||
| any one-line `/` text | a moderator, member or author. The session replies before `Control`, and the text is passed to neither `Control` nor Claude | `Only admins and owners of this group can send / commands.`, quoting the message | [hub.ts:28](../src/hub.ts#L28), [:157](../src/hub.ts#L157), [:307-309](../src/hub.ts#L307-L309) |
|
||||
| any one-line `/` text | a moderator, member or author. The session replies before `Control`, and the text is passed to neither `Control` nor Claude | `Only admins and owners of this group can send / commands.`, quoting the message | [hub.ts:28](../src/hub.ts#L28), [:157](../src/hub.ts#L157), [:308-310](../src/hub.ts#L308-L310) |
|
||||
|
||||
The requests `give CHAT N` and `observer #G ID` of [2.1](#21-commands-and-replies) are parsed only in a plugin session group ([control.ts:857-858](../src/control.ts#L857-L858)). Approvers are the active members of the session group with the role `admin` or `owner`, other than Claude and `User`, however they joined. An observer can't send, because the core refuses an observer's message ([hub.ts:311-317](../src/hub.ts#L311-L317), [control.ts:43](../src/control.ts#L43), [:580-582](../src/control.ts#L580-L582), [:589-598](../src/control.ts#L589-L598)).
|
||||
The requests `give CHAT N` and `observer #G ID` of [2.1](#21-commands-and-replies) are parsed only in a plugin session group ([control.ts:857-858](../src/control.ts#L857-L858)). Approvers are the active members of the session group with the role `admin` or `owner`, other than Claude and `User`, however they joined. An observer can't send, because the core refuses an observer's message ([hub.ts:312-318](../src/hub.ts#L312-L318), [control.ts:43](../src/control.ts#L43), [:580-582](../src/control.ts#L580-L582), [:589-598](../src/control.ts#L589-L598)).
|
||||
|
||||
The hub handles other messages by these rules, in arrival order, one at a time ([hub.ts:153-160](../src/hub.ts#L153-L160), [:229-232](../src/hub.ts#L229-L232), [:303-313](../src/hub.ts#L303-L313), [control.ts:219-221](../src/control.ts#L219-L221)):
|
||||
The hub handles other messages by these rules, in arrival order, one at a time ([hub.ts:153-160](../src/hub.ts#L153-L160), [:230-233](../src/hub.ts#L230-L233), [:304-314](../src/hub.ts#L304-L314), [control.ts:219-221](../src/control.ts#L219-L221)):
|
||||
|
||||
```
|
||||
on a received message in the session group, by its text:
|
||||
@@ -765,20 +765,21 @@ The cards are those of [2.2](#22-cards), and two more:
|
||||
| `mode` | `I want to run in mode host: Claude Code asks you before each of my actions, and they are performed without approval here.`<br>done: `I run in mode host: ...` | `/'approve N' or /'reject N'` |
|
||||
| `permission` | ``I want to use `TOOL`: `DESCRIPTION` ``, then the input preview, one code span per line, cut to fit the card ([1.9](#19-action-refusals)) | `/'approve N' or /'reject N'` |
|
||||
|
||||
`mode` and `permission` are exempt from the card size check ([control.ts:155](../src/control.ts#L155), [:700-706](../src/control.ts#L700-L706), [:735-740](../src/control.ts#L735-L740)). In `/pending`, their WHAT is `run in mode MODE` and `use TOOL` ([actions.ts:383-384](../src/actions.ts#L383-L384)). The last line of a `mode` or `permission` card is `Ended.` when the hub ends the card at a turn, a detach or the option `requests`, and `Expired.` when it expires ([actions.ts:237-241](../src/actions.ts#L237-L241), [control.ts:695-696](../src/control.ts#L695-L696)).
|
||||
`mode` and `permission` are exempt from the card size check ([control.ts:155](../src/control.ts#L155), [:700-706](../src/control.ts#L700-L706), [:735-740](../src/control.ts#L735-L740)). In `/pending`, their WHAT is `run in mode MODE` and `use TOOL` ([actions.ts:383-384](../src/actions.ts#L383-L384)). The last line of a `mode` or `permission` card is `Ended.` when the hub ends the card, and `Expired.` when it expires. The hub ends a `permission` card at an answer, or at a prompt that is not mid-turn, whose hook started after the card was created, and at the last detach; it ends a `mode` card at the option `requests` ([hub.ts:135](../src/hub.ts#L135), [:181](../src/hub.ts#L181), [:204-208](../src/hub.ts#L204-L208), [service.ts:321](../src/service.ts#L321), [actions.ts:237-241](../src/actions.ts#L237-L241), [control.ts:695-696](../src/control.ts#L695-L696)).
|
||||
|
||||
Posts:
|
||||
|
||||
| Poster | Text | Code |
|
||||
|---|---|---|
|
||||
| Claude | the final answer of each turn, in parts. The turn's prompt from the group, chosen by the hub from the turn records below, is quoted in the first part when the quote fits with the answer's first character. A changed short description is set after the answer | [hub.ts:180-201](../src/hub.ts#L180-L201), [:266-295](../src/hub.ts#L266-L295) |
|
||||
| Claude | `Session N is not running.`, as a reply to a prompt when the session is not attached at the prompt's delivery. The hub delivers the prompt after the earlier prompts and after the prompt's own file. In the first 30 s after the service's start, the reply is posted only when the session does not attach by their end | [hub.ts:153-160](../src/hub.ts#L153-L160), [:234-248](../src/hub.ts#L234-L248), [:378](../src/hub.ts#L378) |
|
||||
| Claude | `The file of this message was not received: ERROR`, as a reply to a prompt whose file was not received, see [4.5](#45-channel) | [hub.ts:234-258](../src/hub.ts#L234-L258) |
|
||||
| Claude | the final answer of each turn, in parts. The turn's prompt from the group, chosen by the hub from the turn records below, is quoted in the first part when the quote fits with the answer's first character. A changed short description is set after the answer | [hub.ts:180-202](../src/hub.ts#L180-L202), [:267-296](../src/hub.ts#L267-L296) |
|
||||
| Claude | `Session N is not running.`, as a reply to a prompt when the session is not attached at the prompt's delivery. The hub delivers the prompt after the earlier prompts and after the prompt's own file. In the first 30 s after the service's start, the reply is posted only when the session does not attach by their end | [hub.ts:153-160](../src/hub.ts#L153-L160), [:235-249](../src/hub.ts#L235-L249), [:379](../src/hub.ts#L379) |
|
||||
| Claude | `The file of this message was not received: ERROR`, as a reply to a prompt whose file was not received, see [4.5](#45-channel) | [hub.ts:235-259](../src/hub.ts#L235-L259) |
|
||||
| Claude | the reply to the one-line `/` texts of the rules above, quoting the message | [hub.ts:28](../src/hub.ts#L28), [:157](../src/hub.ts#L157) |
|
||||
| `User` | each prompt typed in the terminal, in parts. A prompt with `typed: false` is left out, such as a notification of a background task. A request without `typed`, from an older plugin, is posted as typed. Blank prompts, prompts made only of this server's channel tags, the prompts pushed from the group and one-line `/` commands are left out too. `User` posts in the group that is marked with the session's number | [hub.ts:184-195](../src/hub.ts#L184-L195), [user.ts:29-32](../src/user.ts#L29-L32) |
|
||||
| Claude | a text in place of an answer or a terminal prompt that the core refuses with `feature not allowed NAME`, as `SimpleX links` for a SimpleX link. The text for an answer is `Claude's answer was not posted: NAME are off in the group of this session; its owners can turn them on in the group's preferences.`, quoting the turn's prompt as the answer would. A terminal prompt is replaced by `User's prompt was not posted: NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences.`, even while NAME is on only for roles above that of `User`. Claude is an owner of the group, so only the first text applies to its answers. The turn goes on | [hub.ts:195](../src/hub.ts#L195), [:277-287](../src/hub.ts#L277-L287), [:523-525](../src/hub.ts#L523-L525), [tools.ts:1607-1614](../src/tools.ts#L1607-L1614) |
|
||||
| Claude | `note` of a `/turn` request, a line about one of Claude Code's own prompts, without a quote, before the other posts of the request. See the hook's notes below | [hub.ts:195](../src/hub.ts#L195), [hook.ts:217-290](../src/hook.ts#L217-L290) |
|
||||
| `User` | each prompt typed in the terminal, also one typed during a turn, in parts. A prompt with `typed: false` is left out, such as a notification of a background task. A request without `typed`, from an older plugin, is posted as typed. Blank prompts, prompts made only of this server's channel tags, the prompts pushed from the group and one-line `/` commands are left out too. `User` posts in the group that is marked with the session's number | [hub.ts:184-196](../src/hub.ts#L184-L196), [user.ts:29-32](../src/user.ts#L29-L32) |
|
||||
| Claude | a text in place of an answer, a note or a terminal prompt that the core refuses with `feature not allowed NAME`, as `SimpleX links` for a SimpleX link. The text for an answer is `Claude's answer was not posted: NAME are off in the group of this session; its owners can turn them on in the group's preferences.`, quoting the turn's prompt as the answer would. A note is replaced by `A note on Claude Code's prompt was not posted: ` and the same preference text. A terminal prompt is replaced by `User's prompt was not posted: NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences.`, even while NAME is on only for roles above that of `User`. Claude is an owner of the group, so its answers and notes get only the texts with `are off`. The turn goes on | [hub.ts:195-196](../src/hub.ts#L195-L196), [:278-288](../src/hub.ts#L278-L288), [:524-526](../src/hub.ts#L524-L526), [tools.ts:1607-1614](../src/tools.ts#L1607-L1614) |
|
||||
| Claude | files sent by `reply`, at once | [tools.ts:713-730](../src/tools.ts#L713-L730), [hub.ts:93](../src/hub.ts#L93) |
|
||||
| Claude | the rights of the member's role, below. They are posted once for each join and each role change of a member other than `User`, at its `joinedGroupMember`, `connectedToGroupMember` or `memberRole` | [hub.ts:220-227](../src/hub.ts#L220-L227), [:518](../src/hub.ts#L518), [control.ts:40-43](../src/control.ts#L40-L43), [:884-891](../src/control.ts#L884-L891) |
|
||||
| Claude | the rights of the member's role, below. They are posted once for each join and each role change of a member other than `User`, at its `joinedGroupMember`, `connectedToGroupMember` or `memberRole` | [hub.ts:221-228](../src/hub.ts#L221-L228), [:519](../src/hub.ts#L519), [control.ts:40-43](../src/control.ts#L40-L43), [:884-891](../src/control.ts#L884-L891) |
|
||||
|
||||
Rights posts, by the member's role in the session group:
|
||||
|
||||
@@ -791,17 +792,18 @@ Rights posts, by the member's role in the session group:
|
||||
|
||||
#G is the session group, and ID is the member. The core raises no `memberRole` event for a role change that Claude makes itself, with `/observer`. The reply to `/observer` is the observer's post instead.
|
||||
|
||||
Parts ([hub.ts:531-548](../src/hub.ts#L531-L548), [tools.ts:1575-1578](../src/tools.ts#L1575-L1578)): the hub cuts the text into the longest runs of whole characters that `fitsMessage` accepts as one message. `fitsMessage` is the measure of `send` in [1.3](#13-send), in UTF-8 bytes. The first part is measured with its quote. The hub puts up to 14962 bytes of text into a part without a quote: 14962 Latin, 7481 Cyrillic or 4987 CJK characters, fewer for characters escaped in JSON.
|
||||
Parts ([hub.ts:532-549](../src/hub.ts#L532-L549), [tools.ts:1575-1578](../src/tools.ts#L1575-L1578)): the hub cuts the text into the longest runs of whole characters that `fitsMessage` accepts as one message. `fitsMessage` is the measure of `send` in [1.3](#13-send), in UTF-8 bytes. The first part is measured with its quote. The hub puts up to 14962 bytes of text into a part without a quote: 14962 Latin, 7481 Cyrillic or 4987 CJK characters, fewer for characters escaped in JSON.
|
||||
|
||||
Claude can quote a message in its answer and its replies. When the core refuses such a post with `errorStore` `invalidQuote` or `chatItemNotFound`, as for a deleted prompt, or with `largeMsg`, as for a reply that quotes a message near the size limit, the post is sent again without the quote ([hub.ts:289-295](../src/hub.ts#L289-L295), [:550-553](../src/hub.ts#L550-L553)).
|
||||
Claude can quote a message in its answer and its replies. When the core refuses such a post with `errorStore` `invalidQuote` or `chatItemNotFound`, as for a deleted prompt, or with `largeMsg`, as for a reply that quotes a message near the size limit, the post is sent again without the quote ([hub.ts:290-296](../src/hub.ts#L290-L296), [:551-554](../src/hub.ts#L551-L554)).
|
||||
|
||||
Turn records, one per `/turn` with `prompt`, are read and changed before the first await of each `/turn` ([hub.ts:54](../src/hub.ts#L54), [:180-186](../src/hub.ts#L180-L186), [:266-275](../src/hub.ts#L266-L275)):
|
||||
Turn records, added at a `/turn` with `prompt`, are read and changed before the first await of each `/turn` ([hub.ts:54](../src/hub.ts#L54), [:180-186](../src/hub.ts#L180-L186), [:267-276](../src/hub.ts#L267-L276)):
|
||||
|
||||
```
|
||||
on /turn {at, prompt}:
|
||||
on /turn {at, prompt, midTurn}:
|
||||
item = oldest pushed prompt that prompt contains in a channel tag of this server,
|
||||
or that equals prompt and was pushed in the last 60 s; else null
|
||||
turns += {at, item}, unless at is below answeredAt; the matched pushed prompts are removed
|
||||
turns += {at, item}, unless at is below answeredAt, or midTurn is true and nothing matched
|
||||
the matched pushed prompts are removed
|
||||
on /turn {at, answer}, also an empty answer:
|
||||
earlier = turns with at below the answer's at
|
||||
earlier not empty:
|
||||
@@ -813,7 +815,7 @@ on /turn {at, answer}, also an empty answer:
|
||||
at = performance.timeOrigin of the hook process; absent: Infinity for an answer's quote, now otherwise
|
||||
```
|
||||
|
||||
Group profile ([`createSessionGroup`](../src/hub.ts#L477-L489), [`Control.load`](../src/control.ts#L115-L122), [`describe`](../src/control.ts#L129-L131), [`updateProfile`](../src/control.ts#L133-L140)):
|
||||
Group profile ([`createSessionGroup`](../src/hub.ts#L478-L490), [`Control.load`](../src/control.ts#L115-L122), [`describe`](../src/control.ts#L129-L131), [`updateProfile`](../src/control.ts#L133-L140)):
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
@@ -827,7 +829,7 @@ Group profile ([`createSessionGroup`](../src/hub.ts#L477-L489), [`Control.load`]
|
||||
|
||||
Claude makes the profile updates one at a time. It starts each from the group's current profile in the chat database and changes only the display name, the short description or the command menu. So a rename and a model change that overlap both stay.
|
||||
|
||||
The hub takes the model and the effort level of a `/turn` only when its `at` is not older than the `at` of the value it took last. It keeps the two times apart, one for the model and one for the effort level. The model of a `/title` comes with the `at` of its SessionStart hook, as described in [4.6](#46-socket-protocol). A request without `at` counts as the current time. So when a Stop request that waited for its transcript entry arrives after a later model switch, the model of the switch stays ([hub.ts:187-193](../src/hub.ts#L187-L193), [:260-264](../src/hub.ts#L260-L264)).
|
||||
The hub takes the model and the effort level of a `/turn` only when its `at` is not older than the `at` of the value it took last. It keeps the two times apart, one for the model and one for the effort level. The model of a `/title` comes with the `at` of its SessionStart hook, as described in [4.6](#46-socket-protocol). A request without `at` counts as the current time. So when a Stop request that waited for its transcript entry arrives after a later model switch, the model of the switch stays ([hub.ts:187-193](../src/hub.ts#L187-L193), [:261-265](../src/hub.ts#L261-L265)).
|
||||
|
||||
### 4.4 Tool results in the plugin
|
||||
|
||||
@@ -869,7 +871,7 @@ Channel instructions: `Messages in the simplex channel are prompts of the member
|
||||
|
||||
The session server negotiates the protocol revision 2025-11-25 and answers `server/discover` with `Method not found`, as `McpServer` of the SDK 2.3.1 does by default. Claude Code 2.1.319 registers no channel for a server that negotiates the modern revision 2026-07-28. A unit test of the session server checks both answers ([session.test.ts](../test/unit/session.test.ts)).
|
||||
|
||||
The prompts of a session, from the members of [4.3](#43-session-groups), are delivered one at a time, in arrival order ([hub.ts:159](../src/hub.ts#L159), [:303-305](../src/hub.ts#L303-L305), [:234-248](../src/hub.ts#L234-L248)). While a session is attached, a prompt's file is received without a card, with relays approved, into `ROOT/_sessions/ID/files/group/<file ID><extension>`. The prompt is pushed after `rcvFileComplete`. After `rcvFileError`, a failed receive or 10 minutes, it is pushed without `file`. The next prompt waits until then ([hub.ts:234-258](../src/hub.ts#L234-L258), [:209-214](../src/hub.ts#L209-L214)). Pushed prompts are kept until they are matched by a turn's `prompt`, at most 20 ([hub.ts:23](../src/hub.ts#L23), [:186](../src/hub.ts#L186), [:246](../src/hub.ts#L246), [:268-272](../src/hub.ts#L268-L272)).
|
||||
The prompts of a session, from the members of [4.3](#43-session-groups), are delivered one at a time, in arrival order ([hub.ts:159](../src/hub.ts#L159), [:304-306](../src/hub.ts#L304-L306), [:235-249](../src/hub.ts#L235-L249)). While a session is attached, a prompt's file is received without a card, with relays approved, into `ROOT/_sessions/ID/files/group/<file ID><extension>`. The prompt is pushed after `rcvFileComplete`. After `rcvFileError`, a failed receive or 10 minutes, it is pushed without `file`. The next prompt waits until then ([hub.ts:235-259](../src/hub.ts#L235-L259), [:210-215](../src/hub.ts#L210-L215)). Pushed prompts are kept until they are matched by a turn's `prompt`, at most 20 ([hub.ts:23](../src/hub.ts#L23), [:186](../src/hub.ts#L186), [:247](../src/hub.ts#L247), [:269-273](../src/hub.ts#L269-L273)).
|
||||
|
||||
### 4.6 Socket protocol
|
||||
|
||||
@@ -882,10 +884,10 @@ The service speaks HTTP/1.1 over `ROOT/service.sock`, the fallback path or the W
|
||||
| `POST /attach` | `{id}` | a stream held open: the first line `{version, protocol}`, then `{prompt}` and `{permission}` lines | [service.ts:304-324](../src/service.ts#L304-L324) |
|
||||
| `POST /call` | `{id, tool, input}` | lines `{progress: TEXT}`, then one line `{result: CallToolResult or null}`. The call is aborted when the request is closed | [service.ts:326-345](../src/service.ts#L326-L345) |
|
||||
| `POST /permission` | `{id, requestId, toolName, description, inputPreview}` | `{}` after the card's action is created | [service.ts:143-147](../src/service.ts#L143-L147) |
|
||||
| `POST /turn` | `{id, pid?, at?, prompt?, typed?, answer?, model?, effort?}`, `at` the time the hook started, `typed` whether a person typed the prompt | `{}` after the posts | [service.ts:148-152](../src/service.ts#L148-L152) |
|
||||
| `POST /turn` | `{id, pid?, at?, prompt?, typed?, note?, midTurn?, answer?, model?, effort?}`, `at` the time the hook started, `typed` whether a person typed the prompt, `note` the line Claude posts about one of Claude Code's own prompts, `midTurn` whether Claude Code added the prompt to a running turn | `{}` after the posts | [service.ts:148-152](../src/service.ts#L148-L152) |
|
||||
| `GET /status` | none | `{version, protocol, mainGroup, owner: {owners}, sessions: [{number, name, attached}]}`, with the open sessions | [service.ts:424-427](../src/service.ts#L424-L427) |
|
||||
| `GET /link` | none | `{owners, link?}`, the link while the Main group has no owner | [service.ts:154](../src/service.ts#L154), [hub.ts:391-394](../src/hub.ts#L391-L394) |
|
||||
| `POST /reset-owners` | none | `{link}`, the link of the new Main group. The group is replaced at once, even while owners exist | [service.ts:155](../src/service.ts#L155), [hub.ts:402-404](../src/hub.ts#L402-L404) |
|
||||
| `GET /link` | none | `{owners, link?}`, the link while the Main group has no owner | [service.ts:154](../src/service.ts#L154), [hub.ts:392-395](../src/hub.ts#L392-L395) |
|
||||
| `POST /reset-owners` | none | `{link}`, the link of the new Main group. The group is replaced at once, even while owners exist | [service.ts:155](../src/service.ts#L155), [hub.ts:403-405](../src/hub.ts#L403-L405) |
|
||||
| `POST /stop` | none | `{}` after the stop sequence. The process exits after the reply | [service.ts:156-159](../src/service.ts#L156-L159) |
|
||||
|
||||
| Status | Error | Condition |
|
||||
@@ -926,11 +928,11 @@ on a service stop: the held title requests, with t
|
||||
on the next start: each one taken as a new /title
|
||||
```
|
||||
|
||||
`/session` and `/title` without `unattended` apply `config` to the hub ([hub.ts:396-400](../src/hub.ts#L396-L400), [service.ts:213](../src/service.ts#L213), [:221](../src/service.ts#L221), [:232](../src/service.ts#L232), [:259](../src/service.ts#L259)):
|
||||
`/session` and `/title` without `unattended` apply `config` to the hub ([hub.ts:397-401](../src/hub.ts#L397-L401), [service.ts:213](../src/service.ts#L213), [:221](../src/service.ts#L221), [:232](../src/service.ts#L232), [:259](../src/service.ts#L259)):
|
||||
- The hub sets the expiry of all sessions from `expireHours`.
|
||||
- The hub renames the Main group when `mainGroup` differs.
|
||||
|
||||
`/session` requests the session's mode ([hub.ts:132-151](../src/hub.ts#L132-L151), [:319-322](../src/hub.ts#L319-L322), [:324-327](../src/hub.ts#L324-L327), [:75](../src/hub.ts#L75), [:518](../src/hub.ts#L518)):
|
||||
`/session` requests the session's mode ([hub.ts:132-151](../src/hub.ts#L132-L151), [:320-323](../src/hub.ts#L320-L323), [:325-328](../src/hub.ts#L325-L328), [:75](../src/hub.ts#L75), [:519](../src/hub.ts#L519)):
|
||||
- `requests` applies at once. The hub ends a pending mode card and clears `hostDeclined`.
|
||||
- For `host`, the hub posts the mode card when the group has an approver and `hostDeclined` is unset. It posts the card at once, or after the next membership event of the group.
|
||||
- When the mode card is rejected, the hub sets `hostDeclined` in session.json.
|
||||
@@ -945,7 +947,7 @@ on the next start: each one taken as a new /title
|
||||
| `simplex-mcp session` | `.mcp.json` | MCP over stdio |
|
||||
| `simplex-mcp service` | `spawnService` | the ready line `ready`, `running` or `error: TEXT` on fd `SIMPLEX_MCP_READY_FD`, or on stdout when it is unset. If another running process holds ROOT/service.lock, the service checks the lock and the socket up to 150 times, 100 ms apart. It starts again once the lock is released, and its ready line is `running` once the socket answers. The log is written to stdout and stderr |
|
||||
| `simplex-mcp hook session-start` | SessionStart hook | one JSON line, see [4.8](#48-plugin-options-files-and-hook-output) |
|
||||
| `simplex-mcp hook turn` | UserPromptSubmit, Stop and PostModelSwitch hooks | `{}`. A prompt or an answer over 250,000 characters is cut there and ends with `…` ([hook.ts:16](../src/hook.ts#L16), [:190-192](../src/hook.ts#L190-L192)). The Stop hook sends the model of its answer, read from the transcript ([hook.ts:95](../src/hook.ts#L95), [:114-188](../src/hook.ts#L114-L188)). The UserPromptSubmit hook sends `typed`, read from the prompt's entry in the transcript ([:96](../src/hook.ts#L96), [:124-129](../src/hook.ts#L124-L129)) |
|
||||
| `simplex-mcp hook turn` | UserPromptSubmit, Stop and PostModelSwitch hooks | `{}`. A prompt or an answer over 250,000 characters is cut there and ends with `…` ([hook.ts:16](../src/hook.ts#L16), [:307-309](../src/hook.ts#L307-L309)). The Stop hook sends the model of its answer, read from the transcript ([hook.ts:118](../src/hook.ts#L118), [:137-145](../src/hook.ts#L137-L145), [:153-185](../src/hook.ts#L153-L185)). The UserPromptSubmit hook sends `typed`, `note` and `midTurn`, read from the prompt's record in the transcript ([:119](../src/hook.ts#L119), [:147-151](../src/hook.ts#L147-L151)) |
|
||||
| `simplex-mcp link` | people | with owners, `Owners of "MAIN": A, B. To replace them, run npx -y @simplex-chat/mcp@VERSION reset-owners in a terminal.` When the service reports neither owners nor a link, `The Main group has no link. Run npx -y @simplex-chat/mcp@VERSION reset-owners in a terminal.` Otherwise, on a terminal, `Join "MAIN" in the SimpleX app. The link works once:`, a QR code and the link, and elsewhere `Run npx -y @simplex-chat/mcp@VERSION link in a terminal to see the link to "MAIN".` |
|
||||
| `simplex-mcp reset-owners` | people | after `POST /reset-owners` of [4.6](#46-socket-protocol), on a terminal, `"MAIN" was replaced. Join the new one in the SimpleX app. The link works once:`, a QR code and the link, and elsewhere `"MAIN" was replaced. Run npx -y @simplex-chat/mcp@VERSION link in a terminal to see the link to the new one.` |
|
||||
|
||||
@@ -963,7 +965,7 @@ The service is spawned with the variables of the spawning process whose names ma
|
||||
|
||||
| Code | Message | Code location |
|
||||
|---|---|---|
|
||||
| 0 | the hooks, even after errors, `link` and `reset-owners`, and the service after a stop or with `running` | [hook.ts:74-76](../src/hook.ts#L74-L76), [:108-111](../src/hook.ts#L108-L111), [service.ts:440](../src/service.ts#L440) |
|
||||
| 0 | the hooks, even after errors, `link` and `reset-owners`, and the service after a stop or with `running` | [hook.ts:97-99](../src/hook.ts#L97-L99), [:131-134](../src/hook.ts#L131-L134), [service.ts:440](../src/service.ts#L440) |
|
||||
| 2 | `simplex-mcp session runs from the Claude Code plugin.` | [session.ts:42](../src/session.ts#L42) |
|
||||
| 2 | `Not a Claude Code session ID: ID` | [session.ts:43](../src/session.ts#L43) |
|
||||
| 1 | `Restart Claude Code to update the SimpleX plugin.`, or a spawn error, from `link` and `reset-owners` | [client.ts:45](../src/client.ts#L45), [:84](../src/client.ts#L84), [:111](../src/client.ts#L111) |
|
||||
@@ -980,12 +982,12 @@ The service's stdout and stderr are written to `service.log` ([client.ts:77](../
|
||||
| no owners, members present | `No owners in the Main group.` | [main-group.ts:15](../src/main-group.ts#L15), [:70](../src/main-group.ts#L70), [:124](../src/main-group.ts#L124) |
|
||||
| owner joined | `NAME joined (member ID) and is now an owner. The link is deleted.` | [main-group.ts:139](../src/main-group.ts#L139) |
|
||||
| Main group lost | `The Main group is lost. Run npx -y @simplex-chat/mcp@VERSION reset-owners in a terminal.` | [main-group.ts:144](../src/main-group.ts#L144) |
|
||||
| session group created | `Group "N · NAME" of session N created.` | [hub.ts:487](../src/hub.ts#L487) |
|
||||
| session group created | `Group "N · NAME" of session N created.` | [hub.ts:488](../src/hub.ts#L488) |
|
||||
| session group lost | `The group "N · NAME" is lost.` | [control.ts:483](../src/control.ts#L483) |
|
||||
| actions | as in [3.4](#34-terminal-lines), with ` of session N` after `Action N`, and `allowed.` for a tool use | [actions.ts:210](../src/actions.ts#L210), [:410](../src/actions.ts#L410) |
|
||||
| stop | `Cancelled K action(s).`, `Stopping: sending K cancelled card(s), up to 10 s. Ctrl-C to stop now.`, `Stopped.` | [service.ts:189](../src/service.ts#L189), [serve.ts:164](../src/serve.ts#L164), [service.ts:192](../src/service.ts#L192) |
|
||||
|
||||
stderr: `CONTEXT: ERROR` from `logError`, with CONTEXT among `Main group command`, `EVENT in the Main group`, `EVENT in the group of session N`, `prompt of session N`, `invitation to session N`, `User`, `User in session N`, `group of session N`, `session N`, `owner of CHAT`, `mode host of session N`, `title`, `ROOT/_sessions/ID/session.json`, `ROOT/titles.json`, `ROOT/service.log`, `METHOD PATH` and those of [3.4](#34-terminal-lines). Session processes and hooks write to their own stderr ([session.ts:55](../src/session.ts#L55), [:61](../src/session.ts#L61), [:93](../src/session.ts#L93), [hook.ts:87](../src/hook.ts#L87), [:109](../src/hook.ts#L109)):
|
||||
stderr: `CONTEXT: ERROR` from `logError`, with CONTEXT among `Main group command`, `EVENT in the Main group`, `EVENT in the group of session N`, `prompt of session N`, `invitation to session N`, `User`, `User in session N`, `group of session N`, `session N`, `owner of CHAT`, `mode host of session N`, `title`, `ROOT/_sessions/ID/session.json`, `ROOT/titles.json`, `ROOT/service.log`, `METHOD PATH` and those of [3.4](#34-terminal-lines). Session processes and hooks write to their own stderr ([session.ts:55](../src/session.ts#L55), [:61](../src/session.ts#L61), [:93](../src/session.ts#L93), [hook.ts:110](../src/hook.ts#L110), [:132](../src/hook.ts#L132)):
|
||||
- A session process writes `SimpleX service: ERROR`, `SimpleX channel: ERROR` and `permission relay: ERROR`.
|
||||
- The SessionStart hook of an unattended run writes `SimpleX MCP session start: ERROR`, and the turn hook `SimpleX MCP turn: ERROR`.
|
||||
|
||||
@@ -1011,15 +1013,29 @@ The default is used for a missing or blank variable ([config.ts:35-38](../src/co
|
||||
| [`plugin/allow.js`](../plugin/allow.js) | prints `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}` |
|
||||
| [`/.claude-plugin/marketplace.json`](../../../.claude-plugin/marketplace.json) | marketplace `simplex-chat`, plugin `simplex`, source `{"source": "npm", "package": "@simplex-chat/mcp"}` |
|
||||
|
||||
Hook input fields used ([hook.ts:23-47](../src/hook.ts#L23-L47)):
|
||||
Hook input fields used ([hook.ts:27-70](../src/hook.ts#L27-L70)):
|
||||
- SessionStart: `session_id`, `session_title`, `cwd` and `model`.
|
||||
- The other hooks: `session_id`, `hook_event_name`, `transcript_path`, `prompt_id`, `prompt`, `last_assistant_message`, `to_model` and `effort.level`.
|
||||
|
||||
The Stop hook reads `type`, `isSidechain`, `message.model` and the `text` parts of `message.content` from the last entries of the transcript ([hook.ts:154-188](../src/hook.ts#L154-L188)). It reads the transcript up to 20 times, 100 ms apart, until Claude's last entry is the answer. A missing transcript is read again, as a transcript without that entry is ([hook.ts:17](../src/hook.ts#L17), [:114-122](../src/hook.ts#L114-L122), [:131-139](../src/hook.ts#L131-L139)).
|
||||
The Stop hook reads `type`, `isSidechain`, `message.model` and the `text` parts of `message.content` from the last entries of the transcript ([hook.ts:176-185](../src/hook.ts#L176-L185), [:292-305](../src/hook.ts#L292-L305)). It reads the transcript up to 20 times, 100 ms apart, until Claude's last entry is the answer. A missing transcript is read again, as a transcript without that entry is ([hook.ts:17](../src/hook.ts#L17), [:137-145](../src/hook.ts#L137-L145), [:153-161](../src/hook.ts#L153-L161)).
|
||||
|
||||
The UserPromptSubmit hook finds the prompt's entry among the last user entries of the transcript. Entries of subagents and tool results are skipped. The entry's `promptId` equals the hook's `prompt_id`. Without `prompt_id`, as in older Claude Code, the hook takes the last entry whose text equals the prompt. `typed` is true when the entry's `origin.kind` is `human`. A task notification, a message of another session and a channel prompt have other kinds. Claude Code writes the entry only after the synchronous UserPromptSubmit hooks end, and it creates the transcript file with the session's first entry. So the hook reads the transcript up to 600 times, 100 ms apart. A missing transcript is read again, as a transcript without the entry is. When the entry is not found within these reads, `typed` is false ([hook.ts:18-19](../src/hook.ts#L18-L19), [:124-139](../src/hook.ts#L124-L139), [:165-173](../src/hook.ts#L165-L173)).
|
||||
The UserPromptSubmit hook finds the prompt's record among the last entries of the transcript. A record is a user entry, without subagent entries and tool results, or a `queued_command` attachment, the record of a prompt that Claude Code added to a running turn. The record is the newest one whose text equals the prompt: the entry whose `promptId` equals the hook's `prompt_id`, or a record after the first entry with that ID. Claude Code gives the hook of a prompt added to a running turn that turn's prompt ID, and the turn's tool results carry it too, so the first entry with that ID is found also when the turn's first entry is out of the tail. Until an entry with `prompt_id` is in the tail, the hook waits for it, and at the last read it takes any record with the prompt's text. While a `queue-operation` `enqueue` entry with the prompt's text follows the record, the hook waits too: the prompt is a later one with the same text, still queued. Without `prompt_id`, as in older Claude Code, it takes any record at once. `typed` is true when the record's `origin.kind` is `human`, and `midTurn` is true when the record is not the entry with `prompt_id`. Claude Code writes the entry only after the synchronous UserPromptSubmit hooks end, and it creates the transcript file with the session's first entry. So the hook reads the transcript up to 600 times, 100 ms apart. A missing transcript is read again, as a transcript without the entry is. Claude Code runs the hook of a person's prompt when it is submitted, and of its own prompts only when they are taken. So at the last read, the hook classifies a record still followed by such an `enqueue` entry by the record, and marks a typed one mid-turn: the queued prompt is the typed prompt itself, or a later prompt with the text of Claude Code's own prompt. When no record is found within these reads, an `enqueue` entry with the prompt's text after the entry with `prompt_id`, or anywhere without that entry, makes the prompt typed and mid-turn. Otherwise `typed` is true when an entry with `prompt_id` has the origin `human` ([hook.ts:18-19](../src/hook.ts#L18-L19), [:147-161](../src/hook.ts#L147-L161), [:187-222](../src/hook.ts#L187-L222)).
|
||||
|
||||
SessionStart output ([hook.ts:58-89](../src/hook.ts#L58-L89)):
|
||||
The hook's `note` is a line of at most 200 characters; a longer one is cut to 199 and ends with `…`. A typed prompt, a channel prompt, a teammate's prompt of idle notifications only and another record without origin that is not scheduled have no note ([hook.ts:217-290](../src/hook.ts#L217-L290)):
|
||||
|
||||
| Kind | Record | Line |
|
||||
|---|---|---|
|
||||
| task notification | origin `task-notification`, or a `queued_command` attachment without origin whose `commandMode` is `task-notification` | an emoji, the first line of `<summary>` or `Task notification`, and `: ` with the first line of `<event>` when there is one. Entities are decoded. The emoji is ✅ for `<status>` completed, ❌ for failed, ⏹️ for stopped or killed; without a status, 📡 with an event and 🔔 without. A prompt without a `<task-notification>` block gets 🔔 and its first line |
|
||||
| message of another session | origin `peer` | `✉️ Message from NAME: ` and the first line of `body`. NAME is `name`, or `from` |
|
||||
| message of a teammate | no origin; the prompt starts with `Another Claude session sent a message` and a `<teammate-message teammate_id="NAME" ...>` tag | `✉️ Message from NAME: ` and the tag's `summary`, or the first line of the message without one, from the first tag whose message is not an idle notification, a JSON `type` of `idle_notification`. A prompt with idle notifications only has no note |
|
||||
| subagent report | origin `peer` with `handback` | `📋 Report from subagent NAME: ` and the first line of `handbackReportText`, or of `body` |
|
||||
| scheduled prompt | no origin, `turnOrigin` `scheduled` | `⏰ Scheduled prompt: ` and the first line of the prompt |
|
||||
| automatic prompt | origin `auto-continuation` | `🔄 Automatic prompt: ` and the first line of the prompt |
|
||||
| another kind | another origin | `⚙️ Claude Code: ` and the first line of the prompt |
|
||||
|
||||
A first line is the first line with other than blank characters. In a first line and in NAME, control and format characters become spaces, so a note is one line.
|
||||
|
||||
SessionStart output ([hook.ts:81-112](../src/hook.ts#L81-L112)):
|
||||
|
||||
| Case | Output |
|
||||
|---|---|
|
||||
|
||||
@@ -758,14 +758,14 @@ Data flow of a tool call:
|
||||
3. The session process sends `POST /call` with the session ID, the tool and the input. It relays each `{progress}` line as an MCP progress notification, and returns the `{result}` line ([session.ts:132-151](../src/session.ts#L132-L151)).
|
||||
4. The service checks the token ([socket.ts:18-48](../src/socket.ts#L18-L48)). It finds or opens the entry of the session or of its alias, and runs the session's `AgentTools.call` with a signal tied to the request ([service.ts:326-345](../src/service.ts#L326-L345)).
|
||||
5. `AgentTools` sends chat commands to the core `_hub`. Actions are created in the session's `Actions`, and the session's `Control` posts them as cards in the session's group ([hub.ts:69-103](../src/hub.ts#L69-L103)).
|
||||
6. The core emits events to `Hub.onEvent`. The hub passes them to the Main group, each session's `AgentTools.onEvent`, and the `Control` of the session group they belong to ([hub.ts:491-521](../src/hub.ts#L491-L521)).
|
||||
6. The core emits events to `Hub.onEvent`. The hub passes them to the Main group, each session's `AgentTools.onEvent`, and the `Control` of the session group they belong to ([hub.ts:492-522](../src/hub.ts#L492-L522)).
|
||||
|
||||
Data flow of a prompt from the session group:
|
||||
|
||||
1. `Session.onMessage` receives a message of a member in the group of session N ([hub.ts:495-500](../src/hub.ts#L495-L500)). A one-line `/` command goes to `Control`. Another message is queued after the earlier ones ([:153-160](../src/hub.ts#L153-L160)). `Session.prompt` drops a message of `User` and delivers the rest ([:229-232](../src/hub.ts#L229-L232)).
|
||||
2. In the first 30 s after the hub opened, a delivery without an attachment waits for one. With an attachment, the file of the message, if any, is received. Then, if the session is not attached, the hub replies `Session N is not running.` Otherwise the prompt is pushed, and the line `{prompt}` is written to every `/attach` stream of the session ([hub.ts:234-248](../src/hub.ts#L234-L248), [service.ts:314](../src/service.ts#L314)).
|
||||
1. `Session.onMessage` receives a message of a member in the group of session N ([hub.ts:496-501](../src/hub.ts#L496-L501)). A one-line `/` command goes to `Control`. Another message is queued after the earlier ones ([:153-160](../src/hub.ts#L153-L160)). `Session.prompt` drops a message of `User` and delivers the rest ([:230-233](../src/hub.ts#L230-L233)).
|
||||
2. In the first 30 s after the hub opened, a delivery without an attachment waits for one. With an attachment, the file of the message, if any, is received. Then, if the session is not attached, the hub replies `Session N is not running.` Otherwise the prompt is pushed, and the line `{prompt}` is written to every `/attach` stream of the session ([hub.ts:235-249](../src/hub.ts#L235-L249), [service.ts:314](../src/service.ts#L314)).
|
||||
3. The session process sends it to Claude Code as `notifications/claude/channel` ([session.ts:53-56](../src/session.ts#L53-L56), [:197-201](../src/session.ts#L197-L201)).
|
||||
4. The hooks post the terminal prompts and the final answer of each turn with `POST /turn` ([hook.ts:91-112](../src/hook.ts#L91-L112), [hub.ts:180-201](../src/hub.ts#L180-L201)).
|
||||
4. The hooks post the terminal prompts and the final answer of each turn with `POST /turn` ([hook.ts:114-135](../src/hook.ts#L114-L135), [hub.ts:180-202](../src/hub.ts#L180-L202)).
|
||||
|
||||
### 8.2 Modules
|
||||
|
||||
@@ -854,24 +854,24 @@ Data flow of a prompt from the session group:
|
||||
| `Session.onMessage` | [153-160](../src/hub.ts#L153-L160) | The hub answers a `/` command from a member who is not an approver with the one refusal, found by `refusesCommand` and posted on the `delivery` chain. The remaining one-line `/` texts go to `Control`, and other messages go to `prompt` on the `delivery` chain, in arrival order. |
|
||||
| `Session.claimPending` | [162](../src/hub.ts#L162) | When a connection of `connect` recorded in the last day completes, its record is removed and its chat is claimed. |
|
||||
| `Session.permission` | [169](../src/hub.ts#L169) | a `permission` action in mode `requests`. Its verdict is written to the attachments, and the action is removed when decided. |
|
||||
| `Session.turn` | [180](../src/hub.ts#L180) | Before any await, at a prompt or an answer, the permissions created before its hook started are ended. An answer's quote is chosen, and its hook's start is recorded as the latest answer's hook start. A turn record is added for a prompt whose hook started after the latest answer's hook. The model and the effort level of the request are taken only when its `at` is not older than the `at` of the value taken last, kept apart for each ([`newer`](../src/hub.ts#L260-L264)). A `/title` passes its model with the `at` of its SessionStart hook. A request without `at` counts as the current time. A changed description is recorded in `session.json`. After these steps, `User` posts the terminal prompt unless its `typed` is false, or it is blank, made only of this plugin's channel tags, pushed or a command. A prompt without `typed` is posted as typed. The turn record of a prompt is kept whatever its `typed`. Claude posts the answer unless it is blank. The changed short description is set, even after a failed post. A prompt or an answer that the core refuses for a group preference is replaced by Claude's post with the preference's name. |
|
||||
| `Session.endPermissions`, `fileDone` | [203-214](../src/hub.ts#L203-L214) | the end of pending permissions created before a time; the end of a prompt's file |
|
||||
| `Session.invite`, `announceRights` | [216-227](../src/hub.ts#L216-L227) | invitation through the Main group. At a member's join or role change, other than `User`'s, the rights of the member's role are posted. The `/observer` command is added only for a role that can send, other than owner ([225](../src/hub.ts#L225)). |
|
||||
| `Session.prompt` | [229-232](../src/hub.ts#L229-L232) | a message of `User` dropped; the rest delivered |
|
||||
| `Session.deliver`, `receive`, `turnQuote`, `answer`, `postRefusal`, `post`, `pushedIn` | [234-301](../src/hub.ts#L234-L301) | `deliver` waits for the held prompts, and then receives the file while the session is attached. It writes the prompt line with the file's path. After a failure of the file, the line is written without the path, and a reply is posted. Without an attachment, the reply is `Session N is not running.` `receive` receives the file into the session's folder within 10 minutes. `turnQuote` returns the newest turn record before an answer, or else the oldest pushed prompt not quoted yet, which it marks quoted. `answer` posts the answer in parts, with its quote when the quote fits with the answer's first character. `postRefusal` replaces a post that the core refuses with `feature not allowed NAME` by the subject and the text with the preference's name. The text is made by `featureOff` for an answer, and by `notAllowedForUser` for a prompt of `User`. `post` sends a post to the group, and sends it again without its quote when the core refuses the quote. `pushedIn` returns the pushed prompts contained in a turn's prompt. |
|
||||
| `Session.queue`, `refusesCommand` | [303-309](../src/hub.ts#L303-L309) | the `delivery` chain; a one-line `/` text of a member other than `User` who is not an approver |
|
||||
| `Session.approves`, `isUser`, `setMode`, `declineHost`, `store`, `savePending` | [311-339](../src/hub.ts#L311-L339) | approver check: not `User`, the role `admin` or `owner` in the session group; the member of the contact `Hub.userContactId`; the mode and its record in the group's custom data; `hostDeclined` and its record; fields written into `session.json`; a pending connection recorded, those older than a day dropped |
|
||||
| `Hub.userContactId` | [350](../src/hub.ts#L350) | the hub's contact marked `simplexMcpUser`, read at the start |
|
||||
| `Hub.open` | [367](../src/hub.ts#L367) | core `_hub`, Main group found or created, `MainGroup` load and start, `User` unless it fails, the contact of `User`, the stored sessions, events |
|
||||
| `Hub.configure`, `resetOwners` | [396-404](../src/hub.ts#L396-L404) | expiry of all sessions and the Main group name. The Main group is replaced at once, even while owners exist. |
|
||||
| `Hub.session` | [406](../src/hub.ts#L406) | the open session, renamed when its name changed, or a new `Session` with its stored or new group. The owners are invited to a new group. |
|
||||
| `Hub.sessionsText`, `join`, `inviteOwner` | [430-452](../src/hub.ts#L430-L452) | `SessionGroups` of the Main group |
|
||||
| `Hub.stop` | [458](../src/hub.ts#L458) | actions stopped, events awaited, cancelled cards awaited up to 10 s, cores closed |
|
||||
| `storedGroup`, `createSessionGroup` | [470-489](../src/hub.ts#L470-L489) | the group of `session.json` with a matching session number; a new group with `User` added |
|
||||
| `Hub.onEvent` | [491](../src/hub.ts#L491) | event dispatch. Pending connections are claimed at `contactConnected` and `userJoinedGroup`. A session group's membership events go to its `Control`, `announceRights` and `askMode`, one at a time. |
|
||||
| `notAllowedForUser` | [523](../src/hub.ts#L523) | `NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences.` It is posted for a prompt of `User` refused by a group preference, including one that is on only for roles above that of `User`. |
|
||||
| `textParts` | [531](../src/hub.ts#L531) | the longest runs of whole characters that each fit in one message by `fitsMessage`, the first with the given quote. Each part is found by a binary search among the next `maxMessageLength` characters. |
|
||||
| `isRefusedQuote` | [550](../src/hub.ts#L550) | `errorStore` `invalidQuote`, `chatItemNotFound` or `largeMsg` |
|
||||
| `Session.turn` | [180](../src/hub.ts#L180) | Before any await, at an answer or a prompt that is not mid-turn, the permissions created before its hook started are ended. An answer's quote is chosen, and its hook's start is recorded as the latest answer's hook start. A turn record is added for a prompt whose hook started no earlier than the latest answer's hook, unless the prompt is mid-turn and matched no pushed prompt. The model and the effort level of the request are taken only when its `at` is not older than the `at` of the value taken last, kept apart for each ([`newer`](../src/hub.ts#L261-L265)). A `/title` passes its model with the `at` of its SessionStart hook. A request without `at` counts as the current time. A changed description is recorded in `session.json`. After these steps, Claude posts the request's `note` without a quote, and `User` posts the terminal prompt unless its `typed` is false, or it is blank, made only of this plugin's channel tags, pushed or a command. A prompt without `typed` is posted as typed. The turn record of a prompt is kept whatever its `typed`. Claude posts the answer unless it is blank. The changed short description is set, even after a failed post. A prompt, a note or an answer that the core refuses for a group preference is replaced by Claude's post with the preference's name. |
|
||||
| `Session.endPermissions`, `fileDone` | [204-215](../src/hub.ts#L204-L215) | the end of pending permissions created before a time; the end of a prompt's file |
|
||||
| `Session.invite`, `announceRights` | [217-228](../src/hub.ts#L217-L228) | invitation through the Main group. At a member's join or role change, other than `User`'s, the rights of the member's role are posted. The `/observer` command is added only for a role that can send, other than owner ([226](../src/hub.ts#L226)). |
|
||||
| `Session.prompt` | [230-233](../src/hub.ts#L230-L233) | a message of `User` dropped; the rest delivered |
|
||||
| `Session.deliver`, `receive`, `turnQuote`, `answer`, `postRefusal`, `post`, `pushedIn` | [235-302](../src/hub.ts#L235-L302) | `deliver` waits for the held prompts, and then receives the file while the session is attached. It writes the prompt line with the file's path. After a failure of the file, the line is written without the path, and a reply is posted. Without an attachment, the reply is `Session N is not running.` `receive` receives the file into the session's folder within 10 minutes. `turnQuote` returns the newest turn record before an answer, or else the oldest pushed prompt not quoted yet, which it marks quoted. `answer` posts the answer in parts, with its quote when the quote fits with the answer's first character. `postRefusal` replaces a post that the core refuses with `feature not allowed NAME` by the subject and the text with the preference's name. The text is made by `featureOff` for an answer, and by `notAllowedForUser` for a prompt of `User`. `post` sends a post to the group, and sends it again without its quote when the core refuses the quote. `pushedIn` returns the pushed prompts contained in a turn's prompt. |
|
||||
| `Session.queue`, `refusesCommand` | [304-310](../src/hub.ts#L304-L310) | the `delivery` chain; a one-line `/` text of a member other than `User` who is not an approver |
|
||||
| `Session.approves`, `isUser`, `setMode`, `declineHost`, `store`, `savePending` | [312-340](../src/hub.ts#L312-L340) | approver check: not `User`, the role `admin` or `owner` in the session group; the member of the contact `Hub.userContactId`; the mode and its record in the group's custom data; `hostDeclined` and its record; fields written into `session.json`; a pending connection recorded, those older than a day dropped |
|
||||
| `Hub.userContactId` | [351](../src/hub.ts#L351) | the hub's contact marked `simplexMcpUser`, read at the start |
|
||||
| `Hub.open` | [368](../src/hub.ts#L368) | core `_hub`, Main group found or created, `MainGroup` load and start, `User` unless it fails, the contact of `User`, the stored sessions, events |
|
||||
| `Hub.configure`, `resetOwners` | [397-405](../src/hub.ts#L397-L405) | expiry of all sessions and the Main group name. The Main group is replaced at once, even while owners exist. |
|
||||
| `Hub.session` | [407](../src/hub.ts#L407) | the open session, renamed when its name changed, or a new `Session` with its stored or new group. The owners are invited to a new group. |
|
||||
| `Hub.sessionsText`, `join`, `inviteOwner` | [431-453](../src/hub.ts#L431-L453) | `SessionGroups` of the Main group |
|
||||
| `Hub.stop` | [459](../src/hub.ts#L459) | actions stopped, events awaited, cancelled cards awaited up to 10 s, cores closed |
|
||||
| `storedGroup`, `createSessionGroup` | [471-490](../src/hub.ts#L471-L490) | the group of `session.json` with a matching session number; a new group with `User` added |
|
||||
| `Hub.onEvent` | [492](../src/hub.ts#L492) | event dispatch. Pending connections are claimed at `contactConnected` and `userJoinedGroup`. A session group's membership events go to its `Control`, `announceRights` and `askMode`, one at a time. |
|
||||
| `notAllowedForUser` | [524](../src/hub.ts#L524) | `NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences.` It is posted for a prompt of `User` refused by a group preference, including one that is on only for roles above that of `User`. |
|
||||
| `textParts` | [532](../src/hub.ts#L532) | the longest runs of whole characters that each fit in one message by `fitsMessage`, the first with the given quote. Each part is found by a binary search among the next `maxMessageLength` characters. |
|
||||
| `isRefusedQuote` | [551](../src/hub.ts#L551) | `errorStore` `invalidQuote`, `chatItemNotFound` or `largeMsg` |
|
||||
|
||||
#### [`main-group.ts`](../src/main-group.ts)
|
||||
|
||||
@@ -908,10 +908,11 @@ Data flow of a prompt from the session group:
|
||||
|
||||
| Symbol | Line | Contents |
|
||||
|---|---|---|
|
||||
| `sessionStart` | [hook.ts:58](../src/hook.ts#L58) | `{}` for a run that is not interactive. When the run is not interactive only because of `CLAUDE_CODE_SESSION_ATTENDED`, its process is marked first. In an interactive run, the hook checks Node.js, reads the options, calls `ensureService`, sends `POST /title` with the title, the folder, the model and its own start time `performance.timeOrigin`, and returns the link message. |
|
||||
| `markUnattended` | [hook.ts:79](../src/hook.ts#L79) | When `CLAUDE_PID` is set, the hook calls `ensureService` and sends `POST /title` with `unattended`. A failure is logged. |
|
||||
| `turn` | [hook.ts:91](../src/hook.ts#L91) | The output is `{}`. In a run that is not interactive, the hook sends nothing. Otherwise it calls `ensureService`, then sends `POST /turn` with the fields of [8.6](#86-channel-and-mirroring). The request is tried up to 15 times, 1 s apart, while the service returns status 409. |
|
||||
| `answerModel`, `promptTyped`, `findInTranscript`, `readTail`, `lastAnswer`, `promptEntry` | [hook.ts:114-188](../src/hook.ts#L114-L188) | `answerModel` finds the model of Stop's answer. It is the `message.model` of the last entry of type `assistant` without `isSidechain` in the tail of `transcript_path`, once that entry's text is the answer. No model is sent for `<synthetic>`, an answer without text, an empty path, an unreadable transcript, or an entry not written within the reads. `promptTyped` finds whether a person typed the prompt of UserPromptSubmit. Its entry is the user entry with the hook's `prompt_id` as `promptId`, or, without `prompt_id`, the last one whose text is the prompt, without subagent entries and tool results. The prompt is typed when the entry's `origin.kind` is `human`, and not typed when no entry is found within the reads. `findInTranscript` reads the tail, the last 1 MiB plus twice the bytes of the answer or the prompt, 100 ms apart: at most 20 times for an answer and 600 times for a prompt. It treats a failed read, as of a missing file, as an empty tail. |
|
||||
| `sessionStart` | [hook.ts:81](../src/hook.ts#L81) | `{}` for a run that is not interactive. When the run is not interactive only because of `CLAUDE_CODE_SESSION_ATTENDED`, its process is marked first. In an interactive run, the hook checks Node.js, reads the options, calls `ensureService`, sends `POST /title` with the title, the folder, the model and its own start time `performance.timeOrigin`, and returns the link message. |
|
||||
| `markUnattended` | [hook.ts:102](../src/hook.ts#L102) | When `CLAUDE_PID` is set, the hook calls `ensureService` and sends `POST /title` with `unattended`. A failure is logged. |
|
||||
| `turn` | [hook.ts:114](../src/hook.ts#L114) | The output is `{}`. In a run that is not interactive, the hook sends nothing. Otherwise it calls `ensureService`, then sends `POST /turn` with the fields of [8.6](#86-channel-and-mirroring). The request is tried up to 15 times, 1 s apart, while the service returns status 409. |
|
||||
| `answerModel`, `promptKind`, `findInTranscript`, `readTail`, `lastAnswer`, `promptRecord`, `isPrompt`, `recordText`, `recordKind` | [hook.ts:137-222](../src/hook.ts#L137-L222) | `answerModel` finds the model of Stop's answer. It is the `message.model` of the last entry of type `assistant` without `isSidechain` in the tail of `transcript_path`, once that entry's text is the answer. No model is sent for `<synthetic>`, an answer without text, an empty path, an unreadable transcript, or an entry not written within the reads. `promptKind` finds whether a person typed the prompt of UserPromptSubmit, its note and whether it is mid-turn. Its record, found by `promptRecord`, is the newest user entry or `queued_command` attachment whose text is the prompt, without subagent entries and tool results: the entry with the hook's `prompt_id` as `promptId`, or a record after the first user entry with that ID, a tool result included. Until such an entry is in the tail, `promptRecord` waits; at the last read, and at once without `prompt_id`, it takes any record with the prompt's text. It also waits while an `enqueue` entry with the prompt's text follows the record. The prompt is typed when the record's `origin.kind` is `human`, and mid-turn when the record is not the entry with `prompt_id`. A `queued_command` attachment without origin and with the `commandMode` `task-notification` is a task notification. At the last read, a record with an `enqueue` entry after it is classified by its origin, and a typed one is mid-turn. Without a record, an `enqueue` entry with the prompt's text makes the prompt typed and mid-turn; otherwise an entry with `prompt_id` and the origin `human` makes it typed. `findInTranscript` reads the tail, the last 1 MiB plus twice the bytes of the answer or the prompt, 100 ms apart: at most 20 times for an answer and 600 times for a prompt, and it tells its search which read is the last. It treats a failed read, as of a missing file, as an empty tail. |
|
||||
| `noteOf`, `taskNote`, `teammateNote`, `idleNotification`, `peerName`, `firstLine`, `decoded`, `stringOf`, `shortened` | [hook.ts:224-290](../src/hook.ts#L224-L290) | `noteOf` makes the note of a record from its origin, its `turnOrigin` and the prompt, as [api.md](api.md#48-plugin-options-files-and-hook-output) lists the lines. `taskNote` reads `<summary>`, `<event>` and `<status>` of the first `<task-notification>` block, and takes the first line of a prompt without one. `teammateNote` reads the sender, the `summary` and the message of the first `<teammate-message>` tag of a prompt without origin whose message is not an idle notification; `idleNotification` checks whether a message's JSON `type` is `idle_notification`. `firstLine`, `peerName` and `teammateNote` replace control and format characters with spaces in each first line and in the sender's name, as `oneLine` does, so a note is one line. `shortened` cuts a note to 200 characters, counted in code points. |
|
||||
| `linkCommand`, `resetCommand` | [owner.ts:7-8](../src/owner.ts#L7-L8) | `npx -y @simplex-chat/mcp@VERSION link` and `reset-owners`, VERSION of this package |
|
||||
| `linkText`, `resetOwnersText` | [owner.ts:10-20](../src/owner.ts#L10-L20) | the Main group's name with the owners, or with the link and a QR code on a terminal only |
|
||||
| `showLink`, `resetOwners` | [owner.ts:22-33](../src/owner.ts#L22-L33) | `link` takes the link from `GET /link` while no owner is in the Main group. `reset-owners` replaces the Main group at once, and shows the new link on a terminal only. |
|
||||
@@ -956,8 +957,8 @@ Memory of the service:
|
||||
| Held titles | `Service.held`, PID to its last held `/title` request ([service.ts:77](../src/service.ts#L77)) | `onTitle`, the end of its wait | `onTitle`, `shutdown` |
|
||||
| Processes of unattended runs | `Service.unattended`, PID to the time of its mark ([service.ts:78](../src/service.ts#L78)) | `onTitle` with `unattended` | `onSession` |
|
||||
| Process of a session server | `Entry.pid`, `Entry.seen` ([service.ts:65-66](../src/service.ts#L65-L66)) | `onSession`, the end of the last attachment | `processSession` |
|
||||
| Sessions | `Hub.sessions`, by number ([hub.ts:352](../src/hub.ts#L352)) | `Hub.session` | events, Main group commands |
|
||||
| End of the held prompts | `Hub.promptsHeldUntil`, 30 s after the stored sessions opened ([hub.ts:351](../src/hub.ts#L351), [:378](../src/hub.ts#L378)) | `Hub.open` | `Session.deliver` |
|
||||
| Sessions | `Hub.sessions`, by number ([hub.ts:353](../src/hub.ts#L353)) | `Hub.session` | events, Main group commands |
|
||||
| End of the held prompts | `Hub.promptsHeldUntil`, 30 s after the stored sessions opened ([hub.ts:352](../src/hub.ts#L352), [:379](../src/hub.ts#L379)) | `Hub.open` | `Session.deliver` |
|
||||
| Prompts in delivery | `Session.delivery`, a promise chain in arrival order ([hub.ts:60](../src/hub.ts#L60)) | `onMessage` | `deliver` |
|
||||
| Actions of a session | `Session.actions`, numbered from 1 per session group ([hub.ts:45](../src/hub.ts#L45), [:75](../src/hub.ts#L75)) | tools, `permission`, `requestMode` | `Control`, `busy` |
|
||||
| Pushed prompts | `Session.pushed`, at most 20, each kept until it is matched by a turn's prompt. An entry is marked `quoted` once it is quoted by an answer without a turn record ([hub.ts:50](../src/hub.ts#L50)). | `deliver`, `turnQuote` | `turn`, `turnQuote` |
|
||||
@@ -975,7 +976,7 @@ Chat database custom data is in the core `_hub` unless noted:
|
||||
| Item | Entity | Value | Written by | Read by |
|
||||
|---|---|---|---|---|
|
||||
| Main group marker | Main group | `{simplexMcpMain: true}` | [`createMainGroup`](../src/main-group.ts#L195-L205) | [`findMainGroup`](../src/main-group.ts#L185-L188) |
|
||||
| Session group | group of session N | `{simplexMcpSession: {session: N, pending?: [{connId, at}], mode?}}`, where `mode` is the approved mode | [`createSessionGroup`](../src/hub.ts#L477-L489), [`setMode`](../src/hub.ts#L319-L322), [`savePending`](../src/hub.ts#L335-L339), [`claimPending`](../src/hub.ts#L162-L167) | [`storedGroup`](../src/hub.ts#L470-L475), [`Session` constructor](../src/hub.ts#L75), [`claimPending`](../src/hub.ts#L162-L167) |
|
||||
| Session group | group of session N | `{simplexMcpSession: {session: N, pending?: [{connId, at}], mode?}}`, where `mode` is the approved mode | [`createSessionGroup`](../src/hub.ts#L478-L490), [`setMode`](../src/hub.ts#L320-L323), [`savePending`](../src/hub.ts#L336-L340), [`claimPending`](../src/hub.ts#L162-L167) | [`storedGroup`](../src/hub.ts#L471-L476), [`Session` constructor](../src/hub.ts#L75), [`claimPending`](../src/hub.ts#L162-L167) |
|
||||
| Action counter | group of session N | `{simplexMcp: {control: true, nextAction}}`, merged with the other keys | [`saveCounter`, `saveData`](../src/control.ts#L172-L184) | [`Session` constructor](../src/hub.ts#L75) |
|
||||
| Chat owner | contact or group of a peer | `{...other keys, simplexMcpOwner: {session: ID}}` | [`claim`](../src/tools.ts#L581-L585), [`giveChat`](../src/tools.ts#L568-L571) | [`owns`](../src/tools.ts#L577-L579) |
|
||||
| Standing approvals | contact or group of a peer | as in [3.2](#32-chat-database-custom-data) | `Control` of the owning session's group | the same |
|
||||
@@ -994,16 +995,16 @@ Files:
|
||||
| `ROOT/service.sock` | the socket | `listen` ([socket.ts:40-43](../src/socket.ts#L40-L43)) | clients |
|
||||
| `ROOT/service.log` | the service's stdout and stderr, emptied over 10 MB at a spawn and every hour | `spawnService` ([client.ts:71-79](../src/client.ts#L71-L79)), [`trimLog`](../src/files.ts#L91-L94) | people |
|
||||
| `ROOT/_hub/`, `ROOT/_user/` | databases and `tmp/` of the profiles `Claude` and `User` | [`openCore`](../src/core.ts#L19-L35) | the cores |
|
||||
| `ROOT/_sessions/ID/session.json` | `{number, name, project, created, group?, aliases?, model?, effort?, hostDeclined?}`, 0600, replaced whole through `session.json.tmp` | `openAgent`, `rename`, `alias`, `Hub.session`, `declineHost`, `store` ([service.ts:392-402](../src/service.ts#L392-L402), [:297-302](../src/service.ts#L297-L302), [:290-295](../src/service.ts#L290-L295), [hub.ts:416](../src/hub.ts#L416), [:324-333](../src/hub.ts#L324-L333)) | `Service` constructor, `resolve`, `Hub.session`, `alias`, `store` |
|
||||
| `ROOT/_sessions/ID/files/` | downloads of the session's chats as in [3.3](#33-files). The files of the prompts from the group are in `group/`. `sent/` is deleted when the session opens. | the core ([hub.ts:250-258](../src/hub.ts#L250-L258), [:413](../src/hub.ts#L413)) | tools, Claude |
|
||||
| `ROOT/_sessions/ID/session.json` | `{number, name, project, created, group?, aliases?, model?, effort?, hostDeclined?}`, 0600, replaced whole through `session.json.tmp` | `openAgent`, `rename`, `alias`, `Hub.session`, `declineHost`, `store` ([service.ts:392-402](../src/service.ts#L392-L402), [:297-302](../src/service.ts#L297-L302), [:290-295](../src/service.ts#L290-L295), [hub.ts:417](../src/hub.ts#L417), [:325-334](../src/hub.ts#L325-L334)) | `Service` constructor, `resolve`, `Hub.session`, `alias`, `store` |
|
||||
| `ROOT/_sessions/ID/files/` | downloads of the session's chats as in [3.3](#33-files). The files of the prompts from the group are in `group/`. `sent/` is deleted when the session opens. | the core ([hub.ts:251-259](../src/hub.ts#L251-L259), [:414](../src/hub.ts#L414)) | tools, Claude |
|
||||
|
||||
### 8.4 Process lifecycle
|
||||
|
||||
#### Session start
|
||||
|
||||
1. The SessionStart hook checks Node.js 22, reads the options, starts the service when it is not running, and sends `POST /title` with the session ID, `CLAUDE_PID`, its start time `at`, title, project folder, model and options ([hook.ts:58-77](../src/hook.ts#L58-L77)). In a run that is not interactive, the hook returns `{}`. When the run is not interactive only because `CLAUDE_CODE_SESSION_ATTENDED` is `0`, the hook first sends `POST /title` with `unattended`. Then the service refuses `/session` from that `CLAUDE_PID` with 403 for 10 s ([flow 30](flows.md#30-a-run-that-is-not-interactive)).
|
||||
2. `/title` resolves the ID to a session as in [API 4.6](api.md#46-socket-protocol). So `/clear`, `/resume` and `--continue` keep the session of the running Claude Code process. The service gives an alias only to an ID without `session.json`. For a new ID from a process without a known session, `/title` replies first, and then waits up to 10 s for the server of that process to register. `/title` then opens the session from `session.json`, or with a new number and the name from the title or the folder. `Hub.session` finds the group of `session.json` or creates one. It adds `User`, invites the Main group's owners and loads the group's `Control` ([service.ts:218-262](../src/service.ts#L218-L262), [:392-402](../src/service.ts#L392-L402), [hub.ts:406-424](../src/hub.ts#L406-L424)).
|
||||
3. At a new title, the service renames the group and `session.json`. The model, when Claude Code passes it, is written to the group's short description with the hook's `at`, so a model of a hook that started later stays ([service.ts:260-261](../src/service.ts#L260-L261)). The Stop hook of each turn sends the model of its answer from the transcript. So the model is shown in the short description from the first answer, even when the SessionStart hook has none ([hook.ts:95](../src/hook.ts#L95), [:114-122](../src/hook.ts#L114-L122)).
|
||||
1. The SessionStart hook checks Node.js 22, reads the options, starts the service when it is not running, and sends `POST /title` with the session ID, `CLAUDE_PID`, its start time `at`, title, project folder, model and options ([hook.ts:81-100](../src/hook.ts#L81-L100)). In a run that is not interactive, the hook returns `{}`. When the run is not interactive only because `CLAUDE_CODE_SESSION_ATTENDED` is `0`, the hook first sends `POST /title` with `unattended`. Then the service refuses `/session` from that `CLAUDE_PID` with 403 for 10 s ([flow 30](flows.md#30-a-run-that-is-not-interactive)).
|
||||
2. `/title` resolves the ID to a session as in [API 4.6](api.md#46-socket-protocol). So `/clear`, `/resume` and `--continue` keep the session of the running Claude Code process. The service gives an alias only to an ID without `session.json`. For a new ID from a process without a known session, `/title` replies first, and then waits up to 10 s for the server of that process to register. `/title` then opens the session from `session.json`, or with a new number and the name from the title or the folder. `Hub.session` finds the group of `session.json` or creates one. It adds `User`, invites the Main group's owners and loads the group's `Control` ([service.ts:218-262](../src/service.ts#L218-L262), [:392-402](../src/service.ts#L392-L402), [hub.ts:407-425](../src/hub.ts#L407-L425)).
|
||||
3. At a new title, the service renames the group and `session.json`. The model, when Claude Code passes it, is written to the group's short description with the hook's `at`, so a model of a hook that started later stays ([service.ts:260-261](../src/service.ts#L260-L261)). The Stop hook of each turn sends the model of its answer from the transcript. So the model is shown in the short description from the first answer, even when the SessionStart hook has none ([hook.ts:118](../src/hook.ts#L118), [:137-145](../src/hook.ts#L137-L145)).
|
||||
4. The hook prints the link message while no owner is in the Main group, and `{}` otherwise.
|
||||
5. The session process connects in the background. `/session` resolves its ID, and waits up to 10 s for the title of its process when the ID is new. It then registers the options and the parent process, and requests the mode ([service.ts:201-216](../src/service.ts#L201-L216)). `/attach` sets the session's line writer ([:304-324](../src/service.ts#L304-L324)). When `/attach` ends or the connection fails, the session process connects again, except after a `ProtocolError` or a 403 of `/session` ([session.ts:88-112](../src/session.ts#L88-L112)).
|
||||
|
||||
@@ -1030,29 +1031,29 @@ ensureService(VERSION): client.ts:32
|
||||
- Otherwise the ready line is `error: Another service uses ROOT (PID N). If no service runs, remove ROOT/service.lock.`, and the process exits with code 1.
|
||||
2. The stored sessions are read with their aliases, and the next number is set ([service.ts:87-91](../src/service.ts#L87-L91)).
|
||||
3. The service listens on the socket before the hub opens, and requests wait for the hub ([service.ts:97-98](../src/service.ts#L97-L98), [:163-168](../src/service.ts#L163-L168)).
|
||||
4. The service reads the options in `openHub` ([service.ts:126-129](../src/service.ts#L126-L129)). `Hub.open` then opens the core `_hub` with profile `Claude`, and finds the Main group by its marker or creates it. It runs `MainGroup.load` and `start`, with a link while no owner is in the Main group. The core `_user` opens, and connects to `Claude` at the first start. A `Session` opens for each stored session, prompts are held for 30 s, and events are dispatched ([hub.ts:367-385](../src/hub.ts#L367-L385)).
|
||||
4. The service reads the options in `openHub` ([service.ts:126-129](../src/service.ts#L126-L129)). `Hub.open` then opens the core `_hub` with profile `Claude`, and finds the Main group by its marker or creates it. It runs `MainGroup.load` and `start`, with a link while no owner is in the Main group. The core `_user` opens, and connects to `Claude` at the first start. A `Session` opens for each stored session, prompts are held for 30 s, and events are dispatched ([hub.ts:368-386](../src/hub.ts#L368-L386)).
|
||||
5. When the hub fails to open, the listener closes and the lock is released. The service answers the requests that waited with status 500 ([service.ts:99-118](../src/service.ts#L99-L118)).
|
||||
6. The stop timer and the hourly log trim start. The titles held at the last stop are read from `ROOT/titles.json` and taken as new `/title` requests. The service logs `SimpleX MCP service VERSION, data folder ROOT` and writes the ready line `ready` ([service.ts:105-113](../src/service.ts#L105-L113), [:444-445](../src/service.ts#L444-L445)).
|
||||
|
||||
#### Event dispatch
|
||||
|
||||
After a stop, `Hub.onEvent` ignores events ([hub.ts:491-521](../src/hub.ts#L491-L521)). Otherwise it runs `expireDue` of every session first, and then dispatches the event:
|
||||
After a stop, `Hub.onEvent` ignores events ([hub.ts:492-522](../src/hub.ts#L492-L522)). Otherwise it runs `expireDue` of every session first, and then dispatches the event:
|
||||
|
||||
| Event | Condition | Handler |
|
||||
|---|---|---|
|
||||
| `newChatItems` | item of the Main group | [`MainGroup.onMessage`](../src/main-group.ts#L83) |
|
||||
| `newChatItems` | item of a session group | [`Session.onMessage`](../src/hub.ts#L153) |
|
||||
| `rcvFileComplete`, `rcvFileError` | | [`Session.fileDone`](../src/hub.ts#L209) of every session |
|
||||
| `rcvFileComplete`, `rcvFileError` | | [`Session.fileDone`](../src/hub.ts#L210) of every session |
|
||||
| `contactConnected`, `userJoinedGroup` | a connection ID | [`Session.claimPending`](../src/hub.ts#L162) of every session |
|
||||
| any event | | [`AgentTools.onEvent`](../src/tools.ts#L665) of every session |
|
||||
| `sndFileError` | a chat of the session, or its group | [`Control.fileNotSent`](../src/control.ts#L205) |
|
||||
| membership events | of the Main group | [`MainGroup.onEvent`](../src/main-group.ts#L95), queued in the Main group and not awaited by the event loop. It posts the statement of trust at a join ([flow 28](flows.md#28-a-member-joins-the-main-group-and-a-sessions-group-and-a-person-is-added-to-it)). |
|
||||
| membership events | of a session group | [`Control.onEvent`](../src/control.ts#L228), then [`Session.announceRights`](../src/hub.ts#L220) and [`Session.askMode`](../src/hub.ts#L140), queued |
|
||||
| membership events | of a session group | [`Control.onEvent`](../src/control.ts#L228), then [`Session.announceRights`](../src/hub.ts#L221) and [`Session.askMode`](../src/hub.ts#L140), queued |
|
||||
|
||||
#### Attach, idle close and idle stop
|
||||
|
||||
- The service cancels the session's idle timer at each attachment. When the last attachment ends, the service records the time, clears the line writer, ends the pending permissions and starts the timer ([service.ts:304-324](../src/service.ts#L304-L324)).
|
||||
- After 10 minutes, the idle timer closes the entry when no call of the session runs and none of its actions is in memory. Otherwise the timer starts again ([service.ts:404-414](../src/service.ts#L404-L414)). The hub keeps the `Session` of a closed session, so Claude still answers `/list` and `/revoke` in its group ([hub.ts:406-411](../src/hub.ts#L406-L411)).
|
||||
- After 10 minutes, the idle timer closes the entry when no call of the session runs and none of its actions is in memory. Otherwise the timer starts again ([service.ts:404-414](../src/service.ts#L404-L414)). The hub keeps the `Session` of a closed session, so Claude still answers `/list` and `/revoke` in its group ([hub.ts:407-412](../src/hub.ts#L407-L412)).
|
||||
- When no entry remains, the stop timer stops the service after 10 minutes. The timer is cleared when a new entry opens ([service.ts:416-422](../src/service.ts#L416-L422), [:362](../src/service.ts#L362)).
|
||||
|
||||
#### Stop
|
||||
@@ -1060,25 +1061,25 @@ After a stop, `Hub.onEvent` ignores events ([hub.ts:491-521](../src/hub.ts#L491-
|
||||
On `SIGINT`, `SIGTERM`, `POST /stop` or the stop timer ([service.ts:177-199](../src/service.ts#L177-L199)):
|
||||
|
||||
1. Timers are cleared, the held titles are saved in `ROOT/titles.json`, the listener closes, and open streams are destroyed.
|
||||
2. `Hub.stop` stops the actions of every session, and edits their cards to `Cancelled: the server stopped.` It awaits the queued group events, and gives the cancelled cards 10 s to be sent. Then the download checks stop, and the cores `_user` and `_hub` close ([hub.ts:458-468](../src/hub.ts#L458-L468)).
|
||||
2. `Hub.stop` stops the actions of every session, and edits their cards to `Cancelled: the server stopped.` It awaits the queued group events, and gives the cancelled cards 10 s to be sent. Then the download checks stop, and the cores `_user` and `_hub` close ([hub.ts:459-469](../src/hub.ts#L459-L469)).
|
||||
3. The service logs `Cancelled K action(s).`, releases the lock and logs `Stopped.` The process exits after the `/stop` reply is sent, or after its client disconnects before the reply is written.
|
||||
|
||||
### 8.5 Approval model
|
||||
|
||||
| Rule | Code |
|
||||
|---|---|
|
||||
| Rights in a session group are set by the member's role there, however the member joined. An approver is an active member other than Claude and `User`, with the role `admin` or `owner`. Approvals and tool-use decisions are accepted only from approvers. | [hub.ts:311-317](../src/hub.ts#L311-L317), [control.ts:43](../src/control.ts#L43), [:580-582](../src/control.ts#L580-L582), [:589-598](../src/control.ts#L589-L598) |
|
||||
| Prompts are accepted from every member except `User`, and the group's `/` commands only from approvers. The other members get one reply to each one-line `/` text. | [hub.ts:153-160](../src/hub.ts#L153-L160), [:229-232](../src/hub.ts#L229-L232), [:307-313](../src/hub.ts#L307-L313) |
|
||||
| With `/join N`, a member of the Main group is invited as `admin`, and an owner of the Main group as `owner`. Owners invited at a session start or at an owner's join get the role `owner`. | [hub.ts:439](../src/hub.ts#L439), [:421](../src/hub.ts#L421), [:450](../src/hub.ts#L450) |
|
||||
| Rights in a session group are set by the member's role there, however the member joined. An approver is an active member other than Claude and `User`, with the role `admin` or `owner`. Approvals and tool-use decisions are accepted only from approvers. | [hub.ts:312-318](../src/hub.ts#L312-L318), [control.ts:43](../src/control.ts#L43), [:580-582](../src/control.ts#L580-L582), [:589-598](../src/control.ts#L589-L598) |
|
||||
| Prompts are accepted from every member except `User`, and the group's `/` commands only from approvers. The other members get one reply to each one-line `/` text. | [hub.ts:153-160](../src/hub.ts#L153-L160), [:230-233](../src/hub.ts#L230-L233), [:308-314](../src/hub.ts#L308-L314) |
|
||||
| With `/join N`, a member of the Main group is invited as `admin`, and an owner of the Main group as `owner`. Owners invited at a session start or at an owner's join get the role `owner`. | [hub.ts:440](../src/hub.ts#L440), [:422](../src/hub.ts#L422), [:451](../src/hub.ts#L451) |
|
||||
| With `/observer #G ID`, the sender sets the role `observer` of a current member. The sender's role must be admin or owner, and not below the member's role, as SimpleX requires. For a member with status `pending_approval` or `pending_review`, Claude replies `NAME's role can't be changed.` For a member who is neither current nor pending, such as an invited member who has not joined, the reply is `No member ID in this group.` An observer neither prompts nor approves. From the reply on, the standing approvals that the observer gave are not used while that member is not an admin or owner. | [control.ts:375-387](../src/control.ts#L375-L387), [:880-882](../src/control.ts#L880-L882), [:167-170](../src/control.ts#L167-L170), [tools.ts:1549-1551](../src/tools.ts#L1549-L1551) |
|
||||
| A new action of a session is refused while its group has no approver | [control.ts:156-157](../src/control.ts#L156-L157) |
|
||||
| Changes of membership or role in the Main group, and its replacement by a reset of the owners, leave the session groups as they are | [main-group.ts:117-132](../src/main-group.ts#L117-L132), [:99-109](../src/main-group.ts#L99-L109) |
|
||||
| Everyone in the Main group is trusted with all sessions. This is stated in the group's short description and welcome message, set when the group is created, and in Claude's post at each join. In a session group, Claude posts the member's rights at each join and each role change, with the `/observer` command only for a role that can send, other than owner. The observer's rights are stated in Claude's reply to `/observer`. | [main-group.ts:16-18](../src/main-group.ts#L16-L18), [:195-205](../src/main-group.ts#L195-L205), [:127-128](../src/main-group.ts#L127-L128), [hub.ts:220-227](../src/hub.ts#L220-L227), [control.ts:386](../src/control.ts#L386), [:888-891](../src/control.ts#L888-L891) |
|
||||
| Everyone in the Main group is trusted with all sessions. This is stated in the group's short description and welcome message, set when the group is created, and in Claude's post at each join. In a session group, Claude posts the member's rights at each join and each role change, with the `/observer` command only for a role that can send, other than owner. The observer's rights are stated in Claude's reply to `/observer`. | [main-group.ts:16-18](../src/main-group.ts#L16-L18), [:195-205](../src/main-group.ts#L195-L205), [:127-128](../src/main-group.ts#L127-L128), [hub.ts:221-228](../src/hub.ts#L221-L228), [control.ts:386](../src/control.ts#L386), [:888-891](../src/control.ts#L888-L891) |
|
||||
| A file of `reply` is sent at once, in both modes. It can be refused by the group's preference for files and media, which owners set and the core enforces. A post of Claude or `User` in a session group, when refused by a group preference, is replaced by Claude's post with the preference's name, and is never dropped without one ([tools.ts:1607-1614](../src/tools.ts#L1607-L1614)). Claude updates a group's profile from its current profile in the chat database, and changes only its own fields, so the owners' preferences are kept. | [tools.ts:713-730](../src/tools.ts#L713-L730), [hub.ts:93](../src/hub.ts#L93), [control.ts:115-140](../src/control.ts#L115-L140), [:632-640](../src/control.ts#L632-L640), [main-group.ts:57-66](../src/main-group.ts#L57-L66) |
|
||||
| The first human who joins the Main group while it has no owner becomes an owner, and the link is deleted | [main-group.ts:122](../src/main-group.ts#L122), [:134-140](../src/main-group.ts#L134-L140) |
|
||||
| A session runs in mode `host` after an approver approves its `mode` card. The card is posted once an approver is in the group. After a rejection, the card is posted again only after `requests`. `requests` applies at once, and the hub ends a pending `mode` card. The mode is kept in the session group's custom data. | [hub.ts:132-151](../src/hub.ts#L132-L151), [:324-327](../src/hub.ts#L324-L327), [:518](../src/hub.ts#L518), [tools.ts:563-564](../src/tools.ts#L563-L564) |
|
||||
| At a reset of the owners from the computer that runs Claude Code, the service replaces the Main group at once, even while owners exist. No owner's approval is needed for `reset-owners` and `POST /reset-owners`. | [hub.ts:402-404](../src/hub.ts#L402-L404), [owner.ts:28-33](../src/owner.ts#L28-L33), [main-group.ts:99-109](../src/main-group.ts#L99-L109) |
|
||||
| A chat without an owner is given to the session that connects it. The owner is set at one of four points: the perform, the connection event of its action, the completion of a pending connection that the session recorded, or a `connect` to the chat as a known chat. The tools of other sessions don't show the chat. With `/give CHAT N`, an approver moves the chat to session N. | [tools.ts:577-585](../src/tools.ts#L577-L585), [:750-755](../src/tools.ts#L750-L755), [:826](../src/tools.ts#L826), [:835](../src/tools.ts#L835), [:893](../src/tools.ts#L893), [hub.ts:162-167](../src/hub.ts#L162-L167), [:504-505](../src/hub.ts#L504-L505), [control.ts:362-373](../src/control.ts#L362-L373) |
|
||||
| A session runs in mode `host` after an approver approves its `mode` card. The card is posted once an approver is in the group. After a rejection, the card is posted again only after `requests`. `requests` applies at once, and the hub ends a pending `mode` card. The mode is kept in the session group's custom data. | [hub.ts:132-151](../src/hub.ts#L132-L151), [:325-328](../src/hub.ts#L325-L328), [:519](../src/hub.ts#L519), [tools.ts:563-564](../src/tools.ts#L563-L564) |
|
||||
| At a reset of the owners from the computer that runs Claude Code, the service replaces the Main group at once, even while owners exist. No owner's approval is needed for `reset-owners` and `POST /reset-owners`. | [hub.ts:403-405](../src/hub.ts#L403-L405), [owner.ts:28-33](../src/owner.ts#L28-L33), [main-group.ts:99-109](../src/main-group.ts#L99-L109) |
|
||||
| A chat without an owner is given to the session that connects it. The owner is set at one of four points: the perform, the connection event of its action, the completion of a pending connection that the session recorded, or a `connect` to the chat as a known chat. The tools of other sessions don't show the chat. With `/give CHAT N`, an approver moves the chat to session N. | [tools.ts:577-585](../src/tools.ts#L577-L585), [:750-755](../src/tools.ts#L750-L755), [:826](../src/tools.ts#L826), [:835](../src/tools.ts#L835), [:893](../src/tools.ts#L893), [hub.ts:162-167](../src/hub.ts#L162-L167), [:505-506](../src/hub.ts#L505-L506), [control.ts:362-373](../src/control.ts#L362-L373) |
|
||||
|
||||
Tool-use state machine, one action of tool `permission` per request:
|
||||
|
||||
@@ -1087,7 +1088,7 @@ Tool-use state machine, one action of tool `permission` per request:
|
||||
| `permission_request` | | `pending`, card posted | [hub.ts:169-170](../src/hub.ts#L169-L170) |
|
||||
| `/approve N` | `pending` | `performing`, `allow` pushed, then `done` | [hub.ts:172-173](../src/hub.ts#L172-L173), [tools.ts:553-566](../src/tools.ts#L553-L566) |
|
||||
| `/reject N` | `pending` | `rejected`, `deny` pushed | [hub.ts:172-173](../src/hub.ts#L172-L173) |
|
||||
| a prompt or an answer of a hook that started after the card's creation, end of the last attachment | `pending` | `expired`, card edited to `Ended.` | [hub.ts:181](../src/hub.ts#L181), [:203-207](../src/hub.ts#L203-L207), [service.ts:321](../src/service.ts#L321), [actions.ts:237-241](../src/actions.ts#L237-L241) |
|
||||
| an answer, or a prompt that is not mid-turn, of a hook that started after the card's creation; end of the last attachment | `pending` | `expired`, card edited to `Ended.` | [hub.ts:181](../src/hub.ts#L181), [:204-208](../src/hub.ts#L204-L208), [service.ts:321](../src/service.ts#L321), [actions.ts:237-241](../src/actions.ts#L237-L241) |
|
||||
| expiry | `pending` | `expired`, card edited to `Expired.` | [actions.ts:302-312](../src/actions.ts#L302-L312) |
|
||||
| `done`, `rejected` or `expired` | | removed from the session's actions | [hub.ts:174-176](../src/hub.ts#L174-L176) |
|
||||
|
||||
@@ -1097,7 +1098,8 @@ stateDiagram-v2
|
||||
pending --> performing: /approve N, allow pushed
|
||||
performing --> done
|
||||
pending --> rejected: /reject N, deny pushed
|
||||
pending --> expired: later prompt or answer, detach: Ended.#59; expiry: Expired.
|
||||
pending --> expired: later answer or prompt that is not mid-turn, last detach, card Ended.
|
||||
pending --> expired: expiry, card Expired.
|
||||
done --> [*]: removed
|
||||
rejected --> [*]: removed
|
||||
expired --> [*]: removed
|
||||
@@ -1111,7 +1113,7 @@ stateDiagram-v2
|
||||
| session to Claude Code | `notifications/claude/channel` `{content, meta: {from, item, file?}}`; `notifications/claude/channel/permission` `{request_id, behavior}` | [session.ts:197-201](../src/session.ts#L197-L201) |
|
||||
| Claude Code to session | `notifications/claude/channel/permission_request` `{request_id, tool_name, description, input_preview}` | [session.ts:58-62](../src/session.ts#L58-L62) |
|
||||
| session to service | `POST /permission` | [session.ts:114-118](../src/session.ts#L114-L118) |
|
||||
| hooks to service | `POST /turn` `{id, pid?, at?, prompt?, typed?, answer?, model?, effort?}`. `pid` is `CLAUDE_PID`, and `at` is the hook's `performance.timeOrigin`. `prompt` and `answer`, the last answer, are cut to 250,000 characters. `typed` of UserPromptSubmit is true when a person typed the prompt. `model` is the new model of PostModelSwitch, or the model of Stop's answer in the transcript. `effort` is the effort level. | [hook.ts:91-192](../src/hook.ts#L91-L192) |
|
||||
| hooks to service | `POST /turn` `{id, pid?, at?, prompt?, typed?, note?, midTurn?, answer?, model?, effort?}`. `pid` is `CLAUDE_PID`, and `at` is the hook's `performance.timeOrigin`. `prompt` and `answer`, the last answer, are cut to 250,000 characters. `typed` of UserPromptSubmit is true when a person typed the prompt. `note` is the line about one of Claude Code's own prompts. `midTurn` is true for a prompt that Claude Code added to a running turn. `model` is the new model of PostModelSwitch, or the model of Stop's answer in the transcript. `effort` is the effort level. | [hook.ts:114-309](../src/hook.ts#L114-L309) |
|
||||
|
||||
```
|
||||
on a message m in N: one-line "/" text from a member who is neither an admin, an owner nor User:
|
||||
@@ -1125,15 +1127,18 @@ deliver(m): no attachment: wait for one until 30 s after
|
||||
no attachment now: reply "Session N is not running."
|
||||
else: pushed += (m.text, m.item, now), at most 20; push {prompt}
|
||||
on /turn at time at, before any await:
|
||||
prompt p or answer a: end pending permissions created before at
|
||||
prompt p not midTurn, or answer a: end pending permissions created before at
|
||||
answer a, also empty: earlier = turns with at below at; quoted = the item of the newest earlier,
|
||||
or the oldest pushed not quoted, marked quoted, when earlier is empty; earlier leave turns
|
||||
answeredAt = max(answeredAt, at)
|
||||
prompt p: matched = pushed entries in this plugin's channel tags of p, or equal to p and pushed in the last 60 s
|
||||
at not below answeredAt: turns += (at, the oldest matched or null)
|
||||
at not below answeredAt, and not midTurn or matched not empty:
|
||||
turns += (at, the oldest matched or null)
|
||||
matched leave pushed
|
||||
model or effort: skipped when at is older than modelAt or effortAt, the at of the value taken last
|
||||
else: modelAt or effortAt = at; a changed value: description, session.json
|
||||
on /turn note: Claude posts note, without a quote; refused for NAME: Claude posts
|
||||
"A note on Claude Code's prompt was not posted: " and the preference's text
|
||||
on /turn prompt p: typed not false, nothing matched, p not blank, not only this plugin's channel tags,
|
||||
not a one-line "/" command:
|
||||
User posts parts(p) in the group marked N
|
||||
@@ -1153,21 +1158,21 @@ sequenceDiagram
|
||||
Note over D: a later answer with at 4 quotes prompt N+1
|
||||
```
|
||||
|
||||
Sources: [hub.ts:153-207](../src/hub.ts#L153-L207), [:229-301](../src/hub.ts#L229-L301), [:531-548](../src/hub.ts#L531-L548).
|
||||
Sources: [hub.ts:153-208](../src/hub.ts#L153-L208), [:230-302](../src/hub.ts#L230-L302), [:532-549](../src/hub.ts#L532-L549).
|
||||
|
||||
### 8.7 Security boundaries
|
||||
|
||||
| Rule | Code |
|
||||
|---|---|
|
||||
| The socket is in ROOT, mode 0700. For a path over 103 bytes, the socket is `TMP/simplex-mcp-HASH.sock`, and on Windows it is a named pipe. The service accepts a request only with the token, compared with `timingSafeEqual`. | [socket.ts:19-25](../src/socket.ts#L19-L25), [files.ts:74-79](../src/files.ts#L74-L79) |
|
||||
| The Main group link is shown only in the hook's `systemMessage`, and on a terminal with `link`. In tool results, refusals and other output, the command is named instead. Of the socket's routes, only `/title`, `/link` and `/reset-owners` return a Main group link. `/reset-owners` returns the link of the new group. | [hook.ts:71-73](../src/hook.ts#L71-L73), [owner.ts:7-15](../src/owner.ts#L7-L15), [control.ts:39](../src/control.ts#L39), [service.ts:154-155](../src/service.ts#L154-L155), [:215](../src/service.ts#L215), [:426](../src/service.ts#L426), [hub.ts:402-404](../src/hub.ts#L402-L404) |
|
||||
| The Main group link is shown only in the hook's `systemMessage`, and on a terminal with `link`. In tool results, refusals and other output, the command is named instead. Of the socket's routes, only `/title`, `/link` and `/reset-owners` return a Main group link. `/reset-owners` returns the link of the new group. | [hook.ts:94-96](../src/hook.ts#L94-L96), [owner.ts:7-15](../src/owner.ts#L7-L15), [control.ts:39](../src/control.ts#L39), [service.ts:154-155](../src/service.ts#L154-L155), [:215](../src/service.ts#L215), [:426](../src/service.ts#L426), [hub.ts:403-405](../src/hub.ts#L403-L405) |
|
||||
| `reset-owners` shows the new link only on a terminal | [owner.ts:17-20](../src/owner.ts#L17-L20), [:28-33](../src/owner.ts#L28-L33) |
|
||||
| The plugin runs its own `dist/cli.js`. Node.js loads its modules, bundled in the package, from the plugin's folder, so they can't be replaced by the `node_modules` of a project. | [.mcp.json:5](../.mcp.json#L5), [hooks.json:3-7](../hooks/hooks.json#L3-L7), [package.json:35](../package.json#L35) |
|
||||
| The service gets only the environment variables of `serviceVariables` | [client.ts:13](../src/client.ts#L13), [:78](../src/client.ts#L78) |
|
||||
| `send` and `reply` refuse the files of ROOT except `files/` of the session's own folder | [tools.ts:996-1001](../src/tools.ts#L996-L1001), [hub.ts:90-91](../src/hub.ts#L90-L91) |
|
||||
| `User`'s messages are neither prompts nor commands. `Session.prompt` and `Control.onMessage` drop the messages of the member of the hub's contact marked `simplexMcpUser`, which is read at the hub's start. `User` joins only the groups to which it is invited by its `Claude` contact. | [hub.ts:230](../src/hub.ts#L230), [:315-317](../src/hub.ts#L315-L317), [:376](../src/hub.ts#L376), [control.ts:221](../src/control.ts#L221), [user.ts:50-57](../src/user.ts#L50-L57), [:60-62](../src/user.ts#L60-L62) |
|
||||
| `User`'s messages are neither prompts nor commands. `Session.prompt` and `Control.onMessage` drop the messages of the member of the hub's contact marked `simplexMcpUser`, which is read at the hub's start. `User` joins only the groups to which it is invited by its `Claude` contact. | [hub.ts:231](../src/hub.ts#L231), [:316-318](../src/hub.ts#L316-L318), [:377](../src/hub.ts#L377), [control.ts:221](../src/control.ts#L221), [user.ts:50-57](../src/user.ts#L50-L57), [:60-62](../src/user.ts#L60-L62) |
|
||||
| The hub's own groups and the `User` contact have no owner key, so the tools of every session leave them out | [tools.ts:577-579](../src/tools.ts#L577-L579), [:1284-1292](../src/tools.ts#L1284-L1292) |
|
||||
| The approved mode is kept in the chat database, not in a file of ROOT | [hub.ts:75](../src/hub.ts#L75), [:319-322](../src/hub.ts#L319-L322), [files.ts:11-21](../src/files.ts#L11-L21) |
|
||||
| The approved mode is kept in the chat database, not in a file of ROOT | [hub.ts:75](../src/hub.ts#L75), [:320-323](../src/hub.ts#L320-L323), [files.ts:11-21](../src/files.ts#L11-L21) |
|
||||
| These rules hold against Claude's tools, but not against a shell running as the same user. Such a shell can read ROOT, with the token and the chat databases, and send requests to the service. | |
|
||||
|
||||
### 8.8 Limits
|
||||
@@ -1185,9 +1190,10 @@ Sources: [hub.ts:153-207](../src/hub.ts#L153-L207), [:229-301](../src/hub.ts#L22
|
||||
| record of a pending connection | 1 day | [hub.ts:25](../src/hub.ts#L25) |
|
||||
| wait of a session server for the title of its process, the time a detached session server's process is kept, and the mark of an unattended run's process, removed at a later mark | 10 s | [service.ts:19](../src/service.ts#L19), [:237-243](../src/service.ts#L237-L243) |
|
||||
| attempts of a turn the service refuses with status 409 | 15, 1 s apart | [hook.ts:13-15](../src/hook.ts#L13-L15) |
|
||||
| reads of the transcript for the model of Stop's answer and the origin of a prompt | 20 for the answer and 600 for the prompt, 100 ms apart, each of the last 1 MiB and twice the bytes of the answer or the prompt | [hook.ts:17-20](../src/hook.ts#L17-L20), [:131-152](../src/hook.ts#L131-L152) |
|
||||
| reads of the transcript for the model of Stop's answer and the origin of a prompt | 20 for the answer and 600 for the prompt, 100 ms apart, each of the last 1 MiB and twice the bytes of the answer or the prompt | [hook.ts:17-20](../src/hook.ts#L17-L20), [:153-174](../src/hook.ts#L153-L174) |
|
||||
| length of a note of Claude Code's own prompt | 200 characters, the last one `…` when cut | [hook.ts:22](../src/hook.ts#L22), [:287-290](../src/hook.ts#L287-L290) |
|
||||
| attachment retries of a session server | 1 s, doubled up to 30 s | [session.ts:19-20](../src/session.ts#L19-L20) |
|
||||
| part of an answer or a terminal prompt | one message by `fitsMessage`: 15602 bytes with the 600-byte envelope; 14962 bytes of text without a quote | [hub.ts:531-548](../src/hub.ts#L531-L548), [tools.ts:163-164](../src/tools.ts#L163-L164), [:1575-1578](../src/tools.ts#L1575-L1578) |
|
||||
| part of an answer or a terminal prompt | one message by `fitsMessage`: 15602 bytes with the 600-byte envelope; 14962 bytes of text without a quote | [hub.ts:532-549](../src/hub.ts#L532-L549), [tools.ts:163-164](../src/tools.ts#L163-L164), [:1575-1578](../src/tools.ts#L1575-L1578) |
|
||||
| cancelled cards wait at stop | 10 s | [hub.ts:21](../src/hub.ts#L21) |
|
||||
| `service.log` | emptied over 10 MB, at a spawn and every hour | [files.ts:9](../src/files.ts#L9), [:91-94](../src/files.ts#L91-L94), [service.ts:20](../src/service.ts#L20) |
|
||||
| socket path | 103 bytes: `sun_path` of `sockaddr_un` holds 104 bytes on macOS and 108 on Linux, with the terminating NUL | [files.ts:8](../src/files.ts#L8) |
|
||||
|
||||
@@ -57,6 +57,7 @@ Claude Code plugin ([participants](#claude-code-plugin-flows)):
|
||||
28. [A member joins the Main group and a session's group, and a person is added to it](#28-a-member-joins-the-main-group-and-a-sessions-group-and-a-person-is-added-to-it)
|
||||
29. [`reply`](#29-reply)
|
||||
30. [A run that is not interactive](#30-a-run-that-is-not-interactive)
|
||||
31. [A prompt of Claude Code](#31-a-prompt-of-claude-code)
|
||||
|
||||
---
|
||||
|
||||
@@ -211,7 +212,7 @@ Notes:
|
||||
| other links | `apiConnectPreparedLink(USER, incognito, LINK)` |
|
||||
|
||||
- After a failed prepared connect, the server deletes the prepared chat without notifying ([tools.ts:876-883](../src/tools.ts#L876-L883)).
|
||||
- The connection is matched by `contactConnected` or `userJoinedGroup`: by contact or group ID, or by the pending connection ID ([tools.ts:655-663](../src/tools.ts#L655-L663), [:885-890](../src/tools.ts#L885-L890)). In the plugin, the pending connection ID is also recorded in the session group's custom data. When the connection completes after the call returned, within a day of the record, its chat becomes the session's ([tools.ts:826](../src/tools.ts#L826), [hub.ts:162-167](../src/hub.ts#L162-L167), [:504-505](../src/hub.ts#L504-L505)).
|
||||
- The connection is matched by `contactConnected` or `userJoinedGroup`: by contact or group ID, or by the pending connection ID ([tools.ts:655-663](../src/tools.ts#L655-L663), [:885-890](../src/tools.ts#L885-L890)). In the plugin, the pending connection ID is also recorded in the session group's custom data. When the connection completes after the call returned, within a day of the record, its chat becomes the session's ([tools.ts:826](../src/tools.ts#L826), [hub.ts:162-167](../src/hub.ts#L162-L167), [:505-506](../src/hub.ts#L505-L506)).
|
||||
- In the perform step the server waits for the other side until `startedAt + wait`, at most until `created + 23 h 50 min`, and then reports `connected: false` ([tools.ts:153](../src/tools.ts#L153), [:814](../src/tools.ts#L814), [:840-843](../src/tools.ts#L840-L843)).
|
||||
- Without `message`, the idle time is counted from the connection; with `message`, from the first reply ([tools.ts:897](../src/tools.ts#L897), [messages.ts:327-335](../src/messages.ts#L327-L335)).
|
||||
- For a target the agent is connected to, the result is `status: known` with its chat fields, and no action is created ([tools.ts:737](../src/tools.ts#L737)). In the plugin, the chat becomes the session's when it has no owner ([tools.ts:750-755](../src/tools.ts#L750-L755)).
|
||||
@@ -815,17 +816,17 @@ sequenceDiagram
|
||||
|
||||
Notes:
|
||||
|
||||
- Only the person gets the link. It is passed in the hook's `systemMessage`, and it is in no hook context or tool result ([hook.ts:71-73](../src/hook.ts#L71-L73)).
|
||||
- Only the person gets the link. It is passed in the hook's `systemMessage`, and it is in no hook context or tool result ([hook.ts:94-96](../src/hook.ts#L94-L96)).
|
||||
- The service deletes the preset contact of a new profile, in `_hub` and in `_user` ([core.ts:28](../src/core.ts#L28), [:44-52](../src/core.ts#L44-L52)).
|
||||
- `User` connects only at the first start. At later starts, the service finds the hub's contact marked `simplexMcpUser`, the contact whose connection belongs to the invitation that the hub created. When `User` does not connect within 60 s, the service runs without it, and terminal prompts are not posted ([user.ts:21](../src/user.ts#L21), [:38-48](../src/user.ts#L38-L48), [:60-62](../src/user.ts#L60-L62), [hub.ts:375](../src/hub.ts#L375)).
|
||||
- `User` connects only at the first start. At later starts, the service finds the hub's contact marked `simplexMcpUser`, the contact whose connection belongs to the invitation that the hub created. When `User` does not connect within 60 s, the service runs without it, and terminal prompts are not posted ([user.ts:21](../src/user.ts#L21), [:38-48](../src/user.ts#L38-L48), [:60-62](../src/user.ts#L60-L62), [hub.ts:376](../src/hub.ts#L376)).
|
||||
- At a later start without owners, the service keeps the Main group's link ([main-group.ts:68-76](../src/main-group.ts#L68-L76)).
|
||||
- Owners are invited to the groups of the open sessions when they join the Main group. The groups of closed sessions are joined with `/join N` ([hub.ts:448-452](../src/hub.ts#L448-L452), [:435-446](../src/hub.ts#L435-L446)).
|
||||
- Owners are invited to the groups of the open sessions when they join the Main group. The groups of closed sessions are joined with `/join N` ([hub.ts:449-453](../src/hub.ts#L449-L453), [:436-447](../src/hub.ts#L436-L447)).
|
||||
- The trust given to the Main group's members is stated in the group's short description and welcome message, which Claude sets when it creates the group ([main-group.ts:16-18](../src/main-group.ts#L16-L18), [:195-205](../src/main-group.ts#L195-L205)). Claude also states it in a post at each human's `joinedGroupMember` or `connectedToGroupMember` ([main-group.ts:127-128](../src/main-group.ts#L127-L128)). The joiner is found as in [flow 28](#28-a-member-joins-the-main-group-and-a-sessions-group-and-a-person-is-added-to-it).
|
||||
- Claude changes only the name and the menu of the Main group's profile, and starts each change from the group's current profile. So the short description, the welcome message and the preferences that owners set are kept ([main-group.ts:57-66](../src/main-group.ts#L57-L66), [control.ts:632-640](../src/control.ts#L632-L640)).
|
||||
- At each join other than `User`'s, Claude posts in the session group the rights of the joiner's role. For a role that can send, other than owner, the post ends with the command that makes the joiner an observer ([hub.ts:220-227](../src/hub.ts#L220-L227), [:518](../src/hub.ts#L518)).
|
||||
- The service reads the hub's contact of `User` after `User` opens, so that the sessions recognize `User`'s messages ([hub.ts:376](../src/hub.ts#L376)).
|
||||
- At each join other than `User`'s, Claude posts in the session group the rights of the joiner's role. For a role that can send, other than owner, the post ends with the command that makes the joiner an observer ([hub.ts:221-228](../src/hub.ts#L221-L228), [:519](../src/hub.ts#L519)).
|
||||
- The service reads the hub's contact of `User` after `User` opens, so that the sessions recognize `User`'s messages ([hub.ts:377](../src/hub.ts#L377)).
|
||||
|
||||
Source: [hook.ts:58-77](../src/hook.ts#L58-L77), [client.ts:35-92](../src/client.ts#L35-L92), [service.ts:93-119](../src/service.ts#L93-L119), [:218-262](../src/service.ts#L218-L262), [hub.ts:367-385](../src/hub.ts#L367-L385), [:406-424](../src/hub.ts#L406-L424), [:477-489](../src/hub.ts#L477-L489), [main-group.ts:117-140](../src/main-group.ts#L117-L140), [user.ts:16-57](../src/user.ts#L16-L57).
|
||||
Source: [hook.ts:81-100](../src/hook.ts#L81-L100), [client.ts:35-92](../src/client.ts#L35-L92), [service.ts:93-119](../src/service.ts#L93-L119), [:218-262](../src/service.ts#L218-L262), [hub.ts:368-386](../src/hub.ts#L368-L386), [:407-425](../src/hub.ts#L407-L425), [:478-490](../src/hub.ts#L478-L490), [main-group.ts:117-140](../src/main-group.ts#L117-L140), [user.ts:16-57](../src/user.ts#L16-L57).
|
||||
|
||||
---
|
||||
|
||||
@@ -892,7 +893,7 @@ sequenceDiagram
|
||||
|
||||
Notes:
|
||||
|
||||
- Approvers in the session group are its active members with the role `admin` or `owner`, other than Claude and `User`, however they joined ([hub.ts:311-317](../src/hub.ts#L311-L317), [control.ts:580-582](../src/control.ts#L580-L582)).
|
||||
- Approvers in the session group are its active members with the role `admin` or `owner`, other than Claude and `User`, however they joined ([hub.ts:312-318](../src/hub.ts#L312-L318), [control.ts:580-582](../src/control.ts#L580-L582)).
|
||||
- Without an approver in `#G`, the action is refused with the text of [API 4.4](api.md#44-tool-results-in-the-plugin).
|
||||
- The session's ID is set as the owner of the connected chat ([tools.ts:581-585](../src/tools.ts#L581-L585), [:835](../src/tools.ts#L835)).
|
||||
|
||||
@@ -947,12 +948,12 @@ sequenceDiagram
|
||||
|
||||
Notes:
|
||||
|
||||
- Every message of a member other than `User` is a prompt, however the member joined, except a one-line `/` text. Claude answers a one-line `/` text of a moderator, member or author with `Only admins and owners of this group can send / commands.` From an admin or owner, a one-line `/` text is a command of the group. For one outside the group's requests, such as `/model sonnet`, the reply is `Unknown command.` ([hub.ts:153-160](../src/hub.ts#L153-L160), [:229-232](../src/hub.ts#L229-L232), [:307-313](../src/hub.ts#L307-L313), [control.ts:249](../src/control.ts#L249), [:672-677](../src/control.ts#L672-L677)).
|
||||
- The session handles messages in arrival order. So a prompt is delivered after the file of an earlier prompt. The reply to a one-line `/` text of a moderator, member or author is posted after the earlier prompts ([hub.ts:157](../src/hub.ts#L157), [:159](../src/hub.ts#L159), [:303-305](../src/hub.ts#L303-L305)).
|
||||
- After a service start, a prompt that arrives before its session attaches again is held up to 30 s from the hub's open. So a prompt sent while the service was stopped is still delivered to the session ([hub.ts:234-236](../src/hub.ts#L234-L236), [:378](../src/hub.ts#L378)).
|
||||
- Every message of a member other than `User` is a prompt, however the member joined, except a one-line `/` text. Claude answers a one-line `/` text of a moderator, member or author with `Only admins and owners of this group can send / commands.` From an admin or owner, a one-line `/` text is a command of the group. For one outside the group's requests, such as `/model sonnet`, the reply is `Unknown command.` ([hub.ts:153-160](../src/hub.ts#L153-L160), [:230-233](../src/hub.ts#L230-L233), [:308-314](../src/hub.ts#L308-L314), [control.ts:249](../src/control.ts#L249), [:672-677](../src/control.ts#L672-L677)).
|
||||
- The session handles messages in arrival order. So a prompt is delivered after the file of an earlier prompt. The reply to a one-line `/` text of a moderator, member or author is posted after the earlier prompts ([hub.ts:157](../src/hub.ts#L157), [:159](../src/hub.ts#L159), [:304-306](../src/hub.ts#L304-L306)).
|
||||
- After a service start, a prompt that arrives before its session attaches again is held up to 30 s from the hub's open. So a prompt sent while the service was stopped is still delivered to the session ([hub.ts:235-237](../src/hub.ts#L235-L237), [:379](../src/hub.ts#L379)).
|
||||
- In a session started without the channel flag, Claude Code receives the notification and drops it.
|
||||
|
||||
Source: [hub.ts:153-160](../src/hub.ts#L153-L160), [:229-258](../src/hub.ts#L229-L258), [service.ts:314](../src/service.ts#L314), [session.ts:53-56](../src/session.ts#L53-L56), [:197-201](../src/session.ts#L197-L201).
|
||||
Source: [hub.ts:153-160](../src/hub.ts#L153-L160), [:230-259](../src/hub.ts#L230-L259), [service.ts:314](../src/service.ts#L314), [session.ts:53-56](../src/session.ts#L53-L56), [:197-201](../src/session.ts#L197-L201).
|
||||
|
||||
---
|
||||
|
||||
@@ -978,7 +979,7 @@ sequenceDiagram
|
||||
HK->>D: ensureService, POST /turn {id, pid, at, prompt, typed}
|
||||
D->>N: turn
|
||||
N->>N: end pending permissions created before at
|
||||
N->>N: no pushed prompt matched: turns += (at, null)
|
||||
N->>N: no pushed prompt matched: turns += (at, null), unless at is below answeredAt
|
||||
N->>U: post(N, parts), when typed and not a "/" command
|
||||
U->>O: the prompt in #35;G, from User
|
||||
CC->>CC: turn ends
|
||||
@@ -1002,41 +1003,53 @@ sequenceDiagram
|
||||
|
||||
Notes:
|
||||
|
||||
- `at` is `performance.timeOrigin` of the hook process, the hook's start time. In an answer, the hub quotes the newest prompt record whose hook started before the answer's hook. This record is quoted also when the request of the next prompt arrives first, and while the answer's request waits for the short description ([hook.ts:91](../src/hook.ts#L91), [hub.ts:180-186](../src/hub.ts#L180-L186), [:266-275](../src/hub.ts#L266-L275)).
|
||||
- `at` is `performance.timeOrigin` of the hook process, the hook's start time. In an answer, the hub quotes the newest prompt record whose hook started before the answer's hook. This record is quoted also when the request of the next prompt arrives first, and while the answer's request waits for the short description ([hook.ts:114](../src/hook.ts#L114), [hub.ts:180-186](../src/hub.ts#L180-L186), [:267-276](../src/hub.ts#L267-L276)).
|
||||
- `User` does not post a prompt that came from the group. The hub matches a pushed prompt to the terminal prompt in either case:
|
||||
- its item and its text are in a `<channel source="plugin:simplex:simplex" ... item="I" ...>` tag of the prompt;
|
||||
- its text is equal to the raw prompt, and it was pushed in the last 60 s.
|
||||
|
||||
Matched prompts are removed from the pushed prompts, and the oldest of them becomes the item of the turn record ([hub.ts:22](../src/hub.ts#L22), [:27](../src/hub.ts#L27), [:184-186](../src/hub.ts#L184-L186), [:297-301](../src/hub.ts#L297-L301)).
|
||||
- For an answer without an earlier turn record, the hub quotes the oldest pushed prompt not quoted yet, and marks it quoted. That prompt stays pushed, so the hub still matches it to a prompt request handled after the Stop request, and `User` does not post it ([hub.ts:268-272](../src/hub.ts#L268-L272)).
|
||||
- For an empty answer, the hub removes the turn record as for any other answer, but posts nothing ([hub.ts:182](../src/hub.ts#L182), [:196](../src/hub.ts#L196)).
|
||||
Matched prompts are removed from the pushed prompts, and the oldest of them becomes the item of the turn record ([hub.ts:22](../src/hub.ts#L22), [:27](../src/hub.ts#L27), [:184-186](../src/hub.ts#L184-L186), [:298-302](../src/hub.ts#L298-L302)).
|
||||
- For an answer without an earlier turn record, the hub quotes the oldest pushed prompt not quoted yet, and marks it quoted. That prompt stays pushed, so the hub still matches it to a prompt request handled after the Stop request, and `User` does not post it ([hub.ts:269-273](../src/hub.ts#L269-L273)).
|
||||
- For an empty answer, the hub removes the turn record as for any other answer, but posts nothing ([hub.ts:182](../src/hub.ts#L182), [:197](../src/hub.ts#L197)).
|
||||
- No turn record is made for a prompt request whose hook started before an answer that was already handled. So that prompt is not quoted in a later answer ([hub.ts:183](../src/hub.ts#L183), [:185](../src/hub.ts#L185)).
|
||||
- The UserPromptSubmit hook runs for every prompt of the session, also for Claude Code's own prompts. It marks a prompt as typed only when the prompt's entry in the transcript has the origin `human`. Task notifications, messages of other sessions and channel prompts have other origins. The hook finds the entry by `prompt_id` as `promptId`, or, without `prompt_id`, by the prompt's text. Claude Code writes the entry only after the synchronous UserPromptSubmit hooks end, such as a slow hook in the user's settings, and it creates the transcript file with the session's first entry. So the hook reads the transcript up to 600 times, 100 ms apart, and it treats a missing file as empty. When the entry is not written within these reads, the prompt is not typed. The hub keeps the turn record of every prompt, so quotes stay right ([hook.ts:18-19](../src/hook.ts#L18-L19), [:96](../src/hook.ts#L96), [:124-139](../src/hook.ts#L124-L139), [:165-173](../src/hook.ts#L165-L173)).
|
||||
- These terminal prompts are not posted ([hub.ts:195](../src/hub.ts#L195)):
|
||||
- The UserPromptSubmit hook runs for every prompt of the session that queries the model, also for Claude Code's own prompts. It marks a prompt as typed only when the prompt's record in the transcript has the origin `human`. Task notifications, messages of other sessions and channel prompts have other origins. The record is the newest one whose text is the prompt: a user entry, or a `queued_command` attachment of a prompt that Claude Code added to a running turn. It is the entry with `prompt_id` as `promptId`, or a record after the first entry with that ID, tool results included, so a long turn whose first entry is out of the tail is found by its tool results. While a `queue-operation` `enqueue` entry with the prompt's text follows the record, the hook waits: the prompt is a later one with that text, still queued. Claude Code writes the entry only after the synchronous UserPromptSubmit hooks end, such as a slow hook in the user's settings, and it creates the transcript file with the session's first entry. So the hook reads the transcript up to 600 times, 100 ms apart, and it treats a missing file as empty. Until the entry with `prompt_id` is in the tail, the hook waits for it; at the last read it takes any record with the prompt's text, and without `prompt_id` it does so at once. Claude Code runs the hook of a person's prompt when it is submitted, and of its own prompts only when they are taken. So at the last read, the hook classifies a record still followed by such an `enqueue` entry by the record, and marks a typed one mid-turn: the queued prompt is the typed prompt itself, or a later prompt with the text of Claude Code's own prompt, as a repeated monitor event. When no record is written within the reads, an `enqueue` entry with the prompt's text after the entry with `prompt_id`, or anywhere without that entry, makes the prompt typed and mid-turn. Otherwise the prompt is typed when an entry with `prompt_id` has the origin `human` ([hook.ts:18-19](../src/hook.ts#L18-L19), [:119](../src/hook.ts#L119), [:147-161](../src/hook.ts#L147-L161), [:187-222](../src/hook.ts#L187-L222)).
|
||||
- Claude Code adds a prompt that arrives during a turn to that turn, and gives its hook the running turn's prompt ID. The hook sends `midTurn: true` for a prompt whose record is not the entry with `prompt_id`. A mid-turn prompt ends no tool-use card. A prompt adds a turn record only when its hook started no earlier than the hook of the last answer handled (`answeredAt`), and a mid-turn prompt only when it also matched a pushed prompt. So the answer of the turn quotes the turn's prompt, or an owner's prompt added to the turn ([hub.ts:181](../src/hub.ts#L181), [:185](../src/hub.ts#L185)).
|
||||
- The hook sends `note`, a line about one of Claude Code's own prompts, and Claude posts it without a quote ([hook.ts:217-290](../src/hook.ts#L217-L290), [hub.ts:195](../src/hub.ts#L195)). A typed prompt, a channel prompt and a teammate's prompt of idle notifications only have no note, nor has another record without origin that is not scheduled. The line is cut to 200 characters and ends with `…`. A note that a group preference refuses is replaced by `A note on Claude Code's prompt was not posted: ` and the preference's text.
|
||||
|
||||
| Kind | Record | Line |
|
||||
|---|---|---|
|
||||
| task notification | origin `task-notification`, or a `queued_command` attachment without origin whose `commandMode` is `task-notification` | an emoji, the first line of `<summary>`, and `: ` with the first line of `<event>` when there is one, with entities decoded. The emoji is ✅ for `<status>` completed, ❌ for failed, ⏹️ for stopped or killed, and without a status 📡 with an event or 🔔 without. Without a `<task-notification>` block: 🔔 and the first line |
|
||||
| message of another session | origin `peer` | `✉️ Message from NAME: ` and the first line of `body` |
|
||||
| message of a teammate | no origin, a `<teammate-message teammate_id="NAME" ...>` tag after `Another Claude session sent a message` | `✉️ Message from NAME: ` and the tag's `summary`, or the first line of the message, from the first tag that is not an idle notification; nothing for idle notifications only |
|
||||
| subagent report | origin `peer` with `handback` | `📋 Report from subagent NAME: ` and the first line of `handbackReportText`, or of `body` |
|
||||
| scheduled prompt | no origin, `turnOrigin` `scheduled` | `⏰ Scheduled prompt: ` and the first line |
|
||||
| automatic prompt | origin `auto-continuation` | `🔄 Automatic prompt: ` and the first line |
|
||||
| another kind | another origin | `⚙️ Claude Code: ` and the first line |
|
||||
- These terminal prompts are not posted ([hub.ts:196](../src/hub.ts#L196)):
|
||||
- a prompt with `typed: false`, such as a notification of a background task. A request without `typed`, from an older plugin, is posted as typed;
|
||||
- a blank prompt, which Claude Code sends for a prompt with images only;
|
||||
- a prompt made only of this plugin's channel tags, as after the pushed prompts were lost in a service restart;
|
||||
- a one-line `/` command, such as `/compact`.
|
||||
- An answer and a terminal prompt are posted in parts. Each part is the longest run of whole characters that fits in one message, as `send` measures it, and the first part of an answer is measured with its quote. The hub searches each part among the next 15602 characters. No command reply is posted to a part that `User` posts and that starts with `/` ([hub.ts:195](../src/hub.ts#L195), [:277-287](../src/hub.ts#L277-L287), [:531-548](../src/hub.ts#L531-L548), [tools.ts:1575-1578](../src/tools.ts#L1575-L1578), [control.ts:221](../src/control.ts#L221)).
|
||||
- When the core refuses the quote of an answer with `invalidQuote` or `chatItemNotFound`, as for a deleted prompt, Claude posts the answer without the quote. It does the same when the core refuses the message with the quote as too large, with `largeMsg`. Claude also posts these replies without the quote in the same cases ([hub.ts:289-295](../src/hub.ts#L289-L295), [:550-553](../src/hub.ts#L550-L553)):
|
||||
- An answer and a terminal prompt are posted in parts. Each part is the longest run of whole characters that fits in one message, as `send` measures it, and the first part of an answer is measured with its quote. The hub searches each part among the next 15602 characters. No command reply is posted to a part that `User` posts and that starts with `/` ([hub.ts:196](../src/hub.ts#L196), [:278-288](../src/hub.ts#L278-L288), [:532-549](../src/hub.ts#L532-L549), [tools.ts:1575-1578](../src/tools.ts#L1575-L1578), [control.ts:221](../src/control.ts#L221)).
|
||||
- When the core refuses the quote of an answer with `invalidQuote` or `chatItemNotFound`, as for a deleted prompt, Claude posts the answer without the quote. It does the same when the core refuses the message with the quote as too large, with `largeMsg`. Claude also posts these replies without the quote in the same cases ([hub.ts:290-296](../src/hub.ts#L290-L296), [:551-554](../src/hub.ts#L551-L554)):
|
||||
- `Session N is not running.`
|
||||
- `The file of this message was not received: ERROR`
|
||||
- the reply to a one-line `/` text of a moderator, member or author
|
||||
- When the core refuses an answer or a terminal prompt with `feature not allowed NAME`, Claude posts a text in its place, and the turn goes on ([hub.ts:195](../src/hub.ts#L195), [:277-287](../src/hub.ts#L277-L287), [:523-525](../src/hub.ts#L523-L525)). NAME is, for example, `SimpleX links` for a SimpleX link while that preference is off. A prompt of `User` is also refused while the preference is on only for roles above that of `User`. The texts are:
|
||||
- When the core refuses an answer or a terminal prompt with `feature not allowed NAME`, Claude posts a text in its place, and the turn goes on ([hub.ts:196](../src/hub.ts#L196), [:278-288](../src/hub.ts#L278-L288), [:524-526](../src/hub.ts#L524-L526)). NAME is, for example, `SimpleX links` for a SimpleX link while that preference is off. A prompt of `User` is also refused while the preference is on only for roles above that of `User`. The texts are:
|
||||
- for an answer, `Claude's answer was not posted: NAME are off in the group of this session; its owners can turn them on in the group's preferences.`, quoting the turn's prompt as the answer would;
|
||||
- for a terminal prompt, `User's prompt was not posted: NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences.`
|
||||
- The hook cuts a prompt or an answer over 250,000 characters at that length and appends `…`, so that the request fits within the socket's limit of 1 MiB ([hook.ts:16](../src/hook.ts#L16), [:190-192](../src/hook.ts#L190-L192)).
|
||||
- A card of a tool use that started after the hook stays pending, because the hook's start time `at` is earlier than the card's creation ([hook.ts:91](../src/hook.ts#L91), [hub.ts:203-207](../src/hub.ts#L203-L207)).
|
||||
- The Stop hook sends the model of its answer ([hook.ts:17](../src/hook.ts#L17), [:19-21](../src/hook.ts#L19-L21), [:95](../src/hook.ts#L95), [:114-188](../src/hook.ts#L114-L188)):
|
||||
- The hook cuts a prompt or an answer over 250,000 characters at that length and appends `…`, so that the request fits within the socket's limit of 1 MiB ([hook.ts:16](../src/hook.ts#L16), [:307-309](../src/hook.ts#L307-L309)).
|
||||
- A card of a tool use that started after the hook stays pending, because the hook's start time `at` is earlier than the card's creation ([hook.ts:114](../src/hook.ts#L114), [hub.ts:204-208](../src/hub.ts#L204-L208)).
|
||||
- The Stop hook sends the model of its answer ([hook.ts:17](../src/hook.ts#L17), [:19-21](../src/hook.ts#L19-L21), [:118](../src/hook.ts#L118), [:137-145](../src/hook.ts#L137-L145), [:153-185](../src/hook.ts#L153-L185)):
|
||||
- The model is the `message.model` of Claude's last entry in the transcript, an entry of type `assistant` without `isSidechain`. It is taken once the text of that entry is equal to the answer.
|
||||
- Only the end of the transcript is read, 1 MiB plus twice the answer's size in bytes. The hook reads it up to 20 times, 100 ms apart, as Claude Code writes the transcript every 100 ms.
|
||||
- No model is sent for the model `<synthetic>`, for an answer without text, for an empty `transcript_path` or an unreadable transcript, and when the answer's entry is not written within the reads.
|
||||
- PostModelSwitch sends `{id, pid, at, model, effort}`, with `effort` when the hook's input has it ([hook.ts:95-97](../src/hook.ts#L95-L97)). Nothing is posted for it. When the model or effort changed, the hub writes them to `session.json` and updates the short description ([hub.ts:187-200](../src/hub.ts#L187-L200)).
|
||||
- The hub takes a model or an effort level only from a request whose `at` is not older than the `at` of the value it took last. It keeps the two times apart, one for the model and one for the effort level. The model of a `/title` comes with the `at` of its SessionStart hook, so a hook that started during the wait of a held title keeps its model ([flow 27](#27-clear---continue-and-resume-in-one-session)). A request without `at` counts as the current time. So when a Stop request that waited for its transcript entry arrives after a later PostModelSwitch request, the model of the switch stays ([hub.ts:260-264](../src/hub.ts#L260-L264)).
|
||||
- For a Stop request with a changed model or effort, the hub posts the answer before it updates the short description. So the prompt of a request handled meanwhile is posted after the answer. The description is updated also when a post fails ([hub.ts:194-200](../src/hub.ts#L194-L200)).
|
||||
- A turn hook starts the service when none runs. It repeats a turn refused with 409 up to 15 times, 1 s apart, which is longer than the 10 s wait of a held title. It prints `{}` and logs errors on its stderr ([hook.ts:91-112](../src/hook.ts#L91-L112)). Claude Code gives a hook without `timeout` 600 s, more than the 60 s of a prompt's reads and the 15 s of repeats.
|
||||
- PostModelSwitch sends `{id, pid, at, model, effort}`, with `effort` when the hook's input has it ([hook.ts:118-120](../src/hook.ts#L118-L120)). Nothing is posted for it. When the model or effort changed, the hub writes them to `session.json` and updates the short description ([hub.ts:187-201](../src/hub.ts#L187-L201)).
|
||||
- The hub takes a model or an effort level only from a request whose `at` is not older than the `at` of the value it took last. It keeps the two times apart, one for the model and one for the effort level. The model of a `/title` comes with the `at` of its SessionStart hook, so a hook that started during the wait of a held title keeps its model ([flow 27](#27-clear---continue-and-resume-in-one-session)). A request without `at` counts as the current time. So when a Stop request that waited for its transcript entry arrives after a later PostModelSwitch request, the model of the switch stays ([hub.ts:261-265](../src/hub.ts#L261-L265)).
|
||||
- For a Stop request with a changed model or effort, the hub posts the answer before it updates the short description. So the prompt of a request handled meanwhile is posted after the answer. The description is updated also when a post fails ([hub.ts:194-201](../src/hub.ts#L194-L201)).
|
||||
- A turn hook starts the service when none runs. It repeats a turn refused with 409 up to 15 times, 1 s apart, which is longer than the 10 s wait of a held title. It prints `{}` and logs errors on its stderr ([hook.ts:114-135](../src/hook.ts#L114-L135)). Claude Code gives a hook without `timeout` 600 s, more than the 60 s of a prompt's reads and the 15 s of repeats.
|
||||
|
||||
Source: [hooks.json:5-7](../hooks/hooks.json#L5-L7), [hub.ts:180-201](../src/hub.ts#L180-L201), [:266-295](../src/hub.ts#L266-L295), [:531-548](../src/hub.ts#L531-L548), [user.ts:29-32](../src/user.ts#L29-L32).
|
||||
Source: [hooks.json:5-7](../hooks/hooks.json#L5-L7), [hub.ts:180-202](../src/hub.ts#L180-L202), [:267-296](../src/hub.ts#L267-L296), [:532-549](../src/hub.ts#L532-L549), [user.ts:29-32](../src/user.ts#L29-L32).
|
||||
|
||||
---
|
||||
|
||||
@@ -1066,7 +1079,7 @@ sequenceDiagram
|
||||
Notes:
|
||||
|
||||
- On `/reject N`, the session pushes `deny`, and the card ends with `Rejected by NAME.` ([hub.ts:172-173](../src/hub.ts#L172-L173)).
|
||||
- The first answer, in the terminal or in the group, applies. The last line of a card that is still pending becomes `Ended.` at a prompt or an answer whose hook started after the card was created, and when the last attachment of the session ends ([hub.ts:181](../src/hub.ts#L181), [:203-207](../src/hub.ts#L203-L207), [service.ts:321](../src/service.ts#L321), [control.ts:695-696](../src/control.ts#L695-L696)).
|
||||
- The first answer, in the terminal or in the group, applies. The last line of a card that is still pending becomes `Ended.` at an answer, or at a prompt that is not mid-turn, whose hook started after the card was created, and when the last attachment of the session ends. A prompt that Claude Code adds to the running turn ends no card ([hub.ts:181](../src/hub.ts#L181), [:204-208](../src/hub.ts#L204-L208), [service.ts:321](../src/service.ts#L321), [control.ts:695-696](../src/control.ts#L695-L696)).
|
||||
- The input preview is cut to fit the card ([control.ts:154](../src/control.ts#L154), [:784-798](../src/control.ts#L784-L798)).
|
||||
- The card is posted in mode `requests` also for a session in mode `host` ([hub.ts:170](../src/hub.ts#L170)).
|
||||
|
||||
@@ -1098,12 +1111,12 @@ sequenceDiagram
|
||||
Notes:
|
||||
|
||||
- At most one `mode` card is pending at a time. After a card is rejected or expires, the request is forgotten until the next `/session` ([hub.ts:140-151](../src/hub.ts#L140-L151)).
|
||||
- When a card is rejected, the hub sets `hostDeclined` in `session.json`. While it is set, no card is posted for a `/session` request of `host`, also after a service restart. It is cleared at a `/session` with `requests` ([hub.ts:70-74](../src/hub.ts#L70-L74), [:136](../src/hub.ts#L136), [:141](../src/hub.ts#L141), [:145](../src/hub.ts#L145), [:324-327](../src/hub.ts#L324-L327)).
|
||||
- When the session opens, the approved mode is read from the custom data of `#G`, and is `requests` when none is stored. No mode is stored in `session.json` ([hub.ts:75](../src/hub.ts#L75), [:319-322](../src/hub.ts#L319-L322)).
|
||||
- When a card is rejected, the hub sets `hostDeclined` in `session.json`. While it is set, no card is posted for a `/session` request of `host`, also after a service restart. It is cleared at a `/session` with `requests` ([hub.ts:70-74](../src/hub.ts#L70-L74), [:136](../src/hub.ts#L136), [:141](../src/hub.ts#L141), [:145](../src/hub.ts#L145), [:325-328](../src/hub.ts#L325-L328)).
|
||||
- When the session opens, the approved mode is read from the custom data of `#G`, and is `requests` when none is stored. No mode is stored in `session.json` ([hub.ts:75](../src/hub.ts#L75), [:320-323](../src/hub.ts#L320-L323)).
|
||||
- An idle session is closed also while a `mode` card is pending ([hub.ts:119-121](../src/hub.ts#L119-L121)).
|
||||
- The session process marks the action tools for Claude Code's confirmation by the option read at its own start, before the owner decides ([session.ts:57](../src/session.ts#L57)).
|
||||
|
||||
Source: [hub.ts:132-151](../src/hub.ts#L132-L151), [:319-333](../src/hub.ts#L319-L333), [:518](../src/hub.ts#L518), [tools.ts:563-564](../src/tools.ts#L563-L564).
|
||||
Source: [hub.ts:132-151](../src/hub.ts#L132-L151), [:320-334](../src/hub.ts#L320-L334), [:519](../src/hub.ts#L519), [tools.ts:563-564](../src/tools.ts#L563-L564).
|
||||
|
||||
---
|
||||
|
||||
@@ -1124,7 +1137,7 @@ sequenceDiagram
|
||||
K->>O: Gave bot X (@4) to session 2.
|
||||
```
|
||||
|
||||
Source: [control.ts:362-373](../src/control.ts#L362-L373), [tools.ts:568-571](../src/tools.ts#L568-L571), [hub.ts:426-428](../src/hub.ts#L426-L428).
|
||||
Source: [control.ts:362-373](../src/control.ts#L362-L373), [tools.ts:568-571](../src/tools.ts#L568-L571), [hub.ts:427-429](../src/hub.ts#L427-L429).
|
||||
|
||||
---
|
||||
|
||||
@@ -1155,8 +1168,8 @@ sequenceDiagram
|
||||
Notes:
|
||||
|
||||
- VERSION is the plugin's version, so that the command runs the service's version ([owner.ts:7-8](../src/owner.ts#L7-L8)).
|
||||
- `reset-owners` replaces the group at once, also while owners exist, without their approval. On a terminal, it prints the new link with a QR code. Without a terminal, it names the `link` command instead, so the link is never in Claude's context ([owner.ts:17-20](../src/owner.ts#L17-L20), [:28-33](../src/owner.ts#L28-L33), [hub.ts:402-404](../src/hub.ts#L402-L404)).
|
||||
- The members who joined the session groups from the old Main group stay there with their roles and the rights of those roles ([hub.ts:311-313](../src/hub.ts#L311-L313)).
|
||||
- `reset-owners` replaces the group at once, also while owners exist, without their approval. On a terminal, it prints the new link with a QR code. Without a terminal, it names the `link` command instead, so the link is never in Claude's context ([owner.ts:17-20](../src/owner.ts#L17-L20), [:28-33](../src/owner.ts#L28-L33), [hub.ts:403-405](../src/hub.ts#L403-L405)).
|
||||
- The members who joined the session groups from the old Main group stay there with their roles and the rights of those roles ([hub.ts:312-314](../src/hub.ts#L312-L314)).
|
||||
|
||||
Source: [main-group.ts:99-109](../src/main-group.ts#L99-L109).
|
||||
|
||||
@@ -1186,7 +1199,7 @@ Notes:
|
||||
- The service cancels the stop timer when it creates an entry for a call or an attachment ([service.ts:357-367](../src/service.ts#L357-L367)).
|
||||
- A service of a higher version is kept. When the service speaks another protocol version, clients fail with `Restart Claude Code to update the SimpleX plugin.` ([client.ts:35-47](../src/client.ts#L35-L47)).
|
||||
|
||||
Source: [service.ts:177-199](../src/service.ts#L177-L199), [:315-323](../src/service.ts#L315-L323), [:404-422](../src/service.ts#L404-L422), [hub.ts:458-468](../src/hub.ts#L458-L468).
|
||||
Source: [service.ts:177-199](../src/service.ts#L177-L199), [:315-323](../src/service.ts#L315-L323), [:404-422](../src/service.ts#L404-L422), [hub.ts:459-469](../src/hub.ts#L459-L469).
|
||||
|
||||
---
|
||||
|
||||
@@ -1247,7 +1260,7 @@ Notes:
|
||||
- Aliases are read from `session.json` at the service's start, so the service routes later hooks and calls with B or X to the same session ([service.ts:87-91](../src/service.ts#L87-L91), [:290-295](../src/service.ts#L290-L295)).
|
||||
- Without `CLAUDE_PID`, before Claude Code 2.1.214, a new session server waits the 10 s and then registers its own ID.
|
||||
|
||||
Source: [hook.ts:70](../src/hook.ts#L70), [:97](../src/hook.ts#L97), [:194-197](../src/hook.ts#L194-L197), [session.ts:53](../src/session.ts#L53), [service.ts:201-295](../src/service.ts#L201-L295).
|
||||
Source: [hook.ts:93](../src/hook.ts#L93), [:120](../src/hook.ts#L120), [:311-314](../src/hook.ts#L311-L314), [session.ts:53](../src/session.ts#L53), [service.ts:201-295](../src/service.ts#L201-L295).
|
||||
|
||||
---
|
||||
|
||||
@@ -1295,26 +1308,26 @@ sequenceDiagram
|
||||
|
||||
Notes:
|
||||
|
||||
- A member's rights depend on the member's role in the session group, not on the way the member joined or on the member's role in the Main group. Admins and owners approve and send the group's `/` commands. The session groups stay as they are at changes in the Main group ([hub.ts:216-218](../src/hub.ts#L216-L218), [:311-313](../src/hub.ts#L311-L313), [main-group.ts:117-132](../src/main-group.ts#L117-L132)).
|
||||
- With `/join N`, a member of the Main group gets an invitation as an admin, and an owner of the Main group as an owner ([hub.ts:439](../src/hub.ts#L439)).
|
||||
- When a member of the group changes a member's role, the core raises `memberRole`, and Claude posts the new rights. For a role change by Claude, as with `/observer`, the core raises no event, and Claude states the observer's rights in its reply to `/observer` ([hub.ts:220-227](../src/hub.ts#L220-L227), [control.ts:384-386](../src/control.ts#L384-L386), [:888-891](../src/control.ts#L888-L891)).
|
||||
- A member's rights depend on the member's role in the session group, not on the way the member joined or on the member's role in the Main group. Admins and owners approve and send the group's `/` commands. The session groups stay as they are at changes in the Main group ([hub.ts:217-219](../src/hub.ts#L217-L219), [:312-314](../src/hub.ts#L312-L314), [main-group.ts:117-132](../src/main-group.ts#L117-L132)).
|
||||
- With `/join N`, a member of the Main group gets an invitation as an admin, and an owner of the Main group as an owner ([hub.ts:440](../src/hub.ts#L440)).
|
||||
- When a member of the group changes a member's role, the core raises `memberRole`, and Claude posts the new rights. For a role change by Claude, as with `/observer`, the core raises no event, and Claude states the observer's rights in its reply to `/observer` ([hub.ts:221-228](../src/hub.ts#L221-L228), [control.ts:384-386](../src/control.ts#L384-L386), [:888-891](../src/control.ts#L888-L891)).
|
||||
- `/observer #G ID` is accepted from a sender whose role is admin or owner and not below the member's role, as SimpleX requires for a role change. Only a current member's role changes ([control.ts:375-387](../src/control.ts#L375-L387), [tools.ts:1549-1551](../src/tools.ts#L1549-L1551)):
|
||||
- For a member with the status `pending_approval` or `pending_review`, Claude replies `NAME's role can't be changed.`
|
||||
- `No member ID in this group.` is the reply for a member who is neither current nor pending, such as an invited member who has not joined.
|
||||
|
||||
After the role change, the members are read again. So the standing approvals that the new observer gave are not counted while that member is not an admin or owner. They stay in the chat's custom data and are counted again when the member becomes one again ([control.ts:167-170](../src/control.ts#L167-L170)).
|
||||
- Claude finds the joiner of the Main group's post among the refreshed members, because in `connectedToGroupMember` the member's status is the one before the connection. The post is made only for a human joiner ([main-group.ts:127-128](../src/main-group.ts#L127-L128)).
|
||||
- Claude posts nothing when `User` joins a session group or when its role changes ([hub.ts:223](../src/hub.ts#L223), [:315-317](../src/hub.ts#L315-L317)).
|
||||
- Claude posts nothing when `User` joins a session group or when its role changes ([hub.ts:224](../src/hub.ts#L224), [:316-318](../src/hub.ts#L316-L318)).
|
||||
- One post is made for each join. For each connection, the core raises one of two events:
|
||||
- `joinedGroupMember` for a member who joined through the hub, by its invitation or link;
|
||||
- `connectedToGroupMember` for a member whom another member added.
|
||||
|
||||
The end-to-end test counts one post for each join in both groups ([test/e2e/service.test.ts](../test/e2e/service.test.ts)).
|
||||
- A person added to the group directly has the rights of the role that the adding member set, as a member from the Main group has the rights of its role ([hub.ts:229-232](../src/hub.ts#L229-L232), [:311-313](../src/hub.ts#L311-L313)).
|
||||
- Claude answers `/join N` from a member of the group of session N with `You are a member of "N · NAME".` ([hub.ts:438-443](../src/hub.ts#L438-L443)).
|
||||
- A person added to the group directly has the rights of the role that the adding member set, as a member from the Main group has the rights of its role ([hub.ts:230-233](../src/hub.ts#L230-L233), [:312-314](../src/hub.ts#L312-L314)).
|
||||
- Claude answers `/join N` from a member of the group of session N with `You are a member of "N · NAME".` ([hub.ts:439-444](../src/hub.ts#L439-L444)).
|
||||
- At a reset of the owners, the session groups and their members stay as they are ([flow 25](#25-reset-owners)).
|
||||
|
||||
Source: [main-group.ts:111-115](../src/main-group.ts#L111-L115), [:117-132](../src/main-group.ts#L117-L132), [hub.ts:216-227](../src/hub.ts#L216-L227), [:435-446](../src/hub.ts#L435-L446), [:518](../src/hub.ts#L518), [control.ts:375-387](../src/control.ts#L375-L387), [:884-891](../src/control.ts#L884-L891).
|
||||
Source: [main-group.ts:111-115](../src/main-group.ts#L111-L115), [:117-132](../src/main-group.ts#L117-L132), [hub.ts:217-228](../src/hub.ts#L217-L228), [:436-447](../src/hub.ts#L436-L447), [:519](../src/hub.ts#L519), [control.ts:375-387](../src/control.ts#L375-L387), [:884-891](../src/control.ts#L884-L891).
|
||||
|
||||
---
|
||||
|
||||
@@ -1385,6 +1398,44 @@ Notes:
|
||||
- For its hooks, Claude Code sets `CLAUDE_CODE_SESSION_ATTENDED` to `1` or `0`, and to `0` for a run nobody attends. Its MCP servers get the variable only from the environment of the command that started Claude Code. In the run recorded with Claude Code 2.1.319 in [`claude-p-runs.jsonl`](../test/unit/claude-p-runs.jsonl), the hooks got `0` and a `CLAUDE_PID` equal to the server's parent process. The server got the parent session's `1` and `CLAUDE_PID`.
|
||||
- The service checks the mark before and after the wait of `/session` for the title of its process. So the session server is refused whether its `/session` arrives before or after the hook's mark. A mark is valid for 10 s, and after that it is removed at the next mark ([service.ts:203-205](../src/service.ts#L203-L205), [:237-248](../src/service.ts#L237-L248)).
|
||||
- A refused server answers every call with that text, relays no permission request and does not register again ([session.ts:79-80](../src/session.ts#L79-L80), [:92](../src/session.ts#L92), [:115](../src/session.ts#L115), [:127](../src/session.ts#L127), [:162-165](../src/session.ts#L162-L165)).
|
||||
- A hook without `CLAUDE_PID` sends no mark. A failed mark is logged as `SimpleX MCP session start` ([hook.ts:79-89](../src/hook.ts#L79-L89)).
|
||||
- A hook without `CLAUDE_PID` sends no mark. A failed mark is logged as `SimpleX MCP session start` ([hook.ts:102-112](../src/hook.ts#L102-L112)).
|
||||
|
||||
Source: [config.ts:22-32](../src/config.ts#L22-L32), [hook.ts:58-62](../src/hook.ts#L58-L62), [:92](../src/hook.ts#L92), [service.ts:221](../src/service.ts#L221), [:237-248](../src/service.ts#L237-L248), [session.ts:45](../src/session.ts#L45).
|
||||
Source: [config.ts:22-32](../src/config.ts#L22-L32), [hook.ts:81-85](../src/hook.ts#L81-L85), [:115](../src/hook.ts#L115), [service.ts:221](../src/service.ts#L221), [:237-248](../src/service.ts#L237-L248), [session.ts:45](../src/session.ts#L45).
|
||||
|
||||
---
|
||||
|
||||
## 31. A prompt of Claude Code
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CC as Claude Code
|
||||
participant HK as UserPromptSubmit hook
|
||||
participant T as Transcript
|
||||
participant D as Service
|
||||
participant N as Session N
|
||||
participant O as Owner
|
||||
Note over CC,O: at a turn's start
|
||||
CC->>HK: {prompt_id of the new turn, prompt: a task notification}
|
||||
CC->>T: the prompt's entry, origin task-notification
|
||||
HK->>T: the entry with prompt_id whose text is the prompt
|
||||
HK->>D: POST /turn {prompt, typed: false, note}
|
||||
D->>N: end tool-use cards created before at#59; turns += (at, null), unless at is below answeredAt
|
||||
N->>O: Claude: ✅ Background command "Build" completed (exit code 0)
|
||||
Note over CC,O: during the turn
|
||||
CC->>HK: {prompt_id of the running turn, prompt: a task notification}
|
||||
CC->>T: a queued_command attachment with the prompt and its origin
|
||||
HK->>T: the attachment after the entry with prompt_id
|
||||
HK->>D: POST /turn {prompt, typed: false, note, midTurn: true}
|
||||
D->>N: cards stay pending, and a turn record needs a matched pushed prompt
|
||||
N->>O: Claude: ❌ Background command "Lint" failed with exit code 1
|
||||
CC->>D: Stop hook: POST /turn {answer}
|
||||
N->>O: Claude: the answer, without a quote
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- The note is posted before the answer of its turn, in the order in which the hooks' requests arrive. The UserPromptSubmit hook of a turn starts before its Stop hook ([hub.ts:195-197](../src/hub.ts#L195-L197)).
|
||||
- A mid-turn prompt ends no tool-use card. A prompt adds a turn record only when its hook started no earlier than the hook of the last answer handled (`answeredAt`), and a mid-turn prompt only when it also matched a pushed prompt, an owner's prompt from the group. So the answer quotes the turn's prompt, or an owner's prompt added to the turn ([hub.ts:181](../src/hub.ts#L181), [:185](../src/hub.ts#L185), [:267-276](../src/hub.ts#L267-L276)).
|
||||
- A person's prompt typed during a turn runs its hook at once. Its record is written later, as a `queued_command` attachment when Claude Code adds it to the running turn, or as the entry of the next turn. `User` posts it as typed and mid-turn ([hook.ts:187-203](../src/hook.ts#L187-L203)).
|
||||
|
||||
Source: [hook.ts:147-151](../src/hook.ts#L147-L151), [:187-290](../src/hook.ts#L187-L290), [hub.ts:180-202](../src/hub.ts#L180-L202).
|
||||
@@ -2,7 +2,7 @@ import {open} from "fs/promises"
|
||||
import {ServiceClient} from "./client"
|
||||
import {interactive, interactiveEntrypoint, readConfig} from "./config"
|
||||
import {dataRoot} from "./files"
|
||||
import {errorText, logError} from "./log"
|
||||
import {errorText, logError, oneLine} from "./log"
|
||||
import {TitleReply} from "./protocol"
|
||||
import {qrCodeText} from "./qr"
|
||||
import {SocketError, isNotRunning} from "./socket"
|
||||
@@ -19,6 +19,10 @@ const promptReads = 600
|
||||
const transcriptReadMs = 100
|
||||
const transcriptTailBytes = 1_048_576
|
||||
const syntheticModel = "<synthetic>"
|
||||
const maxNote = 200
|
||||
const statusEmoji = new Map([["completed", "✅"], ["failed", "❌"], ["stopped", "⏹️"], ["killed", "⏹️"]])
|
||||
const teammatePrompt = /^Another Claude session sent a message[^:\n]*:\n<teammate-message /
|
||||
const teammateMessage = /<teammate-message teammate_id="([^"]*)"([^>]*)>\n([\s\S]*?)\n<\/teammate-message>/g
|
||||
|
||||
interface SessionStartInput {
|
||||
session_id: string
|
||||
@@ -38,14 +42,33 @@ interface TurnInput {
|
||||
effort?: {level?: string}
|
||||
}
|
||||
|
||||
interface Origin {
|
||||
kind?: unknown
|
||||
name?: unknown
|
||||
from?: unknown
|
||||
body?: unknown
|
||||
handback?: unknown
|
||||
handbackReportText?: unknown
|
||||
}
|
||||
|
||||
interface TranscriptEntry {
|
||||
type?: unknown
|
||||
isSidechain?: unknown
|
||||
promptId?: unknown
|
||||
origin?: {kind?: unknown} | null
|
||||
origin?: Origin | null
|
||||
turnOrigin?: unknown
|
||||
operation?: unknown
|
||||
content?: unknown
|
||||
attachment?: {type?: unknown; prompt?: unknown; origin?: Origin | null; commandMode?: unknown}
|
||||
message?: {model?: unknown; content?: unknown}
|
||||
}
|
||||
|
||||
interface PromptKind {
|
||||
typed: boolean
|
||||
note?: string
|
||||
midTurn?: boolean
|
||||
}
|
||||
|
||||
export interface HookOutput {
|
||||
systemMessage?: string
|
||||
}
|
||||
@@ -93,8 +116,8 @@ export async function turn(stdin: string, env: NodeJS.ProcessEnv = process.env,
|
||||
try {
|
||||
const input = JSON.parse(stdin) as TurnInput
|
||||
const model = input.to_model ?? (input.hook_event_name === "Stop" ? await answerModel(input, readMs) : undefined)
|
||||
const typed = input.hook_event_name === "UserPromptSubmit" ? await promptTyped(input, readMs) : undefined
|
||||
const request = {id: input.session_id, pid: claudePid(env), at, prompt: cut(input.prompt), typed, answer: cut(input.last_assistant_message), model, effort: input.effort?.level}
|
||||
const kind = input.hook_event_name === "UserPromptSubmit" ? await promptKind(input, readMs) : undefined
|
||||
const request = {id: input.session_id, pid: claudePid(env), at, prompt: cut(input.prompt), ...kind, answer: cut(input.last_assistant_message), model, effort: input.effort?.level}
|
||||
await client.ensureService(version)
|
||||
for (let attempt = 1; ; attempt++) {
|
||||
try {
|
||||
@@ -121,18 +144,17 @@ async function answerModel({transcript_path: path, last_assistant_message: messa
|
||||
return last?.model
|
||||
}
|
||||
|
||||
async function promptTyped({transcript_path: path, prompt_id: id, prompt}: TurnInput, readMs: number): Promise<boolean> {
|
||||
async function promptKind({transcript_path: path, prompt_id: id, prompt}: TurnInput, readMs: number): Promise<PromptKind> {
|
||||
const text = prompt?.trim()
|
||||
if (!path || !text) return false
|
||||
const entry = await findInTranscript(path, text, promptReads, readMs, tail => promptEntry(tail, id, text))
|
||||
return entry?.origin?.kind === "human"
|
||||
if (!path || !text) return {typed: false}
|
||||
return (await findInTranscript(path, text, promptReads, readMs, (tail, last) => promptRecord(tail, id, text, last))) ?? {typed: false}
|
||||
}
|
||||
|
||||
async function findInTranscript<T>(path: string, text: string, reads: number, readMs: number, find: (tail: string) => T | undefined): Promise<T | undefined> {
|
||||
async function findInTranscript<T>(path: string, text: string, reads: number, readMs: number, find: (tail: string, last: boolean) => T | undefined): Promise<T | undefined> {
|
||||
const bytes = transcriptTailBytes + 2 * Buffer.byteLength(text)
|
||||
for (let read = 1; ; read++) {
|
||||
const tail = await readTail(path, bytes).catch(() => "")
|
||||
const found = find(tail)
|
||||
const found = find(tail, read === reads)
|
||||
if (found !== undefined || read === reads) return found
|
||||
await new Promise(resolve => setTimeout(resolve, readMs))
|
||||
}
|
||||
@@ -162,14 +184,109 @@ function lastAnswer(tail: string): {text: string; model?: string} | undefined {
|
||||
return undefined
|
||||
}
|
||||
|
||||
function promptEntry(tail: string, id: string | undefined, text: string): TranscriptEntry | undefined {
|
||||
const prompts = tail.split("\n").flatMap(line => {
|
||||
const entry = transcriptEntry(line)
|
||||
const content = entry?.message?.content
|
||||
const toolResult = Array.isArray(content) && content.some((part: {type?: unknown} | null) => part?.type === "tool_result")
|
||||
return entry?.type === "user" && entry.isSidechain !== true && !toolResult ? [entry] : []
|
||||
})
|
||||
return id !== undefined ? prompts.find(entry => entry.promptId === id) : prompts.filter(entry => textOf(entry.message?.content) === text).at(-1)
|
||||
function promptRecord(tail: string, id: string | undefined, text: string, last: boolean): PromptKind | undefined {
|
||||
const entries = tail.split("\n").flatMap(line => transcriptEntry(line) ?? [])
|
||||
const first = id === undefined ? -1 : entries.findIndex(entry => entry.type === "user" && entry.isSidechain !== true && entry.promptId === id)
|
||||
if (first === -1 && id !== undefined && !last) return undefined
|
||||
const after = entries.slice(Math.max(first, 0))
|
||||
const records = after.flatMap((entry, i) => (recordText(entry) === text ? [i] : []))
|
||||
const queuedAfter = (start: number): boolean => after.slice(start).some(entry => entry.type === "queue-operation" && entry.operation === "enqueue" && textOf(entry.content) === text)
|
||||
const record = records.at(-1)
|
||||
if (record !== undefined && !queuedAfter(record + 1)) return recordKind(after[record], id, text)
|
||||
if (!last) return undefined
|
||||
if (record !== undefined) {
|
||||
const kind = recordKind(after[record], id, text)
|
||||
return kind.typed ? {...kind, midTurn: true} : kind
|
||||
}
|
||||
if (queuedAfter(0)) return {typed: true, midTurn: true}
|
||||
return first === -1 ? undefined : {typed: after.some(entry => isPrompt(entry) && entry.promptId === id && entry.origin?.kind === "human")}
|
||||
}
|
||||
|
||||
function isPrompt(entry: TranscriptEntry): boolean {
|
||||
const content = entry.message?.content
|
||||
const toolResult = Array.isArray(content) && content.some((part: {type?: unknown} | null) => part?.type === "tool_result")
|
||||
return entry.type === "user" && entry.isSidechain !== true && !toolResult
|
||||
}
|
||||
|
||||
function recordText(entry: TranscriptEntry): string | undefined {
|
||||
if (isPrompt(entry)) return textOf(entry.message?.content)
|
||||
if (entry.type === "attachment" && entry.isSidechain !== true && entry.attachment?.type === "queued_command") return textOf(entry.attachment.prompt)
|
||||
return undefined
|
||||
}
|
||||
|
||||
function recordKind(record: TranscriptEntry, id: string | undefined, text: string): PromptKind {
|
||||
const origin = record.type === "attachment" ? (record.attachment?.origin ?? (record.attachment?.commandMode === "task-notification" ? {kind: "task-notification"} : undefined)) : record.origin
|
||||
const note = noteOf(origin, record.turnOrigin, text)
|
||||
const midTurn = record.type !== "user" || (id !== undefined && record.promptId !== id)
|
||||
return {typed: origin?.kind === "human", ...(note === undefined ? {} : {note: shortened(note)}), ...(midTurn ? {midTurn} : {})}
|
||||
}
|
||||
|
||||
function noteOf(origin: Origin | null | undefined, turnOrigin: unknown, text: string): string | undefined {
|
||||
switch (origin?.kind) {
|
||||
case "human":
|
||||
case "channel":
|
||||
return undefined
|
||||
case "task-notification":
|
||||
return taskNote(text)
|
||||
case "peer":
|
||||
return origin.handback === true
|
||||
? `📋 Report from subagent ${peerName(origin)}: ${firstLine(stringOf(origin.handbackReportText) ?? stringOf(origin.body) ?? text)}`
|
||||
: `✉️ Message from ${peerName(origin)}: ${firstLine(stringOf(origin.body) ?? text)}`
|
||||
case "auto-continuation":
|
||||
return `🔄 Automatic prompt: ${firstLine(text)}`
|
||||
case undefined:
|
||||
return turnOrigin === "scheduled" ? `⏰ Scheduled prompt: ${firstLine(text)}` : teammateNote(text)
|
||||
default:
|
||||
return typeof origin?.kind === "string" ? `⚙️ Claude Code: ${firstLine(text)}` : undefined
|
||||
}
|
||||
}
|
||||
|
||||
function taskNote(text: string): string {
|
||||
const block = /<task-notification>([\s\S]*?)<\/task-notification>/.exec(text)?.[1]
|
||||
if (block === undefined) return `🔔 ${firstLine(text)}`
|
||||
const field = (name: string): string => firstLine(decoded(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(block)?.[1] ?? ""))
|
||||
const summary = field("summary") || "Task notification"
|
||||
const event = field("event")
|
||||
const emoji = statusEmoji.get(field("status")) ?? (event === "" ? "🔔" : "📡")
|
||||
return `${emoji} ${summary}${event === "" ? "" : `: ${event}`}`
|
||||
}
|
||||
|
||||
function teammateNote(text: string): string | undefined {
|
||||
if (!teammatePrompt.test(text)) return undefined
|
||||
const match = [...text.matchAll(teammateMessage)].find(([, , , body]) => !idleNotification(body))
|
||||
if (match === undefined) return undefined
|
||||
const [, sender, attributes, body] = match
|
||||
const summary = /\ssummary="([^"]*)"/.exec(attributes)?.[1]
|
||||
return `✉️ Message from ${oneLine(decoded(sender))}: ${firstLine(summary === undefined ? body : decoded(summary))}`
|
||||
}
|
||||
|
||||
function idleNotification(body: string): boolean {
|
||||
try {
|
||||
return (JSON.parse(body) as {type?: unknown} | null)?.type === "idle_notification"
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
function peerName(origin: Origin): string {
|
||||
return oneLine(stringOf(origin.name) ?? stringOf(origin.from) ?? "another session")
|
||||
}
|
||||
|
||||
function firstLine(text: string): string {
|
||||
return text.split("\n").map(line => oneLine(line).trim()).find(line => line !== "") ?? ""
|
||||
}
|
||||
|
||||
function decoded(text: string): string {
|
||||
return text.replace(/</g, "<").replace(/>/g, ">").replace(/"/g, '"').replace(/'/g, "'").replace(/&/g, "&")
|
||||
}
|
||||
|
||||
function stringOf(value: unknown): string | undefined {
|
||||
return typeof value === "string" ? value : undefined
|
||||
}
|
||||
|
||||
function shortened(note: string): string {
|
||||
const chars = [...note]
|
||||
return chars.length <= maxNote ? note : `${chars.slice(0, maxNote - 1).join("")}…`
|
||||
}
|
||||
|
||||
function transcriptEntry(line: string): TranscriptEntry | undefined {
|
||||
|
||||
@@ -177,12 +177,12 @@ export class Session {
|
||||
})
|
||||
}
|
||||
|
||||
async turn({at, prompt, typed, answer, model, effort}: TurnRequest): Promise<void> {
|
||||
if (prompt !== undefined || answer !== undefined) this.endPermissions(at)
|
||||
async turn({at, prompt, typed, note, midTurn, answer, model, effort}: TurnRequest): Promise<void> {
|
||||
if ((prompt !== undefined && midTurn !== true) || answer !== undefined) this.endPermissions(at)
|
||||
const quoted = answer === undefined ? undefined : this.turnQuote(at ?? Infinity)
|
||||
if (answer !== undefined) this.answeredAt = Math.max(this.answeredAt, at ?? Date.now())
|
||||
const matched = prompt === undefined ? [] : this.pushedIn(prompt)
|
||||
if (prompt !== undefined && (at ?? Date.now()) >= this.answeredAt) this.turns.push({at: at ?? Date.now(), item: matched[0]?.item ?? null})
|
||||
if (prompt !== undefined && (midTurn !== true || matched.length > 0) && (at ?? Date.now()) >= this.answeredAt) this.turns.push({at: at ?? Date.now(), item: matched[0]?.item ?? null})
|
||||
this.pushed.splice(0, this.pushed.length, ...this.pushed.filter(entry => !matched.includes(entry)))
|
||||
const newModel = this.newer("model", model, at ?? Date.now())
|
||||
const newEffort = this.newer("effort", effort, at ?? Date.now())
|
||||
@@ -192,6 +192,7 @@ export class Session {
|
||||
this.store(this.description)
|
||||
}
|
||||
try {
|
||||
if (note !== undefined) await this.post([note]).catch(error => this.postRefusal(error, "A note on Claude Code's prompt was not posted", featureOff))
|
||||
if (prompt !== undefined && typed !== false && prompt.replace(channelPrompt, "").trim() !== "" && matched.length === 0 && parseCommand(prompt) === undefined) await this.hub.user?.post(this.number, textParts(prompt)).catch(error => this.postRefusal(error, "User's prompt was not posted", notAllowedForUser))
|
||||
if (answer !== undefined && answer.trim() !== "") await this.answer(answer, quoted)
|
||||
} finally {
|
||||
|
||||
@@ -51,6 +51,8 @@ export interface TurnRequest {
|
||||
at?: number
|
||||
prompt?: string
|
||||
typed?: boolean
|
||||
note?: string
|
||||
midTurn?: boolean
|
||||
answer?: string
|
||||
model?: string
|
||||
effort?: string
|
||||
|
||||
@@ -348,7 +348,7 @@ test("while SimpleX links are off in a session's group, the connect card of a bo
|
||||
await sendNotice
|
||||
}, 600_000)
|
||||
|
||||
test("the hooks post a prompt typed in the terminal as User, also the session's first one whose hook starts before the transcript file is created, and not a task notification, and the answer as Claude in the session's group, whose description shows the model of the first answer from the transcript; a prompt to a session without Claude Code gets Session 1 is not running., without the quote for a prompt as long as a message can be; an owner's prompt reaches an attached session, in the channel tag or raw it is not posted again, and the answer quotes it", async () => {
|
||||
test("the hooks post a prompt typed in the terminal as User, also the session's first one whose hook starts before the transcript file is created, a task notification at a turn's start or within a running turn as Claude's one-line note, and the answer as Claude in the session's group, whose description shows the model of the first answer from the transcript; a prompt to a session without Claude Code gets Session 1 is not running., without the quote for a prompt as long as a message can be; an owner's prompt reaches an attached session, in the channel tag or raw it is not posted again, and the answer quotes it", async () => {
|
||||
const root = join(dir, "mirror", "root")
|
||||
await prepareRoot(smpServer.address, root)
|
||||
const alice = await personIn("mirror", "Alice")
|
||||
@@ -402,9 +402,16 @@ test("the hooks post a prompt typed in the terminal as User, also the session's
|
||||
await hook({hook_event_name: "UserPromptSubmit", prompt: `<channel source="plugin:simplex:simplex" from="Alice" item="${item}">\nRun the tests\n</channel>`})
|
||||
await hook({hook_event_name: "Stop", last_assistant_message: "Tests pass."})
|
||||
await passed
|
||||
const notification = "<task-notification>\n<task-id>b1</task-id>\n<status>completed</status>\n</task-notification>"
|
||||
const notification = '<task-notification>\n<task-id>b1</task-id>\n<status>completed</status>\n<summary>Background command "Build" completed (exit code 0)</summary>\n</task-notification>'
|
||||
const noted = received(alice.chat, message('✅ Background command "Build" completed (exit code 0)', "Claude"))
|
||||
appendFileSync(transcript, userEntry("p2", notification, "task-notification"))
|
||||
await hook({hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: "p2", prompt: notification})
|
||||
await noted
|
||||
const midTurn = '<task-notification>\n<task-id>b2</task-id>\n<status>failed</status>\n<summary>Background command "Lint" failed with exit code 1</summary>\n</task-notification>'
|
||||
const midTurnNoted = received(alice.chat, message('❌ Background command "Lint" failed with exit code 1', "Claude"))
|
||||
appendFileSync(transcript, `${JSON.stringify({type: "attachment", attachment: {type: "queued_command", prompt: midTurn, origin: {kind: "task-notification"}, commandMode: "task-notification"}})}\n`)
|
||||
await hook({hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: "p2", prompt: midTurn})
|
||||
await midTurnNoted
|
||||
const [lint] = await alice.chat.apiSendTextMessage([T.ChatType.Group, groupId], "Run the linter")
|
||||
await until(() => attached.length === 3)
|
||||
const linted = received(alice.chat, message("Lint passes.", "Claude", lint.chatItem.meta.itemId))
|
||||
|
||||
@@ -243,6 +243,255 @@ describe("turn hooks", () => {
|
||||
}
|
||||
})
|
||||
|
||||
const notification = (fields: string, after = "") => `<task-notification>\n${fields}\n</task-notification>${after}`
|
||||
const userEntry = (promptId: string, content: unknown, extra: object = {}) => `${JSON.stringify({type: "user", promptId, ...extra, message: {role: "user", content}})}\n`
|
||||
const queuedEntry = (prompt: string, origin: object) => `${JSON.stringify({type: "attachment", attachment: {type: "queued_command", prompt, origin, commandMode: "prompt"}})}\n`
|
||||
const enqueueEntry = (content: string) => `${JSON.stringify({type: "queue-operation", operation: "enqueue", content})}\n`
|
||||
const kinds = (requests: unknown[]) => requests.map(request => (request as {body: {note?: string; typed: boolean; midTurn?: boolean}}).body).map(({note, typed, midTurn}) => [note, typed, midTurn])
|
||||
|
||||
it("send a one-line note of each kind of Claude Code's own prompt, from the origin of its transcript entry, and none for a typed or a channel prompt", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const long = "x".repeat(300)
|
||||
const prompts: [string, string, object][] = [
|
||||
["p1", notification(`<task-id>b2gj1pdcw</task-id>\n<output-file>/p/tasks/b2gj1pdcw.output</output-file>\n<status>completed</status>\n<summary>Background command "Rebuild tests && show errors" completed (exit code 0)</summary>`), {origin: {kind: "task-notification", producer: "session-task"}}],
|
||||
["p2", notification(`<task-id>w5asfny36</task-id>\n<status>failed</status>\n<summary>Dynamic workflow "Research" failed: TypeError: null is not an object\n at <anonymous> (workflow.js:144:22)</summary>`), {origin: {kind: "task-notification"}}],
|
||||
["p3", notification(`<task-id>b4mg8bpso</task-id>\n<status>killed</status>\n<summary>Background command "Serve the docs" was stopped</summary>`), {origin: {kind: "task-notification"}}],
|
||||
["p4", notification(`<task-id>boud456ze</task-id>\n<summary>Monitor event: "Exit status of each of the 4 flag-combination builds"</summary>\n<event>\nserverpg exit 0\nclientpg exit 0</event>`, "\nIf this event is something the user would act on now, send a PushNotification."), {origin: {kind: "task-notification"}}],
|
||||
["p5", notification("<summary>Goal check-in: background work still running</summary>", "\n<system-reminder>\nThe goal is still active.\n</system-reminder>"), {origin: {kind: "task-notification"}}],
|
||||
["p6", 'Another Claude session sent a message:\n<agent-message from="mcp-impl2">\nI read the evidence.\n\nDetails follow.\n</agent-message>', {origin: {kind: "peer", from: "mcp-impl2", senderTaskId: "amcp-impl2-1", name: "mcp-impl2", body: "I read the evidence.\n\nDetails follow."}}],
|
||||
["p7", 'Another Claude session sent a message:\n<agent-message from="a43be993e71d0a22f">\n[Subagent hand-back] The report follows:\n \n ## Review of the race fix\n</agent-message>', {origin: {kind: "peer", from: "a43be993e71d0a22f", senderTaskId: "a43be993e71d0a22f", name: "general-purpose", body: "[Subagent hand-back] The report follows:\n \n ## Review of the race fix", handback: true, handbackReportText: "\n## Review of the race fix\n\nNo defect."}}],
|
||||
["p8", 'Another Claude session sent a message:\n<agent-message from="ios-terminal">\n[Subagent hand-back] The report follows:\n All done.\n</agent-message>', {origin: {kind: "peer", from: "ios-terminal", senderTaskId: "a1", name: "ios-terminal", body: "[Subagent hand-back] The report follows:\n All done.", handback: true}}],
|
||||
["p9", "Reply with the single word tick.", {isMeta: true, turnOrigin: "scheduled", scheduledTaskId: "d2657e37"}],
|
||||
["p10", "Your claude.ai usage limit has reset. Continue the task you were working on when the limit was reached; do not repeat work that is already complete.", {isMeta: true, origin: {kind: "auto-continuation"}}],
|
||||
["p11", "The coordinator sent a message while you were working:\nApproved.", {isMeta: true, origin: {kind: "coordinator"}}],
|
||||
["p12", "Fix the build", {origin: {kind: "human"}}],
|
||||
["p13", '<channel source="plugin:simplex:simplex" from="Alice" item="7">\nRun the tests\n</channel>', {isMeta: true, origin: {kind: "channel", server: "plugin:simplex:simplex"}}],
|
||||
["p14", "Run the checks", {turnOrigin: "sdk"}],
|
||||
["p15", `Another Claude session sent a message:\n<agent-message from="reviewer">\n${long}\n</agent-message>`, {origin: {kind: "peer", from: "reviewer", name: "reviewer", body: long}}],
|
||||
]
|
||||
writeFileSync(transcript, prompts.map(([promptId, content, extra]) => userEntry(promptId, content, extra)).join(""))
|
||||
const {client, requests} = turnClient()
|
||||
for (const [promptId, content] of prompts) await turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt: content}), {}, client, 0, 1, 1)
|
||||
const prefix = "✉️ Message from reviewer: "
|
||||
expect(kinds(requests)).toEqual([
|
||||
['✅ Background command "Rebuild tests && show errors" completed (exit code 0)', false, undefined],
|
||||
['❌ Dynamic workflow "Research" failed: TypeError: null is not an object', false, undefined],
|
||||
['⏹️ Background command "Serve the docs" was stopped', false, undefined],
|
||||
['📡 Monitor event: "Exit status of each of the 4 flag-combination builds": serverpg exit 0', false, undefined],
|
||||
["🔔 Goal check-in: background work still running", false, undefined],
|
||||
["✉️ Message from mcp-impl2: I read the evidence.", false, undefined],
|
||||
["📋 Report from subagent general-purpose: ## Review of the race fix", false, undefined],
|
||||
["📋 Report from subagent ios-terminal: [Subagent hand-back] The report follows:", false, undefined],
|
||||
["⏰ Scheduled prompt: Reply with the single word tick.", false, undefined],
|
||||
["🔄 Automatic prompt: Your claude.ai usage limit has reset. Continue the task you were working on when the limit was reached; do not repeat work that is already complete.", false, undefined],
|
||||
["⚙️ Claude Code: The coordinator sent a message while you were working:", false, undefined],
|
||||
[undefined, true, undefined],
|
||||
[undefined, false, undefined],
|
||||
[undefined, false, undefined],
|
||||
[`${prefix}${"x".repeat(199 - [...prefix].length)}…`, false, undefined],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("find a prompt that reaches a running turn by its queued command or its own later entry after the entry of the turn's prompt ID, and mark it mid-turn", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const alpha = notification('<task-id>buq1jepzn</task-id>\n<status>completed</status>\n<summary>Background command "Run the tests" completed (exit code 0)</summary>')
|
||||
const gamma = notification('<task-id>btjw2lm2a</task-id>\n<status>completed</status>\n<summary>Background command "Echo gamma" completed (exit code 0)</summary>')
|
||||
writeFileSync(transcript, [
|
||||
userEntry("t1", "Run the tests in the background, then wait.", {origin: {kind: "human"}}),
|
||||
userEntry("t1", [{type: "tool_result", tool_use_id: "toolu_1", content: "Command running in background with ID: buq1jepzn."}]),
|
||||
enqueueEntry(alpha),
|
||||
enqueueEntry("Also say the word bravo."),
|
||||
].join(""))
|
||||
const {client, requests} = turnClient()
|
||||
const submit = (promptId: string, prompt: string) => turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt}), {}, client, 0, 1, 10)
|
||||
const added = submit("t1", alpha)
|
||||
const queued = new Promise<void>(resolve => setTimeout(() => resolve(appendFileSync(transcript, `${queuedEntry(alpha, {kind: "task-notification", producer: "session-task"})}${queuedEntry("Also say the word bravo.", {kind: "human"})}`)), 30))
|
||||
await added
|
||||
await queued
|
||||
await submit("t1", "Also say the word bravo.")
|
||||
appendFileSync(transcript, [
|
||||
userEntry("t2", gamma, {origin: {kind: "task-notification"}}),
|
||||
enqueueEntry("Say the word charlie."),
|
||||
queuedEntry("Say the word charlie.", {kind: "human"}),
|
||||
userEntry("t3", "Then lint it.", {origin: {kind: "human"}}),
|
||||
].join(""))
|
||||
await submit("t2", gamma)
|
||||
await submit("t2", "Say the word charlie.")
|
||||
await submit("t2", "Then lint it.")
|
||||
expect(kinds(requests)).toEqual([
|
||||
['✅ Background command "Run the tests" completed (exit code 0)', false, true],
|
||||
[undefined, true, true],
|
||||
['✅ Background command "Echo gamma" completed (exit code 0)', false, undefined],
|
||||
[undefined, true, true],
|
||||
[undefined, true, true],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("send a note of a teammate's message with its sender and summary, or the first line without a summary, from the first tag that is not an idle notification, and none for idle notifications only", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const tag = (attributes: string, body: string) => `<teammate-message teammate_id="lookalikes-builder" color="green"${attributes}>\n${body}\n</teammate-message>`
|
||||
const teammate = (...tags: string[]) => `Another Claude session sent a message:\n${tags.join("\n\n")}\n\nThis came from another Claude session — not typed by your user.`
|
||||
const idle = tag("", '{"type":"idle_notification","from":"lookalikes-builder","timestamp":"2026-11-12T19:00:02.715Z"}')
|
||||
const prompts: [string, string][] = [
|
||||
["p1", teammate(tag(' summary="X Ads look-alike seed file "v2" written"', "The seed file is written.\n\nSeeds: 37 handles."))],
|
||||
["p2", teammate(tag("", "\nThe seed file is written.\n\nSeeds: 37 handles."))],
|
||||
["p3", teammate(idle)],
|
||||
["p4", teammate(idle, tag(' summary="Handles checked"', "All 37 handles are live."), idle)],
|
||||
["p5", teammate(idle, idle)],
|
||||
]
|
||||
writeFileSync(transcript, prompts.map(([promptId, content]) => userEntry(promptId, content)).join(""))
|
||||
const {client, requests} = turnClient()
|
||||
for (const [promptId, content] of prompts) await turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt: content}), {}, client, 0, 1, 1)
|
||||
expect(kinds(requests)).toEqual([
|
||||
['✉️ Message from lookalikes-builder: X Ads look-alike seed file "v2" written', false, undefined],
|
||||
["✉️ Message from lookalikes-builder: The seed file is written.", false, undefined],
|
||||
[undefined, false, undefined],
|
||||
["✉️ Message from lookalikes-builder: Handles checked", false, undefined],
|
||||
[undefined, false, undefined],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("keep a note on one line when the sender's name has a line break or a control character", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const prompts: [string, string, object][] = [
|
||||
["p1", 'Another Claude session sent a message:\n<agent-message from="a1">\nDone.\n</agent-message>', {origin: {kind: "peer", from: "a1", name: "mcp-impl2\nreviewer", body: "Done."}}],
|
||||
["p2", 'Another Claude session sent a message:\n<agent-message from="a2">\nAll done.\n</agent-message>', {origin: {kind: "peer", from: "a2", name: "ios\r\nterminal", body: "All done.", handback: true, handbackReportText: "All done."}}],
|
||||
["p3", 'Another Claude session sent a message:\n<teammate-message teammate_id="lookalikes\nbuilder" color="green">\nThe seed file is written.\n</teammate-message>', {}],
|
||||
]
|
||||
writeFileSync(transcript, prompts.map(([promptId, content, extra]) => userEntry(promptId, content, extra)).join(""))
|
||||
const {client, requests} = turnClient()
|
||||
for (const [promptId, content] of prompts) await turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt: content}), {}, client, 0, 1, 1)
|
||||
expect(kinds(requests)).toEqual([
|
||||
["✉️ Message from mcp-impl2 reviewer: Done.", false, undefined],
|
||||
["📋 Report from subagent ios terminal: All done.", false, undefined],
|
||||
["✉️ Message from lookalikes builder: The seed file is written.", false, undefined],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("find a prompt of a long turn whose first entry is out of the tail by the turn's tool results, and keep waiting for a prompt with the text of the turn's own prompt while it is queued", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const toolResult = (promptId: string) => userEntry(promptId, [{type: "tool_result", tool_use_id: "toolu_1", content: "ok"}])
|
||||
writeFileSync(transcript, [
|
||||
toolResult("t1"),
|
||||
enqueueEntry("Run the linter"),
|
||||
userEntry("t2", "continue", {origin: {kind: "human"}}),
|
||||
toolResult("t2"),
|
||||
enqueueEntry("continue"),
|
||||
].join(""))
|
||||
const {client, requests} = turnClient()
|
||||
const submit = (promptId: string, prompt: string, readMs = 1) => turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt}), {}, client, 0, 1, readMs)
|
||||
await submit("t1", "Run the linter")
|
||||
const again = submit("t2", "continue", 10)
|
||||
const queued = new Promise<void>(resolve => setTimeout(() => resolve(appendFileSync(transcript, queuedEntry("continue", {kind: "human"}))), 30))
|
||||
await again
|
||||
await queued
|
||||
expect(kinds(requests)).toEqual([
|
||||
[undefined, true, true],
|
||||
[undefined, true, true],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("classify a prompt by its record when a later prompt with its text is still queued after the reads: Claude Code's own prompt by its origin, as a repeated monitor event, and a typed prompt as typed and mid-turn", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const event = notification('<task-id>bfmkogk6v</task-id>\n<summary>Monitor event: "Build errors"</summary>\n<event>error: missing import</event>')
|
||||
writeFileSync(transcript, [
|
||||
enqueueEntry(event),
|
||||
userEntry("t1", event, {origin: {kind: "task-notification"}}),
|
||||
enqueueEntry(event),
|
||||
userEntry("t2", "continue", {origin: {kind: "human"}}),
|
||||
enqueueEntry("continue"),
|
||||
].join(""))
|
||||
const {client, requests} = turnClient()
|
||||
const submit = (promptId: string, prompt: string) => turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt}), {}, client, 0, 1, 1)
|
||||
await submit("t1", event)
|
||||
await submit("t2", "continue")
|
||||
expect(kinds(requests)).toEqual([
|
||||
['📡 Monitor event: "Build errors": error: missing import', false, undefined],
|
||||
[undefined, true, true],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("send the first line of a task notification without a block, also from a queued command that has only its command mode", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
const stopped = '3 background agents were stopped by the user: "Duarte drafts the ad post", "Miller drafts the ad post".'
|
||||
const stoppedAgain = '2 background agents were stopped by the user: "Heath brothers draft the ad post".'
|
||||
writeFileSync(transcript, [
|
||||
userEntry("t1", stopped, {origin: {kind: "task-notification"}}),
|
||||
`${JSON.stringify({type: "attachment", attachment: {type: "queued_command", prompt: stoppedAgain, commandMode: "task-notification"}})}\n`,
|
||||
].join(""))
|
||||
const {client, requests} = turnClient()
|
||||
for (const prompt of [stopped, stoppedAgain]) await turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: "t1", prompt}), {}, client, 0, 1, 1)
|
||||
expect(kinds(requests)).toEqual([
|
||||
[`🔔 ${stopped}`, false, undefined],
|
||||
[`🔔 ${stoppedAgain}`, false, true],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("take the entry of the prompt ID whose text is the prompt, also when an older prompt has the same text, mark a prompt still queued after the reads as typed and mid-turn, and fall back to the origin of the prompt ID's entry", async () => {
|
||||
const folder = mkdtempSync(join(tmpdir(), "simplex-mcp-transcript-"))
|
||||
try {
|
||||
const transcript = join(folder, "session.jsonl")
|
||||
writeFileSync(transcript, [
|
||||
userEntry("p1", "<system-reminder>\nTools used before the summary.\n</system-reminder>", {isMeta: true}),
|
||||
userEntry("p1", "Fix the build", {origin: {kind: "human"}}),
|
||||
userEntry("p2", notification("<status>completed</status>\n<summary>Agent \"Review\" finished</summary>"), {origin: {kind: "task-notification"}}),
|
||||
enqueueEntry("Run the linter"),
|
||||
].join(""))
|
||||
const {client, requests} = turnClient()
|
||||
const submit = (promptId: string, prompt: string) => turn(JSON.stringify({session_id: id, hook_event_name: "UserPromptSubmit", transcript_path: transcript, prompt_id: promptId, prompt}), {}, client, 0, 1, 1)
|
||||
await submit("p1", "Fix the build")
|
||||
await submit("p2", "Run the linter")
|
||||
await submit("p1", "Fix the build, then deploy")
|
||||
const again = submit("p3", "Fix the build")
|
||||
const written = new Promise<void>(resolve => setTimeout(() => resolve(appendFileSync(transcript, userEntry("p3", "Fix the build", {origin: {kind: "human"}}))), 30))
|
||||
await again
|
||||
await written
|
||||
expect(kinds(requests)).toEqual([
|
||||
[undefined, true, undefined],
|
||||
[undefined, true, true],
|
||||
[undefined, true, undefined],
|
||||
[undefined, true, undefined],
|
||||
])
|
||||
} finally {
|
||||
rmSync(folder, {recursive: true, force: true})
|
||||
}
|
||||
})
|
||||
|
||||
it("cut a prompt or an answer over 250,000 characters, so that the request fits the socket's 1 MiB", async () => {
|
||||
const {client, requests} = turnClient()
|
||||
await turn(JSON.stringify({session_id: id, last_assistant_message: `${"a".repeat(249_999)}😀${"b".repeat(1_000_000)}`}), {}, client)
|
||||
|
||||
@@ -697,6 +697,48 @@ describe("session channel", () => {
|
||||
expect(session["turns"]).toEqual([{at: 7, item: null}])
|
||||
})
|
||||
|
||||
it("posts the note of Claude Code's own prompt as Claude without a quote, and the answer of the turn it starts without a quote", async () => {
|
||||
const chat = new FakeChat()
|
||||
const {hub, session} = await channel(chat)
|
||||
const posts: string[] = []
|
||||
hub.user = {post: async (_n: number, parts: string[]) => void posts.push(parts.join(""))} as unknown as User
|
||||
const note = '✅ Background command "Build" completed (exit code 0)'
|
||||
await ownerPrompt(session, 42, "Fix the build")
|
||||
await session.turn({id: id1, at: 1, prompt: tag(42, "Fix the build"), typed: false})
|
||||
await session.turn({id: id1, at: 2, answer: "Fixed."})
|
||||
await session.turn({id: id1, at: 3, prompt: "<task-notification>\n<task-id>b1</task-id>\n</task-notification>", typed: false, note})
|
||||
await session.turn({id: id1, at: 4, answer: "The build passed."})
|
||||
expect(posts).toEqual([])
|
||||
expect(answers(chat)).toEqual([[{text: "Fixed.", quotedItemId: 42}], [{text: note, quotedItemId: undefined}], [{text: "The build passed.", quotedItemId: undefined}]])
|
||||
})
|
||||
|
||||
it("keeps the turn's quote and its open tool-use cards for a prompt that reaches the running turn, and adds a turn record for an owner's prompt among them", async () => {
|
||||
const chat = new FakeChat()
|
||||
const {hub, session} = await channel(chat)
|
||||
const posts: string[] = []
|
||||
hub.user = {post: async (_n: number, parts: string[]) => void posts.push(parts.join(""))} as unknown as User
|
||||
const note = '✅ Background command "Tests" completed (exit code 0)'
|
||||
await ownerPrompt(session, 42, "Fix the build")
|
||||
await session.turn({id: id1, at: 1, prompt: tag(42, "Fix the build"), typed: false})
|
||||
session.permission({id: id1, requestId: "abcde", toolName: "Bash", description: "Run shell command", inputPreview: "ls"})
|
||||
await until(() => sentTo(chat, 20).length === 1)
|
||||
const later = Date.now() + 1_000
|
||||
await session.turn({id: id1, at: later, prompt: "<task-notification>\n<task-id>b2</task-id>\n</task-notification>", typed: false, note, midTurn: true})
|
||||
await session.turn({id: id1, at: later + 1, prompt: "Also run the linter", typed: true, midTurn: true})
|
||||
expect(session.actions.pending().map(({tool}) => tool)).toEqual(["permission"])
|
||||
expect(chat.updates).toEqual([])
|
||||
await session.turn({id: id1, at: later + 2, answer: "Fixed, and the linter passes."})
|
||||
expect(posts).toEqual(["Also run the linter"])
|
||||
expect(answers(chat).slice(1)).toEqual([[{text: note, quotedItemId: undefined}], [{text: "Fixed, and the linter passes.", quotedItemId: 42}]])
|
||||
await until(() => chat.updates.length === 1)
|
||||
await ownerPrompt(session, 43, "Deploy")
|
||||
await session.turn({id: id1, at: later + 3, prompt: tag(43, "Deploy"), typed: false})
|
||||
await ownerPrompt(session, 44, "and tag it")
|
||||
await session.turn({id: id1, at: later + 4, prompt: tag(44, "and tag it"), typed: false, midTurn: true})
|
||||
await session.turn({id: id1, at: later + 5, answer: "Deployed and tagged."})
|
||||
expect(answers(chat).at(-1)).toEqual([{text: "Deployed and tagged.", quotedItemId: 44}])
|
||||
})
|
||||
|
||||
it("splits an answer and a terminal prompt where a message reaches the size the core accepts, with the quote in the first part of an answer, for Latin, Cyrillic and CJK texts", async () => {
|
||||
const chat = new FakeChat()
|
||||
const {hub, session} = await channel(chat)
|
||||
@@ -1241,6 +1283,14 @@ describe("session channel", () => {
|
||||
expect(groupPosts(chat)).toEqual([{type: "text", text: `Claude's answer was not posted: ${off("SimpleX links")}`}])
|
||||
})
|
||||
|
||||
it("posts that a note on Claude Code's prompt was not posted, naming the preference", async () => {
|
||||
const chat = new FakeChat()
|
||||
const {session} = await channel(chat)
|
||||
refuseInGroup(chat)
|
||||
await session.turn({id: id1, prompt: "Another Claude session sent a message: ...", typed: false, note: `✉️ Message from reviewer: Join ${link}`})
|
||||
expect(groupPosts(chat)).toEqual([{type: "text", text: `A note on Claude Code's prompt was not posted: ${off("SimpleX links")}`}])
|
||||
})
|
||||
|
||||
it("posts that User's prompt was not posted, naming the preference, and posts the answer", async () => {
|
||||
const chat = new FakeChat()
|
||||
const {hub, session} = await channel(chat)
|
||||
|
||||
@@ -0,0 +1,343 @@
|
||||
# SimpleX MCP: notes of Claude Code's own prompts
|
||||
|
||||
Status: implemented on `ep/mcp-harness-notes`. Q1 was answered A by the user on 2026-11-12. Code references: master `9d3241b06` (MCP 0.3.0). Claude Code references: version 2.1.322 and its binary at the offsets given; the transcripts of one machine, Claude Code 2.1.186 to 2.1.322; and two interactive sessions of Claude Code 2.1.322, recorded on 2026-11-12 with a UserPromptSubmit hook that logs its input. R1 has task notifications, a background subagent and a scheduled prompt. R2 has prompts that arrive during running turns. Decisions of the 0.3.0 plan are cited as "0.3.0 decision N".
|
||||
|
||||
## 1. Goal
|
||||
|
||||
Roadmap line, [ROADMAP.md:18](../packages/simplex-chat-mcp/ROADMAP.md): "See what Claude is doing while it works, with its code changes as diffs." This pull request covers its first part, Claude Code's own prompts. The diffs stay on the roadmap.
|
||||
|
||||
The user's words, 2026-11-12:
|
||||
|
||||
> I think it's in line with "show what claude is doing improvements, and maybe they could be one-line messages from claude itself?
|
||||
|
||||
> the this should be like the next PR, because I don't want to trade bad notifications for no notifications for a long time - they are kind of helpful even in their broken state
|
||||
|
||||
> agreed, and I propose add some emojis per type to differentiate them from the normal responses. Maybe this should be not "claude" (model) but "claude code" user (harness)? though it's more complex.
|
||||
|
||||
Before 0.3.0 decision 121, `User` posted Claude Code's own prompts whole, such as `<task-notification>` blocks. 0.3.0 posts nothing for them ([the 0.3.0 plan](2026-11-07-mcp-claude-code-channel.md)).
|
||||
|
||||
Outcome:
|
||||
- Each of Claude Code's own prompts appears in the session's group as one line, with an emoji for its kind.
|
||||
- Prompts typed in the terminal and messages of the group post nothing new.
|
||||
- A prompt that reaches a running turn is classified by its own record: `User` posts it when a person typed it, and Claude posts its note otherwise.
|
||||
|
||||
## 2. What users see
|
||||
|
||||
Claude posts one line in the session's group for each prompt of Claude Code itself. The line has no quote. When the prompt starts a turn, Claude's answer follows as before, without a quote.
|
||||
|
||||
Lines, each from a real prompt of Claude Code 2.1.281 to 2.1.322 in the transcripts or in R1:
|
||||
|
||||
```
|
||||
kind line
|
||||
task completed ✅ Background command "Rebuild tests and show errors or UsageStats warnings" completed (exit code 0)
|
||||
✅ MCP task kb5cik1y2 (simplex-demo/receive) completed.
|
||||
task failed ❌ Background command "Run agent and XFTP agent test suites" failed with exit code 1
|
||||
task stopped or killed ⏹️ Background shell command didn't finish before the previous session ended
|
||||
monitor event 📡 Monitor event: "Exit status of each of the 4 flag-combination builds": serverpg exit 0
|
||||
other task notification 🔔 Goal check-in: background work still running
|
||||
message of a session ✉️ Message from mcp-impl2: I read the channel-verify evidence, and it confirms your fact. I will record it in TESTING check 6 after round 6, with Claude Code 2.1.319, and I hold code changes until th…
|
||||
subagent report 📋 Report from subagent ios-terminal: ## iOS terminal layout: owner decisions and screenshot tests
|
||||
teammate's message ✉️ Message from lookalikes-builder: X Ads look-alike seed file written
|
||||
plain task notification 🔔 3 background agents were stopped by the user: "Duarte drafts the ad post", "Miller drafts the ad post", "Heath brothers draft the ad post".
|
||||
scheduled prompt ⏰ Scheduled prompt: Reply with the single word tick. (R1)
|
||||
automatic prompt 🔄 Automatic prompt: Your claude.ai usage limit has reset. Continue the task you were working on when the limit was reached; do not repeat work that is already complete.
|
||||
another kind ⚙️ Claude Code: FIRST LINE (no sample in the main transcripts)
|
||||
```
|
||||
|
||||
Rules of the line:
|
||||
```
|
||||
task notification: EMOJI SUMMARY, and ": EVENT" when the notification has an event
|
||||
SUMMARY the first line of <summary>, with < > & decoded; "Task notification" without one
|
||||
EVENT the first non-blank line of <event>, decoded the same way
|
||||
EMOJI <status> completed ✅, failed ❌, stopped or killed ⏹️;
|
||||
without <status>: 📡 with an event, 🔔 without
|
||||
without a block 🔔 and the first non-blank line of the prompt
|
||||
message of a session ✉️ Message from NAME: the first non-blank line of the message
|
||||
subagent report 📋 Report from subagent NAME: the first non-blank line of the report
|
||||
teammate's message ✉️ Message from NAME: its summary, or the first non-blank line of the message,
|
||||
from the first tag that is not an idle notification; nothing for idle notifications only
|
||||
scheduled prompt ⏰ Scheduled prompt: the first non-blank line of the prompt
|
||||
automatic prompt 🔄 Automatic prompt: the first non-blank line of the prompt
|
||||
another kind ⚙️ Claude Code: the first non-blank line of the prompt
|
||||
length at most 200 characters; a longer line keeps 199 and ends with …
|
||||
```
|
||||
|
||||
Nothing new is posted for:
|
||||
- a prompt typed in the terminal: `User` posts it, as in 0.3.0;
|
||||
- a channel prompt, such as a message of the group: it is already in the group;
|
||||
- a prompt whose record is not in the transcript within 60 s, as in 0.3.0.
|
||||
|
||||
Before and after:
|
||||
```
|
||||
prompt 0.3.0 this pull request
|
||||
task notification at a turn's start nothing Claude: one line
|
||||
task notification during a turn User: the whole block in a typed turn; Claude: one line
|
||||
nothing in another turn
|
||||
prompt typed during a turn User: the prompt in a typed turn; User: the prompt
|
||||
nothing in another turn
|
||||
message of a session, subagent report nothing Claude: one line
|
||||
scheduled or automatic prompt nothing Claude: one line
|
||||
```
|
||||
|
||||
When a group preference refuses the line, as "SimpleX links" refuses a line with a SimpleX link, Claude posts in its place:
|
||||
```
|
||||
A note on Claude Code's prompt was not posted: NAME are off in the group of this session; its owners can turn them on in the group's preferences.
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant B as background task
|
||||
participant CC as Claude Code
|
||||
participant HK as UserPromptSubmit hook
|
||||
participant D as service
|
||||
participant O as owner's app
|
||||
B->>CC: the task ends
|
||||
CC->>CC: a task notification starts a turn
|
||||
CC->>HK: {prompt_id, prompt}
|
||||
HK->>HK: the prompt's record in the transcript: origin task-notification
|
||||
HK->>D: POST /turn {prompt, typed: false, note}
|
||||
D->>O: Claude: ✅ Background command "Build" completed (exit code 0)
|
||||
CC->>CC: Claude answers
|
||||
CC->>D: Stop hook: POST /turn {answer}
|
||||
D->>O: Claude: the answer, without a quote
|
||||
```
|
||||
|
||||
During a turn, Claude Code adds a prompt to the running turn. The note appears then, before the turn's answer, and the answer still quotes the owner's prompt of the turn:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant O as owner's app
|
||||
participant CC as Claude Code
|
||||
participant HK as UserPromptSubmit hook
|
||||
participant D as service
|
||||
O->>D: Fix the build
|
||||
D->>CC: channel prompt, turn 1 starts
|
||||
CC->>CC: a background task ends during turn 1
|
||||
CC->>HK: {prompt_id of turn 1, the task notification}
|
||||
CC->>CC: the notification enters turn 1 as a queued command
|
||||
HK->>HK: its record: the queued command after turn 1's entry
|
||||
HK->>D: POST /turn {prompt, typed: false, note, midTurn: true}
|
||||
D->>O: Claude: ✅ Background command "Tests" completed (exit code 0)
|
||||
CC->>D: Stop hook of turn 1: POST /turn {answer}
|
||||
D->>O: Claude: the answer, quoting Fix the build
|
||||
```
|
||||
|
||||
## 3. Questions for the user
|
||||
|
||||
Q1. Who posts these lines? Answered A by the user on 2026-11-12.
|
||||
- A, recommended: Claude. Claude is in every session group already, so the lines appear in existing groups after the update. Claude's answers and the notes share one sender; the emoji tells them apart. Cost: the hook and one call in the hub, about 100 source lines.
|
||||
- B: a new member "Claude Code". It separates the harness from the model, as the user proposed. It adds a third profile of the service in `ROOT/_code`, with its own database and SimpleX connections, connected to Claude once, like `User`. Claude adds it to every new session group, and to each existing group at the first start after the update; it joins by itself. The hub drops its messages and leaves it out of approvers and rights posts. A group preference limited to roles above its own refuses its posts, with a text that names it. Each member sees one more member in every session group, and each member's app keeps one more connection per group. A member can hide all notes in the app with "Block member". Cost: about 150 more source lines and 150 more test lines than A, a change of the data folder, and conflicts with the agent profile item, which changes the profiles. B can follow A later without changing the lines.
|
||||
|
||||
## 4. Decisions
|
||||
|
||||
Facts:
|
||||
1. The UserPromptSubmit hook runs for every prompt that queries the model, Claude Code's own prompts included: `processUserInput` skips the hooks only when the prompt does not query, for a poll event, or with `skipSubmissionHooks` (binary 2.1.322 at 303247461: `!x.shouldQuery&&!as||y==="bash"||...||le===!0||$e===void 0`); `skipSubmissionHooks` is set only for poll events, empty dispatches, the repeated question of a closed card, orphaned permissions in remote sessions and the print loop's owed call (offsets 313424654, 313449609, 313560117, 313627254, 313694316, 322663513). R1 recorded the hook for task notifications, a scheduled prompt and typed prompts.
|
||||
2. A task notification that only records a result does not query, so it runs no hook: after a subagent's hand-back, its `Agent "..." finished` notification has no `turnOrigin` and no answer (a transcript of 2026-10-30).
|
||||
3. Claude Code adds a prompt that arrives during a turn to that turn as a `queued_command` attachment. It runs the UserPromptSubmit hooks then for a prompt whose hooks have not run ("prompt.submit at the fold", binary 302897343: `if(R??=SXo(n),!Wr(v)||!R)` and `fl`). The transcript entry has `type: attachment` and `attachment: {type: "queued_command", prompt, origin, commandMode}`, without `promptId` (builder at 296820244). Of 4,318 task-notification records in the main transcripts, 1,235 are such attachments.
|
||||
4. The hook's `prompt_id` is the current turn's prompt ID, `requestJournal.promptId()` (binary 296962410 `prompt_id:_F()`, 283172287). For a prompt added to a running turn, it is the running turn's ID. R2 recorded `prompt_id` of the running turn for a task notification added to a typed turn and for prompts typed during a typed turn and during a notification turn.
|
||||
5. Claude Code runs the hook of a typed prompt when the person submits it, also during a turn; it runs the hook of its own prompt only when the prompt is taken, at a turn's start or when added to a running turn (`Wr` at binary 302895135 skips a queued command with `promptSubmitted`. In R2 the hook of "Also say the word bravo." logged its input 41 ms after the prompt's `queue-operation` `enqueue` entry; the hook of a task notification logged it 22 s after the notification's `enqueue` entry, when the running tool ended).
|
||||
6. A prompt's record carries its text: the entry with `promptId` for a turn's start, the `queued_command` attachment for a prompt added to a turn, and a later entry with a new `promptId` for a typed prompt that waits for its own turn. In R1, R2 and the channel run recorded for 0.3.0 (TESTING.md, check 6), each hook's `prompt` equals the text of exactly one record, 16 prompts in all. One prompt ID can have several entries: the channel run has a meta `<system-reminder>` entry before the prompt's entry with the same `promptId`.
|
||||
7. The origin kinds in 2.1.322 are `human`, `task-notification`, `peer`, `channel`, `auto-continuation`, `coordinator`, `observer`, `observer-activity`, `slack-ping`, `unclassified`, `voice-call` and `plugin` (`RCi` at binary 295246396). A scheduled prompt has no `origin`; its entry has `turnOrigin: "scheduled"`, `scheduledTaskId` and `isMeta: true` (R1; 452 entries in the transcripts).
|
||||
8. Task notifications: `<summary>` in 4,318 of 4,318; `<status>` `completed`, `failed`, `stopped` or `killed`; `<event>` in monitor events and artifact watches; one block per prompt. `<summary>` and `<event>` contain only the entities `&`, `>` and `<` (transcripts).
|
||||
9. A message of another session has `origin: {kind: "peer", from, name, senderTaskId, body}`, with `body` equal to the text in `<agent-message from="...">` or `<cross-session-message ...>`. A subagent's hand-back adds `handback: true` and, since 2.1.302, `handbackReportText`, the report without its frame. `name` is the agent's name, or its type, such as `general-purpose`, for an unnamed agent (transcripts). `<agent-message>` has no `summary` attribute. A message of a teammate in an agent team has no `origin`: its prompt is `Another Claude session sent a message:` and a `<teammate-message teammate_id="NAME" color="..." summary="...">` tag, with an optional `summary` escaped as XML (binary 292849344). Of 2,096 teammate message tags in the transcripts, 1,762 hold an idle notification, a JSON body with `"type":"idle_notification"`.
|
||||
10. `auto-continuation` is the origin of the usage-limit continuation (binary 308243173) and of other automatic prompts, such as "Implement the following plan:" after plan mode (324005632) and a command's next input (324147282).
|
||||
11. 0.3.0 finds the entry with `prompt_id` and takes the first one ([hook.ts:172](../packages/simplex-chat-mcp/src/hook.ts#L172)), whatever its text. So a task notification added to a typed turn is marked typed, and `User` posts the block; a prompt typed during a notification or channel turn is not typed, and `User` does not post it.
|
||||
12. 0.3.0 adds a turn record with the hook's `at` for every prompt request whose hook started no earlier than the hook of the last answer handled (`answeredAt`), and ends open tool-use cards created before it at every prompt and answer ([hub.ts:181](../packages/simplex-chat-mcp/src/hub.ts#L181), [:185](../packages/simplex-chat-mcp/src/hub.ts#L185)). A record without an item, added during a turn, takes the place of that turn's prompt in its answer's quote ([hub.ts:266-275](../packages/simplex-chat-mcp/src/hub.ts#L266-L275)).
|
||||
|
||||
Choices:
|
||||
|
||||
13. Claude posts the notes (Q1 A). `User`'s posts keep meaning prompts a person typed (0.3.0 decision 121).
|
||||
14. The hook composes the line and sends it as `note` in `POST /turn`; the hub posts it unchanged as one message of Claude, without a quote ([hub.ts:289-295](../packages/simplex-chat-mcp/src/hub.ts#L289-L295)).
|
||||
15. The hook finds the prompt's record by its text, so that a prompt added to a running turn gets its own origin. The record is the newest of these whose text is the prompt: the entry with `prompt_id`, and the records after the first entry with `prompt_id`, both user entries and `queued_command` attachments. Until an entry with `prompt_id` is in the tail, the hook waits for it, so that an older prompt with the same text is not taken; at the last read it takes any record of the tail. User entries of subagents and tool results are skipped, as in 0.3.0. Without `prompt_id`, the newest such record at once. The hook reads up to 600 times, 100 ms apart, as in 0.3.0.
|
||||
16. After the last read without a record, a `queue-operation` `enqueue` entry with the prompt's text after the entry with `prompt_id` makes the prompt typed and mid-turn: by fact 5, only a submitted prompt runs its hook while it waits. Otherwise the prompt is typed when an entry with `prompt_id` has the origin `human`, past a meta entry without origin, and it gets no note.
|
||||
17. A prompt is mid-turn when its record is not an entry with `prompt_id`. The hook sends `midTurn: true` for it.
|
||||
18. A mid-turn prompt ends no tool-use card. It adds a turn record only when it matched a pushed prompt and, as every prompt, its hook started no earlier than the hook of the last answer handled (`answeredAt`). So the answer of the turn quotes the turn's prompt, or an owner's prompt added to the turn, as in 0.3.0. It amends 0.3.0 decisions 29 and 39.
|
||||
19. The kind comes from the record's `origin.kind`, and from `turnOrigin: "scheduled"` without `origin`. `human` is typed. `channel` gets no note: its messages are in the group, or come from another channel's people, and Claude's answer is posted. A record without `origin` and not scheduled gets no note.
|
||||
20. The note of a subagent's report uses `handbackReportText`, and `body` without it.
|
||||
21. A line has at most 200 characters, counted in code points; a longer line keeps 199 and ends with `…`. In each first line and in NAME, control and format characters become spaces, as in [log.ts:33-35](../packages/simplex-chat-mcp/src/log.ts#L33-L35), so a note is one line. Of 5,127 notes computed from this machine's transcripts, 1,279 are cut.
|
||||
22. A note refused by a group preference is replaced by Claude's post `A note on Claude Code's prompt was not posted: ` and PREF OFF, by the path of 0.3.0 decision 114 ([hub.ts:283-287](../packages/simplex-chat-mcp/src/hub.ts#L283-L287)).
|
||||
23. Notes are posted when their request arrives, in the order of the hooks' requests, as answers and `User`'s prompts are. A turn's UserPromptSubmit hook starts before its Stop hook; a mid-turn prompt's hook starts during the turn.
|
||||
24. The protocol version stays 1: `note` and `midTurn` are optional, and a service without them posts nothing for them, as 0.3.0.
|
||||
|
||||
Decided after review round 1 of `9c78e6276`:
|
||||
|
||||
25. A teammate's message gets `✉️ Message from NAME: `, as a message of another session, and its `summary`, or the first line of the message without one, cut to 200. The note is made from the first tag that is not an idle notification, and a prompt of idle notifications only gets no note (fact 9, decision 31). The user, 2026-11-12, on the first emoji of this note: "👥 this looks horrible".
|
||||
26. The first entry with `prompt_id` is any user entry of the main conversation with that ID, a tool result included: a long turn's first entry can be more than 1 MiB back, and its tool results carry its ID. The `enqueue` fallback of decision 16 also applies when no entry with `prompt_id` is in the tail.
|
||||
27. While an `enqueue` entry with the prompt's text follows the found record, the hook waits: the prompt is a later one with the text of the turn's own prompt, still queued. An `enqueue` entry precedes the record of every queued prompt in R2.
|
||||
28. A task notification without a `<task-notification>` block, such as `3 background agents were stopped by the user: ...`, gets 🔔 and its first line. A `queued_command` attachment without `origin` and with the `commandMode` `task-notification` is a task notification.
|
||||
|
||||
Decided after review round 2 of `ef93ce0dd`:
|
||||
|
||||
29. At the last read, the hook classifies a record still followed by an `enqueue` entry with its text by the record, and marks a typed record mid-turn. Claude Code runs the hook of its own prompt only when the prompt is taken (fact 5), so at the last read the queued prompt is a later one with the same text, such as a repeated monitor event. Before, the hook marked such a prompt typed, and `User` posted its block. The fallback of decision 16 applies only without a record.
|
||||
30. The wait of decision 27 stays. The hook of Claude Code's own prompt added to a turn can read the transcript before the fold's entries are written, and without the wait it would take the record of an earlier prompt with its text. In R2 the hook of the task notification started with a transcript of 292,045 bytes, before the tool result, the `remove` entries and the `queued_command` attachment. So when a later prompt with the text of a turn's own prompt is added to that turn within the reads, the hook of the turn's prompt takes the later record. Its note is the same line, it is mid-turn, and the turn gets no turn record: the answer then quotes the oldest pushed prompt not quoted yet, when there is one ([hub.ts:268-272](../packages/simplex-chat-mcp/src/hub.ts#L268-L272)).
|
||||
31. A teammate's prompt can have several `<teammate-message>` tags, separated by blank lines. Of 1,903 teammate prompts in the transcripts, 204 have several tags, and 54 of these have an idle notification first and a message after it; 1,084 have only idle notifications.
|
||||
|
||||
## 5. Design
|
||||
|
||||
Options for where the line is made:
|
||||
```
|
||||
option producer (hook) consumer (hub) wire older parts
|
||||
H. hook composes, sends note parses the record and the posts note + note, + midTurn old hook: no note, as 0.3.0
|
||||
(chosen) prompt: about 90 lines
|
||||
S. hook sends origin, hub composes sends origin, turnOrigin parses the prompt and origin; + origin with body: a message old hook: no note, as 0.3.0
|
||||
learns Claude Code's formats twice, up to 250,000 each
|
||||
M. Claude writes the line none none none channel instructions; tokens
|
||||
on every prompt
|
||||
```
|
||||
S costs more at the consumer and on the wire for the same lines. M costs tokens on every prompt and depends on the model following an instruction.
|
||||
|
||||
Options for finding the record of a prompt added to a running turn:
|
||||
```
|
||||
option cost
|
||||
text match among records (chosen) one pass over the tail's records; exact by fact 6
|
||||
prompt ID only, as 0.3.0 wrong origin for every mid-turn prompt (fact 11)
|
||||
the prompt's text decides the kind a typed prompt that starts with <task-notification> becomes a note; no name or report
|
||||
entry time against the hook's start Claude Code writes entries before and after the hook (R1, R2): no reliable bound
|
||||
```
|
||||
|
||||
Options for who posts: Q1.
|
||||
|
||||
Changes:
|
||||
```
|
||||
file function change
|
||||
src/protocol.ts TurnRequest + note?: string, + midTurn?: boolean
|
||||
src/hook.ts TranscriptEntry + turnOrigin, attachment {type, prompt, origin}, operation, content
|
||||
turn typed, note and midTurn from promptKind
|
||||
promptTyped -> promptKind the record (decisions 15-17); typed, note, midTurn
|
||||
promptEntry -> promptRecord records by text; the last read applies decision 16
|
||||
findInTranscript find gets the last read's flag
|
||||
noteOf, taskNote, firstLine the line (section 2, decisions 19-21)
|
||||
src/hub.ts Session.turn endPermissions skips mid-turn prompts, and the turn record skips those
|
||||
that matched no pushed prompt (decision 18);
|
||||
post note as Claude, PREF OFF on refusal (decision 22)
|
||||
```
|
||||
|
||||
Hook:
|
||||
```
|
||||
on UserPromptSubmit {prompt_id, prompt, transcript_path}:
|
||||
text = trimmed prompt; blank: typed false, no note
|
||||
read the tail up to 600 times, 100 ms apart:
|
||||
records = user entries without isSidechain and tool results, and queued_command attachments
|
||||
first = the first entry with promptId = prompt_id
|
||||
record = the newest record whose text is text: at or after first, or anywhere without first
|
||||
found, and no enqueue entry of content text after it: stop
|
||||
first absent and prompt_id given: wait, except at the last read
|
||||
last read, a record with an enqueue entry of content text after it:
|
||||
the record's kind; a typed record is also mid-turn
|
||||
last read, no record:
|
||||
an enqueue entry of content text after first: typed true, midTurn true, no note
|
||||
else: typed = an entry with promptId = prompt_id has origin.kind human; no note
|
||||
typed = record.origin.kind = human
|
||||
midTurn = record is not an entry with promptId = prompt_id
|
||||
note = noteOf(record, prompt), cut to 200
|
||||
POST /turn {id, pid, at, prompt, typed, note?, midTurn?, effort}
|
||||
```
|
||||
|
||||
Hub:
|
||||
```
|
||||
on POST /turn, before any await:
|
||||
prompt and not midTurn, or answer: end tool-use cards created before at
|
||||
prompt, at not below answeredAt, and (not midTurn, or matched):
|
||||
turns += (at, the oldest matched or null)
|
||||
then:
|
||||
note: Claude posts [note], no quote; refused by NAME: Claude posts
|
||||
"A note on Claude Code's prompt was not posted: " + PREF OFF
|
||||
typed prompt: User posts it, as in 0.3.0
|
||||
answer: Claude posts it, as in 0.3.0
|
||||
```
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
T[transcript tail] --> R{record of the prompt's text}
|
||||
R -- entry with prompt_id --> S[turn start]
|
||||
R -- queued_command or later entry --> M[mid-turn]
|
||||
R -- none, enqueue entry --> Q[typed, mid-turn]
|
||||
S --> K{origin.kind or turnOrigin}
|
||||
M --> K
|
||||
K -- human --> U[typed: User posts]
|
||||
K -- channel --> N[nothing]
|
||||
K -- others --> L[note: Claude posts one line]
|
||||
M --> X[no card ended; record only for a matched owner prompt whose hook started no earlier than answeredAt]
|
||||
```
|
||||
|
||||
## 6. Compatibility
|
||||
|
||||
- Older SimpleX apps: notes are text messages with emoji, shown by every version.
|
||||
- Older Claude Code: without `origin`, nothing is posted, as in 0.3.0, except a teammate's message, found by its tag. Without `prompt_id`, the record is the newest one with the prompt's text. Before 2.1.302 a report's note shows the first line of `body`, the frame's first line. Without `queued_command` attachments, the fallback of decision 16 applies.
|
||||
- Older plugin data folders: no data changes. A service of this version with an older hook gets no `note` and no `midTurn`, and behaves as 0.3.0. The hook stops a service only when its version is older ([client.ts:37-40](../packages/simplex-chat-mcp/src/client.ts#L37-L40)), so an older service with this hook does not occur once the release bumps the version. `package.json` stays at 0.3.0 here; the release pull request bumps it.
|
||||
- `serve`: unchanged.
|
||||
|
||||
## 7. Acceptance and tests
|
||||
|
||||
Done when:
|
||||
```
|
||||
# criterion checked by
|
||||
1 each kind of section 2 gives its exact line, cut at 200 unit: hook
|
||||
2 a typed prompt, a channel prompt and a missing record give no note unit: hook
|
||||
3 a task notification added to a typed turn is a note and not typed; User does not post it unit: hook; e2e
|
||||
4 a prompt typed during a notification turn is typed and mid-turn; User posts it unit: hook
|
||||
5 the entry with prompt_id is taken by its text, past a meta entry with the same ID unit: hook
|
||||
6 a typed prompt still queued after the reads is typed and mid-turn unit: hook
|
||||
7 Claude posts the note without a quote; the answer of a notification turn has no quote unit: sessions; e2e
|
||||
8 a mid-turn note keeps the turn's quote and its open tool-use cards unit: sessions
|
||||
9 a refused note is replaced by the PREF OFF post unit: sessions
|
||||
10 a request without note and midTurn behaves as in 0.3.0 existing unit and e2e tests unchanged
|
||||
11 real session: a background command, a subagent and a scheduled prompt show their lines TESTING check
|
||||
12 the note of Claude Code's prompt is sent while a repeat of its text is queued after the reads unit: hook
|
||||
13 a teammate's message after idle notifications in one prompt gets its note unit: hook
|
||||
14 a sender's name with a line break or a control character keeps the note on one line unit: hook
|
||||
```
|
||||
|
||||
Tests:
|
||||
- `test/unit/hook.test.ts`, new, in "turn hooks":
|
||||
- "send a one-line note of each kind of Claude Code's own prompt, from the origin of its transcript entry, and none for a typed or a channel prompt": entries of R1 and of this machine's transcripts, with paths replaced. It fails on master, which sends no `note`.
|
||||
- "find a prompt that reaches a running turn by its queued command or its own later entry after the entry of the turn's prompt ID, and mark it mid-turn": the R2 records. With master, the notification in the typed turn is typed and "Say the word charlie." is not, so it fails.
|
||||
- "take the entry of the prompt ID whose text is the prompt, also when an older prompt has the same text, mark a prompt still queued after the reads as typed and mid-turn, and fall back to the origin of the prompt ID's entry".
|
||||
- "send a note of a teammate's message with its sender and summary, or the first line without a summary, from the first tag that is not an idle notification, and none for idle notifications only". On `ef93ce0dd` the prompt with an idle notification before a message gets no note.
|
||||
- "keep a note on one line when the sender's name has a line break or a control character". On `bbfd9c88d` the notes have the names' line breaks.
|
||||
- "find a prompt of a long turn whose first entry is out of the tail by the turn's tool results, and keep waiting for a prompt with the text of the turn's own prompt while it is queued".
|
||||
- "classify a prompt by its record when a later prompt with its text is still queued after the reads: Claude Code's own prompt by its origin, as a repeated monitor event, and a typed prompt as typed and mid-turn". On `ef93ce0dd` the monitor event is typed and mid-turn.
|
||||
- "send the first line of a task notification without a block, also from a queued command that has only its command mode".
|
||||
- The tests build the records of R1 and R2 in their own code, so the test of 0.3.0 decision 121 stays unchanged and no fixture file is added.
|
||||
- `test/unit/sessions.test.ts`, new, in "session channel":
|
||||
- "posts the note of Claude Code's own prompt as Claude without a quote, and the answer of the turn it starts without a quote". It fails on master: nothing is posted.
|
||||
- "keeps the turn's quote and its open tool-use cards for a prompt that reaches the running turn, and adds a turn record for an owner's prompt among them". It fails on master: the answer loses the quote and the card ends.
|
||||
- "posts that a note on Claude Code's prompt was not posted, naming the preference", in "while a preference of the session group refuses a post".
|
||||
- `test/e2e/service.test.ts`, changed: the mirroring test, now "the hooks post a prompt typed in the terminal as User, also the session's first one whose hook starts before the transcript file is created, a task notification at a turn's start or within a running turn as Claude's one-line note, ...". It adds a summary to its notification, expects Claude's line and no post of `User`, and adds a failed task as a queued command of the running notification turn `p2`.
|
||||
- Run: `npm test --prefix packages/simplex-chat-mcp` for unit tests, and the end-to-end tests as TESTING.md states. The reduced build runs them in CI. No app changes, so no app test workflows.
|
||||
|
||||
## 8. Docs to change
|
||||
|
||||
- `README.md:36`: Claude Code's own prompts appear as one line each.
|
||||
- `REFERENCE.md`, "Prompts and answers" (603-616): the lines, the kinds, the cut, the refusal text; `User` posts typed prompts also when typed during a turn.
|
||||
- `ROADMAP.md:18` stays as it is: the line also names the diffs.
|
||||
- `spec/flows.md`: flow 21 notes; a new flow, a prompt of Claude Code at a turn's start and during a turn.
|
||||
- `spec/api.md`: 4.3 (Claude's posts), 4.6 (`POST /turn` with `note` and `midTurn`), the hook's record rules (1020).
|
||||
- `spec/architecture.md`: 8.2 (`promptKind`, `promptRecord`, `noteOf`), 8.6 (the wire and the turn rules).
|
||||
- `TESTING.md:156`, `:173`: the new tests; a real-session check of the three kinds.
|
||||
|
||||
## 9. Conflict areas with the other items
|
||||
|
||||
```
|
||||
file where items
|
||||
src/hub.ts Session.turn (180-201) mcp-replies (quotes, pushed prompts), mcp-reactions
|
||||
src/protocol.ts TurnRequest (48-57), AttachLine (59-62) mcp-replies, mcp-reactions (AttachLine)
|
||||
test/unit/sessions.test.ts turn and answer tests (624-910) mcp-replies, mcp-reactions
|
||||
test/e2e/service.test.ts the mirroring test (351-417) mcp-replies, mcp-reactions
|
||||
REFERENCE.md "Prompts and answers" (603-616) mcp-replies, mcp-reactions
|
||||
spec/flows.md, api.md, flows 20-21, 4.3, 4.6, 8.6 mcp-replies, mcp-reactions
|
||||
architecture.md
|
||||
ROADMAP.md lines 18-20, adjacent mcp-reactions (19), mcp-replies (20)
|
||||
src/user.ts, Hub.open, only with Q1 B mcp-agent-profile
|
||||
createSessionGroup
|
||||
```
|
||||
|
||||
## 10. Estimate
|
||||
|
||||
```
|
||||
part source lines test lines
|
||||
hook.ts 90 150, and the fixture
|
||||
hub.ts, protocol.ts 10 90
|
||||
docs 60 lines of text
|
||||
```
|
||||
About one working day, with two review rounds. Q1 B adds about 150 source lines, 150 test lines and a day.
|
||||
Reference in new issue
Block a user