omp-onlyne 0.0.0-stage → 0.1.0

package/src/tool-text.ts

@@ -0,0 +1,133 @@
+import { createTranslator } from "@onlyne/node-host/i18n";
+
+const en = {
+	label: "Onlyne Message",
+	"param.delivery_kind": "The delivery intent in natural language",
+	"param.msg": "The message body or the local query",
+	"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.
+
+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.
+
+A reply arrives by itself. The plugin injects it as an onlyne.inbound message and starts a turn; you do not need to check. Do not poll after a send: no inbox scans, thread reads, evidence queries, log greps or SQLite lookups. Read state only when the user asks about history, or when a specific fact is missing from the result in hand.
+
+State reads: read the root \`onlyne://\` for the views this node publishes — neighbors, threads, conversations, inbox, contexts, outbound — instead of guessing a route. A conversation is one exchange with both directions: \`onlyne://conversations\` lists them with the latest message and time, \`onlyne://conversations/<sender>/<id>\` shows every message in it, and one message is at \`onlyne://messages/<sender>/<id>\`. Raw thread entries stay at \`onlyne://threads/<thread-id>/messages/<seq>\`.
+
+Resource reads belong to the main OMP session; a subagent session is refused and reads its own message slice instead. meta.scope "resources" selects the resource channel and meta.op names the query:
+
+- Inventory: { delivery_kind: "list the resources", msg: "which resources does this node serve", meta: { scope: "resources", op: "list" } }. Without meta.owner the read covers the local node and every owner whose key exchange completed, and each owner answers with its own page or its own error, so one unreachable owner does not hide the others. meta.owner narrows the read to one owner: meta { scope: "resources", op: "list", owner: "<node>" }.
+- One resource: meta { scope: "resources", op: "describe", resource: { owner: "<node>", id: "<resource>" } }.
+- Event log: the same resource with op "log", meta.since as a decimal event id to resume after the last event you read, and meta.page_size (1 to 100) with meta.cursor for the page.
+- One event: the same resource with op "event" and meta.event_id.
+- Operation history: the same resource with op "operations", paged with meta.page_size and meta.cursor.
+- One operation: the same resource with op "status" and meta.operation_id.
+
+The same reads are internal paths: \`onlyne://resources\` lists every owner, \`onlyne://resources/<owner>\` one owner, \`onlyne://resources/<owner>/<id>\` one resource, \`onlyne://resources/<owner>/<id>/log\` the event log with \`onlyne://resources/<owner>/<id>/log/<event-id>\` for one event, \`onlyne://resources/<owner>/<id>/operations\` the operation history with \`onlyne://resources/<owner>/<id>/operations/<operation-id>\` for one operation. Page them with ?page_size= and ?cursor=, and resume a log with ?since=.
+
+A delivery is stored in the thread it names, and the thread's owner stores it: the initiator owns the thread for the whole conversation, so a member writes into it and the owner admits. A reply names no thread; it lands in the thread that holds the original message. The receipt reports the landing as thread <id> seq <n> and names the message it answers as in_reply_to.
+
+meta.to takes one node or a list of nodes. A list is delivered one target at a time and returns one result per target, so a failure on one target does not hide the others; report each result separately.
+
+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" } }
+- 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.`,
+	"summary.no_result": "Onlyne returned no structured result.",
+	"summary.where": " to {owner}",
+	"summary.thread_ref": " (thread {thread} 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.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.",
+	"summary.plain": "Onlyne answered; the structured result follows.",
+	"failure.invalid_args": "Invalid msg arguments: {message}",
+	"failure.not_configured": "Onlyne is not configured for this project. Create .onlyne/config.toml or run /onlyne init.",
+	"failure.no_target": "meta.to names no target. Name one peer, or send one call per peer.",
+	"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}",
+} as const;
+
+const zh: Record<keyof typeof en, string> = {
+	label: "Onlyne 消息",
+	"param.delivery_kind": "用自然语言描述的投递意图",
+	"param.msg": "消息正文，或本地查询",
+	"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。
+
+发送是一次调用。结果就是投递事实：admission "accepted" 表示接收方已经记录这条消息；wait "timed_out" 只表示等待期内没有回信，消息本身已经投递；reply_body "withheld" 表示这个上下文已经展示过那段正文。报告结果，到此为止。
+
+回信会自己到达。插件把它作为 onlyne.inbound 消息注入并开启一轮对话；你不需要去查。发送之后不要轮询：不要扫信箱、读 thread、查证据、grep 日志或翻 SQLite。只在用户问起历史、或手上的结果缺某个具体事实时才读状态。
+
+状态读取：读根路径 \`onlyne://\`，看这个节点发布了哪些视图——neighbors、threads、conversations、inbox、contexts、outbound——不要猜路径。一次 conversation 是一段双向往来：\`onlyne://conversations\` 列出它们以及最新一条消息和时间，\`onlyne://conversations/<sender>/<id>\` 展示其中每一条消息，单条消息在 \`onlyne://messages/<sender>/<id>\`。thread 的原始条目留在 \`onlyne://threads/<thread-id>/messages/<seq>\`。
+
+资源读取只属于主 OMP 会话；子代理会话会被拒绝，改为读自己的消息切片。meta.scope 为 "resources" 选中资源通道，meta.op 指明查询：
+
+- 清单：{ delivery_kind: "列出资源", msg: "这个节点提供哪些资源", meta: { scope: "resources", op: "list" } }。不带 meta.owner 时，读取覆盖本节点和所有已完成密钥交换的 owner，每个 owner 各自返回一页或各自返回一条错误，所以一个 owner 连不上不会遮住其他 owner。meta.owner 把读取收窄到一个 owner：meta { scope: "resources", op: "list", owner: "<node>" }。
+- 单个资源：meta { scope: "resources", op: "describe", resource: { owner: "<node>", id: "<resource>" } }。
+- 事件日志：同一个 resource 配 op "log"，meta.since 是十进制事件 id，用来从你上次读到的事件之后继续，meta.page_size（1 到 100）配 meta.cursor 取页。
+- 单个事件：同一个 resource 配 op "event" 和 meta.event_id。
+- 操作历史：同一个 resource 配 op "operations"，用 meta.page_size 和 meta.cursor 分页。
+- 单个操作：同一个 resource 配 op "status" 和 meta.operation_id。
+
+同样的读取也是内部路径：\`onlyne://resources\` 列出所有 owner，\`onlyne://resources/<owner>\` 一个 owner，\`onlyne://resources/<owner>/<id>\` 一个资源，\`onlyne://resources/<owner>/<id>/log\` 是事件日志，单个事件用 \`onlyne://resources/<owner>/<id>/log/<event-id>\`，\`onlyne://resources/<owner>/<id>/operations\` 是操作历史，单个操作用 \`onlyne://resources/<owner>/<id>/operations/<operation-id>\`。用 ?page_size= 和 ?cursor= 分页，用 ?since= 续读日志。
+
+一次投递存进它指名的 thread，并由 thread 的 owner 保存：发起者在整段对话里都是 owner，所以成员往 thread 里写、由 owner 准入。回信不指名 thread；它落进持有原消息的那个 thread。回执以 thread <id> seq <n> 报告落点，并以 in_reply_to 指出它回复的那条消息。
+
+meta.to 接受一个节点或一组节点。一组会逐个目标投递，每个目标各得一条结果，所以某个目标失败不会掩盖其他目标；逐个报告结果。
+
+用例，每个都是完整调用：
+
+- 回复你收到的消息。不要指名 thread；接收方会把回信放到原消息所在的 thread：
+  { delivery_kind: "回答 dpdp 的问题", msg: "可以，第二组没问题。", meta: { in_reply_to: { sender: "urn:onlyne:agent:dpdp", id: "<message id>" }, 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），把结果交回主会话，由主会话发送。`,
+	"summary.no_result": "Onlyne 没有返回结构化结果。",
+	"summary.where": "，投递给 {owner}",
+	"summary.thread_ref": "（thread {thread} 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.not_confirmed": "未确认：{failure}。{next}",
+	"summary.retry": "记录保持打开，运行时自己重试；再发一次会提交第二个意图。",
+	"summary.recover": "记录保持打开，等待恢复；不要再发同一个意图。",
+	"summary.plain": "Onlyne 已应答；结构化结果如下。",
+	"failure.invalid_args": "msg 参数无效：{message}",
+	"failure.not_configured": "这个项目没有配置 Onlyne。创建 .onlyne/config.toml，或运行 /onlyne init。",
+	"failure.no_target": "meta.to 没有指明目标。写一个 peer，或每个 peer 各发一次。",
+	"draft.ready": "草稿 {draft_id} 已就绪；主会话用 meta.draft_id 发出它。",
+	"multi.delivered": "→ {to}: {summary}",
+	"multi.failed": "→ {to}: 未发送 —— {error}",
+};
+
+export const toolText = createTranslator({ en, "zh-CN": zh });

package/src/tool.ts

@@ -0,0 +1,236 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { type ExtensionAPI, type ExtensionContext, type SessionEntry, z } from "@oh-my-pi/pi-coding-agent";
+import type { Json, MsgInput, SendOutcome } from "@onlyne/lib";
+import { runDecision } from "./decider.ts";
+import { createDraft, sendDraft } from "./drafts.ts";
+import { observeToolResult } from "./messages.ts";
+import { getRuntime } from "./runtime.ts";
+import { toolText } from "./tool-text.ts";
+
+/** Custom entry naming a reply an `await` returned, left pending for the host bridge to confirm. */
+export const AWAIT_RESULT = "onlyne.await-result";
+/** The custom entry type naming an await result the model has actually read. */
+export const AWAIT_CONSUMED = "onlyne.await-consumed";
+
+export function registerMsgTool(pi: ExtensionAPI): void {
+	const parameters = z.object({
+		delivery_kind: z.string().min(1).describe(toolText("param.delivery_kind")),
+		msg: z.string().describe(toolText("param.msg")),
+		meta: z.record(z.string(), z.unknown()).optional().describe(toolText("param.meta")),
+	});
+	pi.registerTool({
+		name: "msg",
+		label: toolText("label"),
+		description: toolText("description"),
+		parameters,
+		approval: "read",
+		strict: true,
+		execute: async (
+			toolCallId,
+			raw,
+			signal,
+			_onUpdate,
+			ctx,
+		): Promise<AgentToolResult<{ result: unknown }>> => {
+			const parsed = parameters.safeParse(raw);
+			if (!parsed.success) return failure(toolText("failure.invalid_args", { message: parsed.error.message }));
+			const runtime = getRuntime();
+			if (runtime === undefined) return failure(toolText("failure.not_configured"));
+			const input: MsgInput = {
+				delivery_kind: parsed.data.delivery_kind,
+				msg: parsed.data.msg,
+				...(parsed.data.meta === undefined ? {} : { meta: parsed.data.meta as Record<string, Json> }),
+			};
+			const scope = {
+				ctx,
+				input,
+				...(signal === undefined ? {} : { signal }),
+				...(ctx.agent.kind === "sub" ? { readOnly: true } : {}),
+			};
+			const started = Date.now();
+			try {
+				const op = parsed.data.meta?.op;
+				if (op === "draft") {
+					const result = await createDraft(runtime, ctx, input, signal);
+					pi.logger.info("onlyne.draft.created", { ms: Date.now() - started });
+					// createDraft is typed unknown but always returns the draft record it just stored.
+					const draft = result as { draft_id: string };
+					return { content: [{ type: "text", text: toolText("draft.ready", { draft_id: draft.draft_id }) }], details: { result } };
+				}
+				if (typeof parsed.data.meta?.draft_id === "string") {
+					const result = await sendDraft(runtime, ctx, parsed.data.meta.draft_id, signal);
+					recordAwaitResult(pi, toolCallId, result, ctx);
+					return { content: [{ type: "text", text: `${summary(result)}\n\n${JSON.stringify(visibleResult(result), null, 2)}` }], details: { result: visibleResult(result) } };
+				}
+				const targets = parsed.data.meta?.to;
+				if (Array.isArray(targets)) {
+					if (targets.length === 0) return failure(toolText("failure.no_target"));
+					const rows: Array<{ to: unknown; outcome?: unknown; error?: string }> = [];
+					for (const target of targets) {
+						const one: MsgInput = { ...input, meta: { ...input.meta, to: target as Json } };
+						const oneScope = { ...scope, input: one };
+						try {
+							rows.push({ to: target, outcome: await runDecision(oneScope, () => runtime.node.client.msg(one, {
+								...(signal === undefined ? {} : { signal }), context: ctx.agent.id,
+							})) });
+						} catch (error) {
+							rows.push({ to: target, error: error instanceof Error ? error.message : String(error) });
+						}
+					}
+					const text = rows.map(row => row.error === undefined
+						? toolText("multi.delivered", { to: String(row.to), summary: summary(row.outcome) })
+						: toolText("multi.failed", { to: String(row.to), error: row.error })).join("\n");
+					pi.logger.info("onlyne.msg.multi", { targets: rows.length, failed: rows.filter(row => row.error !== undefined).length });
+					return { content: [{ type: "text", text: `${text}\n\n${JSON.stringify(rows, null, 2)}` }], details: { result: rows } };
+				}
+				const result = await runDecision(scope, () =>
+					runtime.node.client.msg(input, {
+						...(signal === undefined ? {} : { signal }),
+						context: ctx.agent.id,
+					}),
+				);
+				recordAwaitResult(pi, toolCallId, result, ctx);
+				const visible = visibleResult(result);
+				pi.logger.info("onlyne.msg.result", { kind: input.delivery_kind, ms: Date.now() - started, ...outcomeFacts(result) });
+				return {
+					content: [{ type: "text", text: `${summary(result)}\n\n${JSON.stringify(visible, null, 2)}` }],
+					details: { result: visible },
+				};
+			} catch (error) {
+				pi.logger.warn("onlyne.msg.failed", {
+					kind: input.delivery_kind, ms: Date.now() - started,
+					error: error instanceof Error ? error.message : String(error),
+				});
+				return failure(error instanceof Error ? error.message : String(error));
+			}
+		},
+	});
+}
+
+/**
+ * The outcome as one sentence. A structured result invites a key-by-key search —
+ * `wait: timed_out` beside `admission: accepted` reads as a contradiction until the
+ * reader knows the contract — so the delivery fact is stated first and the JSON below
+ * it is for the rare case that needs a machine-readable detail.
+ */
+export function summary(result: unknown): string {
+	if (result === null || typeof result !== "object") return toolText("summary.no_result");
+	const outcome = result as Partial<SendOutcome>;
+	const owner = outcome.receipt?.thread_ref?.owner ?? outcome.reply?.thread_ref.owner;
+	const where = owner === undefined ? "" : toolText("summary.where", { owner });
+	// The answer is part of the delivery fact: a reply the receipt cannot attribute is one the
+	// sender cannot prove landed on the message it meant (cyanea report 2, problem 2).
+	const answers = outcome.receipt?.in_reply_to;
+	const answering = answers === undefined ? "" : toolText("summary.answering", { sender: answers.sender, id: answers.id });
+	const facts = outcome.receipt === undefined
+		? ""
+		: toolText("summary.thread_ref", { thread: outcome.receipt.thread_ref.id, seq: outcome.receipt.seq, answering });
+	// The receipt names a thread the receiver owns, which is not a local object; the outbound
+	// record is. Point the reader at the handle that opens (dpdp report, problem 1).
+	const trail = outcome.receipt === undefined ? "" : toolText("summary.outbound", { id: outcome.receipt.message_ref.id });
+	if (outcome.admission !== undefined) {
+		if (outcome.admission !== "accepted") {
+			const error = outcome.error;
+			const failure = error === undefined ? outcome.admission : `${error.code}: ${error.message}`;
+			// `retryable` belongs to the runtime, not to the caller: the record stays open and the
+			// runtime drives it again, while a second send commits a second intent.
+			const next = error?.retryable === true
+				? toolText("summary.retry")
+				: toolText("summary.recover");
+			return toolText("summary.not_confirmed", { failure, next });
+		}
+		if (outcome.wait === "answered" && outcome.reply !== undefined) {
+			const answer = { author: outcome.reply.authenticated_author, seq: outcome.reply.seq, where, facts, trail };
+			return outcome.reply_body === "withheld"
+				? toolText("summary.delivered_withheld", answer)
+				: toolText("summary.delivered_answered", answer);
+		}
+		if (outcome.wait === "timed_out") {
+			return toolText("summary.delivered_timed_out", { where, facts, trail });
+		}
+		if (outcome.wait === "cancelled") {
+			return toolText("summary.delivered_cancelled", { where, facts, trail });
+		}
+		return toolText("summary.delivered", { where, facts, trail });
+	}
+	return toolText("summary.plain");
+}
+
+/** The facts one `msg` call produced, without the reply body. */
+function outcomeFacts(result: unknown): Record<string, unknown> {
+	if (result === null || typeof result !== "object") return {};
+	const outcome = result as Partial<SendOutcome>;
+	return {
+		...(outcome.admission === undefined ? {} : { admission: outcome.admission }),
+		...(outcome.wait === undefined ? {} : { wait: outcome.wait }),
+		...(outcome.reply_body === undefined ? {} : { withheld: outcome.reply_body === "withheld" }),
+		...(outcome.receipt?.seq === undefined ? {} : { seq: outcome.receipt.seq }),
+		...(outcome.receipt?.in_reply_to === undefined ? {} : { reply_to: `${outcome.receipt.in_reply_to.sender}/${outcome.receipt.in_reply_to.id}` }),
+		...(outcome.reply === undefined ? {} : { entry: `${outcome.reply.thread_ref.owner}/${outcome.reply.thread_ref.id}/${outcome.reply.seq}` }),
+		...(outcome.error === undefined ? {} : { code: outcome.error.code }),
+	};
+}
+
+/**
+ * An `await` that returned a reply is recorded as a pending custom entry. The
+ * host bridge confirms consumption when the model actually reads the result;
+ * submitting the tool result proves nothing (RFC 0008 §5).
+ */
+function recordAwaitResult(pi: ExtensionAPI, toolCallId: string, result: unknown, ctx: ExtensionContext): void {
+	if (result === null || typeof result !== "object") return;
+	if ((result as Partial<SendOutcome>).reply_body === "withheld") return;
+	const reply = (result as Partial<SendOutcome>).reply;
+	if (reply === null || reply === undefined || typeof reply !== "object") return;
+	if (typeof reply.seq !== "string" || typeof reply.thread_ref?.owner !== "string" || typeof reply.thread_ref.id !== "string") return;
+	if (typeof reply.message?.sender !== "string" || typeof reply.message.id !== "string") return;
+	observeToolResult(toolCallId, reply, ctx.agent.id);
+	pi.appendEntry(AWAIT_RESULT, {
+		tool_call_id: toolCallId,
+		context: ctx.agent.id,
+		ref: { sender: reply.message.sender, id: reply.message.id },
+		thread_ref: reply.thread_ref,
+		seq: reply.seq,
+		state: "pending",
+		at: new Date().toISOString(),
+	});
+}
+
+function visibleResult(result: unknown): unknown {
+	if (result === null || typeof result !== "object") return result;
+	const outcome = result as Partial<SendOutcome>;
+	if (outcome.reply_body !== "withheld" || outcome.reply === undefined) return result;
+	const { thread_ref, seq, authenticated_author, reply_authority, at, message } = outcome.reply;
+	return {
+		...outcome,
+		reply: {
+			thread_ref, seq, authenticated_author, reply_authority, at,
+			message: { sender: message.sender, id: message.id },
+		},
+	};
+}
+
+export function pendingAwaitResults(branch: readonly SessionEntry[]): Array<{ toolCallId: string; context: string; entry: NonNullable<SendOutcome["reply"]> }> {
+	const consumed = new Set(branch.flatMap(entry => entry.type === "custom" && entry.customType === AWAIT_CONSUMED
+		&& typeof (entry.data as { tool_call_id?: unknown })?.tool_call_id === "string"
+		? [(entry.data as { tool_call_id: string }).tool_call_id] : []));
+	const results = new Map(branch.flatMap(entry => entry.type === "message" && entry.message.role === "toolResult"
+		? [[entry.message.toolCallId, entry.message] as const] : []));
+	return branch.flatMap(entry => {
+		if (entry.type !== "custom" || entry.customType !== AWAIT_RESULT) return [];
+		const data = entry.data as { tool_call_id?: unknown; context?: unknown; ref?: { sender?: unknown; id?: unknown } } | undefined;
+		if (typeof data?.tool_call_id !== "string" || typeof data.context !== "string" || consumed.has(data.tool_call_id)) return [];
+		const outcome = (results.get(data.tool_call_id)?.details as { result?: Partial<SendOutcome> } | undefined)?.result;
+		const reply = outcome?.reply;
+		if (outcome?.reply_body === "withheld" || typeof reply?.message?.msg !== "string"
+			|| reply.message.sender !== data.ref?.sender || reply.message.id !== data.ref?.id) return [];
+		return [{ toolCallId: data.tool_call_id, context: data.context, entry: reply }];
+	});
+}
+
+function failure(text: string): AgentToolResult<{ result: unknown }> {
+	return {
+		content: [{ type: "text", text }],
+		details: { result: undefined },
+		isError: true,
+	};
+}

package/src/types.ts

@@ -0,0 +1,136 @@
+import type { MessageRef, NodeId, ThreadRef, TrustPhase, TrustSeed } from "@onlyne/lib";
+import type { Locale } from "@onlyne/node-host/i18n";
+
+/**
+ * Project-scoped configuration in `<project>/.onlyne/config.toml`.
+ *
+ * Delivery decisions are made by OMP's `judge` model role, so no model
+ * endpoint or model name belongs here.
+ */
+export interface OnlyneConfig {
+	path: string;
+	language?: Locale;
+	/** Protocol membership, independent from the node identity. */
+	region: string;
+	node: {
+		id: NodeId;
+		key_ref?: string;
+		/** Where the node identity lives: the project's `.onlyne/keys`, the user's key store, or no key at all. */
+		key_scope?: "project" | "global" | "none";
+	};
+	server: {
+		bind: string;
+		/** The externally reachable base URL when a reverse proxy fronts the node. */
+		public_url?: string;
+	};
+	threads: {
+		page_size: number;
+	};
+	/** Bootstrap contact seeds the node reaches at every start. */
+	discovery?: {
+		seeds?: string[];
+	};
+	/** Pinned peer fingerprints; an arriving key that matches is trusted without a prompt. */
+	trust?: TrustSeed[];
+}
+
+/** One execution context the plugin registered for a delivered message. */
+export interface ContextRecord {
+	alias: string;
+	node_id: NodeId;
+	main_agent_id: string;
+	source?: { sender: NodeId; id: string };
+	agent_id?: string;
+	session_file?: string;
+	parent_id?: string;
+	thread_ref?: ThreadRef;
+	summary: string;
+	state: "unbound" | "idle" | "running" | "parked" | "lost";
+	created_at: string;
+	bound_at?: string;
+}
+
+/** One row of the viewer's queue page. */
+export interface QueueItem {
+	id: string;
+	kind: "inbound" | "outbound" | "context" | "decision";
+	label: string;
+	detail: string;
+	at?: string;
+}
+
+/** One message row in the viewer's chat page. */
+export interface ViewerMessage {
+	ref: MessageRef;
+	seq: string;
+	direction: "in" | "out";
+	author: string;
+	at: string;
+	text: string;
+	relation?: string;
+}
+
+/** One thread row in the viewer's chat page. */
+export interface ViewerThread {
+	ref: ThreadRef;
+	alias: string;
+	title: string;
+	state: "open" | "closed";
+	unread: number;
+	last_seq: string;
+	messages: ViewerMessage[];
+}
+
+/** One discovery record row the viewer lists as an automatic-discovery candidate. */
+export interface ViewerDiscovery {
+	node_id: NodeId;
+	instance_id: string;
+	base_url: string;
+	source: string;
+	region?: string;
+	membership_state?: "active" | "left";
+	verified_at?: string;
+	expires_at: string;
+	last_seen: string;
+	error?: string;
+}
+
+/** One reachable peer the viewer lists on its contacts page. */
+export interface ViewerContact {
+	node_id: NodeId;
+	instance_id: string;
+	base_url: string;
+	region?: string;
+	last_seen: string;
+}
+
+/** Read-only snapshot the viewer renders. */
+export interface ViewerSnapshot {
+	region?: string;
+	endpoint?: string;
+	queue: QueueItem[];
+	threads: ViewerThread[];
+	contexts: ContextRecord[];
+	discovery: ViewerDiscovery[];
+	contacts: ViewerContact[];
+	discovery_error?: string;
+	/** Every trust row, projected through `trustPhase`: the only stage this package renders. */
+	trust?: Array<{
+		node_id: NodeId;
+		fingerprint: string;
+		phase: TrustPhase;
+		base_url: string;
+	}>;
+	identity?: { public_key: string; fingerprint: string };
+}
+
+/** The one-line runtime status a status widget renders. */
+export interface OnlyneStatus {
+	region: string;
+	node_id: NodeId;
+	nodes: number;
+	neighbors: number;
+	alerts: number;
+	unread: number;
+	discovery_error?: string;
+}

package/src/ui/bootstrap-text.ts

@@ -0,0 +1,125 @@
+import { createTranslator } from "@onlyne/node-host/i18n";
+
+/**
+ * Text of the first-run form, the status row, the mail card and the relative
+ * time phrases: one UI layer, one catalog. Keys are English source text; the
+ * translator reads the process locale on every call, so nothing here is frozen
+ * at import time.
+ */
+const en = {
+	"bootstrap.title": "Onlyne init",
+	"bootstrap.overlayHead": "Onlyne init",
+	"bootstrap.field.region": "Region",
+	"bootstrap.field.nodeId": "Node id",
+	"bootstrap.field.bind": "Server bind",
+	"bootstrap.field.keyScope": "Node key (project/global/none)",
+	"bootstrap.field.pageSize": "Page size",
+	"bootstrap.field.contact": "Node addresses (optional)",
+	"bootstrap.hint.region": "A short name is stored as urn:onlyne:region:<name>",
+	"bootstrap.hint.nodeId": "A short name is stored as urn:onlyne:agent:<name>",
+	"bootstrap.hint.bind": "127.0.0.1",
+	"bootstrap.hint.keyScope":
+		"project: keys in .onlyne/keys (must be git-ignored); global: keys in ~/.config/onlyne/keys; none: loopback development only",
+	"bootstrap.hint.pageSize": "1..100, default 50",
+	"bootstrap.hint.contact":
+		"Nodes discovery cannot reach are contacted by address; stored as discovery.seeds and contacted on every start. Separate addresses with commas",
+	"bootstrap.empty": "[empty]",
+	"bootstrap.regionMissing": "Region is required; a short name is stored as urn:onlyne:region:<name>",
+	"bootstrap.regionPreview": "Will be stored as {uri}",
+	"bootstrap.regionEmpty": "Region must not be empty.",
+	"bootstrap.keyScopeInvalid": "Node key must be project, global or none.",
+	"bootstrap.seedFailed": "Configuration saved and the node started, but {seed} did not connect: {reason}",
+	"bootstrap.started": "Onlyne initialized: {region}",
+	"bootstrap.startFailed": "Configuration written, start failed: {reason}",
+	"bootstrap.notSaved": "Not saved: {reason}",
+	"bootstrap.save": "Save and start",
+	"bootstrap.saving": "Saving…",
+	"bootstrap.cancel": "Cancel",
+	"bootstrap.keys": "Tab/Shift+Tab newline · Enter next field · Ctrl+Enter save · Esc cancel",
+	"bootstrap.header": "{source}. Saving starts this node and publishes discovery.{existing}",
+	"bootstrap.headerExisting": " A project configuration already exists and saving overwrites it.",
+	"status.nodes": "nodes",
+	"status.neighbors": "neighbors",
+	"status.alert": "alert",
+	"status.unread": "unread",
+	"status.discovery": "discovery",
+	"status.unconfigured": "unconfigured",
+	"status.starting": "starting",
+	"mail.supplement": "supplement",
+	"mail.routing": "forwarded",
+	"mail.letter": "letter",
+	"mail.from": "From",
+	"mail.date": "Date",
+	"mail.thread": "Thread",
+	"mail.relation": "Relation",
+	"mail.inReplyTo": "In-Reply-To",
+	"mail.delivery": "Delivery",
+	"mail.status": "Status",
+	"mail.consumed": " · consumed {state}",
+	"mail.rawRecord": "Raw record",
+	"mail.wholeThread": "Whole thread",
+	"time.justNow": "just now",
+	"time.minutesAgo": "{count} min ago",
+	"time.hoursAgo": "{count} h ago",
+	"time.daysAgo": "{count} d ago",
+} as const;
+
+const zh: Record<keyof typeof en, string> = {
+	"bootstrap.title": "Onlyne init",
+	"bootstrap.overlayHead": "Onlyne init",
+	"bootstrap.field.region": "Region",
+	"bootstrap.field.nodeId": "Node id",
+	"bootstrap.field.bind": "Server bind",
+	"bootstrap.field.keyScope": "Node key (project/global/none)",
+	"bootstrap.field.pageSize": "Page size",
+	"bootstrap.field.contact": "节点地址（可选）",
+	"bootstrap.hint.region": "短名保存为 urn:onlyne:region:<短名>",
+	"bootstrap.hint.nodeId": "短名保存为 urn:onlyne:agent:<短名>",
+	"bootstrap.hint.bind": "127.0.0.1",
+	"bootstrap.hint.keyScope":
+		"project：密钥存 .onlyne/keys（git 内需 ignore）；global：存 ~/.config/onlyne/keys；none：回环开发绑定",
+	"bootstrap.hint.pageSize": "1..100，默认 50",
+	"bootstrap.hint.contact": "自动发现到不了的节点按地址联系；保存为 discovery.seeds，每次启动都会联系。多个地址用逗号分隔",
+	"bootstrap.empty": "[空]",
+	"bootstrap.regionMissing": "Region 必填；短名将保存为 urn:onlyne:region:<短名>",
+	"bootstrap.regionPreview": "将保存为 {uri}",
+	"bootstrap.regionEmpty": "Region 不能为空。",
+	"bootstrap.keyScopeInvalid": "Node key 只能是 project、global 或 none。",
+	"bootstrap.seedFailed": "配置已保存并启动，但 {seed} 没连上：{reason}",
+	"bootstrap.started": "Onlyne 已初始化：{region}",
+	"bootstrap.startFailed": "配置已写入，启动失败：{reason}",
+	"bootstrap.notSaved": "未保存：{reason}",
+	"bootstrap.save": "保存并启动",
+	"bootstrap.saving": "保存中…",
+	"bootstrap.cancel": "取消",
+	"bootstrap.keys": "Tab/Shift+Tab 换行 · Enter 下一项 · Ctrl+Enter 保存 · Esc 取消",
+	"bootstrap.header": "{source}。保存后启动本节点并发布发现。{existing}",
+	"bootstrap.headerExisting": "已存在项目配置，保存将覆盖。",
+	"status.nodes": "节点",
+	"status.neighbors": "邻居",
+	"status.alert": "提醒",
+	"status.unread": "未读",
+	"status.discovery": "发现",
+	"status.unconfigured": "未配置",
+	"status.starting": "启动中",
+	"mail.supplement": "补笺",
+	"mail.routing": "转递",
+	"mail.letter": "来信",
+	"mail.from": "发件人",
+	"mail.date": "日期",
+	"mail.thread": "线程",
+	"mail.relation": "关系",
+	"mail.inReplyTo": "回复",
+	"mail.delivery": "投送",
+	"mail.status": "状态",
+	"mail.consumed": " · 已消费 {state}",
+	"mail.rawRecord": "原始记录",
+	"mail.wholeThread": "整段对话",
+	"time.justNow": "刚刚",
+	"time.minutesAgo": "{count} 分钟前",
+	"time.hoursAgo": "{count} 小时前",
+	"time.daysAgo": "{count} 天前",
+};
+
+export const t = createTranslator({ en, "zh-CN": zh });
+export type UiTextKey = keyof typeof en;