omp-onlyne 0.1.0 → 0.2.0

package/src/runtime.ts

@@ -1,9 +1,12 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { dirname, join } from "node:path";
-import { OnlyneError, trustPhase, type DiscoveryCandidate, type DiscoveryRecord, type KeyExchange, type KeyHook, type MaintenanceClock, type NotifyEvent, type OnlyneNode, type Outbound, type Page } from "@onlyne/lib";
+import { OnlyneError, trustPhase, type DiscoveryCandidate, type DiscoveryRecord, type KeyExchange, type KeyHook, type MaintenanceClock, type NotifyEvent, type OnlyneNode, type Outbound, type Page, type TrustEntry } from "@onlyne/lib";
 import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
 import { ensureKeyDir } from "@onlyne/node-host/keys";
 import { NetworkDiscovery } from "@onlyne/node-host/network";
 import { resolveLocale, setLocale } from "@onlyne/node-host/i18n";
+import { acquisitionOf } from "./acquire.ts";
+import { AcquisitionLog, approvePeer, beginPeer, handshakeEntry, isTrustThread, judgeApproval, judgementFacts, revokePeer, trustThread, TRUST_THREAD, type ApprovalDeps, type ApprovalJudgement, type ApprovalRequest } from "./handshake.ts";
 import { commandText as t } from "./ui/command-text.ts";
 import { registerMsgTool } from "./tool.ts";
 import { currentDecision, JudgeDecider } from "./decider.ts";
@@ -14,6 +17,9 @@ import { canAnswer, ContextRegistry, SqliteStorage } from "./store.ts";
 import { resourceQuery } from "./resources.ts";
 import type { OnlyneConfig, OnlyneStatus, QueueItem, ViewerContact, ViewerDiscovery, ViewerMessage, ViewerSnapshot, ViewerThread } from "./types.ts";
 
+/** The trust transition of RFC 0017 §5, as the host receives it. */
+type TrustNotify = Extract<NotifyEvent, { event: "trust" }>;
+
 export interface PluginRuntime {
 	readonly config: OnlyneConfig;
 	readonly endpoint: string;
@@ -32,9 +38,16 @@ export interface PluginRuntime {
 	contact(endpoint: string): Promise<void>;
 	/** Stage one of one exchange; the returned session carries the fingerprint the peer proved. */
 	trustBegin(node: string): Promise<KeyExchange>;
+	/** A human's confirmation in the panel: RFC 0018 §2 keeps that gate outside the policy. */
 	trustAccept(node: string, fingerprint: string): Promise<void>;
 	trustRevoke(node: string): Promise<void>;
 	trustRotate(): Promise<{ fingerprint: string }>;
+	/** RFC 0018 §2/§3.1: an agent's approval, judged against the acquisition policy first. */
+	acquireAccept(node: string, fingerprint: string): Promise<TrustEntry>;
+	/** RFC 0018 §2/§3.1: an agent's revocation. The policy never applies to dropping a peer. */
+	acquireRevoke(node: string): Promise<void>;
+	/** RFC 0018 §2/§3.1: an agent's initiation, judged before the key read that would begin it. */
+	acquireBegin(node: string): Promise<TrustEntry>;
 	refreshDiscovery(): Promise<void>;
 	updateConfig(next: OnlyneConfig): Promise<void>;
 	close(): Promise<void>;
@@ -61,11 +74,35 @@ export async function restartRuntime(config: OnlyneConfig, pi: ExtensionAPI, ctx
 	registerMsgTool(pi);
 	return runtime;
 }
-export async function stopRuntime(): Promise<void> { await active?.close(); }
+export async function stopRuntime(): Promise<void> {
+	const closing = active;
+	active = undefined;
+	await closing?.close();
+}
 
 /** How often the discovery catalog is re-observed; well inside the library's 120 s freshness window. */
 const DISCOVERY_REFRESH_MS = 30_000;
 
+/** The alias the context registry gives this node's main session (`ContextRegistry.ensureMain`). */
+const MAIN_CONTEXT = "main";
+
+/** One mutation's identity for the library: a fresh key and a window that outlives this call. */
+function mutation(): { idempotency_key: string; retry_until: string } {
+	return { idempotency_key: crypto.randomUUID(), retry_until: new Date(Date.now() + 60_000).toISOString() };
+}
+
+/** The port a configured public_url names, defaulting by scheme; undefined when it names none. */
+function publicPort(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	try {
+		const url = new URL(value);
+		if (url.port !== "") return Number(url.port);
+		return url.protocol === "https:" ? 443 : 80;
+	} catch {
+		return undefined;
+	}
+}
+
 class OmpRuntime implements PluginRuntime {
 	readonly contexts: ContextRegistry;
 	readonly storage: SqliteStorage;
@@ -73,6 +110,11 @@ class OmpRuntime implements PluginRuntime {
 	node!: OnlyneNode;
 	decider!: JudgeDecider;
 	endpoint = "";
+	/** RFC 0018 §2.1: where the connection being served came from, for the library's own call into `notify`. */
+	private readonly connection = new AsyncLocalStorage<string | undefined>();
+	private readonly log: AcquisitionLog;
+	/** The host side of one approval, built once with the node in `start`. */
+	private peers!: ApprovalDeps;
 	private server?: ReturnType<typeof Bun.serve>;
 	private keyDir?: string;
 	private network?: NetworkDiscovery;
@@ -88,12 +130,45 @@ class OmpRuntime implements PluginRuntime {
 		this.mainAgentId = main.agent.id;
 		this.storage = new SqliteStorage(join(dirname(config.path), "omp.db"));
 		this.contexts = new ContextRegistry(this.storage, config.node.id, main.agent.id);
+		this.log = new AcquisitionLog(this.storage);
 	}
 	async start(): Promise<void> {
 		let handler: (request: Request) => Promise<Response> = async () => new Response(t("initializing"), { status: 503 });
-		this.server = Bun.serve({ hostname: this.config.server.bind, port: 0, fetch: request => handler(request) });
+		// RFC 0018 §2.1: the address a peer statement arrived from is known only here. The
+		// library calls `notify` synchronously from inside the request it is serving, so the
+		// connection's own store is still in scope when the trust event is handled.
+		const serve = (port: number) => Bun.serve({
+			hostname: this.config.server.bind, port,
+			fetch: (request, server) => this.connection.run(server.requestIP(request)?.address, () => handler(request)),
+		});
+		// A configured public_url is a promise about where this node answers. Advertising it
+		// without listening there leaves every peer that pinned the address calling a port
+		// nobody serves, so the port is taken unless it is already in use. Without a public_url
+		// the port this node last bound is reused: an address that changes on every start is one
+		// every peer has to be taught again, and the operator's only recourse is to pin it by hand.
+		const wanted = publicPort(this.config.server.public_url) ?? this.config.server.port;
+		let fellBack = false;
+		// `server.port` is optional because Bun omits it for a unix socket; this listener is TCP.
+		let bound: number;
+		try {
+			this.server = serve(wanted ?? 0);
+			bound = this.server.port!;
+		} catch (error) {
+			if (wanted === undefined) throw error;
+			fellBack = true;
+			this.server = serve(0);
+			bound = this.server.port!;
+			this.pi.logger.warn("onlyne.port.taken", { wanted, bound, error: errorText(error) });
+		}
 		const host = advertisedHost(this.config.server.bind);
-		this.endpoint = `http://${host.includes(":") ? `[${host}]` : host}:${this.server.port}/onlyne/v3`;
+		const actual = `http://${host.includes(":") ? `[${host}]` : host}:${bound}/onlyne/v3`;
+		this.endpoint = this.config.server.public_url === undefined || fellBack ? actual : normalizeServiceUrl(this.config.server.public_url);
+		// The port the system chose is this node's address for as long as it keeps it. Writing it
+		// back is what makes the next start answer where the peers already look, and it costs one
+		// file write on the first start and none afterwards.
+		if (this.config.server.public_url === undefined && this.config.server.port !== bound) {
+			await this.rememberPort(bound);
+		}
 		const instanceId = crypto.randomUUID();
 		// The decider probes peers for their execution contexts, so it must use the node's own
 		// transport: an unsigned probe is refused by every keyed peer.
@@ -107,6 +182,9 @@ class OmpRuntime implements PluginRuntime {
 				else this.pi.logger.debug(message, fields);
 			},
 			listPeers: async () => (await this.node.discovery.listRecords()).filter(record => record.verified_at !== undefined && Date.parse(record.expires_at) > Date.now()),
+			listTrust: async () => (await this.node.trust.list(this.node.auth)).map(row => ({
+				node_id: row.node_id, phase: trustPhase(row), base_url: row.base_url,
+			})),
 			listReceiverContexts: async id => id === this.config.node.id
 				? [
 						{ alias: "main", summary: t("main"), state: this.main.isIdle() ? "idle" : "running" },
@@ -117,8 +195,16 @@ class OmpRuntime implements PluginRuntime {
 							.map(record => ({ alias: record.alias, summary: record.summary, state: record.state }))),
 					]
 				: transport!.request(id, "GET", "/contexts", undefined, this.controller.signal),
-			listThreads: () => allPages(cursor => this.node.threads.list(this.node.auth, { page_size: 100, cursor })),
+			// RFC 0018 §3.2: the handshake thread is this host's own record, never a candidate
+			// for a conversation the agent routes or reads by name.
+			listThreads: async () => (await allPages(cursor => this.node.threads.list(this.node.auth, { page_size: 100, cursor })))
+				.filter(thread => !isTrustThread(this.config.node.id, thread.thread_ref)),
+			listJoinedThreads: async () => (await allPages(cursor => this.node.threads.joined(this.node.auth, { page_size: 100, cursor })))
+				.filter(thread => !isTrustThread(this.config.node.id, thread.thread_ref)),
 			listMessages: (thread, cursor) => this.node.messages.list(this.node.auth, thread, { attention: "thread", page_size: 100, cursor }),
+			listInbox: async () => (await allPages(cursor => this.node.messages.inbox(this.node.auth, { page_size: 100, cursor })))
+				.map(row => ({ context: row.context, attention: row.attention })),
+			threadMembers: async thread => (await this.node.threads.describe(this.node.auth, thread)).members.map(member => member.peer),
 		});
 		const bridge = createRuntimeBridge({ pi: this.pi, main: this.main, decider: this.decider, contexts: this.contexts, nodeId: this.config.node.id });
 		const projectRoot = dirname(dirname(this.config.path));
@@ -145,9 +231,19 @@ class OmpRuntime implements PluginRuntime {
 			},
 		});
 		transport = this.node.transport;
+		this.peers = {
+			policy: acquisitionOf(this.config),
+			log: this.log,
+			observed: async (nodeId, fingerprint) => (await this.log.observation(nodeId, fingerprint))?.observed,
+			declared: async nodeId => (await this.node.trust.entry(nodeId))?.base_url,
+			recorded: nodeId => this.recorded(nodeId),
+			audit: judgement => this.pi.logger.info("onlyne.acquire.decided", judgementFacts(judgement)),
+			accept: (nodeId, fingerprint) => this.node.trust.accept(this.node.auth, nodeId, fingerprint),
+			revoke: nodeId => this.node.trust.revoke(this.node.auth, nodeId),
+			now: () => new Date().toISOString(),
+		};
 		const memberships = (await this.node.domains.list(this.node.auth)).items;
 		const current = memberships[0];
-		const mutation = () => ({ idempotency_key: crypto.randomUUID(), retry_until: new Date(Date.now() + 60_000).toISOString() });
 		if (current && current.domain_id !== this.config.region) await this.node.domains.leave(this.node.auth, current.domain_id, { ...mutation(), expected_revision: current.revision });
 		if (!current || current.domain_id !== this.config.region) {
 			let expected_revision: string | undefined;
@@ -191,11 +287,110 @@ class OmpRuntime implements PluginRuntime {
 			this.pi.logger.info(`onlyne.trust.${event.cause}`, {
 				node: event.entry.node_id, phase: event.phase, fingerprint: event.entry.fingerprint,
 			});
+			// RFC 0018 §2.1: the address this statement arrived from exists only inside the
+			// call the library is making right now, and nothing after it can recover it.
+			this.trustEvent(event, this.connection.getStore());
 		}
 		this.changed();
 	}
 	onChange(listener: () => void): () => void { this.listeners.add(listener); return () => this.listeners.delete(listener); }
 	private changed(): void { for (const listener of this.listeners) listener(); }
+	/**
+	 * RFC 0018 §2/§3: one trust transition's host work — the observation its statement's
+	 * connection left, the judgement of an invitation this host may approve itself, and the
+	 * handshake entry the agent reads. Everything is reported by the library's own call, so it
+	 * runs beside it; a failure here is logged and is never a reason to doubt the committed row.
+	 */
+	private trustEvent(event: TrustNotify, observed: string | undefined): void {
+		void this.handleTrust(event, observed).catch(error => {
+			this.pi.logger.warn("onlyne.trust.handling_failed", { node: event.entry.node_id, phase: event.phase, error: errorText(error) });
+		});
+	}
+	private async handleTrust(event: TrustNotify, observed: string | undefined): Promise<void> {
+		const node = event.entry.node_id;
+		const fingerprint = event.entry.fingerprint;
+		// The address is recorded for every peer statement, before its verdict. Local
+		// transitions never replace it with the address of the approval call (which has none),
+		// so an approval decided later still reads the statement's original connection.
+		const at = new Date().toISOString();
+		if (event.cause === "peer-statement") {
+			await this.log.observe(node, fingerprint, {
+				...(observed === undefined ? {} : { observed }), at, cause: event.cause,
+			});
+		} else await this.log.transition(node, fingerprint, at, event.cause);
+		// RFC 0018 §2.2: the verdict reads the catalog as it stood when the statement arrived.
+		// The record this host derives from that statement is not part of the judgement, or the
+		// two conditions would collapse into one.
+		const recorded = await this.recorded(node);
+		// The statement's own address is also a discovery candidate here, as the tern host's
+		// bridge records it.
+		if (event.entry.base_url) {
+			await this.node.discovery.observe(event.entry.base_url, "trust-statement", node).catch(() => undefined);
+		}
+		// §2.2: only an invitation whose statement covered a connection this host observed, and
+		// whose declared and recorded addresses all stay inside the allow set, is committed
+		// without a human deciding first.
+		const judgement = event.phase === "invited" && event.cause === "peer-statement"
+			? await judgeApproval(this.peers, { node_id: node, fingerprint, observed, recorded })
+			: undefined;
+		if (judgement?.verdict.allowed === true) this.approveDeferred(node, fingerprint);
+		await this.deliverHandshake(event, observed, judgement);
+	}
+	/**
+	 * RFC 0018 §2: the approval an invitation earned is committed outside the library's call,
+	 * so the admission that notified this host is never re-entered.
+	 */
+	private approveDeferred(node: string, fingerprint: string): void {
+		queueMicrotask(() => {
+			void this.peers.accept(node, fingerprint)
+				.catch(error => this.pi.logger.warn("onlyne.acquire.approve_failed", { node, error: errorText(error) }));
+		});
+	}
+	/**
+	 * RFC 0018 §3: one handshake entry per `(node, fingerprint, phase)`, written into this
+	 * node's own thread under a plan bound to the main session. The thread has this node as its
+	 * only member, so the entry never leaves the node.
+	 */
+	private async deliverHandshake(event: TrustNotify, observed: string | undefined, judgement: ApprovalJudgement | undefined): Promise<void> {
+		const node = event.entry.node_id;
+		const fingerprint = event.entry.fingerprint;
+		if (await this.log.delivered(node, fingerprint, event.phase)) return;
+		const handshake = handshakeEntry({
+			node_id: node, fingerprint, phase: event.phase, declared: event.entry.base_url, observed,
+			policy: this.peers.policy, judgement, approved: judgement?.verdict.allowed === true,
+		});
+		await this.ensureTrustThread();
+		const outcome = await this.node.client.send(this.config.node.id, {
+			id: crypto.randomUUID(),
+			sender: this.config.node.id,
+			delivery_kind: "trust",
+			msg: handshake.msg,
+			// The mention is what puts the entry in this node's own inbox: the delivery plan
+			// names the main context, and the bridge reads the facts for its todo hook.
+			meta: { thread: trustThread(this.config.node.id), mentions: [this.config.node.id], data: { trust: handshake.trust } },
+		}, { response: "none", execution: "existing", context: MAIN_CONTEXT });
+		if (outcome.admission !== "accepted") {
+			this.pi.logger.warn("onlyne.trust.delivery_failed", { node, phase: event.phase, error: outcome.error?.message });
+			return;
+		}
+		await this.log.markDelivered(node, fingerprint, event.phase, new Date().toISOString());
+	}
+	/** RFC 0018 §3.2: the handshake thread, created on first use. Its id is fixed, so it is one thread for the node's lifetime. */
+	private async ensureTrustThread(): Promise<void> {
+		const ref = trustThread(this.config.node.id);
+		try {
+			await this.node.threads.describe(this.node.auth, ref);
+			return;
+		} catch (error) {
+			if (!(error instanceof OnlyneError && error.error.code === "not_found")) throw error;
+		}
+		await this.node.threads.create(this.node.auth, { title: TRUST_THREAD, id: ref.id, ...mutation() });
+	}
+	/** RFC 0018 §2.2: every address discovery holds for this node is an outbound candidate the policy must allow. */
+	private async recorded(node: string): Promise<string[]> {
+		const records = await this.node.discovery.listRecords();
+		return [...new Set(records.filter(record => record.node_id === node).map(record => record.base_url))];
+	}
 	/**
 	 * A user-typed address. It is normalized once, read for its own identity and everything it
 	 * declares, and only a successful read becomes a seed. The node keeps running: a seed is a
@@ -242,6 +437,16 @@ class OmpRuntime implements PluginRuntime {
 		const saved = await saveConfig({ ...this.config, discovery: { seeds: [...seeds, seed] } });
 		this.config.discovery = saved.discovery;
 	}
+	/**
+	 * The listening port is configuration for the same reason a seed is: a peer holds the
+	 * address it last reached, and a node that answers somewhere new has moved without telling
+	 * anyone. One write on the first start, and one more only after a port conflict moved it.
+	 */
+	private async rememberPort(port: number): Promise<void> {
+		const saved = await saveConfig({ ...this.config, server: { ...this.config.server, port } });
+		this.config.server = saved.server;
+		this.pi.logger.info("onlyne.port.persisted", { port, path: this.config.path });
+	}
 	/** Stage one of one exchange: the peer's proved fingerprint, and the session that commits it. */
 	async trustBegin(node: string): Promise<KeyExchange> {
 		return this.node.trust.begin(this.node.auth, node);
@@ -252,6 +457,31 @@ class OmpRuntime implements PluginRuntime {
 	async trustRevoke(node: string): Promise<void> {
 		await this.node.trust.revoke(this.node.auth, node);
 	}
+	/** RFC 0018 §2/§3.1: the agent's approval, refused with `policy_denied` when the policy does not allow it. */
+	async acquireAccept(node: string, fingerprint: string): Promise<TrustEntry> {
+		return approvePeer(this.peers, node, fingerprint);
+	}
+	/** RFC 0018 §2/§3.1: the agent's revocation, which no policy judges. */
+	async acquireRevoke(node: string): Promise<void> {
+		await revokePeer(this.peers, node);
+	}
+	/**
+	 * RFC 0018 §2/§3.1: the agent's initiation of one exchange. The judgement reads only what this
+	 * host already stores; the peer's key is read after it, so a refusal sends nothing.
+	 */
+	async acquireBegin(node: string): Promise<TrustEntry> {
+		const row = await this.node.trust.entry(node);
+		const statement = row === undefined ? undefined : (await this.log.observation(node, row.fingerprint))?.observed;
+		const records = (await this.node.discovery.listRecords()).filter(record => record.node_id === node);
+		const observed = outboundObserved({ statement, records, declared: row?.base_url });
+		const request: ApprovalRequest = {
+			node_id: node,
+			...(row === undefined ? {} : { fingerprint: row.fingerprint }),
+			...(observed === undefined ? {} : { observed }),
+		};
+		const committed = await beginPeer(this.peers, target => this.node.trust.begin(this.node.auth, target), request);
+		return committed.entry;
+	}
 	async trustRotate(): Promise<{ fingerprint: string }> {
 		const identity = await this.node.trust.rotate(this.node.auth);
 		return { fingerprint: identity.fingerprint };
@@ -307,6 +537,9 @@ class OmpRuntime implements PluginRuntime {
 		for (const thread of await allPages(cursor => this.node.threads.list(this.node.auth, { page_size: 100, cursor }))) {
 			const ref = thread.thread_ref;
 			hosted.add(`${ref.owner}/${ref.id}`);
+			// RFC 0018 §3.2: the handshake entries stay out of the conversation tree. The
+			// thread is still recorded above, so its own inbox rows are not re-rendered here.
+			if (isTrustThread(this.config.node.id, ref)) continue;
 			const entries = await allPages(cursor => this.node.messages.list(this.node.auth, ref, { attention: "thread", page_size: 100, cursor }));
 			views.push({ ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: thread.title, state: thread.state,
 				unread: inbox.filter(item => !item.injected && item.attention.thread_ref.owner === ref.owner && item.attention.thread_ref.id === ref.id).length,
@@ -319,11 +552,20 @@ class OmpRuntime implements PluginRuntime {
 		// sees the reply and not the question that started it.
 		const outbound = await this.storage.transaction(tx => tx.scan<Outbound>("outbound/"));
 		const seen = new Map<string, ViewerThread>();
+		// A grant can arrive before any message, and a thread this node was invited into is a row
+		// the viewer must show. The local joined listing supplies those rows; the owner is never
+		// asked here, so the viewer stays a read of this node's own records.
+		for (const row of await allPages(cursor => this.node.threads.joined(this.node.auth, { page_size: 100, cursor }))) {
+			const ref = row.thread_ref;
+			const key = `${ref.owner}/${ref.id}`;
+			if (hosted.has(key) || seen.has(key)) continue;
+			seen.set(key, { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: row.last_seq, messages: [], read_only: true });
+		}
 		for (const item of inbox) {
 			const ref = item.attention.thread_ref;
 			const key = `${ref.owner}/${ref.id}`;
 			if (hosted.has(key)) continue;
-			const view = seen.get(key) ?? { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: "0", messages: [] };
+			const view = seen.get(key) ?? { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: "0", messages: [], read_only: true };
 			seen.set(key, view);
 			if (!item.injected) view.unread++;
 			const entry = item.attention.entry;
@@ -338,7 +580,7 @@ class OmpRuntime implements PluginRuntime {
 			const ref = receipt.thread_ref;
 			const key = `${ref.owner}/${ref.id}`;
 			if (hosted.has(key)) continue;
-			const view = seen.get(key) ?? { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: "0", messages: [] };
+			const view = seen.get(key) ?? { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: "0", messages: [], read_only: true };
 			seen.set(key, view);
 			const message = row.value.request.message;
 			view.messages.push({ ref: { sender: message.sender, id: message.id }, seq: receipt.seq, direction: "out", author: message.sender, at: row.value.created_at ?? "", text: message.msg, relation: message.meta?.relation });
@@ -407,6 +649,24 @@ export async function allPages<T>(read: (cursor?: string) => Promise<Page<T>>):
 
 function errorText(error: unknown): string { return error instanceof Error ? error.message : String(error); }
 
+/**
+ * RFC 0018 §2.1–2.2: the address an outbound judgement reads for a peer this host may initiate
+ * with. The arrival address this host recorded for the peer's last statement is the strongest
+ * fact it holds; a peer that never sent one is judged at an address discovery verified by
+ * probing, and with no record at all at the address the library's own fallback would connect to.
+ */
+export function outboundObserved(facts: {
+	statement?: string;
+	records: readonly DiscoveryRecord[];
+	declared?: string;
+}): string | undefined {
+	if (facts.statement !== undefined && facts.statement !== "") return facts.statement;
+	const verified = facts.records
+		.filter(record => record.verified_at !== undefined)
+		.sort((left, right) => right.received_at.localeCompare(left.received_at));
+	return verified[0]?.base_url ?? (facts.declared === "" ? undefined : facts.declared);
+}
+
 /** A verified record beats an unverified one; within each class the newest observation wins. */
 function newerRecord(candidate: DiscoveryRecord, kept: DiscoveryRecord): boolean {
 	const candidateVerified = candidate.verified_at !== undefined;

package/src/tool-text.ts

@@ -7,7 +7,7 @@ const en = {
 	"param.meta": "Explicit references and operation fields",
 	description: `The only surface for Onlyne messages, threads and resources. There is no CLI and nothing else to look up: call this tool with your intent instead of reading docs or source first.
 
-Shape: { delivery_kind, msg, meta }. delivery_kind names the intent in plain language ("reply to dpdp's greeting", "show this thread", "read that message"). meta carries references you already know: to, thread, context, in_reply_to {thread,seq} or {sender,id}, relation (reply|followup), mentions, message {sender,id} or {thread,seq}, resource {owner,id}, operation, expected_revision, op, title, scope, seq, attention, cursor, page_size, data, domain_id, owner, since, event_id, operation_id.
+Shape: { delivery_kind, msg, meta }. delivery_kind names the intent in plain language ("reply to dpdp's greeting", "show this thread", "read that message"). meta carries references you already know: to, thread, context, in_reply_to {thread,seq} (preferred) or {sender,id}, relation (reply|followup), mentions, message {sender,id} or {thread,seq}, resource {owner,id}, operation, expected_revision, op, title, scope, seq, attention, cursor, page_size, data, domain_id, owner, since, event_id, operation_id.
 
 A send is one call. The result is the delivery fact: admission "accepted" means the receiver recorded the message; wait "timed_out" only means no reply arrived before the wait bound, the message is still delivered; reply_body "withheld" means this context already showed that body. Report the outcome and stop there.
 
@@ -32,27 +32,36 @@ meta.to takes one node or a list of nodes. A list is delivered one target at a t
 
 Use cases, each a complete call:
 
-- Reply to a message you received. Do not name a thread; the receiver lands the reply where the original lives:
-  { delivery_kind: "answer dpdp's question", msg: "Yes, the second set is fine.", meta: { in_reply_to: { sender: "urn:onlyne:agent:dpdp", id: "<message id>" }, relation: "reply" } }
+- Reply to a message you received. Reference it as {thread, seq}, copied from the delivery card — never an id from memory; the receiver lands the reply where the original lives:
+  { delivery_kind: "answer dpdp's question", msg: "Yes, the second set is fine.", meta: { in_reply_to: { thread: "<thread id>", seq: "<seq>" }, relation: "reply" } }
 - Send a fresh message to one peer: { delivery_kind: "greet lazuli", msg: "Hello from the workbench.", meta: { to: "lazuli" } }
 - Send the same note to two peers: { delivery_kind: "notify both", msg: "Report is up.", meta: { to: ["caerulea", "lazuli"] } } — you get one result per target, and a failure on one does not hide the other.
 - Read the whole exchange with one peer: read \`onlyne://conversations/<sender>/<id>\` from a list you got at \`onlyne://conversations\`. Read one message with \`onlyne://messages/<sender>/<id>\`.
 - Check what happened to a message you sent: read \`onlyne://outbound/<message-id>\`; it shows the landing the receiver reported, whether it is accepted, and the reply if one arrived.
 - Look at what a resource offers before operating it: read \`onlyne://resources\` or \`onlyne://resources/<owner>/<id>\`, then send the operation as { delivery_kind: "list the operations of this resource", msg: "show me what it can do", meta: { resource: { owner: "<node>", id: "<resource>" }, operation: "<name>" } }. meta.data carries the arguments; meta.expected_revision requires the revision you read.
-- In a subagent, answer without sending: { delivery_kind: "draft the reply", msg: "Here is the answer.", meta: { op: "draft", to: "dpdp", relation: "reply", in_reply_to: { sender: "urn:onlyne:agent:dpdp", id: "<message id>" } } } returns { draft_id }. The main session sends exactly that draft: { delivery_kind: "send the drafted reply", msg: "send draft", meta: { draft_id: "<draft id>" } }.
-- When a send fails with no trusted key, do not retry and do not try to pair: the error names both nodes, the responsible holder and the entry in the host surface. Report it and stop.
-
-The judge role chooses the action and plan from your intent, so never invent message ids, idempotency keys or revisions. A reply or followup states its relation; omitting it is rejected rather than assumed. A reply targets the original reply authority, so a conflicting to is rejected. A subagent session reads its own slice (onlyne://threads, onlyne://inbox, onlyne://contexts) and returns the result to the main session, which does the sending.`,
+- In a subagent, answer without sending: { delivery_kind: "draft the reply", msg: "Here is the answer.", meta: { op: "draft", to: "dpdp", relation: "reply", in_reply_to: { thread: "<thread id>", seq: "<seq>" } } } returns { draft_id }. The main session sends exactly that draft: { delivery_kind: "send the drafted reply", msg: "send draft", meta: { draft_id: "<draft id>" } }.
+- Approve a peer whose invitation waits for you: { delivery_kind: "accept the trust handshake", msg: "accept the peer", meta: { op: "trust_accept", node_id: "<node>", fingerprint: "<fingerprint>" } }. The acquisition policy judges it first, and a refusal names the rule it matched and leaves the peer as it was.
+- Drop an approval: { delivery_kind: "revoke the trust handshake", msg: "revoke the peer", meta: { op: "trust_revoke", node_id: "<node>" } }. Revocation is never judged by the policy and names no fingerprint.
+- Start an exchange with a discovered peer you are not paired with yet: { delivery_kind: "start the handshake with lazuli", msg: "start the exchange", meta: { op: "trust_begin", node_id: "lazuli" } }. The acquisition policy judges it before anything is sent: a refusal names the rule it matched and leaves the peer as it was, and an allow commits the local approval, sends the statement and reports the phase that followed.
+- Put a peer into a conversation, so the thread carries several members: { delivery_kind: "add dpdp to the plan thread", msg: "add dpdp", meta: { op: "member_add", thread: "<thread id or title>", to: "dpdp" } }; one call per member when meta.to is a list. Take one out with op "member_remove". Adding a member puts them in that thread, so a later meta.to array WITH meta.thread addresses one thread, while without meta.thread each target gets its own.
+- When a send fails with no trusted key, do not retry: the error names both nodes, and a pending invitation is confirmed by the acquisition policy or by that node's holder, not by another send. Report it and stop.
+
+The judge role chooses the action and plan from your intent, so never invent message ids, idempotency keys or revisions. Reference a message as {thread, seq}; when a call states neither a reference nor a relation and this context has unanswered inbound messages, the judge asks which one it answers. A reply targets the original reply authority, so a conflicting to is rejected. A subagent session reads its own slice (onlyne://threads, onlyne://inbox, onlyne://contexts) and returns the result to the main session, which does the sending.`,
 	"summary.no_result": "Onlyne returned no structured result.",
-	"summary.where": " to {owner}",
-	"summary.thread_ref": " (thread {thread} seq {seq}{answering})",
+	"summary.addressee": "Sent to {to}",
+	"summary.addressee_self": "Sent to yourself",
+	"summary.stored_here": "thread {thread} is hosted on your node, seq {seq}{answering}",
+	"summary.stored_there": "thread {thread} is hosted on {owner}, seq {seq}{answering}",
 	"summary.answering": ", answering {sender}/{id}",
-	"summary.outbound": " · read back: onlyne://outbound/{id}",
-	"summary.delivered": "Delivered{where}{facts}{trail} and recorded durably.",
-	"summary.delivered_answered": "Delivered{where}{facts}{trail}. {author} answered at seq {seq}.",
-	"summary.delivered_withheld": "Delivered{where}{facts}{trail}. {author} answered at seq {seq}, but that body was already shown in this context, so only its arrival is reported.",
-	"summary.delivered_timed_out": "Delivered{where}{facts}{trail} and recorded durably. No reply arrived within the wait; it will arrive on its own as an inbound message.",
-	"summary.delivered_cancelled": "Delivered{where}{facts}{trail} and recorded durably. The wait was cancelled; a reply will arrive on its own as an inbound message.",
+	"summary.sep": " · ",
+	"summary.resolved": "resolved: {node}",
+	"summary.outbound": "read back: onlyne://outbound/{id}",
+	"summary.grant_notice": "; the entry lives here because you host the thread, and {to} reads it as a member once the grant notice reaches it",
+	"summary.delivered": "{facts} and recorded durably{mechanism}.",
+	"summary.delivered_answered": "{facts} and recorded durably{mechanism}. {author} answered at seq {seq}.",
+	"summary.delivered_withheld": "{facts} and recorded durably{mechanism}. {author} answered at seq {seq}, but that body was already shown in this context, so only its arrival is reported.",
+	"summary.delivered_timed_out": "{facts} and recorded durably{mechanism}. No reply arrived within the wait; it will arrive on its own as an inbound message.",
+	"summary.delivered_cancelled": "{facts} and recorded durably{mechanism}. The wait was cancelled; a reply will arrive on its own as an inbound message.",
 	"summary.not_confirmed": "Not confirmed: {failure}. {next}",
 	"summary.retry": "The record stays open and the runtime retries it; sending again would commit a second intent.",
 	"summary.recover": "The record stays open for recovery; do not re-send the same intent.",
@@ -63,6 +72,14 @@ The judge role chooses the action and plan from your intent, so never invent mes
 	"draft.ready": "Draft {draft_id} is ready; the main session sends it with meta.draft_id.",
 	"multi.delivered": "→ {to}: {summary}",
 	"multi.failed": "→ {to}: not sent — {error}",
+	"trust.accepted": "Approved {node} ({fingerprint}); the trust phase is now {phase}.",
+	"trust.revoked": "Revoked {node}; local approval is dropped.",
+	"trust.begun": "Started the exchange with {node} ({fingerprint}); the trust phase is now {phase}. The local approval is committed and the statement is sent, so this peer can exchange messages once it approves in turn.",
+	"thread.member_added": "Added {member} to thread {thread}. That member now reads and posts in it, and a later meta.to array with meta.thread {thread} puts every target in this one thread; the same array without meta.thread gives each target its own thread.",
+	"thread.member_removed": "Removed {member} from thread {thread}. The thread stays open and its earlier entries are still its history; a later bare send to {member} opens its own two-party thread.",
+	"failure.trust_node_unknown": "{action} names no known node {node}. Name the node id, or a short alias that exactly one known peer carries.",
+	"failure.trust_fields": "A trust action needs a non-empty string {field}.",
+	"failure.trust_main_only": "Only the main session approves or revokes a peer; a subagent drafts instead.",
 } as const;
 
 const zh: Record<keyof typeof en, string> = {
@@ -72,7 +89,7 @@ const zh: Record<keyof typeof en, string> = {
 	"param.meta": "显式引用与操作字段",
 	description: `Onlyne 消息、thread 与资源的唯一入口。没有 CLI，也没有别处要查：把意图交给这个工具，不要先去读文档或源码。
 
-形状：{ delivery_kind, msg, meta }。delivery_kind 用日常语言说出意图（“回复 dpdp 的问候”“看看这个 thread”“读那条消息”）。meta 放你已经知道的引用：to、thread、context、in_reply_to {thread,seq} 或 {sender,id}、relation（reply|followup）、mentions、message {sender,id} 或 {thread,seq}、resource {owner,id}、operation、expected_revision、op、title、scope、seq、attention、cursor、page_size、data、domain_id、owner、since、event_id、operation_id。
+形状：{ delivery_kind, msg, meta }。delivery_kind 用日常语言说出意图（“回复 dpdp 的问候”“看看这个 thread”“读那条消息”）。meta 放你已经知道的引用：to、thread、context、in_reply_to {thread,seq}（首选）或 {sender,id}、relation（reply|followup）、mentions、message {sender,id} 或 {thread,seq}、resource {owner,id}、operation、expected_revision、op、title、scope、seq、attention、cursor、page_size、data、domain_id、owner、since、event_id、operation_id。
 
 发送是一次调用。结果就是投递事实：admission "accepted" 表示接收方已经记录这条消息；wait "timed_out" 只表示等待期内没有回信，消息本身已经投递；reply_body "withheld" 表示这个上下文已经展示过那段正文。报告结果，到此为止。
 
@@ -97,27 +114,36 @@ meta.to 接受一个节点或一组节点。一组会逐个目标投递，每个
 
 用例，每个都是完整调用：
 
-- 回复你收到的消息。不要指名 thread；接收方会把回信放到原消息所在的 thread：
-  { delivery_kind: "回答 dpdp 的问题", msg: "可以，第二组没问题。", meta: { in_reply_to: { sender: "urn:onlyne:agent:dpdp", id: "<message id>" }, relation: "reply" } }
+- 回复你收到的消息。引用写成 {thread, seq}，从投递卡片上照抄——绝不凭记忆写 id；接收方会把回信放到原消息所在的 thread：
+  { delivery_kind: "回答 dpdp 的问题", msg: "可以，第二组没问题。", meta: { in_reply_to: { thread: "<thread id>", seq: "<seq>" }, relation: "reply" } }
 - 给一个 peer 发新消息：{ delivery_kind: "向 lazuli 问好", msg: "来自工作台的问候。", meta: { to: "lazuli" } }
 - 把同一段话发给两个 peer：{ delivery_kind: "通知双方", msg: "报告已上传。", meta: { to: ["caerulea", "lazuli"] } } —— 每个目标各得一条结果，某个目标失败不会掩盖另一个。
 - 读与某个 peer 的整段往来：先读 \`onlyne://conversations\` 拿到一条，再读 \`onlyne://conversations/<sender>/<id>\`。读单条消息用 \`onlyne://messages/<sender>/<id>\`。
 - 查你发出的消息后来怎样了：读 \`onlyne://outbound/<message-id>\`；它显示接收方报告的落点、是否被接纳，以及回信（如果到了）。
 - 操作资源前先看它提供什么：读 \`onlyne://resources\` 或 \`onlyne://resources/<owner>/<id>\`，然后发操作 { delivery_kind: "列出该资源的操作", msg: "看看它能做什么", meta: { resource: { owner: "<node>", id: "<resource>" }, operation: "<name>" } }。meta.data 带参数；meta.expected_revision 要求版本与你读到的一致。
-- 在子代理里，只写不发：{ delivery_kind: "起草回复", msg: "这是答案。", meta: { op: "draft", to: "dpdp", relation: "reply", in_reply_to: { sender: "urn:onlyne:agent:dpdp", id: "<message id>" } } } 返回 { draft_id }。主会话原样发出这份草稿：{ delivery_kind: "发出起草的回复", msg: "发送草稿", meta: { draft_id: "<draft id>" } }。
-- 发送失败且没有可信密钥时，不要重试也不要尝试配对：错误里写明了两个节点、负责的持有者和宿主界面上的入口。报告它，然后停下。
-
-动作和执行计划由 judge 角色根据你的意图选择，所以永远不要自己编 message id、幂等键或版本号。回信或 followup 必须说明关系；省略会被拒绝，而不是被假定。回信只针对原来的回信权限方，所以冲突的 to 会被拒绝。子代理会话读自己的切片（onlyne://threads、onlyne://inbox、onlyne://contexts），把结果交回主会话，由主会话发送。`,
+- 在子代理里，只写不发：{ delivery_kind: "起草回复", msg: "这是答案。", meta: { op: "draft", to: "dpdp", relation: "reply", in_reply_to: { thread: "<thread id>", seq: "<seq>" } } } 返回 { draft_id }。主会话原样发出这份草稿：{ delivery_kind: "发出起草的回复", msg: "发送草稿", meta: { draft_id: "<draft id>" } }。
+- 批准一个在等你决定的对端：{ delivery_kind: "批准信任握手", msg: "批准这个对端", meta: { op: "trust_accept", node_id: "<node>", fingerprint: "<fingerprint>" } }。先由获取策略判定；被拒时错误里写明命中的规则，对端保持原样。
+- 撤回一次批准：{ delivery_kind: "撤销信任握手", msg: "撤销这个对端", meta: { op: "trust_revoke", node_id: "<node>" } }。撤销永远不受策略限制，也不需要指纹。
+- 与一个已发现但尚未配对的对端发起交换：{ delivery_kind: "与 lazuli 开始握手", msg: "开始交换", meta: { op: "trust_begin", node_id: "lazuli" } }。获取策略会在发出任何请求之前判定：被拒时错误里写明命中的规则，对端保持原样；放行时提交本地批准、发出陈述，并报告其后的信任阶段。
+- 把一个对端加进一段对话，让这个 thread 带多个成员：{ delivery_kind: "把 dpdp 加进 plan thread", msg: "加上 dpdp", meta: { op: "member_add", thread: "<thread id 或标题>", to: "dpdp" } }；meta.to 是列表时每个成员各一次调用。用 op "member_remove" 移出。加入成员就是把他放进那个 thread，所以之后带 meta.thread 的 meta.to 数组只指向一个 thread，不带 meta.thread 时每个目标各得一个。
+- 发送失败且没有可信密钥时，不要重试：错误里写明了两个节点；待确认的邀请由获取策略或那一侧的持有者确认，再发一次不会。报告它，然后停下。
+
+动作和执行计划由 judge 角色根据你的意图选择，所以永远不要自己编 message id、幂等键或版本号。引用消息一律写成 {thread, seq}；当一次调用既没有引用也没有 relation、而本上下文还有未答复的入站消息时，由 judge 判断它在回答哪一条。回信只针对原来的回信权限方，所以冲突的 to 会被拒绝。子代理会话读自己的切片（onlyne://threads、onlyne://inbox、onlyne://contexts），把结果交回主会话，由主会话发送。`,
 	"summary.no_result": "Onlyne 没有返回结构化结果。",
-	"summary.where": "，投递给 {owner}",
-	"summary.thread_ref": "（thread {thread} seq {seq}{answering}）",
+	"summary.addressee": "已发给 {to}",
+	"summary.addressee_self": "已发给自己",
+	"summary.stored_here": "thread {thread} 建在你这侧，seq {seq}{answering}",
+	"summary.stored_there": "thread {thread} 建在 {owner} 那侧，seq {seq}{answering}",
 	"summary.answering": "，回复 {sender}/{id}",
-	"summary.outbound": "；读回: onlyne://outbound/{id}",
-	"summary.delivered": "已送达{where}{facts}，并已持久记录{trail}。",
-	"summary.delivered_answered": "已送达{where}{facts}，并已持久记录{trail}。{author} 在 seq {seq} 回复了。",
-	"summary.delivered_withheld": "已送达{where}{facts}，并已持久记录{trail}。{author} 在 seq {seq} 回复了，但那段正文已经在这个上下文里展示过，所以只报告它到达。",
-	"summary.delivered_timed_out": "已送达{where}{facts}，并已持久记录{trail}。等待期内没有回信；回信会作为入站消息自己到达。",
-	"summary.delivered_cancelled": "已送达{where}{facts}，并已持久记录{trail}。等待被取消；回信会作为入站消息自己到达。",
+	"summary.sep": "；",
+	"summary.resolved": "resolved: {node}",
+	"summary.outbound": "读回: onlyne://outbound/{id}",
+	"summary.grant_notice": "；条目留在你这里是因为 thread 由你持有，{to} 收到 grant 通知后作为成员读它",
+	"summary.delivered": "{facts}，并已持久记录{mechanism}。",
+	"summary.delivered_answered": "{facts}，并已持久记录{mechanism}。{author} 在 seq {seq} 回复了。",
+	"summary.delivered_withheld": "{facts}，并已持久记录{mechanism}。{author} 在 seq {seq} 回复了，但那段正文已经在这个上下文里展示过，所以只报告它到达。",
+	"summary.delivered_timed_out": "{facts}，并已持久记录{mechanism}。等待期内没有回信；回信会作为入站消息自己到达。",
+	"summary.delivered_cancelled": "{facts}，并已持久记录{mechanism}。等待被取消；回信会作为入站消息自己到达。",
 	"summary.not_confirmed": "未确认：{failure}。{next}",
 	"summary.retry": "记录保持打开，运行时自己重试；再发一次会提交第二个意图。",
 	"summary.recover": "记录保持打开，等待恢复；不要再发同一个意图。",
@@ -128,6 +154,14 @@ meta.to 接受一个节点或一组节点。一组会逐个目标投递，每个
 	"draft.ready": "草稿 {draft_id} 已就绪；主会话用 meta.draft_id 发出它。",
 	"multi.delivered": "→ {to}: {summary}",
 	"multi.failed": "→ {to}: 未发送 —— {error}",
+	"trust.accepted": "已批准 {node}（{fingerprint}），信任阶段现在是 {phase}。",
+	"trust.revoked": "已撤销 {node}；本地批准已撤回。",
+	"trust.begun": "已与 {node}（{fingerprint}）发起交换，信任阶段现在是 {phase}。本地批准已提交、陈述已发出，等对端反向批准后即可互通消息。",
+	"thread.member_added": "已把 {member} 加入 thread {thread}。该成员现在可以读写这个 thread；之后带 meta.thread {thread} 的 meta.to 数组会把每个目标都放进这一个 thread，而不带 meta.thread 的同一数组会让每个目标各得一个 thread。",
+	"thread.member_removed": "已把 {member} 移出 thread {thread}。thread 本身保留、此前的条目仍是它的历史；之后单独发给 {member} 的消息会另开一个两人 thread。",
+	"failure.trust_node_unknown": "{action} 没有指名任何已知节点 {node}。写节点 id，或写只有一个已知对端持有的短别名。",
+	"failure.trust_fields": "信任动作需要非空字符串字段 {field}。",
+	"failure.trust_main_only": "只有主会话可以批准或撤销对端；子代理只能起草。",
 };
 
 export const toolText = createTranslator({ en, "zh-CN": zh });