@trevonistrevon/pi-loop 0.5.8 → 0.6.0

package/coverage/src/ui/widget.ts.html

@@ -147,44 +147,44 @@
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">68x</span>
-<span class="cline-any cline-yes">68x</span>
+<span class="cline-any cline-yes">72x</span>
+<span class="cline-any cline-yes">72x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">107x</span>
+<span class="cline-any cline-yes">108x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">46x</span>
+<span class="cline-any cline-yes">47x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">63x</span>
+<span class="cline-any cline-yes">67x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">192x</span>
-<span class="cline-any cline-yes">164x</span>
+<span class="cline-any cline-yes">191x</span>
+<span class="cline-any cline-yes">168x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">164x</span>
-<span class="cline-any cline-yes">164x</span>
-<span class="cline-any cline-yes">164x</span>
+<span class="cline-any cline-yes">168x</span>
+<span class="cline-any cline-yes">168x</span>
+<span class="cline-any cline-yes">168x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">164x</span>
-<span class="cline-any cline-yes">68x</span>
+<span class="cline-any cline-yes">168x</span>
+<span class="cline-any cline-yes">70x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">96x</span>
-<span class="cline-any cline-yes">96x</span>
-<span class="cline-any cline-yes">96x</span>
-<span class="cline-any cline-yes">96x</span>
+<span class="cline-any cline-yes">98x</span>
+<span class="cline-any cline-yes">98x</span>
+<span class="cline-any cline-yes">98x</span>
+<span class="cline-any cline-yes">98x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">96x</span>
-<span class="cline-any cline-yes">96x</span>
-<span class="cline-any cline-yes">96x</span>
+<span class="cline-any cline-yes">98x</span>
+<span class="cline-any cline-yes">98x</span>
+<span class="cline-any cline-yes">98x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
@@ -193,12 +193,12 @@
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">120x</span>
+<span class="cline-any cline-yes">117x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
-<span class="cline-any cline-yes">45x</span>
-<span class="cline-any cline-yes">44x</span>
+<span class="cline-any cline-yes">40x</span>
+<span class="cline-any cline-yes">39x</span>
 <span class="cline-any cline-yes">6x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js">import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
@@ -277,7 +277,7 @@ function isStatusVisibleLoop(loop: LoopEntry): boolean {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-19T00:56:38.236Z
+                at 2026-07-02T19:31:50.067Z
             </div>
         <script src="../../prettify.js"></script>
         <script>

package/dist/api.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API surface for sibling extensions (imported as
+ * `@trevonistrevon/pi-loop/api`). Everything else under src/ is internal —
+ * the package `exports` map deliberately blocks deep imports.
+ */
+export { type CleanReply, type CreateTaskParams, type CreateTaskReply, type PendingReply, type PingReply, replyChannel, type SpawnParams, type SpawnReply, SUBAGENTS_RPC, TASK_EVENTS, TASKS_RPC, type TaskEntryWire, type TaskStatusWire, type UpdateTaskParams, type UpdateTaskReply, } from "./rpc/channels.js";
+export { type HandleRpcOptions, handleRpc, PROTOCOL_VERSION, RpcError, type RpcEventBus, type RpcReply, rpcCall, rpcProbe, } from "./rpc/cross-extension-rpc.js";
+export { NATIVE_TASKS_PROVIDER } from "./runtime/native-task-rpc.js";
+export { resolveLoopStorePath, resolveTaskStorePath } from "./runtime/scope.js";
+export { TaskStore } from "./task-store.js";
+export type { TaskEntry, TaskStatus, TaskStoreData } from "./task-types.js";

package/dist/api.js

@@ -0,0 +1,10 @@
+/**
+ * Public API surface for sibling extensions (imported as
+ * `@trevonistrevon/pi-loop/api`). Everything else under src/ is internal —
+ * the package `exports` map deliberately blocks deep imports.
+ */
+export { replyChannel, SUBAGENTS_RPC, TASK_EVENTS, TASKS_RPC, } from "./rpc/channels.js";
+export { handleRpc, PROTOCOL_VERSION, RpcError, rpcCall, rpcProbe, } from "./rpc/cross-extension-rpc.js";
+export { NATIVE_TASKS_PROVIDER } from "./runtime/native-task-rpc.js";
+export { resolveLoopStorePath, resolveTaskStorePath } from "./runtime/scope.js";
+export { TaskStore } from "./task-store.js";

package/dist/commands/loop-command.js

@@ -53,7 +53,7 @@ export function registerLoopCommand(options) {
         if (!selected || selected === "< Back")
             return;
         const match = selected.match(/#(\d+)/);
-        if (match) {
+        if (match?.[1]) {
             const entry = getStore().get(match[1]);
             if (entry) {
                 const actions = ["x Delete"];
@@ -114,7 +114,7 @@ export function registerLoopCommand(options) {
             }
             const intervalMatch = trimmed.match(/^(\d+\s*[smhdS]\b)/i);
             if (intervalMatch) {
-                const interval = intervalMatch[1];
+                const interval = intervalMatch[1] ?? intervalMatch[0];
                 const prompt = trimmed.slice(intervalMatch[0].length).trim();
                 if (!prompt) {
                     ui.notify("Provide a prompt after the interval, e.g., /loop 5m check the deploy", "warning");

package/dist/commands/tasks-command.js

@@ -47,10 +47,10 @@ export function registerTasksCommand(options) {
             await createNativeTaskInteractively(ui);
             return viewNativeTasks(ui);
         }
-        const match = selected.match(/#(\d+)/);
-        if (!match)
+        const taskId = selected.match(/#(\d+)/)?.[1];
+        if (!taskId)
             return viewNativeTasks(ui);
-        const task = taskStore.get(match[1]);
+        const task = taskStore.get(taskId);
         if (!task)
             return viewNativeTasks(ui);
         const actions = ["x Delete"];

package/dist/coordinator.d.ts

@@ -1,5 +1,5 @@
 export type ReducerSource = "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
-export type ReducerEntityType = "task" | "loop" | "monitor" | "notification" | "goal";
+export type ReducerEntityType = "task" | "loop" | "monitor" | "notification";
 export interface ReducerEvent<TType extends string = string, TPayload = unknown> {
     type: TType;
     at: number;

package/dist/index.js

@@ -18,6 +18,7 @@ import { registerTasksCommand } from "./commands/tasks-command.js";
 import { atMaxFires } from "./loop-reducer.js";
 import { MonitorManager } from "./monitor-manager.js";
 import { createMonitorOnDoneRuntime } from "./runtime/monitor-ondone-runtime.js";
+import { registerNativeTaskRpc } from "./runtime/native-task-rpc.js";
 import { createNotificationRuntime, } from "./runtime/notification-runtime.js";
 import { resolveLoopStorePath, resolveTaskStorePath } from "./runtime/scope.js";
 import { registerSessionRuntimeHooks } from "./runtime/session-runtime.js";
@@ -36,6 +37,9 @@ function debug(...args) {
     if (DEBUG)
         console.error("[pi-loop]", ...args);
 }
+function isStaleExtensionContextError(error) {
+    return error instanceof Error && error.message.includes("extension ctx is stale");
+}
 export default function (pi) {
     const piLoopEnv = process.env.PI_LOOP;
     const piLoopScope = process.env.PI_LOOP_SCOPE;
@@ -50,7 +54,9 @@ export default function (pi) {
     // call), so stale monitors don't linger in the count between turns.
     monitorManager.setOnChange(() => widget.update());
     widget.setTaskSummaryProvider(() => {
-        if (!nativeTaskStore)
+        // Once pi-tasks owns the channels, any native store created during the
+        // detection window is a shadow — never surface it in the status line.
+        if (tasksAvailable || !nativeTaskStore)
             return { count: 0 };
         const tasks = nativeTaskStore.list().filter(t => t.status === "pending" || t.status === "in_progress");
         const active = tasks.find(t => t.status === "in_progress");
@@ -66,8 +72,18 @@ export default function (pi) {
     triggerSystem = new TriggerSystem(pi, scheduler, store, onLoopFire);
     // ── pi-tasks integration ──
     let tasksAvailable = false;
+    let tasksDetectionSettled = false;
     let nativeTaskStore;
     let nativeTasksRegistered = false;
+    function getOrCreateNativeTaskStore() {
+        // pi-tasks owns the task channels; don't create a shadow store.
+        if (tasksAvailable)
+            return undefined;
+        if (!nativeTaskStore) {
+            nativeTaskStore = new TaskStore(resolveTaskStorePath(getScopeOptions(), _sessionId));
+        }
+        return nativeTaskStore;
+    }
     const taskRuntime = createTaskRuntimeBridge({
         pi,
         isTasksAvailable: () => tasksAvailable,
@@ -83,6 +99,29 @@ export default function (pi) {
             widget.update();
             await evaluateTaskBacklog(taskStore, taskStore.pendingCount());
         },
+        onDetectionStarted: () => {
+            tasksDetectionSettled = false;
+        },
+        onDetectionSettled: () => {
+            tasksDetectionSettled = true;
+        },
+        debug,
+    });
+    // The RPC server registers at init (not behind the 6s tool-fallback timer) so
+    // early cross-extension calls never race the timer; it stands down via
+    // isEnabled once an external pi-tasks is detected. checkTasksVersion ignores
+    // this server's own ping reply via its provider field. Mutating verbs stay
+    // silent until the detection probe settles, so a co-resident pi-tasks can
+    // never race the native server into creating divergent task state.
+    registerNativeTaskRpc({
+        pi,
+        getNativeTaskStore: getOrCreateNativeTaskStore,
+        isEnabled: () => !tasksAvailable,
+        isDetectionSettled: () => tasksDetectionSettled,
+        evaluateTaskBacklog: (taskStore, pendingCount) => evaluateTaskBacklog(taskStore, pendingCount),
+        updateWidget: () => {
+            widget.update();
+        },
         debug,
     });
     taskRuntime.checkTasksVersion();
@@ -153,6 +192,12 @@ export default function (pi) {
         hasPendingTasks: () => hasPendingTasks(),
         bootstrapTaskLoop: (entry) => maybeBootstrapTaskLoop(entry),
         triggerHasEventSource,
+        emitLoopAutodeleted: (payload) => {
+            pi.events.emit("loops:autodeleted", payload);
+        },
+        emitTaskBacklogEmpty: (payload) => {
+            pi.events.emit("tasks:backlog_empty", payload);
+        },
         debug,
     });
     const flushPendingNotifications = notificationRuntime.flushPendingNotifications;
@@ -263,28 +308,43 @@ export default function (pi) {
         },
     });
     // ── Native task tools (only when pi-tasks is absent) ──
-    setTimeout(async () => {
+    // Only tool/command registration stays deferred: the tool names collide with
+    // pi-tasks and cannot be unregistered. The RPC server is already live (above).
+    const nativeTaskFallbackTimer = setTimeout(() => {
         if (tasksAvailable || nativeTasksRegistered)
             return;
-        nativeTaskStore = new TaskStore(resolveTaskStorePath(getScopeOptions(), _sessionId));
+        const taskStore = getOrCreateNativeTaskStore();
+        if (!taskStore)
+            return;
+        try {
+            registerTasksCommand({
+                pi,
+                getNativeTaskStore: () => nativeTaskStore,
+                evaluateTaskBacklog,
+                updateWidget: () => {
+                    widget.update();
+                },
+            });
+            registerNativeTaskTools({
+                pi,
+                taskStore,
+                evaluateTaskBacklog,
+                updateWidget: () => {
+                    widget.update();
+                },
+            });
+        }
+        catch (error) {
+            if (isStaleExtensionContextError(error)) {
+                debug("native task fallback skipped: extension context went stale");
+                return;
+            }
+            throw error;
+        }
         nativeTasksRegistered = true;
-        const taskStore = nativeTaskStore;
-        registerTasksCommand({
-            pi,
-            getNativeTaskStore: () => nativeTaskStore,
-            evaluateTaskBacklog,
-            updateWidget: () => {
-                widget.update();
-            },
-        });
-        registerNativeTaskTools({
-            pi,
-            taskStore,
-            evaluateTaskBacklog,
-            updateWidget: () => {
-                widget.update();
-            },
-        });
         debug("native task tools registered (pi-tasks not detected)");
     }, 6000);
+    pi.on("session_shutdown", () => {
+        clearTimeout(nativeTaskFallbackTimer);
+    });
 }

package/dist/loop-parse.js

@@ -21,6 +21,8 @@ const COMMON_INTERVALS = {
     86400: "0 0 * * *",
 };
 function roundToNearestCommon(seconds) {
+    // COMMON_INTERVALS is a non-empty const table, so keys[0] and
+    // COMMON_INTERVALS[best] below are true invariants, not runtime fallbacks.
     const keys = Object.keys(COMMON_INTERVALS).map(Number).sort((a, b) => a - b);
     let best = keys[0];
     for (const k of keys) {
@@ -55,8 +57,8 @@ export function parseInterval(input) {
     }
     const match = trimmed.match(/^(\d+)\s*(s|m|h|d)$/i);
     if (match) {
-        const value = parseInt(match[1], 10);
-        const unit = match[2].toLowerCase();
+        const value = parseInt(match[1] ?? "", 10);
+        const unit = (match[2] ?? "").toLowerCase();
         const totalSec = value * (UNIT_TO_CRON[unit] ?? 60);
         if (totalSec < 60) {
             return { cron: `*/1 * * * *`, description: `${totalSec} seconds (rounded to 1 minute)` };
@@ -70,6 +72,13 @@ export function cronToNextFire(cronExpr, fromDate = new Date()) {
     if (parts.length !== 5)
         throw new Error(`Invalid cron expression: ${cronExpr}`);
     const [minF, hourF, dayF, monthF, dowF] = parts;
+    if (minF === undefined ||
+        hourF === undefined ||
+        dayF === undefined ||
+        monthF === undefined ||
+        dowF === undefined) {
+        throw new Error(`Invalid cron expression: ${cronExpr}`);
+    }
     const now = new Date(fromDate);
     now.setSeconds(0, 0);
     for (let minutesAdvanced = 1; minutesAdvanced < 525600; minutesAdvanced++) {
@@ -96,7 +105,7 @@ function cronFieldMatches(field, value) {
         if (part === "*")
             return true;
         if (part.includes("/")) {
-            const [range, stepStr] = part.split("/");
+            const [range = "", stepStr = ""] = part.split("/");
             const step = parseInt(stepStr, 10);
             let rangeMin;
             let rangeMax;
@@ -105,7 +114,7 @@ function cronFieldMatches(field, value) {
                 rangeMax = 59;
             }
             else if (range.includes("-")) {
-                const [minS, maxS] = range.split("-");
+                const [minS = "", maxS = ""] = range.split("-");
                 rangeMin = parseInt(minS, 10);
                 rangeMax = parseInt(maxS, 10);
             }
@@ -121,7 +130,7 @@ function cronFieldMatches(field, value) {
             continue;
         }
         if (part.includes("-")) {
-            const [minS, maxS] = part.split("-");
+            const [minS = "", maxS = ""] = part.split("-");
             const min = parseInt(minS, 10);
             const max = parseInt(maxS, 10);
             if (value >= min && value <= max)

package/dist/monitor-manager.d.ts

@@ -1,11 +1,14 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { MonitorEntry, MonitorProcess } from "./types.js";
+export type SpawnFn = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
 export declare class MonitorManager {
     private pi;
     private processes;
     private nextId;
     private onChange;
-    constructor(pi: ExtensionAPI);
+    private spawnFn;
+    constructor(pi: ExtensionAPI, spawnFn?: SpawnFn);
     /**
      * Register a callback fired when a monitor's status changes or it is pruned
      * (e.g. autonomous completion/error/stop/prune with no tool call). Used to

package/dist/monitor-manager.js

@@ -1,12 +1,14 @@
-import { spawn } from "node:child_process";
+import { spawn as nodeSpawn } from "node:child_process";
 import { reduceMonitorState, } from "./monitor-reducer.js";
 export class MonitorManager {
     pi;
     processes = new Map();
     nextId = 1;
     onChange;
-    constructor(pi) {
+    spawnFn;
+    constructor(pi, spawnFn) {
         this.pi = pi;
+        this.spawnFn = spawnFn ?? ((cmd, args, opts) => nodeSpawn(cmd, args, opts));
     }
     /**
      * Register a callback fired when a monitor's status changes or it is pruned
@@ -76,7 +78,7 @@ export class MonitorManager {
         const id = String(this.nextId - 1);
         const entry = result.state.monitorsById[id];
         const abortController = new AbortController();
-        const child = spawn("sh", ["-c", command], {
+        const child = this.spawnFn("sh", ["-c", command], {
             stdio: ["ignore", "pipe", "pipe"],
             signal: abortController.signal,
             env: { ...process.env },

package/dist/reducer-backed-store.d.ts

@@ -25,7 +25,7 @@ export interface ReducerBackedStoreConfig<TEntry, TState, TEvent, TData> {
 }
 /**
  * Shared persistence + reducer-dispatch machinery for the file-backed entity
- * stores (loops, tasks, goals). Owns file locking, signature-gated load, atomic
+ * stores (loops, tasks). Owns file locking, signature-gated load, atomic
  * save, and reducer application; subclasses add only their entity-specific
  * command methods.
  *

package/dist/reducer-backed-store.js

@@ -48,7 +48,7 @@ function isProcessRunning(pid) {
 }
 /**
  * Shared persistence + reducer-dispatch machinery for the file-backed entity
- * stores (loops, tasks, goals). Owns file locking, signature-gated load, atomic
+ * stores (loops, tasks). Owns file locking, signature-gated load, atomic
  * save, and reducer application; subclasses add only their entity-specific
  * command methods.
  *

package/dist/rpc/channels.d.ts

@@ -0,0 +1,73 @@
+/** Cross-extension RPC channels served by a tasks provider (pi-tasks or pi-loop native). */
+export declare const TASKS_RPC: {
+    readonly ping: "tasks:rpc:ping";
+    readonly create: "tasks:rpc:create";
+    readonly update: "tasks:rpc:update";
+    readonly pending: "tasks:rpc:pending";
+    readonly clean: "tasks:rpc:clean";
+};
+/** Cross-extension RPC channels served by @tintinweb/pi-subagents. */
+export declare const SUBAGENTS_RPC: {
+    readonly ping: "subagents:rpc:ping";
+    readonly spawn: "subagents:rpc:spawn";
+    readonly stop: "subagents:rpc:stop";
+};
+/** Broadcast (fire-and-forget) task lifecycle events. */
+export declare const TASK_EVENTS: {
+    readonly ready: "tasks:ready";
+    readonly created: "tasks:created";
+    readonly started: "tasks:started";
+    readonly completed: "tasks:completed";
+    readonly reopened: "tasks:reopened";
+    readonly updated: "tasks:updated";
+    readonly deleted: "tasks:deleted";
+};
+export declare function replyChannel(channel: string, requestId: string): string;
+export type TaskStatusWire = "pending" | "in_progress" | "completed";
+export interface TaskEntryWire {
+    id: string;
+    subject: string;
+    description: string;
+    status: TaskStatusWire;
+    createdAt: number;
+    updatedAt: number;
+    completedAt?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateTaskParams {
+    subject: string;
+    description: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateTaskReply {
+    id: string;
+    task: TaskEntryWire;
+}
+export interface UpdateTaskParams {
+    id: string;
+    status?: TaskStatusWire;
+    subject?: string;
+    description?: string;
+}
+export interface UpdateTaskReply {
+    task: TaskEntryWire;
+}
+export interface PendingReply {
+    pending: number;
+}
+export interface CleanReply {
+    pruned: number;
+}
+export interface PingReply {
+    version: number;
+    /** Identifies which extension answered; lets a provider ignore its own reply. */
+    provider?: string;
+}
+export interface SpawnParams {
+    type: string;
+    prompt: string;
+    options?: Record<string, unknown>;
+}
+export interface SpawnReply {
+    id: string;
+}

package/dist/rpc/channels.js

@@ -0,0 +1,30 @@
+// VENDORED MODULE — canonical copy shared verbatim by pi-loop and pi-orca.
+// If you edit this file, copy it to the sibling repo and bump VENDOR_REV.
+// VENDOR_REV: 1
+/** Cross-extension RPC channels served by a tasks provider (pi-tasks or pi-loop native). */
+export const TASKS_RPC = {
+    ping: "tasks:rpc:ping",
+    create: "tasks:rpc:create",
+    update: "tasks:rpc:update",
+    pending: "tasks:rpc:pending",
+    clean: "tasks:rpc:clean",
+};
+/** Cross-extension RPC channels served by @tintinweb/pi-subagents. */
+export const SUBAGENTS_RPC = {
+    ping: "subagents:rpc:ping",
+    spawn: "subagents:rpc:spawn",
+    stop: "subagents:rpc:stop",
+};
+/** Broadcast (fire-and-forget) task lifecycle events. */
+export const TASK_EVENTS = {
+    ready: "tasks:ready",
+    created: "tasks:created",
+    started: "tasks:started",
+    completed: "tasks:completed",
+    reopened: "tasks:reopened",
+    updated: "tasks:updated",
+    deleted: "tasks:deleted",
+};
+export function replyChannel(channel, requestId) {
+    return `${channel}:reply:${requestId}`;
+}

package/dist/rpc/cross-extension-rpc.d.ts

@@ -0,0 +1,59 @@
+import { type PingReply } from "./channels.js";
+/**
+ * Cross-extension request/reply over the in-process pi event bus.
+ *
+ * Wire contract (matches the pi-mono convention used by @tintinweb/pi-subagents):
+ *   request:  emit(channel, { requestId, ...params })
+ *   reply:    emit(`${channel}:reply:${requestId}`, RpcReply)
+ */
+export declare const PROTOCOL_VERSION = 2;
+export type RpcReply<T = void> = {
+    success: true;
+    data?: T;
+} | {
+    success: false;
+    error: string;
+};
+export declare class RpcError extends Error {
+    readonly channel: string;
+    readonly timedOut: boolean;
+    constructor(channel: string, message: string, timedOut?: boolean);
+}
+/** Minimal event-bus surface — satisfied by pi.events. */
+export interface RpcEventBus {
+    on(event: string, handler: (data: unknown) => void): () => void;
+    emit(event: string, data: unknown): void;
+}
+/**
+ * Call a remote handler and await its reply.
+ *
+ * Rejects with RpcError on a failure envelope or on timeout (timedOut=true).
+ * Callers that treat failure as "fall back" wrap this in try/catch at the
+ * layer that knows the fallback — the RPC layer itself never returns sentinels.
+ */
+export declare function rpcCall<T = void>(bus: RpcEventBus, channel: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+/**
+ * Detection probe: resolves undefined when nobody answers the ping channel.
+ * Absence of a provider is expected, not an error.
+ *
+ * First reply wins. If the probing extension also serves this channel, its
+ * own reply will settle the probe — in that case listen on the reply channel
+ * directly for the full window and filter by PingReply.provider instead.
+ */
+export declare function rpcProbe(bus: RpcEventBus, pingChannel: string, timeoutMs?: number): Promise<PingReply | undefined>;
+export interface HandleRpcOptions {
+    /**
+     * When false, the handler is a silent no-op: another extension owns the
+     * channel and will reply; emitting a failure here would race its reply.
+     */
+    enabled?: () => boolean;
+    debug?: (...args: unknown[]) => void;
+}
+/**
+ * Register a server handler for one RPC channel. Returns the unsubscribe fn.
+ *
+ * Malformed requests get a failure reply, never a silent drop — the only
+ * silent case is a missing requestId, which leaves no reply address.
+ * A thrown/rejected fn becomes a failure envelope.
+ */
+export declare function handleRpc<P extends object, R = unknown>(bus: RpcEventBus, channel: string, fn: (params: P) => R | Promise<R>, opts?: HandleRpcOptions): () => void;