omp-onlyne 0.0.0-stage → 0.1.0

package/src/drafts.ts

@@ -0,0 +1,57 @@
+import { OnlyneError, type Json, type MessageRef, type MsgInput, type PreparedSend } from "@onlyne/lib";
+import type { ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { runDecision } from "./decider.ts";
+import type { PluginRuntime } from "./runtime.ts";
+import { bridgeText as t } from "./bridge-text.ts";
+
+interface Draft {
+	id: string;
+	created_by: string;
+	created_at: string;
+	prepared: PreparedSend;
+}
+
+export async function createDraft(runtime: PluginRuntime, ctx: ExtensionContext, input: MsgInput, signal?: AbortSignal): Promise<unknown> {
+	const meta = { ...input.meta };
+	delete meta.op;
+	if (meta.relation !== "reply" && meta.relation !== "followup") throw new OnlyneError("invalid_request", t("draftNeedsRelation"));
+	const original = await resolveSource(runtime, meta.in_reply_to);
+	if (ctx.agent.kind === "sub") {
+		const authorized = (await runtime.contexts.list()).some(record => record.agent_id === ctx.agent.id
+			&& record.source?.sender === original.sender && record.source.id === original.id);
+		if (!authorized) throw new OnlyneError("forbidden", t("draftChildScope"));
+	}
+	meta.in_reply_to = { sender: original.sender, id: original.id };
+	const normalized = { ...input, meta };
+	const prepared = await runDecision({ ctx, input: normalized, signal, readOnly: false }, () => runtime.node.client.prepare(normalized));
+	const draft: Draft = { id: crypto.randomUUID(), created_by: ctx.agent.id, created_at: new Date().toISOString(), prepared };
+	await runtime.storage.transaction(tx => tx.put(`draft/${draft.id}`, draft));
+	return { draft_id: draft.id, to: prepared.to, relation: prepared.message.meta?.relation,
+		in_reply_to: original, body: prepared.message.msg, state: "draft", send: { meta: { draft_id: draft.id } } };
+}
+
+export async function sendDraft(runtime: PluginRuntime, ctx: ExtensionContext, id: string, signal?: AbortSignal): Promise<unknown> {
+	if (ctx.agent.kind === "sub") throw new OnlyneError("forbidden", t("draftChildCannotSend"));
+	const draft = await runtime.storage.transaction(tx => tx.get<Draft>(`draft/${id}`));
+	if (draft === undefined) throw new OnlyneError("not_found", t("draftNotFound", { id }));
+	const { to, message, plan } = draft.prepared;
+	return runtime.node.client.send(to, message, plan, { context: ctx.agent.id, signal });
+}
+
+async function resolveSource(runtime: PluginRuntime, value: Json | undefined): Promise<MessageRef> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new OnlyneError("invalid_request", t("draftNeedsReference"));
+	if (typeof value.sender === "string" && typeof value.id === "string") return { sender: value.sender, id: value.id };
+	if (typeof value.thread === "string" && (typeof value.seq === "string" || typeof value.seq === "number")) {
+		const slash = value.thread.lastIndexOf("/");
+		const thread = slash < 0 ? { owner: runtime.config.node.id, id: value.thread }
+			: { owner: value.thread.slice(0, slash), id: value.thread.slice(slash + 1) };
+		let cursor: string | undefined;
+		do {
+			const result = await runtime.node.messages.list(runtime.node.auth, thread, { attention: "thread", page_size: 100, cursor });
+			const found = result.items.find(row => row.seq === String(value.seq));
+			if (found !== undefined) return { sender: found.message.sender, id: found.message.id };
+			cursor = result.next_cursor ?? undefined;
+		} while (cursor !== undefined);
+	}
+	throw new OnlyneError("not_found", t("draftSourceUnavailable"));
+}

package/src/host-text.ts

@@ -0,0 +1,86 @@
+import { createTranslator } from "@onlyne/node-host/i18n";
+const en = {
+  regionEmpty: "region must not be empty.",
+  nodeIdEmpty: "node.id must not be empty.",
+  addressEmpty: "A node address must not be empty.",
+  addressUrl: "A node address must be an absolute URL, got {value}.",
+  addressScheme: "A node address must use http or https, got {value}.",
+  addressShape: "A node address is an origin (http://host:7801) or a service URL (http://host:7801{service}), got {value}.",
+  configMissing: "No Onlyne configuration at {path}. Run /onlyne init to create it.",
+  configParse: "{path}: {error}",
+  languageInvalid: "language must be en or zh-CN.",
+  keyScopeInvalid: "node.key_scope must be project, global or none, got {value}.",
+  publicUrlEmpty: "server.public_url must not be empty.",
+  bindEmpty: "server.bind must not be empty.",
+  bindShape: "server.bind must be a hostname or IP address, got {value}.",
+  pageSizeRange: "threads.page_size must be an integer from 1 to 100, got {value}.",
+  retiredEndpoint: "node.endpoint is not supported; the endpoint comes from server.bind and the assigned port.",
+  retiredPort: "server.port is not supported; the operating system assigns the listening port.",
+  retiredPeers: "peers is not supported; peers are discovered over the network and kept in the project SQLite.",
+  retiredOmp: "omp is not supported; delivery and spawning are decided by the OMP judge.",
+  retiredAttention: "threads.default_attention is not supported; reads default to the attention list.",
+  tableExpected: "{path}: {key} must be a table.",
+  stringExpected: "{field} must be a string.",
+  integerExpected: "{field} must be an integer.",
+  stringArrayExpected: "{field} must be an array of non-empty strings.",
+  trustArray: "{path}: trust must be an array of tables.",
+  trustEntry: "{path}: a trust entry needs node_id and a 16-character fingerprint.",
+  addressUnavailable: "No concrete network address is available for this bind host.",
+  keyProvider: "External credential references need a host key provider.",
+  loopbackBind: "The unauthenticated development binding requires a loopback bind host. Create a node key to serve a remote address.",
+  managementIdentity: "HTTP callers cannot claim this node's management identity.",
+  mentionNotFound: "No unique discovered node is named {name}.",
+  guideContacts: "Contacts",
+  guidePending: "Pending",
+  guideAccept: "Accept",
+  guideDiscover: "Discover",
+  guideRequestExchange: "Request key exchange",
+  resourcePageSize: "page_size must be from 1 to 100.",
+  resourceOwner: "Resource owner must be a non-empty node id.",
+  resourceRef: "Resource reads need meta.resource {owner,id}.",
+  resourceSince: "since must be a decimal event id.",
+  resourceOp: "Resource reads use list, describe, log, event with event_id, operations, or status with operation_id.",
+};
+const zh: Record<keyof typeof en, string> = {
+  regionEmpty: "region 不能为空。",
+  nodeIdEmpty: "node.id 不能为空。",
+  addressEmpty: "节点地址不能为空。",
+  addressUrl: "节点地址必须是绝对 URL，收到的是 {value}。",
+  addressScheme: "节点地址必须使用 http 或 https，收到的是 {value}。",
+  addressShape: "节点地址应写成源站（http://host:7801）或服务 URL（http://host:7801{service}），收到的是 {value}。",
+  configMissing: "在 {path} 没有 Onlyne 配置。运行 /onlyne init 创建。",
+  configParse: "{path}: {error}",
+  languageInvalid: "language 必须是 en 或 zh-CN。",
+  keyScopeInvalid: "node.key_scope 必须是 project、global 或 none，收到的是 {value}。",
+  publicUrlEmpty: "server.public_url 不能为空。",
+  bindEmpty: "server.bind 不能为空。",
+  bindShape: "server.bind 必须是主机名或 IP 地址，收到的是 {value}。",
+  pageSizeRange: "threads.page_size 必须是 1 到 100 之间的整数，收到的是 {value}。",
+  retiredEndpoint: "不支持 node.endpoint；端点由 server.bind 和系统分配的端口决定。",
+  retiredPort: "不支持 server.port；监听端口由操作系统分配。",
+  retiredPeers: "不支持 peers；对端通过网络发现，并保存在项目 SQLite 中。",
+  retiredOmp: "不支持 omp；投送与派生由 OMP judge 决定。",
+  retiredAttention: "不支持 threads.default_attention；读取默认使用关注列表。",
+  tableExpected: "{path}: {key} 必须是表。",
+  stringExpected: "{field} 必须是字符串。",
+  integerExpected: "{field} 必须是整数。",
+  stringArrayExpected: "{field} 必须是非空字符串数组。",
+  trustArray: "{path}: trust 必须是表数组。",
+  trustEntry: "{path}: 每条 trust 记录需要 node_id 和 16 个字符的指纹。",
+  addressUnavailable: "这个绑定主机没有可用的具体网络地址。",
+  keyProvider: "外部凭据引用需要主机密钥提供者。",
+  loopbackBind: "未认证的开发绑定需要回环绑定主机。要对外提供服务，请创建节点密钥。",
+  managementIdentity: "HTTP 调用方不能冒用本节点的管理身份。",
+  mentionNotFound: "没有唯一发现到的节点名为 {name}。",
+  guideContacts: "联系人",
+  guidePending: "待确认",
+  guideAccept: "同意",
+  guideDiscover: "发现",
+  guideRequestExchange: "请求交换密钥",
+  resourcePageSize: "page_size 必须是 1 到 100。",
+  resourceOwner: "资源 owner 必须是非空节点 id。",
+  resourceRef: "读取资源需要 meta.resource {owner,id}。",
+  resourceSince: "since 必须是十进制事件 id。",
+  resourceOp: "读取资源可用 list、describe、log、带 event_id 的 event、operations，或带 operation_id 的 status。",
+};
+export const hostText = createTranslator({ en, "zh-CN": zh });

package/src/messages.ts

@@ -0,0 +1,327 @@
+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 { 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;
+}
+/**
+ * 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;
+}
+const inboundAttempts = new Map<string, InboundAttempt>();
+
+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 {
+	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) {
+				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"));
+			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 };
+			}
+			// 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) {
+				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 === "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" },
+				);
+			} else {
+				deps.pi.sendMessage(payload(entry, INBOUND, token), { deliverAs: "nextTurn" });
+			}
+			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));
+			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"]): string {
+	const token = `onlyne-${crypto.randomUUID()}`;
+	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.
+	registerPending(entry, child, "fragment");
+	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,127 @@
+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> => {
+		const target = id === config.node.id
+			? { node_id: id, base_url: deps.endpoint }
+			: await node.discovery.resolve(id);
+		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"));
+}