omp-onlyne 0.0.0-stage → 0.2.0

package/AGENTS.sample.md

@@ -0,0 +1,27 @@
+# Onlyne in this project
+
+A starting point for a project that hosts an Onlyne node. Copy what you need into the project's own `AGENTS.md`; the wording assumes the `omp-onlyne` plugin is loaded.
+
+## Reaching another node
+
+`msg` is the only entry:
+
+    msg({ delivery_kind: "ask reviewer to check the data", msg: "…", meta: { to: "reviewer" } })
+
+`delivery_kind` states the intent in plain language; the judge role turns it into an action. Put the references you already have in `meta` — `to`, `thread`, `in_reply_to {thread,seq}` or `{sender,id}`, `relation`, `message`, `scope`, `seq`.
+
+The tool is the whole surface. Do not look for a CLI, do not read the plugin source to learn the protocol, and do not open the node database to find out how it works.
+
+## Reading a result
+
+The first line of a result is the outcome. `admission: "accepted"` with `guarantee: "durable"` means the receiver recorded the message. `wait: "timed_out"` means no reply arrived within the wait, not that the send failed. Report the outcome and stop.
+
+A reply arrives by itself: the plugin injects it as an `onlyne.inbound` message and starts a turn. Do not poll after a send — no inbox scans, thread reads, evidence queries, log reads or database queries. Read state when the user asks about history, or when a fact the result did not carry is genuinely needed.
+
+## Subagent sessions
+
+A subagent can read its slice but cannot send. Return the reply text and the target so the main session can send it.
+
+## Local files
+
+`.onlyne/config.toml` holds the node id, region and bind address. The `omp.db` beside it is the node's own record, owned by the plugin; treat it as runtime state, not documentation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dbydd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# omp-onlyne
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Onlyne v3 for OMP. One model entry, `msg({ delivery_kind, msg, meta })`, backed by
+thread-aware message admission, reply correlation and OMP's `judge` model role.
+
+The plugin owns the OMP integration: a local Onlyne HTTP node, project-scoped
+configuration, `onlyne://` reads, custom inbound messages and the `msg` tool.
+The protocol library is [`@onlyne/lib`](../lib).
+
+## Configuration
+
+Configuration belongs to the project at `<project>/.onlyne/config.toml`. It is
+not read from user-level plugin settings, so two projects on one machine keep
+separate identities. `/onlyne init` creates it; no file is required before the
+first run.
+
+```toml
+language = "en"
+
+[node]
+region = "urn:onlyne:region:research-chamber"
+id = "urn:onlyne:agent:lazuli"
+key_scope = "project"
+
+[server]
+bind = "127.0.0.1"
+# port is written by the runtime; set it only to pin one by hand.
+
+[threads]
+page_size = 50
+```
+
+`region` is the required protocol membership and `id` is the stable node
+identity. They are independent; moving region does not change existing message
+references. `/onlyne init` suggests region from the current Tern session name
+and leaves the node id empty for the user. A short region is saved as
+`urn:onlyne:region:<encoded name>`.
+
+The first start lets the operating system choose the listening port, and the
+runtime writes that port back as `server.port`; every later start reuses it, so
+the address a peer recorded keeps answering. A port another process already
+holds moves the node to a system-chosen one, which is written back the same way.
+The runtime derives the endpoint and publishes it through discovery. Discovery
+uses a seed address supplied during bootstrap and an HTTP candidate exchange
+stored in `.onlyne/omp.db`. DNS-SD is an optional same-link accelerator: install
+`bonjour-service` to enable it. The configuration does not contain endpoint,
+peers, task-spawn policy or supplement windows.
+
+`node.key_scope` names where the identity key lives. `project` keeps it in
+`<project>/.onlyne/keys`, which a git work tree must ignore; the node refuses to
+create it otherwise and names both escapes. `global` keeps it in
+`~/.config/onlyne/keys`, shared by every project on the machine. `none` runs the
+keyless loopback development binding, which refuses a non-loopback `bind`. A
+configuration without the key keeps reading the global store.
+
+`key_ref` is parsed but not enforced. The current development binding refuses a
+non-empty value and a non-loopback `bind`, because it authenticates with
+`Onlyne-Actor` only. Credential exchange and proof of possession remain a
+separate security proposal; leave both at their defaults for the first E2E.
+
+## Surface
+
+- `msg` — send, reply, read, manage threads and operate resources. The judge
+  role chooses the action and delivery plan; the result reports the plan that
+  ran. A new execution context belongs to the receiver; the sender never mints
+  one.
+- `onlyne://threads`, `onlyne://threads/<alias>`, `onlyne://threads/<alias>/messages/<seq>`,
+  `onlyne://conversations`, `onlyne://conversations/<sender>/<id>`,
+  `onlyne://messages/<sender>/<id>`, `onlyne://contexts`, `onlyne://inbox`,
+  `onlyne://outbound`, `onlyne://neighbors` — read-only views. List views accept
+  `page_size` (or `limit`) and `cursor`; a conversation holds both directions of one
+  exchange.
+- `onlyne://threads` also lists the threads this node was invited into and does not own.
+  Those rows carry the owner, the last sequence the local records know, and the member
+  list when the owner answers; they are read-only, so the composer refuses them and
+  entries are read from the owner.
+- `onlyne://resources` reads the local node and peers whose key exchange is complete.
+  Each owner returns its authorized resources or an explicit failure. Select
+  `onlyne://resources/<encoded-owner>` for one owner's inventory and pagination.
+  A resource lives at `onlyne://resources/<encoded-owner>/<encoded-id>`, with
+  `/log`, `/log/<event-id>`, `/operations`, and `/operations/<operation-id>` reads.
+  Log pages accept an exclusive `since` event id. Resource reads belong to the
+  main OMP session because context records contain no resource grants.
+- Inbound messages arrive as `onlyne.inbound` custom messages. A supplement for
+  an existing context uses `onlyne.supplement` and `sendCustomMessage`.
+- Tern renders these messages as mailing-list letters: an `[onlyne]` subject,
+  sender, date, thread and reply headers, Markdown body, and a link to the
+  original entry. Other terminals show the same fields as text. Consumption
+  markers stay in the model payload and are hidden from the letter.
+- Consumption is confirmed only after the host observes the entry in an actual
+  provider request; submitting a custom message or tool result does not advance
+  the record.
+- `/onlyne` opens a domain rail, thread sidebar, message flow and domain node list.
+  Threads, messages and nodes scroll independently. The inbox opens from the sidebar.
+  Posting names the thread's owner and id; clicking an incoming message selects its
+  message reference for a reply. Reply routing currently follows the original
+  author and can land in another thread. `/onlyne settings` edits the project
+  configuration. `/onlyne init` writes a first config and starts the node; with
+  no config, `/onlyne` and `/onlyne settings` open the same bootstrap.
+
+Subagent sessions may read only the context slice attached to their own agent
+identity and may not send; the main agent owns the node identity and the reply
+path.
+
+The equivalent `msg` query uses `meta: { scope: "resources", op: "list" }`.
+An optional `owner` selects one inventory. The `describe`, `log`, `event`,
+`operations`, and `status` queries name `resource: { owner, id }`.
+`event` requires `event_id`; `status` requires `operation_id`.
+Paged queries accept `page_size` and `cursor`. A resource cursor requires one owner.
+
+## Language
+
+`/onlyne language en` and `/onlyne language zh-CN` save the project language.
+The command changes rendered text, judge prompts, and the registered `msg`
+description in the current session. Configuration forms preserve this setting.
+The optional top-level `language` setting takes precedence over `ONLYNE_LANG`,
+then `LC_ALL` or `LANG`. The default is English. Route names, protocol fields,
+error codes, diagnostic event names, and user messages keep their original values.
+
+`AGENTS.sample.md` is the agent-facing half of that surface. Copy it into the
+host project's `AGENTS.md`: it states that `msg` is the only entry, that a send's
+`admission` is the delivery fact rather than the wait, and that replies arrive as
+inbound messages so a send needs no polling.
+
+Select a domain node to request a key exchange. The viewer reads the
+peer's public key and shows both fingerprints before sending. Confirmation sends
+the signed introduction and records local approval. The peer's sidebar and message
+flow show the pending request. Both nodes become trusted after the peer approves. Committed
+trust changes notify the viewer immediately, including introductions received over
+HTTP, so an open viewer does not wait for maintenance to show a request or approval.
+
+## Run
+
+```sh
+bun install
+bun run --filter omp-onlyne check
+bun run --filter omp-onlyne test
+```
+
+The package is loaded by OMP through its `omp.extensions` field. It requires
+OMP 18.12.6 or newer.

package/index.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { registerContextBinding } from "./src/binding.ts";
+import { ConfigError } from "./src/config.ts";
+import { registerMessageRenderers, registerProviderBoundary } from "./src/messages.ts";
+import { registerTodoRecovery } from "./src/todo.ts";
+import { startRuntime, stopRuntime, type RuntimeHost } from "./src/runtime.ts";
+import { registerMsgTool } from "./src/tool.ts";
+import { registerOnlyneUrls } from "./src/urls.ts";
+import { attachStatus, registerUi } from "./src/ui/index.ts";
+
+/**
+ * OMP extension entry. The factory runs for every session, including subagents;
+ * the network node belongs to the main session only. State recovery and the
+ * listener start on `session_start`, never during factory execution.
+ */
+export default function ompOnlyne(pi: ExtensionAPI, host: RuntimeHost = {}): void {
+	registerOnlyneUrls();
+	registerMessageRenderers(pi);
+	registerProviderBoundary(pi);
+	registerMsgTool(pi);
+	registerContextBinding(pi);
+	registerTodoRecovery(pi);
+	registerUi(pi);
+	let detachStatus: (() => void) | undefined;
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.agent.kind !== "main") return;
+		if (ctx.hasUI) {
+			try {
+				detachStatus?.();
+				detachStatus = attachStatus(ctx);
+			} catch (error) {
+				pi.logger.warn("onlyne status widget could not be attached", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+		try {
+			await startRuntime(pi, ctx, host);
+		} catch (error) {
+			// A project without a saved config is the normal first-run state; /onlyne init creates it.
+			if (error instanceof ConfigError && error.code === "missing") return;
+			pi.logger.warn("onlyne could not start for this project", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (ctx.agent.kind !== "main") return;
+		detachStatus?.();
+		detachStatus = undefined;
+		await stopRuntime();
+	});
+}

package/package.json

@@ -1,6 +1,63 @@
 {
-  "name": "omp-onlyne",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "omp-onlyne",
+	"version": "0.2.0",
+	"description": "Onlyne v3 for OMP: one msg tool, thread-aware attention and SystemOne delivery decisions",
+	"type": "module",
+	"main": "./index.ts",
+	"types": "./index.ts",
+	"license": "MIT",
+	"homepage": "https://github.com/dbydd/onlyne#readme",
+	"bugs": "https://github.com/dbydd/onlyne/issues",
+	"keywords": ["onlyne", "omp", "agent", "messaging", "tools"],
+	"publishConfig": { "access": "public" },
+	"engines": { "bun": ">=1.4.3" },
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dbydd/onlyne.git",
+		"directory": "packages/omp-onlyne"
+	},
+	"files": [
+		"index.ts",
+		"src",
+		"AGENTS.sample.md",
+		"README.md",
+		"LICENSE"
+	],
+	"omp": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"exports": {
+		".": "./index.ts",
+		"./runtime": "./src/runtime.ts",
+		"./config": "./src/config.ts",
+		"./types": "./src/types.ts"
+	},
+	"scripts": {
+		"check": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@onlyne/lib": "^3.1.0",
+		"@onlyne/node-host": "^3.1.0"
+	},
+	"peerDependencies": {
+		"@oh-my-pi/pi-agent-core": "*",
+		"@oh-my-pi/pi-coding-agent": "*",
+		"@oh-my-pi/pi-tui": "*",
+		"omp-todo-more": ">=0.1.4"
+	},
+	"peerDependenciesMeta": {
+		"omp-todo-more": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@oh-my-pi/pi-agent-core": "18.12.6",
+		"@oh-my-pi/pi-coding-agent": "18.12.6",
+		"@oh-my-pi/pi-tui": "18.12.6",
+		"@types/bun": "latest",
+		"typescript": "latest"
+	}
+}

package/src/acquire.ts

@@ -0,0 +1,182 @@
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+
+/** RFC 0018 §2: how far a peer may be acquired without a human confirming first. */
+export type AcquirePolicy = "all" | "segment" | "none";
+
+/** RFC 0018 §5: host-side acquisition settings. The library never reads them. */
+export interface AcquisitionPolicy {
+	policy: AcquirePolicy;
+	/** CIDR blocks and host names; only read when `policy` is `segment`. */
+	allow: string[];
+}
+
+/**
+ * The default delegation: loopback only. Discovery excludes loopback by default, so the two
+ * defaults together mean a remote peer is neither discovered nor approved (RFC 0018 §5.1).
+ */
+export const DEFAULT_ACQUISITION: AcquisitionPolicy = {
+	policy: "segment",
+	allow: ["127.0.0.0/8", "::1/128"],
+};
+
+/** Turns a host name into the addresses it names; an empty list means it names none. */
+export type Resolver = (host: string) => Promise<string[]>;
+
+const dnsResolver: Resolver = async host => (await lookup(host, { all: true })).map(row => row.address);
+
+/** The configured policy, or the documented default when the config carries none. */
+export function acquisitionOf(config: { acquisition?: AcquisitionPolicy }): AcquisitionPolicy {
+	return config.acquisition ?? DEFAULT_ACQUISITION;
+}
+
+export type AcquireReason =
+	| "policy_all"
+	| "policy_segment"
+	| "policy_denied_none"
+	| "policy_unobserved"
+	| "policy_denied_observed"
+	| "policy_denied_declared"
+	| "policy_denied_recorded";
+
+/** RFC 0018 §2.1–2.2: what the host observed, what the peer declared, what discovery recorded. */
+export interface AcquireInput {
+	/** The address this statement's connection arrived from; absent when it was not observed. */
+	observed?: string;
+	/** The `base_url` the peer wrote into its own statement. */
+	declared?: string;
+	/** The discovery addresses recorded for this node id when the statement arrived. */
+	recorded?: readonly string[];
+}
+
+export interface AcquireVerdict {
+	allowed: boolean;
+	reason: AcquireReason;
+	/** The allow entry the observed address matched, when one did. */
+	matched?: string;
+}
+
+interface Block {
+	network: string;
+	prefix: number;
+	type: "ipv4" | "ipv6";
+}
+
+const HOST_NAME = /^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$/;
+
+/** One `[acquisition] allow` entry: `network/prefix`, or a host name to accept as written. */
+export function parseAllowBlock(value: string): Block | { name: string } | undefined {
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	const slash = trimmed.lastIndexOf("/");
+	if (slash <= 0) {
+		// A name is matched by its own spelling, so listing it involves no resolution. A bare
+		// address is not a block: it needs a prefix to say what it covers.
+		if (isIP(trimmed) !== 0 || !HOST_NAME.test(trimmed)) return undefined;
+		return { name: trimmed.toLowerCase() };
+	}
+	const prefix = Number(trimmed.slice(slash + 1));
+	if (!Number.isInteger(prefix) || prefix < 0) return undefined;
+	const network = literalAddress(trimmed.slice(0, slash));
+	if (network === undefined) return undefined;
+	if (prefix > (network.type === "ipv4" ? 32 : 128)) return undefined;
+	return { network: network.address, prefix, type: network.type };
+}
+
+/** The host a value names: a URL's hostname, or the value itself when it is already a host. */
+function hostOf(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	if (!trimmed.includes("://")) return trimmed.replace(/^\[(.*)\]$/, "$1");
+	try {
+		const host = new URL(trimmed).hostname;
+		return host.replace(/^\[(.*)\]$/, "$1");
+	} catch {
+		return undefined;
+	}
+}
+
+/** A host that is already a literal address, with IPv4-mapped IPv6 read as IPv4. */
+function literalAddress(host: string): { address: string; type: "ipv4" | "ipv6" } | undefined {
+	const bare = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+	const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(bare);
+	if (mapped !== null) return { address: mapped[1]!, type: "ipv4" };
+	const family = isIP(bare);
+	if (family === 4) return { address: bare, type: "ipv4" };
+	if (family === 6) return { address: bare, type: "ipv6" };
+	return undefined;
+}
+
+function blockHolds(address: { address: string; type: "ipv4" | "ipv6" }, block: Block): boolean {
+	if (block.type !== address.type) return false;
+	const blocks = new BlockList();
+	blocks.addSubnet(block.network, block.prefix, block.type);
+	return blocks.check(address.address, block.type);
+}
+
+/** The allow entry an address falls in, or undefined. */
+function entryFor(address: { address: string; type: "ipv4" | "ipv6" }, allow: readonly string[]): string | undefined {
+	for (const entry of allow) {
+		const block = parseAllowBlock(entry);
+		if (block === undefined || "name" in block) continue;
+		if (blockHolds(address, block)) return entry.trim();
+	}
+	return undefined;
+}
+
+/**
+ * The allow entry a value matches, or undefined. A literal address is judged as itself. A host
+ * name matches an allow entry of the same name; otherwise it is resolved and every address it
+ * names must fall inside the allow set (RFC 0018 §2.1) — a name that resolves to nothing, or to
+ * one address outside the set, matches nothing.
+ */
+export async function allowMatch(value: string, allow: readonly string[], resolve: Resolver = dnsResolver): Promise<string | undefined> {
+	const host = hostOf(value);
+	if (host === undefined) return undefined;
+	const literal = literalAddress(host);
+	if (literal !== undefined) return entryFor(literal, allow);
+	const named = allow.find(entry => {
+		const block = parseAllowBlock(entry);
+		return block !== undefined && "name" in block && block.name === host.toLowerCase();
+	});
+	if (named !== undefined) return named.trim();
+	const resolved = await resolve(host).catch(() => [] as string[]);
+	let matched: string | undefined;
+	for (const address of resolved) {
+		const target = literalAddress(address);
+		if (target === undefined) return undefined;
+		const entry = entryFor(target, allow);
+		if (entry === undefined) return undefined;
+		matched ??= entry;
+	}
+	return matched;
+}
+
+/**
+ * RFC 0018 §2: decide whether this peer may be approved without a human confirming first.
+ *
+ * The declared address is checked because the trust row stores it and `peerBase` falls back to
+ * it when discovery has no record. The recorded addresses are checked because
+ * `discovery.resolve()` re-probes every one of them before it connects, so a record outside the
+ * allow set is an outbound request the policy never authorized.
+ */
+export async function evaluateAcquisition(
+	policy: AcquisitionPolicy,
+	input: AcquireInput,
+	resolve: Resolver = dnsResolver,
+): Promise<AcquireVerdict> {
+	if (policy.policy === "none") return { allowed: false, reason: "policy_denied_none" };
+	if (policy.policy === "all") return { allowed: true, reason: "policy_all" };
+	if (input.observed === undefined) return { allowed: false, reason: "policy_unobserved" };
+	const observed = await allowMatch(input.observed, policy.allow, resolve);
+	if (observed === undefined) return { allowed: false, reason: "policy_denied_observed" };
+	if (input.declared !== undefined && await allowMatch(input.declared, policy.allow, resolve) === undefined) {
+		return { allowed: false, reason: "policy_denied_declared", matched: observed };
+	}
+	for (const address of input.recorded ?? []) {
+		if (await allowMatch(address, policy.allow, resolve) === undefined) {
+			return { allowed: false, reason: "policy_denied_recorded", matched: observed };
+		}
+	}
+	return { allowed: true, reason: "policy_segment", matched: observed };
+}

package/src/binding.ts

@@ -0,0 +1,132 @@
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { AgentRegistry } from "@oh-my-pi/pi-coding-agent/registry/agent-registry";
+import { getRuntime, type PluginRuntime } from "./runtime.ts";
+
+let registryRegistered = false;
+
+/**
+ * Task-spawned sessions are bound to the context alias their dispatch named.
+ * The name is only the marker: the registry reference must still prove the
+ * session is a child of this node's main agent before any record is bound.
+ */
+export function registerContextBinding(pi: ExtensionAPI): void {
+	pi.on("tool_result", async (event, _ctx) => {
+		if (event.toolName !== "task") return;
+		const runtime = getRuntime();
+		if (runtime === undefined) return;
+		try {
+			const input = event.input;
+			const items = Array.isArray(input.tasks) ? input.tasks : [input];
+			const details = event.details as
+				| { progress?: unknown; results?: unknown }
+				| undefined;
+			for (const candidate of [...array(details?.progress), ...array(details?.results)]) {
+				const id = stringField(candidate, "id");
+				if (id === undefined) continue;
+				const index = numberField(candidate, "index");
+				const name = index === undefined ? undefined : stringField(items[index], "name");
+				const alias = aliasOf(name);
+				if (alias === undefined) continue;
+				await bind(runtime, alias, id);
+			}
+		} catch (error) {
+			pi.logger.warn("onlyne.context.binding.failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	});
+
+	if (registryRegistered) return;
+	registryRegistered = true;
+	AgentRegistry.global().onChange(event => {
+		const runtime = getRuntime();
+		if (runtime === undefined) return;
+		if (event.type === "removed") {
+			void updateState(runtime, event.ref.id, "lost").catch(report(pi));
+			return;
+		}
+		if (event.type === "status_changed") {
+			void updateState(runtime, event.ref.id, stateOf(event.ref.status)).catch(report(pi));
+			return;
+		}
+		const alias = aliasOf(event.ref.displayName);
+		if (alias === undefined) return;
+		void bind(runtime, alias, event.ref.id).catch(report(pi));
+	});
+}
+
+async function bind(
+	runtime: PluginRuntime,
+	alias: string,
+	agentId: string,
+): Promise<void> {
+	const existing = await runtime.contexts.find(alias);
+	if (existing === undefined) return;
+	if (existing.node_id !== runtime.config.node.id) return;
+	if (existing.main_agent_id !== runtime.mainAgentId) return;
+	if (existing.agent_id !== undefined && existing.agent_id !== agentId) return;
+	if (existing.agent_id === agentId && existing.session_file !== undefined) return;
+	const ref = AgentRegistry.global().get(agentId);
+	if (ref === undefined || ref.kind !== "sub" || ref.parentId !== runtime.mainAgentId) return;
+	await runtime.contexts.bind(alias, {
+		agent_id: agentId,
+		...(ref.sessionFile === null || ref.sessionFile === undefined ? {} : { session_file: ref.sessionFile }),
+		...(ref.parentId === undefined ? {} : { parent_id: ref.parentId }),
+	});
+}
+
+/** An alias-recorded update follows the bound agent id, never a display name. */
+async function updateState(
+	runtime: PluginRuntime,
+	agentId: string,
+	state: "idle" | "running" | "parked" | "lost",
+): Promise<void> {
+	const records = await runtime.contexts.list();
+	const record = records.find(candidate =>
+		candidate.node_id === runtime.config.node.id &&
+		candidate.main_agent_id === runtime.mainAgentId &&
+		candidate.agent_id === agentId,
+	);
+	if (record === undefined) return;
+	await runtime.contexts.updateState(record.alias, state);
+}
+
+/**
+ * The task name carries the alias; the host may append a numeric suffix to a
+ * repeated name. Nothing else about the name is trusted.
+ */
+function aliasOf(name: string | undefined): string | undefined {
+	if (name === undefined) return undefined;
+	return /^onlyne-(c-[0-9]+)(?:-[0-9]+)?$/.exec(name)?.[1];
+}
+
+function array(value: unknown): unknown[] {
+	return Array.isArray(value) ? value : [];
+}
+
+function stringField(value: unknown, key: string): string | undefined {
+	if (value === null || typeof value !== "object") return undefined;
+	const found = (value as Record<string, unknown>)[key];
+	return typeof found === "string" && found.length > 0 ? found : undefined;
+}
+
+function numberField(value: unknown, key: string): number | undefined {
+	if (value === null || typeof value !== "object") return undefined;
+	const found = (value as Record<string, unknown>)[key];
+	return typeof found === "number" && Number.isInteger(found) ? found : undefined;
+}
+
+function stateOf(status: string): "idle" | "running" | "parked" | "lost" {
+	if (status === "running") return "running";
+	if (status === "parked") return "parked";
+	if (status === "aborted") return "lost";
+	return "idle";
+}
+
+function report(pi: ExtensionAPI): (error: unknown) => void {
+	return error => {
+		pi.logger.warn("onlyne.context.state.failed", {
+			error: error instanceof Error ? error.message : String(error),
+		});
+	};
+}