@pinet/slack-bridge 0.1.0

package/dist/task-assignments.js

@@ -0,0 +1,527 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const WORKTREE_BRANCH_REGEX = /\bgit\s+worktree\s+add\b[^\n]*?\s-b\s+([^\s`"',;]+)/i;
+const CHECKOUT_BRANCH_REGEX = /\bgit\s+(?:checkout|switch)\s+-[cb]\s+([^\s`"',;]+)/i;
+const EXPLICIT_BRANCH_LABEL_REGEX = /\bbranch(?:\s+to\s+work\s+on|\s+name)?\s*:\s*[`"']?([A-Za-z0-9._/-]+)\b/i;
+const ISSUE_PR_LINE_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?issue\/pr\s*:\s*#(\d+)\b/gi;
+const ISSUE_LINE_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?issue\s*:\s*#(\d+)\b/gi;
+const ISSUE_HEADING_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?issue\s+#(\d+)(?=\s*(?:[—–:-]|$))/gi;
+const TASK_ISSUE_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?task\s*:\s*[^\n#]*\bissue\s*#(\d+)\b/gi;
+const NEW_TASK_ISSUE_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?new(?:\s+[a-z-]+){0,3}\s+task\b[^\n#]*\bissue\s*#(\d+)\b/gi;
+const FOLLOW_UP_TASK_ISSUE_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?follow-up\s+task(?:\s+from)?\s+issue\s*#(\d+)\b/gi;
+const GITHUB_REPO_URL_REGEX = /github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/(?:issues|pull)\/(\d+)\b/gi;
+const GITHUB_REPO_ISSUE_URL_REGEX = /github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/(\d+)\b/gi;
+const REPO_LABEL_REGEX = /(?:^|\n)\s*(?:[-*]\s*)?(?:repo|repository)\s*:\s*(?:https?:\/\/github\.com\/)?([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\b/i;
+const READ_ONLY_REVIEW_REGEX = /\b(?:read-only|do not mutate|do not edit|review-only|review only|second-pass|second pass|code review)\b/i;
+const REVIEW_TASK_REGEX = /\b(?:review|code review)\b/i;
+const QA_ONLY_TASK_REGEX = /\b(?:qa-only|qa only|test-only|test only|verify-only|verify only|validation-only|validation only)\b/i;
+const QA_TASK_REGEX = /\b(?:qa|test|verify|validation|visual verify|visual verification)\b/i;
+const MERGE_TASK_REGEX = /\bmerge\s+pr\s*#?\d+|\bmerge-only\b|\bmerge only\b/i;
+const INTERACTIVE_TASK_REGEX = /\b(?:interactive-session|human-gated|manual|browser session)\b/i;
+const IMPLEMENTATION_TASK_REGEX = /\b(?:implementation lane|implement|fix|build|change|patch|create a pr|open a pr|branch|worktree)\b/i;
+async function runCommand(file, args, cwd, runner) {
+    try {
+        const result = await runner(file, args, { cwd, encoding: "utf-8" });
+        const stdout = typeof result.stdout === "string" ? result.stdout : result.stdout?.toString();
+        const trimmed = stdout?.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runJsonCommand(file, args, cwd, runner) {
+    const stdout = await runCommand(file, args, cwd, runner);
+    if (!stdout) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeMessageForTaskParsing(message) {
+    return message.replace(/\r\n/g, "\n").replace(/[`*_]/g, "");
+}
+function parseBranch(message) {
+    const normalized = normalizeMessageForTaskParsing(message);
+    const match = normalized.match(WORKTREE_BRANCH_REGEX) ??
+        normalized.match(CHECKOUT_BRANCH_REGEX) ??
+        normalized.match(EXPLICIT_BRANCH_LABEL_REGEX);
+    const branch = match?.[1]?.trim().replace(/[.,;:]+$/, "");
+    return branch ? branch : null;
+}
+function parseIssueNumbers(message) {
+    const normalized = normalizeMessageForTaskParsing(message);
+    const issueNumbers = new Set();
+    for (const regex of [
+        ISSUE_PR_LINE_REGEX,
+        ISSUE_LINE_REGEX,
+        ISSUE_HEADING_REGEX,
+        TASK_ISSUE_REGEX,
+        NEW_TASK_ISSUE_REGEX,
+        FOLLOW_UP_TASK_ISSUE_REGEX,
+    ]) {
+        for (const match of normalized.matchAll(regex)) {
+            const issueNumber = Number(match[1]);
+            if (Number.isFinite(issueNumber)) {
+                issueNumbers.add(issueNumber);
+            }
+        }
+    }
+    for (const match of normalized.matchAll(GITHUB_REPO_ISSUE_URL_REGEX)) {
+        const issueNumber = Number(match[3]);
+        if (Number.isFinite(issueNumber)) {
+            issueNumbers.add(issueNumber);
+        }
+    }
+    return [...issueNumbers].sort((left, right) => left - right);
+}
+function parseRepo(message, issueNumber) {
+    const normalized = normalizeMessageForTaskParsing(message);
+    for (const match of normalized.matchAll(GITHUB_REPO_ISSUE_URL_REGEX)) {
+        if (Number(match[3]) === issueNumber) {
+            return { repoOwner: match[1] ?? null, repoName: match[2] ?? null };
+        }
+    }
+    const repoMatch = normalized.match(REPO_LABEL_REGEX);
+    if (repoMatch) {
+        return { repoOwner: repoMatch[1] ?? null, repoName: repoMatch[2] ?? null };
+    }
+    const urlRepos = new Map();
+    for (const match of normalized.matchAll(GITHUB_REPO_URL_REGEX)) {
+        if (match[1] && match[2]) {
+            urlRepos.set(`${match[1].toLowerCase()}/${match[2].toLowerCase()}`, {
+                repoOwner: match[1],
+                repoName: match[2],
+            });
+        }
+    }
+    if (urlRepos.size === 1) {
+        return [...urlRepos.values()][0] ?? { repoOwner: null, repoName: null };
+    }
+    return { repoOwner: null, repoName: null };
+}
+function parseTaskKind(message, branch) {
+    const normalized = normalizeMessageForTaskParsing(message);
+    if (MERGE_TASK_REGEX.test(normalized))
+        return "merge";
+    if (INTERACTIVE_TASK_REGEX.test(normalized))
+        return "interactive";
+    if (READ_ONLY_REVIEW_REGEX.test(normalized))
+        return "review";
+    if (QA_ONLY_TASK_REGEX.test(normalized))
+        return "qa";
+    if (branch || IMPLEMENTATION_TASK_REGEX.test(normalized))
+        return "implementation";
+    if (REVIEW_TASK_REGEX.test(normalized))
+        return "review";
+    if (QA_TASK_REGEX.test(normalized))
+        return "qa";
+    return "unknown";
+}
+export function extractTaskAssignmentsFromMessage(message) {
+    const branch = parseBranch(message);
+    const taskKind = parseTaskKind(message, branch);
+    return parseIssueNumbers(message).map((issueNumber) => ({
+        issueNumber,
+        branch,
+        ...parseRepo(message, issueNumber),
+        taskKind,
+    }));
+}
+function compareTaskAssignmentRecency(left, right) {
+    const updatedAt = Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+    if (updatedAt !== 0) {
+        return updatedAt;
+    }
+    const createdAt = Date.parse(right.createdAt) - Date.parse(left.createdAt);
+    if (createdAt !== 0) {
+        return createdAt;
+    }
+    return right.id - left.id;
+}
+function canonicalizeTaskAssignmentFromSourceMessage(assignment, sourceMessagesById) {
+    if (assignment.sourceMessageId == null) {
+        return assignment;
+    }
+    const sourceMessage = sourceMessagesById.get(assignment.sourceMessageId);
+    if (!sourceMessage) {
+        return assignment;
+    }
+    const parsedAssignments = extractTaskAssignmentsFromMessage(sourceMessage);
+    if (parsedAssignments.length === 0) {
+        return null;
+    }
+    const matchingAssignment = parsedAssignments.find((candidate) => candidate.issueNumber === assignment.issueNumber);
+    if (matchingAssignment) {
+        return {
+            ...assignment,
+            branch: matchingAssignment.branch,
+            repoOwner: matchingAssignment.repoOwner ?? assignment.repoOwner,
+            repoName: matchingAssignment.repoName ?? assignment.repoName,
+            taskKind: matchingAssignment.taskKind,
+        };
+    }
+    if (parsedAssignments.length === 1) {
+        const [canonicalAssignment] = parsedAssignments;
+        return {
+            ...assignment,
+            issueNumber: canonicalAssignment.issueNumber,
+            branch: canonicalAssignment.branch,
+            repoOwner: canonicalAssignment.repoOwner ?? assignment.repoOwner,
+            repoName: canonicalAssignment.repoName ?? assignment.repoName,
+            taskKind: canonicalAssignment.taskKind,
+        };
+    }
+    return null;
+}
+export function normalizeTrackedTaskAssignments(assignments, sourceMessagesById = new Map()) {
+    const canonicalAssignments = assignments
+        .map((assignment) => canonicalizeTaskAssignmentFromSourceMessage(assignment, sourceMessagesById))
+        .filter((assignment) => assignment != null)
+        .sort(compareTaskAssignmentRecency);
+    const visibleAssignments = [];
+    const seenIssueKeys = new Set();
+    for (const assignment of canonicalAssignments) {
+        const repoKey = assignment.repoOwner && assignment.repoName
+            ? `${assignment.repoOwner.toLowerCase()}/${assignment.repoName.toLowerCase()}`
+            : assignment.repoRoot
+                ? `root:${assignment.repoRoot}`
+                : "repo_unknown";
+        const issueKey = `${repoKey}#${assignment.issueNumber}`;
+        if (seenIssueKeys.has(issueKey)) {
+            continue;
+        }
+        seenIssueKeys.add(issueKey);
+        visibleAssignments.push(assignment);
+    }
+    return visibleAssignments;
+}
+function normalizePullRequests(prs) {
+    if (!Array.isArray(prs)) {
+        return [];
+    }
+    return prs.filter((pr) => typeof pr?.number === "number" &&
+        typeof pr?.state === "string" &&
+        typeof pr?.headRefName === "string");
+}
+function chooseBestPullRequest(prs) {
+    if (prs.length === 0) {
+        return null;
+    }
+    const score = (pr) => {
+        if (pr.mergedAt)
+            return 3;
+        if (pr.state.toUpperCase() === "OPEN")
+            return 2;
+        return 1;
+    };
+    return ([...prs].sort((left, right) => {
+        const byScore = score(right) - score(left);
+        if (byScore !== 0)
+            return byScore;
+        const leftMergedAt = left.mergedAt ? Date.parse(left.mergedAt) : 0;
+        const rightMergedAt = right.mergedAt ? Date.parse(right.mergedAt) : 0;
+        if (rightMergedAt !== leftMergedAt)
+            return rightMergedAt - leftMergedAt;
+        return right.number - left.number;
+    })[0] ?? null);
+}
+async function resolveBaseRef(cwd, runner) {
+    for (const ref of ["origin/main", "main"]) {
+        const resolved = await runCommand("git", ["rev-parse", "--verify", "--quiet", ref], cwd, runner);
+        if (resolved) {
+            return ref;
+        }
+    }
+    return null;
+}
+async function getBranchAheadCount(branch, baseRef, cwd, runner) {
+    if (!branch || !baseRef) {
+        return 0;
+    }
+    let maxAheadCount = 0;
+    const refs = [...new Set([branch, `origin/${branch}`])];
+    for (const ref of refs) {
+        const resolved = await runCommand("git", ["rev-parse", "--verify", "--quiet", ref], cwd, runner);
+        if (!resolved) {
+            continue;
+        }
+        const count = await runCommand("git", ["rev-list", "--count", `${baseRef}..${ref}`], cwd, runner);
+        const aheadCount = Number.parseInt(count ?? "0", 10);
+        if (Number.isFinite(aheadCount) && aheadCount > maxAheadCount) {
+            maxAheadCount = aheadCount;
+        }
+    }
+    return maxAheadCount;
+}
+function getRepoArg(assignment) {
+    return assignment.repoOwner && assignment.repoName
+        ? ["--repo", `${assignment.repoOwner}/${assignment.repoName}`]
+        : [];
+}
+async function getPullRequestForBranch(assignment, cwd, runner) {
+    if (!assignment.branch) {
+        return null;
+    }
+    const rawPrs = await runJsonCommand("gh", [
+        "pr",
+        "list",
+        ...getRepoArg(assignment),
+        "--head",
+        assignment.branch,
+        "--state",
+        "all",
+        "--json",
+        "number,state,mergedAt,headRefName",
+    ], cwd, runner);
+    if (rawPrs === undefined) {
+        return undefined;
+    }
+    const prs = normalizePullRequests(rawPrs);
+    return chooseBestPullRequest(prs);
+}
+async function getPullRequestByNumber(prNumber, assignment, cwd, runner) {
+    const pr = await runJsonCommand("gh", [
+        "pr",
+        "view",
+        String(prNumber),
+        ...getRepoArg(assignment),
+        "--json",
+        "number,state,mergedAt,headRefName",
+    ], cwd, runner);
+    if (pr === undefined) {
+        return undefined;
+    }
+    return normalizePullRequests([pr])[0] ?? null;
+}
+async function getIssueByNumber(assignment, cwd, runner) {
+    const issue = await runJsonCommand("gh", [
+        "issue",
+        "view",
+        String(assignment.issueNumber),
+        ...getRepoArg(assignment),
+        "--json",
+        "number,state",
+    ], cwd, runner);
+    if (issue === undefined) {
+        return undefined;
+    }
+    if (issue && typeof issue.number === "number" && typeof issue.state === "string") {
+        return issue;
+    }
+    return null;
+}
+function normalizeIssueState(issue) {
+    const state = issue?.state?.toUpperCase();
+    if (state === "OPEN" || state === "CLOSED") {
+        return state;
+    }
+    return null;
+}
+function hasTrackedPullRequestLink(assignment, pr) {
+    return (assignment.prNumber === pr.number ||
+        assignment.status === "pr_open" ||
+        assignment.status === "pr_merged" ||
+        assignment.status === "pr_closed");
+}
+function resolveTaskStatus(assignment, branchAheadCount, pr) {
+    if (pr === undefined && assignment.status.startsWith("pr_")) {
+        return { nextStatus: assignment.status, nextPrNumber: assignment.prNumber };
+    }
+    if (pr?.state.toUpperCase() === "OPEN") {
+        return { nextStatus: "pr_open", nextPrNumber: pr.number };
+    }
+    if (pr?.mergedAt) {
+        if (hasTrackedPullRequestLink(assignment, pr)) {
+            return { nextStatus: "pr_merged", nextPrNumber: pr.number };
+        }
+        if (branchAheadCount > 0) {
+            return { nextStatus: "branch_pushed", nextPrNumber: null };
+        }
+        return { nextStatus: "assigned", nextPrNumber: null };
+    }
+    if (pr) {
+        if (hasTrackedPullRequestLink(assignment, pr)) {
+            return { nextStatus: "pr_closed", nextPrNumber: pr.number };
+        }
+        if (branchAheadCount > 0) {
+            return { nextStatus: "branch_pushed", nextPrNumber: null };
+        }
+        return { nextStatus: "assigned", nextPrNumber: null };
+    }
+    if (branchAheadCount > 0) {
+        return { nextStatus: "branch_pushed", nextPrNumber: null };
+    }
+    return { nextStatus: "assigned", nextPrNumber: null };
+}
+export async function resolveTaskAssignments(assignments, cwd = process.cwd(), runner = execFileAsync) {
+    if (assignments.length === 0) {
+        return [];
+    }
+    const baseRefCache = new Map();
+    const resolveBaseRefForCwd = (repoCwd) => {
+        const cached = baseRefCache.get(repoCwd);
+        if (cached)
+            return cached;
+        const promise = resolveBaseRef(repoCwd, runner);
+        baseRefCache.set(repoCwd, promise);
+        return promise;
+    };
+    const branchProgressCache = new Map();
+    const pullRequestByNumberCache = new Map();
+    const issueByNumberCache = new Map();
+    const resolveBranchProgress = (assignment) => {
+        const repoCwd = assignment.repoRoot ?? (assignment.repoOwner && assignment.repoName ? null : null);
+        const commandCwd = repoCwd ?? cwd;
+        const cacheKey = `${assignment.repoOwner ?? ""}/${assignment.repoName ?? ""}:${repoCwd ?? "repo_root_unavailable"}:${assignment.branch ?? ""}`;
+        const cached = branchProgressCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const canResolveRemotePr = repoCwd != null || (assignment.repoOwner != null && assignment.repoName != null);
+        const branchAheadCountPromise = repoCwd
+            ? resolveBaseRefForCwd(repoCwd).then((baseRef) => getBranchAheadCount(assignment.branch, baseRef, repoCwd, runner))
+            : Promise.resolve(0);
+        const promise = Promise.all([
+            branchAheadCountPromise,
+            canResolveRemotePr ? getPullRequestForBranch(assignment, commandCwd, runner) : null,
+        ]).then(([branchAheadCount, pr]) => ({ branchAheadCount, pr }));
+        branchProgressCache.set(cacheKey, promise);
+        return promise;
+    };
+    const resolvePullRequestByNumber = (prNumber, assignment, repoCwd) => {
+        const cacheKey = `${assignment.repoOwner ?? ""}/${assignment.repoName ?? ""}:${repoCwd}#${prNumber}`;
+        const cached = pullRequestByNumberCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const promise = getPullRequestByNumber(prNumber, assignment, repoCwd, runner);
+        pullRequestByNumberCache.set(cacheKey, promise);
+        return promise;
+    };
+    const resolveIssueByNumber = (assignment) => {
+        const cacheKey = `${assignment.repoOwner ?? ""}/${assignment.repoName ?? ""}#${assignment.issueNumber}`;
+        const cached = issueByNumberCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const promise = getIssueByNumber(assignment, cwd, runner);
+        issueByNumberCache.set(cacheKey, promise);
+        return promise;
+    };
+    return Promise.all(assignments.map(async (assignment) => {
+        const { branchAheadCount, pr } = await resolveBranchProgress(assignment);
+        const canResolveStoredPr = assignment.repoRoot != null ||
+            (assignment.repoOwner != null && assignment.repoName != null);
+        const resolvedPr = pr == null && assignment.prNumber != null && canResolveStoredPr
+            ? await resolvePullRequestByNumber(assignment.prNumber, assignment, assignment.repoRoot ?? cwd)
+            : pr;
+        const issueState = normalizeIssueState(await resolveIssueByNumber(assignment));
+        const { nextStatus, nextPrNumber } = resolveTaskStatus(assignment, branchAheadCount, resolvedPr);
+        return {
+            ...assignment,
+            nextStatus,
+            nextPrNumber,
+            branchAheadCount,
+            issueState,
+        };
+    }));
+}
+export function hasTaskAssignmentStatusChange(assignment) {
+    return (assignment.status !== assignment.nextStatus || assignment.prNumber !== assignment.nextPrNumber);
+}
+function isImplementationProgressTask(taskKind) {
+    return taskKind === "implementation" || taskKind === "unknown";
+}
+function formatTaskProgressFragment(assignment) {
+    if (!isImplementationProgressTask(assignment.taskKind)) {
+        return `#${assignment.issueNumber} → ${assignment.taskKind} task, no implementation PR expected`;
+    }
+    switch (assignment.status) {
+        case "pr_merged":
+            return `#${assignment.issueNumber} → PR #${assignment.prNumber ?? "?"} MERGED ✅`;
+        case "pr_open":
+            return `#${assignment.issueNumber} → PR #${assignment.prNumber ?? "?"} OPEN 🔄`;
+        case "pr_closed":
+            return `#${assignment.issueNumber} → PR #${assignment.prNumber ?? "?"} CLOSED ⚠️`;
+        case "branch_pushed":
+            return `#${assignment.issueNumber} → commits on ${assignment.branch ?? "tracked branch"}, no PR 👀`;
+        case "assigned":
+        default:
+            if (!assignment.repoOwner && !assignment.repoName && !assignment.repoRoot) {
+                return `#${assignment.issueNumber} → repo unknown; progress not checked ⚠️`;
+            }
+            if (assignment.branch &&
+                assignment.repoOwner &&
+                assignment.repoName &&
+                !assignment.repoRoot) {
+                return `#${assignment.issueNumber} → no PR found for ${assignment.branch}; commits not checked (repo root unavailable) ⚠️`;
+            }
+            return `#${assignment.issueNumber} → no commits, no PR ⚠️`;
+    }
+}
+function getVisibleTaskAssignmentReportEntries(assignments) {
+    return assignments.filter((assignment) => assignment.issueState !== "CLOSED" &&
+        assignment.status !== "pr_merged" &&
+        (assignment.status !== "pr_closed" || isImplementationProgressTask(assignment.taskKind)));
+}
+function formatAgentLabel(agentId, agentsById) {
+    const agent = agentsById.get(agentId);
+    if (!agent) {
+        return agentId;
+    }
+    return `${agent.emoji} ${agent.name}`.trim();
+}
+function getAgentSortKey(agentId, agentsById) {
+    const agent = agentsById.get(agentId);
+    return agent?.name ?? agentId;
+}
+export function buildTaskAssignmentReport(assignments, agentsById, cycleStartedAt) {
+    const visibleAssignments = getVisibleTaskAssignmentReportEntries(assignments);
+    if (visibleAssignments.length === 0) {
+        return null;
+    }
+    const grouped = new Map();
+    for (const assignment of visibleAssignments) {
+        const bucket = grouped.get(assignment.agentId);
+        if (bucket) {
+            bucket.push(assignment);
+        }
+        else {
+            grouped.set(assignment.agentId, [assignment]);
+        }
+    }
+    const lines = [...grouped.entries()]
+        .sort(([leftAgentId], [rightAgentId]) => {
+        const leftLabel = getAgentSortKey(leftAgentId, agentsById);
+        const rightLabel = getAgentSortKey(rightAgentId, agentsById);
+        return leftLabel.localeCompare(rightLabel);
+    })
+        .map(([agentId, agentAssignments]) => {
+        const summary = [...agentAssignments]
+            .sort((left, right) => left.issueNumber - right.issueNumber)
+            .map((assignment) => formatTaskProgressFragment(assignment))
+            .join("; ");
+        return `- ${formatAgentLabel(agentId, agentsById)}: ${summary}`;
+    });
+    const header = cycleStartedAt
+        ? ["RALPH LOOP — WORKER STATUS:", `Timestamp: ${cycleStartedAt}`]
+        : ["RALPH LOOP — WORKER STATUS:"];
+    return [...header, ...lines].join("\n");
+}
+export function getPendingTaskAssignmentReport(assignments, agentsById, lastDeliveredSignature, cycleStartedAt) {
+    const signature = buildTaskAssignmentReport(assignments, agentsById);
+    if (!signature || signature === lastDeliveredSignature) {
+        return null;
+    }
+    const message = buildTaskAssignmentReport(assignments, agentsById, cycleStartedAt);
+    if (!message) {
+        return null;
+    }
+    return { message, signature };
+}

package/dist/thread-confirmations.d.ts

@@ -0,0 +1,22 @@
+import type { ConfirmationRequest } from "./helpers.js";
+import { type SecurityGuardrails } from "./guardrails.js";
+export interface RegisterConfirmationRequestResult {
+    status: "created" | "refreshed" | "conflict";
+    conflict?: ConfirmationRequest;
+}
+export interface ThreadConfirmationPolicy {
+    formatAction: (action: string) => string;
+    registerRequest: (threadTs: string, tool: string, action: string) => RegisterConfirmationRequestResult;
+    consumeReply: (threadTs: string, text: string, options?: {
+        receivedAt?: string | number | Date;
+    }) => {
+        approved: boolean;
+    } | null;
+    requireToolPolicy: (toolName: string, threadTs: string | undefined, action: string) => void;
+}
+export interface CreateThreadConfirmationPolicyDeps {
+    getGuardrails: () => SecurityGuardrails;
+    now?: () => number;
+    ttlMs?: number;
+}
+export declare function createThreadConfirmationPolicy(deps: CreateThreadConfirmationPolicyDeps): ThreadConfirmationPolicy;

package/dist/thread-confirmations.js

@@ -0,0 +1,139 @@
+import { DEFAULT_CONFIRMATION_REQUEST_TTL_MS, confirmationRequestMatches, consumeMatchingConfirmationRequest, isThreadConfirmationStateEmpty, normalizeThreadConfirmationState, registerThreadConfirmationRequest, } from "./helpers.js";
+import { isConfirmationApproval, isConfirmationRejection, isToolBlocked, toolNeedsConfirmation, } from "./guardrails.js";
+export function createThreadConfirmationPolicy(deps) {
+    const threadConfirmationStates = new Map();
+    const getNow = deps.now ?? Date.now;
+    const ttlMs = deps.ttlMs ?? DEFAULT_CONFIRMATION_REQUEST_TTL_MS;
+    function storeThreadConfirmationState(threadTs, state, now = getNow()) {
+        const normalized = normalizeThreadConfirmationState(state, now, ttlMs);
+        if (isThreadConfirmationStateEmpty(normalized)) {
+            threadConfirmationStates.delete(threadTs);
+            return null;
+        }
+        threadConfirmationStates.set(threadTs, normalized);
+        return normalized;
+    }
+    function sweepThreadConfirmationStates(now = getNow()) {
+        for (const [threadTs, state] of threadConfirmationStates) {
+            storeThreadConfirmationState(threadTs, state, now);
+        }
+    }
+    function getThreadConfirmationState(threadTs) {
+        sweepThreadConfirmationStates();
+        let state = threadConfirmationStates.get(threadTs);
+        if (!state) {
+            state = { pending: [], approved: [], rejected: [] };
+            threadConfirmationStates.set(threadTs, state);
+        }
+        return state;
+    }
+    function cleanupThreadConfirmationState(threadTs) {
+        const state = threadConfirmationStates.get(threadTs);
+        if (!state)
+            return;
+        storeThreadConfirmationState(threadTs, state);
+    }
+    function formatAction(action) {
+        return JSON.stringify(action);
+    }
+    function registerRequest(threadTs, tool, action) {
+        const now = getNow();
+        const result = registerThreadConfirmationRequest(getThreadConfirmationState(threadTs), {
+            toolPattern: tool,
+            action,
+            requestedAt: now,
+        }, now);
+        storeThreadConfirmationState(threadTs, result.state, now);
+        return {
+            status: result.status,
+            conflict: result.conflict,
+        };
+    }
+    function consumeReply(threadTs, text, options = {}) {
+        sweepThreadConfirmationStates();
+        const state = threadConfirmationStates.get(threadTs);
+        if (!state || state.pending.length === 0)
+            return null;
+        const trimmed = text.trim();
+        const isApproval = isConfirmationApproval(trimmed);
+        const isRejection = isConfirmationRejection(trimmed);
+        if (!isApproval && !isRejection)
+            return null;
+        const request = state.pending[0];
+        if (!request)
+            return null;
+        if (options.receivedAt !== undefined) {
+            const receivedAtMs = options.receivedAt instanceof Date
+                ? options.receivedAt.getTime()
+                : typeof options.receivedAt === "number"
+                    ? options.receivedAt
+                    : Date.parse(options.receivedAt);
+            if (!Number.isFinite(receivedAtMs) || receivedAtMs < request.requestedAt) {
+                return null;
+            }
+        }
+        state.pending.shift();
+        if (isApproval) {
+            state.approved.push(request);
+            cleanupThreadConfirmationState(threadTs);
+            return { approved: true };
+        }
+        state.rejected.push(request);
+        cleanupThreadConfirmationState(threadTs);
+        return { approved: false };
+    }
+    function getConfirmationDecision(threadTs, toolName, action) {
+        sweepThreadConfirmationStates();
+        const state = threadConfirmationStates.get(threadTs);
+        if (!state)
+            return null;
+        const approved = consumeMatchingConfirmationRequest(state.approved, toolName, action);
+        if (approved) {
+            cleanupThreadConfirmationState(threadTs);
+            return true;
+        }
+        const rejected = consumeMatchingConfirmationRequest(state.rejected, toolName, action);
+        if (rejected) {
+            cleanupThreadConfirmationState(threadTs);
+            return false;
+        }
+        return null;
+    }
+    function requireToolPolicy(toolName, threadTs, action) {
+        const guardrails = deps.getGuardrails();
+        if (isToolBlocked(toolName, guardrails)) {
+            throw new Error(`Tool "${toolName}" is blocked by Slack security guardrails.`);
+        }
+        if (!toolNeedsConfirmation(toolName, guardrails)) {
+            return;
+        }
+        const quotedAction = formatAction(action);
+        if (!threadTs) {
+            throw new Error(`Tool "${toolName}" requires confirmation for action ${quotedAction}. Include a thread_ts and call slack with action "confirm_action" before executing this tool.`);
+        }
+        const decision = getConfirmationDecision(threadTs, toolName, action);
+        if (decision === true)
+            return;
+        if (decision === false) {
+            throw new Error(`Tool "${toolName}" was denied by Slack user confirmation for action ${quotedAction}.`);
+        }
+        sweepThreadConfirmationStates();
+        const state = threadConfirmationStates.get(threadTs);
+        const pendingMatch = state?.pending.find((request) => confirmationRequestMatches(request, toolName, action)) ??
+            null;
+        if (pendingMatch) {
+            throw new Error(`Tool "${toolName}" requires confirmation for action ${quotedAction}. A matching confirmation request is already pending in thread ${threadTs}; wait for the user's approval first.`);
+        }
+        const pendingConflict = state?.pending[0];
+        if (pendingConflict) {
+            throw new Error(`Thread ${threadTs} already has a pending confirmation for tool "${pendingConflict.toolPattern}" and action ${formatAction(pendingConflict.action)}. Wait for a reply or expiry before requesting another action in the same thread.`);
+        }
+        throw new Error(`Tool "${toolName}" requires confirmation for action ${quotedAction}. Call slack with action "confirm_action" in thread ${threadTs} using tool "${toolName}" and action ${quotedAction}, then wait for the user's approval first.`);
+    }
+    return {
+        formatAction,
+        registerRequest,
+        consumeReply,
+        requireToolPolicy,
+    };
+}