@pinet/slack-bridge 0.1.0

package/dist/pinet-home-tabs.js

@@ -0,0 +1,101 @@
+import { probeGitBranch } from "./git-metadata.js";
+import { publishSlackHomeTab, renderBrokerControlPlaneHomeTabView, renderStandalonePinetHomeTabView, } from "./home-tab.js";
+function buildHomeTabPublishFailureMessage(formatError, err) {
+    return `Pinet Home tab publish failed: ${formatError(err)}`;
+}
+function getConnectedState(deps) {
+    const mode = deps.getRuntimeMode();
+    const brokerHomeTabs = deps.getBrokerHomeTabs();
+    if (mode === "broker") {
+        return brokerHomeTabs.isConnected();
+    }
+    if (mode === "follower") {
+        return deps.isFollowerConnected();
+    }
+    if (mode === "single") {
+        return deps.isSinglePlayerConnected();
+    }
+    return false;
+}
+export function createPinetHomeTabs(deps) {
+    function reportHomeTabPublishFailure(ctx, err) {
+        const brokerHomeTabs = deps.getBrokerHomeTabs();
+        const homeTabMessage = buildHomeTabPublishFailureMessage(deps.formatError, err);
+        if (homeTabMessage !== brokerHomeTabs.getLastHomeTabError()) {
+            ctx.ui.notify(homeTabMessage, "warning");
+        }
+        brokerHomeTabs.setLastHomeTabError(homeTabMessage);
+    }
+    async function refreshBrokerControlPlaneHomeTabs(ctx, snapshot, refreshedAt, userIds = deps.getBrokerHomeTabs().getHomeTabViewerIds()) {
+        const botToken = deps.getBotToken();
+        if (!botToken || userIds.length === 0) {
+            return;
+        }
+        const brokerHomeTabs = deps.getBrokerHomeTabs();
+        brokerHomeTabs.setLastHomeTabSnapshot(snapshot);
+        let hadError = false;
+        for (const userId of userIds) {
+            try {
+                await publishSlackHomeTab({
+                    slack: deps.slack,
+                    token: botToken,
+                    userId,
+                    view: renderBrokerControlPlaneHomeTabView(snapshot),
+                });
+            }
+            catch (err) {
+                hadError = true;
+                reportHomeTabPublishFailure(ctx, err);
+            }
+        }
+        if (!hadError) {
+            brokerHomeTabs.setLastHomeTabError(null);
+        }
+        brokerHomeTabs.setLastHomeTabRefreshAt(refreshedAt);
+    }
+    async function publishCurrentPinetHomeTab(userId, ctx, openedAt = new Date().toISOString()) {
+        const botToken = deps.getBotToken();
+        if (!botToken) {
+            return;
+        }
+        const brokerHomeTabs = deps.getBrokerHomeTabs();
+        if (brokerHomeTabs.isConnected() && deps.getBrokerRole() === "broker") {
+            if (await brokerHomeTabs.publishCurrentHomeTabSafely(userId, ctx, openedAt)) {
+                return;
+            }
+        }
+        const currentBranch = deps.getCurrentBranch
+            ? await deps.getCurrentBranch()
+            : ((await probeGitBranch(process.cwd())) ?? null);
+        await publishSlackHomeTab({
+            slack: deps.slack,
+            token: botToken,
+            userId,
+            view: renderStandalonePinetHomeTabView({
+                agentName: deps.getAgentName(),
+                agentEmoji: deps.getAgentEmoji(),
+                connected: getConnectedState(deps),
+                mode: deps.getRuntimeMode(),
+                activeThreads: deps.getActiveThreads(),
+                pendingInbox: deps.getPendingInboxCount(),
+                currentBranch,
+                defaultChannel: deps.getDefaultChannel() ?? null,
+            }),
+        });
+        brokerHomeTabs.setLastHomeTabError(null);
+    }
+    async function publishCurrentPinetHomeTabSafely(userId, ctx, openedAt = new Date().toISOString()) {
+        try {
+            await publishCurrentPinetHomeTab(userId, ctx, openedAt);
+        }
+        catch (err) {
+            reportHomeTabPublishFailure(ctx, err);
+        }
+    }
+    return {
+        refreshBrokerControlPlaneHomeTabs,
+        reportHomeTabPublishFailure,
+        publishCurrentPinetHomeTab,
+        publishCurrentPinetHomeTabSafely,
+    };
+}

package/dist/pinet-maintenance-delivery.d.ts

@@ -0,0 +1,22 @@
+export interface PinetMaintenanceDeliveryAgentRecord {
+    id: string;
+    name?: string;
+    emoji?: string;
+}
+export interface PinetMaintenanceDeliveryBrokerDbPort {
+    getAgentById: (agentId: string) => PinetMaintenanceDeliveryAgentRecord | null;
+    getThread: (threadId: string) => unknown;
+    createThread: (threadId: string, source: string, channel: string, owner: string) => void;
+    insertMessage: (threadId: string, source: string, direction: "outbound" | "inbound", sender: string, body: string, recipients: string[], metadata?: Record<string, unknown>) => void;
+}
+export interface PinetMaintenanceDeliveryDeps {
+    getActiveBrokerDb: () => PinetMaintenanceDeliveryBrokerDbPort | null;
+    getActiveBrokerSelfId: () => string | null;
+    isIdle: () => boolean;
+    sendUserMessage: (body: string) => void;
+}
+export interface PinetMaintenanceDelivery {
+    sendBrokerMaintenanceMessage: (targetAgentId: string, body: string) => void;
+    trySendBrokerFollowUp: (body: string, onDelivered: () => void) => void;
+}
+export declare function createPinetMaintenanceDelivery(deps: PinetMaintenanceDeliveryDeps): PinetMaintenanceDelivery;

package/dist/pinet-maintenance-delivery.js

@@ -0,0 +1,45 @@
+function formatBrokerOnlyMaintenanceMessage(target, body) {
+    const label = [target.emoji, target.name].filter(Boolean).join(" ") || target.id;
+    return [
+        `RALPH broker-only maintenance for ${label} (${target.id}):`,
+        "",
+        "Original worker-directed maintenance note (not delivered to the worker/follower Pi queue):",
+        body,
+    ].join("\n");
+}
+export function createPinetMaintenanceDelivery(deps) {
+    function sendBrokerMaintenanceMessage(targetAgentId, body) {
+        const db = deps.getActiveBrokerDb();
+        const selfId = deps.getActiveBrokerSelfId();
+        if (!db || !selfId)
+            return;
+        const target = db.getAgentById(targetAgentId);
+        if (!target)
+            return;
+        const threadId = `a2a:${selfId}:${selfId}`;
+        if (!db.getThread(threadId)) {
+            db.createThread(threadId, "agent", "", selfId);
+        }
+        db.insertMessage(threadId, "agent", "outbound", selfId, formatBrokerOnlyMaintenanceMessage(target, body), [selfId], {
+            kind: "ralph_loop_nudge",
+            targetAgentId: target.id,
+            brokerOnly: true,
+        });
+    }
+    function trySendBrokerFollowUp(body, onDelivered) {
+        if (!deps.isIdle()) {
+            return;
+        }
+        try {
+            deps.sendUserMessage(body);
+            onDelivered();
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    return {
+        sendBrokerMaintenanceMessage,
+        trySendBrokerFollowUp,
+    };
+}

package/dist/pinet-mesh-ops.d.ts

@@ -0,0 +1,97 @@
+import { type AgentMessageStorage } from "./broker/agent-messaging.js";
+import type { AgentInfo, TaskAssignmentInfo, TaskAssignmentKind } from "./broker/types.js";
+import type { ActivityLogEntry } from "./activity-log.js";
+export interface PinetMeshOpsAgentRecord {
+    emoji: string;
+    name: string;
+    id: string;
+    pid?: number;
+    status: "working" | "idle";
+    metadata: Record<string, unknown> | null;
+    lastHeartbeat: string;
+    lastSeen?: string;
+    disconnectedAt?: string | null;
+    resumableUntil?: string | null;
+    outboundCount?: number;
+    pendingInboxCount?: number;
+}
+export interface PinetMeshOpsRecordedAssignment {
+    issueNumber: number;
+    branch: string | null;
+}
+export interface PinetMeshOpsTransferableThread {
+    threadId: string;
+    source?: string;
+    channel?: string;
+}
+export interface PinetMeshOpsBrokerDbPort extends AgentMessageStorage {
+    getAllAgents: () => AgentInfo[];
+    getPendingInboxCount: (agentId: string) => number;
+    getThread: (threadId: string) => PinetMeshOpsTransferableThread | null;
+    transferThreadOwnership: (threadId: string, ownerAgent: string) => {
+        reassignedInboxCount: number;
+        updatedMessageCount: number;
+    };
+    recordTaskAssignment: (agentId: string, issueNumber: number, branch: string | null, threadId: string, sourceMessageId: number, options?: {
+        repoOwner?: string | null;
+        repoName?: string | null;
+        repoRoot?: string | null;
+        taskKind?: TaskAssignmentKind;
+    }) => TaskAssignmentInfo;
+    scheduleWakeup: (agentId: string, message: string, fireAt: string) => {
+        id: number;
+        fireAt: string;
+    } | Promise<{
+        id: number;
+        fireAt: string;
+    }>;
+}
+export interface PinetMeshOpsFollowerAgentRecord extends Omit<PinetMeshOpsAgentRecord, "status"> {
+    status?: PinetMeshOpsAgentRecord["status"] | null;
+}
+export interface PinetMeshOpsFollowerClientPort {
+    sendAgentMessage: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<number>;
+    scheduleWakeup: (fireAt: string, message: string) => Promise<{
+        id: number;
+        fireAt: string;
+    }>;
+    listAgents: (includeGhosts: boolean) => Promise<PinetMeshOpsFollowerAgentRecord[]>;
+}
+export interface PinetMeshOpsDeps {
+    getPinetEnabled: () => boolean;
+    getBrokerRole: () => "broker" | "follower" | null;
+    getActiveBrokerDb: () => PinetMeshOpsBrokerDbPort | null;
+    getActiveBrokerSelfId: () => string | null;
+    getAgentName: () => string;
+    getFollowerClient: () => PinetMeshOpsFollowerClientPort | null;
+    formatTrackedAgent: (agentId: string) => string;
+    logActivity: (entry: ActivityLogEntry) => void;
+}
+export interface PinetMeshOps {
+    sendPinetAgentMessage: (target: string, body: string, metadata?: Record<string, unknown>) => Promise<{
+        messageId: number;
+        target: string;
+        transferredThreadId?: string;
+        transferredThreadChannel?: string;
+    }>;
+    sendPinetBroadcastMessage: (channel: string, body: string) => {
+        channel: string;
+        messageIds: number[];
+        recipients: string[];
+    };
+    scheduleBrokerWakeup: (fireAt: string, message: string) => Promise<{
+        id: number;
+        fireAt: string;
+    }>;
+    scheduleFollowerWakeup: (fireAt: string, message: string) => Promise<{
+        id: number;
+        fireAt: string;
+    }>;
+    listBrokerAgents: () => PinetMeshOpsAgentRecord[];
+    listFollowerAgents: (includeGhosts: boolean) => Promise<PinetMeshOpsAgentRecord[]>;
+}
+export declare function parseGitHubRemoteRepo(remoteUrl: string): {
+    repoOwner: string;
+    repoName: string;
+} | null;
+export declare function createPinetMeshOps(deps: PinetMeshOpsDeps): PinetMeshOps;

package/dist/pinet-mesh-ops.js

@@ -0,0 +1,266 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizeOutgoingPinetControlMessage } from "./helpers.js";
+import { dispatchBroadcastAgentMessage, dispatchDirectAgentMessage, isBroadcastChannelTarget, } from "./broker/agent-messaging.js";
+import { extractTaskAssignmentsFromMessage } from "./task-assignments.js";
+const execFileAsync = promisify(execFile);
+function prepareOutgoingPinetAgentMessage(body, metadata) {
+    const control = normalizeOutgoingPinetControlMessage(body, metadata);
+    if (control) {
+        return {
+            body: control.body,
+            metadata: control.metadata,
+        };
+    }
+    return { body, metadata };
+}
+function getThreadOwnershipTransferMetadata(metadata) {
+    const transfer = metadata?.threadOwnershipTransfer;
+    return transfer && typeof transfer === "object" && !Array.isArray(transfer)
+        ? transfer
+        : null;
+}
+function getThreadOwnershipTransferId(metadata) {
+    const threadId = getThreadOwnershipTransferMetadata(metadata)?.threadId;
+    return typeof threadId === "string" && threadId.trim().length > 0 ? threadId.trim() : null;
+}
+function appendSlackThreadTransferNotice(body, threadId, channel) {
+    return [
+        body,
+        "",
+        "Transferred Slack thread context:",
+        `- thread_ts: ${threadId}`,
+        `- channel: ${channel}`,
+        `- To report directly in the transferred Slack thread, use slack_send with thread_ts ${threadId}; the channel is already recorded in Pinet.`,
+        "- If slack_send says the thread is already owned by another agent, ask the broker to inspect ownership and transfer it again.",
+    ].join("\n");
+}
+export function parseGitHubRemoteRepo(remoteUrl) {
+    const match = remoteUrl
+        .trim()
+        .match(/^(?:(?:https?:\/\/|ssh:\/\/)(?:[^@/\s]+@)?|(?:[^@/\s]+@)?)github(?:\.com|[-.][^/:]+)?[:/]([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/i);
+    if (!match?.[1] || !match[2]) {
+        return null;
+    }
+    return { repoOwner: match[1], repoName: match[2] };
+}
+async function resolveCurrentGitHubRepo() {
+    try {
+        const [rootResult, remoteResult] = await Promise.all([
+            execFileAsync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" }),
+            execFileAsync("git", ["remote", "get-url", "origin"], { encoding: "utf-8" }),
+        ]);
+        const remoteRepo = parseGitHubRemoteRepo(String(remoteResult.stdout).trim());
+        return {
+            repoOwner: remoteRepo?.repoOwner ?? null,
+            repoName: remoteRepo?.repoName ?? null,
+            repoRoot: String(rootResult.stdout).trim() || null,
+        };
+    }
+    catch {
+        return { repoOwner: null, repoName: null, repoRoot: null };
+    }
+}
+export function createPinetMeshOps(deps) {
+    async function sendPinetAgentMessage(targetRef, body, metadata) {
+        if (!deps.getPinetEnabled()) {
+            throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
+        }
+        if (isBroadcastChannelTarget(targetRef)) {
+            throw new Error("Broadcast channels are broker-only. Send the request to the broker instead.");
+        }
+        const outgoing = prepareOutgoingPinetAgentMessage(body, metadata);
+        const finalBody = outgoing.body;
+        const finalMetadata = outgoing.metadata;
+        if (deps.getBrokerRole() === "broker") {
+            const db = deps.getActiveBrokerDb();
+            const selfId = deps.getActiveBrokerSelfId();
+            if (!db || !selfId) {
+                throw new Error("Broker agent identity is unavailable.");
+            }
+            const transferThreadId = getThreadOwnershipTransferId(finalMetadata);
+            const transferThread = transferThreadId ? db.getThread(transferThreadId) : null;
+            if (transferThreadId && !transferThread) {
+                throw new Error(`Cannot transfer unknown thread ${transferThreadId}.`);
+            }
+            if (transferThread && (transferThread.source !== "slack" || !transferThread.channel)) {
+                throw new Error(`Thread ${transferThreadId} is not a transferable Slack thread.`);
+            }
+            const transferThreadChannel = transferThread?.channel;
+            const transferMetadata = getThreadOwnershipTransferMetadata(finalMetadata);
+            const dispatchMetadata = transferThreadId
+                ? {
+                    ...(finalMetadata ?? {}),
+                    threadOwnershipTransfer: {
+                        ...(transferMetadata ?? {}),
+                        mode: "transfer",
+                        threadId: transferThreadId,
+                        source: "slack",
+                        channel: transferThreadChannel,
+                    },
+                }
+                : finalMetadata;
+            const dispatchBody = transferThreadId && transferThreadChannel
+                ? appendSlackThreadTransferNotice(finalBody, transferThreadId, transferThreadChannel)
+                : finalBody;
+            const result = dispatchDirectAgentMessage(db, {
+                senderAgentId: selfId,
+                senderAgentName: deps.getAgentName(),
+                target: targetRef,
+                body: dispatchBody,
+                metadata: dispatchMetadata,
+            });
+            if (transferThreadId) {
+                const transfer = db.transferThreadOwnership(transferThreadId, result.target.id);
+                deps.logActivity({
+                    kind: "thread_transfer",
+                    level: "actions",
+                    title: "Thread ownership transferred",
+                    summary: `Transferred ${transferThreadId} to ${deps.formatTrackedAgent(result.target.id)}.`,
+                    fields: [
+                        { label: "Worker", value: deps.formatTrackedAgent(result.target.id) },
+                        { label: "Thread", value: transferThreadId },
+                        { label: "A2A message", value: result.messageId },
+                        { label: "Reassigned inbox rows", value: transfer.reassignedInboxCount },
+                    ],
+                    tone: "info",
+                });
+            }
+            const parsedAssignments = extractTaskAssignmentsFromMessage(body);
+            const fallbackRepo = parsedAssignments.some((assignment) => !assignment.repoOwner || !assignment.repoName)
+                ? await resolveCurrentGitHubRepo()
+                : { repoOwner: null, repoName: null, repoRoot: null };
+            const recordedAssignments = [];
+            for (const assignment of parsedAssignments) {
+                const repoOwner = assignment.repoOwner ?? fallbackRepo.repoOwner;
+                const repoName = assignment.repoName ?? fallbackRepo.repoName;
+                const usesFallbackRepoIdentity = !assignment.repoOwner || !assignment.repoName;
+                const fallbackMatchesAssignmentRepo = assignment.repoOwner?.toLowerCase() === fallbackRepo.repoOwner?.toLowerCase() &&
+                    assignment.repoName?.toLowerCase() === fallbackRepo.repoName?.toLowerCase();
+                const repoRoot = usesFallbackRepoIdentity || fallbackMatchesAssignmentRepo ? fallbackRepo.repoRoot : null;
+                const tracked = db.recordTaskAssignment(result.target.id, assignment.issueNumber, assignment.branch, result.threadId, result.messageId, {
+                    repoOwner,
+                    repoName,
+                    repoRoot,
+                    taskKind: assignment.taskKind,
+                });
+                recordedAssignments.push({ issueNumber: tracked.issueNumber, branch: tracked.branch });
+            }
+            if (recordedAssignments.length > 0) {
+                deps.logActivity({
+                    kind: "task_assignment",
+                    level: "actions",
+                    title: recordedAssignments.length === 1 ? "Task assigned" : "Tasks assigned",
+                    summary: `Assigned ${recordedAssignments.map((assignment) => `#${assignment.issueNumber}`).join(", ")} to ${deps.formatTrackedAgent(result.target.id)}.`,
+                    details: recordedAssignments.map((assignment) => assignment.branch
+                        ? `#${assignment.issueNumber} on \`${assignment.branch}\``
+                        : `#${assignment.issueNumber}`),
+                    fields: [
+                        { label: "Worker", value: deps.formatTrackedAgent(result.target.id) },
+                        { label: "Thread", value: result.threadId },
+                        { label: "Message", value: result.messageId },
+                    ],
+                    tone: "info",
+                });
+            }
+            return {
+                messageId: result.messageId,
+                target: result.target.name,
+                ...(transferThreadId ? { transferredThreadId: transferThreadId } : {}),
+                ...(transferThreadChannel ? { transferredThreadChannel: transferThreadChannel } : {}),
+            };
+        }
+        if (deps.getBrokerRole() === "follower") {
+            const client = deps.getFollowerClient();
+            if (!client) {
+                throw new Error("Pinet is in an unexpected state.");
+            }
+            const messageId = await client.sendAgentMessage(targetRef, finalBody, finalMetadata);
+            return { messageId, target: targetRef };
+        }
+        throw new Error("Pinet is in an unexpected state.");
+    }
+    function sendPinetBroadcastMessage(channel, body) {
+        const db = deps.getActiveBrokerDb();
+        const selfId = deps.getActiveBrokerSelfId();
+        if (!db || !selfId) {
+            throw new Error("Broker agent identity is unavailable.");
+        }
+        const outgoing = prepareOutgoingPinetAgentMessage(body);
+        const result = dispatchBroadcastAgentMessage(db, {
+            senderAgentId: selfId,
+            senderAgentName: deps.getAgentName(),
+            channel,
+            body: outgoing.body,
+            ...(outgoing.metadata ? { metadata: outgoing.metadata } : {}),
+        });
+        return {
+            channel: result.channel,
+            messageIds: result.messageIds,
+            recipients: result.targets.map((target) => target.name),
+        };
+    }
+    async function scheduleBrokerWakeup(fireAt, message) {
+        const db = deps.getActiveBrokerDb();
+        const selfId = deps.getActiveBrokerSelfId();
+        if (!db || !selfId) {
+            throw new Error("Broker agent identity is unavailable.");
+        }
+        return await db.scheduleWakeup(selfId, message, fireAt);
+    }
+    async function scheduleFollowerWakeup(fireAt, message) {
+        const client = deps.getFollowerClient();
+        if (!client) {
+            throw new Error("Pinet is in an unexpected state.");
+        }
+        return await client.scheduleWakeup(fireAt, message);
+    }
+    function listBrokerAgents() {
+        const db = deps.getActiveBrokerDb();
+        if (!db) {
+            throw new Error("Broker agent identity is unavailable.");
+        }
+        return db.getAllAgents().map((agent) => ({
+            emoji: agent.emoji,
+            name: agent.name,
+            id: agent.id,
+            pid: agent.pid,
+            status: agent.status,
+            metadata: agent.metadata,
+            lastHeartbeat: agent.lastHeartbeat,
+            lastSeen: agent.lastSeen,
+            disconnectedAt: agent.disconnectedAt,
+            resumableUntil: agent.resumableUntil,
+            outboundCount: agent.outboundCount,
+            pendingInboxCount: db.getPendingInboxCount(agent.id),
+        }));
+    }
+    async function listFollowerAgents(includeGhosts) {
+        const client = deps.getFollowerClient();
+        if (!client) {
+            throw new Error("Pinet is in an unexpected state.");
+        }
+        return (await client.listAgents(includeGhosts)).map((agent) => ({
+            emoji: agent.emoji,
+            name: agent.name,
+            id: agent.id,
+            pid: agent.pid,
+            status: agent.status ?? "idle",
+            metadata: agent.metadata,
+            lastHeartbeat: agent.lastHeartbeat,
+            lastSeen: agent.lastSeen,
+            disconnectedAt: agent.disconnectedAt,
+            resumableUntil: agent.resumableUntil,
+            outboundCount: agent.outboundCount,
+            pendingInboxCount: agent.pendingInboxCount,
+        }));
+    }
+    return {
+        sendPinetAgentMessage,
+        sendPinetBroadcastMessage,
+        scheduleBrokerWakeup,
+        scheduleFollowerWakeup,
+        listBrokerAgents,
+        listFollowerAgents,
+    };
+}

package/dist/pinet-registration-gate.d.ts

@@ -0,0 +1,14 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+export interface PinetRegistrationGateDeps {
+    getArgv?: () => string[];
+    getStdinIsTTY?: () => boolean | undefined;
+    getStdoutIsTTY?: () => boolean | undefined;
+}
+export interface PinetRegistrationGate {
+    isBlocked: () => boolean;
+    getBlockReason: () => string;
+    evaluateSessionStart: (ctx: ExtensionContext) => boolean;
+    assertCanRegister: () => void;
+    reset: () => void;
+}
+export declare function createPinetRegistrationGate(deps?: PinetRegistrationGateDeps): PinetRegistrationGate;

package/dist/pinet-registration-gate.js

@@ -0,0 +1,42 @@
+import { isLikelyLocalSubagentContext } from "./helpers.js";
+const PINET_REGISTRATION_BLOCK_REASON = "Pinet is disabled in local subagent sessions to avoid polluting the agent mesh.";
+export function createPinetRegistrationGate(deps = {}) {
+    const getArgv = deps.getArgv ?? (() => process.argv.slice(2));
+    const getStdinIsTTY = deps.getStdinIsTTY ?? (() => process.stdin.isTTY);
+    const getStdoutIsTTY = deps.getStdoutIsTTY ?? (() => process.stdout.isTTY);
+    let pinetRegistrationBlocked = false;
+    function isBlocked() {
+        return pinetRegistrationBlocked;
+    }
+    function getBlockReason() {
+        return PINET_REGISTRATION_BLOCK_REASON;
+    }
+    function evaluateSessionStart(ctx) {
+        const sessionHeader = ctx.sessionManager.getHeader?.();
+        pinetRegistrationBlocked = isLikelyLocalSubagentContext({
+            sessionHeader,
+            sessionFile: ctx.sessionManager.getSessionFile(),
+            leafId: ctx.sessionManager.getLeafId(),
+            argv: getArgv(),
+            hasUI: ctx.hasUI,
+            stdinIsTTY: getStdinIsTTY(),
+            stdoutIsTTY: getStdoutIsTTY(),
+        });
+        return pinetRegistrationBlocked;
+    }
+    function assertCanRegister() {
+        if (pinetRegistrationBlocked) {
+            throw new Error(getBlockReason());
+        }
+    }
+    function reset() {
+        pinetRegistrationBlocked = false;
+    }
+    return {
+        isBlocked,
+        getBlockReason,
+        evaluateSessionStart,
+        assertCanRegister,
+        reset,
+    };
+}

package/dist/pinet-remote-control-acks.d.ts

@@ -0,0 +1,16 @@
+import type { PinetControlCommand } from "./helpers.js";
+export interface PinetRemoteControlAcksDeps {
+    queueBrokerInboxIds: (inboxIds: Iterable<number>) => void;
+    isBrokerConnected: () => boolean;
+    markBrokerInboxIdsDelivered: (inboxIds: number[]) => void;
+    queueFollowerInboxIds: (inboxIds: Iterable<number>) => void;
+    markFollowerInboxIdsDelivered: (inboxIds: Iterable<number>) => void;
+    flushDeliveredFollowerAcks: () => void | Promise<void>;
+}
+export interface PinetRemoteControlAcks {
+    resetPendingRemoteControlAcks: () => void;
+    deferBrokerControlAck: (command: PinetControlCommand, inboxId: number) => void;
+    deferFollowerControlAck: (command: PinetControlCommand, inboxId: number) => void;
+    flushDeferredRemoteControlAcks: (command: PinetControlCommand) => void;
+}
+export declare function createPinetRemoteControlAcks(deps: PinetRemoteControlAcksDeps): PinetRemoteControlAcks;

package/dist/pinet-remote-control-acks.js

@@ -0,0 +1,46 @@
+function createAckBuckets() {
+    return {
+        interrupt: new Set(),
+        reload: new Set(),
+        exit: new Set(),
+    };
+}
+export function createPinetRemoteControlAcks(deps) {
+    const pendingBrokerControlInboxIds = createAckBuckets();
+    const pendingFollowerControlInboxIds = createAckBuckets();
+    function resetPendingRemoteControlAcks() {
+        pendingBrokerControlInboxIds.interrupt.clear();
+        pendingBrokerControlInboxIds.reload.clear();
+        pendingBrokerControlInboxIds.exit.clear();
+        pendingFollowerControlInboxIds.interrupt.clear();
+        pendingFollowerControlInboxIds.reload.clear();
+        pendingFollowerControlInboxIds.exit.clear();
+    }
+    function deferBrokerControlAck(command, inboxId) {
+        pendingBrokerControlInboxIds[command].add(inboxId);
+        deps.queueBrokerInboxIds([inboxId]);
+    }
+    function deferFollowerControlAck(command, inboxId) {
+        pendingFollowerControlInboxIds[command].add(inboxId);
+        deps.queueFollowerInboxIds([inboxId]);
+    }
+    function flushDeferredRemoteControlAcks(command) {
+        const brokerIds = [...pendingBrokerControlInboxIds[command]];
+        if (brokerIds.length > 0 && deps.isBrokerConnected()) {
+            deps.markBrokerInboxIdsDelivered(brokerIds);
+            pendingBrokerControlInboxIds[command].clear();
+        }
+        const followerIds = [...pendingFollowerControlInboxIds[command]];
+        if (followerIds.length > 0) {
+            deps.markFollowerInboxIdsDelivered(followerIds);
+            pendingFollowerControlInboxIds[command].clear();
+            void deps.flushDeliveredFollowerAcks();
+        }
+    }
+    return {
+        resetPendingRemoteControlAcks,
+        deferBrokerControlAck,
+        deferFollowerControlAck,
+        flushDeferredRemoteControlAcks,
+    };
+}

package/dist/pinet-remote-control.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type PinetControlCommand, type PinetRemoteControlRequestResult } from "./helpers.js";
+export type PinetRuntimeControlContext = ExtensionContext & {
+    abort?: () => void;
+    shutdown?: () => void;
+};
+export interface PinetRemoteControlDeps {
+    flushDeferredRemoteControlAcks: (command: PinetControlCommand) => void;
+    reloadPinetRuntime: (ctx: ExtensionContext) => Promise<void>;
+    formatError: (error: unknown) => string;
+}
+export interface PinetRemoteControl {
+    requestRemoteControl: (command: PinetControlCommand, ctx: ExtensionContext) => PinetRemoteControlRequestResult;
+    runRemoteControl: (command: PinetControlCommand, ctx: ExtensionContext) => void;
+    resetRemoteControlState: () => void;
+}
+export declare function createPinetRemoteControl(deps: PinetRemoteControlDeps): PinetRemoteControl;