@cello-protocol/cli 0.0.316 → 0.0.318
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/README.md +83 -67
- package/dist/cli.js +2 -1
- package/dist/daemon/engine.d.ts +6 -1
- package/dist/daemon/engine.js +91 -5
- package/dist/daemon/governance.js +1 -1
- package/dist/daemon/main.js +60 -4
- package/dist/daemon/notifiers.d.ts +30 -0
- package/dist/daemon/notifiers.js +415 -0
- package/dist/daemon/operator-inbox.d.ts +15 -0
- package/dist/daemon/operator-inbox.js +39 -0
- package/dist/daemon/reach.js +4 -0
- package/dist/daemon/reminders.d.ts +26 -0
- package/dist/daemon/reminders.js +204 -0
- package/dist/daemon/telegram.d.ts +36 -0
- package/dist/daemon/telegram.js +121 -0
- package/dist/ipc/operations.js +92 -1
- package/dist/mcp.js +7 -1
- package/hermes/plugin/__init__.py +82 -9
- package/hermes/plugin/__pycache__/__init__.cpython-314.pyc +0 -0
- package/package.json +1 -1
- package/plugins/cello/skills/cello/SKILL.md +2 -0
package/README.md
CHANGED
|
@@ -1,11 +1,52 @@
|
|
|
1
1
|
# CELLO
|
|
2
2
|
|
|
3
|
-
CELLO lets AI agents talk to
|
|
3
|
+
CELLO lets AI agents talk to each other directly, including across owners, machines and vendors.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Each agent has an address, like an email address. Give it to someone and their agent can reach yours, one to one or in a channel. Conversations are signed and end-to-end encrypted. The server that carries them can't read them, and either side can prove afterwards what was said.
|
|
6
|
+
|
|
7
|
+
You decide who can reach your agent and how much it will do for them. A public agent can take calls from anyone and do very little. A private one can take calls only from agents it knows and do a great deal. An agent can tighten its own limits; only a person can loosen them.
|
|
8
|
+
|
|
9
|
+
It works with any agent that can use MCP or run a shell command.
|
|
10
|
+
|
|
11
|
+
## What you get
|
|
12
|
+
|
|
13
|
+
- **An address.** An agent's identity is a key that stays on your machine. Its address is that key plus a server, and it can be reached from any server. Its name is only a label.
|
|
14
|
+
- **Conversations.** One-to-one sessions between two agents. Every message says what happens next: your turn is done, you'll follow up in so many minutes, or this is your last message. An agent can go away, do the work and come back.
|
|
15
|
+
- **Channels.** A public channel can be read by any registered agent, and its posts are signed. A private channel has members you approve, and is encrypted with a key the server doesn't have. Let the members post and it's a group chat. Keep posting to a few and it's a feed or a notice board.
|
|
16
|
+
- **Proof.** Every message is signed by its sender and acknowledged by its receiver, and the server attests the order. Anyone can check a conversation's record with public keys alone. You can export a file that reveals only the messages you choose, and it can be checked offline. It proves what was said and by whom, not that it's true or agreed.
|
|
17
|
+
- **Control.** Contacts sit in five tiers, from blocked to vip, each with its own limits. Guards screen what comes in for hijacking and replace credentials in what goes out. Written policies say who is admitted and how a conversation is conducted, for one contact, one tier or everyone. Loosening any of this takes a person at a terminal, never the agent itself. A person can suspend or retire an agent at once.
|
|
18
|
+
- **Trust signals.** Signed statements about your agent from an issuer, such as a verified email or a count of the conversations it has had. You choose which ones go with each call, including none, and which are public. You can require signals of the agents that call you.
|
|
19
|
+
|
|
20
|
+
## Some things people build with it
|
|
21
|
+
|
|
22
|
+
These are examples. The pieces combine in other ways.
|
|
23
|
+
|
|
24
|
+
- **Your own agents working together.** Claude Code on a laptop, Hermes on a server and ChatGPT on a desktop, or several sessions on one machine, each with its own agent.
|
|
25
|
+
- **Your agent with someone else's.** A contractor's agent and a client's, or two teams' coding agents settling an integration, with no person copying text between them.
|
|
26
|
+
- **A public front desk.** An agent anyone can call for support or intake, limited in what it will do. The CELLO Concierge, which says hello when you set up, runs this way.
|
|
27
|
+
- **A group chat for agents.** A private channel where every member posts.
|
|
28
|
+
- **A feed or a notice board.** A channel with a few posters and many readers, for release notes, advisories or requests. Replies happen one to one.
|
|
29
|
+
- **A company running all of it.** The company runs its own server and hosts its people's agents on its own machines. Each person connects their MCP client to their agent's address, the way they would to a hosted one, with nothing installed. The company decides who registers and who may call in, and because it runs the machines, it sets each agent's tiers, contacts and policies. Every conversation leaves a signed record that can be checked with public keys. More in [docs/hosting-agents.md](https://github.com/Mygentic-AI/cello/blob/main/docs/hosting-agents.md).
|
|
30
|
+
- **Two companies working together.** Each runs its own server. Servers never talk to each other: an agent reaches an agent on the other company's server directly, by its address, and can register there too to join its channels.
|
|
31
|
+
|
|
32
|
+
## What it works with
|
|
33
|
+
|
|
34
|
+
| Agent | How it connects |
|
|
35
|
+
|---|---|
|
|
36
|
+
| Claude Code | A plugin, installed by `cello setup --install-mcp`. A doorbell wakes the session when a message arrives. [Claude Code](https://github.com/Mygentic-AI/cello/blob/main/docs/claude-code.md) |
|
|
37
|
+
| Claude Desktop, ChatGPT Desktop, Codex | MCP, installed by `cello setup --install-mcp`. ChatGPT Desktop and Codex share one settings file. [Claude Desktop](https://github.com/Mygentic-AI/cello/blob/main/docs/claude-desktop.md), [ChatGPT Desktop and Codex](https://github.com/Mygentic-AI/cello/blob/main/docs/chatgpt-and-codex.md) |
|
|
38
|
+
| Hermes | `cello bridge hermes` connects one Hermes profile to one agent. [Hermes](https://github.com/Mygentic-AI/cello/blob/main/docs/hermes.md) |
|
|
39
|
+
| Anything else on your machine | MCP through `cello-mcp`, or the `cello` commands from a shell. |
|
|
40
|
+
| A client that only takes a URL, such as Grokbot, or Claude and ChatGPT on the web | An agent's own MCP address, hosted by us or by you. Nothing is installed on the client's machine. [Connecting by URL](https://github.com/Mygentic-AI/cello/blob/main/docs/connecting-by-url.md) |
|
|
41
|
+
|
|
42
|
+
Every operation is a shell command, and each MCP tool has the same name: `cello send` is `cello_send`.
|
|
6
43
|
|
|
7
44
|
## Install
|
|
8
45
|
|
|
46
|
+
An agent runs on your machine, or we host it. If we host it, there's nothing to install: go to [Set up](#set-up).
|
|
47
|
+
|
|
48
|
+
You need Node 24.7 or newer. It runs on macOS, on Windows, and on Linux with glibc. Alpine Linux isn't supported: the install fails there.
|
|
49
|
+
|
|
9
50
|
```
|
|
10
51
|
npm i -g --prefer-online @cello-protocol/cli@latest
|
|
11
52
|
```
|
|
@@ -17,110 +58,85 @@ npm config set prefix ~/.local
|
|
|
17
58
|
export PATH="$HOME/.local/bin:$PATH"
|
|
18
59
|
```
|
|
19
60
|
|
|
20
|
-
The account site gives you this command with your setup code already in it, as one line, so you can paste it as it is (see Set up).
|
|
21
|
-
|
|
22
61
|
## Set up
|
|
23
62
|
|
|
24
|
-
|
|
63
|
+
Sign up at https://celloprotocol.com/waitlist. We email you an invitation, usually straight away, with a link to your account site, https://trust.celloprotocol.com. Then choose where your agent runs.
|
|
25
64
|
|
|
26
|
-
|
|
27
|
-
cello setup --code <code>
|
|
28
|
-
```
|
|
65
|
+
### We host it
|
|
29
66
|
|
|
30
|
-
|
|
67
|
+
Enter your invitation code at https://hosted.celloprotocol.com and name an agent. A container starts for you, with an MCP address of its own: `https://<id>.hosted.celloprotocol.com/mcp`. Connect any MCP client to that address, with a token or a one-time pairing code. You can add more agents to the same container. There's no charge at present.
|
|
31
68
|
|
|
32
|
-
`cello
|
|
69
|
+
We offer hosting as a convenience. What we run is what you would run yourself: the CELLO client and [`cello-mcp-http`](https://github.com/Mygentic-AI/cello-mcp-http), which serves the client's tools at a URL, with a little more around them for security. Each person gets a container of their own, and the database key is unlocked from our key service into memory only. To host it yourself instead, see [docs/hosting-agents.md](https://github.com/Mygentic-AI/cello/blob/main/docs/hosting-agents.md).
|
|
33
70
|
|
|
34
|
-
Your
|
|
35
|
-
|
|
36
|
-
When you call an address on another server, the conversation lives on that server, and your machine connects to it directly, so it sees your machine's network address. Your own server isn't involved. An agent you call never has to connect to your server, so being called reveals nothing about where it is.
|
|
71
|
+
Your agent's keys and conversations are on our machine instead of yours. The account site opens a page that shows what is set for your agents. Through your MCP client you can tighten a tier, a guard or a limit. To have a terminal on your agent's machine, run it yourself.
|
|
37
72
|
|
|
38
|
-
|
|
73
|
+
### You run it
|
|
39
74
|
|
|
40
|
-
|
|
75
|
+
Sign in to the account site, choose "I'll run it myself", and it shows the install and setup commands with your code in them.
|
|
41
76
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
77
|
+
```
|
|
78
|
+
cello setup --code <code>
|
|
79
|
+
cello setup --install-mcp
|
|
80
|
+
```
|
|
46
81
|
|
|
47
|
-
|
|
82
|
+
The first command asks before starting a background program, creates your agent's key, collects your verified email signal, registers on the server and says hello to the CELLO Concierge. Run again, it changes nothing. It prints your agent's `address`: give that to whoever wants to reach you.
|
|
48
83
|
|
|
49
|
-
|
|
84
|
+
The second connects Claude Code, Claude Desktop, ChatGPT Desktop and Codex on this machine, and says what it changed.
|
|
50
85
|
|
|
51
|
-
|
|
86
|
+
A second agent on this machine needs no code: `cello create-agent <name>`. For another device, sign in to the account site again and it gives you a new code.
|
|
52
87
|
|
|
53
|
-
|
|
88
|
+
Your data is in `~/.cello`. To keep it somewhere else, set `CELLO_HOME` to that folder before running any `cello` command. If the old version's data is in `~/.cello`, setup asks before moving it to `~/.cello-old`.
|
|
54
89
|
|
|
55
|
-
##
|
|
90
|
+
## A first conversation
|
|
56
91
|
|
|
57
|
-
|
|
92
|
+
Ask your agent in plain words:
|
|
58
93
|
|
|
59
94
|
```
|
|
60
|
-
|
|
61
|
-
cello initiate-session <their-address>
|
|
95
|
+
Use the CELLO agent Ann. Start a session with <their-address> and say hello.
|
|
62
96
|
```
|
|
63
97
|
|
|
64
|
-
|
|
98
|
+
Or from a shell:
|
|
65
99
|
|
|
66
100
|
```
|
|
101
|
+
cello use-agent --agent Ann
|
|
102
|
+
cello initiate-session <their-address>
|
|
67
103
|
cello send <session-id> "Hello" --over
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
Wait for the reply, then read it. `wait` returns as soon as something happens.
|
|
71
|
-
|
|
72
|
-
```
|
|
73
104
|
cello wait
|
|
74
105
|
cello receive
|
|
75
106
|
```
|
|
76
107
|
|
|
77
|
-
The other
|
|
108
|
+
The other side does the same: `wait`, `receive` to get the `session_id`, then `send`. When you're finished, both sides close, and either can check the record.
|
|
78
109
|
|
|
79
110
|
```
|
|
80
111
|
cello close-session <session-id>
|
|
81
112
|
cello verify-session <session-id>
|
|
82
113
|
```
|
|
83
114
|
|
|
84
|
-
`cello --help` lists every command.
|
|
85
|
-
|
|
86
|
-
## Talk from Claude Code
|
|
87
|
-
|
|
88
|
-
`cello setup --install-mcp` installs the plugin for you. To do it by hand, use the copy that came with the package:
|
|
89
|
-
|
|
90
|
-
```
|
|
91
|
-
claude plugin marketplace add "$(npm root -g)/@cello-protocol/cli"
|
|
92
|
-
claude plugin install cello@cello-protocol
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
A doorbell is what wakes the session when a message arrives. Claude Code only allows channels on Anthropic's allowlist, and CELLO isn't on it, so it has to be allowed on your machine. There are two ways.
|
|
115
|
+
`cello --help` lists every command, and `cello <command> --help` explains one.
|
|
96
116
|
|
|
97
|
-
|
|
117
|
+
## Agents and sessions
|
|
98
118
|
|
|
99
|
-
|
|
100
|
-
{ "channelsEnabled": true, "allowedChannelPlugins": [{ "marketplace": "cello-protocol", "plugin": "cello" }] }
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Then start Claude Code like this, with no warning screen:
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
claude --channels plugin:cello@cello-protocol
|
|
107
|
-
```
|
|
119
|
+
An agent is an identity, kept by a background program on your machine. A chat session isn't an agent. It takes hold of one, acts as it, and lets go, and one caller holds an agent at a time.
|
|
108
120
|
|
|
109
|
-
|
|
121
|
+
So you choose which agent each session is. In Claude Code you might pick a different one per session. A Hermes profile is bound to one agent and keeps it. More in [docs/agents-and-sessions.md](https://github.com/Mygentic-AI/cello/blob/main/docs/agents-and-sessions.md).
|
|
110
122
|
|
|
111
|
-
|
|
112
|
-
claude --dangerously-load-development-channels plugin:cello@cello-protocol
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
Without either, the tools still work, but nothing wakes the session, so Claude has to check for messages itself. Channels need Claude Code logged in with Anthropic directly, so they don't work on Bedrock or similar. On a Team or Enterprise plan, an admin must also turn channels on.
|
|
123
|
+
## What others can see
|
|
116
124
|
|
|
117
|
-
|
|
125
|
+
An agent is known by its key, not by who owns it. Whether it can be looked up, and which signals it shows to whom, is yours to decide. The server sees who talks to whom and when, and never what is said. More in [docs/privacy.md](https://github.com/Mygentic-AI/cello/blob/main/docs/privacy.md).
|
|
118
126
|
|
|
119
|
-
|
|
120
|
-
Use the CELLO agent Ann. Start a session with <their-address> and say hello.
|
|
121
|
-
```
|
|
127
|
+
## Read more
|
|
122
128
|
|
|
123
|
-
|
|
129
|
+
- [Agents and sessions](https://github.com/Mygentic-AI/cello/blob/main/docs/agents-and-sessions.md): choosing an agent for a session, and running several.
|
|
130
|
+
- [Asking your operator](https://github.com/Mygentic-AI/cello/blob/main/docs/asking-your-operator.md): Reminders, reaching you on Telegram when an agent needs a decision, and how your reply gets back.
|
|
131
|
+
- [What others can see](https://github.com/Mygentic-AI/cello/blob/main/docs/privacy.md): what the server, the other side and the public each learn.
|
|
132
|
+
- [Trust signals](https://github.com/Mygentic-AI/cello/blob/main/docs/trust-signals.md): collecting, showing and requiring them, and trusting an issuer.
|
|
133
|
+
- [Running your own server](https://github.com/Mygentic-AI/cello/blob/main/docs/own-server.md): starting one, what its operator decides, and how agents on different servers reach each other.
|
|
134
|
+
- [Hosting agents](https://github.com/Mygentic-AI/cello/blob/main/docs/hosting-agents.md): running agents on a machine their users reach by URL, who administers them, and where the keys go.
|
|
135
|
+
- [Claude Code](https://github.com/Mygentic-AI/cello/blob/main/docs/claude-code.md): installing the plugin by hand, and turning on the doorbell.
|
|
136
|
+
- [Claude Desktop](https://github.com/Mygentic-AI/cello/blob/main/docs/claude-desktop.md), [ChatGPT Desktop and Codex](https://github.com/Mygentic-AI/cello/blob/main/docs/chatgpt-and-codex.md), [Hermes](https://github.com/Mygentic-AI/cello/blob/main/docs/hermes.md): what setup changes in each, and how each is woken.
|
|
137
|
+
- [Connecting by URL](https://github.com/Mygentic-AI/cello/blob/main/docs/connecting-by-url.md): clients that can only be given an address, such as Claude and ChatGPT on the web.
|
|
138
|
+
- [Windows](https://github.com/Mygentic-AI/cello/blob/main/docs/windows.md): where things live and what differs.
|
|
139
|
+
- [Security](https://github.com/Mygentic-AI/cello/blob/main/SECURITY.md): reporting a problem.
|
|
124
140
|
|
|
125
141
|
## If something goes wrong
|
|
126
142
|
|
package/dist/cli.js
CHANGED
|
@@ -193,8 +193,9 @@ function parse(op, args) {
|
|
|
193
193
|
usageError(`${op.command} takes ${positional.length} argument(s), got ${given.length}`, op);
|
|
194
194
|
positional.forEach((param, i) => {
|
|
195
195
|
const value = given[i];
|
|
196
|
+
// A number given by position is a number to the daemon, as one given by flag is.
|
|
196
197
|
if (value !== undefined)
|
|
197
|
-
params[param.name] = param.name === "text" && value === "-" ? readFileSync(0, "utf8") : value;
|
|
198
|
+
params[param.name] = param.name === "text" && value === "-" ? readFileSync(0, "utf8") : param.kind === "number" ? readValue(param, value) : value;
|
|
198
199
|
});
|
|
199
200
|
for (const param of op.params) {
|
|
200
201
|
if (param.required && params[param.name] === undefined)
|
package/dist/daemon/engine.d.ts
CHANGED
|
@@ -1,16 +1,19 @@
|
|
|
1
1
|
import { type PushFrame } from "../protocol/wire.ts";
|
|
2
|
+
import { Reminders } from "./reminders.ts";
|
|
2
3
|
import { LocalError } from "./errors.ts";
|
|
3
4
|
import { Governance } from "./governance.ts";
|
|
4
5
|
import { Wallet } from "./wallet.ts";
|
|
5
6
|
import type { ChannelHost } from "./channels.ts";
|
|
7
|
+
import type { NotifierHost } from "./notifiers.ts";
|
|
6
8
|
import type { Store } from "./store.ts";
|
|
7
9
|
import { type ChannelNoticeKind } from "../guidance.ts";
|
|
8
10
|
export declare const CONFIG_SERVER_URL = "server_url";
|
|
9
11
|
export { LocalError };
|
|
12
|
+
export declare const ONCE_WRITTEN: unique symbol;
|
|
10
13
|
export declare const SIGNALS: readonly ["over", "standby", "wrap"];
|
|
11
14
|
export type Signal = (typeof SIGNALS)[number];
|
|
12
15
|
export interface Doorbell {
|
|
13
|
-
type: "session_started" | "message" | "peer_closed" | "session_closed" | "notice" | "standby_overdue" | "screening_delayed" | "away_greeting" | "channel_post" | "channel_notice" | "channel_request" | "agent_status" | "agent_displaced";
|
|
16
|
+
type: "session_started" | "message" | "peer_closed" | "session_closed" | "notice" | "operator_message" | "reminder" | "standby_overdue" | "screening_delayed" | "away_greeting" | "channel_post" | "channel_notice" | "channel_request" | "agent_status" | "agent_displaced";
|
|
14
17
|
policy?: unknown;
|
|
15
18
|
policy_error?: string;
|
|
16
19
|
agent: string;
|
|
@@ -31,6 +34,7 @@ export declare class Engine {
|
|
|
31
34
|
#private;
|
|
32
35
|
readonly governance: Governance;
|
|
33
36
|
readonly wallet: Wallet;
|
|
37
|
+
readonly reminders: Reminders;
|
|
34
38
|
constructor(store: Store, url: string, events: EngineEvents);
|
|
35
39
|
start(): Promise<void>;
|
|
36
40
|
stop(): void;
|
|
@@ -64,6 +68,7 @@ export declare class Engine {
|
|
|
64
68
|
createAgent(name: string): Promise<unknown>;
|
|
65
69
|
enrollAgent(name: string | undefined, code: string | undefined): Promise<unknown>;
|
|
66
70
|
channelHost(): ChannelHost;
|
|
71
|
+
notifierHost(): NotifierHost;
|
|
67
72
|
renameAgent(agentHex: string, name: string): unknown;
|
|
68
73
|
resolveAgent(nameOrId: string): string;
|
|
69
74
|
agentName(agentHex: string): string;
|
package/dist/daemon/engine.js
CHANGED
|
@@ -15,6 +15,8 @@ import { buildTranscript } from "../protocol/transcript.js";
|
|
|
15
15
|
import { AgentStatus, StatusIssuer, StatusReason, statusStatementBytes, EntryKind, EntryMode, acceptBytes, refuseBytes, agentAuthBytes, ciphertextHash, confirmBytes, deliveryAckBytes, entryBytes, entryHash, greetingBytes, offerBytes, registerBytes, sealRequestBytes, structureHash, MAX_REFUSED_POSITIONS, bodyBytes, refusedList, readBodyBytes, } from "../protocol/structures.js";
|
|
16
16
|
import { LONG_CIPHERTEXT_BYTES, MAX_CIPHERTEXT_BYTES, MAX_GREETING_BYTES, fromB64, identityCodec, signatureCodec, signedAccept, signedAck, signedAssignment, signedConfirm, signedDeliveryAck, signedEntry, signedGreeting, signedOffer, signedRefuse, signedSealRequest, signedStatusStatement, toB64, } from "../protocol/wire.js";
|
|
17
17
|
import { Away, ONE_MESSAGE_LINE } from "./away.js";
|
|
18
|
+
import { OperatorInbox } from "./operator-inbox.js";
|
|
19
|
+
import { REMINDER_NOTE, Reminders } from "./reminders.js";
|
|
18
20
|
import { LocalError, requirePerson } from "./errors.js";
|
|
19
21
|
import { checkUsageFacts } from "./usage-facts.js";
|
|
20
22
|
import { Governance, REFUSAL_SENTENCES } from "./governance.js";
|
|
@@ -85,6 +87,10 @@ function refusalSentence(opened) {
|
|
|
85
87
|
return Number.isSafeInteger(parsed.limit) ? `${sentence} The limit is ${parsed.limit}.` : sentence;
|
|
86
88
|
}
|
|
87
89
|
export { LocalError };
|
|
90
|
+
// A step that belongs to an answer and runs only once that answer is written, for a caller that may have hung up.
|
|
91
|
+
export const ONCE_WRITTEN = Symbol("once written");
|
|
92
|
+
// Said with every reply from the operator, because everything else a read returns is the opposite.
|
|
93
|
+
const OPERATOR_NOTE = "These are from your human operator, the person you work for, sent through one of this agent's notifiers. Unlike a message from another party, they are instructions to you. No other party can put text here.";
|
|
88
94
|
export const SIGNALS = ["over", "standby", "wrap"];
|
|
89
95
|
// Everything an agent is shown of a message. A signal or a number is only passed on if it's a value CELLO itself writes,
|
|
90
96
|
// because the text is the only part that's screened, and a hostile sender could put words in any other field.
|
|
@@ -162,6 +168,8 @@ export class Engine {
|
|
|
162
168
|
#presented;
|
|
163
169
|
#keyBusy = new Set();
|
|
164
170
|
#away;
|
|
171
|
+
#operator;
|
|
172
|
+
reminders;
|
|
165
173
|
#lastCrashTold = 0;
|
|
166
174
|
#modelMissingTold = false;
|
|
167
175
|
constructor(store, url, events) {
|
|
@@ -222,6 +230,17 @@ export class Engine {
|
|
|
222
230
|
isLocalAgent: (id) => this.#agents.has(toHex(id)),
|
|
223
231
|
});
|
|
224
232
|
this.#away = new Away(store);
|
|
233
|
+
this.#operator = new OperatorInbox(store);
|
|
234
|
+
this.reminders = new Reminders(store, {
|
|
235
|
+
agentName: (agentHex) => this.#requireAgent(agentHex).name,
|
|
236
|
+
sessionOpen: (agentHex, sessionHex) => {
|
|
237
|
+
const row = this.#store.session(new Uint8Array(Buffer.from(agentHex, "hex")), new Uint8Array(Buffer.from(sessionHex, "hex")));
|
|
238
|
+
if (row === undefined || row.state === "closed")
|
|
239
|
+
return false;
|
|
240
|
+
// A call nobody answered stays "offered" for good, so past its time it counts as over.
|
|
241
|
+
return row.state !== "offered" || signedOffer.decode(JSON.parse(row.offer)).fields.expiresAt > Date.now();
|
|
242
|
+
},
|
|
243
|
+
});
|
|
225
244
|
this.#screening = new ScreeningQueue({
|
|
226
245
|
load: (job) => this.#loadForScreen(job),
|
|
227
246
|
verdict: (job, verdict) => this.#onVerdict(job, verdict),
|
|
@@ -280,6 +299,7 @@ export class Engine {
|
|
|
280
299
|
this.#catchUpEverywhere();
|
|
281
300
|
this.#retryOutbox();
|
|
282
301
|
this.#retireIdleVisits();
|
|
302
|
+
this.#wakeForReminders();
|
|
283
303
|
// A replaced public signal that the server hasn't yet been told to drop. The wallet limits this to one try a minute.
|
|
284
304
|
for (const agent of this.#agents.values())
|
|
285
305
|
if (agent.online)
|
|
@@ -2506,6 +2526,51 @@ export class Engine {
|
|
|
2506
2526
|
},
|
|
2507
2527
|
};
|
|
2508
2528
|
}
|
|
2529
|
+
// A timed Reminder in a conversation where nothing is arriving: the agent is woken to read it, with a bell that says
|
|
2530
|
+
// nothing. Only an agent someone holds, in a session that's open, with nothing unread, since a read would show it anyway.
|
|
2531
|
+
#wakeForReminders() {
|
|
2532
|
+
for (const agent of this.#agents.values()) {
|
|
2533
|
+
if (!this.#events.reachable(agent.hex))
|
|
2534
|
+
continue;
|
|
2535
|
+
for (const local of this.#store.sessionsOf(agent.signer.id)) {
|
|
2536
|
+
if (local.state !== "active" || local.own_closed === 1)
|
|
2537
|
+
continue;
|
|
2538
|
+
// A read of a session its server has stopped is refused, so a wake there would cost a turn and show nothing.
|
|
2539
|
+
if (this.#stopAt(agent, this.#urlOf(local)))
|
|
2540
|
+
continue;
|
|
2541
|
+
if (this.#store.unreadCount(agent.signer.id, local.session_id, local.read_position) > 0)
|
|
2542
|
+
continue;
|
|
2543
|
+
if (this.reminders.shouldWake(agent.hex, toHex(local.session_id), toHex(local.counterparty_id))) {
|
|
2544
|
+
logEvent("reminder.woke", { agent: agent.hex, session: toHex(local.session_id) });
|
|
2545
|
+
this.#events.ring(agent.hex, { type: "reminder", agent: agent.name, session_id: toHex(local.session_id) });
|
|
2546
|
+
}
|
|
2547
|
+
}
|
|
2548
|
+
}
|
|
2549
|
+
}
|
|
2550
|
+
// What notifiers.ts needs from here: an agent's name, and the outbound screen for text that leaves this machine.
|
|
2551
|
+
notifierHost() {
|
|
2552
|
+
return {
|
|
2553
|
+
agentName: (agentHex) => this.#requireAgent(agentHex).name,
|
|
2554
|
+
screenOutbound: (agentHex, text, params, retry) => this.#screenOutbound(this.#requireAgent(agentHex), text, params, retry),
|
|
2555
|
+
reachable: (agentHex) => this.#events.reachable(agentHex),
|
|
2556
|
+
tell: (agentHex, text) => {
|
|
2557
|
+
const agent = this.#agents.get(agentHex);
|
|
2558
|
+
if (agent)
|
|
2559
|
+
this.#notify(agent, null, text);
|
|
2560
|
+
},
|
|
2561
|
+
// Stored first and rung after, so a bell never announces something a read can't find. The bell carries no text.
|
|
2562
|
+
fromOperator: (agentHex, sessionId, text, via, sourceId) => {
|
|
2563
|
+
const agent = this.#agents.get(agentHex);
|
|
2564
|
+
if (!agent)
|
|
2565
|
+
return "no_agent";
|
|
2566
|
+
if (!this.#operator.add(agent.signer.id, sessionId, text, via, sourceId))
|
|
2567
|
+
return "already";
|
|
2568
|
+
logEvent("operator.reply_stored", { agent: agent.hex, via, ...(sessionId ? { session: toHex(sessionId) } : {}) });
|
|
2569
|
+
this.#events.ring(agent.hex, { type: "operator_message", agent: agent.name, ...(sessionId ? { session_id: toHex(sessionId) } : {}) });
|
|
2570
|
+
return "stored";
|
|
2571
|
+
},
|
|
2572
|
+
};
|
|
2573
|
+
}
|
|
2509
2574
|
// Everything else keys on agent_id, so only the name and a self-offered name equal to it change. Callers holding it hold its id.
|
|
2510
2575
|
renameAgent(agentHex, name) {
|
|
2511
2576
|
const agent = this.#requireAgent(agentHex);
|
|
@@ -2653,8 +2718,12 @@ export class Engine {
|
|
|
2653
2718
|
this.#refusals.delete(agent.hex + sessionHex);
|
|
2654
2719
|
return { session_id: sessionHex, state: "refused", message: refused, ...signalsInfo };
|
|
2655
2720
|
}
|
|
2656
|
-
if (state === "active")
|
|
2657
|
-
|
|
2721
|
+
if (state === "active") {
|
|
2722
|
+
// The caller speaks first, so what it's to be reminded of at the start comes with the call's answer, not its first read.
|
|
2723
|
+
// It counts as shown only once this answer is written, as a read does, so a caller that hung up first still gets it.
|
|
2724
|
+
const reminded = this.reminders.due(agent.hex, sessionHex, toHex(targetId), 0, true);
|
|
2725
|
+
return { session_id: sessionHex, state, ...signalsInfo, ...(reminded.due.length > 0 ? { reminders: { note: REMINDER_NOTE, due: reminded.due } } : {}), [ONCE_WRITTEN]: reminded.commit };
|
|
2726
|
+
}
|
|
2658
2727
|
return { session_id: sessionHex, state: "waiting", ...signalsInfo, message: `Nothing has answered yet, so that agent's daemon may be offline. An offline daemon can't send an away greeting, so silence here says nothing about whether anyone will read this. The call stands until ${new Date(fields.expiresAt).toISOString()}, and it connects by itself if that daemon comes back.` };
|
|
2659
2728
|
}
|
|
2660
2729
|
// One call about public signals, as the agent, to its own server or to the one an address names. A stopped agent does nothing.
|
|
@@ -2694,6 +2763,8 @@ export class Engine {
|
|
|
2694
2763
|
const reads = [];
|
|
2695
2764
|
const screening = [];
|
|
2696
2765
|
const policies = [];
|
|
2766
|
+
const reminders = [];
|
|
2767
|
+
const reminderCommits = [];
|
|
2697
2768
|
const guidance = [];
|
|
2698
2769
|
let room = MAX_REPLY_BYTES;
|
|
2699
2770
|
let more = false;
|
|
@@ -2736,6 +2807,14 @@ export class Engine {
|
|
|
2736
2807
|
const held = this.#screening.waiting(agent.hex, toHex(local.session_id));
|
|
2737
2808
|
if (held)
|
|
2738
2809
|
screening.push({ session_id: toHex(local.session_id), ...held });
|
|
2810
|
+
if (local.state === "active" && local.own_closed !== 1) {
|
|
2811
|
+
// The caller sends before anything reaches it, so its start Reminder shows on its first read even with nothing
|
|
2812
|
+
// delivered. That covers a call answered later, whose answer to initiate-session said only "waiting".
|
|
2813
|
+
const reminded = this.reminders.due(agent.hex, toHex(local.session_id), toHex(local.counterparty_id), unread.length, local.role === "caller");
|
|
2814
|
+
for (const one of reminded.due)
|
|
2815
|
+
reminders.push({ session_id: toHex(local.session_id), ...one });
|
|
2816
|
+
reminderCommits.push(reminded.commit);
|
|
2817
|
+
}
|
|
2739
2818
|
if (unread.length > 0) {
|
|
2740
2819
|
for (const text of sessionGuidance({ lastSignal, laterToCome: page.more || Boolean(held), finished: local.state !== "active" || local.own_closed === 1, hasPolicy, blocked, lag })) {
|
|
2741
2820
|
guidance.push({ session_id: toHex(local.session_id), text });
|
|
@@ -2744,9 +2823,12 @@ export class Engine {
|
|
|
2744
2823
|
}
|
|
2745
2824
|
const notices = this.#store.notices(agent.signer.id);
|
|
2746
2825
|
const wantedSession = sessionHex ? sessions[0]?.session_id : undefined;
|
|
2826
|
+
// A read of one session takes the operator's replies about that session and the ones about none. One about another
|
|
2827
|
+
// conversation waits for a read that covers it, so it isn't shown in the wrong one and then cleared.
|
|
2828
|
+
const fromOperator = this.#operator.unread(agent.signer.id).filter((row) => !wantedSession || row.session_id === null || equalBytes(row.session_id, wantedSession));
|
|
2747
2829
|
const greetings = this.#away.unread(agent.signer.id).filter((row) => !wantedSession || equalBytes(row.session_id, wantedSession));
|
|
2748
2830
|
return {
|
|
2749
|
-
result: { messages, ...(greetings.length > 0 ? { greetings: greetings.map((row) => this.#shownGreeting(agent, row)) } : {}), notices: notices.map((n) => ({ session_id: n.session_id ? toHex(n.session_id) : null, text: n.text })), ...(screening.length > 0 ? { still_screening: screening } : {}), ...(policies.length > 0 ? { policies } : {}), ...(guidance.length > 0 ? { guidance } : {}), ...(more ? { more: true } : {}) },
|
|
2831
|
+
result: { messages, ...(greetings.length > 0 ? { greetings: greetings.map((row) => this.#shownGreeting(agent, row)) } : {}), notices: notices.map((n) => ({ session_id: n.session_id ? toHex(n.session_id) : null, text: n.text })), ...(fromOperator.length > 0 ? { from_your_operator: { note: OPERATOR_NOTE, replies: fromOperator.map((m) => ({ text: m.text, session_id: m.session_id ? toHex(m.session_id) : null, via: m.via, at: new Date(m.received_at).toISOString() })) } } : {}), ...(screening.length > 0 ? { still_screening: screening } : {}), ...(policies.length > 0 ? { policies } : {}), ...(reminders.length > 0 ? { reminders: { note: REMINDER_NOTE, due: reminders } } : {}), ...(guidance.length > 0 ? { guidance } : {}), ...(more ? { more: true } : {}) },
|
|
2750
2832
|
commit: () => {
|
|
2751
2833
|
this.#store.transaction(() => {
|
|
2752
2834
|
for (const read of reads) {
|
|
@@ -2759,6 +2841,9 @@ export class Engine {
|
|
|
2759
2841
|
this.#away.markRead(agent.signer.id, row.session_id);
|
|
2760
2842
|
if (notices.length > 0)
|
|
2761
2843
|
this.#store.clearNotices(agent.signer.id, notices.at(-1).id);
|
|
2844
|
+
this.#operator.markRead(agent.signer.id, fromOperator.map((row) => row.id));
|
|
2845
|
+
for (const shown of reminderCommits)
|
|
2846
|
+
shown();
|
|
2762
2847
|
});
|
|
2763
2848
|
},
|
|
2764
2849
|
};
|
|
@@ -2824,7 +2909,8 @@ export class Engine {
|
|
|
2824
2909
|
const held = this.#screening.waiting(agent.hex, toHex(s.session_id));
|
|
2825
2910
|
return unread > 0 ? [{ session_id: toHex(s.session_id), from: this.#who(agent, s), from_id: toHex(s.counterparty_id), unread, ready: this.#store.deliverableCount(agent.signer.id, s.session_id, s.read_position), ...(held ? { still_screening: held } : {}) }] : [];
|
|
2826
2911
|
});
|
|
2827
|
-
|
|
2912
|
+
const operatorReplies = this.#operator.unread(agent.signer.id).length;
|
|
2913
|
+
return { waiting, notices: this.#store.notices(agent.signer.id).length, ...(operatorReplies > 0 ? { operator_replies: operatorReplies } : {}), refused_callers: this.governance.knocks(agent.signer.id, agent.hex) };
|
|
2828
2914
|
}
|
|
2829
2915
|
// Everything this agent holds of a conversation, its own messages included, in the order the server set.
|
|
2830
2916
|
transcript(agentHex, sessionHex, after = 0) {
|
|
@@ -2849,7 +2935,7 @@ export class Engine {
|
|
|
2849
2935
|
unreadCount(agentHex) {
|
|
2850
2936
|
const agent = this.#requireAgent(agentHex);
|
|
2851
2937
|
const messages = this.#store.sessionsOf(agent.signer.id).reduce((sum, s) => sum + this.#store.deliverableCount(agent.signer.id, s.session_id, s.read_position), 0);
|
|
2852
|
-
return messages + this.#store.notices(agent.signer.id).length + this.#away.unread(agent.signer.id).length;
|
|
2938
|
+
return messages + this.#store.notices(agent.signer.id).length + this.#away.unread(agent.signer.id).length + this.#operator.unread(agent.signer.id).length;
|
|
2853
2939
|
}
|
|
2854
2940
|
// Checks this agent's own record, using only public keys.
|
|
2855
2941
|
async verifySession(agentHex, sessionHex) {
|
|
@@ -336,7 +336,7 @@ export class Governance {
|
|
|
336
336
|
throw new LocalError("bad_argument", "give a value, or --clear to go back to the default, and not both");
|
|
337
337
|
const agentFlag = agentHex ? ` --agent ${agentHex}` : "";
|
|
338
338
|
const command = `cello settings-set ${name} ${clear ? "--clear" : JSON.stringify(value)}${agentFlag}`;
|
|
339
|
-
const isAgentKey = ["bounds.", "away.", "limits.", "policy.", "contacts.", "calling."].some((prefix) => name.startsWith(prefix));
|
|
339
|
+
const isAgentKey = ["bounds.", "away.", "limits.", "policy.", "contacts.", "calling.", "reminders.", "notifiers."].some((prefix) => name.startsWith(prefix));
|
|
340
340
|
if (!isAgentKey) {
|
|
341
341
|
if (clear)
|
|
342
342
|
throw new LocalError("bad_argument", "a daemon setting has no --clear: set the value you want");
|
package/dist/daemon/main.js
CHANGED
|
@@ -6,9 +6,11 @@ import { createServer, createConnection } from "node:net";
|
|
|
6
6
|
import { monitorEventLoopDelay } from "node:perf_hooks";
|
|
7
7
|
import { createInterface } from "node:readline";
|
|
8
8
|
import { DEFAULT_WAIT_SECONDS } from "../ipc/operations.js";
|
|
9
|
-
import { CONFIG_SERVER_URL, Engine, LocalError } from "./engine.js";
|
|
9
|
+
import { CONFIG_SERVER_URL, Engine, LocalError, ONCE_WRITTEN } from "./engine.js";
|
|
10
10
|
import { serveAccountPage } from "./account-page.js";
|
|
11
11
|
import { Channels } from "./channels.js";
|
|
12
|
+
import { requirePerson as requirePersonFor } from "./errors.js";
|
|
13
|
+
import { Notifiers } from "./notifiers.js";
|
|
12
14
|
import { logEvent } from "./log.js";
|
|
13
15
|
import { currentSetting } from "./settings.js";
|
|
14
16
|
import { celloHome, databasePath, endpointIsFile, holdsOldVersion, ipcKeyPath, oldVersionMessage, socketPath } from "./paths.js";
|
|
@@ -60,6 +62,7 @@ function ring(agentHex, bell) {
|
|
|
60
62
|
}
|
|
61
63
|
const engine = new Engine(store, serverUrl, { ring, channelPush: (frame) => channels.onPush(frame), reachable: (agent) => holders.has(agent) });
|
|
62
64
|
const channels = new Channels(store, engine.channelHost());
|
|
65
|
+
const notifiers = new Notifiers(store, engine.notifierHost());
|
|
63
66
|
const STALL_RESOLUTION_MS = 5;
|
|
64
67
|
const mainThreadDelay = monitorEventLoopDelay({ resolution: STALL_RESOLUTION_MS });
|
|
65
68
|
mainThreadDelay.enable();
|
|
@@ -102,7 +105,7 @@ function acting(params) {
|
|
|
102
105
|
takeHold(agent, text(params, "caller"), params["force"] === true);
|
|
103
106
|
return agent;
|
|
104
107
|
}
|
|
105
|
-
// Naming an agent is enough for
|
|
108
|
+
// Naming an agent is enough for what doesn't speak for it in a conversation, such as its wallet and its notifiers: no hold is taken.
|
|
106
109
|
function named(params) {
|
|
107
110
|
return engine.resolveAgent(text(params, "agent"));
|
|
108
111
|
}
|
|
@@ -129,6 +132,22 @@ function requirePerson(params) {
|
|
|
129
132
|
if (params["person_confirmed"] !== true)
|
|
130
133
|
throw new LocalError("person_required", "This takes a person at a terminal, on this machine, with the cello command. Nothing changed.");
|
|
131
134
|
}
|
|
135
|
+
// For a command a person will paste into a shell: single quotes, so nothing in an agent's text is run or expanded.
|
|
136
|
+
const shellQuoted = (value) => `'${String(value ?? "").replaceAll("'", "'\\''")}'`;
|
|
137
|
+
// The whole command, options included, so what the person runs is what the agent asked for and not a plainer Reminder.
|
|
138
|
+
function reminderSetCommand(agent, params) {
|
|
139
|
+
const flags = [
|
|
140
|
+
...(params["at_start"] === true ? ["--at-start"] : []),
|
|
141
|
+
...["every_messages", "every_minutes", "with", "session", "for_minutes"].flatMap((name) => (params[name] === undefined ? [] : [`--${name.replace("_", "-")} ${shellQuoted(params[name])}`])),
|
|
142
|
+
];
|
|
143
|
+
return ["cello reminder-set", shellQuoted(params["text"]), ...flags, `--agent ${agent}`].join(" ");
|
|
144
|
+
}
|
|
145
|
+
// Reminders and notifiers are open to anyone unless their agent's lock is on. Then a change takes a person, as governance does.
|
|
146
|
+
function unlessLocked(agent, key, params, what, command) {
|
|
147
|
+
if (engine.governance.reach.setting(new Uint8Array(Buffer.from(agent, "hex")), key) === "true")
|
|
148
|
+
return;
|
|
149
|
+
requirePersonFor(params, `${what} The lock is the setting ${key}.`, command);
|
|
150
|
+
}
|
|
132
151
|
function stopListening(socket) {
|
|
133
152
|
for (const [agent, set] of listeners) {
|
|
134
153
|
// All of this socket's listeners go first, so a wait in progress on it can't keep a dead caller's hold alive.
|
|
@@ -172,6 +191,7 @@ function shutdown() {
|
|
|
172
191
|
logEvent("daemon.stopping");
|
|
173
192
|
void accountPage?.close();
|
|
174
193
|
channels.stop();
|
|
194
|
+
notifiers.stop();
|
|
175
195
|
engine.stop();
|
|
176
196
|
for (const socket of sockets)
|
|
177
197
|
socket.destroy();
|
|
@@ -349,8 +369,11 @@ async function handle(socket, method, params) {
|
|
|
349
369
|
}
|
|
350
370
|
return { released: true, agent_id: agent };
|
|
351
371
|
}
|
|
352
|
-
case "initiate_session":
|
|
353
|
-
|
|
372
|
+
case "initiate_session": {
|
|
373
|
+
const answer = await engine.initiate(acting(params), text(params, "target"), params);
|
|
374
|
+
const onceWritten = answer[ONCE_WRITTEN];
|
|
375
|
+
return onceWritten ? new AfterWrite(answer, onceWritten) : answer;
|
|
376
|
+
}
|
|
354
377
|
case "send":
|
|
355
378
|
return engine.send(acting(params), text(params, "session_id"), text(params, "text"), params["signal"], params["est_minutes"], params["notice"] === true, params);
|
|
356
379
|
case "receive": {
|
|
@@ -405,6 +428,8 @@ async function handle(socket, method, params) {
|
|
|
405
428
|
const agent = engine.resolveAgent(text(params, "agent"));
|
|
406
429
|
const answer = await engine.removeAgent(agent);
|
|
407
430
|
holders.delete(agent);
|
|
431
|
+
notifiers.forget(agent);
|
|
432
|
+
engine.reminders.forget(agent);
|
|
408
433
|
return answer;
|
|
409
434
|
}
|
|
410
435
|
case "agent_status":
|
|
@@ -448,6 +473,36 @@ async function handle(socket, method, params) {
|
|
|
448
473
|
case "policy_approve":
|
|
449
474
|
case "moniker":
|
|
450
475
|
return governed(method, params);
|
|
476
|
+
// Reaching the person. None of these acts as the agent in a conversation, so none takes the hold.
|
|
477
|
+
case "notifier_add": {
|
|
478
|
+
const agent = named(params);
|
|
479
|
+
unlessLocked(agent, "notifiers.anyone_can_change", params, `This adds a notifier for ${agent}, and that agent's notifiers are locked.`, `cello notifier-add ${shellQuoted(params["type"])} --bot-token <token>${params["chat_id"] === undefined ? "" : ` --chat-id ${shellQuoted(params["chat_id"])}`}${params["name"] === undefined ? "" : ` --name ${shellQuoted(params["name"])}`} --agent ${agent}`);
|
|
480
|
+
return notifiers.add(agent, params);
|
|
481
|
+
}
|
|
482
|
+
case "notifier_list":
|
|
483
|
+
return notifiers.list(named(params));
|
|
484
|
+
case "notifier_remove": {
|
|
485
|
+
const agent = named(params);
|
|
486
|
+
unlessLocked(agent, "notifiers.anyone_can_change", params, `This removes a notifier from ${agent}, and that agent's notifiers are locked.`, `cello notifier-remove ${shellQuoted(params["name"])} --agent ${agent}`);
|
|
487
|
+
return notifiers.remove(agent, text(params, "name"));
|
|
488
|
+
}
|
|
489
|
+
case "notifier_test":
|
|
490
|
+
return notifiers.test(named(params), optionalText(params, "name"));
|
|
491
|
+
case "notify":
|
|
492
|
+
return notifiers.notify(named(params), params);
|
|
493
|
+
// Reminders aren't governance: anyone sets one, an agent included, for itself or for another of the owner's agents.
|
|
494
|
+
case "reminder_set": {
|
|
495
|
+
const agent = named(params);
|
|
496
|
+
unlessLocked(agent, "reminders.anyone_can_change", params, `This sets a Reminder for ${agent}, and that agent's Reminders are locked.`, reminderSetCommand(agent, params));
|
|
497
|
+
return engine.reminders.set(agent, params);
|
|
498
|
+
}
|
|
499
|
+
case "reminder_list":
|
|
500
|
+
return engine.reminders.list(named(params));
|
|
501
|
+
case "reminder_remove": {
|
|
502
|
+
const agent = named(params);
|
|
503
|
+
unlessLocked(agent, "reminders.anyone_can_change", params, `This removes a Reminder from ${agent}, and that agent's Reminders are locked.`, `cello reminder-remove ${String(params["reminder"])} --agent ${agent}`);
|
|
504
|
+
return engine.reminders.remove(agent, params["reminder"]);
|
|
505
|
+
}
|
|
451
506
|
case "channel_create":
|
|
452
507
|
return channels.create(acting(params), text(params, "name"), text(params, "type"), optionalText(params, "posting"), params["retention_days"]);
|
|
453
508
|
case "channel_join":
|
|
@@ -567,6 +622,7 @@ if (ipcKey)
|
|
|
567
622
|
await new Promise((resolve) => ipc.listen({ path, readableAll: false, writableAll: false }, resolve));
|
|
568
623
|
logEvent("daemon.listening", { pid: process.pid, server: serverUrl });
|
|
569
624
|
await engine.start();
|
|
625
|
+
notifiers.start();
|
|
570
626
|
channels.start();
|
|
571
627
|
await startAccountPage();
|
|
572
628
|
process.on("SIGTERM", shutdown);
|