omp-onlyne 0.0.0-stage → 0.2.0

package/src/messages.ts

@@ -0,0 +1,427 @@
+import { OnlyneError, type DeliveryPlan, type Entry, type Message, type NotifyEvent, type Runtime, type TraceEvent } from "@onlyne/lib";
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { AgentRegistry } from "@oh-my-pi/pi-coding-agent/registry/agent-registry";
+import { refreshMailCards, renderMailMessage, type OnlyneMessageDetails } from "./ui/mail-message.ts";
+import type { InboundDecision, JudgeDecider } from "./decider.ts";
+import type { ContextRegistry } from "./store.ts";
+import type { ContextRecord } from "./types.ts";
+import { AWAIT_CONSUMED, pendingAwaitResults } from "./tool.ts";
+import { applyMessageTodo, type TodoPlanner } from "./todo.ts";
+import { getRuntime } from "./runtime.ts";
+import { handshakeFacts } from "./handshake.ts";
+import { bridgeText as t } from "./bridge-text.ts";
+
+export const INBOUND = "onlyne.inbound";
+export const ROUTING = "onlyne.routing";
+export const SUPPLEMENT = "onlyne.supplement";
+
+export interface BridgeDeps {
+	pi: ExtensionAPI;
+	main: ExtensionContext;
+	decider: JudgeDecider;
+	contexts: ContextRegistry;
+	nodeId: string;
+	/** Wall clock, so the escalation window can be tested without waiting for it. */
+	now?: () => number;
+}
+/**
+ * One inbound entry is judged once per process. A retry replays the recorded decision
+ * and, at most, the delivery it names; asking the judge again would turn the
+ * maintenance tick into a model poll (RFC 0005 §1: one message gets one action). A
+ * failed judgment is recorded too: the entry stays owed, and the tick does not re-ask.
+ */
+interface InboundAttempt {
+	decision?: InboundDecision;
+	failure?: OnlyneError;
+	landed?: string;
+	/** Maintenance passes this entry has been reported landed without being confirmed. */
+	passes?: number;
+	/** Whether the held delivery has already been forced through as a trigger. */
+	escalated?: boolean;
+	/** Set once the second window passed with no confirmation; the warning is written once. */
+	unconfirmed?: boolean;
+	/** How the delivery was submitted: a trigger starts work, a next-turn fragment waits. */
+	delivery?: { via: "trigger" | "nextTurn"; at: number };
+}
+
+/**
+ * How long a next-turn fragment may stay unread before the host offers it again. A turn takes at
+ * least one provider round trip, so a window measured in maintenance passes fires while the
+ * session is still working and duplicates the delivery (dpdp report, follow_up queue).
+ */
+const NEXT_TURN_ESCALATE_MS = 60_000;
+/** Times an entry may be decided again after its binding went away before it is delivered instead. */
+const MAX_REDECISIONS = 2;
+const inboundAttempts = new Map<string, InboundAttempt>();
+/**
+ * Deliveries attempted per entry, kept outside the attempt record: dropping that record is what
+ * makes the next pass decide again, and it must not reset the budget that bounds the deciding.
+ */
+const deliveryAttempts = new Map<string, number>();
+
+function countedAttempt(key: string): number {
+	const next = (deliveryAttempts.get(key) ?? 0) + 1;
+	deliveryAttempts.set(key, next);
+	return next;
+}
+
+/** The end of the line for an entry nothing can hold: the main session takes it once, visibly. */
+function escalate(deps: BridgeDeps, entry: Entry, key: string, reason: string) {
+	const token = registerPending(entry, deps.main.agent.id, "fragment");
+	deps.pi.sendMessage(payload(entry, INBOUND, token), { triggerTurn: true });
+	deps.pi.logger.info("onlyne.delivery.escalated", { entry: key, reason, attempts: deliveryAttempts.get(key) });
+	return { context: deps.main.agent.id, consumed: false, outcome: "delivered" as const };
+}
+
+function inboundKey(entry: Entry): string {
+	return `${entry.thread_ref.owner}/${entry.thread_ref.id}/${entry.seq}`;
+}
+/** Transitions that repeat every maintenance pass once a record is decided. */
+const TRACE_DEBUG = new Set(["inbound.inject", "inbound.duplicate"]);
+
+export function createRuntimeBridge(deps: BridgeDeps): Runtime {
+	const now = deps.now ?? Date.now;
+	return {
+		/**
+		 * Admission is the last cheap place to refuse a plan this host cannot honor (RFC 0005
+		 * §1): a `new` context needs the task tool. It runs inside the library's admission
+		 * transaction, so it may not read the context registry — that opens a second transaction
+		 * on the same store and waits on itself. A plan that names a lost context is refused by
+		 * `decideInbound` instead, which runs outside any transaction.
+		 */
+		async supports(plan: DeliveryPlan, _message?: Message): Promise<boolean> {
+			return plan.execution !== "new" || taskTool(deps.main) !== undefined;
+		},
+		trace: (event: TraceEvent) => {
+			const fields = { ...event } as Record<string, unknown>;
+			const name = String(fields.event);
+			delete fields.event;
+			const thread = fields.thread as { owner?: unknown; id?: unknown } | undefined;
+			if (thread !== undefined) fields.thread = `${String(thread.owner)}/${String(thread.id)}`;
+			if (TRACE_DEBUG.has(name)) deps.pi.logger.debug(`onlyne.${name}`, fields);
+			else deps.pi.logger.info(`onlyne.${name}`, fields);
+		},
+		async inject(entry: Entry, context?: string, plan?: DeliveryPlan) {
+			const key = inboundKey(entry);
+			let attempt = inboundAttempts.get(key);
+			if (attempt === undefined) {
+				const started = Date.now();
+				let decision: InboundDecision;
+				try {
+					decision = await deps.decider.decideInbound(deps.main, entry, plan);
+				} catch (error) {
+					const failure = error instanceof OnlyneError
+						? error
+						: new OnlyneError("decision_unavailable", error instanceof Error ? error.message : String(error));
+					deps.pi.logger.warn("onlyne.judge.failed", {
+						entry: key, ms: Date.now() - started, error: failure.message,
+					});
+					inboundAttempts.set(key, { failure });
+					throw failure;
+				}
+				attempt = { decision };
+				inboundAttempts.set(key, attempt);
+				deps.pi.logger.info("onlyne.judge.answered", {
+					entry: key, action: decision.action, ms: Date.now() - started,
+					...(decision.context === undefined ? {} : { context: decision.context }),
+				});
+			}
+			if (attempt.failure !== undefined) {
+				// A lost binding cannot be re-decided into existence: past the budget the entry is
+				// delivered to the main session instead, so the judgement stops burning model calls
+				// and the message stops being invisible.
+				if (attempt.failure.error.code === "context_lost" && countedAttempt(key) > MAX_REDECISIONS) {
+					return escalate(deps, entry, key, "context-lost");
+				}
+				deps.pi.logger.debug("onlyne.delivery.held", { entry: key, reason: "judge-failed", error: attempt.failure.message });
+				throw attempt.failure;
+			}
+			const decision = attempt.decision;
+			if (decision === undefined) throw new OnlyneError("decision_unavailable", t("noDecision"));
+			// The body is already where the decision put it; re-sending it would append a
+			// second copy that the cursor can only confirm once.
+			if (attempt.landed !== undefined) {
+			// RFC 0008 §5: a delivery is landed only while the context holding it can still
+			// confirm it. A subagent session that ended leaves the entry unconfirmed forever,
+			// and reporting it delivered on every maintenance pass is a retry storm, not a
+			// delivery. Mark the dead binding lost and let the next pass decide again.
+			const holder = (await deps.contexts.list()).find(record => record.agent_id === attempt.landed);
+			if (holder !== undefined && holder.state !== "idle" && holder.state !== "running") {
+				if (countedAttempt(key) > MAX_REDECISIONS) return escalate(deps, entry, key, "context-lost");
+				await deps.contexts.updateState(holder.alias, "lost").catch(() => undefined);
+				inboundAttempts.delete(key);
+				throw new OnlyneError("context_lost", t("contextLost", { alias: holder.alias }), { context: holder.alias });
+			}
+			// A delivery nobody confirmed has two shapes and one bound. A next-turn fragment waits
+			// for an assembly the session may never reach. A trigger starts its own turn, and that
+			// turn can die before the model reads the payload — a provider response at or above 400
+			// drops the observation it recorded — leaving the entry unconfirmed while every pass
+			// reports it delivered. Both are retried once, after a window long enough to be sure the
+			// session is not simply working, and only while it is idle right now.
+			attempt.passes = (attempt.passes ?? 0) + 1;
+			const delivery = attempt.delivery;
+			const waiting = delivery !== undefined && now() - delivery.at >= NEXT_TURN_ESCALATE_MS;
+			if (attempt.landed === deps.main.agent.id && waiting && delivery !== undefined && deps.main.isIdle()) {
+				if (attempt.escalated !== true) {
+					attempt.escalated = true;
+					// The retry opens its own window; measuring the second one from the first send
+					// would report it as unconfirmed on the very next pass.
+					attempt.delivery = { via: "trigger", at: now() };
+					const token = registerPending(entry, deps.main.agent.id, "fragment");
+					deps.pi.sendMessage(payload(entry, INBOUND, token), { triggerTurn: true });
+					deps.pi.logger.info("onlyne.delivery.escalated", {
+						entry: key, reason: "unconfirmed", via: delivery.via, waited_ms: now() - delivery.at,
+					});
+				} else if (attempt.unconfirmed !== true) {
+					// One warning per entry: the reason is recorded once, and the pass stops shouting.
+					attempt.unconfirmed = true;
+					deps.pi.logger.warn("onlyne.delivery.unconfirmed", {
+						entry: key, via: delivery.via, passes: attempt.passes, waited_ms: now() - delivery.at, context: attempt.landed,
+					});
+				}
+			}
+				deps.pi.logger.debug("onlyne.delivery.held", { entry: key, reason: "already-delivered", context: attempt.landed });
+				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
+			}
+			if (decision.action === "new_subagent") {
+				attempt.landed = await startSubagent(deps, entry);
+				// A spawn is a submission, not a read: the child's prompt carries the token and its
+				// first provider request is the proof, so nothing is consumed here.
+				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
+			}
+			if (decision.action === "context") {
+				const alias = decision.context;
+				if (alias === undefined) throw new OnlyneError("decision_unavailable", t("noContextNamed"));
+				const record = await deps.contexts.find(alias);
+				if (record?.agent_id === undefined || record.state === "lost" || record.state === "unbound") {
+					// The binding went away between the decision and the delivery: the entry stays
+					// owed, and an explicit new decision is the only way to land it (RFC 0005 §1).
+					throw new OnlyneError("context_lost", t("contextLost", { alias }), { context: alias });
+				}
+				const token = registerPending(entry, record.agent_id, "fragment");
+				try {
+					await deliverToContext(record.agent_id, payload(entry, SUPPLEMENT, token), record.state === "running");
+				} catch (error) {
+					// The session behind this context is gone. Mark the binding lost so no decision
+					// offers it again, and keep the entry owed: a silent delivery into a disposed
+					// session is how a reply disappears (caerulea report 3, problem 1).
+					await deps.contexts.updateState(alias, "lost").catch(() => undefined);
+					throw error;
+				}
+				attempt.landed = record.agent_id;
+				deps.pi.logger.info("onlyne.delivery.sent", { entry: key, action: "context", target: record.agent_id, running: record.state === "running" });
+				return { context: record.agent_id, consumed: false, outcome: "delivered" as const };
+			}
+			const token = registerPending(entry, deps.main.agent.id, "fragment");
+			if (decision.action === "wake") {
+				// An explicit deliverAs never starts a turn on an idle session, so an idle main
+				// session gets a plain trigger whatever the insertion mode says.
+				const idle = deps.main.isIdle();
+				const mode = idle ? undefined : decision.insertion;
+				deps.pi.sendMessage(
+					payload(entry, INBOUND, token),
+					mode === undefined ? { triggerTurn: true } : { deliverAs: mode === "steer" ? "steer" : "followUp" },
+				);
+				attempt.delivery = { via: "trigger", at: now() };
+			} else {
+				// RFC 0008 §7: a fragment enters the next context assembly without starting a turn.
+				// An idle session never reaches that assembly by itself, so the entry would sit in
+				// the queue as `injected: false` forever; idle means there is no turn to wait for.
+				const idle = deps.main.isIdle();
+				deps.pi.sendMessage(payload(entry, INBOUND, token), idle ? { triggerTurn: true } : { deliverAs: "nextTurn" });
+				if (idle) deps.pi.logger.info("onlyne.delivery.escalated", { entry: key, reason: "idle-fragment" });
+				attempt.delivery = { via: idle ? "trigger" : "nextTurn", at: now() };
+			}
+			attempt.landed = deps.main.agent.id;
+			deps.pi.logger.info("onlyne.delivery.sent", {
+				entry: key, action: decision.action, target: deps.main.agent.id, turn: decision.action === "wake",
+				...(decision.insertion === undefined ? {} : { insertion: decision.insertion }),
+			});
+			return { context: deps.main.agent.id, consumed: false, outcome: "delivered" as const };
+		},
+		todo: async (entry, context) => {
+			inboundAttempts.delete(inboundKey(entry));
+			deliveryAttempts.delete(inboundKey(entry));
+			// RFC 0018 §3: a handshake status update is delivered for the record, not as work.
+			// Only an entry that owes a decision takes the todo decision path.
+			if (handshakeFacts(entry.message.meta)?.pending === false) {
+				refreshMailCards();
+				return;
+			}
+			const planner: TodoPlanner = {
+				decideTodo: (incoming, current) => deps.decider.decideTodo(deps.main, incoming, current),
+			};
+			await applyMessageTodo(entry, context, planner);
+			// The card reports the consumption this hook just served.
+			refreshMailCards();
+		},
+		notify: (event: NotifyEvent) => {
+			getRuntime()?.notify(event);
+		},
+	};
+}
+
+/** A provider request contains the payload; submission only schedules it. */
+interface PendingObservation {
+	entry: Entry;
+	context: string;
+	kind: "fragment" | "tool_result";
+}
+const pending = new Map<string, PendingObservation>();
+const toolResults = new Map<string, PendingObservation>();
+const observed = new Map<string, string[]>();
+
+function registerPending(entry: Entry, context: string, kind: PendingObservation["kind"], token = `onlyne-${crypto.randomUUID()}`): string {
+	pending.set(token, { entry, context, kind });
+	return token;
+}
+export function observeToolResult(toolCallId: string, entry: Entry, context: string): void {
+	toolResults.set(toolCallId, { entry, context, kind: "tool_result" });
+}
+export function registerProviderBoundary(pi: ExtensionAPI): void {
+	pi.on("before_provider_request", (event, ctx) => {
+		for (const result of pendingAwaitResults(ctx.sessionManager.getBranch())) {
+			if (result.context === ctx.agent.id) observeToolResult(result.toolCallId, result.entry, result.context);
+		}
+		const text = typeof event.payload === "string" ? event.payload : JSON.stringify(event.payload);
+		const found: string[] = [];
+		for (const [token, record] of pending) if (record.context === ctx.agent.id && text.includes(token)) found.push(token);
+		for (const [toolCallId, record] of toolResults) {
+			if (record.context !== ctx.agent.id || !text.includes(toolCallId)) continue;
+			pending.set(`tool:${toolCallId}`, record);
+			toolResults.delete(toolCallId);
+			found.push(`tool:${toolCallId}`);
+		}
+		observed.set(ctx.agent.id, found);
+	});
+	pi.on("after_provider_response", async (event, ctx) => {
+		const tokens = observed.get(ctx.agent.id) ?? [];
+		observed.delete(ctx.agent.id);
+		if (event.status >= 400) return;
+		const runtime = getRuntime();
+		if (!runtime) return;
+		for (const token of tokens) {
+			const record = pending.get(token);
+			if (!record) continue;
+			try {
+				await runtime.node.client.confirmConsumption(record.entry, record.context, record.kind);
+				// A confirmed consumption changes what the delivery card reports.
+				refreshMailCards();
+				if (record.kind === "tool_result") pi.appendEntry(AWAIT_CONSUMED, {
+					tool_call_id: token.slice("tool:".length), context: record.context,
+					ref: { sender: record.entry.message.sender, id: record.entry.message.id },
+					thread_ref: record.entry.thread_ref, seq: record.entry.seq, at: new Date().toISOString(),
+				});
+				pending.delete(token);
+			} catch (error) {
+				pi.logger.warn("onlyne.consumption.failed", {
+					entry: inboundKey(record.entry), context: record.context, via: record.kind,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+	});
+}
+
+async function deliverToContext(agentId: string, payload: MessagePayload, running: boolean): Promise<void> {
+	// Never revive a session for an inbound delivery: a disposed subagent accepts the message
+	// where nobody reads it, and the library records the injection as delivered.
+	const session = AgentRegistry.global().get(agentId)?.session ?? undefined;
+	if (session === undefined) throw new OnlyneError("not_found", t("noLiveSession", { context: agentId }));
+	await session.sendCustomMessage(payload, running ? { deliverAs: "steer" } : { triggerTurn: true });
+}
+/**
+ * One source message owns one context, for the process lifetime: a replay of the same
+ * inbox record (the maintain loop's every-2s pass) must never spawn a second task. A
+ * record bound to a live agent is returned as is; an unbound one from a failed earlier
+ * spawn is reused under its own alias. The task text is the child's first prompt and it
+ * carries the consumption token, so the child's first provider request is what proves the
+ * model read the delivery; the spawn itself consumes nothing.
+ */
+async function startSubagent(deps: BridgeDeps, entry: Entry): Promise<string> {
+	const existing = await findContextBySource(deps.contexts, entry);
+	if (existing?.agent_id !== undefined) return existing.agent_id;
+	const tool = taskTool(deps.main);
+	if (!tool) throw new OnlyneError("unsupported_delivery", t("noTaskTool"));
+	// Both references the child can actually use: the message id for `{sender,id}` replies and
+	// the thread/seq pair for reads. A bare `thread/seq` string fits neither (cyanea report 1).
+	const source = `${entry.thread_ref.owner}/${entry.thread_ref.id}/${entry.seq}`;
+	const references = t("deliveryReferences", {
+		message: entry.message.id,
+		thread: `${entry.thread_ref.owner}/${entry.thread_ref.id}`,
+		seq: entry.seq,
+	});
+	const record = existing ?? await deps.contexts.allocate(entry.thread_ref, `onlyne ${source}`, entry.message);
+	const name = `onlyne-${record.alias}`;
+	const token = `onlyne-${crypto.randomUUID()}`;
+	const result = await tool.execute(`onlyne-${crypto.randomUUID()}`, {
+		// The child cannot send: its task text says so and names the one structured return that
+		// does work, because a session told to "handle" a delivery with no send right reads the
+		// refusal as its own failure (dpdp report 4).
+		task: [
+			t("subagentPreamble", { author: entry.authenticated_author, references }),
+			t("subagentCannotSend"),
+			t("subagentDraftCall", {
+				to: JSON.stringify(entry.reply_authority),
+				sender: JSON.stringify(entry.message.sender),
+				id: JSON.stringify(entry.message.id),
+			}),
+			t("subagentNoRetry"),
+			`[[${token}]]`,
+			"",
+			entry.message.msg,
+		].join("\n"),
+		solutionSpace: t("subagentSolutionSpace"),
+		name,
+	});
+	const details = result.details as unknown as { progress?: Array<{ id?: string; index?: number }>; results?: Array<{ id?: string; index?: number }> } | undefined;
+	const child = [...(details?.progress ?? []), ...(details?.results ?? [])].find(item => typeof item.id === "string" && item.id.length > 0)?.id;
+	if (child === undefined) throw new OnlyneError("unavailable", t("noChildIdentity"));
+	const parentId = AgentRegistry.global().get(child)?.parentId;
+	await deps.contexts.bind(record.alias, { agent_id: child, ...(parentId === undefined ? {} : { parent_id: parentId }) });
+	// The token is already in the child's prompt, so it can only be registered once the child's
+	// identity is known; until then there is no provider boundary to observe it at.
+	// It is registered as the token the prompt carries: a fresh one would never appear in any
+	// provider payload, and the delivery could never be confirmed.
+	registerPending(entry, child, "fragment", token);
+	return child;
+}
+async function findContextBySource(contexts: ContextRegistry, entry: Entry): Promise<ContextRecord | undefined> {
+	const records = await contexts.list();
+	return records.find(record =>
+		record.source?.sender === entry.message.sender && record.source?.id === entry.message.id
+		&& record.thread_ref?.owner === entry.thread_ref.owner && record.thread_ref?.id === entry.thread_ref.id);
+}
+function taskTool(ctx: ExtensionContext) {
+	return AgentRegistry.global().get(ctx.agent.id)?.session?.getToolByName("task");
+}
+interface MessagePayload {
+	customType: string;
+	content: string;
+	display: true;
+	attribution: "agent";
+	details: OnlyneMessageDetails;
+}
+function payload(entry: Entry, customType: string, token: string): MessagePayload {
+	return { customType, content: `${renderEntry(entry, customType)}\n\n[[${token}]]`, display: true, attribution: "agent" as const,
+		details: {
+			thread_ref: entry.thread_ref, seq: entry.seq,
+			message_ref: { sender: entry.message.sender, id: entry.message.id },
+			// This card exists because the entry reached this node's inbox; whether the model has
+			// consumed it is read from history, never assumed here.
+			delivery: "received", consumption: "pending",
+			mail: {
+				from: entry.authenticated_author, at: entry.at, subject: entry.message.delivery_kind, body: entry.message.msg,
+				...(entry.message.meta?.relation === undefined ? {} : { relation: entry.message.meta.relation }),
+				...(entry.message.meta?.in_reply_to === undefined ? {} : { in_reply_to: entry.message.meta.in_reply_to }),
+			},
+		} };
+}
+export function registerMessageRenderers(pi: ExtensionAPI): void {
+	for (const type of [INBOUND, ROUTING, SUPPLEMENT]) pi.registerMessageRenderer(type, renderMailMessage);
+}
+function renderEntry(entry: Entry, customType: string): string {
+	const label = customType === SUPPLEMENT ? t("labelSupplement") : t("labelInbound");
+	const relation = entry.message.meta?.relation === undefined ? "" : ` · ${entry.message.meta.relation}`;
+	return `${entry.thread_ref.id}/${entry.seq} · ${label} · ${entry.authenticated_author}${relation}\n${entry.message.msg.split(/\r?\n/).map(line => `  > ${line}`).join("\n")}`;
+}

package/src/node.ts

@@ -0,0 +1,139 @@
+import { networkInterfaces } from "node:os";
+import { FetchTransport, OnlyneError, OnlyneNode, trustPhase, type Action, type AdmissionContext, type Auth, type Json, type KeyHook, type KeyMaterial, type MaintenanceClock, type MsgInput, type Runtime, type SigningTransportOptions, type Storage, type Target } from "@onlyne/lib";
+import { loadOrCreateKey, writeKeyMaterial } from "@onlyne/node-host/keys";
+import { hostText as t } from "./host-text.ts";
+import { canAnswer, type ContextRegistry } from "./store.ts";
+import type { OnlyneConfig } from "./types.ts";
+
+export interface NodeDeps {
+	config: OnlyneConfig;
+	endpoint: string;
+	instanceId: string;
+	storage: Storage;
+	contexts: ContextRegistry;
+	decide(input: MsgInput): Promise<Action>;
+	runtime: Runtime;
+	/** The timer primitives of the library's own maintenance loop (RFC 0017 §6). */
+	clock: MaintenanceClock;
+	/** The directory the host resolved for this node's identity key; absent keeps the loopback development binding. */
+	keyDir?: string;
+	keys?: KeyHook;
+}
+
+export function advertisedHost(bind: string): string {
+	if (bind !== "0.0.0.0" && bind !== "::") return bind;
+	for (const addresses of Object.values(networkInterfaces())) {
+		for (const address of addresses ?? []) {
+			if (!address.internal && address.family === "IPv4") return address.address;
+		}
+	}
+	throw new OnlyneError("unavailable", t("addressUnavailable"));
+}
+
+export function createOnlyneNode(deps: NodeDeps): OnlyneNode {
+	const { config } = deps;
+	if (config.node.key_ref && deps.keys === undefined) throw new OnlyneError("unsupported_delivery", t("keyProvider"));
+	// Without a key directory the node keeps the loopback development binding (RFC 0001 §1).
+	if (deps.keys === undefined && deps.keyDir === undefined && !["127.0.0.1", "::1", "localhost"].includes(config.server.bind)) {
+		throw new OnlyneError("unsupported_delivery", t("loopbackBind"));
+	}
+	let node: OnlyneNode;
+	const authenticate = async (request: Request): Promise<Auth | null> => {
+		const actor = request.headers.get("Onlyne-Actor");
+		if (!actor || !/^[A-Za-z][A-Za-z0-9+.-]*:[^\s]+$/.test(actor)) return null;
+		if (actor === config.node.id) throw new OnlyneError("forbidden", t("managementIdentity"));
+		return { actor };
+	};
+	const resolve = async (id: string): Promise<Target> => {
+		let target: Target;
+		if (id === config.node.id) {
+			target = { node_id: id, base_url: deps.endpoint };
+		} else {
+			try {
+				target = await node.discovery.resolve(id);
+			} catch (error) {
+				const trustEntry = await node.trust.entry(id).catch(() => undefined);
+				if (trustEntry?.base_url) {
+					target = { node_id: id, base_url: trustEntry.base_url };
+				} else {
+					throw error;
+				}
+			}
+		}
+		return { ...target, headers: { "Onlyne-Actor": config.node.id } };
+	};
+	/**
+	 * Admission reads the trust projection, never the discovery catalog (design §1.1): a discovered
+	 * peer is a clue (RFC 0017 §4), and `discovery.known` is process-local, so a restart would refuse
+	 * a peer whose exchange already completed.
+	 */
+	const admitted = async (id: string, context: AdmissionContext): Promise<boolean> => {
+		if (id === config.node.id) return true;
+		return await context.trust(id) === "exchanged";
+	};
+	const keyDir = deps.keyDir;
+	const keys: KeyHook | undefined = deps.keys ?? (keyDir === undefined ? undefined : Object.assign(
+		() => loadOrCreateKey(keyDir, config.node.id),
+		{ replace: (material: KeyMaterial) => writeKeyMaterial(keyDir, material, { replace: true }) },
+	));
+	// The library's own signing transport, built here for one reason: a missing trust row has to
+	// end at this host's menu. Signing still happens only for a keyed node, and the trust reads
+	// resolve lazily because the service exists only once the node is built.
+	const signing: SigningTransportOptions | undefined = keys === undefined ? undefined : {
+		trust: {
+			entry: id => node.trust.entry(id),
+			signRequest: (request, target, raw) => node.trust.signRequest(request, target, raw),
+			verifyResponse: (target, request, response, body) => node.trust.verifyResponse(target, request, response, body),
+		},
+		guidance: details => ({
+			entry: details.required_action === "confirm_exchange"
+				? ["/onlyne", t("guideContacts"), t("guidePending"), t("guideAccept")]
+				: ["/onlyne", t("guideDiscover"), t("guideRequestExchange")],
+		}),
+	};
+	node = new OnlyneNode({
+		node_id: config.node.id, base_url: deps.endpoint, instance_id: deps.instanceId,
+		now: () => Date.now(), id: () => crypto.randomUUID(),
+		authentication: keys === undefined ? ["none"] : ["signature"], plugins: {
+			storage: deps.storage, authenticate, resolve, decide: deps.decide, runtime: deps.runtime, maintenanceClock: deps.clock,
+			...(keys === undefined ? {} : { keys }),
+			...(signing === undefined ? {} : { transport: new FetchTransport(resolve, fetch, signing) }),
+			...(config.trust === undefined ? {} : { trust_seeds: config.trust }),
+			domainCandidates: id => node.discovery.candidates(id),
+			// The keyless development binding checks no identity (RFC 0001 §1): every declared
+			// actor may open a thread. A keyed node admits only peers whose exchange completed.
+			mayAdmit: async (actor, _thread, context) => keys === undefined || await admitted(actor, context),
+			inboundThread: async (actor, context) => keys === undefined || await admitted(actor, context),
+			// A context that cannot answer is not a continuation target: publishing one lets a
+			// sender aim a message at a session that can never reply (caerulea report 4, problem 7).
+			executionContexts: async () => (await deps.contexts.list()).filter(canAnswer)
+				.map(record => ({ alias: record.alias, summary: record.summary, state: record.state })) as Json,
+			mention: async alias => {
+				const name = alias.replace(/^@/, "");
+				if (name === "self" || name === config.node.id) return config.node.id;
+				const matches = (await node.discovery.listRecords()).filter(record => record.node_id === name || record.node_id.split(":").at(-1) === name);
+				const ids = [...new Set(matches.map(record => record.node_id))];
+				if (ids.length !== 1) throw new OnlyneError(ids.length ? "ambiguous_target" : "not_found", t("mentionNotFound", { name }));
+				return ids[0]!;
+			},
+			directory: async () => ({ node: config.node.id, region: config.region, endpoint: deps.endpoint, peers: await node.discovery.listRecords(), contexts: await deps.contexts.list() }) as unknown as Json,
+			// The same rows onlyne://neighbors renders: every observed node with its trust state.
+			neighbors: async () => {
+				const records = await node.discovery.listRecords();
+				const trust = new Map((await node.trust.list(node.auth)).map(entry => [entry.node_id, entry]));
+				return records.map(record => {
+					const entry = trust.get(record.node_id);
+					return {
+						node_id: record.node_id, base_url: record.base_url,
+						...(record.membership?.domain_id === undefined ? {} : { region: record.membership.domain_id }),
+						...(record.last_seen === undefined ? {} : { last_seen: record.last_seen }),
+						verified: record.verified_at !== undefined && Date.parse(record.expires_at) > Date.now(),
+						phase: entry === undefined ? "no_exchange" : trustPhase(entry),
+						fingerprint: entry?.fingerprint ?? null,
+					};
+				});
+			},
+		},
+	});
+	return node;
+}

package/src/resources.ts

@@ -0,0 +1,36 @@
+import { OnlyneError, trustPhase, type OnlyneNode, type ResourceReadQuery } from "@onlyne/lib";
+import { hostText as t } from "./host-text.ts";
+
+export async function resourceOwners(node: OnlyneNode): Promise<string[]> {
+	const trusted = await node.trust.list(node.auth);
+	return [node.auth.actor, ...trusted.filter(entry => trustPhase(entry) === "exchanged").map(entry => entry.node_id)];
+}
+
+export async function resourceQuery(node: OnlyneNode, meta: Record<string, unknown>): Promise<ResourceReadQuery> {
+	const op = meta.op ?? "list";
+	const cursor = typeof meta.cursor === "string" ? meta.cursor : undefined;
+	const size = meta.page_size;
+	if (size !== undefined && (typeof size !== "number" || !Number.isInteger(size) || size < 1 || size > 100)) {
+		throw new OnlyneError("invalid_request", t("resourcePageSize"));
+	}
+	const page = { ...(cursor === undefined ? {} : { cursor }), ...(size === undefined ? {} : { page_size: size as number }) };
+	if (op === "list") {
+		if (meta.owner !== undefined && (typeof meta.owner !== "string" || meta.owner.length === 0)) throw new OnlyneError("invalid_request", t("resourceOwner"));
+		const owners = typeof meta.owner === "string" ? [meta.owner] : await resourceOwners(node);
+		return { op, owners, ...page };
+	}
+	const ref = meta.resource as { owner?: unknown; id?: unknown } | null | undefined;
+	if (ref === null || typeof ref !== "object" || typeof ref.owner !== "string" || ref.owner.length === 0 || typeof ref.id !== "string" || ref.id.length === 0) {
+		throw new OnlyneError("invalid_request", t("resourceRef"));
+	}
+	const resource = { owner: ref.owner, id: ref.id };
+	if (op === "describe") return { op, resource };
+	if (op === "log") {
+		if (meta.since !== undefined && (typeof meta.since !== "string" || !/^(0|[1-9][0-9]*)$/.test(meta.since))) throw new OnlyneError("invalid_request", t("resourceSince"));
+		return { op, resource, ...page, ...(meta.since === undefined ? {} : { since: meta.since as string }) };
+	}
+	if (op === "operations") return { op, resource, ...page };
+	if (op === "event" && typeof meta.event_id === "string" && meta.event_id.length > 0) return { op, resource, event_id: meta.event_id };
+	if (op === "status" && typeof meta.operation_id === "string" && meta.operation_id.length > 0) return { op, resource, operation_id: meta.operation_id };
+	throw new OnlyneError("invalid_request", t("resourceOp"));
+}