@pinet/slack-bridge 0.1.0

package/dist/home-tab.d.ts

@@ -0,0 +1,27 @@
+import type { BrokerControlPlaneDashboardSnapshot } from "./broker/control-plane-dashboard.js";
+import type { SlackBridgeRuntimeMode } from "./runtime-mode.js";
+export type SlackBlock = Record<string, unknown>;
+export interface SlackHomeView {
+    type: "home";
+    blocks: SlackBlock[];
+}
+export interface PublishSlackHomeTabInput {
+    slack: (method: string, token: string, body?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    token: string;
+    userId: string;
+    view: SlackHomeView;
+}
+export interface StandalonePinetHomeTabInput {
+    agentName: string;
+    agentEmoji: string;
+    connected: boolean;
+    mode: SlackBridgeRuntimeMode;
+    activeThreads: number;
+    pendingInbox: number;
+    currentBranch?: string | null;
+    defaultChannel?: string | null;
+}
+export declare function renderBrokerControlPlaneHomeTabView(snapshot: BrokerControlPlaneDashboardSnapshot): SlackHomeView;
+export declare function renderStandalonePinetHomeTabView(input: StandalonePinetHomeTabInput): SlackHomeView;
+export declare function buildSlackHomeTabPublishRequest(userId: string, view: SlackHomeView): Record<string, unknown>;
+export declare function publishSlackHomeTab(input: PublishSlackHomeTabInput): Promise<void>;

package/dist/home-tab.js

@@ -0,0 +1,242 @@
+const MAX_SECTION_TEXT_LENGTH = 2800;
+const MAX_ROSTER_ENTRIES = 20;
+function asNonEmptyString(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : null;
+}
+function formatTimestamp(value) {
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        return value;
+    }
+    return new Date(parsed)
+        .toISOString()
+        .replace("T", " ")
+        .replace(".000", "")
+        .replace(/:\d\dZ$/, "Z");
+}
+function formatDuration(ms) {
+    if (ms == null || !Number.isFinite(ms))
+        return "n/a";
+    if (ms < 1_000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1_000;
+    if (seconds < 60)
+        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+    const minutes = seconds / 60;
+    return `${minutes.toFixed(minutes < 10 ? 1 : 0)}m`;
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+function plainText(text) {
+    return {
+        type: "plain_text",
+        text: truncate(text, 150),
+        emoji: true,
+    };
+}
+function mrkdwn(text) {
+    return {
+        type: "mrkdwn",
+        text,
+    };
+}
+function headerBlock(text) {
+    return {
+        type: "header",
+        text: plainText(text),
+    };
+}
+function contextBlock(lines) {
+    return {
+        type: "context",
+        elements: lines.map((line) => mrkdwn(line)),
+    };
+}
+function dividerBlock() {
+    return { type: "divider" };
+}
+function sectionBlock(options) {
+    return {
+        type: "section",
+        ...(options.text ? { text: mrkdwn(options.text) } : {}),
+        ...(options.fields && options.fields.length > 0
+            ? { fields: options.fields.slice(0, 10).map((field) => mrkdwn(field)) }
+            : {}),
+        ...(options.accessory ? { accessory: options.accessory } : {}),
+    };
+}
+function buildLineSections(lines, emptyState) {
+    if (lines.length === 0) {
+        return [sectionBlock({ text: emptyState })];
+    }
+    const chunks = [];
+    let current = "";
+    for (const line of lines) {
+        const candidate = current.length > 0 ? `${current}\n${line}` : line;
+        if (candidate.length > MAX_SECTION_TEXT_LENGTH && current.length > 0) {
+            chunks.push(current);
+            current = line;
+            continue;
+        }
+        if (line.length > MAX_SECTION_TEXT_LENGTH) {
+            if (current.length > 0) {
+                chunks.push(current);
+                current = "";
+            }
+            chunks.push(truncate(line, MAX_SECTION_TEXT_LENGTH));
+            continue;
+        }
+        current = candidate;
+    }
+    if (current.length > 0) {
+        chunks.push(current);
+    }
+    return chunks.map((chunk) => sectionBlock({ text: chunk }));
+}
+function buildRosterBlocks(snapshot) {
+    const visibleRoster = snapshot.roster.slice(0, MAX_ROSTER_ENTRIES);
+    const blocks = visibleRoster.length > 0
+        ? visibleRoster.map((row) => sectionBlock({
+            text: [
+                `*${row.label}* · \`${row.role}\``,
+                `Health: ${row.health} · Status: ${row.status}`,
+                `Workload: ${row.workload}`,
+                `Task: ${truncate(row.taskSummary, 120)}`,
+                `Heartbeat: ${row.heartbeat}`,
+                `Branch: ${row.branch} · Worktree: ${row.worktree}`,
+            ].join("\n"),
+        }))
+        : [sectionBlock({ text: "No agents are currently registered." })];
+    if (snapshot.roster.length > visibleRoster.length) {
+        blocks.push(contextBlock([
+            `_Showing ${visibleRoster.length} of ${snapshot.roster.length} agents on the Home tab._`,
+        ]));
+    }
+    return blocks;
+}
+export function renderBrokerControlPlaneHomeTabView(snapshot) {
+    const anomalyLines = snapshot.anomalies.length > 0
+        ? snapshot.anomalies.map((anomaly) => `• ${anomaly}`)
+        : ["• Healthy ✅"];
+    const maintenanceLines = snapshot.maintenanceAnomalies.map((anomaly) => `• ${anomaly}`);
+    const snoozeLine = snapshot.ralphSnooze?.active
+        ? `active until ${snapshot.ralphSnooze.until ?? "unknown"}${snapshot.ralphSnooze.reason ? ` — ${snapshot.ralphSnooze.reason}` : ""}`
+        : `off${snapshot.ralphSnooze ? ` · ${snapshot.ralphSnooze.emptyCycleCount} empty cycles` : ""}`;
+    const cycleLines = snapshot.recentCycles.map((cycle) => `• *${cycle.startedAt}* — ${cycle.duration} · ${cycle.agentCount} agents · backlog ${cycle.backlogCount} · ghosts ${cycle.ghostCount} · stuck ${cycle.stuckCount} · follow-up ${cycle.followUpDelivered ? "yes" : "no"}\n  ${cycle.anomalySummary}`);
+    const blocks = [
+        headerBlock("Pinet Broker Control Plane"),
+        contextBlock([
+            `_Updated ${formatTimestamp(snapshot.cycleStartedAt)} · cycle ${formatDuration(snapshot.cycleDurationMs)}_`,
+        ]),
+        sectionBlock({
+            text: "This Home tab mirrors the broker control-plane dashboard with live mesh, task, and RALPH loop status.",
+        }),
+        dividerBlock(),
+        headerBlock("Mesh summary"),
+        sectionBlock({
+            fields: [
+                `*Main checkout*\n\`${snapshot.currentBranch ?? "unknown"}\``,
+                `*Agents*\n${snapshot.liveAgents} live / ${snapshot.totalAgents} total`,
+                `*Workers*\n${snapshot.workingWorkers} working · ${snapshot.idleWorkers} idle`,
+                `*Backlog*\n${snapshot.pendingBacklogCount} pending · ${snapshot.assignedBacklogCount} assigned`,
+                `*RALPH nudges*\n${snapshot.nudgesThisCycle} nudges · ${snapshot.idleDrainCandidates} idle drains`,
+                `*RALPH snooze*\n${snoozeLine}`,
+                `*Maintenance*\n${snapshot.reapedAgents} reaped · ${snapshot.repairedThreadClaims} repaired claims`,
+            ],
+        }),
+        headerBlock("Active anomalies"),
+        ...buildLineSections(anomalyLines, "Healthy ✅"),
+        ...(maintenanceLines.length > 0
+            ? [headerBlock("Maintenance anomalies"), ...buildLineSections(maintenanceLines, "None.")]
+            : []),
+        headerBlock("Agent roster"),
+        ...buildRosterBlocks(snapshot),
+        headerBlock("Task / PR status"),
+        sectionBlock({
+            fields: [
+                `*Assigned*\n${snapshot.taskCounts.assigned}`,
+                `*Branch pushed*\n${snapshot.taskCounts.branchPushed}`,
+                `*Open PRs*\n${snapshot.taskCounts.openPrs}`,
+                `*Merged PRs*\n${snapshot.taskCounts.mergedPrs}`,
+                `*Closed PRs*\n${snapshot.taskCounts.closedPrs}`,
+            ],
+        }),
+        headerBlock("Active tasks"),
+        ...buildLineSections(snapshot.activeTasks.map((task) => `• ${task}`), "No active tracked tasks."),
+        headerBlock("Recent outcomes"),
+        ...buildLineSections(snapshot.recentOutcomes.map((task) => `• ${task}`), "No merged or closed PR outcomes tracked yet."),
+        headerBlock("Lane metadata"),
+        headerBlock("Active/managed lanes"),
+        ...buildLineSections(snapshot.activeLanes.map((lane) => `• ${lane}`), "No active managed lanes tracked."),
+        headerBlock("Detached/manual-supervision lanes"),
+        ...buildLineSections(snapshot.detachedLanes.map((lane) => `• ${lane}`), "No detached lanes tracked."),
+        headerBlock("Recent RALPH cycles"),
+        ...buildLineSections(cycleLines, "No recorded RALPH cycles yet."),
+        dividerBlock(),
+        headerBlock("Quick actions"),
+        sectionBlock({
+            text: [
+                "• Open a DM with Pinet in the *Messages* tab to assign or follow up on work.",
+                "• Mention Pinet in a channel thread to route a task into the broker mesh.",
+            ].join("\n"),
+        }),
+    ];
+    return {
+        type: "home",
+        blocks,
+    };
+}
+export function renderStandalonePinetHomeTabView(input) {
+    const modeLabel = input.mode;
+    const branch = asNonEmptyString(input.currentBranch) ?? "unknown";
+    const defaultChannel = asNonEmptyString(input.defaultChannel) ?? "not configured";
+    return {
+        type: "home",
+        blocks: [
+            headerBlock("Pinet Home"),
+            contextBlock([
+                `${input.agentEmoji} *${input.agentName}* · ${input.connected ? "connected" : "disconnected"}`,
+            ]),
+            sectionBlock({
+                text: "Pinet is available from Slack’s Home tab. When the broker mesh is running, this surface upgrades into the full control-plane dashboard.",
+            }),
+            dividerBlock(),
+            headerBlock("Current runtime"),
+            sectionBlock({
+                fields: [
+                    `*Mode*\n${modeLabel}`,
+                    `*Connection*\n${input.connected ? "connected" : "disconnected"}`,
+                    `*Branch*\n\`${branch}\``,
+                    `*Active threads*\n${input.activeThreads}`,
+                    `*Pending inbox*\n${input.pendingInbox}`,
+                    `*Default channel*\n${defaultChannel}`,
+                ],
+            }),
+            headerBlock("Getting started"),
+            sectionBlock({
+                text: [
+                    "• Open the *Messages* tab and start a conversation with Pinet.",
+                    "• Mention Pinet in a channel to continue work in-thread.",
+                    '• Use `runtimeMode: "single"` for local Slack-only mode, or `/pinet start` and `/pinet follow` for mesh runtimes.',
+                ].join("\n"),
+            }),
+        ],
+    };
+}
+export function buildSlackHomeTabPublishRequest(userId, view) {
+    const normalizedUserId = asNonEmptyString(userId);
+    if (!normalizedUserId) {
+        throw new Error("Home tab publish requires a user ID.");
+    }
+    return {
+        user_id: normalizedUserId,
+        view,
+    };
+}
+export async function publishSlackHomeTab(input) {
+    await input.slack("views.publish", input.token, buildSlackHomeTabPublishRequest(input.userId, input.view));
+}

package/dist/imessage-tools.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { NormalizedMessageContent } from "@pinet/transport-core";
+import type { Broker } from "./broker/index.js";
+export interface IMessageToolSendInput {
+    threadId: string;
+    body: string;
+    source: "imessage";
+    channel: string;
+    content: NormalizedMessageContent;
+    agentName: string;
+    agentEmoji: string;
+    agentOwnerToken: string;
+    metadata: Record<string, unknown>;
+}
+export interface IMessageToolSendResult {
+    adapter: string;
+    messageId: number;
+}
+export interface RegisterIMessageToolsDeps {
+    pinetEnabled: () => boolean;
+    brokerRole: () => "broker" | "follower" | null;
+    requireToolPolicy: (toolName: string, threadTs: string | undefined, action: string) => void;
+    getActiveBroker: () => Broker | null;
+    getActiveBrokerSelfId: () => string | null;
+    sendFollowerIMessage: (input: IMessageToolSendInput) => Promise<IMessageToolSendResult>;
+    getAgentIdentity: () => {
+        name: string;
+        emoji: string;
+        ownerToken: string;
+    };
+    trackOwnedThread: (threadId: string, channel: string, source: "imessage") => void;
+}
+export declare function registerIMessageTools(pi: ExtensionAPI, deps: RegisterIMessageToolsDeps): void;

package/dist/imessage-tools.js

@@ -0,0 +1,96 @@
+import { Type } from "@sinclair/typebox";
+import { getDefaultIMessageThreadId, normalizeIMessageRecipient } from "@pinet/imessage-bridge";
+import { sendBrokerMessage } from "./broker/message-send.js";
+export function registerIMessageTools(pi, deps) {
+    pi.registerTool({
+        name: "imessage_send",
+        label: "iMessage Send",
+        description: "Send a message through the local send-first iMessage adapter on the active broker.",
+        promptSnippet: "Send a message through the local send-first iMessage adapter on the active Pinet broker. Use when a task needs a narrow macOS iMessage send path.",
+        parameters: Type.Object({
+            to: Type.String({
+                description: "Recipient handle, phone number, email, or local chat identifier",
+            }),
+            text: Type.String({ description: "Message body" }),
+            thread_id: Type.Optional(Type.String({
+                description: "Optional transport thread id. Defaults to a stable iMessage thread id derived from the recipient.",
+            })),
+        }),
+        async execute(_id, params) {
+            deps.requireToolPolicy("imessage_send", undefined, `to=${params.to} | thread_id=${params.thread_id ?? ""} | text=${params.text}`);
+            if (!deps.pinetEnabled()) {
+                throw new Error("Pinet is not running. Use /pinet start or /pinet follow first.");
+            }
+            const recipient = normalizeIMessageRecipient(params.to);
+            const text = params.text.trim();
+            if (!text) {
+                throw new Error("text is required");
+            }
+            const threadId = params.thread_id?.trim() || getDefaultIMessageThreadId(recipient);
+            const { name, emoji, ownerToken } = deps.getAgentIdentity();
+            const request = {
+                threadId,
+                body: text,
+                source: "imessage",
+                channel: recipient,
+                content: { text },
+                agentName: name,
+                agentEmoji: emoji,
+                agentOwnerToken: ownerToken,
+                metadata: { recipient },
+            };
+            let result;
+            if (deps.brokerRole() === "broker") {
+                const broker = deps.getActiveBroker();
+                const selfId = deps.getActiveBrokerSelfId();
+                if (!broker || !selfId) {
+                    throw new Error("Broker agent identity is unavailable.");
+                }
+                if (!broker.adapters.some((candidate) => candidate.name === "imessage")) {
+                    throw new Error("iMessage adapter is not enabled or not ready on the active broker. Set slack-bridge.imessage.enabled: true and restart /pinet start.");
+                }
+                const brokerResult = await sendBrokerMessage({
+                    db: broker.db,
+                    adapters: broker.adapters,
+                }, {
+                    threadId,
+                    body: text,
+                    senderAgentId: selfId,
+                    source: request.source,
+                    channel: request.channel,
+                    content: request.content,
+                    agentName: request.agentName,
+                    agentEmoji: request.agentEmoji,
+                    agentOwnerToken: request.agentOwnerToken,
+                    metadata: request.metadata,
+                });
+                result = {
+                    adapter: brokerResult.adapter,
+                    messageId: brokerResult.message.id,
+                };
+            }
+            else if (deps.brokerRole() === "follower") {
+                result = await deps.sendFollowerIMessage(request);
+            }
+            else {
+                throw new Error("Pinet is in an unexpected state.");
+            }
+            deps.trackOwnedThread(threadId, recipient, "imessage");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Sent iMessage to ${recipient} (thread_id: ${threadId}).`,
+                    },
+                ],
+                details: {
+                    threadId,
+                    channel: recipient,
+                    source: "imessage",
+                    adapter: result.adapter,
+                    messageId: result.messageId,
+                },
+            };
+        },
+    });
+}

package/dist/inbox-drain-runtime.d.ts

@@ -0,0 +1,30 @@
+import { type FollowerDeliveryState } from "./follower-delivery.js";
+import { type InboxMessage } from "./helpers.js";
+export interface InboxDrainRuntimeDeps {
+    sendUserMessage: (text: string) => void;
+    isIdle: () => boolean;
+    takeInboxMessages: (maxMessages?: number) => InboxMessage[];
+    restoreInboxMessages: (messages: InboxMessage[]) => void;
+    updateBadge: () => void;
+    reportStatus: (status: "working" | "idle") => Promise<void>;
+    userNames: {
+        get: (key: string) => string | undefined;
+    };
+    getSecurityPrompt: () => string;
+    deliverTrackedSlackFollowUpMessage: (options: {
+        prompt: string;
+        messages: Pick<InboxMessage, "threadTs">[];
+    }) => boolean;
+    getBrokerRole: () => "broker" | "follower" | null;
+    hasFollowerClient: () => boolean;
+    flushFollowerDeliveredAcks: () => Promise<void>;
+    markBrokerInboxIdsDelivered: (inboxIds: number[]) => void;
+    getFollowerDeliveryState: () => FollowerDeliveryState;
+    maxMessagesPerDrain?: number;
+}
+export interface InboxDrainRuntime {
+    deliverFollowUpMessage: (text: string) => boolean;
+    flushDeliveredFollowerAcks: () => Promise<void>;
+    drainInbox: () => void;
+}
+export declare function createInboxDrainRuntime(deps: InboxDrainRuntimeDeps): InboxDrainRuntime;

package/dist/inbox-drain-runtime.js

@@ -0,0 +1,71 @@
+import { getBrokerInboxIds } from "./broker-delivery.js";
+import { markFollowerInboxIdsDelivered } from "./follower-delivery.js";
+import { formatInboxMessages } from "./helpers.js";
+const DEFAULT_MAX_MESSAGES_PER_DRAIN = 5;
+export function createInboxDrainRuntime(deps) {
+    function deliverFollowUpMessage(text) {
+        if (!deps.isIdle()) {
+            return false;
+        }
+        try {
+            deps.sendUserMessage(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function flushDeliveredFollowerAcks() {
+        if (deps.getBrokerRole() !== "follower" || !deps.hasFollowerClient()) {
+            return;
+        }
+        await deps.flushFollowerDeliveredAcks();
+    }
+    function drainInbox() {
+        if (!deps.isIdle()) {
+            return;
+        }
+        const maxMessages = deps.maxMessagesPerDrain ?? DEFAULT_MAX_MESSAGES_PER_DRAIN;
+        const pending = deps.takeInboxMessages(maxMessages);
+        if (pending.length === 0) {
+            return;
+        }
+        const brokerInboxIds = getBrokerInboxIds(pending);
+        deps.updateBadge();
+        void deps.reportStatus("working").catch(() => {
+            /* best effort */
+        });
+        let prompt = formatInboxMessages(pending, deps.userNames);
+        const securityPrompt = deps.getSecurityPrompt();
+        if (securityPrompt) {
+            prompt = `${securityPrompt}\n\n${prompt}`;
+        }
+        if (deps.deliverTrackedSlackFollowUpMessage({
+            prompt,
+            messages: pending,
+        })) {
+            if (brokerInboxIds.length > 0) {
+                if (deps.getBrokerRole() === "follower") {
+                    markFollowerInboxIdsDelivered(deps.getFollowerDeliveryState(), brokerInboxIds);
+                    void flushDeliveredFollowerAcks();
+                }
+                else if (deps.getBrokerRole() === "broker") {
+                    try {
+                        deps.markBrokerInboxIdsDelivered(brokerInboxIds);
+                    }
+                    catch {
+                        /* best effort */
+                    }
+                }
+            }
+            return;
+        }
+        deps.restoreInboxMessages(pending);
+        deps.updateBadge();
+    }
+    return {
+        deliverFollowUpMessage,
+        flushDeliveredFollowerAcks,
+        drainInbox,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;