@pinet/slack-bridge 0.1.0

package/dist/broker-runtime.js

@@ -0,0 +1,533 @@
+import { buildPinetOwnerToken, buildPinetSkinAssignment, DEFAULT_PINET_SKIN_THEME, normalizePinetSkinTheme, resolvePinetMeshAuth, syncBrokerInboxEntries, } from "./helpers.js";
+import { startBroker } from "./broker/index.js";
+import { DEFAULT_HEARTBEAT_TIMEOUT_MS } from "./broker/socket-server.js";
+import { MessageRouter } from "./broker/router.js";
+import { DEFAULT_BROKER_MAINTENANCE_INTERVAL_MS, DEFAULT_BUSY_ASSIGNMENT_AGE_MS, runBrokerMaintenancePass, } from "./broker/maintenance.js";
+import { HEARTBEAT_INTERVAL_MS } from "./broker/client.js";
+import { isBrokerInboxIdTracked, markBrokerInboxIdsHandled, queueBrokerInboxIds, resetBrokerDeliveryState, } from "./broker-delivery.js";
+import {} from "./activity-log.js";
+import { clearRalphLoopSnooze, createRalphLoopState, getRalphLoopSnoozeStatus, setRalphLoopSnooze, startRalphLoop, stopRalphLoop, } from "./ralph-loop.js";
+import { TtlCache } from "./ttl-cache.js";
+import { createBrokerGhostReaper } from "./broker/ghost-reaper.js";
+import { buildPinetRuntimeAdapterBindings, connectPinetRuntimeAdapters, } from "./pinet-runtime-composition.js";
+function normalizeOptionalSetting(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : null;
+}
+export function resolveConfiguredBrokerSkinTheme(settings) {
+    return normalizePinetSkinTheme(settings.skinTheme) ?? DEFAULT_PINET_SKIN_THEME;
+}
+export function createBrokerRuntime(deps) {
+    let activeBroker = null;
+    let activeRouter = null;
+    let activeSelfId = null;
+    let brokerHeartbeatTimer = null;
+    let brokerMaintenanceTimer = null;
+    let brokerScheduledWakeupTimer = null;
+    let brokerMaintenanceRunning = false;
+    let brokerScheduledWakeupRunning = false;
+    let lastBrokerMaintenance = null;
+    let lastBrokerMaintenanceSignature = "";
+    let activityLogger = null;
+    let activityLogContext = null;
+    let lastActivityLogFailureAt = 0;
+    const brokerControlPlaneHomeTabViewers = new TtlCache({
+        maxSize: 100,
+        ttlMs: 12 * 60 * 60 * 1000,
+    });
+    let lastBrokerControlPlaneHomeTabSnapshot = null;
+    let lastBrokerControlPlaneHomeTabRefreshAt = null;
+    let lastBrokerControlPlaneHomeTabError = null;
+    const ghostReaper = createBrokerGhostReaper({
+        brokerAgentId: () => activeSelfId,
+        getAgentById: (agentId) => activeBroker?.db.getAgentById(agentId) ?? null,
+    });
+    const ralphLoopState = createRalphLoopState();
+    function ensureActivityLogger() {
+        if (activityLogger) {
+            return activityLogger;
+        }
+        activityLogger = deps.createActivityLogger((error) => {
+            const formatted = deps.formatError(error);
+            console.error(`[slack-bridge] activity log failed: ${formatted}`);
+            const now = Date.now();
+            if (!activityLogContext?.hasUI || now - lastActivityLogFailureAt < 60_000) {
+                return;
+            }
+            lastActivityLogFailureAt = now;
+            activityLogContext.ui.notify(`Pinet activity log failed: ${formatted}`, "warning");
+        });
+        return activityLogger;
+    }
+    function stopBrokerHeartbeat() {
+        if (!brokerHeartbeatTimer)
+            return;
+        clearInterval(brokerHeartbeatTimer);
+        brokerHeartbeatTimer = null;
+    }
+    function startBrokerHeartbeat() {
+        stopBrokerHeartbeat();
+        if (!activeBroker || !activeSelfId)
+            return;
+        const broker = activeBroker;
+        const selfId = activeSelfId;
+        brokerHeartbeatTimer = setInterval(() => {
+            try {
+                broker.db.heartbeatAgent(selfId);
+            }
+            catch {
+                /* best effort */
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+        brokerHeartbeatTimer.unref?.();
+    }
+    function stopBrokerMaintenance() {
+        if (!brokerMaintenanceTimer)
+            return;
+        clearInterval(brokerMaintenanceTimer);
+        brokerMaintenanceTimer = null;
+    }
+    function syncBrokerDbInbox(agentId, db, ctx) {
+        db.recoverPendingTargetedBacklog(agentId);
+        const pending = db
+            .getInbox(agentId)
+            .filter((item) => !isBrokerInboxIdTracked(deps.deliveryState, item.entry.id));
+        if (pending.length === 0) {
+            return;
+        }
+        const synced = syncBrokerInboxEntries(pending.map((item) => ({
+            inboxId: item.entry.id,
+            message: {
+                threadId: item.message.threadId,
+                sender: typeof item.message.metadata?.senderAgent === "string"
+                    ? item.message.metadata.senderAgent
+                    : item.message.sender,
+                body: item.message.body,
+                createdAt: item.message.createdAt,
+                metadata: item.message.metadata,
+            },
+        })));
+        const handledInboxIds = new Set();
+        const commandsToStart = [];
+        for (const entry of synced.controlEntries) {
+            try {
+                const queued = deps.requestRemoteControl(entry.command, ctx);
+                if (queued.ackDisposition === "immediate") {
+                    handledInboxIds.add(entry.inboxId);
+                }
+                else {
+                    deps.deferControlAck(queued.scheduledCommand, entry.inboxId);
+                }
+                if (queued.shouldStartNow) {
+                    commandsToStart.push(entry.command);
+                }
+            }
+            catch (error) {
+                ctx.ui.notify(`Pinet remote control failed: ${deps.formatError(error)}`, "error");
+            }
+        }
+        if (handledInboxIds.size > 0) {
+            db.markDelivered([...handledInboxIds], agentId);
+        }
+        for (const command of commandsToStart) {
+            deps.runRemoteControl(command, ctx);
+        }
+        if (synced.inboxMessages.length === 0) {
+            return;
+        }
+        queueBrokerInboxIds(deps.deliveryState, synced.inboxMessages.flatMap((message) => message.brokerInboxId != null ? [message.brokerInboxId] : []));
+        deps.pushInboxMessages(synced.inboxMessages);
+        deps.updateBadge();
+        deps.maybeDrainInboxIfIdle(ctx);
+    }
+    function runMaintenance(ctx) {
+        if (!activeBroker || !activeSelfId || brokerMaintenanceRunning)
+            return;
+        brokerMaintenanceRunning = true;
+        try {
+            const result = runBrokerMaintenancePass(activeBroker.db, {
+                brokerAgentId: activeSelfId,
+                staleAfterMs: DEFAULT_HEARTBEAT_TIMEOUT_MS,
+                busyAssignmentAgeMs: DEFAULT_BUSY_ASSIGNMENT_AGE_MS,
+            });
+            const staleAgents = result.reapedAgentIds
+                .map((agentId) => activeBroker?.db.getAgentById(agentId) ?? null)
+                .filter((agent) => agent !== null);
+            const processReap = ghostReaper.reapGhosts(staleAgents);
+            if (processReap.signaledAgentIds.length > 0) {
+                result.anomalies.push(`signaled ${processReap.signaledAgentIds.length} broker-managed ghost process${processReap.signaledAgentIds.length === 1 ? "" : "es"}`);
+            }
+            syncBrokerDbInbox(activeSelfId, activeBroker.db, ctx);
+            lastBrokerMaintenance = result;
+            const previousSignature = lastBrokerMaintenanceSignature;
+            const signature = result.anomalies.join("|");
+            deps.onMaintenanceResult(ctx, { result, previousSignature, signature });
+            lastBrokerMaintenanceSignature = signature;
+        }
+        catch (error) {
+            deps.onMaintenanceError(ctx, error);
+        }
+        finally {
+            brokerMaintenanceRunning = false;
+        }
+    }
+    function startBrokerMaintenance(ctx) {
+        stopBrokerMaintenance();
+        brokerMaintenanceTimer = setInterval(() => {
+            runMaintenance(ctx);
+        }, DEFAULT_BROKER_MAINTENANCE_INTERVAL_MS);
+        brokerMaintenanceTimer.unref?.();
+        runMaintenance(ctx);
+    }
+    function runBrokerScheduledWakeups(ctx) {
+        if (!activeBroker || brokerScheduledWakeupRunning)
+            return;
+        brokerScheduledWakeupRunning = true;
+        try {
+            const deliveries = activeBroker.db.deliverDueScheduledWakeups();
+            if (deliveries.length > 0 && activeSelfId) {
+                syncBrokerDbInbox(activeSelfId, activeBroker.db, ctx);
+            }
+        }
+        catch (error) {
+            deps.onScheduledWakeupError(ctx, error);
+        }
+        finally {
+            brokerScheduledWakeupRunning = false;
+        }
+    }
+    function stopBrokerScheduledWakeups() {
+        brokerScheduledWakeupRunning = false;
+        if (!brokerScheduledWakeupTimer)
+            return;
+        clearInterval(brokerScheduledWakeupTimer);
+        brokerScheduledWakeupTimer = null;
+    }
+    function startBrokerScheduledWakeups(ctx) {
+        stopBrokerScheduledWakeups();
+        brokerScheduledWakeupTimer = setInterval(() => {
+            runBrokerScheduledWakeups(ctx);
+        }, 1000);
+        brokerScheduledWakeupTimer.unref?.();
+        runBrokerScheduledWakeups(ctx);
+    }
+    function getRalphLoopDeps() {
+        return {
+            getBrokerDb: () => activeBroker?.db ?? null,
+            getBrokerAgentId: () => activeSelfId,
+            heartbeatTimerActive: () => brokerHeartbeatTimer != null,
+            maintenanceTimerActive: () => brokerMaintenanceTimer != null,
+            runMaintenance: (ctx) => runMaintenance(ctx),
+            sendMaintenanceMessage: (targetAgentId, body) => deps.sendMaintenanceMessage(targetAgentId, body),
+            trySendFollowUp: (body, onDelivered) => deps.trySendFollowUp(body, onDelivered),
+            logActivity: (entry) => {
+                if (!activeBroker) {
+                    return;
+                }
+                ensureActivityLogger().log(entry);
+            },
+            formatTrackedAgent: (agentId) => deps.formatTrackedAgent(agentId),
+            summarizeTrackedAssignmentStatus: (status, prNumber, branch) => deps.summarizeTrackedAssignmentStatus(status, prNumber, branch),
+            refreshHomeTabs: (ctx, snapshot, refreshedAt) => deps.refreshHomeTabs(ctx, snapshot, refreshedAt),
+            getLastMaintenance: () => lastBrokerMaintenance,
+            getSettings: () => deps.getSettings(),
+            buildControlPlaneDashboardSnapshot: (input) => deps.buildControlPlaneDashboardSnapshot(input),
+            setLastHomeTabSnapshot: (snapshot) => {
+                lastBrokerControlPlaneHomeTabSnapshot = snapshot;
+            },
+            getLastHomeTabError: () => lastBrokerControlPlaneHomeTabError,
+            setLastHomeTabError: (error) => {
+                lastBrokerControlPlaneHomeTabError = error;
+            },
+        };
+    }
+    function startObservability(ctx) {
+        if (!activeBroker) {
+            return;
+        }
+        activityLogContext = ctx;
+        startRalphLoop(ctx, ralphLoopState, getRalphLoopDeps());
+    }
+    function stopObservability() {
+        stopRalphLoop(ralphLoopState);
+        brokerControlPlaneHomeTabViewers.clear();
+        lastBrokerControlPlaneHomeTabSnapshot = null;
+        lastBrokerControlPlaneHomeTabRefreshAt = null;
+        lastBrokerControlPlaneHomeTabError = null;
+        activityLogger?.clearPending();
+        activityLogContext = null;
+    }
+    async function publishCurrentHomeTabSafely(userId, ctx, openedAt = new Date().toISOString()) {
+        if (!activeBroker) {
+            return false;
+        }
+        activityLogContext = ctx;
+        brokerControlPlaneHomeTabViewers.set(userId, { openedAt });
+        try {
+            const snapshot = (await deps.buildCurrentDashboardSnapshot(openedAt)) ??
+                lastBrokerControlPlaneHomeTabSnapshot;
+            if (!snapshot) {
+                return false;
+            }
+            await deps.refreshHomeTabs(ctx, snapshot, openedAt, [userId]);
+            return true;
+        }
+        catch (error) {
+            const homeTabMessage = `Pinet Home tab publish failed: ${deps.formatError(error)}`;
+            if (homeTabMessage !== lastBrokerControlPlaneHomeTabError) {
+                ctx.ui.notify(homeTabMessage, "warning");
+            }
+            lastBrokerControlPlaneHomeTabError = homeTabMessage;
+            return false;
+        }
+    }
+    async function disconnect(options = {}) {
+        stopObservability();
+        stopBrokerHeartbeat();
+        stopBrokerMaintenance();
+        stopBrokerScheduledWakeups();
+        ghostReaper.dispose();
+        brokerMaintenanceRunning = false;
+        brokerScheduledWakeupRunning = false;
+        if (activeBroker) {
+            try {
+                if (options.releaseIdentity && activeSelfId) {
+                    activeBroker.db.unregisterAgent(activeSelfId);
+                }
+                await activeBroker.stop();
+            }
+            catch {
+                /* best effort */
+            }
+        }
+        activeBroker = null;
+        activeRouter = null;
+        activeSelfId = null;
+        lastBrokerMaintenance = null;
+        lastBrokerMaintenanceSignature = "";
+        resetBrokerDeliveryState(deps.deliveryState);
+    }
+    return {
+        async connect(ctx) {
+            const settings = deps.getSettings();
+            const meshAuth = resolvePinetMeshAuth(settings);
+            const allowedUsers = deps.getAllowedUsers();
+            const broker = await startBroker({
+                ...(meshAuth.meshSecret ? { meshSecret: meshAuth.meshSecret } : {}),
+                ...(meshAuth.meshSecretPath ? { meshSecretPath: meshAuth.meshSecretPath } : {}),
+            });
+            let selfId = null;
+            activityLogContext = ctx;
+            try {
+                broker.db.setAllowedUsers(allowedUsers);
+                const router = new MessageRouter(broker.db);
+                const persistedBrokerStableId = normalizeOptionalSetting(broker.db.getSetting("pinet.brokerStableId")) ??
+                    broker.db
+                        .getAllAgents()
+                        .flatMap((agent) => {
+                        const stableId = normalizeOptionalSetting(agent.stableId);
+                        if (!stableId) {
+                            return [];
+                        }
+                        if (deps.getMeshRoleFromMetadata(agent.metadata ?? undefined, "worker") !== "broker") {
+                            return [];
+                        }
+                        const lastSeenMs = Date.parse(agent.lastSeen);
+                        const connectedAtMs = Date.parse(agent.connectedAt);
+                        const recencyMs = Number.isNaN(lastSeenMs)
+                            ? Number.isNaN(connectedAtMs)
+                                ? 0
+                                : connectedAtMs
+                            : lastSeenMs;
+                        return [{ stableId, recencyMs }];
+                    })
+                        .sort((left, right) => right.recencyMs - left.recencyMs)[0]?.stableId ??
+                    null;
+                const brokerStableId = persistedBrokerStableId ?? deps.getBrokerStableId();
+                deps.setBrokerStableId(brokerStableId);
+                broker.db.setSetting("pinet.brokerStableId", brokerStableId);
+                deps.setAgentOwnerToken(buildPinetOwnerToken(brokerStableId));
+                const activeSkinTheme = resolveConfiguredBrokerSkinTheme(deps.getSettings());
+                deps.setActiveSkinTheme(activeSkinTheme);
+                broker.db.setSetting("pinet.skinTheme", activeSkinTheme);
+                broker.server.setAgentRegistrationResolver((registration) => {
+                    const theme = deps.getActiveSkinTheme() ?? DEFAULT_PINET_SKIN_THEME;
+                    const assignment = buildPinetSkinAssignment({
+                        theme,
+                        role: deps.getMeshRoleFromMetadata(registration.metadata, "worker"),
+                        seed: registration.stableId ?? registration.agentId,
+                    });
+                    return {
+                        name: assignment.name,
+                        emoji: assignment.emoji,
+                        metadata: deps.buildSkinMetadata(registration.metadata, assignment.personality, assignment.statusVocabulary),
+                    };
+                });
+                const selfAssignment = buildPinetSkinAssignment({
+                    theme: activeSkinTheme,
+                    role: "broker",
+                    seed: brokerStableId,
+                });
+                const selfAgent = broker.db.registerAgent(ctx.sessionManager.getLeafId() ?? `broker-${process.pid}`, selfAssignment.name, selfAssignment.emoji, process.pid, deps.buildSkinMetadata(await deps.getAgentMetadata("broker"), selfAssignment.personality, selfAssignment.statusVocabulary), brokerStableId);
+                selfId = selfAgent.id;
+                deps.applyLocalAgentIdentity(selfAgent.name, selfAgent.emoji, selfAssignment.personality);
+                const brokerSelfId = selfId;
+                const adapterBindings = await buildPinetRuntimeAdapterBindings(deps.createAdapterBindings, {
+                    broker,
+                    router,
+                    selfId: brokerSelfId,
+                    ctx,
+                });
+                const adapterConnectResult = await connectPinetRuntimeAdapters({
+                    broker,
+                    bindings: adapterBindings,
+                    onInbound: (message) => {
+                        void deps.handleInboundMessage({ message, broker, router, selfId: brokerSelfId, ctx });
+                    },
+                });
+                activeBroker = broker;
+                activeRouter = router;
+                activeSelfId = brokerSelfId;
+                resetBrokerDeliveryState(deps.deliveryState);
+                const releasedBrokerClaims = broker.db.releaseThreadClaims(brokerSelfId);
+                const recoveredTargetedBacklogCount = broker.db.recoverPendingTargetedBacklog(brokerSelfId);
+                const recoveredBrokerMessages = broker.db.getPendingInboxCount(brokerSelfId);
+                syncBrokerDbInbox(brokerSelfId, broker.db, ctx);
+                broker.server.onAgentMessage((targetAgentId) => {
+                    if (targetAgentId !== brokerSelfId)
+                        return;
+                    syncBrokerDbInbox(brokerSelfId, broker.db, ctx);
+                });
+                broker.server.onAgentStatusChange((changedAgentId, status) => {
+                    if (status === "idle") {
+                        runMaintenance(ctx);
+                    }
+                    deps.onAgentStatusChange(ctx, changedAgentId, status);
+                });
+                startBrokerHeartbeat();
+                startBrokerMaintenance(ctx);
+                startBrokerScheduledWakeups(ctx);
+                return {
+                    botUserId: adapterConnectResult.botUserId,
+                    recoveredBrokerMessages,
+                    recoveredTargetedBacklogCount,
+                    releasedBrokerClaims,
+                };
+            }
+            catch (error) {
+                try {
+                    if (selfId) {
+                        broker.db.unregisterAgent(selfId);
+                    }
+                }
+                catch {
+                    /* best effort */
+                }
+                try {
+                    await broker.stop();
+                }
+                catch {
+                    /* best effort */
+                }
+                activeBroker = null;
+                activeRouter = null;
+                activeSelfId = null;
+                lastBrokerMaintenance = null;
+                lastBrokerMaintenanceSignature = "";
+                resetBrokerDeliveryState(deps.deliveryState);
+                stopObservability();
+                throw error;
+            }
+        },
+        async disconnect(options = {}) {
+            await disconnect(options);
+        },
+        claimThread(threadTs, channelId, source = "slack") {
+            if (!activeRouter || !activeSelfId) {
+                return;
+            }
+            activeRouter.claimThread(threadTs, activeSelfId, channelId, source);
+        },
+        runMaintenance(ctx) {
+            runMaintenance(ctx);
+        },
+        markDelivered(inboxIds) {
+            if (!activeBroker || !activeSelfId || inboxIds.length === 0) {
+                return;
+            }
+            activeBroker.db.markDelivered(inboxIds, activeSelfId);
+            markBrokerInboxIdsHandled(deps.deliveryState, inboxIds);
+        },
+        startObservability(ctx) {
+            startObservability(ctx);
+        },
+        clearFollowUpPending() {
+            ralphLoopState.followUpPending = false;
+        },
+        logActivity(entry) {
+            if (!activeBroker) {
+                return;
+            }
+            ensureActivityLogger().log(entry);
+        },
+        getRecentActivityEntries(limit = 20) {
+            return activityLogger?.getRecentEntries(limit) ?? [];
+        },
+        getBroker() {
+            return activeBroker;
+        },
+        getSelfId() {
+            return activeSelfId;
+        },
+        getLastMaintenance() {
+            return lastBrokerMaintenance;
+        },
+        getRalphSnoozeStatus() {
+            return getRalphLoopSnoozeStatus(ralphLoopState);
+        },
+        snoozeRalphLoop(input) {
+            return setRalphLoopSnooze(ralphLoopState, {
+                durationMs: input.durationMs,
+                reason: input.reason,
+                source: "manual",
+            });
+        },
+        clearRalphSnooze() {
+            clearRalphLoopSnooze(ralphLoopState);
+            return getRalphLoopSnoozeStatus(ralphLoopState);
+        },
+        heartbeatTimerActive() {
+            return brokerHeartbeatTimer != null;
+        },
+        maintenanceTimerActive() {
+            return brokerMaintenanceTimer != null;
+        },
+        isConnected() {
+            return activeBroker != null;
+        },
+        getHomeTabViewerIds() {
+            return [...brokerControlPlaneHomeTabViewers.entries()].map(([userId]) => userId);
+        },
+        getLastHomeTabSnapshot() {
+            return lastBrokerControlPlaneHomeTabSnapshot;
+        },
+        setLastHomeTabSnapshot(snapshot) {
+            lastBrokerControlPlaneHomeTabSnapshot = snapshot;
+        },
+        getLastHomeTabRefreshAt() {
+            return lastBrokerControlPlaneHomeTabRefreshAt;
+        },
+        setLastHomeTabRefreshAt(value) {
+            lastBrokerControlPlaneHomeTabRefreshAt = value;
+        },
+        getLastHomeTabError() {
+            return lastBrokerControlPlaneHomeTabError;
+        },
+        setLastHomeTabError(value) {
+            lastBrokerControlPlaneHomeTabError = value;
+        },
+        async publishCurrentHomeTabSafely(userId, ctx, openedAt = new Date().toISOString()) {
+            return publishCurrentHomeTabSafely(userId, ctx, openedAt);
+        },
+    };
+}

package/dist/broker-thread-owner-hints.d.ts

@@ -0,0 +1,10 @@
+import type { ThreadOwnerHint } from "./broker/router.js";
+import { type SlackCall } from "./slack-access.js";
+export interface BrokerThreadOwnerHintsDeps {
+    slack: SlackCall;
+    getBotToken: () => string;
+}
+export interface BrokerThreadOwnerHints {
+    resolveBrokerThreadOwnerHint: (channel: string, threadTs: string) => Promise<ThreadOwnerHint | null>;
+}
+export declare function createBrokerThreadOwnerHints(deps: BrokerThreadOwnerHintsDeps): BrokerThreadOwnerHints;

package/dist/broker-thread-owner-hints.js

@@ -0,0 +1,14 @@
+import { resolveSlackThreadOwnerHint } from "./slack-access.js";
+export function createBrokerThreadOwnerHints(deps) {
+    async function resolveBrokerThreadOwnerHint(channel, threadTs) {
+        return resolveSlackThreadOwnerHint({
+            slack: deps.slack,
+            token: deps.getBotToken(),
+            channel,
+            threadTs,
+        });
+    }
+    return {
+        resolveBrokerThreadOwnerHint,
+    };
+}

package/dist/canvases.d.ts

@@ -0,0 +1,80 @@
+export interface SlackCanvasDocumentContent {
+    type: "markdown";
+    markdown: string;
+}
+export type SlackCanvasCreateMethod = "canvases.create" | "conversations.canvases.create";
+export type SlackCanvasCreateKind = "standalone" | "channel";
+export type SlackCanvasUpdateMode = "append" | "prepend" | "replace";
+export type SlackCanvasSectionType = "h1" | "h2" | "h3" | "any_header";
+export type SlackCanvasEditOperation = "insert_at_end" | "insert_at_start" | "replace";
+export interface SlackCanvasCommentRecord {
+    id?: string;
+    userId?: string;
+    createdTs?: string;
+    text: string;
+}
+export interface SlackCanvasCommentsPage {
+    canvasId: string;
+    title?: string;
+    permalink?: string;
+    commentsCount: number;
+    returnedCount: number;
+    page?: number;
+    pages?: number;
+    comments: SlackCanvasCommentRecord[];
+    nextCursor?: string;
+}
+export interface SlackCanvasCreateInput {
+    kind?: string;
+    title?: string;
+    markdown?: string;
+    channelId?: string;
+}
+export interface SlackCanvasCreateRequest {
+    kind: SlackCanvasCreateKind;
+    method: SlackCanvasCreateMethod;
+    body: {
+        title?: string;
+        channel_id?: string;
+        document_content?: SlackCanvasDocumentContent;
+    };
+}
+export interface SlackCanvasEditRequest {
+    canvas_id: string;
+    changes: [
+        {
+            operation: SlackCanvasEditOperation;
+            document_content: SlackCanvasDocumentContent;
+            section_id?: string;
+        }
+    ];
+}
+export interface SlackCanvasSectionLookupRequest {
+    canvas_id: string;
+    criteria: {
+        contains_text: string;
+        section_types?: SlackCanvasSectionType[];
+    };
+}
+export interface SlackCanvasSectionLookupResult {
+    id?: string;
+}
+export declare function normalizeSlackCanvasCreateKind(kind?: string): SlackCanvasCreateKind;
+export declare function normalizeSlackCanvasUpdateMode(mode?: string): SlackCanvasUpdateMode;
+export declare function normalizeSlackCanvasSectionType(type?: string): SlackCanvasSectionType | undefined;
+export declare function normalizeSlackCanvasCommentsLimit(limit?: number): number;
+export declare function buildSlackCanvasCreateRequest(input: SlackCanvasCreateInput): SlackCanvasCreateRequest;
+export declare function buildSlackCanvasEditRequest(input: {
+    canvasId: string;
+    markdown: string;
+    mode?: string;
+    sectionId?: string;
+}): SlackCanvasEditRequest;
+export declare function buildSlackCanvasSectionsLookupRequest(input: {
+    canvasId: string;
+    containsText: string;
+    sectionType?: string;
+}): SlackCanvasSectionLookupRequest;
+export declare function pickSlackCanvasSectionId(sections: SlackCanvasSectionLookupResult[] | undefined, sectionIndex?: number): string;
+export declare function extractSlackChannelCanvasId(response: Record<string, unknown>): string | null;
+export declare function extractSlackCanvasCommentsPage(response: Record<string, unknown>, fallbackCanvasId?: string): SlackCanvasCommentsPage;