@genee/omp-opsx-addon 0.3.0 → 0.5.0

package/lib/pipe-core.ts

@@ -0,0 +1,784 @@
+// ── opsx pipe core ───────────────────────────────────────────────────
+// Cross-broker, project-scoped message bus. Every omp broker (a primary
+// session process/window) working in the same project directory shares the
+// runtime tree under `<project>/.omp/opsx/pipe/`:
+//
+//   registry/<broker-id>.json       presence: pid, startedAt, sessions[],
+//                                   roster[]; file mtime is the heartbeat.
+//   mbox/<broker-id>/<msg-id>.json  one mailbox slot per broker; messages are
+//                                   landed via same-directory tmp + rename.
+//
+// The broker-id is the primary session id (`ctx.sessionManager.getSessionId()`).
+// This module implements the CORE only: directory layout, presence heartbeat,
+// roster mirroring, the file mbox protocol (with the single shared `consume()`
+// primitive), four LLM tools, and background GC. The `deliver` field is
+// defined, validated, and stored — NEVER injected (injection is the scope of
+// opsx-pipe-push).
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import type { ExtensionAPI, ExtensionContext } from '@oh-my-pi/pi-coding-agent';
+import { TASK_SUBAGENT_EVENT_CHANNEL, TASK_SUBAGENT_LIFECYCLE_CHANNEL } from '@oh-my-pi/pi-coding-agent/task';
+
+// ── constants ────────────────────────────────────────────────────────
+
+/** Heartbeat: rewrite own presence file every 10s (mtime = heartbeat). */
+export const HEARTBEAT_MS = 10_000;
+/** Online TTL: presence mtime older than 30s counts as offline. */
+export const PRESENCE_TTL_MS = 30_000;
+/** GC: messages and corpse registry files older than 24h are deleted. */
+export const GC_MAX_AGE_MS = 24 * 60 * 60_000;
+/** GC scan period. */
+export const GC_INTERVAL_MS = 60 * 60_000;
+/** Maximum `body` size, in bytes. */
+export const BODY_MAX_BYTES = 32 * 1024;
+/** Wait-tool polling granularity. */
+const WAIT_POLL_MS = 200;
+/** Conservative broker-id whitelist: primary session ids are path segments
+ *  under registry/ and mbox/, so reject separators, '.', '..', etc. */
+const BROKER_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+export type DeliverMode = 'steer' | 'followUp' | 'nextTurn';
+export const DELIVER_MODES: readonly DeliverMode[] = ['steer', 'followUp', 'nextTurn'];
+
+/** The primary session's agent name (harness registry id MAIN_AGENT_ID). */
+const MAIN_AGENT_ID = 'Main';
+
+// ── message structure ────────────────────────────────────────────────
+
+export interface Deliver {
+    mode: DeliverMode;
+    triggerTurn: boolean;
+}
+
+export interface PipeMessage {
+    /** Short random msg-id (sender-generated); used for idempotent dedup. */
+    id: string;
+    from: { broker: string; session: string; agent: typeof MAIN_AGENT_ID };
+    to: { broker: string; session?: string };
+    /** Sender-decided delivery semantics; core only validates/stores this. */
+    deliver: Deliver;
+    type: string;
+    body: string;
+    replyTo?: string;
+    /** Unix epoch seconds. */
+    ts: number;
+}
+
+export interface PresenceFile {
+    pid: number;
+    startedAt: number;
+    sessions: string[];
+    roster: string[];
+}
+
+export interface BrokerView {
+    broker: string;
+    pid: number;
+    startedAt: number;
+    sessions: string[];
+    roster: string[];
+}
+
+// ── deliver / message validation (pure, unit-tested) ─────────────────
+
+/**
+ * Normalize a user-supplied `deliver` field: defaults are
+ * `{ mode: 'followUp', triggerTurn: true }`; an invalid `mode`/`triggerTurn`
+ * is rejected. core never acts on the field — pipe-push owns the
+ * mode → injection mapping.
+ */
+export function normalizeDeliver(input: unknown): Deliver {
+    if (input === undefined || input === null) {
+        return { mode: 'followUp', triggerTurn: true };
+    }
+    if (typeof input !== 'object') {
+        throw new Error('deliver must be an object { mode, triggerTurn }');
+    }
+    const rec = input as Record<string, unknown>;
+    const mode = rec.mode === undefined ? 'followUp' : rec.mode;
+    if (typeof mode !== 'string' || !(DELIVER_MODES as readonly string[]).includes(mode)) {
+        throw new Error(`deliver.mode must be one of ${DELIVER_MODES.join('/')}, got: ${String(mode)}`);
+    }
+    const triggerTurn = rec.triggerTurn === undefined ? true : rec.triggerTurn;
+    if (typeof triggerTurn !== 'boolean') {
+        throw new Error('deliver.triggerTurn must be a boolean');
+    }
+    return { mode: mode as DeliverMode, triggerTurn };
+}
+
+function assertBody(body: unknown): asserts body is string {
+    if (typeof body !== 'string') {
+        throw new Error('body must be a string');
+    }
+    const bytes = Buffer.byteLength(body, 'utf-8');
+    if (bytes > BODY_MAX_BYTES) {
+        throw new Error(
+            `body exceeds ${BODY_MAX_BYTES} bytes (got ${bytes}); route large payloads via local:// references`,
+        );
+    }
+}
+
+function assertBrokerId(id: unknown, field: string): asserts id is string {
+    if (typeof id !== 'string' || !BROKER_ID_RE.test(id)) {
+        throw new Error(`${field} must be a non-empty broker id matching ${BROKER_ID_RE}`);
+    }
+}
+
+function mintMsgId(): string {
+    // Short random, filename-safe.
+    const raw =
+        globalThis.crypto?.randomUUID?.() ??
+        `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    return raw.replace(/-/g, '').slice(0, 16);
+}
+
+// ── filesystem layout ────────────────────────────────────────────────
+
+export function pipeRootDir(projectDir: string): string {
+    return join(projectDir, '.omp', 'opsx', 'pipe');
+}
+
+function registryDir(root: string): string {
+    return join(root, 'registry');
+}
+
+function mboxDir(root: string): string {
+    return join(root, 'mbox');
+}
+
+function brokerMboxDir(root: string, brokerId: string): string {
+    return join(mboxDir(root), brokerId);
+}
+
+function registryFile(root: string, brokerId: string): string {
+    return join(registryDir(root), `${brokerId}.json`);
+}
+
+/** mkdir -p registry/ and mbox/; idempotent. */
+export async function ensureLayouts(root: string): Promise<void> {
+    await fs.mkdir(registryDir(root), { recursive: true });
+    await fs.mkdir(mboxDir(root), { recursive: true });
+}
+
+// ── atomic writes (same-directory tmp + rename) ──────────────────────
+
+let writeSeq = 0;
+
+async function atomicWriteJson(file: string, data: unknown): Promise<void> {
+    const dir = join(file, '..');
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${writeSeq++}`;
+    await fs.writeFile(tmp, JSON.stringify(data), 'utf-8');
+    await fs.rename(tmp, file);
+}
+
+// ── presence ─────────────────────────────────────────────────────────
+
+export async function writePresence(root: string, brokerId: string, presence: PresenceFile): Promise<void> {
+    await atomicWriteJson(registryFile(root, brokerId), presence);
+}
+
+/**
+ * List online brokers: every `registry/*.json` whose mtime is within
+ * PRESENCE_TTL_MS. Stale brokers are filtered out. Unreadable entries are
+ * skipped (a half-written file is never visible: writers land via rename).
+ */
+export async function listBrokers(root: string, now: number = Date.now()): Promise<BrokerView[]> {
+    const dir = registryDir(root);
+    let names: string[];
+    try {
+        names = await fs.readdir(dir);
+    } catch {
+        return [];
+    }
+    const out: BrokerView[] = [];
+    for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        const file = join(dir, name);
+        try {
+            const st = await fs.stat(file);
+            if (now - st.mtimeMs > PRESENCE_TTL_MS) continue;
+            const parsed = JSON.parse(await fs.readFile(file, 'utf-8')) as Partial<PresenceFile>;
+            out.push({
+                broker: name.slice(0, -'.json'.length),
+                pid: typeof parsed.pid === 'number' ? parsed.pid : -1,
+                startedAt: typeof parsed.startedAt === 'number' ? parsed.startedAt : 0,
+                sessions: Array.isArray(parsed.sessions)
+                    ? parsed.sessions.filter((s): s is string => typeof s === 'string')
+                    : [],
+                roster: Array.isArray(parsed.roster)
+                    ? parsed.roster.filter((s): s is string => typeof s === 'string')
+                    : [],
+            });
+        } catch {
+            // Raced with a rewrite/delete, or corrupt — skip.
+        }
+    }
+    return out;
+}
+
+// ── mbox send / consume ──────────────────────────────────────────────
+
+export interface SendInput {
+    fromBroker: string;
+    toBroker: string;
+    toSession?: string;
+    body: string;
+    /** Raw deliver input; normalized/defaulted by {@link normalizeDeliver}. */
+    deliver?: unknown;
+    type?: string;
+    replyTo?: string;
+    /** Injectable for tests; defaults to a fresh minted id. */
+    id?: string;
+    ts?: number;
+}
+
+/** Build, validate, and atomically land a message in the target mbox. */
+export async function sendMessage(root: string, input: SendInput): Promise<PipeMessage> {
+    assertBrokerId(input.fromBroker, 'from.broker');
+    assertBrokerId(input.toBroker, 'to.broker');
+    assertBody(input.body);
+    if (input.toSession !== undefined && typeof input.toSession !== 'string') {
+        throw new Error('to.session must be a string when provided');
+    }
+    if (input.replyTo !== undefined && typeof input.replyTo !== 'string') {
+        throw new Error('replyTo must be a string when provided');
+    }
+    const type = input.type === undefined ? 'text' : input.type;
+    if (typeof type !== 'string' || !type) {
+        throw new Error('type must be a non-empty string');
+    }
+
+    const msg: PipeMessage = {
+        id: input.id ?? mintMsgId(),
+        from: { broker: input.fromBroker, session: input.fromBroker, agent: MAIN_AGENT_ID },
+        to: { broker: input.toBroker, ...(input.toSession ? { session: input.toSession } : {}) },
+        deliver: normalizeDeliver(input.deliver),
+        type,
+        body: input.body,
+        ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+        ts: input.ts ?? Math.floor(Date.now() / 1000),
+    };
+
+    const file = join(brokerMboxDir(root, input.toBroker), `${msg.id}.json`);
+    await atomicWriteJson(file, msg);
+    return msg;
+}
+
+// Process-internal idempotency: consumed msg-ids per (root, broker). Cross-
+// process, the atomic rename guarantees a single consumer wins a given file;
+// worst case a redelivered id surfaces once per process (at-least-once).
+const consumedIds = new Map<string, Set<string>>();
+
+function dedupKey(root: string, brokerId: string): string {
+    return `${root}::${brokerId}`;
+}
+
+/** Test-only: clear the in-process dedup memory. */
+export function _resetConsumeDedupForTest(): void {
+    consumedIds.clear();
+}
+
+/**
+ * The single consumption primitive. recv/wait tools AND the opsx-pipe-push
+ * injector MUST call this — no parallel rename/read/delete logic:
+ *
+ *   1. list `<root>/mbox/<brokerId>/*.json` (writers' tmp files ignored)
+ *   2. atomically `rename` each message aside (`.consumed-<pid>-<seq>`);
+ *      a failed rename means another consumer won the file — skip it
+ *   3. read + parse, then delete; malformed files are deleted to avoid a
+ *      redelivery loop
+ *   4. in-process msg-id dedup: an already-consumed id is dropped
+ *
+ * Returns the messages consumed in this call (filename order).
+ */
+export async function consume(root: string, brokerId: string): Promise<PipeMessage[]> {
+    assertBrokerId(brokerId, 'brokerId');
+    const dir = brokerMboxDir(root, brokerId);
+    let names: string[];
+    try {
+        names = await fs.readdir(dir);
+    } catch {
+        return []; // no mailbox yet
+    }
+    const key = dedupKey(root, brokerId);
+    let seen = consumedIds.get(key);
+    if (!seen) {
+        seen = new Set();
+        consumedIds.set(key, seen);
+    }
+    const out: PipeMessage[] = [];
+    for (const name of names) {
+        // Only settled message files; never touch writers' tmp files.
+        if (!name.endsWith('.json')) continue;
+        const src = join(dir, name);
+        const aside = join(dir, `${name}.consumed-${process.pid}-${writeSeq++}`);
+        try {
+            await fs.rename(src, aside);
+        } catch {
+            // ENOENT/race: another consumer (recv/wait or the pipe-push
+            // injector) claimed it first — rename atomicity is the
+            // single-winner gate.
+            continue;
+        }
+        let parsed: PipeMessage | null = null;
+        try {
+            parsed = JSON.parse(await fs.readFile(aside, 'utf-8')) as PipeMessage;
+        } catch {
+            parsed = null;
+        } finally {
+            // Read complete → delete (the delete in rename→read→delete).
+            await fs.rm(aside, { force: true }).catch(() => {});
+        }
+        if (!parsed || typeof parsed.id !== 'string' || typeof parsed.body !== 'string') {
+            continue; // corrupt — already removed
+        }
+        if (seen.has(parsed.id)) continue; // in-process idempotency
+        seen.add(parsed.id);
+        out.push(parsed);
+    }
+    return out;
+}
+
+/**
+ * Block up to `timeoutMs` for messages, consuming as soon as any arrive.
+ * Returns immediately with whatever was consumed on the first non-empty poll;
+ * returns [] on timeout. Elapsed time is accumulated from the (injectable)
+ * sleep durations, which keeps tests deterministic under a fake scheduler.
+ */
+export async function waitForMessages(
+    root: string,
+    brokerId: string,
+    timeoutMs: number,
+    opts?: { sleep?: (ms: number) => Promise<void>; signal?: AbortSignal },
+): Promise<PipeMessage[]> {
+    const sleep = opts?.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+    let elapsed = 0;
+    for (;;) {
+        if (opts?.signal?.aborted) return [];
+        const msgs = await consume(root, brokerId);
+        if (msgs.length > 0) return msgs;
+        if (elapsed >= timeoutMs) return [];
+        const step = Math.min(WAIT_POLL_MS, timeoutMs - elapsed);
+        elapsed += step;
+        await sleep(step);
+    }
+}
+
+/**
+ * Delete mbox messages older than GC_MAX_AGE_MS (by file mtime) and corpse
+ * registry files (broker absent far longer than the online TTL).
+ */
+export async function runGc(root: string, now: number = Date.now()): Promise<void> {
+    // mbox: <root>/mbox/<broker-id>/<msg-id>.json
+    const mbox = mboxDir(root);
+    let brokerDirs: string[] = [];
+    try {
+        brokerDirs = await fs.readdir(mbox);
+    } catch {
+        brokerDirs = [];
+    }
+    for (const b of brokerDirs) {
+        const dir = join(mbox, b);
+        let files: string[];
+        try {
+            const st = await fs.stat(dir);
+            if (!st.isDirectory()) continue;
+            files = await fs.readdir(dir);
+        } catch {
+            continue;
+        }
+        for (const f of files) {
+            const file = join(dir, f);
+            try {
+                const st = await fs.stat(file);
+                if (st.isFile() && now - st.mtimeMs > GC_MAX_AGE_MS) {
+                    await fs.rm(file, { force: true });
+                }
+            } catch {
+                // raced — ignore
+            }
+        }
+    }
+    // registry corpses
+    const reg = registryDir(root);
+    let regFiles: string[] = [];
+    try {
+        regFiles = await fs.readdir(reg);
+    } catch {
+        regFiles = [];
+    }
+    for (const f of regFiles) {
+        if (!f.endsWith('.json')) continue;
+        const file = join(reg, f);
+        try {
+            const st = await fs.stat(file);
+            if (now - st.mtimeMs > GC_MAX_AGE_MS) {
+                await fs.rm(file, { force: true });
+            }
+        } catch {
+            // raced — ignore
+        }
+    }
+}
+
+// ── eventBus access (same hack as the index.ts file header) ──────────
+// Plugins cannot subscribe to eventBus channels via the official
+// ExtensionAPI; we reach through internal properties. The channel string is
+// hardcoded from harness src/task/types.ts:59.
+
+function getEventBusFromCtx(ctx: ExtensionContext): unknown {
+    const sessionManager = ctx.sessionManager as unknown as Record<string, unknown> | undefined;
+    if (!sessionManager) return undefined;
+    for (const key of ['session', '_session', '__session', 'eventBus', '_eventBus']) {
+        const val = sessionManager[key];
+        if (val && typeof val === 'object') {
+            const obj = val as Record<string, unknown>;
+            if (typeof obj.eventBus !== 'undefined') return obj.eventBus;
+            if (key === 'eventBus' || key === '_eventBus') return val;
+        }
+    }
+    return undefined;
+}
+
+function subscribeEventBus(eventBus: unknown, channel: string, handler: (data: unknown) => void): () => void {
+    const bus = eventBus as Record<string, unknown>;
+    const onMethod = bus.on as ((ch: string, h: (data: unknown) => void) => () => void) | undefined;
+    if (typeof onMethod === 'function') return onMethod.call(bus, channel, handler);
+    return () => {};
+}
+
+// ── per-broker runtime state ─────────────────────────────────────────
+
+interface BrokerState {
+    brokerId: string;
+    root: string;
+    startedAt: number;
+    /** Active agent ids observed on the subagent event channel; pruned when
+     *  the lifecycle channel reports a terminal status. */
+    agents: Set<string>;
+    /** eventBus unsubscribers (best-effort cleanup on shutdown). */
+    unsubscribe?: () => void;
+    /** Managed timer handles (ctx.setInterval), cleared via ctx.clearTimer. */
+    heartbeatTimer?: ReturnType<ExtensionContext['setInterval']>;
+    gcTimer?: ReturnType<ExtensionContext['setInterval']>;
+}
+
+const states = new Map<string, BrokerState>();
+
+function stateFor(ctx: ExtensionContext): BrokerState {
+    const brokerId = ctx.sessionManager?.getSessionId?.() ?? '';
+    const existing = states.get(brokerId);
+    if (existing) return existing;
+    const state: BrokerState = {
+        brokerId,
+        root: pipeRootDir(ctx.cwd),
+        startedAt: Date.now(),
+        agents: new Set(),
+    };
+    states.set(brokerId, state);
+    return state;
+}
+
+async function heartbeat(state: BrokerState): Promise<void> {
+    // sessions[] and roster[] are same-source: ids collected from the
+    // TASK_SUBAGENT_EVENT_CHANNEL subscription, always unioned with the
+    // primary session itself. roster names the active agents (Main first);
+    // sessions carries the primary session UUID (the broker-id) plus the
+    // same observed agent ids — those are the hub-addressable targets
+    // (to.session). The primary session is the only session that loads
+    // extensions, which guarantees both lists are never empty.
+    const roster = Array.from(new Set([MAIN_AGENT_ID, ...state.agents])).sort();
+    const sessions = Array.from(new Set([state.brokerId, ...state.agents])).sort();
+    await writePresence(state.root, state.brokerId, {
+        pid: process.pid,
+        startedAt: state.startedAt,
+        sessions,
+        roster,
+    });
+}
+
+function trackSubagentFrame(state: BrokerState, payload: unknown): void {
+    try {
+        if (!payload || typeof payload !== 'object') return;
+        const p = payload as { id?: unknown };
+        if (typeof p.id === 'string' && p.id) state.agents.add(p.id);
+    } catch {
+        /* best-effort */
+    }
+}
+
+/** Mirror roster membership from the lifecycle channel: 'started' adds as a
+ *  fallback for agents that never emit an event frame; terminal statuses
+ *  ('completed' | 'failed' | 'aborted') prune the id so opsx_pipe_list
+ *  never advertises a dead session. The primary session is re-unioned at
+ *  every heartbeat and can never be cropped. */
+function trackSubagentLifecycle(state: BrokerState, payload: unknown): void {
+    try {
+        if (!payload || typeof payload !== 'object') return;
+        const p = payload as { id?: unknown; status?: unknown };
+        if (typeof p.id !== 'string' || !p.id) return;
+        if (p.status === 'completed' || p.status === 'failed' || p.status === 'aborted') {
+            state.agents.delete(p.id);
+        } else if (p.status === 'started') {
+            state.agents.add(p.id);
+        }
+    } catch {
+        /* best-effort */
+    }
+}
+
+/** Initialize (idempotently) pipe core for the primary session of `ctx`. */
+async function ensureBrokerStarted(ctx: ExtensionContext): Promise<BrokerState> {
+    const brokerId = ctx.sessionManager?.getSessionId?.() ?? '';
+    // P2-2 guard: refuse to bootstrap against an id that would escape the
+    // registry directory (e.g. empty, '/', '..') — otherwise we'd write
+    // registry/.json or clobber an unrelated path.
+    if (!BROKER_ID_RE.test(brokerId)) {
+        throw new Error(`[opsx-pipe] invalid broker id, refusing to start: ${JSON.stringify(brokerId)}`);
+    }
+    const state = stateFor(ctx);
+    if (state.heartbeatTimer) return state;
+
+    await ensureLayouts(state.root);
+
+    // Roster/sessions mirror: event channel adds active ids; the lifecycle
+    // channel prunes them on completion/failure/abort. Same eventBus hack
+    // as index.ts's subagent usage subscription; channel constants are
+    // imported from the harness, not hardcoded.
+    const eventBus = getEventBusFromCtx(ctx);
+    if (eventBus) {
+        const unsubEvent = subscribeEventBus(eventBus, TASK_SUBAGENT_EVENT_CHANNEL, (payload) =>
+            trackSubagentFrame(state, payload),
+        );
+        const unsubLifecycle = subscribeEventBus(eventBus, TASK_SUBAGENT_LIFECYCLE_CHANNEL, (payload) =>
+            trackSubagentLifecycle(state, payload),
+        );
+        state.unsubscribe = () => {
+            try {
+                unsubEvent?.();
+            } catch {
+                /* best-effort */
+            }
+            try {
+                unsubLifecycle?.();
+            } catch {
+                /* best-effort */
+            }
+        };
+    }
+    await heartbeat(state);
+
+    // Managed timers are mandatory — a raw setInterval throw would surface
+    // as an uncaughtException and tear the whole session down (extensions.md
+    // "Background work"). Callback bodies additionally guard their errors.
+    const guarded = (fn: () => Promise<void>): (() => Promise<void>) => () => {
+        return fn().catch(() => {
+            /* heartbeat/GC failures must not kill the timer */
+        });
+    };
+    state.heartbeatTimer = ctx.setInterval(guarded(() => heartbeat(state)), HEARTBEAT_MS);
+    state.gcTimer = ctx.setInterval(guarded(() => runGc(state.root)), GC_INTERVAL_MS);
+
+    return state;
+}
+
+async function stopBroker(ctx: ExtensionContext): Promise<void> {
+    const brokerId = ctx.sessionManager?.getSessionId?.() ?? '';
+    const state = brokerId ? states.get(brokerId) : undefined;
+    if (!state) return;
+    states.delete(brokerId);
+    try {
+        state.unsubscribe?.();
+    } catch {
+        /* best-effort */
+    }
+    // Managed timers are also reaped automatically on session_shutdown, but
+    // clear explicitly so a shutdown followed by a restart in-process cannot
+    // double-tick.
+    if (state.heartbeatTimer) ctx.clearTimer(state.heartbeatTimer);
+    if (state.gcTimer) ctx.clearTimer(state.gcTimer);
+    // Drop our presence so list stops advertising this broker immediately;
+    // TTL/GC would reclaim the corpse anyway.
+    await fs.rm(registryFile(state.root, brokerId), { force: true }).catch(() => {});
+}
+
+// ── tool registration ────────────────────────────────────────────────
+
+function textResult(text: string, details: unknown) {
+    return {
+        content: [{ type: 'text' as const, text }],
+        details,
+    };
+}
+
+// Tool parameter shapes (zod-validated at the harness boundary). pi-ai's
+// Static<> only resolves ArkType schemas, so execute sees unknown params for
+// a pi.zod schema; we re-state the validated shape here.
+interface SendToolParams {
+    to: { broker: string; session?: string };
+    deliver?: { mode?: DeliverMode; triggerTurn?: boolean };
+    type?: string;
+    body: string;
+    replyTo?: string;
+}
+
+interface WaitToolParams {
+    timeout: number;
+}
+
+export function registerPipeCore(pi: ExtensionAPI): void {
+    const z = pi.zod;
+
+    // ── opsx_pipe_list ──
+    pi.registerTool({
+        name: 'opsx_pipe_list',
+        label: 'Pipe: list brokers',
+        description:
+            'List online brokers (omp sessions open in this project) and their rosters, cross-broker. Brokers whose heartbeat is older than 30s are filtered out as offline.',
+        parameters: z.object({}),
+        approval: 'read',
+        async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+            const state = await ensureBrokerStarted(ctx);
+            const brokers = await listBrokers(state.root);
+            return textResult(
+                [
+                    `Online brokers: ${brokers.length}`,
+                    ...brokers.map(
+                        (b) =>
+                            `- ${b.broker}${b.broker === state.brokerId ? ' (self)' : ''} roster: [${b.roster.join(', ')}] sessions: [${b.sessions.join(', ')}]`,
+                    ),
+                ].join('\n'),
+                { brokers },
+            );
+        },
+    });
+
+    // ── opsx_pipe_send ──
+    pi.registerTool({
+        name: 'opsx_pipe_send',
+        label: 'Pipe: send message',
+        description:
+            'Fire-and-forget a text message to another broker\'s mbox (same semantics as hub send). Validates the deliver field { mode: steer|followUp|nextTurn, triggerTurn } (defaults followUp/true); core stores but never injects it. body is capped at 32KB.',
+        parameters: z.object({
+            to: z.object({
+                broker: z.string().describe('Target broker id (a primary session id; see opsx_pipe_list)'),
+                session: z.string().optional().describe('Optional target agent/session for hub relay'),
+            }),
+            deliver: z
+                .object({
+                    mode: z.enum(['steer', 'followUp', 'nextTurn']),
+                    triggerTurn: z.boolean(),
+                })
+                .partial()
+                .optional()
+                .describe('Delivery semantics; defaults { mode: followUp, triggerTurn: true }'),
+            type: z.string().optional().describe('Message type; defaults to "text"'),
+            body: z.string().describe('Message body, max 32KB'),
+            replyTo: z.string().optional().describe('msg-id this replies to'),
+        }),
+        approval: 'write',
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            // pi-ai's Static<> resolves ArkType schemas only; the pi.zod
+            // omptype shim yields unknown here (same cast the harness's own
+            // with-deps example uses), so the validated shape is declared
+            // explicitly. normalizeDeliver re-validates deliver at runtime.
+            const p = params as SendToolParams;
+            const state = await ensureBrokerStarted(ctx);
+            const msg = await sendMessage(state.root, {
+                fromBroker: state.brokerId,
+                toBroker: p.to.broker,
+                toSession: p.to.session,
+                deliver: p.deliver,
+                type: p.type,
+                body: p.body,
+                replyTo: p.replyTo,
+            });
+            return textResult(`Sent message ${msg.id} to broker ${msg.to.broker}`, {
+                id: msg.id,
+                to: msg.to,
+            });
+        },
+    });
+
+    // ── opsx_pipe_recv ──
+    pi.registerTool({
+        name: 'opsx_pipe_recv',
+        label: 'Pipe: receive messages',
+        description:
+            'Non-blocking: consume all unconsumed messages from this broker\'s mbox (atomic rename→read→delete). Returns a tool result only — no conversation entry is created. An empty mbox returns an empty list.',
+        parameters: z.object({}),
+        approval: 'read',
+        async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+            const state = await ensureBrokerStarted(ctx);
+            const messages = await consume(state.root, state.brokerId);
+            return textResult(
+                messages.length === 0
+                    ? 'No messages in mbox.'
+                    : `Consumed ${messages.length} message(s):\n${JSON.stringify(messages, null, 2)}`,
+                { messages },
+            );
+        },
+    });
+
+    // ── opsx_pipe_wait ──
+    pi.registerTool({
+        name: 'opsx_pipe_wait',
+        label: 'Pipe: wait for message',
+        description:
+            'Block up to timeout (ms) waiting for messages in this broker\'s mbox; consumes and returns them as soon as any arrive. Returns an empty list on timeout.',
+        parameters: z.object({
+            timeout: z.number().int().positive().describe('Max wait time in milliseconds'),
+        }),
+        approval: 'read',
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const p = params as WaitToolParams;
+            const state = await ensureBrokerStarted(ctx);
+            // Managed setTimeout is cleared on session shutdown; race the
+            // sleep against the abort signal so cancellation still resolves.
+            const sleep = (ms: number): Promise<void> =>
+                new Promise((resolve) => {
+                    if (signal?.aborted) return resolve(undefined);
+                    const timer = ctx.setTimeout(() => resolve(undefined), ms);
+                    signal?.addEventListener(
+                        'abort',
+                        () => {
+                            ctx.clearTimer(timer);
+                            resolve(undefined);
+                        },
+                        { once: true },
+                    );
+                });
+            const messages = await waitForMessages(state.root, state.brokerId, p.timeout, {
+                sleep,
+                signal,
+            });
+            return textResult(
+                messages.length === 0
+                    ? `Timed out after ${p.timeout}ms with no messages.`
+                    : `Consumed ${messages.length} message(s):\n${JSON.stringify(messages, null, 2)}`,
+                { messages, timedOut: messages.length === 0 },
+            );
+        },
+    });
+
+    // registerTool returns void and silently skips name conflicts — log
+    // registration so collision with another extension is diagnosable.
+    pi.logger?.debug?.('[opsx-pipe] registered 4 tools');
+
+    // Heartbeat/GC lifecycle: start on session_start, tear down on shutdown.
+    pi.on('session_start', async (_event, ctx) => {
+        try {
+            await ensureBrokerStarted(ctx);
+        } catch {
+            /* pipe core is best-effort; never break session start */
+        }
+    });
+    pi.on('session_shutdown', async (_event, ctx) => {
+        try {
+            await stopBroker(ctx);
+        } catch {
+            /* best-effort */
+        }
+    });
+}