@pinet/slack-bridge 0.1.0

package/dist/reaction-triggers.js

@@ -0,0 +1,171 @@
+const REACTION_ALIASES = {
+    "📝": "memo",
+    memo: "memo",
+    "🐛": "bug",
+    bug: "bug",
+    "🔍": "mag",
+    mag: "mag",
+    mag_right: "mag_right",
+    "📌": "pushpin",
+    pushpin: "pushpin",
+    "🌐": "globe_with_meridians",
+    globe_with_meridians: "globe_with_meridians",
+    "🔄": "repeat",
+    repeat: "repeat",
+    "👀": "eyes",
+    eyes: "eyes",
+    "✅": "white_check_mark",
+    white_check_mark: "white_check_mark",
+    "⬆️": "arrow_up",
+    "⬆": "arrow_up",
+    arrow_up: "arrow_up",
+    "🛑": "octagonal_sign",
+    octagonal_sign: "octagonal_sign",
+};
+const REACTION_DISPLAY = {
+    memo: "📝",
+    bug: "🐛",
+    mag: "🔍",
+    mag_right: "🔎",
+    pushpin: "📌",
+    globe_with_meridians: "🌐",
+    repeat: "🔄",
+    eyes: "👀",
+    white_check_mark: "✅",
+    arrow_up: "⬆️",
+    octagonal_sign: "🛑",
+};
+export const DEFAULT_REACTION_COMMANDS = {
+    memo: {
+        action: "summarize",
+        prompt: "Summarize the reacted-to message and the surrounding thread. Focus on key decisions, action items, and open questions.",
+    },
+    bug: {
+        action: "file-issue",
+        prompt: "Turn the reacted-to message or thread into a GitHub issue. Capture the problem, context, reproduction clues, and a sensible next step.",
+    },
+    eyes: {
+        action: "review",
+        prompt: "Review the referenced message, code, or work item and report what needs attention. If the context points to a PR or diff, review that artifact.",
+    },
+    white_check_mark: {
+        action: "approve",
+        prompt: "Evaluate whether the referenced work should be approved. If it looks good, say so clearly and note any final caveats.",
+    },
+    repeat: {
+        action: "retry",
+        prompt: "Retry or regenerate the requested work using the reacted message and surrounding thread as the source of truth.",
+    },
+    arrow_up: {
+        action: "steer",
+        prompt: "Treat the reacted-to message as steering. Read the durable message context, then prioritize it as an explicit operator instruction if it is relevant and safe.",
+    },
+    octagonal_sign: {
+        action: "interrupt",
+        prompt: "Interrupt the current owner process for the reacted Slack thread. Stop the active turn safely, then read the durable context before deciding whether more work is needed.",
+    },
+    mag: {
+        action: "search",
+        prompt: "Search the codebase for code related to the reacted message and report the most relevant files or findings.",
+    },
+    pushpin: {
+        action: "track",
+        prompt: "Treat the reacted message as something to preserve and track. Pin or record it in the most appropriate project artifact, such as a Slack canvas.",
+    },
+    globe_with_meridians: {
+        action: "fetch-url",
+        prompt: "If the reacted message contains a URL, fetch the linked page and summarize the important information for the user.",
+    },
+};
+function normalizeReactionNameOrNull(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    const withoutColons = trimmed.replace(/^:+|:+$/g, "").toLowerCase();
+    return (REACTION_ALIASES[trimmed] ??
+        REACTION_ALIASES[withoutColons] ??
+        (/^[a-z0-9_+-]+$/.test(withoutColons) ? withoutColons : null));
+}
+export function normalizeReactionName(input) {
+    const normalized = normalizeReactionNameOrNull(input);
+    if (!normalized) {
+        throw new Error(`Unsupported reaction ${JSON.stringify(input)}. Use a Slack reaction name like "eyes" or a supported emoji such as 👀, ✅, 🔄, 📝, 🐛, ⬆️, or 🛑.`);
+    }
+    return normalized;
+}
+function buildDefaultPromptForAction(action) {
+    switch (action) {
+        case "summarize":
+            return DEFAULT_REACTION_COMMANDS.memo.prompt;
+        case "file-issue":
+            return DEFAULT_REACTION_COMMANDS.bug.prompt;
+        case "review":
+            return DEFAULT_REACTION_COMMANDS.eyes.prompt;
+        case "approve":
+            return DEFAULT_REACTION_COMMANDS.white_check_mark.prompt;
+        case "retry":
+            return DEFAULT_REACTION_COMMANDS.repeat.prompt;
+        case "steer":
+            return DEFAULT_REACTION_COMMANDS.arrow_up.prompt;
+        case "interrupt":
+            return DEFAULT_REACTION_COMMANDS.octagonal_sign.prompt;
+        case "search":
+            return DEFAULT_REACTION_COMMANDS.mag.prompt;
+        case "track":
+            return DEFAULT_REACTION_COMMANDS.pushpin.prompt;
+        case "fetch-url":
+            return DEFAULT_REACTION_COMMANDS.globe_with_meridians.prompt;
+        default:
+            return `Carry out the "${action}" action for the reacted Slack message or thread, using the included context before you decide what to do.`;
+    }
+}
+export function resolveReactionCommands(settings) {
+    const resolved = new Map(Object.entries(DEFAULT_REACTION_COMMANDS));
+    if (!settings) {
+        return resolved;
+    }
+    for (const [rawReaction, config] of Object.entries(settings)) {
+        const normalizedReaction = normalizeReactionNameOrNull(rawReaction);
+        if (!normalizedReaction)
+            continue;
+        if (typeof config === "string") {
+            resolved.set(normalizedReaction, {
+                action: config,
+                prompt: buildDefaultPromptForAction(config),
+            });
+            continue;
+        }
+        if (!config || typeof config !== "object")
+            continue;
+        const action = config.action?.trim() || resolved.get(normalizedReaction)?.action || normalizedReaction;
+        const prompt = config.prompt?.trim() || buildDefaultPromptForAction(action);
+        resolved.set(normalizedReaction, { action, prompt });
+    }
+    return resolved;
+}
+export function formatReactionDisplay(reactionName) {
+    return `${REACTION_DISPLAY[reactionName] ?? `:${reactionName}:`} (:${reactionName}:)`;
+}
+export function buildReactionTriggerMessage(input) {
+    const reactedMessageText = input.reactedMessageText.trim() || "(no text)";
+    return [
+        "Reaction trigger from Slack:",
+        `- reaction: ${formatReactionDisplay(input.reactionName)}`,
+        `- action: ${input.command.action}`,
+        `- reactor: ${input.reactorName}`,
+        `- channel: <#${input.channel}>`,
+        `- thread_ts: ${input.threadTs}`,
+        `- message_ts: ${input.messageTs}`,
+        `- reacted_message_author: ${input.reactedMessageAuthor}`,
+        `- reacted_message_text: ${reactedMessageText}`,
+        "",
+        `Requested action: ${input.command.prompt}`,
+        "Treat this reaction as an explicit user request, but still verify context before acting.",
+    ].join("\n");
+}
+export function buildReactionPromptGuidelines() {
+    return [
+        "Reaction-triggered requests may appear in your Slack inbox as structured 'Reaction trigger from Slack:' messages.",
+        "Treat them as explicit user requests keyed off emoji reactions. Use the included action, reacted message text, and thread context to decide what to do.",
+    ];
+}

package/dist/repo-tool-guardrails.d.ts

@@ -0,0 +1,20 @@
+import { type SecurityGuardrails } from "./guardrails.js";
+import type { SlackToolPolicyTurn } from "./core-tool-guardrails.js";
+export declare const GUARDED_REPO_TOOLS: Set<string>;
+export declare function isGuardedRepoTool(toolName: string): boolean;
+export declare function summarizeRepoToolAction(event: {
+    toolName: string;
+    input: Record<string, unknown>;
+}): string;
+export declare function evaluateSlackOriginRepoToolPolicy(options: {
+    turn: SlackToolPolicyTurn | null;
+    toolName: string;
+    input: Record<string, unknown>;
+    guardrails: SecurityGuardrails;
+    requireToolPolicy: (toolName: string, threadTs: string | undefined, action: string) => void;
+    formatAction: (action: string) => string;
+    formatError: (error: unknown) => string;
+}): {
+    block: true;
+    reason: string;
+} | undefined;

package/dist/repo-tool-guardrails.js

@@ -0,0 +1,81 @@
+import { isToolBlocked, toolNeedsConfirmation } from "./guardrails.js";
+export const GUARDED_REPO_TOOLS = new Set([
+    "open_in_editor",
+    "comment_add",
+    "comment_list",
+    "comment_wipe_all",
+    "psql",
+]);
+export function isGuardedRepoTool(toolName) {
+    return GUARDED_REPO_TOOLS.has(toolName);
+}
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function clipValue(value, maxLength = 120) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength - 1).trimEnd()}…`;
+}
+export function summarizeRepoToolAction(event) {
+    const input = event.input;
+    switch (event.toolName) {
+        case "open_in_editor":
+            return `file=${String(input.file ?? "")} | line=${String(input.line ?? "")}`;
+        case "comment_add": {
+            const comment = typeof input.comment === "string" ? input.comment : "";
+            return [
+                `thread_id=${String(input.thread_id ?? "")}`,
+                `file=${String(input.file ?? "")}`,
+                `start_line=${String(input.start_line ?? "")}`,
+                `end_line=${String(input.end_line ?? "")}`,
+                `comment_length=${comment.length}`,
+            ].join(" | ");
+        }
+        case "comment_list":
+            return `thread_id=${String(input.thread_id ?? "")} | limit=${String(input.limit ?? "")}`;
+        case "comment_wipe_all":
+            return "scope=current_repo";
+        case "psql": {
+            const query = typeof input.query === "string" ? normalizeWhitespace(input.query) : "";
+            return `format=${String(input.format ?? "table")} | query=${clipValue(query)}`;
+        }
+        default:
+            return JSON.stringify(input);
+    }
+}
+export function evaluateSlackOriginRepoToolPolicy(options) {
+    const { turn, toolName, input, guardrails, requireToolPolicy, formatAction, formatError } = options;
+    if (!turn || !isGuardedRepoTool(toolName)) {
+        return undefined;
+    }
+    if (isToolBlocked(toolName, guardrails)) {
+        return {
+            block: true,
+            reason: `Tool "${toolName}" is blocked by Slack security guardrails.`,
+        };
+    }
+    if (!toolNeedsConfirmation(toolName, guardrails)) {
+        return undefined;
+    }
+    const action = summarizeRepoToolAction({ toolName, input });
+    if (!turn.threadTs) {
+        return {
+            block: true,
+            reason: turn.threadCount > 1
+                ? `Tool "${toolName}" requires Slack confirmation for action ${formatAction(action)}, but this Slack-triggered turn currently batches ${turn.threadCount} threads. Process one Slack thread at a time before using that tool.`
+                : `Tool "${toolName}" requires Slack confirmation for action ${formatAction(action)}, but there is no tracked Slack thread available for this turn. Retry from a specific Slack thread and call slack with action "confirm_action" there first.`,
+        };
+    }
+    try {
+        requireToolPolicy(toolName, turn.threadTs, action);
+        return undefined;
+    }
+    catch (error) {
+        return {
+            block: true,
+            reason: formatError(error),
+        };
+    }
+}

package/dist/runtime-agent-context.d.ts

@@ -0,0 +1,93 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type GitContext, type GitDynamicState } from "./git-metadata.js";
+import { type PinetSkinStatusVocabulary, type SlackBridgeSettings } from "./helpers.js";
+import { type SecurityGuardrails } from "./guardrails.js";
+import type { SinglePlayerThreadInfo } from "./single-player-runtime.js";
+export type RuntimeAgentRole = "broker" | "worker";
+export type ReactionCommandMap = Map<string, {
+    action: string;
+    prompt: string;
+}>;
+export interface ReloadableRuntimeSnapshot {
+    settings: SlackBridgeSettings;
+    botToken: string | undefined;
+    appToken: string | undefined;
+    allowedUsers: Set<string> | null;
+    guardrails: SecurityGuardrails;
+    reactionCommands: ReactionCommandMap;
+    securityPrompt: string;
+    agentName: string;
+    agentEmoji: string;
+    activeSkinTheme: string | null;
+    agentPersonality: string | null;
+    agentAliases: string[];
+}
+export interface RuntimeAgentContextDeps {
+    cwd: string;
+    getSettings: () => SlackBridgeSettings;
+    setSettings: (settings: SlackBridgeSettings) => void;
+    getBotToken: () => string | undefined;
+    setBotToken: (token: string | undefined) => void;
+    getAppToken: () => string | undefined;
+    setAppToken: (token: string | undefined) => void;
+    getAllowedUsers: () => Set<string> | null;
+    setAllowedUsers: (users: Set<string> | null) => void;
+    getGuardrails: () => SecurityGuardrails;
+    setGuardrails: (guardrails: SecurityGuardrails) => void;
+    getReactionCommands: () => ReactionCommandMap;
+    setReactionCommands: (commands: ReactionCommandMap) => void;
+    getSecurityPrompt: () => string;
+    setSecurityPrompt: (prompt: string) => void;
+    getAgentName: () => string;
+    setAgentName: (name: string) => void;
+    getAgentEmoji: () => string;
+    setAgentEmoji: (emoji: string) => void;
+    getAgentStableId: () => string;
+    getBrokerStableId: () => string;
+    getBrokerRole: () => "broker" | "follower" | null;
+    getAgentOwnerToken: () => string;
+    setAgentOwnerToken: (ownerToken: string) => void;
+    getActiveSkinTheme: () => string | null;
+    setActiveSkinTheme: (theme: string | null) => void;
+    getAgentPersonality: () => string | null;
+    setAgentPersonality: (personality: string | null) => void;
+    getAgentAliases: () => Set<string>;
+    getThreads: () => Map<string, SinglePlayerThreadInfo>;
+    getExtensionContext: () => ExtensionContext | null;
+    persistState: () => void;
+    updateBadge: () => void;
+    getGitContext: () => Promise<GitContext>;
+    /** Optional test hook for live branch/dirty probing. */
+    getDynamicGitState?: (cwd: string) => Promise<GitDynamicState>;
+}
+export interface RuntimeAgentContext {
+    isUserAllowed: (userId: string) => boolean;
+    maybeWarnSlackUserAccess: (ctx?: ExtensionContext) => void;
+    maybeWarnSlackGuardrailPosture: (ctx?: ExtensionContext) => void;
+    getStableIdForRole: (role: RuntimeAgentRole) => string;
+    getIdentitySeedForRole: (role: RuntimeAgentRole, sessionFile?: string) => string;
+    getSkinSeed: (preferredSeed?: string) => string;
+    rememberAgentAlias: (name: string | undefined) => void;
+    resolveSkinAssignment: (role: RuntimeAgentRole, seed?: string) => {
+        name: string;
+        emoji: string;
+        personality: string;
+        statusVocabulary?: PinetSkinStatusVocabulary;
+    } | null;
+    applyLocalAgentIdentity: (nextName: string, nextEmoji: string, nextPersonality: string | null) => void;
+    refreshSettings: () => void;
+    snapshotReloadableRuntime: () => ReloadableRuntimeSnapshot;
+    restoreReloadableRuntime: (snapshot: ReloadableRuntimeSnapshot) => void;
+    detectProjectTools: (repoRoot: string, cwd: string) => string[];
+    getAgentMetadata: (role?: RuntimeAgentRole) => Promise<Record<string, unknown>>;
+    asStringValue: (value: unknown) => string | undefined;
+    getMeshRoleFromMetadata: (metadata: Record<string, unknown> | undefined, fallback?: RuntimeAgentRole) => RuntimeAgentRole;
+    buildSkinMetadata: (metadata: Record<string, unknown> | undefined, personality: string, statusVocabulary?: PinetSkinStatusVocabulary) => Record<string, unknown>;
+    getIdentityGuidelines: () => [string, string, string];
+    applyRegistrationIdentity: (registration: {
+        name: string;
+        emoji: string;
+        metadata?: Record<string, unknown> | null;
+    }) => void;
+}
+export declare function createRuntimeAgentContext(deps: RuntimeAgentContextDeps): RuntimeAgentContext;

package/dist/runtime-agent-context.js

@@ -0,0 +1,302 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { probeGitDynamic } from "./git-metadata.js";
+import { buildAllowlist, buildIdentityReplyGuidelines, buildPinetOwnerToken, buildPinetSkinAssignment, buildSlackCompatibilityScope, getSlackUserAccessWarning, isUserAllowed as checkUserAllowed, loadSettings as loadSettingsFromFile, normalizeOwnedThreads, normalizePinetSkinTheme, resolveRuntimeAgentIdentity, shortenPath, } from "./helpers.js";
+import { buildSecurityPrompt, getEmptyRuntimeGuardrailsWarning, } from "./guardrails.js";
+import { resolveReactionCommands } from "./reaction-triggers.js";
+export function createRuntimeAgentContext(deps) {
+    let lastSlackUserAccessWarning = "";
+    let lastSlackGuardrailPostureWarning = "";
+    const selfLocation = `${shortenPath(deps.cwd, os.homedir())}@${os.hostname()}`;
+    function isUserAllowed(userId) {
+        return checkUserAllowed(deps.getAllowedUsers(), userId);
+    }
+    function maybeWarnSlackUserAccess(ctx) {
+        const warning = getSlackUserAccessWarning(deps.getAllowedUsers());
+        if (!warning) {
+            lastSlackUserAccessWarning = "";
+            return;
+        }
+        if (warning === lastSlackUserAccessWarning) {
+            return;
+        }
+        lastSlackUserAccessWarning = warning;
+        console.warn(`[slack-bridge] ${warning}`);
+        ctx?.ui.notify(warning, "warning");
+    }
+    function maybeWarnSlackGuardrailPosture(ctx) {
+        const botToken = deps.getBotToken()?.trim();
+        const appToken = deps.getAppToken()?.trim();
+        const allowlist = deps.getAllowedUsers();
+        const hasAdmittedUsers = allowlist === null || allowlist.size > 0;
+        const warning = botToken && appToken && hasAdmittedUsers
+            ? getEmptyRuntimeGuardrailsWarning(deps.getGuardrails())
+            : null;
+        if (!warning) {
+            lastSlackGuardrailPostureWarning = "";
+            return;
+        }
+        if (warning === lastSlackGuardrailPostureWarning) {
+            return;
+        }
+        lastSlackGuardrailPostureWarning = warning;
+        console.warn(`[slack-bridge] ${warning}`);
+        ctx?.ui.notify(warning, "warning");
+    }
+    function getStableIdForRole(role) {
+        return role === "broker" ? deps.getBrokerStableId() : deps.getAgentStableId();
+    }
+    function getIdentitySeedForRole(role, sessionFile = deps.getExtensionContext()?.sessionManager.getSessionFile() ?? undefined) {
+        return role === "broker" ? deps.getBrokerStableId() : (sessionFile ?? deps.getAgentStableId());
+    }
+    function getSkinSeed(preferredSeed) {
+        return (preferredSeed?.trim() ||
+            getStableIdForRole(deps.getBrokerRole() === "broker" ? "broker" : "worker"));
+    }
+    function rememberAgentAlias(name) {
+        const trimmed = name?.trim();
+        if (!trimmed || trimmed === deps.getAgentName()) {
+            return;
+        }
+        const agentAliases = deps.getAgentAliases();
+        agentAliases.add(trimmed);
+        while (agentAliases.size > 24) {
+            const oldest = agentAliases.values().next().value;
+            if (!oldest) {
+                break;
+            }
+            agentAliases.delete(oldest);
+        }
+    }
+    function resolveSkinAssignment(role, seed = getSkinSeed()) {
+        const activeSkinTheme = deps.getActiveSkinTheme();
+        if (!activeSkinTheme) {
+            return null;
+        }
+        const assignment = buildPinetSkinAssignment({ theme: activeSkinTheme, role, seed });
+        return {
+            name: assignment.name,
+            emoji: assignment.emoji,
+            personality: assignment.personality,
+            statusVocabulary: assignment.statusVocabulary,
+        };
+    }
+    function applyLocalAgentIdentity(nextName, nextEmoji, nextPersonality) {
+        const previousName = deps.getAgentName();
+        if (previousName === nextName &&
+            deps.getAgentEmoji() === nextEmoji &&
+            (deps.getAgentPersonality() ?? null) === (nextPersonality ?? null)) {
+            return;
+        }
+        deps.setAgentName(nextName);
+        deps.setAgentEmoji(nextEmoji);
+        deps.setAgentPersonality(nextPersonality ?? null);
+        rememberAgentAlias(previousName);
+        normalizeOwnedThreads(deps.getThreads().values(), deps.getAgentName(), deps.getAgentOwnerToken(), deps.getAgentAliases());
+        deps.persistState();
+        deps.updateBadge();
+    }
+    function refreshSettings() {
+        const settings = loadSettingsFromFile();
+        deps.setSettings(settings);
+        deps.setBotToken(settings.botToken ?? process.env.SLACK_BOT_TOKEN);
+        deps.setAppToken(settings.appToken ?? process.env.SLACK_APP_TOKEN);
+        deps.setAllowedUsers(buildAllowlist(settings, process.env.SLACK_ALLOWED_USERS, process.env.SLACK_ALLOW_ALL_WORKSPACE_USERS));
+        const guardrails = settings.security ?? {};
+        deps.setGuardrails(guardrails);
+        deps.setReactionCommands(resolveReactionCommands(settings.reactionCommands));
+        deps.setSecurityPrompt(buildSecurityPrompt(guardrails));
+        const configuredSkinTheme = normalizePinetSkinTheme(settings.skinTheme);
+        deps.setActiveSkinTheme(configuredSkinTheme);
+        const role = deps.getBrokerRole() === "broker" ? "broker" : "worker";
+        const identitySeed = getIdentitySeedForRole(role);
+        const skinIdentity = resolveSkinAssignment(role, identitySeed);
+        if (skinIdentity) {
+            deps.setAgentName(skinIdentity.name);
+            deps.setAgentEmoji(skinIdentity.emoji);
+            deps.setAgentPersonality(skinIdentity.personality);
+            return;
+        }
+        const refreshedIdentity = resolveRuntimeAgentIdentity({ name: deps.getAgentName(), emoji: deps.getAgentEmoji() }, settings, process.env.PI_NICKNAME, identitySeed, role);
+        deps.setAgentName(refreshedIdentity.name);
+        deps.setAgentEmoji(refreshedIdentity.emoji);
+        deps.setAgentPersonality(null);
+    }
+    function snapshotReloadableRuntime() {
+        return {
+            settings: structuredClone(deps.getSettings()),
+            botToken: deps.getBotToken(),
+            appToken: deps.getAppToken(),
+            allowedUsers: deps.getAllowedUsers() ? new Set(deps.getAllowedUsers()) : null,
+            guardrails: structuredClone(deps.getGuardrails()),
+            reactionCommands: new Map(deps.getReactionCommands()),
+            securityPrompt: deps.getSecurityPrompt(),
+            agentName: deps.getAgentName(),
+            agentEmoji: deps.getAgentEmoji(),
+            activeSkinTheme: deps.getActiveSkinTheme(),
+            agentPersonality: deps.getAgentPersonality(),
+            agentAliases: [...deps.getAgentAliases()],
+        };
+    }
+    function restoreReloadableRuntime(snapshot) {
+        deps.setSettings(structuredClone(snapshot.settings));
+        deps.setBotToken(snapshot.botToken);
+        deps.setAppToken(snapshot.appToken);
+        deps.setAllowedUsers(snapshot.allowedUsers ? new Set(snapshot.allowedUsers) : null);
+        deps.setGuardrails(structuredClone(snapshot.guardrails));
+        deps.setReactionCommands(new Map(snapshot.reactionCommands));
+        deps.setSecurityPrompt(snapshot.securityPrompt);
+        deps.setAgentName(snapshot.agentName);
+        deps.setAgentEmoji(snapshot.agentEmoji);
+        deps.setActiveSkinTheme(snapshot.activeSkinTheme);
+        deps.setAgentPersonality(snapshot.agentPersonality);
+        deps.setAgentOwnerToken(buildPinetOwnerToken(getStableIdForRole(deps.getBrokerRole() === "broker" ? "broker" : "worker")));
+        const agentAliases = deps.getAgentAliases();
+        agentAliases.clear();
+        for (const alias of snapshot.agentAliases) {
+            if (alias && alias !== deps.getAgentName()) {
+                agentAliases.add(alias);
+            }
+        }
+    }
+    function detectProjectTools(repoRoot, cwd) {
+        const tools = new Set();
+        for (const candidate of [path.join(cwd, "package.json"), path.join(repoRoot, "package.json")]) {
+            try {
+                if (!fs.existsSync(candidate)) {
+                    continue;
+                }
+                const parsed = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+                const scripts = parsed.scripts ?? {};
+                if (scripts.test)
+                    tools.add("test");
+                if (scripts.lint)
+                    tools.add("lint");
+                if (scripts.typecheck)
+                    tools.add("typecheck");
+                if (scripts.build)
+                    tools.add("build");
+            }
+            catch {
+                // Ignore unreadable package.json files.
+            }
+        }
+        tools.add("git");
+        return [...tools].sort();
+    }
+    const dynamicGitProbe = deps.getDynamicGitState ?? ((cwd) => probeGitDynamic(cwd));
+    async function getAgentMetadata(role = "worker") {
+        const gitContext = await deps.getGitContext();
+        const { cwd, repo, repoRoot } = gitContext;
+        const resolvedRepoRoot = repoRoot ?? cwd;
+        const tools = detectProjectTools(resolvedRepoRoot, cwd);
+        const scope = buildSlackCompatibilityScope();
+        let dynamic;
+        try {
+            dynamic = await dynamicGitProbe(cwd);
+        }
+        catch {
+            dynamic = { probeFailed: true };
+        }
+        const branch = dynamic.branch;
+        const workdirDirty = dynamic.dirty;
+        const gitProbeFailed = dynamic.probeFailed;
+        const tags = [
+            `role:${role}`,
+            `repo:${repo}`,
+            ...(branch ? [`branch:${branch}`] : []),
+            ...(workdirDirty === true ? ["workdir:dirty"] : []),
+            ...(gitProbeFailed ? ["git-probe-failed"] : []),
+            ...(scope.workspace?.provider ? [`scope-provider:${scope.workspace.provider}`] : []),
+            ...(scope.workspace?.compatibilityKey ? [`scope:${scope.workspace.compatibilityKey}`] : []),
+            ...tools.map((tool) => `tool:${tool}`),
+        ];
+        const skinAssignment = resolveSkinAssignment(role, getIdentitySeedForRole(role));
+        const brokerManaged = role === "worker" && process.env.PINET_BROKER_MANAGED === "1";
+        const brokerManagedMetadata = brokerManaged
+            ? {
+                brokerManaged: true,
+                brokerManagedBy: process.env.PINET_BROKER_AGENT_ID?.trim() || undefined,
+                launchSource: process.env.PINET_LAUNCH_SOURCE?.trim() || "broker-tmux",
+                tmuxSession: process.env.PINET_TMUX_SESSION?.trim() || undefined,
+                brokerManagedAt: new Date().toISOString(),
+            }
+            : {};
+        return {
+            cwd,
+            ...(branch ? { branch } : {}),
+            ...(typeof workdirDirty === "boolean" ? { workdirDirty } : {}),
+            ...(typeof dynamic.dirtyFileCount === "number"
+                ? { workdirDirtyFileCount: dynamic.dirtyFileCount }
+                : {}),
+            ...(gitProbeFailed ? { gitProbeFailed: true } : {}),
+            gitProbedAt: new Date().toISOString(),
+            host: os.hostname(),
+            role,
+            repo,
+            repoRoot,
+            scope,
+            ...brokerManagedMetadata,
+            ...(deps.getActiveSkinTheme() ? { skinTheme: deps.getActiveSkinTheme() } : {}),
+            ...(deps.getAgentPersonality() ? { personality: deps.getAgentPersonality() } : {}),
+            ...(skinAssignment?.statusVocabulary
+                ? { skinStatusVocabulary: skinAssignment.statusVocabulary }
+                : {}),
+            capabilities: {
+                repo,
+                repoRoot,
+                ...(branch ? { branch } : {}),
+                ...(typeof workdirDirty === "boolean" ? { workdirDirty } : {}),
+                role,
+                tools,
+                tags,
+                scope,
+            },
+        };
+    }
+    function asStringValue(value) {
+        return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+    }
+    function getMeshRoleFromMetadata(metadata, fallback = "worker") {
+        return asStringValue(metadata?.role) === "broker" ? "broker" : fallback;
+    }
+    function buildSkinMetadata(metadata, personality, statusVocabulary) {
+        const baseMetadata = { ...(metadata ?? {}) };
+        delete baseMetadata.skinStatusVocabulary;
+        return {
+            ...baseMetadata,
+            ...(deps.getActiveSkinTheme() ? { skinTheme: deps.getActiveSkinTheme() } : {}),
+            personality,
+            ...(statusVocabulary ? { skinStatusVocabulary: statusVocabulary } : {}),
+        };
+    }
+    function getIdentityGuidelines() {
+        return buildIdentityReplyGuidelines(deps.getAgentEmoji(), deps.getAgentName(), selfLocation);
+    }
+    function applyRegistrationIdentity(registration) {
+        deps.setActiveSkinTheme(asStringValue(registration.metadata?.skinTheme) ?? null);
+        applyLocalAgentIdentity(registration.name, registration.emoji, asStringValue(registration.metadata?.personality) ?? null);
+    }
+    return {
+        isUserAllowed,
+        maybeWarnSlackUserAccess,
+        maybeWarnSlackGuardrailPosture,
+        getStableIdForRole,
+        getIdentitySeedForRole,
+        getSkinSeed,
+        rememberAgentAlias,
+        resolveSkinAssignment,
+        applyLocalAgentIdentity,
+        refreshSettings,
+        snapshotReloadableRuntime,
+        restoreReloadableRuntime,
+        detectProjectTools,
+        getAgentMetadata,
+        asStringValue,
+        getMeshRoleFromMetadata,
+        buildSkinMetadata,
+        getIdentityGuidelines,
+        applyRegistrationIdentity,
+    };
+}

package/dist/runtime-mode.d.ts

@@ -0,0 +1,10 @@
+import type { SlackBridgeSettings } from "./helpers.js";
+export type SlackBridgeRuntimeMode = "off" | "single" | "broker" | "follower";
+export declare function normalizeSlackBridgeRuntimeMode(value: string | null | undefined): SlackBridgeRuntimeMode | null;
+export declare function isPinetRuntimeMode(mode: SlackBridgeRuntimeMode): boolean;
+export interface ResolveSlackBridgeStartupRuntimeModeOptions {
+    brokerSocketExists?: boolean;
+    brokerManagedFollowerLaunch?: boolean;
+}
+export declare function isBrokerManagedFollowerLaunch(env?: NodeJS.ProcessEnv): boolean;
+export declare function resolveSlackBridgeStartupRuntimeMode(settings: Pick<SlackBridgeSettings, "runtimeMode" | "autoConnect" | "autoFollow">, options?: ResolveSlackBridgeStartupRuntimeModeOptions): SlackBridgeRuntimeMode;