tinybeeai 0.0.0-stage → 0.16.1

package/dist/agent/rules.js

@@ -0,0 +1,927 @@
+// Custom Rules gate. Every outward action passes through gate(); the rule level for its kind
+// decides whether it runs, waits for approval, or goes to a person.
+import { get, insert, update } from '../db.js';
+import { publish } from '../events.js';
+import { config } from '../config.js';
+import { DEFECT_LABEL, hasStickyMarker, isDefectLabel, githubFor, githubMode } from '../integrations/github.js';
+import { issueApi, parseIssueRef, STATUS_LABELS } from '../integrations/github-issues.js';
+import { executeTicketStatus } from '../integrations/status-change.js';
+import { createTrackerIssue, withDefectMarker } from '../integrations/issue-create.js';
+import { recordDefectLinks } from '../links.js';
+import { unreadRules } from '../pr-scope.js';
+import { jiraFor } from '../integrations/jira.js';
+import { linearFor } from '../integrations/linear.js';
+import { notify } from '../notify/push.js';
+import { adoptPush, updatesOwnDelivery } from '../updates/owner.js';
+import { executeMcpTool } from '../connections/index.js';
+import { executeSlackPost } from '../slack/index.js';
+import { executeReportEdit } from '../reports/index.js';
+import { executeCaseRetire } from '../impact/store.js';
+import { OUTWARD_KINDS, refuseOutward, sandboxOn } from '../sandbox.js';
+import { enqueue } from '../queue.js';
+import { DEFAULT_RULES, } from '../types.js';
+import { checkDestination, CONTENT_RISK_REASON, DESTINATION_REASON } from './destinations.js';
+import { getLlm, MockLlm } from './llm.js';
+import { ModelUnavailableError } from './model-errors.js';
+import { classifySendError, nextRetry, RETRY_WINDOW_MS, waitText } from './send-retry.js';
+import { redactCode } from './redact.js';
+import { clipCheckTitle } from '../review/render.js';
+import { addAction, addStep, isRunCancelled, isRunGone, updateActionResult } from './runs.js';
+import { repoFromTarget } from '../repos.js';
+import { shadowLevel } from '../shadow-week.js';
+import { safeRepoSpecPath } from '../runner/pwgen/propose.js';
+import { classifyEscalation, setCheckCloseHook, supersedeBySent, supersedeOlder } from './approvals.js';
+/** `/Users/<name>/...` and `/home/<name>/...` become `~/...`, so a posted log line does not name the host user. */
+export function redactHomePaths(text) {
+    return text.replace(/(^|[\s(`'"=:])\/(?:Users|home)\/[A-Za-z0-9._-]+(?=\/|[\s)`'"]|$)/gm, '$1~');
+}
+/** Title, body, and a check run's long text and annotations, with home directories shown as ~. */
+function redactActionHomePaths(action) {
+    const out = { ...action, title: redactHomePaths(action.title), body: redactHomePaths(action.body) };
+    const meta = action.meta;
+    if (meta && action.kind === 'check_run') {
+        const m = { ...meta };
+        if (typeof meta.text === 'string')
+            m.text = redactHomePaths(meta.text);
+        if (Array.isArray(meta.annotations))
+            m.annotations = meta.annotations.map((a) => a && typeof a === 'object'
+                ? {
+                    ...a,
+                    ...(typeof a.message === 'string' ? { message: redactHomePaths(a.message) } : {}),
+                    ...(typeof a.title === 'string' ? { title: redactHomePaths(a.title) } : {}),
+                }
+                : a);
+        out.meta = m;
+    }
+    return out;
+}
+/** Kinds that leave the building and are worth a second look before they go. */
+const REVIEWED = ['check_run', 'pr_comment', 'ticket_comment', 'ticket_status', 'open_pr', 'revert', 'slack_post', 'file_defect', 'issue_create'];
+/**
+ * A Slack post may go out under rule `act` only when its producer built it from fixed strings plus
+ * verdict fields and marked it `meta.templated: true`. Any other Slack text can carry model output
+ * shaped by untrusted ticket, PR, or log content, so `act` is treated as `ask` for it.
+ */
+export function slackPostTemplated(action) {
+    return action.kind === 'slack_post' && action.meta?.templated === true;
+}
+/** The level gate() applies: the watch rule, tightened from act to ask for a Slack post that is not templated. */
+export function effectiveLevel(watch, action) {
+    const level = ruleFor(watch, action.kind);
+    if (action.kind === 'slack_post' && level === 'act' && !slackPostTemplated(action))
+        return 'ask';
+    // A case is never retired on its own (KAT-304): whatever the rule says, a person approves it, or does it by hand.
+    if (action.kind === 'case_retire' && level !== 'hand_off')
+        return 'ask';
+    return level;
+}
+/**
+ * A check-run status write built only from fixed strings and run progress: queued, in progress,
+ * superseded, or a closing note. The producer sets `meta.templated: true`. These skip auto-review
+ * (there is no model text in them to check), but they still follow the check_run rule.
+ */
+export function templatedStatusWrite(action) {
+    return action.kind === 'check_run' && action.meta?.templated === true;
+}
+/** Why a first look waits for a person. */
+export const FIRST_LOOK_REASON = "First look at a PR that was already open. A person approves the post. Name authors, a team or issue labels in the repo's PR scope to post on its own.";
+/** Why a ticket comment or status label of a backfilled review waits for a person. */
+export const BACKFILL_REASON = 'Ticket review from before the dot started. Nobody asked for it, so a person approves the comment or status label before it is posted.';
+/**
+ * Why a PR comment or check of this run waits for a person under rule `act`, or null (KAT-352, KAT-363).
+ *
+ * A first look (the first poll): nobody asked for that review, and the PR may belong to another team of a shared repo.
+ *
+ * A PR whose scope rule could not be read: the PR ran because the dot could not tell whose it is, so what it posts waits
+ * until a person has looked. The reason names the rule.
+ *
+ * A review a person asked for is never held.
+ */
+function holdReason(action, watch, runId) {
+    if (!runId)
+        return null;
+    const ticketWrite = action.kind === 'ticket_comment' || action.kind === 'ticket_status';
+    if (action.kind !== 'pr_comment' && action.kind !== 'check_run' && !ticketWrite)
+        return null;
+    const trigger = get('runs', runId)?.trigger;
+    if (!trigger || trigger.requestedBy)
+        return null;
+    // A ticket that was open before the dot started: nobody asked for the review, so its comment and status label wait (KAT-381).
+    if (ticketWrite)
+        return trigger.backfill === true ? BACKFILL_REASON : null;
+    if (trigger.firstLook === true)
+        return FIRST_LOOK_REASON;
+    const unread = unreadRules(watch, trigger);
+    return unread.length ? scopeUnreadReason(unread) : null;
+}
+/** Why a PR whose scope rule could not be read waits for a person. */
+export function scopeUnreadReason(unread) {
+    return `PR scope not applied: could not read ${unread.join(' and ')}, so this PR was let in unchecked. A person approves the post.`;
+}
+export function ruleFor(watch, kind) {
+    // A shadow week that ended reads as the saved level at once, before the sweep writes it back (src/shadow-week.ts).
+    return shadowLevel(watch, kind) ?? watch.rules?.[kind] ?? DEFAULT_RULES[kind];
+}
+/** The rules a review of this event runs with. A review asked for without posting holds the PR comment and the check run in the Inbox (KAT-357). */
+export function rulesForEvent(watch, ev) {
+    if (!ev.outboxOnly)
+        return watch;
+    const rules = { ...watch.rules };
+    for (const kind of ['pr_comment', 'check_run'])
+        if (ruleFor(watch, kind) === 'act')
+            rules[kind] = 'ask';
+    return { ...watch, rules };
+}
+function askedByUser(action) {
+    return action.meta?.askedBy === 'user';
+}
+/** No GitHub credentials means a demo install: pushes are mirrored to the outbox too. */
+function demoInstall() {
+    return githubMode() === 'demo';
+}
+function runLink(runId) {
+    return runId ? `/#/runs/${runId}` : undefined;
+}
+/** A deep link the flow built (for example the run's "What to test" section). Only in-app hash links are kept. */
+export function pushLink(url, runId) {
+    return typeof url === 'string' && /^\/#\/[\w\-/?=&.%]*$/.test(url) ? url : runLink(runId);
+}
+function checkAnnotations(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = v.filter((a) => !!a &&
+        typeof a === 'object' &&
+        typeof a.path === 'string' &&
+        Number.isInteger(a.startLine) &&
+        typeof a.message === 'string' &&
+        ['notice', 'warning', 'failure'].includes(a.level));
+    return out.length ? out.slice(0, 500) : undefined;
+}
+/** Longest body an automatic post may have before a person looks at it. The QA report summary comment has no limit. */
+export const AUTO_POST_MAX_CHARS = 8000;
+/** Check runs stop at GitHub's own summary limit. */
+const CHECK_RUN_MAX_CHARS = 65_000;
+/**
+ * The QA report summary comment: the one sticky PR comment that holds the full report and is edited in place. It is
+ * long by design (every risk, the What to test checklist, the test totals), so no length limit applies to it.
+ */
+export function isQaReportSummary(action) {
+    return action.kind === 'pr_comment' && (action.meta?.sticky === true || action.meta?.reportSummary === true);
+}
+/** The length limit for a kind, or undefined when none applies. */
+export function lengthLimit(action) {
+    if (isQaReportSummary(action))
+        return undefined;
+    return action.kind === 'check_run' ? CHECK_RUN_MAX_CHARS : AUTO_POST_MAX_CHARS;
+}
+/** A model reason about how long a draft is. Code applies the limit, so the model's view of length is not a finding. */
+const LENGTH_REASON = /\b(?:unusually|too|very|overly|excessively|extremely)\s+(?:long|lengthy|large|verbose)\b|\blength\b|\bcharacters long\b/i;
+const NUM = '(?:\\d+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty)';
+const THING = '(?:bugs?|checks?|tests?|risks?|questions?|defects?|gaps?|issues?|findings?)';
+/**
+ * A model reason about how many bugs, checks, tests, risks or questions a QA report states against what it records
+ * ("says eight checks were not tested but the records list six", "check the untested count"). Code checks the
+ * report counts before drafting (reportFacts, reportRefused), so the model's view of them is not a finding.
+ */
+const COUNT_REASON = new RegExp(`\\b(?:counts?|number of|totals?)\\b|\\b${NUM}\\s+(?:[\\w-]+\\s+){0,2}${THING}\\b|\\b(?:records?|lists?|listed|lists|states?|says?|has|have|marks?|shows?|counts?)\\s+(?:only\\s+)?(?:[\\w-]+\\s+){0,2}${NUM}\\b|\\b${NUM}\\s+(?:as\\s+)?(?:not run|not tested|untested|skipped)\\b`, 'i');
+/** A claim about a result (a test failed, a check passed): a person judges it, even when it holds a number. */
+const RESULT_CLAIM = /\b(?:fail(?:s|ed|ing|ure|ures)?|pass(?:es|ed|ing)?|broken|breaks?|regress\w*|errors?|crash\w*|no bugs?|zero bugs?)\b/i;
+/** QA report kinds: the report summary comment and a check run. Their counts are checked by code. */
+export function isQaReportKind(action) {
+    return action.kind === 'check_run' || isQaReportSummary(action);
+}
+/**
+ * The clauses of a model reason: sentences, and the parts a comma, semicolon, "and", "but", "while", "plus" or
+ * "as well as" joins. "Contains a token and the body length looks odd" is two clauses, one of them a finding.
+ */
+export function reasonClauses(reason) {
+    return reason
+        .split(/[.!?;]+(?=\s|$)|,|\b(?:and|but|while|plus|as well as)\b/i)
+        .map((c) => c.trim())
+        .filter((c) => /[\p{L}\p{N}]/u.test(c));
+}
+/**
+ * What a model reason is about when code already checked all of it: the destination, the length, or both (and, for a QA report, counts). Null
+ * when any clause is about something else, or names a content risk (CONTENT_RISK_REASON), because that clause
+ * is a real finding. Such a reason keeps its escalation.
+ */
+export function clearableKinds(reason, opts = {}) {
+    const clauses = reasonClauses(reason);
+    if (!clauses.length)
+        return null;
+    const kinds = new Set();
+    for (const c of clauses) {
+        if (CONTENT_RISK_REASON.test(c))
+            return null;
+        if (DESTINATION_REASON.test(c))
+            kinds.add('destination');
+        else if (LENGTH_REASON.test(c))
+            kinds.add('length');
+        else if (opts.counts && COUNT_REASON.test(c) && !RESULT_CLAIM.test(c))
+            kinds.add('counts');
+        else
+            return null;
+    }
+    return kinds;
+}
+/**
+ * The checks code makes on every reviewed draft, before the model sees it: the destination is one of the
+ * dot's places to post (src/agent/destinations.ts), and the body fits the limit of its kind. Returns the
+ * escalation, or null when the draft passes.
+ */
+export function deterministicReview(action, watch) {
+    const dest = checkDestination(action, watch);
+    if (!dest.ok)
+        return { ok: true, escalate: true, reason: dest.reason, category: 'must_not_rule' };
+    const limit = lengthLimit(action);
+    if (limit !== undefined && action.body.length > limit)
+        return {
+            ok: true,
+            escalate: true,
+            reason: `The draft is ${action.body.length} characters, over the ${limit} a ${action.kind.replace('_', ' ')} may have without a person.`,
+            category: 'other',
+        };
+    return null;
+}
+/** Why a draft waits when the review model could not answer and the code checks alone are not enough for its kind. */
+export const MODEL_UNAVAILABLE_WAIT_REASON = 'Review model unavailable, waiting for a person';
+/**
+ * What may go out on the code checks alone while the review model is down: the QA report summary comment (a
+ * pr_comment that carries the localdost:pr-summary marker) and a check run or commit status (kind check_run), both
+ * only on a GitHub repo the dot may post to. Everything else (defects, issues, ticket comments, Slack, push,
+ * Linear, Jira, open_pr, any other write) waits for a person. A new kind is outside this list until it is added.
+ */
+export function mayGoOnCodeChecksAlone(action, watch) {
+    const dest = checkDestination(action, watch);
+    if (!dest.ok || dest.destination.system !== 'github')
+        return false;
+    if (action.kind === 'check_run')
+        return true;
+    return action.kind === 'pr_comment' && hasStickyMarker(action.body);
+}
+/**
+ * The review when the model could not answer (a spend cap, a quota, no usable reply). It used to escalate every
+ * draft (40 escalations in the dogfood ledger). Now the code checks decide, with the rule-based reviewer for
+ * credentials, copied instructions, destructive kinds and the must-not rule, but only for the kinds in
+ * mayGoOnCodeChecksAlone; every other kind waits in the Inbox. The result says the model was unavailable, and
+ * gate() records that on the draft.
+ */
+async function reviewWithoutModel(action, watch, why) {
+    const modelUnavailable = why.trim() || 'no reply';
+    const ruled = await new MockLlm().review(action, watch);
+    const waits = () => ({
+        ok: true,
+        escalate: true,
+        reason: MODEL_UNAVAILABLE_WAIT_REASON,
+        category: 'reviewer_unavailable',
+        modelUnavailable,
+    });
+    // A finding about the draft itself (a credential, copied instructions, the must-not rule) keeps its own reason. A
+    // destructive kind (open_pr, revert) always waits, and without the model that is the reason to show.
+    if (ruled.escalate || !ruled.ok)
+        return ruled.category === 'destructive' ? waits() : { ...ruled, modelUnavailable };
+    if (!mayGoOnCodeChecksAlone(action, watch))
+        return waits();
+    return {
+        ok: true,
+        escalate: false,
+        reason: `The review model was unavailable (${modelUnavailable}); the code checks passed, so the rule decides.`,
+        modelUnavailable,
+    };
+}
+/** Auto-review for an outward draft: the code checks, then the model on the content. */
+export async function safeReview(action, watch) {
+    const fixed = deterministicReview(action, watch);
+    if (fixed)
+        return fixed;
+    let review;
+    try {
+        review = await getLlm().review(action, watch);
+    }
+    catch (err) {
+        const why = err instanceof ModelUnavailableError ? err.reason : err instanceof Error ? err.message : String(err);
+        console.warn(`[rules] auto-review got no model answer: ${why}`);
+        return reviewWithoutModel(action, watch, why);
+    }
+    // A backend that got no usable decision (no reply, unreadable replies) says so with this category.
+    if (review.category === 'reviewer_unavailable')
+        return reviewWithoutModel(action, watch, review.reason.replace(/\.$/, ''));
+    // The model judges the content only. Code already checked the destination and the length, so a reason that is
+    // wholly about where the draft goes ("outside the permitted project") or how long it is is not a finding. A
+    // reason with any other clause (a token, a customer, anything else) keeps the escalation (KAT-305).
+    if (review.ok && review.escalate) {
+        const kinds = clearableKinds(review.reason, { counts: isQaReportKind(action) });
+        if (kinds) {
+            const parts = [];
+            if (kinds.has('destination')) {
+                const dest = checkDestination(action, watch);
+                console.warn(`[rules] auto-review judged the destination, which code checks (${dest.label}): ${review.reason}`);
+                parts.push(`Destination checked by code: ${dest.label}.`);
+            }
+            if (kinds.has('length')) {
+                console.warn(`[rules] auto-review judged the length, which code checks: ${review.reason}`);
+                parts.push(`Length checked by code: ${action.body.length} characters${isQaReportSummary(action) ? ', the QA report summary has no limit' : ''}.`);
+            }
+            if (kinds.has('counts')) {
+                console.warn(`[rules] auto-review judged report counts, which code checks: ${review.reason}`);
+                parts.push('Counts checked by code before drafting: the report counts match its records.');
+            }
+            return { ok: true, escalate: false, reason: parts.join(' ') };
+        }
+    }
+    return review;
+}
+/**
+ * A templated status write goes out only under rule `act` (or `act_when_asked` when a person asked).
+ * Any other level sends nothing: asking a person to approve "Queued, 2 ahead" would only produce a stale
+ * approval, and the final report still goes through the full gate. The write leaves no step or action on
+ * the run, so a progress update every 30 s does not fill the run page. A failed write is logged, never thrown.
+ */
+async function gateStatusWrite(action, watch, runId) {
+    const level = ruleFor(watch, 'check_run');
+    if (level === 'hand_off')
+        return 'handed_off';
+    if (level !== 'act' && !(level === 'act_when_asked' && askedByUser(action)))
+        return 'blocked';
+    // A first look and a PR whose scope was not applied wait for a person, and a "queued" status is not worth an approval: it is not written.
+    if (level === 'act' && holdReason(action, watch, runId))
+        return 'blocked';
+    if (runId && isRunCancelled(runId) && action.meta?.status !== 'completed')
+        return 'blocked';
+    const safe = redactActionHomePaths({ ...action, title: redactCode(action.title), body: redactCode(action.body) });
+    try {
+        await execute(safe, watch, runId || undefined);
+    }
+    catch (err) {
+        console.warn(`[rules] check status write failed: ${String(err)}`);
+        return 'blocked';
+    }
+    // What execute learned (the new check run id) goes back to the caller's object.
+    if (safe.meta)
+        action.meta = safe.meta;
+    return 'executed';
+}
+/**
+ * A push from outside a run, for a job that has no run yet. Follows the push_notify rule: only `act`
+ * sends. Mirrored to the outbox on a demo install, like the gate's own notices. Returns whether it went out.
+ */
+export async function notifyOwner(n, watch) {
+    if (ruleFor(watch, 'push_notify') !== 'act')
+        return false;
+    await sendNotice(n, watch, '');
+    return true;
+}
+export async function gate(action, watch, runId) {
+    if (templatedStatusWrite(action))
+        return gateStatusWrite(action, watch, runId);
+    // Redaction below copies the action; what execute() learns (a filed URL) is copied back onto the caller's object.
+    const caller = action;
+    const holdWhy = holdReason(action, watch, runId);
+    const held = holdWhy !== null && effectiveLevel(watch, action) === 'act';
+    const level = held ? 'ask' : effectiveLevel(watch, action);
+    // A templated Slack notice still has verdict fields in it: mask secret shapes before review and send.
+    if (slackPostTemplated(action))
+        action = { ...action, title: redactCode(action.title), body: redactCode(action.body) };
+    // Runner output can carry the host's home directory (and with it a username): show it as ~ instead.
+    if (REVIEWED.includes(action.kind))
+        action = redactActionHomePaths(action);
+    const record = (result, approvalId) => {
+        addAction(runId, approvalId ? { action, result, approvalId } : { action, result });
+        return result;
+    };
+    // A cancelled run sends nothing outward, even when its flow was already past the test stage.
+    if (runId && isRunCancelled(runId))
+        return record('blocked');
+    if (level === 'hand_off') {
+        addStep(runId, `Handed off: ${action.title}`, `Rule for ${action.kind} is hand_off; a person does this.`, 'warn');
+        await sendNotice({
+            key: `handoff:${runId}:${action.kind}`,
+            title: `Over to you: ${action.title}`,
+            body: `Your rules say a person does "${action.kind.replace('_', ' ')}". The draft is in the run.`,
+            url: runLink(runId),
+            urgency: 'normal',
+        }, watch, runId);
+        return record('handed_off');
+    }
+    if (level === 'act_when_asked' && !askedByUser(action)) {
+        addStep(runId, `Skipped: ${action.title}`, `Rule for ${action.kind} is act_when_asked and nobody asked.`, 'info');
+        return record('blocked');
+    }
+    const review = REVIEWED.includes(action.kind)
+        ? await safeReview(action, watch)
+        : { ok: true, escalate: false, reason: 'Internal action, no review needed.' };
+    // The review took time: the run may have been cancelled, or the dot deleted with its run row. Nothing
+    // below awaits before the approval insert or execute(), so this check holds until they run.
+    if (runId && isRunGone(runId))
+        return 'blocked';
+    if (runId && isRunCancelled(runId))
+        return record('blocked');
+    if (!get('watches', watch.id))
+        return 'blocked';
+    // No review model answered: the draft says so, on the run, in the Inbox and on the sent action.
+    if (review.modelUnavailable) {
+        action = { ...action, meta: { ...action.meta, reviewModelUnavailable: review.modelUnavailable } };
+        if (runId)
+            addStep(runId, 'Review model unavailable', `${review.modelUnavailable}. The code checks and the rule for ${action.kind} decided.`, 'warn');
+    }
+    if (level === 'ask' || review.escalate || !review.ok) {
+        const tightened = level === 'ask' && ruleFor(watch, action.kind) === 'act';
+        // A draft held only because the review model is down says so in plain words, whatever its rule level.
+        const modelDown = review.modelUnavailable !== undefined && review.category === 'reviewer_unavailable';
+        const reason = modelDown
+            ? MODEL_UNAVAILABLE_WAIT_REASON
+            : level !== 'ask'
+                ? `The safety check wants a person to look first. ${review.reason}`.trim()
+                : held
+                    ? `${holdWhy} ${review.reason}`.trim()
+                    : tightened
+                        ? `Slack posts with written text wait for approval; only templated notices post on their own. ${review.reason}`.trim()
+                        : `Rule for ${action.kind} is ask. ${review.reason}`.trim();
+        const escalated = review.escalate || !review.ok;
+        const escalation = escalated
+            ? { by: level === 'ask' ? 'rule' : 'auto_review', category: review.category ?? classifyEscalation(review.reason) }
+            : { by: 'rule', category: 'rule_ask' };
+        const approval = requestApproval(action, watch, runId, reason, escalation);
+        if (approval.status === 'superseded') {
+            addStep(runId, `Superseded: ${action.title}`, approval.closedReason, 'info');
+            return record('blocked', approval.id);
+        }
+        addStep(runId, `Waiting for approval: ${action.title}`, reason, 'warn');
+        await sendNotice({
+            key: `approval:${approval.id}`,
+            title: `Approve? ${action.title}`,
+            body: reason,
+            url: '/#/inbox',
+            urgency: 'normal',
+            category: 'drafts',
+        }, watch, runId);
+        // A newer draft can supersede this one while the notice is in flight.
+        const now = get('approvals', approval.id);
+        return record(now && now.status !== 'pending' ? 'blocked' : 'pending_approval', approval.id);
+    }
+    try {
+        await execute(action, watch, runId);
+    }
+    catch (err) {
+        addStep(runId, `Failed: ${action.title}`, String(err), 'error');
+        return record('blocked');
+    }
+    if (caller !== action && action.meta)
+        caller.meta = action.meta;
+    addStep(runId, `Sent: ${action.title}`, action.target, 'ok');
+    supersedeBySent(watch.id, action, runId);
+    return record('executed');
+}
+/** Pending approvals expire after this long (API v2 default 24 h); deciding one later returns 410. */
+export const APPROVAL_TTL_MS = Math.max(60_000, Number(process.env.LOCALDOST_APPROVAL_TTL_MS) || 24 * 3600_000);
+export function approvalExpired(a, now = Date.now()) {
+    return a.status === 'expired' || (a.status === 'pending' && !!a.expiresAt && Date.parse(a.expiresAt) <= now);
+}
+function requestApproval(action, watch, runId, reason, escalation) {
+    const expiresAt = new Date(Date.now() + APPROVAL_TTL_MS).toISOString();
+    const approval = insert('approvals', { watchId: watch.id, runId, action, reason, status: 'pending', expiresAt, escalation });
+    // One pending draft per (action kind, target): the newer one replaces the older ones (KAT-94).
+    const closed = supersedeOlder(approval);
+    const self = closed.find((a) => a.id === approval.id);
+    if (self)
+        return self;
+    publish({ type: 'approval', approval });
+    return approval;
+}
+/** Gate-internal pushes (approval requests, hand-offs). Mirrored to the outbox on demo installs. */
+async function sendNotice(n, watch, runId) {
+    // With the update router running, it sends the decision or hand-off once, on every channel (KAT-143).
+    if (!updatesOwnDelivery()) {
+        try {
+            await notify({ watchId: watch.id, ...n });
+        }
+        catch (err) {
+            console.warn('[rules] push failed', err);
+        }
+    }
+    if (demoInstall())
+        toOutbox({ kind: 'push_notify', target: 'push', title: n.title, body: n.body, meta: { urgency: n.urgency, key: n.key } }, watch, runId);
+}
+function toOutbox(action, watch, runId) {
+    const item = insert('outbox', runId ? { watchId: watch.id, runId, action } : { watchId: watch.id, action });
+    publish({ type: 'outbox', item });
+    return item;
+}
+function num(v) {
+    const n = Number(v);
+    if (!Number.isFinite(n))
+        throw new Error(`expected a number, got ${String(v)}`);
+    return n;
+}
+const CONCLUSIONS = ['success', 'failure', 'neutral', 'action_required', 'cancelled', 'skipped', 'timed_out'];
+function checkConclusion(meta) {
+    return CONCLUSIONS.find((c) => c === meta.conclusion) ?? 'neutral';
+}
+/** The check run for a `check_run` action: conclusion, the QA review text and its line annotations. */
+export function checkRunInput(action, runId) {
+    const meta = action.meta ?? {};
+    // A queued or in-progress write has no conclusion; everything else completes the check.
+    const status = meta.status === 'queued' || meta.status === 'in_progress' ? meta.status : 'completed';
+    // GitHub cuts a check title that is longer than CHECK_TITLE_MAX, so every title is cut at a word here (KAT-376).
+    const input = { name: 'localdost', status, title: clipCheckTitle(action.title), summary: action.body };
+    if (status === 'completed')
+        input.conclusion = checkConclusion(meta);
+    if (meta.superseded === true)
+        input.superseded = true;
+    if (meta.runFailed === true)
+        input.runFailed = true;
+    if (typeof meta.statusDescription === 'string' && meta.statusDescription)
+        input.statusDescription = redactHomePaths(redactCode(meta.statusDescription));
+    if (typeof meta.text === 'string' && meta.text)
+        input.text = meta.text;
+    const annotations = checkAnnotations(meta.annotations);
+    if (annotations)
+        input.annotations = annotations;
+    if (config.publicUrl && runId)
+        input.detailsUrl = `${config.publicUrl.replace(/\/$/, '')}/#/runs/${runId}`;
+    return input;
+}
+/** Sends one action through the integration client, or to the outbox when the client is in demo mode. */
+export async function execute(action, watch, runId) {
+    // Sandbox mode (KAT-286): every gated write, an approval's send included, ends here before any network call.
+    // It throws, so a run records a failure and an approval stays in the Inbox with the reason.
+    if (sandboxOn() && OUTWARD_KINDS.has(action.kind))
+        refuseOutward(action.kind, action.target);
+    const meta = action.meta ?? {};
+    switch (action.kind) {
+        case 'push_notify': {
+            const urgency = meta.urgency === 'high' || meta.urgency === 'low' ? meta.urgency : 'normal';
+            const url = pushLink(meta.url, runId);
+            const notice = {
+                key: String(meta.key ?? `${action.target}:${runId ?? action.title}`),
+                title: action.title,
+                body: action.body,
+                ...(url ? { url } : {}),
+                urgency,
+                watchId: watch.id,
+            };
+            // The update router turns the same run into one message per channel (KAT-143). It does not make a message
+            // for every push a flow asks for (a digest ready, a rerun that passed, a QA review alert), so it takes the
+            // push over and sends it once (KAT-281). Nothing else sends it then.
+            if (updatesOwnDelivery())
+                await adoptPush({ ...notice, watchId: watch.id, ...(runId ? { runId } : {}) });
+            else
+                await notify(notice);
+            if (demoInstall())
+                toOutbox(action, watch, runId);
+            return;
+        }
+        case 'run_tests': {
+            enqueue({ kind: 'rerun', watchId: watch.id, payload: { ...meta, requestedBy: meta.askedBy === 'user' ? 'user' : 'rule', sourceRunId: runId } });
+            return;
+        }
+        case 'pr_comment': {
+            // The target names the repo (github:owner/name#12), so a dot with several repos comments on the right one.
+            const gh = githubFor(watch, { repo: repoFromTarget(action.target) ?? undefined });
+            if (gh.mode === 'demo') {
+                toOutbox(action, watch, runId);
+                return;
+            }
+            // A comment a person wrote on an object card (KAT-136) is a new comment; the sticky QA report is never edited with it.
+            if (meta.plain === true)
+                await gh.addComment(num(meta.pr), action.body);
+            else
+                await gh.upsertStickyComment(num(meta.pr), action.body);
+            return;
+        }
+        case 'check_run': {
+            const gh = githubFor(watch, { repo: repoFromTarget(action.target) ?? undefined });
+            if (gh.mode === 'demo') {
+                toOutbox(action, watch, runId);
+                return;
+            }
+            const sha = String(meta.sha ?? '');
+            const input = checkRunInput(action, runId);
+            // A check that was queued or started earlier is changed in place; otherwise a new one is created.
+            const known = Number(meta.checkRunId);
+            if (Number.isInteger(known) && known > 0)
+                await gh.updateCheckRun(known, sha, input);
+            else {
+                const id = await gh.createCheckRun(sha, input);
+                if (id !== undefined)
+                    action.meta = { ...meta, checkRunId: id };
+            }
+            return;
+        }
+        case 'ticket_comment': {
+            const tracker = meta.tracker ?? watch.tracker?.kind ?? 'jira';
+            const key = String(meta.key ?? action.target.replace(/^\w+:/, ''));
+            if (tracker === 'github' && meta.defectComment === true) {
+                // New evidence on a defect the dot or a person filed: a plain comment, never the sticky review comment.
+                const ref = parseIssueRef(key);
+                if (!ref)
+                    throw new Error(`not a GitHub issue key: ${key}`);
+                const gh = githubFor(watch);
+                if (gh.mode === 'demo') {
+                    toOutbox(action, watch, runId);
+                    return;
+                }
+                await gh.addComment(ref.number, action.body);
+                return;
+            }
+            if (tracker === 'github') {
+                // One sticky review comment per issue; a re-review edits it in place.
+                const ref = parseIssueRef(key);
+                if (!ref)
+                    throw new Error(`not a GitHub issue key: ${key}`);
+                if (demoInstall()) {
+                    toOutbox(action, watch, runId);
+                    return;
+                }
+                const api = issueApi(ref.full);
+                // A test status label: set the label, post nothing.
+                if (meta.statusLabel !== undefined) {
+                    const label = STATUS_LABELS.find((l) => l === meta.statusLabel);
+                    if (!label)
+                        throw new Error(`not a status label: ${String(meta.statusLabel)}`);
+                    await api.setStatusLabel(ref.number, label);
+                    return;
+                }
+                // A note on the issue (Seen again in run ...): its own comment, so the sticky review is not overwritten.
+                if (meta.append === true) {
+                    await api.addComment(ref.number, action.body);
+                    return;
+                }
+                await api.upsertReviewComment(ref.number, action.body);
+                return;
+            }
+            const client = tracker === 'linear' ? linearFor(watch) : jiraFor(watch);
+            if (client.mode === 'demo') {
+                toOutbox(action, watch, runId);
+                return;
+            }
+            // Linear's addComment takes the issue id; Jira takes the key
+            await client.addComment(tracker === 'linear' ? String(meta.ticketId ?? key) : key, action.body);
+            return;
+        }
+        case 'ticket_status': {
+            // A status a person picked on an object card (KAT-136). A tracker in demo mode has nothing to change.
+            if ((await executeTicketStatus(action, watch)) === 'demo')
+                toOutbox(action, watch, runId);
+            return;
+        }
+        case 'open_pr': {
+            // Generated Playwright specs carry their files; a live GitHub client opens a draft PR with them.
+            const files = proposedFiles(meta.files);
+            const gh = githubFor(watch);
+            if (files && typeof meta.base === 'string' && typeof meta.branch === 'string' && gh.mode !== 'demo' && gh.openPullWithFiles) {
+                const url = await gh.openPullWithFiles({ base: meta.base, branch: meta.branch, title: action.title, body: action.body, files });
+                if (runId)
+                    addStep(runId, 'Opened a pull request', url || action.title, 'ok');
+                return;
+            }
+            toOutbox(action, watch, runId);
+            return;
+        }
+        case 'revert':
+            // No client support yet: record the draft so a person can carry it out.
+            toOutbox(action, watch, runId);
+            return;
+        case 'mcp_tool':
+            await executeMcpTool(action);
+            return;
+        case 'slack_post':
+            await executeSlackPost(action, watch, runId);
+            return;
+        case 'case_retire':
+            // Retires the case and accepts its impact row. Its results stay.
+            executeCaseRetire(action);
+            return;
+        case 'report_edit':
+            // store.updateReport publishes the saved page as a `report` live event.
+            executeReportEdit(action);
+            return;
+        case 'file_defect':
+        case 'issue_create': {
+            // The filed URL and key go on the action, so the run, the approval and the next comment can link it.
+            const filed = await fileIssue(action, watch);
+            if (!filed) {
+                toOutbox(action, watch, runId);
+                return;
+            }
+            action.meta = { ...meta, filedUrl: filed.url, filedKey: filed.key };
+            if (action.kind === 'issue_create') {
+                const relates = Array.isArray(meta.relates) ? meta.relates.map(String) : [];
+                recordDefectLinks({ watchId: watch.id, defect: filed.key, requirements: relates, sig: typeof meta.sig === 'string' ? meta.sig : undefined });
+            }
+            return;
+        }
+    }
+}
+/** The files of an open_pr action when every path is a safe repo spec path, else null. */
+export function proposedFiles(v) {
+    if (!Array.isArray(v) || !v.length || v.length > 20)
+        return null;
+    const out = [];
+    for (const f of v) {
+        if (!f || typeof f !== 'object')
+            return null;
+        const { path, content } = f;
+        if (!safeRepoSpecPath(path) || typeof content !== 'string' || content.length > 50_000)
+            return null;
+        out.push({ path, content });
+    }
+    return out;
+}
+const strings = (v) => (Array.isArray(v) ? v.map(String).filter(Boolean) : undefined);
+/**
+ * Opens the defect in the tracker named by meta.tracker, through the one creator every tracker shares.
+ * null in demo mode: the draft goes to the outbox. A body keeps its signature marker even when an
+ * edit in the Inbox removed it, so the duplicate guard can still find the issue.
+ */
+async function fileIssue(action, watch) {
+    const meta = action.meta ?? {};
+    // A person may have edited the draft in the Inbox, so the text is redacted again right before it is posted.
+    const title = redactCode(action.title);
+    // meta is frozen at draft time; a person may have corrected the tracker since, so the watch as it is now wins.
+    const t = watch.tracker;
+    const tracker = meta.tracker === 'jira' || meta.tracker === 'linear' ? meta.tracker : 'github';
+    let project = String(meta.project ?? '');
+    let projectName;
+    if (tracker === 'jira' && t?.kind === 'jira' && t.projectKeys[0])
+        project = t.projectKeys[0];
+    if (tracker === 'linear') {
+        if (t?.kind === 'linear' && t.teamKeys[0])
+            project = t.teamKeys[0];
+        const frozen = typeof meta.projectName === 'string' && meta.projectName ? meta.projectName : undefined;
+        projectName = (t?.kind === 'linear' && t.projectName) || frozen;
+    }
+    if (tracker === 'github' && !project && watch.repo)
+        project = `${watch.repo.owner}/${watch.repo.name}`;
+    if (!project)
+        throw new Error(`no ${tracker} project to file "${title}" in`);
+    const sig = typeof meta.sig === 'string' && meta.sig ? meta.sig : undefined;
+    const redacted = redactCode(action.body);
+    const body = sig ? withDefectMarker(redacted, sig) : redacted;
+    const issueType = typeof meta.issueType === 'string' && meta.issueType ? meta.issueType : undefined;
+    const milestone = typeof meta.milestone === 'string' && meta.milestone ? meta.milestone : undefined;
+    // A defect from the PR review always carries the localdost label that the duplicate guard searches for.
+    const labels = strings(meta.labels) ?? [];
+    if (action.kind === 'file_defect' && !labels.some(isDefectLabel))
+        labels.push(DEFECT_LABEL);
+    return createTrackerIssue(tracker, project, { title, body, labels: labels.length ? labels : undefined, issueType, milestone, projectName }, { watch });
+}
+/** A person approved a draft whose automatic retry is still waiting out its backoff (KAT-178). The API answers 409. */
+export class RetryingError extends Error {
+    approvalId;
+    nextAt;
+    constructor(approvalId, nextAt) {
+        super(`approval ${approvalId} is retrying on its own; the next try is at ${nextAt}`);
+        this.approvalId = approvalId;
+        this.nextAt = nextAt;
+    }
+}
+/**
+ * Approves a pending draft and sends it. A send that fails with a transient error (5xx, timeout, reset, 429) stays pending
+ * with a `retry` state and is returned, not thrown: approval-retries.ts sends it again by itself (KAT-178), and a person can
+ * approve again only once that backoff has passed. Any other failure puts the draft back in the Inbox with the error and
+ * throws, so a person decides again. `auto` marks the retry loop's own call; `now` is for tests. `by` names the
+ * person who decided (a paired device's name, a Slack user); the record keeps it as `decidedBy` (KAT-356).
+ */
+export async function approveAction(approvalId, edit, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const approval = get('approvals', approvalId);
+    if (!approval)
+        throw new Error(`approval ${approvalId} not found`);
+    if (approval.status !== 'pending')
+        throw new Error(`approval ${approvalId} is already ${approval.status}`);
+    if (!opts.auto && approval.retry && Date.parse(approval.retry.nextAt) > now())
+        throw new RetryingError(approvalId, approval.retry.nextAt);
+    const watch = get('watches', approval.watchId);
+    if (!watch)
+        throw new Error(`watch ${approval.watchId} not found`);
+    const action = edit && edit.trim() ? { ...approval.action, body: edit } : approval.action;
+    const decidedAt = new Date(now()).toISOString();
+    // The retry loop's own call carries no person: the one who approved first stays on the record.
+    const decidedBy = opts.by ?? (opts.auto ? approval.decidedBy : undefined);
+    // 'approved' marks the send in flight; a failed send goes back to pending with the error, so it can be retried.
+    update('approvals', approvalId, { status: 'approved', decidedAt, action, ...(decidedBy ? { decidedBy } : {}) });
+    try {
+        await execute(action, watch, approval.runId);
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        const kind = classifySendError(err, now());
+        const retry = kind.transient ? nextRetry(approval.retry, error, kind.retryAfterMs, now()) : null;
+        const patch = { status: 'pending', error, retry };
+        // The time to decide starts again from the failure, so a draft retried for a day is not swept as expired.
+        if (retry && !approval.retry)
+            patch.expiresAt = new Date(Math.max(Date.parse(approval.expiresAt ?? '') || 0, now() + RETRY_WINDOW_MS + APPROVAL_TTL_MS)).toISOString();
+        update('approvals', approvalId, patch);
+        const pending = get('approvals', approvalId);
+        publish({ type: 'approval', approval: pending });
+        const detail = retry
+            ? `${error} Retrying on its own (attempt ${retry.attempt}, next try in ${waitText(Date.parse(retry.nextAt) - now())}).`
+            : kind.transient && approval.retry
+                ? `${error} Gave up retrying after 24 h. The draft is back in the Inbox.`
+                : `${error} The draft is back in the Inbox.`;
+        try {
+            addStep(approval.runId, `Send failed: ${action.title}`, detail, retry ? 'warn' : 'error');
+        }
+        catch {
+            /* run may be gone */
+        }
+        if (retry)
+            return pending;
+        throw err;
+    }
+    const executedAt = new Date(now()).toISOString();
+    update('approvals', approvalId, { status: 'executed', executedAt, action, retry: null });
+    const done = { ...approval, action, status: 'executed', decidedAt, executedAt, retry: null, ...(decidedBy ? { decidedBy } : {}) };
+    publish({ type: 'approval', approval: done });
+    try {
+        updateActionResult(approval.runId, approvalId, 'executed', action);
+        const detail = [decidedBy ? `Approved by ${decidedBy}.` : '', edit ? 'Sent with your edits.' : ''].filter(Boolean).join(' ');
+        addStep(approval.runId, `Approved and sent: ${action.title}`, detail || undefined, 'ok');
+    }
+    catch (err) {
+        console.warn('[rules] could not update run after approval', err);
+    }
+    return done;
+}
+/** Closing writes still in flight, so a test or a shutdown can wait for them. */
+const closing = new Set();
+/** Resolves when every closing write started so far has finished. */
+export async function closingChecksIdle() {
+    while (closing.size)
+        await Promise.all([...closing]);
+}
+/**
+ * A report that waited in the Inbox left its commit's check at "Report waiting for approval" (KAT-285). When
+ * a person rejects it, or it expires, that note is closed: neutral on an App check, a success status on a
+ * token (a commit status has no neutral). The write follows from the decision, so it skips the gate and the
+ * auto-review. A failed write is logged and never undoes the decision; a re-review of the same head writes
+ * its own check or status afterwards and replaces this one.
+ */
+export async function closeCheckAfterDecision(approval, decision) {
+    const { action } = approval;
+    if (action.kind !== 'check_run' || action.meta?.templated === true)
+        return;
+    const sha = String(action.meta?.sha ?? '');
+    if (!sha)
+        return;
+    const watch = get('watches', approval.watchId);
+    if (!watch)
+        return;
+    const verb = decision === 'rejected' ? 'Rejected' : 'Expired';
+    const runUrl = config.publicUrl && approval.runId ? `${config.publicUrl.replace(/\/$/, '')}/#/runs/${approval.runId}` : undefined;
+    const meta = {
+        sha,
+        templated: true,
+        status: 'completed',
+        conclusion: 'neutral',
+        statusDescription: `Report not posted: ${verb.toLowerCase()} in localdost`,
+        ...(action.meta?.checkRunId ? { checkRunId: action.meta.checkRunId } : {}),
+    };
+    const closeAction = {
+        kind: 'check_run',
+        target: action.target,
+        title: 'Report not posted',
+        body: `${verb} in localdost${runUrl ? `\n\nRun: ${runUrl}` : ''}`,
+        meta,
+    };
+    try {
+        await execute(closeAction, watch, approval.runId || undefined);
+    }
+    catch (err) {
+        console.warn(`[rules] could not close the check of approval ${approval.id}: ${String(err)}`);
+    }
+}
+/** Starts a closing write without making the caller wait for GitHub. */
+function closeCheckInBackground(approval, decision) {
+    const p = closeCheckAfterDecision(approval, decision).finally(() => closing.delete(p));
+    closing.add(p);
+}
+setCheckCloseHook((approval, status) => closeCheckInBackground(approval, status));
+/**
+ * Rejects a pending approval. With `closedReason` the server is closing it, not a person: the reason is
+ * stored on the approval and shown in the run's step instead of "You rejected this draft." `by` names the
+ * person who rejected it (KAT-356); the step then says who instead of "You".
+ */
+export async function rejectAction(approvalId, closedReason, opts = {}) {
+    const approval = get('approvals', approvalId);
+    if (!approval)
+        throw new Error(`approval ${approvalId} not found`);
+    if (approval.status !== 'pending')
+        throw new Error(`approval ${approvalId} is already ${approval.status}`);
+    const decidedAt = new Date().toISOString();
+    const decidedBy = closedReason ? undefined : opts.by;
+    update('approvals', approvalId, { status: 'rejected', decidedAt, ...(closedReason ? { closedReason } : {}), ...(decidedBy ? { decidedBy } : {}) });
+    const done = { ...approval, status: 'rejected', decidedAt, ...(closedReason ? { closedReason } : {}), ...(decidedBy ? { decidedBy } : {}) };
+    publish({ type: 'approval', approval: done });
+    try {
+        updateActionResult(approval.runId, approvalId, 'blocked');
+        addStep(approval.runId, `Rejected: ${approval.action.title}`, closedReason ?? (decidedBy ? `Rejected by ${decidedBy}.` : 'You rejected this draft.'), 'info');
+    }
+    catch (err) {
+        console.warn('[rules] could not update run after rejection', err);
+    }
+    await closeCheckAfterDecision(approval, 'rejected');
+    return done;
+}
+//# sourceMappingURL=rules.js.map