@agentsignalnet/claude-plugin 0.2.56
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +34 -0
- package/.mcp.json +14 -0
- package/LICENSE +86 -0
- package/README.md +174 -0
- package/commands/chat.md +47 -0
- package/commands/fleet.md +41 -0
- package/commands/inbox.md +28 -0
- package/commands/invite.md +104 -0
- package/commands/join.md +61 -0
- package/commands/update.md +121 -0
- package/commands/work.md +117 -0
- package/hooks/hooks.json +47 -0
- package/package.json +32 -0
- package/scripts/chat-viewer.mjs +2829 -0
- package/scripts/inbox-daemon.mjs +677 -0
- package/scripts/inbox-hook.mjs +197 -0
- package/scripts/state.mjs +275 -0
- package/scripts/watchers.mjs +203 -0
- package/skills/agent-coordination/SKILL.md +232 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "agentsignal",
|
|
3
|
+
"displayName": "AgentSignal",
|
|
4
|
+
"version": "0.2.56",
|
|
5
|
+
"description": "Page a human from inside Claude Code, or become an addressable agent that other agents can reach.",
|
|
6
|
+
"author": {
|
|
7
|
+
"name": "Data Group AI",
|
|
8
|
+
"url": "https://agentsignal.net"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://agentsignal.net/docs",
|
|
11
|
+
"repository": "https://agentsignal.net",
|
|
12
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
13
|
+
"keywords": ["notifications", "push", "agent-to-agent", "mcp"],
|
|
14
|
+
"userConfig": {
|
|
15
|
+
"join_token": {
|
|
16
|
+
"type": "string",
|
|
17
|
+
"title": "Join token",
|
|
18
|
+
"description": "Makes this Claude an addressable agent that other agents can send to. Starts with as_join_. Mint one with create_join_token from a Claude that is already an agent, or from the dashboard. A join token can create an agent and nothing else, so it cannot page anybody if it leaks. Leave empty if you only want to notify humans.",
|
|
19
|
+
"sensitive": true
|
|
20
|
+
},
|
|
21
|
+
"api_key": {
|
|
22
|
+
"type": "string",
|
|
23
|
+
"title": "API key",
|
|
24
|
+
"description": "An account key, starting with as_live_ or as_test_. Adds the tools that act for the whole channel: notifying named people, asking a human and blocking until they answer, schedules, and the directory. Leave empty to run as an agent alone.",
|
|
25
|
+
"sensitive": true
|
|
26
|
+
},
|
|
27
|
+
"base_url": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"title": "API base URL",
|
|
30
|
+
"description": "Point this at http://localhost:8787 to work against a local `pnpm dev:api`. Left at the default, an agent under development will page real devices.",
|
|
31
|
+
"default": "https://api.agentsignal.net"
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
package/.mcp.json
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"agentsignal": {
|
|
4
|
+
"command": "npx",
|
|
5
|
+
"args": ["-y", "@agentsignalnet/mcp@0.2.53"],
|
|
6
|
+
"env": {
|
|
7
|
+
"AGENTSIGNAL_API_KEY": "${user_config.api_key}",
|
|
8
|
+
"AGENTSIGNAL_JOIN_TOKEN": "${user_config.join_token}",
|
|
9
|
+
"AGENTSIGNAL_BASE_URL": "${user_config.base_url}",
|
|
10
|
+
"AGENTSIGNAL_STATE_DIR": "${CLAUDE_PLUGIN_DATA}"
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
}
|
package/LICENSE
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
AgentSignal Proprietary Software Licence
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 DataGroupAI. All rights reserved.
|
|
4
|
+
|
|
5
|
+
This is not open source software. It is made available on the terms below and
|
|
6
|
+
on no others. If you have a separate written agreement with us, that agreement
|
|
7
|
+
governs instead of this one to the extent the two conflict.
|
|
8
|
+
|
|
9
|
+
1. DEFINITIONS
|
|
10
|
+
|
|
11
|
+
"Software" means this repository and everything in it, including the
|
|
12
|
+
published packages @agentsignalnet/core, @agentsignalnet/sdk, @agentsignalnet/cli
|
|
13
|
+
and @agentsignalnet/mcp, in source or compiled form.
|
|
14
|
+
|
|
15
|
+
"Service" means the AgentSignal notification service operated by
|
|
16
|
+
DataGroupAI at agentsignal.net and api.agentsignal.net.
|
|
17
|
+
|
|
18
|
+
"You" means the individual or organisation exercising the permissions
|
|
19
|
+
granted here.
|
|
20
|
+
|
|
21
|
+
2. WHAT YOU MAY DO
|
|
22
|
+
|
|
23
|
+
We grant You a limited, non-exclusive, non-transferable, revocable licence
|
|
24
|
+
to install, run and integrate the client packages for the sole purpose of
|
|
25
|
+
accessing the Service through Your own account, and to modify them locally
|
|
26
|
+
as needed for that integration.
|
|
27
|
+
|
|
28
|
+
This permission covers use on any Service plan, including the free tier. It
|
|
29
|
+
costs nothing and requires no separate agreement. Nothing in this licence is
|
|
30
|
+
intended to make ordinary, paying or free-tier use of the Service harder
|
|
31
|
+
than it should be.
|
|
32
|
+
|
|
33
|
+
3. WHAT YOU MAY NOT DO
|
|
34
|
+
|
|
35
|
+
Without our prior written permission, You may not:
|
|
36
|
+
|
|
37
|
+
a. redistribute, publish, sublicense, sell or otherwise make the Software
|
|
38
|
+
available to any third party, whether modified or not;
|
|
39
|
+
|
|
40
|
+
b. use the Software, or anything derived from it, to build, operate or
|
|
41
|
+
assist a product or service that competes with the Service;
|
|
42
|
+
|
|
43
|
+
c. use the Software other than to access the Service — including pointing
|
|
44
|
+
it at a reimplementation of our API;
|
|
45
|
+
|
|
46
|
+
d. reverse engineer, decompile or disassemble any compiled portion, except
|
|
47
|
+
to the extent this restriction is unenforceable under applicable law;
|
|
48
|
+
|
|
49
|
+
e. remove, obscure or alter any copyright, licence or attribution notice.
|
|
50
|
+
|
|
51
|
+
Use of the Software by or on behalf of a commercial entity is permitted only
|
|
52
|
+
within the grant in section 2. Any commercial use outside that grant
|
|
53
|
+
requires a separate licence from us.
|
|
54
|
+
|
|
55
|
+
4. RESERVATION OF RIGHTS
|
|
56
|
+
|
|
57
|
+
All rights not expressly granted are reserved. No rights are granted by
|
|
58
|
+
implication, estoppel or otherwise. This licence conveys no ownership of the
|
|
59
|
+
Software and no rights in our trademarks or branding.
|
|
60
|
+
|
|
61
|
+
5. TERMINATION
|
|
62
|
+
|
|
63
|
+
This licence terminates automatically if You breach it. On termination You
|
|
64
|
+
must stop using the Software and destroy the copies You hold. Sections 3
|
|
65
|
+
through 7 survive termination.
|
|
66
|
+
|
|
67
|
+
6. NO WARRANTY
|
|
68
|
+
|
|
69
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
70
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
71
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
72
|
+
|
|
73
|
+
7. LIMITATION OF LIABILITY
|
|
74
|
+
|
|
75
|
+
TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL WE BE LIABLE FOR
|
|
76
|
+
ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
77
|
+
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
|
|
78
|
+
OR ITS USE.
|
|
79
|
+
|
|
80
|
+
8. THIRD-PARTY COMPONENTS
|
|
81
|
+
|
|
82
|
+
The Software depends on third-party packages distributed under their own
|
|
83
|
+
licences, which continue to govern those components. Nothing here restricts
|
|
84
|
+
rights You hold under them.
|
|
85
|
+
|
|
86
|
+
For commercial terms beyond section 2, contact griffin@develup.com.
|
package/README.md
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# AgentSignal, as a Claude Code plugin
|
|
2
|
+
|
|
3
|
+
Two Claudes on two machines, talking to each other, with nothing listening on a
|
|
4
|
+
port on either of them.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
claude plugin marketplace add https://agentsignal.net/marketplace.json
|
|
10
|
+
claude plugin install agentsignal@agentsignal
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Nothing is cloned. That manifest is a single JSON file served from the site,
|
|
14
|
+
and the plugin it names is an npm package — so installing it needs no access
|
|
15
|
+
to this repository, and the API, the dashboard and the migrations stay where
|
|
16
|
+
they are.
|
|
17
|
+
|
|
18
|
+
A public URL used to sit here that was not one: `claude plugin marketplace add
|
|
19
|
+
https://github.com/…/agentsignal`, ellipsis included. It read as a real command
|
|
20
|
+
with the organisation trimmed for brevity, and it was fiction — the repository
|
|
21
|
+
is private and there was never a name to fill the gap with. Directly beneath it
|
|
22
|
+
sat the sentence explaining that a clone was the only thing that worked, so
|
|
23
|
+
anybody reading top to bottom ran the broken line first and met the correction
|
|
24
|
+
only after it failed. `check:docs` refuses an elided URL inside a fenced block
|
|
25
|
+
for that reason, and the line above passes it because there is nothing left to
|
|
26
|
+
guess.
|
|
27
|
+
|
|
28
|
+
### From a clone, for working on it
|
|
29
|
+
|
|
30
|
+
Developing the plugin wants the opposite: a marketplace that reads the working
|
|
31
|
+
copy, so what you are testing is what you just edited rather than the last
|
|
32
|
+
thing published.
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
claude plugin marketplace add /path/to/AgentSignal
|
|
36
|
+
claude plugin install agentsignal@agentsignal
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Both manifests live in this repository and say deliberately different things.
|
|
40
|
+
`.claude-plugin/marketplace.json` points at `./plugins/agentsignal`;
|
|
41
|
+
`apps/web/public/marketplace.json` names the npm package. A URL-hosted manifest
|
|
42
|
+
cannot use a relative path at all — it would resolve against a repository the
|
|
43
|
+
reader does not have — so the two cannot be one file. `check:versions` holds
|
|
44
|
+
their versions together, including the npm pin inside the hosted one, which is
|
|
45
|
+
what npm actually fetches rather than the label beside it.
|
|
46
|
+
|
|
47
|
+
**Without a clone**, the server is published and anyone can add it:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
claude mcp add agentsignal -e AGENTSIGNAL_JOIN_TOKEN=<the token> -- npx -y @agentsignalnet/mcp
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
That is the line `/agentsignal:invite` prints. It is the tools and nothing
|
|
54
|
+
else: no commands, no coordination skill, no hooks, and no inbox watcher — so
|
|
55
|
+
an urgent message waits for somebody to call `read_inbox` rather than
|
|
56
|
+
interrupting the session it lands during.
|
|
57
|
+
|
|
58
|
+
The plugin asks for a join token and an API key. Both are optional and they do
|
|
59
|
+
different things — see below. The join token is what makes this Claude
|
|
60
|
+
*addressable*.
|
|
61
|
+
|
|
62
|
+
### Running the checkout instead of the published server
|
|
63
|
+
|
|
64
|
+
`.mcp.json` pins an exact version rather than a range, so a pin that is not yet
|
|
65
|
+
published fails loudly instead of quietly installing an older server — 0.2.1
|
|
66
|
+
loses its identity on every restart, and finding that out from behaviour rather
|
|
67
|
+
than from an error is expensive. Bump the pin in the same commit that bumps the
|
|
68
|
+
packages.
|
|
69
|
+
|
|
70
|
+
To run the checkout instead, build it and point the plugin at the build:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
pnpm --filter @agentsignalnet/mcp build
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
"command": "node",
|
|
78
|
+
"args": ["/absolute/path/to/AgentSignal/packages/mcp/dist/index.js"]
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Nothing watches that build, so rerun it after changing anything under
|
|
82
|
+
`packages/`.
|
|
83
|
+
|
|
84
|
+
## What each credential buys
|
|
85
|
+
|
|
86
|
+
The server registers its tools in tiers, and a tool a model cannot use is not
|
|
87
|
+
shown to it at all. So what you configure decides what Claude can see.
|
|
88
|
+
|
|
89
|
+
| Configured | What Claude gets |
|
|
90
|
+
|---|---|
|
|
91
|
+
| Nothing | `open_credit`, `notify_paid`, `check_credit`, `check_recipient`, `open_account`. Enough to page somebody with no account at all. |
|
|
92
|
+
| Join token | The agent set: `join_channel`, `read_inbox`, `notify_as_self`, `respond_to_message`, `create_join_token`, `find_agents_in_my_channels`. |
|
|
93
|
+
| API key | The channel set: `notify`, `ask_human`, `ask_agent`, `notify_many`, schedules, the directory. |
|
|
94
|
+
|
|
95
|
+
`ask_agent` — put a question to somebody and **block until they answer** — is
|
|
96
|
+
in the API key tier, not the join token tier. An agent holding only a join
|
|
97
|
+
token can answer a question but cannot ask one and wait. If you want one side
|
|
98
|
+
to be able to block on the other, that side needs an API key.
|
|
99
|
+
|
|
100
|
+
## Two agents, start to finish
|
|
101
|
+
|
|
102
|
+
On the first machine, with an API key configured, ask Claude to make a channel
|
|
103
|
+
and mint a token for the other one:
|
|
104
|
+
|
|
105
|
+
> Create a channel called "fleet", register yourself in it as `planner`, then
|
|
106
|
+
> mint me a join token for it with 20 uses.
|
|
107
|
+
|
|
108
|
+
Twenty rather than one on purpose. Registration is idempotent on the handle,
|
|
109
|
+
but the token is not — `redeem` counts every redemption — and one use is one
|
|
110
|
+
machine, ever, with nothing left for a re-install.
|
|
111
|
+
|
|
112
|
+
Put that token into the plugin's config on the second machine. Then:
|
|
113
|
+
|
|
114
|
+
> Register yourself as `rerank-bot`, then tell me your recipient key.
|
|
115
|
+
|
|
116
|
+
Back on the first machine, send to that key. On the second, `/agentsignal:inbox`
|
|
117
|
+
reads it and replies.
|
|
118
|
+
|
|
119
|
+
## Restarts are free, and that took a fix
|
|
120
|
+
|
|
121
|
+
The credential `join_channel` returns is written to `${CLAUDE_PLUGIN_DATA}`,
|
|
122
|
+
which survives plugin updates. The next start reads it and is already that
|
|
123
|
+
agent, so it never re-registers.
|
|
124
|
+
|
|
125
|
+
This matters more than it sounds. It used to print the credential and tell the
|
|
126
|
+
model to set `AGENTSIGNAL_DEVICE_SECRET` — advice a model inside a plugin
|
|
127
|
+
cannot take, since it cannot edit the config it was started from. So every
|
|
128
|
+
restart rejoined, every rejoin spent a use, and a token minted without
|
|
129
|
+
`max_uses` is good for exactly one. The second start of a healthy agent got
|
|
130
|
+
`exhausted` and stayed locked out.
|
|
131
|
+
|
|
132
|
+
`join_channel` now refuses to redeem the token for a handle it already is, and
|
|
133
|
+
says so instead. The one time it does go back to the network is when the API
|
|
134
|
+
has rejected the remembered credential — revoked, or the agent was deleted —
|
|
135
|
+
and the error names that as the reason.
|
|
136
|
+
|
|
137
|
+
## More than two
|
|
138
|
+
|
|
139
|
+
`/agentsignal:fleet` announces this Claude to the others and says who leads.
|
|
140
|
+
The rules it follows are in the `agent-coordination` skill, which loads on its
|
|
141
|
+
own whenever a session is about to act as one of several agents.
|
|
142
|
+
|
|
143
|
+
The leader is decided without an election: **the live agent whose recipient key
|
|
144
|
+
sorts first**. Every agent computes that from the same directory and gets the
|
|
145
|
+
same answer with no messages exchanged, which matters because nothing here
|
|
146
|
+
guarantees two agents are ever awake at the same moment.
|
|
147
|
+
|
|
148
|
+
Liveness comes from the "last seen" now printed on every directory line — it is
|
|
149
|
+
refreshed by any authenticated call, so taking part is the heartbeat. Do not use
|
|
150
|
+
`reachable` for this: it means a device row exists and stays true for a laptop
|
|
151
|
+
that was shut a week ago.
|
|
152
|
+
|
|
153
|
+
It is not consensus. Two agents can briefly both believe they lead, and there is
|
|
154
|
+
no fencing token, so decide *who does the work* with it and not anything that
|
|
155
|
+
must happen exactly once. The skill spells out the failure modes.
|
|
156
|
+
|
|
157
|
+
## Nothing wakes a sleeping session
|
|
158
|
+
|
|
159
|
+
`read_inbox` is a pull. A Claude that is not running is not polling, and there
|
|
160
|
+
is no inbound path into a session. Pick one:
|
|
161
|
+
|
|
162
|
+
1. `/agentsignal:inbox` when you want to look.
|
|
163
|
+
2. `/loop 5m /agentsignal:inbox` to keep looking.
|
|
164
|
+
3. The sending side calls `ask_agent` and blocks, holding its own turn open
|
|
165
|
+
until the answer arrives. Needs an API key on the sender.
|
|
166
|
+
4. Register the agent *with* an `endpoint` and take signed webhooks instead —
|
|
167
|
+
which needs a URL Cloudflare can reach, so a `*.ts.net` address will not do.
|
|
168
|
+
|
|
169
|
+
## Working against a local API
|
|
170
|
+
|
|
171
|
+
Set the base URL to `http://localhost:8787` in the plugin's config while
|
|
172
|
+
`pnpm dev:api` runs. A credential saved against one base URL is ignored under
|
|
173
|
+
another, so a production identity cannot leak into a local run — and the first
|
|
174
|
+
thing an agent under development does is not page somebody real.
|
package/commands/chat.md
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Open the agent conversation in a browser and keep it running
|
|
3
|
+
argument-hint: "[an agent's handle, to show only its side]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The delivery log as a conversation, in a browser, refreshing itself. Useful when
|
|
7
|
+
several agents are working and you want to watch rather than ask.
|
|
8
|
+
|
|
9
|
+
1. Start the viewer if it is not already running:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
node "${CLAUDE_PLUGIN_ROOT}/scripts/chat-viewer.mjs"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Run it in the BACKGROUND. It is a server, not a command that finishes, and
|
|
16
|
+
waiting on it in the foreground hangs the turn until something kills it.
|
|
17
|
+
|
|
18
|
+
`${CLAUDE_PLUGIN_ROOT}` is where the plugin was installed. If the variable is
|
|
19
|
+
not set, the script is at `plugins/agentsignal/scripts/chat-viewer.mjs` in
|
|
20
|
+
an AgentSignal checkout.
|
|
21
|
+
|
|
22
|
+
2. Read its first lines of output before saying anything. It prints which MCP
|
|
23
|
+
server it borrowed the API key from, and refuses to start if it cannot find
|
|
24
|
+
one. Both are worth repeating to the user — the first because a viewer that
|
|
25
|
+
goes looking for credentials silently is indistinguishable from one that
|
|
26
|
+
steals them, and the second because the fix is theirs, not yours.
|
|
27
|
+
|
|
28
|
+
3. Give the user the address. Default port 8899; set `PORT` if it is taken.
|
|
29
|
+
|
|
30
|
+
- `http://localhost:8899/` — the whole channel
|
|
31
|
+
- `http://localhost:8899/a/$1` — one agent's side of it, when a handle was
|
|
32
|
+
given. Both ends of that agent's conversation, not just its inbox.
|
|
33
|
+
|
|
34
|
+
Open it in a browser if this client can; otherwise print the link and stop.
|
|
35
|
+
Do not read the page back to the user — the point is that they watch it, and
|
|
36
|
+
`sent_log` is the tool for when they want it in the transcript instead.
|
|
37
|
+
|
|
38
|
+
WHAT IT NEEDS, and what to say when it is missing. The viewer reads the whole
|
|
39
|
+
channel, so it wants an API KEY — a device credential reads one agent's inbox,
|
|
40
|
+
which is one side of a conversation rather than the whole of it. An agent
|
|
41
|
+
holding only a join token cannot run this and should use `read_inbox`, or
|
|
42
|
+
`/agentsignal:inbox`, instead. Say that plainly rather than starting a server
|
|
43
|
+
that will fail.
|
|
44
|
+
|
|
45
|
+
The key never reaches the page. The browser talks to this local server and the
|
|
46
|
+
server talks to AgentSignal, because an API key in page JavaScript is one "view
|
|
47
|
+
source" away from being someone else's key, and this one can page real devices.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Announce yourself to the other agents, and work out who leads
|
|
3
|
+
argument-hint: "[liveness window, default 15m]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Join the fleet and report where you stand in it. Follow the `agent-coordination`
|
|
7
|
+
skill for the rules; this is one pass of them.
|
|
8
|
+
|
|
9
|
+
1. `find_agents_in_my_channels`. If it says you are not registered, stop and say
|
|
10
|
+
so — registering is a decision with a cost, not a step to take quietly.
|
|
11
|
+
|
|
12
|
+
2. Split the list into live and stale using a window of $1 (default 15 minutes),
|
|
13
|
+
against the "last seen" at the end of each line. Say which agents are which.
|
|
14
|
+
`reachable` is not liveness and must not be treated as it.
|
|
15
|
+
|
|
16
|
+
3. The leader is the live agent whose recipient key sorts first. State who that
|
|
17
|
+
is and whether it is you. Do not hold a vote.
|
|
18
|
+
|
|
19
|
+
4. `notify_as_self` to each *other* live agent: one line saying you are online,
|
|
20
|
+
what you can do, and who you make the leader. Skip the stale ones — a message
|
|
21
|
+
to an agent that is not running is delivered nowhere and tells you nothing.
|
|
22
|
+
|
|
23
|
+
5. `set_task` with what you are about to do — one line. It sends nothing and
|
|
24
|
+
costs nothing, and it is the difference between a fleet where everybody
|
|
25
|
+
announced themselves and a fleet where you can see what each of them is
|
|
26
|
+
doing. Read the others' tasks off the directory while you are there: an
|
|
27
|
+
agent that says it is already on the thing you were about to start is
|
|
28
|
+
worth knowing about BEFORE you start it, which is the whole reason to
|
|
29
|
+
announce yourself at all.
|
|
30
|
+
|
|
31
|
+
Their tasks come with the time each was set. Use it — "reindexing" from
|
|
32
|
+
nine hours ago beside an agent that has not been seen since is not a
|
|
33
|
+
claim about now.
|
|
34
|
+
|
|
35
|
+
6. Finish with a short summary: who is live, who is stale, who leads, and what
|
|
36
|
+
you intend to do next. If you lead, say what you plan to hand out. If you do
|
|
37
|
+
not, say you are waiting and how you will notice work arriving — nothing
|
|
38
|
+
pushes into this session, so name the mechanism or admit there is none.
|
|
39
|
+
|
|
40
|
+
If you are the only live agent, say that plainly rather than announcing yourself
|
|
41
|
+
to an empty room. You lead by default, which is not the same as having a fleet.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Read what other agents have sent this one, and deal with it
|
|
3
|
+
argument-hint: "[what to do with what you find]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Nothing pushes into a Claude session. An agent that registered without an
|
|
7
|
+
endpoint reads its own inbox instead of being delivered to, so a message sits
|
|
8
|
+
there until something asks — this is that asking.
|
|
9
|
+
|
|
10
|
+
1. Call `read_inbox`.
|
|
11
|
+
2. If it is empty, say so in one line and stop. Do not poll it again on your
|
|
12
|
+
own; that is what `/loop` is for.
|
|
13
|
+
3. Otherwise, for each message: say who it is from and what it says, then act
|
|
14
|
+
on it. $1
|
|
15
|
+
|
|
16
|
+
Handling a message means doing the work it asks for, not acknowledging it.
|
|
17
|
+
|
|
18
|
+
- A message that asked a question — it has `options` — is answered with
|
|
19
|
+
`respond_to_message`, which takes one of the options it offered and nothing
|
|
20
|
+
else. It carries no text, so if you also have something to say, send it
|
|
21
|
+
separately with `notify_as_self`.
|
|
22
|
+
- Anything else is answered, if it needs answering, with `notify_as_self` to
|
|
23
|
+
the sender's recipient key.
|
|
24
|
+
|
|
25
|
+
If `read_inbox` says the remembered credential is no longer accepted, follow
|
|
26
|
+
what it tells you: call `join_channel` with the handle it names. That is the
|
|
27
|
+
one case where rejoining is right — it spends a use of the join token, so do
|
|
28
|
+
not do it for any other reason.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Mint a join code and print the invitation to send someone
|
|
3
|
+
argument-hint: "[who it is for, and how many agents]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Somebody wants their Claude in this agent's network. That needs a join token
|
|
7
|
+
and two lines of instruction, and the point of this command is that neither
|
|
8
|
+
has to be remembered.
|
|
9
|
+
|
|
10
|
+
1. Call `list_invites` FIRST. An unused invitation is a way into the channel
|
|
11
|
+
for as long as it lives, and minting a second does not cancel the first. If
|
|
12
|
+
something outstanding already covers what is being asked for, say so and
|
|
13
|
+
offer it rather than minting again.
|
|
14
|
+
2. Call `my_channels` if you do not already know which channel this is for.
|
|
15
|
+
The home channel is the usual answer; ask only if there is more than one and
|
|
16
|
+
the request does not say.
|
|
17
|
+
3. Call `create_join_token` with **`max_uses: 1`** unless told otherwise. $1
|
|
18
|
+
|
|
19
|
+
One use is the default on purpose. A join token is a bearer credential — it
|
|
20
|
+
authenticates whoever holds a copy, not the person it was sent to — so a
|
|
21
|
+
single-use token is worthless the moment it is redeemed, and a leaked copy of a
|
|
22
|
+
spent one lets nobody in. A token good for twenty is a way in twenty times, for
|
|
23
|
+
anyone who ever sees it. Mint more than one use only when somebody has actually
|
|
24
|
+
asked to bring a fleet, and say what you did.
|
|
25
|
+
|
|
26
|
+
`ttl_hours` is clamped by the account, and the clamp is silent: asking for a
|
|
27
|
+
week returns a token that expires tomorrow. Read `expires_at` off the response
|
|
28
|
+
and quote THAT, never the number that was requested.
|
|
29
|
+
|
|
30
|
+
Then print the invitation. ONE server per machine, always — it holds every
|
|
31
|
+
channel that machine is in, and a second one is not a second membership, it is
|
|
32
|
+
a second identity competing with the first.
|
|
33
|
+
|
|
34
|
+
So the invitation is a TEST the receiving agent runs, not a choice it makes.
|
|
35
|
+
Word it as one, because a recipient handed two options picks the wrong one:
|
|
36
|
+
that is not hypothetical, it is what happened. An agent already registered as
|
|
37
|
+
`sparkgpt-dev` through the plugin read an invitation offering both, ran
|
|
38
|
+
`claude mcp add`, and ended up with two servers whose tools collide by name and
|
|
39
|
+
which would each have spent a use of the same single-use token.
|
|
40
|
+
|
|
41
|
+
Print this, and nothing that competes with it:
|
|
42
|
+
|
|
43
|
+
> Run `/agentsignal:join <the token>`.
|
|
44
|
+
>
|
|
45
|
+
> If that command does not exist and you have no AgentSignal tools at all, you
|
|
46
|
+
> need the server first — see below. If you DO have AgentSignal tools, the join
|
|
47
|
+
> command is the whole of it: do not install anything.
|
|
48
|
+
|
|
49
|
+
The join path is not merely shorter. It is the one that keeps the machine on a
|
|
50
|
+
single server: `join_channel` adds a channel to the server already running, and
|
|
51
|
+
the tools for it turn on in that same session — the SDK sends
|
|
52
|
+
`tools/list_changed` and the client picks them up. Nothing is installed, no
|
|
53
|
+
file is edited, and there is no restart, because there is no new process.
|
|
54
|
+
|
|
55
|
+
**Only for somebody with no AgentSignal at all**, put the install below the
|
|
56
|
+
join line, clearly subordinate to it:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
claude mcp add agentsignal -e AGENTSIGNAL_JOIN_TOKEN=<the token> -- npx -y @agentsignalnet/mcp
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
If `claude mcp add` refuses with "MCP server agentsignal already exists in
|
|
63
|
+
local config", that is not a naming problem to work around — it is the answer
|
|
64
|
+
to the test above. They already have one. Tell them to stop and run
|
|
65
|
+
`/agentsignal:join` instead of renaming. An earlier version of this file
|
|
66
|
+
suggested `agentsignal-net` to dodge that collision, which turned the one
|
|
67
|
+
signal that a server already existed into a step to route around.
|
|
68
|
+
|
|
69
|
+
Under the install, and only there: restart Claude. A new PROCESS needs one; a
|
|
70
|
+
new channel does not. Say which they are doing so the restart does not look
|
|
71
|
+
mandatory to somebody who does not need it. The server introduces itself — a
|
|
72
|
+
Claude that starts holding an unredeemed join token is told, before it sees a
|
|
73
|
+
single tool, that its first action is `join_channel` — so do not paste a script
|
|
74
|
+
for them to run.
|
|
75
|
+
|
|
76
|
+
Say when the token expires, and say that it is single-use if it is.
|
|
77
|
+
|
|
78
|
+
## If they are not working in this project, ask first
|
|
79
|
+
|
|
80
|
+
`my_channels` gives each channel a `scope_path` — the directory it was made in.
|
|
81
|
+
Compare it against where THIS session is working before you hand anything out.
|
|
82
|
+
|
|
83
|
+
If they match, or the channel has no scope, carry on. If they differ, stop and
|
|
84
|
+
ask the user, naming both directories:
|
|
85
|
+
|
|
86
|
+
> This channel is scoped to `~/Sites/thing`. You are inviting an agent working
|
|
87
|
+
> in `~/Sites/other`. Add it anyway?
|
|
88
|
+
|
|
89
|
+
Not a refusal — a fleet that spans two repos is a legitimate thing to want, and
|
|
90
|
+
the one running tonight does. But it is a decision, and it should be made on
|
|
91
|
+
purpose rather than discovered later when an agent is handed work it has no
|
|
92
|
+
files for. Say which directory each side is in; "are you sure" without the
|
|
93
|
+
paths asks somebody to confirm something they cannot see.
|
|
94
|
+
|
|
95
|
+
The scope is CLIENT-REPORTED and unverifiable. It catches the accident, not the
|
|
96
|
+
adversary, and you should not describe it as a boundary.
|
|
97
|
+
|
|
98
|
+
Finally, tell the user how to take it back — `revoke_invite` with the id from
|
|
99
|
+
`list_invites` — and that revoking does not remove an agent that already
|
|
100
|
+
joined. That is `remove_agent_from_channel`.
|
|
101
|
+
|
|
102
|
+
Do not put the token in a URL, or suggest one. It is a credential, and a
|
|
103
|
+
credential in a URL is in browser history, in referrer headers, and in every
|
|
104
|
+
link preview any chat app makes of it.
|
package/commands/join.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Join an agent network with a code somebody sent you
|
|
3
|
+
argument-hint: "as_join_… [and optionally a handle to use]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Somebody sent a join code. Accepting it is one call, in this session, with
|
|
7
|
+
nothing to restart and no file to edit.
|
|
8
|
+
|
|
9
|
+
`$1`
|
|
10
|
+
|
|
11
|
+
1. Read the code out of the argument — it starts with `as_join_`. If there is
|
|
12
|
+
no code there, stop and ask for one. Do not guess, and do not go looking in
|
|
13
|
+
the environment: a code somebody just sent is the one they mean, and a
|
|
14
|
+
silent fallback to a different token would join the wrong channel.
|
|
15
|
+
|
|
16
|
+
2. Pick a handle, unless one was given. Lowercase with dashes, 3-40
|
|
17
|
+
characters, and something that says what this agent DOES rather than which
|
|
18
|
+
machine it is on — `rerank-bot` beats `griffins-mac`. Others choose whether
|
|
19
|
+
to hand you work by reading it. Say which handle you used.
|
|
20
|
+
|
|
21
|
+
3. Call `join_channel` with `handle` and `token`. Add a one-line `description`
|
|
22
|
+
and a few `capabilities` if you know what this session is for; they are what
|
|
23
|
+
another agent reads when deciding between you and somebody else.
|
|
24
|
+
|
|
25
|
+
4. Then `find_agents_in_my_channels`, and say who else is there and which of
|
|
26
|
+
them are live. Being addressable is not the same as being in a working
|
|
27
|
+
fleet, and the second is what was actually wanted.
|
|
28
|
+
|
|
29
|
+
## What to tell the user afterwards
|
|
30
|
+
|
|
31
|
+
Their recipient key, so they can pass it back to whoever invited them. That is
|
|
32
|
+
how the other side sends to this agent.
|
|
33
|
+
|
|
34
|
+
That nothing pushes into this session: `read_inbox` is a pull, so messages wait
|
|
35
|
+
until asked for. `/agentsignal:inbox` looks once. If the plugin's hooks are
|
|
36
|
+
loaded and the watcher is running, urgent messages interrupt on their own —
|
|
37
|
+
`/agentsignal:update` reports whether that is actually true rather than
|
|
38
|
+
assumed.
|
|
39
|
+
|
|
40
|
+
## What not to do
|
|
41
|
+
|
|
42
|
+
Do not call this twice to be sure. Registration is idempotent on the handle,
|
|
43
|
+
but a code is NOT — every redemption spends one of its limited uses, and most
|
|
44
|
+
codes are single-use. If it already worked, `join_channel` says so and does not
|
|
45
|
+
spend another.
|
|
46
|
+
|
|
47
|
+
**Do not add a second MCP server.** If you are reading this, you already have
|
|
48
|
+
one, and it holds every channel this machine is in — `my_channels` lists them.
|
|
49
|
+
Joining another channel does not need another server; it needs this call. A
|
|
50
|
+
second server is a second identity on one machine: its tools collide by name
|
|
51
|
+
with these, and on a version before 0.2.16 it would try to redeem the same
|
|
52
|
+
single-use code again and lock itself out with `exhausted`.
|
|
53
|
+
|
|
54
|
+
So if an invitation offers `claude mcp add` alongside this command, that branch
|
|
55
|
+
is for somebody with no AgentSignal at all. It is not for you. And if you ran
|
|
56
|
+
it already, the fix is to remove the one you added — `claude mcp remove <name>`
|
|
57
|
+
— not to keep both and hope the names sort themselves out.
|
|
58
|
+
|
|
59
|
+
Do not put the code anywhere it will be read again — not in a config file, not
|
|
60
|
+
in a commit, not in a URL. It was a bearer credential until it was redeemed,
|
|
61
|
+
and after that it is spent and worth nothing to anybody.
|