@trevonistrevon/pi-loop 0.5.9 → 0.6.1

package/dist/index.js

@@ -4,13 +4,14 @@
  * Tools:
  *   LoopCreate    — Create a scheduled or event-triggered re-wake loop
  *   LoopList      — List all active loops with status and next-fire times
+ *   LoopUpdate    — Continue, pause, or complete a dynamic goal loop
  *   LoopDelete    — Delete or pause a loop by ID
  *   MonitorCreate — Start a background command that streams output via pi events
  *   MonitorList   — List running monitors
  *   MonitorStop   — Stop a running monitor
  *
  * Commands:
- *   /loop    — Schedule or manage re-wake loops: /loop [interval] [prompt]
+ *   /loop    — Schedule or manage re-wake loops, including /loop <goal>
  *   /tasks   — View or manage native fallback tasks when pi-tasks is absent
  */
 import { registerLoopCommand } from "./commands/loop-command.js";
@@ -18,6 +19,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";
@@ -53,24 +55,46 @@ 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");
-        const next = tasks.find(t => t.status === "pending");
-        const focus = active
-            ? `active: ${active.subject.slice(0, 50)}`
-            : next
-                ? `next: ${next.subject.slice(0, 50)}`
+        let count = 0;
+        let activeSubject;
+        let nextSubject;
+        for (const task of nativeTaskStore.list()) {
+            if (task.status === "in_progress") {
+                count++;
+                activeSubject ??= task.subject;
+            }
+            else if (task.status === "pending") {
+                count++;
+                nextSubject ??= task.subject;
+            }
+        }
+        const focus = activeSubject
+            ? `active: ${activeSubject.slice(0, 50)}`
+            : nextSubject
+                ? `next: ${nextSubject.slice(0, 50)}`
                 : undefined;
-        return { count: tasks.length, focusText: focus };
+        return { count, focusText: focus };
     });
     scheduler = new CronScheduler(store, onLoopFire);
     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,
@@ -86,6 +110,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();
@@ -144,6 +191,9 @@ export default function (pi) {
         deleteLoop: (id) => {
             store.delete(id);
         },
+        recordDeletionTombstone: (id, tombstone) => {
+            store.recordDeletionTombstone(id, tombstone);
+        },
         addTrigger: (entry) => {
             triggerSystem.add(entry);
         },
@@ -156,6 +206,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;
@@ -171,6 +227,16 @@ export default function (pi) {
             return;
         }
         store.fire(entry.id);
+        const firedAt = Date.now();
+        const firedEntry = entry.trigger.type === "dynamic"
+            ? store.updateDynamic(entry.id, {
+                dynamic: {
+                    awaitingUpdate: true,
+                    nextWakeAt: undefined,
+                    lastUpdatedAt: firedAt,
+                },
+            }) ?? entry
+            : entry;
         if (entry.autoTask) {
             autoCreateTask(entry).then((taskId) => {
                 if (taskId)
@@ -178,13 +244,14 @@ export default function (pi) {
             });
         }
         pi.events.emit("loop:fire", {
-            loopId: entry.id,
-            prompt: entry.prompt,
-            trigger: entry.trigger,
-            timestamp: Date.now(),
-            readOnly: entry.readOnly,
-            recurring: entry.recurring,
-            autoTask: entry.autoTask,
+            loopId: firedEntry.id,
+            prompt: firedEntry.prompt,
+            trigger: firedEntry.trigger,
+            timestamp: firedAt,
+            readOnly: firedEntry.readOnly,
+            recurring: firedEntry.recurring,
+            autoTask: firedEntry.autoTask,
+            dynamic: firedEntry.dynamic,
         });
     }
     // ── Session lifecycle ──
@@ -266,10 +333,14 @@ export default function (pi) {
         },
     });
     // ── Native task tools (only when pi-tasks is absent) ──
+    // 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;
-        const taskStore = new TaskStore(resolveTaskStorePath(getScopeOptions(), _sessionId));
+        const taskStore = getOrCreateNativeTaskStore();
+        if (!taskStore)
+            return;
         try {
             registerTasksCommand({
                 pi,
@@ -295,7 +366,6 @@ export default function (pi) {
             }
             throw error;
         }
-        nativeTaskStore = taskStore;
         nativeTasksRegistered = true;
         debug("native task tools registered (pi-tasks not detected)");
     }, 6000);

package/dist/loop-format.d.ts

@@ -0,0 +1,3 @@
+import type { Trigger } from "./types.js";
+export type TriggerFormatStyle = "command" | "create" | "list" | "notification";
+export declare function formatTrigger(trigger: Trigger | string, style?: TriggerFormatStyle): string;

package/dist/loop-format.js

@@ -0,0 +1,20 @@
+export function formatTrigger(trigger, style = "list") {
+    if (typeof trigger === "string")
+        return trigger;
+    if (trigger.type === "cron") {
+        return style === "create" || style === "notification"
+            ? `schedule: ${trigger.schedule}`
+            : `cron: ${trigger.schedule}`;
+    }
+    if (trigger.type === "event")
+        return `event: ${trigger.source}`;
+    if (trigger.type === "dynamic")
+        return "dynamic";
+    if (style === "command")
+        return `hybrid: ${trigger.cron}`;
+    if (style === "create")
+        return `hybrid: cron ${trigger.cron} + event ${trigger.event.source}`;
+    if (style === "notification")
+        return "hybrid";
+    return `hybrid: ${trigger.cron} + ${trigger.event.source}`;
+}

package/dist/loop-parse.d.ts

@@ -1,3 +1,4 @@
+export declare function isValidCronExpression(expr: string): boolean;
 export declare function parseInterval(input: string): {
     cron: string;
     description: string;

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) {
@@ -48,15 +50,59 @@ function isFullCron(expr) {
     const parts = expr.trim().split(/\s+/);
     return parts.length === 5;
 }
+function parseCronNumber(input, min, max) {
+    if (!/^\d+$/.test(input))
+        return undefined;
+    const value = Number.parseInt(input, 10);
+    return value >= min && value <= max ? value : undefined;
+}
+function isValidCronField(field, min, max) {
+    return field.split(",").every((part) => {
+        const [base, step, extra] = part.split("/");
+        if (extra !== undefined || base === undefined)
+            return false;
+        if (step !== undefined && (parseCronNumber(step, 1, max - min + 1) === undefined))
+            return false;
+        if (base === "*")
+            return true;
+        const range = base.split("-");
+        if (range.length === 1)
+            return step === undefined && parseCronNumber(base, min, max) !== undefined;
+        if (range.length !== 2)
+            return false;
+        const start = parseCronNumber(range[0] ?? "", min, max);
+        const end = parseCronNumber(range[1] ?? "", min, max);
+        return start !== undefined && end !== undefined && start <= end;
+    });
+}
+export function isValidCronExpression(expr) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return false;
+    const ranges = [
+        [0, 59],
+        [0, 23],
+        [1, 31],
+        [1, 12],
+        [0, 6],
+    ];
+    return fields.every((field, index) => {
+        const range = ranges[index];
+        return range !== undefined && isValidCronField(field, range[0], range[1]);
+    });
+}
 export function parseInterval(input) {
     const trimmed = input.trim();
     if (isFullCron(trimmed)) {
+        if (!isValidCronExpression(trimmed)) {
+            throw new Error(`Invalid cron expression: ${trimmed}`);
+        }
         return { cron: trimmed, description: `cron: ${trimmed}` };
     }
     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)` };
@@ -67,9 +113,16 @@ export function parseInterval(input) {
 }
 export function cronToNextFire(cronExpr, fromDate = new Date()) {
     const parts = cronExpr.trim().split(/\s+/);
-    if (parts.length !== 5)
+    if (!isValidCronExpression(cronExpr))
         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 +149,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 +158,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 +174,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/loop-reducer.d.ts

@@ -1,4 +1,4 @@
-import type { LoopEntry, Trigger } from "./types.js";
+import type { DynamicLoopState, LoopEntry, Trigger } from "./types.js";
 export declare const MAX_LOOP_EXPIRY_MS: number;
 /**
  * Whether a loop has reached its fire cap. Single source of truth for the
@@ -26,6 +26,7 @@ export type LoopReducerEvent = {
         taskBacklog?: boolean;
         readOnly?: boolean;
         maxFires?: number;
+        dynamic?: Partial<DynamicLoopState>;
     };
 } | {
     type: "LOOP_PAUSED" | "LOOP_RESUMED" | "LOOP_FIRED" | "LOOP_DELETED" | "LOOP_MAX_FIRES_REACHED" | "LOOP_BACKLOG_EMPTY";
@@ -46,6 +47,17 @@ export type LoopReducerEvent = {
         id: string;
         reason: "expires_at" | "resume_event_stale" | "already_completed_monitor";
     };
+} | {
+    type: "LOOP_DYNAMIC_UPDATED";
+    at: number;
+    source: ReducerSource;
+    entityType?: "loop";
+    entityId?: string;
+    payload: {
+        id: string;
+        prompt?: string;
+        dynamic: Partial<DynamicLoopState>;
+    };
 };
 export type LoopReducerEffect = {
     type: "PERSIST_LOOP";

package/dist/loop-reducer.js

@@ -32,6 +32,18 @@ export function reduceLoopState(state, event) {
             readOnly: event.payload.readOnly,
             maxFires: event.payload.maxFires,
             fireCount: 0,
+            dynamic: event.payload.trigger.type === "dynamic" || event.payload.dynamic
+                ? {
+                    goal: event.payload.dynamic?.goal ?? event.payload.prompt,
+                    state: event.payload.dynamic?.state,
+                    metrics: event.payload.dynamic?.metrics,
+                    doneCriteria: event.payload.dynamic?.doneCriteria,
+                    iteration: event.payload.dynamic?.iteration ?? 0,
+                    nextWakeAt: event.payload.dynamic?.nextWakeAt,
+                    awaitingUpdate: event.payload.dynamic?.awaitingUpdate ?? false,
+                    lastUpdatedAt: event.payload.dynamic?.lastUpdatedAt ?? event.at,
+                }
+                : undefined,
         };
         next.loopsById[id] = loop;
         return {
@@ -68,6 +80,20 @@ export function reduceLoopState(state, event) {
         loop.fireCount = (loop.fireCount ?? 0) + 1;
         loop.updatedAt = event.at;
     }
+    if (event.type === "LOOP_DYNAMIC_UPDATED") {
+        loop.prompt = event.payload.prompt ?? loop.prompt;
+        loop.dynamic = {
+            goal: event.payload.dynamic.goal ?? loop.dynamic?.goal ?? loop.prompt,
+            state: event.payload.dynamic.state ?? loop.dynamic?.state,
+            metrics: event.payload.dynamic.metrics ?? loop.dynamic?.metrics,
+            doneCriteria: event.payload.dynamic.doneCriteria ?? loop.dynamic?.doneCriteria,
+            iteration: event.payload.dynamic.iteration ?? loop.dynamic?.iteration ?? 0,
+            nextWakeAt: "nextWakeAt" in event.payload.dynamic ? event.payload.dynamic.nextWakeAt : loop.dynamic?.nextWakeAt,
+            awaitingUpdate: event.payload.dynamic.awaitingUpdate ?? loop.dynamic?.awaitingUpdate ?? false,
+            lastUpdatedAt: event.payload.dynamic.lastUpdatedAt ?? event.at,
+        };
+        loop.updatedAt = event.at;
+    }
     next.loopsById[id] = loop;
     return {
         state: next,

package/dist/monitor-manager.js

@@ -246,7 +246,7 @@ export class MonitorManager {
         const bp = this.processes.get(id);
         if (!bp)
             return false;
-        if (bp.entry.status === "completed") {
+        if (bp.entry.status === "completed" || bp.entry.status === "error") {
             callback();
             return true;
         }

package/dist/notification-reducer.d.ts

@@ -1,3 +1,4 @@
+import type { DynamicLoopState } from "./types.js";
 type ReducerSource = "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
 export interface ReducerNotification {
     key: string;
@@ -8,6 +9,7 @@ export interface ReducerNotification {
     recurring?: boolean;
     autoTask?: boolean;
     readOnly?: boolean;
+    dynamic?: DynamicLoopState;
 }
 export interface NotificationReducerState {
     notificationsByKey: Record<string, ReducerNotification>;

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;