omp-onlyne 0.0.0-stage → 0.2.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/handshake.ts

@@ -0,0 +1,291 @@
+import { OnlyneError, type Json, type KeyExchange, type Message, type NodeId, type Storage, type ThreadRef, type TrustEntry, type TrustPhase } from "@onlyne/lib";
+import { evaluateAcquisition, type AcquireInput, type AcquireVerdict, type AcquisitionPolicy } from "./acquire.ts";
+import { bridgeText as t } from "./bridge-text.ts";
+import { hostText } from "./host-text.ts";
+
+/**
+ * RFC 0018 §3.2: the handshake entries live in one thread this node owns alone, so nothing in
+ * them ever leaves the node, and the business thread tree stays a record of conversations
+ * rather than a log of system events.
+ */
+export const TRUST_THREAD = "trust";
+
+export function trustThread(nodeId: NodeId): ThreadRef {
+	return { owner: nodeId, id: TRUST_THREAD };
+}
+
+export function isTrustThread(nodeId: NodeId, ref: ThreadRef | undefined): boolean {
+	return ref !== undefined && ref.owner === nodeId && ref.id === TRUST_THREAD;
+}
+
+/** RFC 0018 §2.1: where one peer statement's connection arrived from. */
+export interface StatementObservation {
+	/** The address the connection came from; absent when this host could not observe one. */
+	observed?: string;
+	at: string;
+	cause: string;
+}
+
+const OBSERVED = "acquire/observed/";
+const DELIVERED = "acquire/delivered/";
+
+function observedKey(nodeId: NodeId, fingerprint: string): string {
+	return `${OBSERVED}${encodeURIComponent(nodeId)}/${encodeURIComponent(fingerprint)}`;
+}
+
+function deliveredKey(nodeId: NodeId, fingerprint: string, phase: TrustPhase): string {
+	return `${DELIVERED}${encodeURIComponent(nodeId)}/${encodeURIComponent(fingerprint)}/${phase}`;
+}
+
+/**
+ * RFC 0018 §2.1/§3: the two durable records this host keeps about a handshake. The observed
+ * address is written for every statement, before any verdict, so an approval decided later
+ * reads the address that statement itself arrived from and never the address of the call that
+ * asks (§2.1). The delivered records are one per `(node_id, fingerprint, phase)`, so a
+ * replayed event appends no second entry.
+ */
+export class AcquisitionLog {
+	constructor(private readonly storage: Storage) {}
+
+	async observe(nodeId: NodeId, fingerprint: string, observation: StatementObservation): Promise<void> {
+		await this.storage.transaction(tx => tx.put(observedKey(nodeId, fingerprint), observation));
+	}
+
+	/**
+	 * A local transition is still an observed trust event, but it must not replace the address
+	 * of the peer statement. Keep its timestamp and cause beside the original address instead.
+	 */
+	async transition(nodeId: NodeId, fingerprint: string, at: string, cause: string): Promise<void> {
+		await this.storage.transaction(async tx => {
+			const key = observedKey(nodeId, fingerprint);
+			const current = await tx.get<StatementObservation>(key);
+			await tx.put(key, { ...(current?.observed === undefined ? {} : { observed: current.observed }), at, cause });
+		});
+	}
+
+	async observation(nodeId: NodeId, fingerprint: string): Promise<StatementObservation | undefined> {
+		return this.storage.transaction(tx => tx.get<StatementObservation>(observedKey(nodeId, fingerprint)));
+	}
+
+	async delivered(nodeId: NodeId, fingerprint: string, phase: TrustPhase): Promise<boolean> {
+		return (await this.storage.transaction(tx => tx.get(deliveredKey(nodeId, fingerprint, phase)))) !== undefined;
+	}
+
+	async markDelivered(nodeId: NodeId, fingerprint: string, phase: TrustPhase, at: string): Promise<void> {
+		await this.storage.transaction(tx => tx.put(deliveredKey(nodeId, fingerprint, phase), { node_id: nodeId, fingerprint, phase, at }));
+	}
+
+	/**
+	 * RFC 0018 §3: the reports an agent already acted on are settled. A revocation names no
+	 * fingerprint, so it settles every report held for the node; a later statement opens its own.
+	 */
+	async settle(nodeId: NodeId, fingerprint?: string): Promise<void> {
+		const prefix = `${DELIVERED}${encodeURIComponent(nodeId)}/${fingerprint === undefined ? "" : `${encodeURIComponent(fingerprint)}/`}`;
+		await this.storage.transaction(async tx => {
+			for (const row of await tx.scan(prefix)) await tx.delete(row.key);
+		});
+	}
+}
+
+/** The machine facts a handshake entry carries beside its body (RFC 0018 §3). */
+export interface HandshakeFacts {
+	node_id: NodeId;
+	fingerprint: string;
+	phase: TrustPhase;
+	/** Whether this entry owes an agent decision; a status update owes none. */
+	pending: boolean;
+}
+
+/** The facts one handshake entry carries, or undefined for an entry that is not one. */
+export function handshakeFacts(meta: Message["meta"] | undefined): HandshakeFacts | undefined {
+	const value = meta?.data?.trust;
+	if (value === null || value === undefined || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const row = value as Record<string, Json>;
+	const { node_id: node, fingerprint, phase, pending } = row;
+	if (typeof node !== "string" || typeof fingerprint !== "string" || typeof pending !== "boolean") return undefined;
+	if (phase !== "invited" && phase !== "requested" && phase !== "exchanged" && phase !== "revoked") return undefined;
+	return { node_id: node, fingerprint, phase, pending };
+}
+
+export interface HandshakeInput {
+	node_id: NodeId;
+	fingerprint: string;
+	phase: TrustPhase;
+	/** The address the peer wrote into its own statement. */
+	declared: string;
+	/** The address that statement arrived from; absent when this host observed none. */
+	observed?: string;
+	policy: AcquisitionPolicy;
+	/** The judgement made for this event, when one was made. */
+	judgement?: ApprovalJudgement;
+	/** Whether an approval was committed without an agent deciding first. */
+	approved: boolean;
+}
+
+/**
+ * RFC 0018 §3: one handshake entry. The body carries what the judgement read and concluded;
+ * the action identifiers appear only when a decision is actually owed, and a status update
+ * says so instead. `pending` is the same fact for the host's todo hook.
+ */
+export function handshakeEntry(input: HandshakeInput): { msg: string; trust: { [key: string]: Json } } {
+	// RFC 0018 §3: only an invitation this host did not approve itself is work. A pending local
+	// approval waits on the peer, so there is nothing to do and nothing to wake a turn for.
+	const pending = input.phase === "invited" && !input.approved;
+	const lines = [
+		t("trustHeader", { phase: input.phase, node: input.node_id }),
+		t("trustFingerprint", { fingerprint: input.fingerprint }),
+		t("trustDeclared", { declared: input.declared }),
+		t("trustObserved", { observed: input.observed ?? t("trustUnobserved") }),
+		t("trustPolicy", { policy: input.policy.policy }),
+	];
+	if (input.judgement !== undefined) {
+		lines.push(t("trustJudgement", {
+			reason: input.judgement.verdict.reason,
+			conclusion: input.judgement.verdict.allowed ? t("trustAllowed") : t("trustRefused"),
+		}));
+	}
+	if (input.phase === "invited") lines.push(input.approved ? t("trustApproved") : t("trustInvited"));
+	else if (input.phase === "requested") lines.push(t("trustRequested"));
+	else if (input.phase === "exchanged") lines.push(t("trustExchanged"));
+	else lines.push(t("trustRevoked"));
+	if (input.phase === "invited" && !input.approved) {
+		// RFC 0018 §3: under `none` the agent may only look. Offering an action the policy
+		// refuses would ask for a decision that can never be made.
+		lines.push(input.policy.policy === "none"
+			? t("trustPanelOnly")
+			: t("trustAcceptAction", { node: input.node_id, fingerprint: input.fingerprint }));
+	}
+	if (pending) lines.push(t("trustRevokeAction", { node: input.node_id }));
+	return { msg: lines.join("\n"), trust: { node_id: input.node_id, fingerprint: input.fingerprint, phase: input.phase, pending } };
+}
+
+/** RFC 0018 §2: one approval judgement and every input it read. */
+export interface ApprovalJudgement {
+	at: string;
+	node_id: NodeId;
+	/** Absent when no fingerprint has been proved yet: an initiation reads the peer's key after the gate. */
+	fingerprint?: string;
+	policy: AcquisitionPolicy;
+	input: AcquireInput;
+	verdict: AcquireVerdict;
+}
+
+/** The judgement as the audit line records it: the time, the peer, and every input the verdict read. */
+export function judgementFacts(judgement: ApprovalJudgement): Record<string, unknown> {
+	const { input, verdict } = judgement;
+	return {
+		at: judgement.at,
+		node: judgement.node_id,
+		fingerprint: judgement.fingerprint ?? null,
+		policy: judgement.policy.policy,
+		allow: [...judgement.policy.allow],
+		observed: input.observed ?? null,
+		declared: input.declared ?? null,
+		recorded: [...(input.recorded ?? [])],
+		allowed: verdict.allowed,
+		reason: verdict.reason,
+		...(verdict.matched === undefined ? {} : { matched: verdict.matched }),
+	};
+}
+
+/** Everything the judgement reads from the host, and the two calls it may then commit. */
+export interface ApprovalDeps {
+	policy: AcquisitionPolicy;
+	log: AcquisitionLog;
+	/** RFC 0018 §2.1: the address the peer's last statement arrived from, as this host recorded it. */
+	observed(nodeId: NodeId, fingerprint: string): Promise<string | undefined>;
+	/** The address the peer wrote into its own statement, never the address of this call. */
+	declared(nodeId: NodeId): Promise<string | undefined>;
+	/** Every discovery address recorded for this node id; each is an outbound candidate (§2.2). */
+	recorded(nodeId: NodeId): Promise<string[]>;
+	/** The audit line, written whether or not the verdict allows the approval (§4.1). */
+	audit(judgement: ApprovalJudgement): void;
+	accept(nodeId: NodeId, fingerprint: string): Promise<TrustEntry>;
+	revoke(nodeId: NodeId): Promise<void>;
+	now(): string;
+}
+
+export interface ApprovalRequest {
+	node_id: NodeId;
+	/** The fingerprint the peer proved. Omitted by an initiation, whose key read comes after the gate. */
+	fingerprint?: string;
+	/** The statement's own connection address, when the caller is holding it. */
+	observed?: string;
+	/**
+	 * The discovery addresses as they stood when the statement arrived (RFC 0018 §2.2). A record
+	 * this host derives from the statement itself is not part of the judgement.
+	 */
+	recorded?: string[];
+}
+
+/**
+ * RFC 0018 §2: the one judgement, read by both the agent path and the auto-approval path.
+ * `observed` is the address a recorded statement arrived from — the caller's live connection
+ * address only when it is judging the statement it just received — and the declared address
+ * and every recorded address are checked with it (§2.1–2.2).
+ */
+export async function judgeApproval(deps: ApprovalDeps, request: ApprovalRequest): Promise<ApprovalJudgement> {
+	const observed = request.observed
+		?? (request.fingerprint === undefined ? undefined : await deps.observed(request.node_id, request.fingerprint));
+	const declared = await deps.declared(request.node_id);
+	const input: AcquireInput = {
+		...(observed === undefined || observed === "" ? {} : { observed }),
+		...(declared === undefined || declared === "" ? {} : { declared }),
+		recorded: request.recorded ?? await deps.recorded(request.node_id),
+	};
+	const judgement: ApprovalJudgement = {
+		at: deps.now(), node_id: request.node_id, fingerprint: request.fingerprint,
+		policy: deps.policy, input, verdict: await evaluateAcquisition(deps.policy, input),
+	};
+	deps.audit(judgement);
+	return judgement;
+}
+
+/** The refusal an agent-initiated approval gets. A refused approval is not a revocation: the peer's row is left as it is. */
+export function approvalRefused(judgement: ApprovalJudgement): OnlyneError {
+	const { policy, verdict } = judgement;
+	return new OnlyneError("forbidden", hostText("acquireDenied", { policy: policy.policy, reason: verdict.reason }), {
+		policy_denied: verdict.reason,
+		policy: policy.policy,
+		...(judgement.input.observed === undefined ? {} : { observed: judgement.input.observed }),
+		...(judgement.input.declared === undefined ? {} : { declared: judgement.input.declared }),
+	});
+}
+
+/** RFC 0018 §2/§3.1: the agent's `trust_accept`, judged before anything is committed. */
+export async function approvePeer(deps: ApprovalDeps, nodeId: NodeId, fingerprint: string): Promise<TrustEntry> {
+	const judgement = await judgeApproval(deps, { node_id: nodeId, fingerprint });
+	if (!judgement.verdict.allowed) throw approvalRefused(judgement);
+	const entry = await deps.accept(nodeId, fingerprint);
+	await deps.log.settle(nodeId, fingerprint);
+	return entry;
+}
+
+/**
+ * RFC 0018 §2/§3.1: the agent's `trust_begin`. The judgement reads stored facts only and runs
+ * before `exchange`, which is this path's first outbound request — the key read that starts the
+ * exchange — so a refusal sends nothing and leaves the peer's row untouched. On an allow the
+ * library commits the local approval and mails the statement, and the entry it returns carries
+ * the phase that commit produced.
+ */
+export async function beginPeer(
+	deps: ApprovalDeps,
+	exchange: (nodeId: NodeId) => Promise<KeyExchange>,
+	request: ApprovalRequest,
+): Promise<{ session: KeyExchange; entry: TrustEntry }> {
+	const judgement = await judgeApproval(deps, request);
+	if (!judgement.verdict.allowed) throw approvalRefused(judgement);
+	const session = await exchange(request.node_id);
+	const entry = await session.confirm(session.fingerprint);
+	await deps.log.settle(request.node_id, entry.fingerprint);
+	return { session, entry };
+}
+
+/**
+ * RFC 0018 §2: the agent's `trust_revoke`, never judged. The policy decides who may come in;
+ * it has no say over who may be turned away, which is also why this path reads no address.
+ */
+export async function revokePeer(deps: ApprovalDeps, nodeId: NodeId): Promise<void> {
+	await deps.revoke(nodeId);
+	await deps.log.settle(nodeId);
+}

package/src/host-text.ts

@@ -0,0 +1,92 @@
+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 listening port.",
+  portRange: "server.port must be an integer from 0 to 65535, got {value}.",
+  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.",
+  acquirePolicy: "acquisition.policy must be all, segment or none, got {value}.",
+  acquireAllow: "acquisition.allow entries must be network/prefix blocks, got {value}.",
+  acquireDenied: "The acquisition policy {policy} refused this approval: {reason}.",
+  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 和监听端口决定。",
+  portRange: "server.port 必须是 0 到 65535 之间的整数，收到的是 {value}。",
+  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 个字符的指纹。",
+  acquirePolicy: "acquisition.policy 必须是 all、segment 或 none，收到的是 {value}。",
+  acquireAllow: "acquisition.allow 的条目必须是 network/prefix 形式，收到的是 {value}。",
+  acquireDenied: "获取策略 {policy} 拒绝了这次批准：{reason}。",
+  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 });