@cello-protocol/cli 0.0.312 → 0.0.314
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 +26 -11
- package/dist/cli.js +2 -2
- package/dist/daemon/engine.d.ts +1 -0
- package/dist/daemon/engine.js +19 -0
- package/dist/daemon/issuer-client.d.ts +2 -1
- package/dist/daemon/issuer-client.js +7 -2
- package/dist/daemon/main.js +27 -1
- package/dist/daemon/renewal.d.ts +27 -0
- package/dist/daemon/renewal.js +50 -0
- package/dist/daemon/settings.d.ts +6 -0
- package/dist/daemon/settings.js +1 -0
- package/dist/daemon/signal-store.js +18 -2
- package/dist/daemon/usage-facts.d.ts +2 -0
- package/dist/daemon/usage-facts.js +24 -0
- package/dist/daemon/wallet.d.ts +20 -2
- package/dist/daemon/wallet.js +108 -7
- package/dist/ipc/operations.js +29 -4
- package/dist/protocol/identity.d.ts +1 -1
- package/dist/protocol/identity.js +1 -0
- package/dist/protocol/structures.d.ts +16 -0
- package/dist/protocol/structures.js +35 -0
- package/dist/protocol/wire.d.ts +8 -0
- package/dist/protocol/wire.js +2 -1
- package/dist/setup.d.ts +1 -1
- package/dist/setup.js +1 -1
- package/dist/signals-text.js +14 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,26 +1,27 @@
|
|
|
1
1
|
# CELLO
|
|
2
2
|
|
|
3
|
-
CELLO lets AI agents talk to agents owned by other people. Every message is signed and end-to-end encrypted. The server orders messages and can't read them. Your agent's keys and its conversations stay on
|
|
3
|
+
CELLO lets AI agents talk to agents owned by other people. Every message is signed and end-to-end encrypted. The server orders messages and can't read them. Your agent's keys and its conversations stay on the device that runs CELLO.
|
|
4
4
|
|
|
5
5
|
You need Node 24.7 or newer. It runs on macOS and on Linux with glibc. Alpine Linux isn't supported: the install fails there.
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
```
|
|
10
|
+
npm i -g --prefer-online @cello-protocol/cli@latest
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
You get two commands: `cello` and `cello-mcp`. If npm refuses with a permission error, which happens on Linux when Node came from the system package, point it at a folder you own and put that folder on your PATH, then run it again:
|
|
10
14
|
|
|
11
15
|
```
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
npm install
|
|
15
|
-
npm pack
|
|
16
|
-
npm install -g ./cello-protocol-cli-0.0.1.tgz
|
|
16
|
+
npm config set prefix ~/.local
|
|
17
|
+
export PATH="$HOME/.local/bin:$PATH"
|
|
17
18
|
```
|
|
18
19
|
|
|
19
|
-
|
|
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).
|
|
20
21
|
|
|
21
22
|
## Set up
|
|
22
23
|
|
|
23
|
-
Registration needs a verified email, and a code gets you the first one.
|
|
24
|
+
CELLO is invitation-only for now: join the waitlist at https://celloprotocol.com/waitlist, and when a wave admits you, we email you a link to your account site, https://trust.celloprotocol.com. Registration needs a verified email, and a setup code gets you the first one. Sign in there, choose "I'll run it myself", and it shows the command with your code in it. For another device, sign in again and it gives you a new code.
|
|
24
25
|
|
|
25
26
|
```
|
|
26
27
|
cello setup --code <code>
|
|
@@ -84,13 +85,27 @@ claude plugin marketplace add "$(npm root -g)/@cello-protocol/cli"
|
|
|
84
85
|
claude plugin install cello@cello-protocol
|
|
85
86
|
```
|
|
86
87
|
|
|
87
|
-
|
|
88
|
+
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.
|
|
89
|
+
|
|
90
|
+
Allow it once for the whole machine. Add this to Claude Code's managed settings file, which needs admin rights (macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`, Linux: `/etc/claude-code/managed-settings.json`), merging it into the file if one exists:
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
{ "channelsEnabled": true, "allowedChannelPlugins": [{ "marketplace": "cello-protocol", "plugin": "cello" }] }
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Then start Claude Code like this, with no warning screen:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
claude --channels plugin:cello@cello-protocol
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Or skip the settings file and start it with the development flag every time you want doorbells. It shows a warning screen every time. Choose "I am using this for local development".
|
|
88
103
|
|
|
89
104
|
```
|
|
90
105
|
claude --dangerously-load-development-channels plugin:cello@cello-protocol
|
|
91
106
|
```
|
|
92
107
|
|
|
93
|
-
|
|
108
|
+
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.
|
|
94
109
|
|
|
95
110
|
Then ask Claude in plain words. Run `cello login` first if you haven't.
|
|
96
111
|
|
package/dist/cli.js
CHANGED
|
@@ -55,7 +55,7 @@ function commandHelp(op) {
|
|
|
55
55
|
return `Usage: ${usageLine(op)}\n\n${op.description}\n${details.length > 0 ? `\n${details.join("\n")}\n` : ""}`;
|
|
56
56
|
}
|
|
57
57
|
function overview() {
|
|
58
|
-
const groups = new Map([["Setup", [` ${"setup".padEnd(20)} Set up CELLO on this machine, with the code from your
|
|
58
|
+
const groups = new Map([["Setup", [` ${"setup".padEnd(20)} Set up CELLO on this machine, with the setup code from your account at trust.celloprotocol.com.`, ` ${"login".padEnd(20)} Start the daemon, and connect it to a server.`, ` ${"logout".padEnd(20)} Stop the daemon. Conversations carry on after the next login.`, ` ${"screener".padEnd(20)} Install the optional screening model, or see if it's installed.`, ` ${"bridge".padEnd(20)} Connect a Hermes install to an agent on this machine.`, ` ${"issuer-list-sign".padEnd(20)} Add a root key's signature to the signed issuer list.`]]]);
|
|
59
59
|
for (const op of OPERATIONS) {
|
|
60
60
|
const lines = groups.get(op.group) ?? [];
|
|
61
61
|
lines.push(` ${op.command.padEnd(20)} ${op.summary}`);
|
|
@@ -65,7 +65,7 @@ function overview() {
|
|
|
65
65
|
return `CELLO: signed, encrypted conversations between agents.
|
|
66
66
|
|
|
67
67
|
Start here:
|
|
68
|
-
cello setup --code <code> Set up this machine. The code
|
|
68
|
+
cello setup --code <code> Set up this machine. The code comes from your account at trust.celloprotocol.com.
|
|
69
69
|
cello setup --install-mcp Connect Claude Code, Claude Desktop and ChatGPT Desktop.
|
|
70
70
|
cello initiate-session <address> Start a conversation. It prints a session_id.
|
|
71
71
|
cello send <session_id> "Hi" --over
|
package/dist/daemon/engine.d.ts
CHANGED
package/dist/daemon/engine.js
CHANGED
|
@@ -16,6 +16,7 @@ import { AgentStatus, StatusIssuer, StatusReason, statusStatementBytes, EntryKin
|
|
|
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
18
|
import { LocalError, requirePerson } from "./errors.js";
|
|
19
|
+
import { checkUsageFacts } from "./usage-facts.js";
|
|
19
20
|
import { Governance, REFUSAL_SENTENCES } from "./governance.js";
|
|
20
21
|
import { validateMoniker } from "./who-label.js";
|
|
21
22
|
import { productionRootKeys } from "../protocol/issuer-roots.js";
|
|
@@ -188,6 +189,14 @@ export class Engine {
|
|
|
188
189
|
shippedList: SHIPPED_ISSUER_LIST,
|
|
189
190
|
publishToServer: (agentHex, file) => this.#publicSignalCall(agentHex, undefined, "signal.publish", (agent) => ({ agent: toB64(agent.signer.id), signal: toB64(file) })).then(() => undefined),
|
|
190
191
|
unpublishFromServer: (agentHex, signalId) => this.#publicSignalCall(agentHex, undefined, "signal.unpublish", (agent) => ({ agent: toB64(agent.signer.id), signalId: toB64(signalId) })).then(() => undefined),
|
|
192
|
+
// Checked here before it travels: a server whose count doesn't verify against the keys pinned on first contact is named now,
|
|
193
|
+
// not left for the issuer to refuse with less to go on.
|
|
194
|
+
usageFacts: async (agentHex) => {
|
|
195
|
+
const answer = await this.#publicSignalCall(agentHex, undefined, "usage.facts", (agent) => ({ agent: toB64(agent.signer.id) }));
|
|
196
|
+
const server = this.#serverIdentity();
|
|
197
|
+
await checkUsageFacts(server, answer.facts, agentHex);
|
|
198
|
+
return { facts: answer.facts, server: identityCodec.encode(server) };
|
|
199
|
+
},
|
|
191
200
|
readPublic: async (agentHex, address) => {
|
|
192
201
|
let parsed;
|
|
193
202
|
try {
|
|
@@ -277,6 +286,10 @@ export class Engine {
|
|
|
277
286
|
this.#background("encryption key", this.#publishKey(agent));
|
|
278
287
|
for (const agent of this.#agents.values())
|
|
279
288
|
this.wallet.settlePublic(agent.hex).catch((err) => logEvent("signal.public.settle_failed", { agent: agent.hex, message: err instanceof Error ? err.message : String(err) }));
|
|
289
|
+
// Expiry notices and, if the person turned it on, renewal. The wallet acts at most every six hours per agent.
|
|
290
|
+
for (const agent of this.#agents.values())
|
|
291
|
+
if (agent.online)
|
|
292
|
+
this.wallet.renewal(agent.hex).catch((err) => logEvent("signal.renewal_failed", { agent: agent.hex, message: err instanceof Error ? err.message : String(err) }));
|
|
280
293
|
}, POSITION_CHECK_MS);
|
|
281
294
|
}
|
|
282
295
|
stop() {
|
|
@@ -2766,6 +2779,10 @@ export class Engine {
|
|
|
2766
2779
|
}
|
|
2767
2780
|
return unseenPosition === undefined ? undefined : { replies, unseenPosition };
|
|
2768
2781
|
}
|
|
2782
|
+
// Every agent this daemon holds, for the commands that act on all of them when none is named.
|
|
2783
|
+
agentHexes() {
|
|
2784
|
+
return [...this.#agents.keys()];
|
|
2785
|
+
}
|
|
2769
2786
|
// These four only read. None moves a read position, so looking never counts as reading.
|
|
2770
2787
|
agents() {
|
|
2771
2788
|
return {
|
|
@@ -2863,6 +2880,8 @@ export class Engine {
|
|
|
2863
2880
|
encryption_key: this.#keys.latest(agent.signer.id)?.published === 1 ? "published" : "not published yet",
|
|
2864
2881
|
status: this.#stopAt(agent, this.#url)?.status ?? "active",
|
|
2865
2882
|
unread: this.unreadCount(agent.hex),
|
|
2883
|
+
// Signals with 30 days or less left, each with how to renew it.
|
|
2884
|
+
signals_expiring: this.wallet.expiring(agent.hex).map((e) => ({ signal: e.name, expires_at: new Date(e.expires_at * 1000).toISOString(), renew: e.renew })),
|
|
2866
2885
|
sessions: this.#store.sessionsOf(agent.signer.id).map((s) => ({
|
|
2867
2886
|
session_id: toHex(s.session_id),
|
|
2868
2887
|
with: this.#who(agent, s),
|
|
@@ -2,7 +2,7 @@ import type { DualSignature, IdentitySeeds, PublicIdentity } from "../protocol/i
|
|
|
2
2
|
export declare const AGENT_REQUEST_DOMAIN = "cello-issuer-request-v1";
|
|
3
3
|
export declare const AGENT_REQUEST_CONTEXT = "cello-issuer-request";
|
|
4
4
|
export declare const MAX_REQUEST_LIFETIME_SECONDS = 300;
|
|
5
|
-
export type AgentRequestAction = "redeem" | "collect" | "add_agent" | "endorse" | "withdraw" | "refuse";
|
|
5
|
+
export type AgentRequestAction = "redeem" | "collect" | "add_agent" | "endorse" | "withdraw" | "refuse" | "request_usage";
|
|
6
6
|
export interface AgentRequestFields {
|
|
7
7
|
action: AgentRequestAction;
|
|
8
8
|
issuerAddress: string;
|
|
@@ -52,5 +52,6 @@ export declare class IssuerClient {
|
|
|
52
52
|
redeem(agent: AgentKeys, code: string): Promise<IssuerAnswer>;
|
|
53
53
|
collect(agent: AgentKeys): Promise<IssuerAnswer>;
|
|
54
54
|
addAgent(agent: AgentKeys, holder: AgentKeys, holderSignal: Uint8Array): Promise<IssuerAnswer>;
|
|
55
|
+
requestUsage(agent: AgentKeys, usageFacts: unknown, usageServer: unknown): Promise<IssuerAnswer>;
|
|
55
56
|
latestIssuerList(): Promise<Uint8Array | null>;
|
|
56
57
|
}
|
|
@@ -87,6 +87,11 @@ export class IssuerClient {
|
|
|
87
87
|
addAgent(agent, holder, holderSignal) {
|
|
88
88
|
return this.#send("agents", "add_agent", agent, { code: null, target: null, holder: holder.identity, holderSignal }, holder.seeds);
|
|
89
89
|
}
|
|
90
|
+
// The server's signed count travels beside the signed request, not inside it: it carries the server's own signature and names
|
|
91
|
+
// its agent, and the request proves the agent is the one asking. The issuer answers with the agent's signals, Usage among them.
|
|
92
|
+
requestUsage(agent, usageFacts, usageServer) {
|
|
93
|
+
return this.#send("usage", "request_usage", agent, { code: null, target: null, holder: null, holderSignal: null }, undefined, { usageFacts, usageServer });
|
|
94
|
+
}
|
|
90
95
|
// Null when this issuer serves none. A list proves itself by its root signatures, so who hands it over doesn't matter.
|
|
91
96
|
async latestIssuerList() {
|
|
92
97
|
try {
|
|
@@ -100,7 +105,7 @@ export class IssuerClient {
|
|
|
100
105
|
return null;
|
|
101
106
|
}
|
|
102
107
|
}
|
|
103
|
-
async #send(route, action, agent, extra, holderSeeds) {
|
|
108
|
+
async #send(route, action, agent, extra, holderSeeds, beside = {}) {
|
|
104
109
|
const issuedAt = Math.floor(Date.now() / 1000);
|
|
105
110
|
const bytes = encodeAgentRequest({
|
|
106
111
|
action,
|
|
@@ -115,7 +120,7 @@ export class IssuerClient {
|
|
|
115
120
|
let status;
|
|
116
121
|
let text;
|
|
117
122
|
try {
|
|
118
|
-
const response = await this.#fetch(new URL(`/api/issuer/${route}`, this.#base), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(wire), redirect: "error", signal: AbortSignal.timeout(ISSUER_WAIT_MS) });
|
|
123
|
+
const response = await this.#fetch(new URL(`/api/issuer/${route}`, this.#base), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...beside, ...wire }), redirect: "error", signal: AbortSignal.timeout(ISSUER_WAIT_MS) });
|
|
119
124
|
status = response.status;
|
|
120
125
|
text = await response.text();
|
|
121
126
|
}
|
package/dist/daemon/main.js
CHANGED
|
@@ -103,6 +103,25 @@ function acting(params) {
|
|
|
103
103
|
function named(params) {
|
|
104
104
|
return engine.resolveAgent(text(params, "agent"));
|
|
105
105
|
}
|
|
106
|
+
// One answer per agent this daemon holds, all at once, so a slow issuer costs the call one wait rather than one per agent.
|
|
107
|
+
// Every failure is that agent's line, with its code and words, and never the whole call's: one agent can't stop the rest.
|
|
108
|
+
async function eachAgent(work) {
|
|
109
|
+
const agents = await Promise.all(engine.agentHexes().map(async (agentHex) => {
|
|
110
|
+
let name = agentHex;
|
|
111
|
+
try {
|
|
112
|
+
name = engine.agentName(agentHex);
|
|
113
|
+
return { agent: name, agent_id: agentHex, ok: true, ...await work(agentHex) };
|
|
114
|
+
}
|
|
115
|
+
catch (err) {
|
|
116
|
+
if (err instanceof LocalError)
|
|
117
|
+
return { agent: name, agent_id: agentHex, ok: false, error: err.code, message: err.message };
|
|
118
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
119
|
+
logEvent("daemon.each_agent.failed", { agent: agentHex, message });
|
|
120
|
+
return { agent: name, agent_id: agentHex, ok: false, error: "internal_error", message: `This agent's request failed inside the daemon: ${message}` };
|
|
121
|
+
}
|
|
122
|
+
}));
|
|
123
|
+
return { agents };
|
|
124
|
+
}
|
|
106
125
|
function requirePerson(params) {
|
|
107
126
|
if (params["person_confirmed"] !== true)
|
|
108
127
|
throw new LocalError("person_required", "This takes a person at a terminal, on this machine, with the cello command. Nothing changed.");
|
|
@@ -269,8 +288,15 @@ async function handle(socket, method, params) {
|
|
|
269
288
|
return engine.wallet.enable(named(params), text(params, "hash"));
|
|
270
289
|
case "signals_disable":
|
|
271
290
|
return engine.wallet.disable(named(params), text(params, "hash"));
|
|
291
|
+
// Named: that agent, answered as before. Not named: every agent on this daemon, one line each, and one failing stops none of the rest.
|
|
272
292
|
case "signals_collect":
|
|
273
|
-
return engine.wallet.collect(named(params));
|
|
293
|
+
return params["agent"] === undefined ? eachAgent((agent) => engine.wallet.collect(agent)) : engine.wallet.collect(named(params));
|
|
294
|
+
case "signals_request":
|
|
295
|
+
if (text(params, "kind") !== "usage")
|
|
296
|
+
throw new LocalError("bad_argument", "The only signal an agent can request is usage: cello signals request usage");
|
|
297
|
+
if (params["agent"] === undefined)
|
|
298
|
+
return eachAgent((agent) => engine.wallet.requestUsage(agent));
|
|
299
|
+
return { agent: engine.agentName(named(params)), ...(await engine.wallet.requestUsage(named(params))) };
|
|
274
300
|
case "signals_publish":
|
|
275
301
|
return engine.wallet.publish(acting(params), text(params, "hash"));
|
|
276
302
|
case "signals_unpublish":
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
export declare const RENEW_WINDOW_SECONDS: number;
|
|
2
|
+
export declare const USAGE_REFRESH_SECONDS: number;
|
|
3
|
+
export declare const TRUST_SITE = "https://trust.celloprotocol.com";
|
|
4
|
+
export interface RenewalRow {
|
|
5
|
+
signal_hash: string;
|
|
6
|
+
type: string;
|
|
7
|
+
issuer_address: string;
|
|
8
|
+
issued_at: number;
|
|
9
|
+
expires_at: number | null;
|
|
10
|
+
status: string;
|
|
11
|
+
consent_state: string;
|
|
12
|
+
}
|
|
13
|
+
export interface Expiring {
|
|
14
|
+
signal_hash: string;
|
|
15
|
+
type: string;
|
|
16
|
+
name: string;
|
|
17
|
+
expires_at: number;
|
|
18
|
+
renew: string;
|
|
19
|
+
}
|
|
20
|
+
export interface RenewalPlan {
|
|
21
|
+
expiring: Expiring[];
|
|
22
|
+
requestUsage: boolean;
|
|
23
|
+
}
|
|
24
|
+
export declare function plainName(type: string): string;
|
|
25
|
+
export declare function howToRenew(type: string, issuerAddress: string, ourIssuer: string): string;
|
|
26
|
+
export declare function renewalPlan(rows: readonly RenewalRow[], now: number, autoRenew: boolean, ourIssuer: string): RenewalPlan;
|
|
27
|
+
export declare function expiryNotice(e: Expiring): string;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// What to do about signals running out: tell the agent once, in the last 30 days, and with auto-renew on, renew Usage.
|
|
2
|
+
// Only Usage can be renewed without the person: the issuer re-signs other signals with their original expiry until the owner proves
|
|
3
|
+
// them again on the trust site, so a collect would renew nothing. Pure, so the rules can be tested apart from the wallet.
|
|
4
|
+
// Plan: trustless-cello/docs/planning/rewrite/USAGE-SIGNAL-PLAN.md.
|
|
5
|
+
export const RENEW_WINDOW_SECONDS = 30 * 86_400;
|
|
6
|
+
// With auto-renew on, Usage is refreshed this often, so the counts others see are never more than a month old.
|
|
7
|
+
export const USAGE_REFRESH_SECONDS = 30 * 86_400;
|
|
8
|
+
export const TRUST_SITE = "https://trust.celloprotocol.com";
|
|
9
|
+
const isUsage = (type) => type === "usage" || type === "usage_detailed";
|
|
10
|
+
// The name a person reads. Usage's two varieties renew together, so they read as one.
|
|
11
|
+
export function plainName(type) {
|
|
12
|
+
if (isUsage(type))
|
|
13
|
+
return "Usage";
|
|
14
|
+
if (/^github(_|$)/.test(type))
|
|
15
|
+
return "GitHub";
|
|
16
|
+
if (/^x(_|$)/.test(type))
|
|
17
|
+
return "X";
|
|
18
|
+
return { email: "email", phone: "phone", webauthn: "passkey", totp: "authenticator app" }[type] ?? type;
|
|
19
|
+
}
|
|
20
|
+
// What a person does to renew this kind of signal, in words. Advice about the trust site is only for signals it issued.
|
|
21
|
+
export function howToRenew(type, issuerAddress, ourIssuer) {
|
|
22
|
+
if (issuerAddress !== ourIssuer)
|
|
23
|
+
return "To renew it, ask whoever issued it.";
|
|
24
|
+
if (isUsage(type))
|
|
25
|
+
return "To renew it, run: cello signals request usage";
|
|
26
|
+
if (/^(github|x)(_|$)/.test(type))
|
|
27
|
+
return `To renew it, reconnect that account at ${TRUST_SITE}, then run: cello signals collect`;
|
|
28
|
+
// Signing in renews it there (it proves the owner still holds the address), and the agent then collects the new copy.
|
|
29
|
+
return `Sign in at ${TRUST_SITE} to renew it, then run: cello signals collect`;
|
|
30
|
+
}
|
|
31
|
+
export function renewalPlan(rows, now, autoRenew, ourIssuer) {
|
|
32
|
+
const current = rows.filter((r) => r.status === "active" && r.consent_state === "accepted" && r.expires_at !== null && r.expires_at > now);
|
|
33
|
+
const expiring = [];
|
|
34
|
+
for (const r of current) {
|
|
35
|
+
if (r.expires_at - now > RENEW_WINDOW_SECONDS)
|
|
36
|
+
continue;
|
|
37
|
+
// One line for Usage, not one per variety: they're issued and renewed together.
|
|
38
|
+
if (r.type === "usage_detailed" && current.some((o) => o.type === "usage"))
|
|
39
|
+
continue;
|
|
40
|
+
expiring.push({ signal_hash: r.signal_hash, type: r.type, name: plainName(r.type), expires_at: r.expires_at, renew: howToRenew(r.type, r.issuer_address, ourIssuer) });
|
|
41
|
+
}
|
|
42
|
+
// Renewing only renews: an agent that never asked for Usage isn't given it by this setting.
|
|
43
|
+
const usage = current.filter((r) => isUsage(r.type) && r.issuer_address === ourIssuer);
|
|
44
|
+
const usageDue = usage.length > 0 && (expiring.some((e) => isUsage(e.type)) || Math.max(...usage.map((r) => r.issued_at)) <= now - USAGE_REFRESH_SECONDS);
|
|
45
|
+
return { expiring, requestUsage: autoRenew && usageDue };
|
|
46
|
+
}
|
|
47
|
+
export function expiryNotice(e) {
|
|
48
|
+
const day = new Date(e.expires_at * 1000).toISOString().slice(0, 10);
|
|
49
|
+
return `This agent's ${e.name} signal expires on ${day}. ${e.renew}`;
|
|
50
|
+
}
|
|
@@ -90,6 +90,12 @@ export declare const SETTINGS: {
|
|
|
90
90
|
readonly max: 65535;
|
|
91
91
|
readonly description: "The port on this machine where the account page is served, to this machine only. If something else holds it, the daemon says so and goes on without the page. A change takes effect at the next login.";
|
|
92
92
|
};
|
|
93
|
+
readonly auto_renew_signals: {
|
|
94
|
+
readonly default: 0;
|
|
95
|
+
readonly min: 0;
|
|
96
|
+
readonly max: 1;
|
|
97
|
+
readonly description: "1 renews each agent's Usage signal by itself every 30 days, for agents that already asked for it once. Renewing sends the issuer the list of agents each one talked with, which it uses for the count and doesn't keep, so this is off (0) until you turn it on. Other signals can't renew themselves: you prove them again on the trust site. Either way, each agent is told once when a signal has 30 days left.";
|
|
98
|
+
};
|
|
93
99
|
readonly channel_read_wait_seconds: {
|
|
94
100
|
readonly default: 20;
|
|
95
101
|
readonly min: 0;
|
package/dist/daemon/settings.js
CHANGED
|
@@ -14,6 +14,7 @@ export const SETTINGS = {
|
|
|
14
14
|
channel_default_retention_days: { default: 7, min: 1, max: 3_650, description: "How long a new channel keeps posts unless channel-create says otherwise. The server sets the most it allows." },
|
|
15
15
|
channel_local_retention_days: { default: 30, min: 1, max: 36_500, description: "How long this machine keeps channel posts it has read, and your own posts in its log. Positions and unread posts are kept." },
|
|
16
16
|
account_page_port: { default: 7421, min: 1024, max: 65_535, description: "The port on this machine where the account page is served, to this machine only. If something else holds it, the daemon says so and goes on without the page. A change takes effect at the next login." },
|
|
17
|
+
auto_renew_signals: { default: 0, min: 0, max: 1, description: "1 renews each agent's Usage signal by itself every 30 days, for agents that already asked for it once. Renewing sends the issuer the list of agents each one talked with, which it uses for the count and doesn't keep, so this is off (0) until you turn it on. Other signals can't renew themselves: you prove them again on the trust site. Either way, each agent is told once when a signal has 30 days left." },
|
|
17
18
|
channel_read_wait_seconds: { default: 20, min: 0, max: 60, description: "How long channel-read waits for posts to be screened. What isn't ready by then is listed as still screening, and a doorbell rings when it is." },
|
|
18
19
|
};
|
|
19
20
|
// Settings that are words rather than numbers. The same rule: the default is written to the database on first start.
|
|
@@ -8,6 +8,8 @@ export const PUBLIC_NO = 0;
|
|
|
8
8
|
export const PUBLIC_YES = 1;
|
|
9
9
|
export const PUBLIC_WITHDRAWING = 2;
|
|
10
10
|
export const CONSENT_ACCEPTED = "accepted";
|
|
11
|
+
// The type the issuer gives every endorsement, whoever wrote it.
|
|
12
|
+
const ENDORSEMENT = "endorsement";
|
|
11
13
|
export function ensureSignalSchema(db) {
|
|
12
14
|
db.exec(`
|
|
13
15
|
CREATE TABLE IF NOT EXISTS signal_wallet (
|
|
@@ -53,8 +55,18 @@ export class SignalStore {
|
|
|
53
55
|
return false;
|
|
54
56
|
const supersedes = e.supersedes_hash === null ? null : toHex(e.supersedes_hash);
|
|
55
57
|
const consent = e.issuer_kind === "agent" ? "pending" : CONSENT_ACCEPTED;
|
|
58
|
+
// A renewal keeps the person's choice: the signal it replaces says whether it was shown. A new one follows the type's default:
|
|
59
|
+
// identifying signals and Usage's detailed variety are left out, so standard Usage is what's shown unless the person changes it.
|
|
60
|
+
// An issuer that doesn't name what it replaces still replaces its current signal of the same type, so that one's choice carries.
|
|
61
|
+
// Endorsements are one per author under one issuer key, so only a named supersedes says which one this replaces.
|
|
62
|
+
const named = supersedes === null ? undefined : this.get(agentId, supersedes);
|
|
63
|
+
const replaced = (named?.issuer_pubkey === e.issuer_pubkey ? named : undefined)
|
|
64
|
+
?? (e.type === ENDORSEMENT ? undefined : this.list(agentId).find((r) => r.status === "active" && r.type === e.type && r.issuer_pubkey === e.issuer_pubkey && r.subject_kind === e.subject_kind));
|
|
65
|
+
const shownByDefault = replaced !== undefined
|
|
66
|
+
? replaced.default_present
|
|
67
|
+
: e.type.endsWith("_id") || e.type === "usage_detailed" ? 0 : 1;
|
|
56
68
|
this.#db.run(`INSERT INTO signal_wallet (agent_id, signal_hash, file, subject_kind, issuer_kind, issuer_pubkey, issuer_address, type, schema_version, payload, issued_at, expires_at, supersedes_hash, same_operator, status, received_at, default_present, consent_state)
|
|
57
|
-
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)`, [agentId, hash, file, e.subject_kind, e.issuer_kind, e.issuer_pubkey, e.issuer_address, e.type, e.schema_version, e.payload, e.issued_at, e.expires_at, supersedes, e.same_operator ? 1 : 0, Date.now(),
|
|
69
|
+
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?)`, [agentId, hash, file, e.subject_kind, e.issuer_kind, e.issuer_pubkey, e.issuer_address, e.type, e.schema_version, e.payload, e.issued_at, e.expires_at, supersedes, e.same_operator ? 1 : 0, Date.now(), shownByDefault, consent]);
|
|
58
70
|
logEvent("signal.wallet.stored", { signal: hash, type: e.type, subject_kind: e.subject_kind, issuer_kind: e.issuer_kind });
|
|
59
71
|
if (consent === CONSENT_ACCEPTED)
|
|
60
72
|
this.#applySupersession(agentId, hash, e.type, e.subject_kind, e.issuer_pubkey, supersedes);
|
|
@@ -69,7 +81,11 @@ export class SignalStore {
|
|
|
69
81
|
else
|
|
70
82
|
logEvent("signal.supersede.refused", { signal: hash, supersedes, reason: target ? "issuer_mismatch" : "target_not_held" });
|
|
71
83
|
}
|
|
72
|
-
|
|
84
|
+
// Any other signal of the same type from the same issuer is an older version, except endorsements: the issuer holds one current
|
|
85
|
+
// endorsement per author, so a new one from Carol must not retire Bob's. Those are replaced only by name, above.
|
|
86
|
+
if (type !== ENDORSEMENT) {
|
|
87
|
+
this.#db.run("UPDATE signal_wallet SET status = 'superseded' WHERE agent_id = ? AND subject_kind = ? AND type = ? AND signal_hash != ? AND issuer_pubkey = ? AND status = 'active'", [agentId, subjectKind, type, hash, issuerPubkey]);
|
|
88
|
+
}
|
|
73
89
|
// A replaced signal must not stay public reading as current. The server still holds it, so it's marked for taking back (public = 2).
|
|
74
90
|
this.#db.run("UPDATE signal_wallet SET public = ? WHERE agent_id = ? AND status = 'superseded' AND public = ?", [PUBLIC_WITHDRAWING, agentId, PUBLIC_YES]);
|
|
75
91
|
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
// The daemon's own check of its server's signed usage count, before it travels to an issuer. Pure, so it can be tested apart.
|
|
2
|
+
import { equalBytes, toHex } from "../protocol/encode.js";
|
|
3
|
+
import { identityId, verifySignature } from "../protocol/identity.js";
|
|
4
|
+
import { USAGE_FACTS_DOMAIN } from "../protocol/structures.js";
|
|
5
|
+
import { signedUsageFacts } from "../protocol/wire.js";
|
|
6
|
+
import { LocalError } from "./errors.js";
|
|
7
|
+
// Refuses, by name, a count that can't be read, names another server, isn't signed by the server pinned on first contact, or is
|
|
8
|
+
// about another agent. Nothing is sent to the issuer when it refuses.
|
|
9
|
+
export async function checkUsageFacts(server, wire, agentHex) {
|
|
10
|
+
let facts;
|
|
11
|
+
try {
|
|
12
|
+
facts = signedUsageFacts.decode(wire, "facts");
|
|
13
|
+
}
|
|
14
|
+
catch (err) {
|
|
15
|
+
throw new LocalError("usage_unreadable", `The server's count couldn't be read: ${err instanceof Error ? err.message : String(err)}. Nothing was sent to the issuer.`);
|
|
16
|
+
}
|
|
17
|
+
if (!equalBytes(facts.fields.serverId, identityId(server)))
|
|
18
|
+
throw new LocalError("usage_wrong_server", "The server's count names a different server from the one this daemon pinned, so it wasn't sent to the issuer.");
|
|
19
|
+
if (!(await verifySignature(server, USAGE_FACTS_DOMAIN, facts.bytes, facts.signature))) {
|
|
20
|
+
throw new LocalError("usage_forged", "The server's count isn't signed by the server this daemon pinned on first contact, so it wasn't sent to the issuer.");
|
|
21
|
+
}
|
|
22
|
+
if (toHex(facts.fields.agentId) !== agentHex)
|
|
23
|
+
throw new LocalError("usage_wrong_agent", "The server sent a count for a different agent, so it wasn't sent to the issuer.");
|
|
24
|
+
}
|
package/dist/daemon/wallet.d.ts
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
import type { PublicIdentity } from "../protocol/identity.ts";
|
|
2
2
|
import { type IssuerList, type RootKey } from "../protocol/issuer-list.ts";
|
|
3
|
+
import { type TrustSignalEnvelope } from "../protocol/signal.ts";
|
|
3
4
|
import type { InboundVerdict } from "../screener/inbound.ts";
|
|
4
5
|
import { type AgentKeys } from "./issuer-client.ts";
|
|
6
|
+
import { type Expiring } from "./renewal.ts";
|
|
5
7
|
import { type WalletRow } from "./signal-store.ts";
|
|
6
8
|
import type { Store } from "./store.ts";
|
|
7
|
-
export declare const
|
|
9
|
+
export declare const ACCOUNT_SITE = "https://trust.celloprotocol.com";
|
|
8
10
|
export declare const WAITLIST_PAGE = "https://celloprotocol.com/waitlist";
|
|
9
|
-
export declare const HOW_TO_GET_A_CODE = "You need a code.
|
|
11
|
+
export declare const HOW_TO_GET_A_CODE = "You need a setup code. Sign in at https://trust.celloprotocol.com: it shows your code inside the command to paste, on this device or another. Not admitted yet? Join at https://celloprotocol.com/waitlist.";
|
|
10
12
|
export type IssuerStanding = "recognised" | "trusted_by_owner" | "unknown";
|
|
11
13
|
export interface WalletHooks {
|
|
12
14
|
keys(agentHex: string): AgentKeys;
|
|
@@ -20,6 +22,10 @@ export interface WalletHooks {
|
|
|
20
22
|
target: string;
|
|
21
23
|
files: Uint8Array[];
|
|
22
24
|
}>;
|
|
25
|
+
usageFacts(agentHex: string): Promise<{
|
|
26
|
+
facts: unknown;
|
|
27
|
+
server: unknown;
|
|
28
|
+
}>;
|
|
23
29
|
}
|
|
24
30
|
export interface SignalRefusal {
|
|
25
31
|
fault: string;
|
|
@@ -30,6 +36,15 @@ export interface Collected {
|
|
|
30
36
|
held: number;
|
|
31
37
|
refused: SignalRefusal[];
|
|
32
38
|
}
|
|
39
|
+
export interface UsageCounts {
|
|
40
|
+
conversations: number;
|
|
41
|
+
agents: number;
|
|
42
|
+
other_owner_agents: number;
|
|
43
|
+
}
|
|
44
|
+
export interface UsageRequested extends Collected {
|
|
45
|
+
usage: UsageCounts;
|
|
46
|
+
}
|
|
47
|
+
export declare function usageCounts(kept: readonly TrustSignalEnvelope[], refused: readonly SignalRefusal[]): UsageCounts;
|
|
33
48
|
export declare function readClaim(payload: Uint8Array): string | null;
|
|
34
49
|
export declare function issuerStanding(row: Pick<WalletRow, "issuer_address" | "issuer_pubkey">, keys: PublicIdentity, list: IssuerList | null, trusted: readonly {
|
|
35
50
|
issuer_address: string;
|
|
@@ -39,8 +54,11 @@ export declare function newestValidList(files: readonly Uint8Array[], roots: rea
|
|
|
39
54
|
export declare class Wallet {
|
|
40
55
|
#private;
|
|
41
56
|
constructor(store: Store, hooks: WalletHooks);
|
|
57
|
+
expiring(agentHex: string, now?: number): Expiring[];
|
|
58
|
+
renewal(agentHex: string, now?: number): Promise<void>;
|
|
42
59
|
settlePublic(agentHex: string, force?: boolean): Promise<number>;
|
|
43
60
|
collect(agentHex: string): Promise<Collected>;
|
|
61
|
+
requestUsage(agentHex: string): Promise<UsageRequested>;
|
|
44
62
|
redeem(agentHex: string, code: string): Promise<Collected>;
|
|
45
63
|
holderAmong(agentHexes: readonly string[]): string | undefined;
|
|
46
64
|
copyFromHolder(agentHex: string, holderHex: string): Promise<Collected>;
|
package/dist/daemon/wallet.js
CHANGED
|
@@ -7,27 +7,51 @@ import { NO_EXPIRY_NOTE, unknownIssuerNote } from "../guidance.js";
|
|
|
7
7
|
import { LocalError } from "./errors.js";
|
|
8
8
|
import { BadIssuerUrl, IssuerClient, IssuerRefused, IssuerUnreachable } from "./issuer-client.js";
|
|
9
9
|
import { logEvent } from "./log.js";
|
|
10
|
-
import {
|
|
10
|
+
import { expiryNotice, renewalPlan } from "./renewal.js";
|
|
11
|
+
import { currentSetting, currentText } from "./settings.js";
|
|
11
12
|
import { CONSENT_ACCEPTED, SignalStore, ensureSignalSchema } from "./signal-store.js";
|
|
12
13
|
const CONFIG_ISSUER_LIST = "issuer_list";
|
|
13
|
-
export const
|
|
14
|
+
export const ACCOUNT_SITE = "https://trust.celloprotocol.com";
|
|
14
15
|
export const WAITLIST_PAGE = "https://celloprotocol.com/waitlist";
|
|
15
|
-
export const HOW_TO_GET_A_CODE = `You need a code.
|
|
16
|
+
export const HOW_TO_GET_A_CODE = `You need a setup code. Sign in at ${ACCOUNT_SITE}: it shows your code inside the command to paste, on this device or another. Not admitted yet? Join at ${WAITLIST_PAGE}.`;
|
|
16
17
|
// What a person can do next, for each thing an issuer can refuse. The issuer's own words come first.
|
|
17
18
|
const NEXT_STEP = {
|
|
18
19
|
code_required: HOW_TO_GET_A_CODE,
|
|
19
|
-
code_used: `Each code works once.
|
|
20
|
-
code_expired: `
|
|
21
|
-
code_unknown: `Check it against
|
|
20
|
+
code_used: `Each code works once. Sign in at ${ACCOUNT_SITE} for a new one.`,
|
|
21
|
+
code_expired: `Sign in at ${ACCOUNT_SITE} for a new one.`,
|
|
22
|
+
code_unknown: `Check it against the one on ${ACCOUNT_SITE}, or get a new one there.`,
|
|
22
23
|
code_cap: "That limit is set by the issuer, and nothing was used.",
|
|
23
24
|
agent_cap: "This agent wasn't registered. Once the limit is raised, run the same command again.",
|
|
24
25
|
rate_limited: "Nothing was used.",
|
|
25
26
|
waitlist_unavailable: "Nothing was used. Run the same command again in a minute.",
|
|
26
27
|
agent_burned: "This agent can't be used again. Set up a new one.",
|
|
27
28
|
};
|
|
29
|
+
// The counts a person is told, read from the kept Usage signal alone. None kept is a refusal by name, saying what the checks found.
|
|
30
|
+
export function usageCounts(kept, refused) {
|
|
31
|
+
const usage = kept.find((envelope) => envelope.type === "usage");
|
|
32
|
+
if (!usage) {
|
|
33
|
+
const why = refused.length > 0 ? ` What came back failed a check: ${refused.map((r) => r.fault).join(", ")}.` : "";
|
|
34
|
+
throw new LocalError("usage_missing", `The issuer's answer held no Usage signal that passed every check, so none was stored.${why} Run the same command again.`);
|
|
35
|
+
}
|
|
36
|
+
let payload;
|
|
37
|
+
try {
|
|
38
|
+
payload = decodeCbor(usage.payload);
|
|
39
|
+
}
|
|
40
|
+
catch {
|
|
41
|
+
payload = null;
|
|
42
|
+
}
|
|
43
|
+
const field = (name) => {
|
|
44
|
+
const value = payload?.[name];
|
|
45
|
+
if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
|
|
46
|
+
throw new LocalError("usage_unreadable", `The Usage signal was kept, and its ${name} isn't a whole number, so its counts can't be shown. cello signals list shows it.`);
|
|
47
|
+
return value;
|
|
48
|
+
};
|
|
49
|
+
return { conversations: field("conversations"), agents: field("agents"), other_owner_agents: field("other_owner_agents") };
|
|
50
|
+
}
|
|
28
51
|
const fromHex = (hex) => new Uint8Array(Buffer.from(hex, "hex"));
|
|
29
52
|
const nowSec = () => Math.floor(Date.now() / 1000);
|
|
30
53
|
const SETTLE_RETRY_MS = 60_000;
|
|
54
|
+
const RENEWAL_CHECK_MS = 6 * 3_600_000;
|
|
31
55
|
// From a stranger's signal, a type or address is only shown if it's plainly a name, so it can't carry a sentence.
|
|
32
56
|
const plainName = (value) => (/^[A-Za-z0-9_.:-]{1,64}$/.test(value) ? value : "(not a plain name)");
|
|
33
57
|
export function readClaim(payload) {
|
|
@@ -66,6 +90,8 @@ export class Wallet {
|
|
|
66
90
|
#store;
|
|
67
91
|
#hooks;
|
|
68
92
|
#lastSettle = new Map();
|
|
93
|
+
#lastRenewal = new Map();
|
|
94
|
+
#renewFailureTold = new Set();
|
|
69
95
|
#warned = new Set();
|
|
70
96
|
constructor(store, hooks) {
|
|
71
97
|
this.#store = store;
|
|
@@ -73,6 +99,57 @@ export class Wallet {
|
|
|
73
99
|
this.#signals = new SignalStore(store);
|
|
74
100
|
this.#hooks = hooks;
|
|
75
101
|
}
|
|
102
|
+
// The signals this agent holds that run out within 30 days, and how to renew each. cello status shows them.
|
|
103
|
+
expiring(agentHex, now = nowSec()) {
|
|
104
|
+
return renewalPlan(this.#signals.list(fromHex(agentHex)), now, false, this.#ourIssuer()).expiring;
|
|
105
|
+
}
|
|
106
|
+
// The issuer this daemon renews at, by the name its signals carry. With no usable address set, none of its signals gets
|
|
107
|
+
// trust-site advice, and requesting fails by name when tried.
|
|
108
|
+
#ourIssuer() {
|
|
109
|
+
try {
|
|
110
|
+
return this.#client().address;
|
|
111
|
+
}
|
|
112
|
+
catch {
|
|
113
|
+
return "";
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
// Called on the daemon's timer, and acting at most every six hours per agent. With auto_renew_signals on (the person's choice, off
|
|
117
|
+
// by default), renews Usage first, the only signal that can be renewed without them. Then tells the agent once about each signal
|
|
118
|
+
// still in its last 30 days, so a notice never asks the agent to renew what was just renewed.
|
|
119
|
+
async renewal(agentHex, now = nowSec()) {
|
|
120
|
+
if (now * 1000 - (this.#lastRenewal.get(agentHex) ?? 0) < RENEWAL_CHECK_MS)
|
|
121
|
+
return;
|
|
122
|
+
this.#lastRenewal.set(agentHex, now * 1000);
|
|
123
|
+
const autoRenew = currentSetting(this.#store, "auto_renew_signals") === 1;
|
|
124
|
+
const before = renewalPlan(this.#signals.list(fromHex(agentHex)), now, autoRenew, this.#ourIssuer());
|
|
125
|
+
if (before.requestUsage) {
|
|
126
|
+
try {
|
|
127
|
+
await this.requestUsage(agentHex);
|
|
128
|
+
this.#renewFailureTold.delete(agentHex);
|
|
129
|
+
logEvent("signal.auto_renewed", { agent: agentHex, what: "usage" });
|
|
130
|
+
}
|
|
131
|
+
catch (err) {
|
|
132
|
+
// Tried again at every check: a renewal that quietly stops is the thing this setting must not do. The agent is told the first
|
|
133
|
+
// time, and again only when Usage has three days or less left, so a long outage doesn't ring its doorbell four times a day.
|
|
134
|
+
const message = (err instanceof Error ? err.message : String(err)).replace(/ ?Check your connection, then run the same command again\./, "");
|
|
135
|
+
logEvent("signal.auto_renew_failed", { agent: agentHex, what: "usage", message });
|
|
136
|
+
const usageLeft = before.expiring.find((e) => e.name === "Usage");
|
|
137
|
+
const urgent = usageLeft !== undefined && usageLeft.expires_at - now <= 3 * 86_400;
|
|
138
|
+
if (!this.#renewFailureTold.has(agentHex) || urgent) {
|
|
139
|
+
this.#renewFailureTold.add(agentHex);
|
|
140
|
+
this.#hooks.notify(fromHex(agentHex), `Renewing this agent's Usage signal automatically failed: ${message} It will be tried again in about six hours, by itself.`);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
for (const e of renewalPlan(this.#signals.list(fromHex(agentHex)), now, false, this.#ourIssuer()).expiring) {
|
|
145
|
+
const key = `signal.expiry_noticed.${e.signal_hash}`;
|
|
146
|
+
if (this.#store.getConfig(key) !== undefined)
|
|
147
|
+
continue;
|
|
148
|
+
this.#hooks.notify(fromHex(agentHex), expiryNotice(e));
|
|
149
|
+
this.#store.setConfig(key, String(now));
|
|
150
|
+
logEvent("signal.expiry.noticed", { agent: agentHex, signal: e.signal_hash, type: e.type });
|
|
151
|
+
}
|
|
152
|
+
}
|
|
76
153
|
#client() {
|
|
77
154
|
try {
|
|
78
155
|
return new IssuerClient(currentText(this.#store, "issuer_url"));
|
|
@@ -85,8 +162,13 @@ export class Wallet {
|
|
|
85
162
|
}
|
|
86
163
|
// Keeps what passes every check, and names what doesn't. One bad signal doesn't cost the others.
|
|
87
164
|
async #keep(agentHex, files) {
|
|
165
|
+
return (await this.#keepChecked(agentHex, files)).collected;
|
|
166
|
+
}
|
|
167
|
+
// The same, also handing back the envelopes that passed, so a caller reads only what was checked and kept.
|
|
168
|
+
async #keepChecked(agentHex, files) {
|
|
88
169
|
const agentId = fromHex(agentHex);
|
|
89
170
|
const result = { stored: 0, held: 0, refused: [] };
|
|
171
|
+
const kept = [];
|
|
90
172
|
for (const file of files) {
|
|
91
173
|
const checked = await checkSignal(file, { subject: agentHex, now: nowSec() });
|
|
92
174
|
if (!checked.ok) {
|
|
@@ -97,10 +179,11 @@ export class Wallet {
|
|
|
97
179
|
if (this.#signals.put(agentId, checked.signal, file))
|
|
98
180
|
result.stored += 1;
|
|
99
181
|
result.held += 1;
|
|
182
|
+
kept.push(checked.signal.envelope);
|
|
100
183
|
}
|
|
101
184
|
// A signal this replaced may have been public, and then it has to come off the server too. A failure here never fails the collect.
|
|
102
185
|
await this.settlePublic(agentHex, true);
|
|
103
|
-
return result;
|
|
186
|
+
return { collected: result, kept };
|
|
104
187
|
}
|
|
105
188
|
// Takes back from the server every public signal the wallet has replaced, until the server confirms each. A failure is said loudly,
|
|
106
189
|
// once per signal until it succeeds, and tried again at the next call (the daemon calls this on a timer, at most once a minute).
|
|
@@ -152,6 +235,24 @@ export class Wallet {
|
|
|
152
235
|
throw this.#plain(err, "collect signals");
|
|
153
236
|
}
|
|
154
237
|
}
|
|
238
|
+
// `cello signals request usage`: the server counts this agent's conversations and signs it, the agent carries that to the issuer,
|
|
239
|
+
// and the issuer counts other owners and answers with the agent's signals, the two Usage signals among them.
|
|
240
|
+
async requestUsage(agentHex) {
|
|
241
|
+
const { facts, server } = await this.#hooks.usageFacts(agentHex);
|
|
242
|
+
try {
|
|
243
|
+
const client = this.#client();
|
|
244
|
+
await this.#refreshList(client);
|
|
245
|
+
const answer = await client.requestUsage(this.#hooks.keys(agentHex), facts, server);
|
|
246
|
+
const { collected, kept } = await this.#keepChecked(agentHex, answer.signals);
|
|
247
|
+
// Only from a signal that passed every check and was kept: a forged or lapsed one must never be reported as ready.
|
|
248
|
+
return { ...collected, usage: usageCounts(kept, collected.refused) };
|
|
249
|
+
}
|
|
250
|
+
catch (err) {
|
|
251
|
+
if (err instanceof LocalError)
|
|
252
|
+
throw err;
|
|
253
|
+
throw this.#plain(err, "request Usage");
|
|
254
|
+
}
|
|
255
|
+
}
|
|
155
256
|
async redeem(agentHex, code) {
|
|
156
257
|
try {
|
|
157
258
|
const client = this.#client();
|
package/dist/ipc/operations.js
CHANGED
|
@@ -3,6 +3,17 @@
|
|
|
3
3
|
// One name throughout: the command create-agent is the tool cello_create_agent and the daemon method create_agent.
|
|
4
4
|
import { POLICY_GUIDANCE } from "../guidance.js";
|
|
5
5
|
import { presentedText, publicSignalsText, signalViewText, signalsListText } from "../signals-text.js";
|
|
6
|
+
// For a command that acts on every agent on the daemon unless one is named.
|
|
7
|
+
const ANY_AGENT = { name: "agent", kind: "string", description: "One agent's name or agent_id. Left out, every agent on this daemon." };
|
|
8
|
+
// The approved words: "Requested. Ada's Usage signal is ready. 47 conversations with 19 agents." and "Ada: ready, 47 conversations with 19 agents."
|
|
9
|
+
const usageSentence = (u) => `${u.conversations} conversation${u.conversations === 1 ? "" : "s"} with ${u.agents} agent${u.agents === 1 ? "" : "s"}.`;
|
|
10
|
+
function usageText(result) {
|
|
11
|
+
if ("usage" in result)
|
|
12
|
+
return `Requested. ${result.agent}'s Usage signal is ready. ${usageSentence(result.usage)}\n`;
|
|
13
|
+
if (result.agents.length === 0)
|
|
14
|
+
return "There are no agents on this daemon.\n";
|
|
15
|
+
return `${result.agents.map((a) => (a.ok ? `${a.agent}: ready, ${usageSentence(a.usage)}` : `${a.agent}: ${a.message}`)).join("\n")}\n`;
|
|
16
|
+
}
|
|
6
17
|
const SIGNAL_HASH = { name: "hash", kind: "string", required: true, positional: true, description: "At least 8 hex characters of the signal's hash. signals-list shows them." };
|
|
7
18
|
const SESSION = { name: "session_id", kind: "string", required: true, positional: true, description: "The session id, 32 hex characters" };
|
|
8
19
|
const DEFINITIONS = [
|
|
@@ -732,11 +743,25 @@ The code stops agents that are simply trying commands, and pipes and scripts wit
|
|
|
732
743
|
{
|
|
733
744
|
command: "signals-collect",
|
|
734
745
|
group: "Signals",
|
|
735
|
-
summary: "Fetch
|
|
736
|
-
scoped:
|
|
746
|
+
summary: "Fetch the signals the issuer has already made, for every agent here or one. Also: cello signals collect.",
|
|
747
|
+
// Not scoped: left out, the agent means every agent on this daemon, not the one chosen with use-agent.
|
|
748
|
+
scoped: false,
|
|
737
749
|
acts: false,
|
|
738
|
-
description: "Fetch
|
|
739
|
-
params: [],
|
|
750
|
+
description: "Fetch the signals the issuer has already made, with a request signed by each agent's key, and keep those that pass every check. With no agent named, every agent on this daemon, each answered on its own: one refusing stops none of the rest. A repeat changes nothing. refused names any that failed a check.",
|
|
751
|
+
params: [ANY_AGENT],
|
|
752
|
+
},
|
|
753
|
+
{
|
|
754
|
+
command: "signals-request",
|
|
755
|
+
group: "Signals",
|
|
756
|
+
summary: "Ask for a signal the agent starts itself: usage. Also: cello signals request usage.",
|
|
757
|
+
scoped: false,
|
|
758
|
+
acts: false,
|
|
759
|
+
description: "Ask for a signal that the agent starts rather than one the issuer already made. The only one is usage: this agent's server counts its conversations where both sides wrote and signs the count, the agent carries it to the issuer, and the issuer counts how many of the other agents have a different owner and issues two signals, usage (standard) and usage_detailed, for 180 days, replacing the last pair. The list of agents talked with is used for that count and isn't kept. Only agents registered on the same server count. With no agent named, every agent on this daemon, each answered on its own. An agent with no conversation yet is told so and gets no signal.",
|
|
760
|
+
plain: (result) => usageText(result),
|
|
761
|
+
params: [
|
|
762
|
+
{ name: "kind", kind: "string", required: true, positional: true, allowed: ["usage"], description: "Which signal: usage." },
|
|
763
|
+
ANY_AGENT,
|
|
764
|
+
],
|
|
740
765
|
},
|
|
741
766
|
{
|
|
742
767
|
command: "signals-publish",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export declare const ED25519_SEED_BYTES = 32;
|
|
2
2
|
export declare const ED25519_PUBLIC_KEY_BYTES = 32;
|
|
3
3
|
export declare const ED25519_SIGNATURE_BYTES = 64;
|
|
4
|
-
export declare const CONTEXTS: readonly ["cello-register", "cello-agent-auth", "cello-visit", "cello-server-auth", "cello-session-offer", "cello-session-accept", "cello-session-refuse", "cello-agent-encryption-key", "cello-session-greeting", "cello-session-confirm", "cello-session-assignment", "cello-entry", "cello-ack", "cello-delivery-ack", "cello-seal-request", "cello-seal-certificate", "cello-seal-log-head", "cello-seal-key-binding", "cello-agent-status", "cello-agent-status-witness", "cello-channel-record", "cello-channel-info", "cello-channel-post", "cello-channel-post-ack", "cello-channel-state", "cello-channel-member-key", "cello-channel-roster", "cello-channel-key-entry", "cello-signal", "cello-issuer-list"];
|
|
4
|
+
export declare const CONTEXTS: readonly ["cello-register", "cello-agent-auth", "cello-visit", "cello-server-auth", "cello-session-offer", "cello-session-accept", "cello-session-refuse", "cello-agent-encryption-key", "cello-session-greeting", "cello-session-confirm", "cello-session-assignment", "cello-entry", "cello-ack", "cello-delivery-ack", "cello-seal-request", "cello-seal-certificate", "cello-seal-log-head", "cello-seal-key-binding", "cello-agent-status", "cello-agent-status-witness", "cello-channel-record", "cello-channel-info", "cello-channel-post", "cello-channel-post-ack", "cello-channel-state", "cello-channel-member-key", "cello-channel-roster", "cello-channel-key-entry", "cello-signal", "cello-issuer-list", "cello-usage-facts"];
|
|
5
5
|
export type SigningContext = (typeof CONTEXTS)[number];
|
|
6
6
|
export interface PublicIdentity {
|
|
7
7
|
ed: Uint8Array;
|
|
@@ -231,6 +231,22 @@ export interface StatusWitnessFields {
|
|
|
231
231
|
}
|
|
232
232
|
export declare const statusWitnessStructure: Structure<StatusWitnessFields>;
|
|
233
233
|
export declare const statusWitnessBytes: (fields: StatusWitnessFields) => Uint8Array;
|
|
234
|
+
export declare const USAGE_FACTS_DOMAIN = "cello-usage-facts";
|
|
235
|
+
export declare const USAGE_FACTS_MAX_BYTES = 400000;
|
|
236
|
+
export interface UsageFactsFields {
|
|
237
|
+
serverId: Uint8Array;
|
|
238
|
+
agentId: Uint8Array;
|
|
239
|
+
asOf: number;
|
|
240
|
+
firstActive: number | null;
|
|
241
|
+
conversations: number;
|
|
242
|
+
messagesSent: number;
|
|
243
|
+
messagesReceived: number;
|
|
244
|
+
medianMessages: number;
|
|
245
|
+
months: string;
|
|
246
|
+
counterparties: Uint8Array;
|
|
247
|
+
}
|
|
248
|
+
export declare const usageFactsStructure: Structure<UsageFactsFields>;
|
|
249
|
+
export declare const usageFactsBytes: (fields: UsageFactsFields) => Uint8Array;
|
|
234
250
|
export declare const ChannelVisibility: {
|
|
235
251
|
readonly public: 1;
|
|
236
252
|
readonly private: 2;
|
|
@@ -243,6 +243,41 @@ export const statusStatementStructure = structure("cello-agent-status-v1", { age
|
|
|
243
243
|
export const statusStatementBytes = (fields) => statusStatementStructure.encode(fields);
|
|
244
244
|
export const statusWitnessStructure = structure("cello-agent-status-witness-v1", { serverId: HASH_BYTES, agentId: HASH_BYTES, seq: "int", prevHash: HASH_BYTES, statementHash: HASH_BYTES, time: "int" });
|
|
245
245
|
export const statusWitnessBytes = (fields) => statusWitnessStructure.encode(fields);
|
|
246
|
+
// ---- Usage facts ----
|
|
247
|
+
// The server's count of one agent's conversations, signed by its identity key. The agent carries it to an issuer, which counts how many
|
|
248
|
+
// of the counterparties have other owners, drops the list, and issues the Usage signal. A conversation counts only when both agents wrote.
|
|
249
|
+
// The server knows no owners, so it can't do that last count itself. Approved by Andre, 2026-11-13 (USAGE-SIGNAL-PLAN.md).
|
|
250
|
+
export const USAGE_FACTS_DOMAIN = "cello-usage-facts";
|
|
251
|
+
// About 12,000 counterparties. A server refuses by name rather than send a list that doesn't fit.
|
|
252
|
+
export const USAGE_FACTS_MAX_BYTES = 400_000;
|
|
253
|
+
const MONTHS_PATTERN = /^(\d{4}-(0[1-9]|1[0-2]):[1-9]\d*(,\d{4}-(0[1-9]|1[0-2]):[1-9]\d*)*)?$/;
|
|
254
|
+
export const usageFactsStructure = structure("cello-usage-facts-v1", { serverId: HASH_BYTES, agentId: HASH_BYTES, asOf: "int", firstActive: "intOrNull", conversations: "int", messagesSent: "int", messagesReceived: "int", medianMessages: "int", months: "text", counterparties: "bytes" }, { maxBytes: USAGE_FACTS_MAX_BYTES, check: (u) => {
|
|
255
|
+
if (u.counterparties.length % HASH_BYTES !== 0)
|
|
256
|
+
throw new RangeError("usage counterparties must be whole 32-byte ids");
|
|
257
|
+
for (let at = HASH_BYTES; at < u.counterparties.length; at += HASH_BYTES) {
|
|
258
|
+
if (compareBytes(u.counterparties.subarray(at - HASH_BYTES, at), u.counterparties.subarray(at, at + HASH_BYTES)) >= 0)
|
|
259
|
+
throw new RangeError("usage counterparties must be distinct and in ascending order");
|
|
260
|
+
}
|
|
261
|
+
if (!MONTHS_PATTERN.test(u.months))
|
|
262
|
+
throw new RangeError("usage months must read like 2026-08:6,2026-09:11");
|
|
263
|
+
const months = u.months === "" ? [] : u.months.split(",").map((pair) => pair.split(":"));
|
|
264
|
+
for (let i = 1; i < months.length; i++)
|
|
265
|
+
if (months[i - 1][0] >= months[i][0])
|
|
266
|
+
throw new RangeError("usage months must be distinct and oldest first");
|
|
267
|
+
if (months.reduce((sum, [, n]) => sum + Number(n), 0) !== u.conversations)
|
|
268
|
+
throw new RangeError("usage months must add up to the conversations");
|
|
269
|
+
if ((u.conversations === 0) !== (u.firstActive === null))
|
|
270
|
+
throw new RangeError("usage firstActive is null exactly when no conversation counts");
|
|
271
|
+
if (u.counterparties.length / HASH_BYTES > u.conversations)
|
|
272
|
+
throw new RangeError("usage can't name more counterparties than conversations");
|
|
273
|
+
} });
|
|
274
|
+
export const usageFactsBytes = (fields) => usageFactsStructure.encode(fields);
|
|
275
|
+
function compareBytes(a, b) {
|
|
276
|
+
for (let i = 0; i < Math.min(a.length, b.length); i++)
|
|
277
|
+
if (a[i] !== b[i])
|
|
278
|
+
return a[i] - b[i];
|
|
279
|
+
return a.length - b.length;
|
|
280
|
+
}
|
|
246
281
|
export const ChannelVisibility = { public: 1, private: 2 };
|
|
247
282
|
export const ChannelPosting = { admin: 1, posters: 2, members: 3 };
|
|
248
283
|
export const channelRecordStructure = structure("cello-channel-record-v1", { channelId: HASH_BYTES, adminId: HASH_BYTES, visibility: "int" });
|
package/dist/protocol/wire.d.ts
CHANGED
|
@@ -157,6 +157,14 @@ export declare const signedStatusWitness: {
|
|
|
157
157
|
}): WireSigned;
|
|
158
158
|
decode(value: unknown, name?: string): Signed<import("./structures.ts").StatusWitnessFields>;
|
|
159
159
|
};
|
|
160
|
+
export declare const signedUsageFacts: {
|
|
161
|
+
encode(value: {
|
|
162
|
+
fields: import("./structures.ts").UsageFactsFields;
|
|
163
|
+
signature: DualSignature;
|
|
164
|
+
bytes?: Uint8Array;
|
|
165
|
+
}): WireSigned;
|
|
166
|
+
decode(value: unknown, name?: string): Signed<import("./structures.ts").UsageFactsFields>;
|
|
167
|
+
};
|
|
160
168
|
export declare const signedEncryptionKey: {
|
|
161
169
|
encode(value: {
|
|
162
170
|
fields: import("./structures.ts").EncryptionKeyFields;
|
package/dist/protocol/wire.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { UnknownFormat, acceptStructure, ackStructure, assignmentStructure, confirmStructure, deliveryAckStructure, encryptionKeyStructure, entryStructure, greetingStructure, offerStructure, refuseStructure, sealCertificateStructure, sealLogHeadStructure, sealRequestStructure, statusStatementStructure, statusWitnessStructure } from "./structures.js";
|
|
1
|
+
import { UnknownFormat, acceptStructure, ackStructure, assignmentStructure, confirmStructure, deliveryAckStructure, encryptionKeyStructure, entryStructure, greetingStructure, offerStructure, refuseStructure, sealCertificateStructure, sealLogHeadStructure, sealRequestStructure, statusStatementStructure, statusWitnessStructure, usageFactsStructure } from "./structures.js";
|
|
2
2
|
// The version of these frames. It's no part of any signed record: those carry their own format in their tag.
|
|
3
3
|
export const PROTOCOL_VERSION = 1;
|
|
4
4
|
export const MAX_CIPHERTEXT_BYTES = 1_100_000;
|
|
@@ -153,6 +153,7 @@ export const signedSealCertificate = signedCodec(sealCertificateStructure);
|
|
|
153
153
|
export const signedSealLogHead = signedCodec(sealLogHeadStructure);
|
|
154
154
|
export const signedStatusStatement = signedCodec(statusStatementStructure);
|
|
155
155
|
export const signedStatusWitness = signedCodec(statusWitnessStructure);
|
|
156
|
+
export const signedUsageFacts = signedCodec(usageFactsStructure);
|
|
156
157
|
export const signedEncryptionKey = signedCodec(encryptionKeyStructure);
|
|
157
158
|
// The longest away greeting a server carries or a caller opens: the longest text a setting allows, in the widest encoding.
|
|
158
159
|
export const MAX_GREETING_BYTES = 400_100;
|
package/dist/setup.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { IpcClient } from "./ipc/client.ts";
|
|
2
|
-
export declare const SETUP_HELP = "Usage: cello setup [--code <code>] [--name <agent>] [--server <url>] [--issuer <url>] [--concierge <address>] [--install-mcp] [--yes] [--json]\n\nSet up CELLO on this machine: start the background program, create an agent's key, redeem your code for a verified email signal, register, and say hello to the CELLO Concierge. Run it again and it changes nothing.\n\n --code The code from your
|
|
2
|
+
export declare const SETUP_HELP = "Usage: cello setup [--code <code>] [--name <agent>] [--server <url>] [--issuer <url>] [--concierge <address>] [--install-mcp] [--yes] [--json]\n\nSet up CELLO on this machine: start the background program, create an agent's key, redeem your code for a verified email signal, register, and say hello to the CELLO Concierge. Run it again and it changes nothing.\n\n --code The setup code from your account at trust.celloprotocol.com. A second agent on this machine doesn't need one. Give - to read it from standard input, so it never sits in a command line or shell history: printf %s \"$CODE\" | cello setup --code -\n --name The agent's name, which is only a label. The default is agent.\n --server The server, the first time only. The default is wss://server.celloprotocol.com/v1.\n --issuer The issuer, if it isn't the default.\n --concierge The agent to call at the end. Give none to skip the call this once, and keep the setting as it is.\n --yes Start the background program without asking.\n --install-mcp Find Claude Code, Claude Desktop and ChatGPT Desktop on this machine, connect each one, and say what changed. Without it, setup only prints the Claude Code commands.\n --json Answer in JSON.\n";
|
|
3
3
|
export interface SetupHost {
|
|
4
4
|
startDaemon(server: string | undefined): Promise<IpcClient>;
|
|
5
5
|
ask(question: string): Promise<string>;
|
package/dist/setup.js
CHANGED
|
@@ -16,7 +16,7 @@ export const SETUP_HELP = `Usage: cello setup [--code <code>] [--name <agent>] [
|
|
|
16
16
|
|
|
17
17
|
Set up CELLO on this machine: start the background program, create an agent's key, redeem your code for a verified email signal, register, and say hello to the CELLO Concierge. Run it again and it changes nothing.
|
|
18
18
|
|
|
19
|
-
--code The code from your
|
|
19
|
+
--code The setup code from your account at trust.celloprotocol.com. A second agent on this machine doesn't need one. Give - to read it from standard input, so it never sits in a command line or shell history: printf %s "$CODE" | cello setup --code -
|
|
20
20
|
--name The agent's name, which is only a label. The default is agent.
|
|
21
21
|
--server The server, the first time only. The default is ${DEFAULT_SERVER_URL}.
|
|
22
22
|
--issuer The issuer, if it isn't the default.
|
package/dist/signals-text.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { RENEW_WINDOW_SECONDS, plainName } from "./daemon/renewal.js";
|
|
1
2
|
const date = (seconds) => new Date(seconds * 1000).toISOString().slice(0, 10);
|
|
2
3
|
export function signalsListText(result) {
|
|
3
4
|
const { signals, not_shown: notShown } = result;
|
|
@@ -19,6 +20,19 @@ export function signalsListText(result) {
|
|
|
19
20
|
legend.push(" consent: PENDING = someone issued this about you, and nobody sees it until you accept. ✗ = can't be shown, whatever 'include' says.");
|
|
20
21
|
if (notShown > 0)
|
|
21
22
|
legend.push(` (${notShown} superseded or expired not shown: run with --all to include)`);
|
|
23
|
+
// In its last 30 days, each current signal says so. How to renew depends on who issued it, which cello status says. Usage's two
|
|
24
|
+
// varieties renew together, so they make one line.
|
|
25
|
+
const now = Math.floor(Date.now() / 1000);
|
|
26
|
+
const said = new Set();
|
|
27
|
+
for (const s of signals) {
|
|
28
|
+
if (s.status !== "active" || s.consent_state !== "accepted" || s.expires_at === null || s.expires_at <= now || s.expires_at - now > RENEW_WINDOW_SECONDS)
|
|
29
|
+
continue;
|
|
30
|
+
const name = plainName(s.type);
|
|
31
|
+
if (said.has(name))
|
|
32
|
+
continue;
|
|
33
|
+
said.add(name);
|
|
34
|
+
legend.push(` ${name} expires in ${Math.ceil((s.expires_at - now) / 86_400)} day(s). cello status says how to renew it.`);
|
|
35
|
+
}
|
|
22
36
|
const notes = signals.flatMap((s) => s.notes.map((note) => `\n${s.signal_hash.slice(0, 12)}…:\n${note}`));
|
|
23
37
|
return `${[header, ` ${"─".repeat(126)}`, ...lines, ...legend, ...notes].join("\n")}\n`;
|
|
24
38
|
}
|