openmausbot 0.1.55

package/dist-server/server/attachments.js

@@ -0,0 +1,471 @@
+// Image attachments: pasted/dropped images become files under
+// ~/.openmausbot/attachments so every CLI engine can open them by path —
+// the app never ships image bytes through the prompt itself.
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, linkSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { link, open, unlink } from "node:fs/promises";
+import { join, extname } from "node:path";
+import { DATA_DIR } from "./config.js";
+export const ATTACHMENTS_DIR = join(DATA_DIR, "attachments");
+/** The spec's ceiling: a screenshot bigger than this is rejected before it
+ * is ever buffered, matching the composer's existing size discipline. */
+export const IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+/** Shared documents are deliberately smaller than Cloudflare's transport
+ * ceiling. This is a local inbox, not unbounded remote storage. */
+export const FILE_MAX_BYTES = 25 * 1024 * 1024;
+/** Attachments are durable because prompts refer to their paths. Never
+ * silently evict them: once this ceiling is reached, a new upload gets an
+ * explicit 507 and the person can decide what to remove. */
+export const ATTACHMENTS_MAX_BYTES = 512 * 1024 * 1024;
+/** Interrupted streamed uploads use private partial files. A crash can leave
+ * one behind, so future uploads remove only our stale partials — never a
+ * committed attachment that a transcript may still reference. */
+export const ATTACHMENT_PARTIAL_MAX_AGE_MS = 60 * 60 * 1000;
+const PARTIAL_NAME = /^\.openmaus-upload-[0-9a-f-]+-[0-9a-f-]+\.partial$/i;
+const UPLOAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const activePartials = new Set();
+const uploadLocks = new Map();
+let reservedAttachmentBytes = 0;
+const STREAM_RESERVATION_INCREMENT_BYTES = 1024 * 1024;
+/** Mimes the endpoint accepts, mapped to the extension stored on disk.
+ * Sniffing is not attempted — a lie here only changes the filename. */
+const IMAGE_MIMES = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+};
+/** Useful document formats accepted by the phone share sheet.
+ * Generic archives, binaries, HTML, SVG, and executable/script mimes stay
+ * out. Office/OpenDocument packages are allowed because they are documents,
+ * despite using ZIP internally. The claimed mime determines the extension;
+ * an attacker-controlled filename never does. */
+const FILE_MIMES = {
+    "text/plain": ".txt",
+    "text/markdown": ".md",
+    "text/csv": ".csv",
+    "text/tab-separated-values": ".tsv",
+    "application/json": ".json",
+    "application/pdf": ".pdf",
+    "application/rtf": ".rtf",
+    "text/rtf": ".rtf",
+    "application/msword": ".doc",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+    "application/vnd.ms-excel": ".xls",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.ms-powerpoint": ".ppt",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+    "application/vnd.oasis.opendocument.text": ".odt",
+    "application/vnd.oasis.opendocument.spreadsheet": ".ods",
+    "application/vnd.oasis.opendocument.presentation": ".odp",
+};
+export function extensionForMime(mime) {
+    if (!mime)
+        return null;
+    return IMAGE_MIMES[mime.split(";")[0].trim().toLowerCase()] ?? null;
+}
+export function ensureAttachmentsDir() {
+    mkdirSync(ATTACHMENTS_DIR, { recursive: true, mode: 0o700 });
+}
+export function validateAttachmentUploadId(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (!UPLOAD_ID.test(normalized)) {
+        throw statusError(400, "uploadId must be a UUID");
+    }
+    return normalized;
+}
+function attachmentUsageAndCleanup(now = Date.now()) {
+    ensureAttachmentsDir();
+    let bytes = 0;
+    let removed = 0;
+    for (const entry of readdirSync(ATTACHMENTS_DIR, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        const path = join(ATTACHMENTS_DIR, entry.name);
+        // A live partial is represented by its in-memory reservation. A fresh
+        // orphan from a crashed process still occupies disk and therefore counts
+        // until this same scan is allowed to remove it.
+        if (PARTIAL_NAME.test(entry.name) && activePartials.has(path))
+            continue;
+        try {
+            const stat = statSync(path);
+            if (PARTIAL_NAME.test(entry.name) && now - stat.mtimeMs >= ATTACHMENT_PARTIAL_MAX_AGE_MS) {
+                unlinkSync(path);
+                removed += 1;
+            }
+            else {
+                bytes += stat.size;
+            }
+        }
+        catch {
+            // A concurrent cleanup or manual removal made this entry consume zero.
+        }
+    }
+    return { bytes, removed };
+}
+/** Remove only abandoned temporary uploads. Active partials are protected
+ * even if a very slow request crosses the age threshold. */
+export function cleanupStaleAttachmentPartials(now = Date.now()) {
+    return attachmentUsageAndCleanup(now).removed;
+}
+/** A retry owns the same UUID namespace as the interrupted attempt. Once it
+ * holds that UUID's in-process lock, any inactive partial with the prefix is
+ * from a crashed/failed process and can be replaced immediately instead of
+ * consuming quota for an hour. */
+function cleanupAttachmentPartialsForUpload(uploadId) {
+    ensureAttachmentsDir();
+    const prefix = `.openmaus-upload-${uploadId}-`;
+    for (const entry of readdirSync(ATTACHMENTS_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.startsWith(prefix) || !PARTIAL_NAME.test(entry.name))
+            continue;
+        const path = join(ATTACHMENTS_DIR, entry.name);
+        if (activePartials.has(path))
+            continue;
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // A concurrent cleanup already removed the abandoned attempt.
+        }
+    }
+}
+class AttachmentReservation {
+    held = 0;
+    released = false;
+    reserve(bytes) {
+        if (this.released || bytes <= 0)
+            return;
+        this.reserveAtLeast(bytes, bytes);
+    }
+    reserveAtLeast(required, preferred) {
+        const used = attachmentUsageAndCleanup().bytes;
+        const available = ATTACHMENTS_MAX_BYTES - used - reservedAttachmentBytes;
+        if (available < required) {
+            throw statusError(507, `attachments storage is full (limit ${ATTACHMENTS_MAX_BYTES} bytes)`);
+        }
+        // Unknown-length HTTP bodies reserve in bounded chunks. Taking whatever
+        // remains below the preferred increment avoids falsely rejecting a small
+        // final upload near the quota while still bounding directory scans.
+        const granted = Math.min(preferred, available);
+        reservedAttachmentBytes += granted;
+        this.held += granted;
+    }
+    ensure(bytes) {
+        if (bytes <= this.held)
+            return;
+        const required = bytes - this.held;
+        const remainingPerFileCapacity = FILE_MAX_BYTES - this.held;
+        const preferred = Math.min(Math.max(required, STREAM_RESERVATION_INCREMENT_BYTES), remainingPerFileCapacity);
+        this.reserveAtLeast(required, preferred);
+    }
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        reservedAttachmentBytes -= this.held;
+        this.held = 0;
+    }
+}
+async function withUploadLock(uploadId, operation) {
+    if (!uploadId)
+        return operation();
+    const previous = uploadLocks.get(uploadId) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    uploadLocks.set(uploadId, current);
+    await previous;
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+        if (uploadLocks.get(uploadId) === current)
+            uploadLocks.delete(uploadId);
+    }
+}
+function committedPathForUpload(uploadId, extension) {
+    ensureAttachmentsDir();
+    const exact = `${uploadId}${extension}`;
+    for (const entry of readdirSync(ATTACHMENTS_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || PARTIAL_NAME.test(entry.name))
+            continue;
+        if (entry.name === exact)
+            return join(ATTACHMENTS_DIR, entry.name);
+        if (entry.name.startsWith(`${uploadId}.`)) {
+            throw statusError(409, "uploadId was already used for another content type");
+        }
+    }
+    return null;
+}
+async function digestFile(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+function statusError(status, message) {
+    return Object.assign(new Error(message), { status });
+}
+function normalizedMime(mime) {
+    const value = mime?.split(";")[0]?.trim().toLowerCase();
+    return value || null;
+}
+export function extensionForFileMime(mime) {
+    const value = normalizedMime(mime);
+    return value ? FILE_MIMES[value] ?? null : null;
+}
+/** Strip platform-reserved characters and replace any sender-provided
+ * extension with the canonical one for the accepted mime. Separators and
+ * encoded separators are rejected rather than massaged so traversal attempts
+ * remain visible as bad requests. */
+export function sanitizeSharedFileName(name, mime) {
+    const extension = extensionForFileMime(mime);
+    if (!extension)
+        throw statusError(400, "content-type must be a supported document type");
+    const normalized = name.normalize("NFKC").trim();
+    if (!normalized)
+        throw statusError(400, "name is required");
+    if (normalized.length > 512)
+        throw statusError(400, "name is too long");
+    if (/[\\/]/.test(normalized) || /%(?:00|2f|5c)/i.test(normalized)) {
+        throw statusError(400, "name must be a filename, not a path");
+    }
+    const dot = normalized.lastIndexOf(".");
+    const withoutExtension = dot > 0 ? normalized.slice(0, dot) : normalized;
+    const safeCharacters = Array.from(withoutExtension, (character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31 || code === 127 || "<>:\"|?*".includes(character) ? "_" : character;
+    }).join("");
+    const stem = safeCharacters
+        .replace(/^\.+/, "")
+        .replace(/[.\s]+$/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+    const boundedStem = Array.from(stem).slice(0, 180).join("");
+    if (!boundedStem)
+        throw statusError(400, "name must contain visible characters");
+    return `${boundedStem}${extension}`;
+}
+/** Stream one shared document to a generated file without ever collecting
+ * the request in memory. A failed, empty, or oversized upload leaves no
+ * partial file behind. */
+export async function saveFile(chunks, originalName, mime, options = {}) {
+    const normalized = normalizedMime(mime);
+    if (!normalized || !extensionForFileMime(normalized)) {
+        throw statusError(400, "content-type must be a supported document type");
+    }
+    const name = sanitizeSharedFileName(originalName, normalized);
+    const extension = extensionForFileMime(normalized);
+    const uploadId = validateAttachmentUploadId(options.uploadId);
+    const expectedBytes = options.expectedBytes;
+    if (expectedBytes !== undefined && (!Number.isSafeInteger(expectedBytes) || expectedBytes < 0)) {
+        throw statusError(400, "content-length must be a non-negative integer");
+    }
+    if (expectedBytes !== undefined && expectedBytes > FILE_MAX_BYTES) {
+        throw statusError(413, `file exceeds ${FILE_MAX_BYTES} bytes`);
+    }
+    return withUploadLock(uploadId, async () => {
+        ensureAttachmentsDir();
+        if (uploadId)
+            cleanupAttachmentPartialsForUpload(uploadId);
+        const existing = uploadId ? committedPathForUpload(uploadId, extension) : null;
+        if (existing) {
+            const incomingHash = createHash("sha256");
+            let bytes = 0;
+            for await (const value of chunks) {
+                const chunk = Buffer.isBuffer(value)
+                    ? value
+                    : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+                if (chunk.byteLength === 0)
+                    continue;
+                if (bytes + chunk.byteLength > FILE_MAX_BYTES) {
+                    throw statusError(413, `file exceeds ${FILE_MAX_BYTES} bytes`);
+                }
+                incomingHash.update(chunk);
+                bytes += chunk.byteLength;
+            }
+            if (bytes === 0)
+                throw statusError(400, "empty file");
+            if (statSync(existing).size !== bytes || await digestFile(existing) !== incomingHash.digest("hex")) {
+                throw statusError(409, "uploadId was already used for different file bytes");
+            }
+            return { path: existing, name, mime: normalized, bytes };
+        }
+        const id = uploadId ?? randomUUID();
+        const path = join(ATTACHMENTS_DIR, `${id}${extension}`);
+        const partialPath = join(ATTACHMENTS_DIR, `.openmaus-upload-${id}-${randomUUID()}.partial`);
+        const reservation = new AttachmentReservation();
+        if (expectedBytes)
+            reservation.reserve(expectedBytes);
+        activePartials.add(partialPath);
+        let file;
+        let bytes = 0;
+        let closed = false;
+        try {
+            file = await open(partialPath, "wx", 0o600);
+            for await (const value of chunks) {
+                const chunk = Buffer.isBuffer(value)
+                    ? value
+                    : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+                if (chunk.byteLength === 0)
+                    continue;
+                if (bytes + chunk.byteLength > FILE_MAX_BYTES) {
+                    throw statusError(413, `file exceeds ${FILE_MAX_BYTES} bytes`);
+                }
+                reservation.ensure(bytes + chunk.byteLength);
+                let offset = 0;
+                while (offset < chunk.byteLength) {
+                    const result = await file.write(chunk, offset, chunk.byteLength - offset, null);
+                    if (result.bytesWritten === 0)
+                        throw new Error("file write made no progress");
+                    offset += result.bytesWritten;
+                }
+                bytes += chunk.byteLength;
+            }
+            if (bytes === 0)
+                throw statusError(400, "empty file");
+            await file.close();
+            closed = true;
+            try {
+                await link(partialPath, path);
+                await unlink(partialPath);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (statSync(path).size !== bytes || await digestFile(path) !== await digestFile(partialPath)) {
+                    throw statusError(409, "uploadId was already used for different file bytes");
+                }
+                await unlink(partialPath);
+            }
+            return { path, name, mime: normalized, bytes };
+        }
+        catch (error) {
+            if (file && !closed)
+                await file.close().catch(() => undefined);
+            await unlink(partialPath).catch(() => undefined);
+            throw error;
+        }
+        finally {
+            activePartials.delete(partialPath);
+            reservation.release();
+        }
+    });
+}
+/** Persist one image and return its path. The UUID filename means the name
+ * is never attacker-controlled and never collides; the extension preserves
+ * the format the sender claimed. */
+export function saveImage(bytes, mime, requestedUploadId) {
+    const ext = extensionForMime(mime);
+    if (!ext)
+        throw Object.assign(new Error("unsupported image type"), { status: 400 });
+    if (bytes.byteLength === 0)
+        throw Object.assign(new Error("empty image"), { status: 400 });
+    if (bytes.byteLength > IMAGE_MAX_BYTES) {
+        throw Object.assign(new Error(`image exceeds ${IMAGE_MAX_BYTES} bytes`), { status: 413 });
+    }
+    const uploadId = validateAttachmentUploadId(requestedUploadId);
+    ensureAttachmentsDir();
+    const existing = uploadId ? committedPathForUpload(uploadId, ext) : null;
+    if (existing) {
+        const saved = readFileSync(existing);
+        if (!saved.equals(bytes)) {
+            throw statusError(409, "uploadId was already used for different image bytes");
+        }
+        return { path: existing, mime: mime.split(";")[0].trim().toLowerCase(), bytes: bytes.byteLength };
+    }
+    const reservation = new AttachmentReservation();
+    reservation.reserve(bytes.byteLength);
+    const id = uploadId ?? randomUUID();
+    const name = `${id}${ext}`;
+    const path = join(ATTACHMENTS_DIR, name);
+    const partialPath = join(ATTACHMENTS_DIR, `.openmaus-upload-${id}-${randomUUID()}.partial`);
+    activePartials.add(partialPath);
+    try {
+        writeFileSync(partialPath, bytes, { mode: 0o600, flag: "wx" });
+        try {
+            linkSync(partialPath, path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const saved = readFileSync(path);
+            if (!saved.equals(bytes)) {
+                throw statusError(409, "uploadId was already used for different image bytes");
+            }
+        }
+        unlinkSync(partialPath);
+        return { path, mime: mime.split(";")[0].trim().toLowerCase(), bytes: bytes.byteLength };
+    }
+    catch (error) {
+        try {
+            unlinkSync(partialPath);
+        }
+        catch {
+            // The successful path already removed it, or the write never created it.
+        }
+        throw error;
+    }
+    finally {
+        activePartials.delete(partialPath);
+        reservation.release();
+    }
+}
+/** HTTP uploads take the same per-ID lock as streamed files. saveImage stays
+ * synchronous for generated avatars, while this wrapper prevents an image
+ * and a document using the same caller-supplied UUID from committing with
+ * different extensions at the same time. */
+export async function saveImageUpload(bytes, mime, requestedUploadId) {
+    const uploadId = validateAttachmentUploadId(requestedUploadId);
+    return withUploadLock(uploadId, async () => {
+        if (uploadId)
+            cleanupAttachmentPartialsForUpload(uploadId);
+        return saveImage(bytes, mime, uploadId);
+    });
+}
+/** Existence check with the same name discipline as readAttachment, without
+ * reading up to 10MB of pixels just to learn the file is there. */
+export function attachmentExists(name) {
+    if (!/^[A-Za-z0-9-]+\.(png|jpg|gif|webp)$/.test(name))
+        return false;
+    try {
+        return statSync(join(ATTACHMENTS_DIR, name)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Read an attachment back for serving. Only names that are exactly a bare
+ * filename (no separators, no dotfiles) inside ATTACHMENTS_DIR resolve —
+ * the route must never become a general file server for the data dir. */
+export function readAttachment(name) {
+    if (!/^[A-Za-z0-9-]+\.(png|jpg|jpeg|gif|webp)$/.test(name))
+        return null;
+    const path = join(ATTACHMENTS_DIR, name);
+    if (extname(path) === ".jpeg")
+        return null; // saved as .jpg; .jpeg is not a name we write
+    try {
+        return { bytes: readFileSync(path), mime: mimeForExt(extname(path)) };
+    }
+    catch {
+        return null;
+    }
+}
+function mimeForExt(ext) {
+    switch (ext) {
+        case ".png":
+            return "image/png";
+        case ".jpg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        default:
+            return "application/octet-stream";
+    }
+}

package/dist-server/server/auto-approve.js

@@ -0,0 +1,162 @@
+// Auto mode: when a bot may answer its own permission requests.
+//
+// Safe Auto and remembered grants stop at the destructive/sensitive and
+// unattended boundaries below. Full access is a separate, explicitly
+// acknowledged mode: it answers every permission request, including those
+// guards, while questions remain outside this module and always reach a human.
+//
+// The guard is deliberately tiny and literal. It is NOT a security
+// boundary (an agent set on damage has a thousand spellings for `rm`);
+// it is a "you probably didn't mean to hand THIS one over unattended"
+// backstop for the obvious catastrophes. Real containment is the
+// sandbox and the bot's own computer, not a regex.
+import { approvalModeFor } from "../shared/approval-mode.js";
+const DESTRUCTIVE = [
+    /\brm\s+(-[a-z]*\s+)*-[a-z]*[rf]/i, // rm -rf, rm -fr, rm -r -f
+    /\bmkfs\b|\bdiskutil\s+erase|\bdd\s+[^|]*\bof=\/dev\//i,
+    /\bshutdown\b|\breboot\b|\bhalt\b/i,
+    /:\(\)\s*\{.*\}\s*;?\s*:/, // fork bomb
+    /\bgit\s+push\s+[^|]*--force(-with-lease)?\b|\bgit\s+reset\s+--hard\b/i,
+    /\bDROP\s+(TABLE|DATABASE)\b|\bTRUNCATE\s+TABLE\b/i,
+    /\bsudo\s+rm\b|\bchmod\s+-R\s+777\s+\//i,
+];
+// Not destructive, but exactly what you don't hand over unattended: a
+// bot reading your keys is quiet, permanent, and unrecoverable.
+const SENSITIVE = [
+    /(^|[\s/"'])\.env(\.|$|["'\s])/i,
+    /\.ssh\/|id_rsa|id_ed25519|authorized_keys/i,
+    /\.aws\/credentials|\.netrc|\.npmrc|\.pypirc|\.docker\/config\.json/i,
+    /security\s+find-(generic|internet)-password|\bkeychain\b/i,
+    /\bcredentials?\.json\b|\bserviceaccount\b/i,
+];
+/** First matching pattern's source, so a verdict can NAME the rule that
+ * made it — the decision log's whole value is "which rule", and deriving
+ * the match a second time at the call site is how the log and the verdict
+ * drift apart. */
+function matchFirst(rules, text) {
+    for (const re of rules)
+        if (re.test(text))
+            return re.source;
+    return null;
+}
+export function looksSensitive(text) {
+    return matchFirst(SENSITIVE, text) !== null;
+}
+export function looksDestructive(text) {
+    return matchFirst(DESTRUCTIVE, text) !== null;
+}
+/** The key an "Always allow" remembers.
+ *
+ * A bare tool name is far too coarse for a command runner: remembering
+ * "Bash" would hand the bot a permanent unattended shell, which is the
+ * opposite of what someone pressing "always allow" on `git status`
+ * intends. Command tools are therefore keyed by their program —
+ * `Bash:git`, `Bash:npm` — so the grant is as narrow as the thing you
+ * actually looked at. Computed once, server-side, and echoed back by the
+ * client so the two sides can never disagree about what was granted. */
+const COMMAND_TOOLS = new Set(["bash", "shell", "execute", "run_command", "computer_exec", "terminal"]);
+export function approvalKey(tool, summary, scope) {
+    const bare = tool.replace(/^mcp__[^_]+__/, "").toLowerCase();
+    if (!COMMAND_TOOLS.has(bare))
+        return scope ? `${scope}:${tool}` : tool;
+    // first bare word of the command, skipping env assignments and sudo
+    const words = summary.trim().split(/\s+/);
+    let i = 0;
+    while (i < words.length && (/^[A-Z_][A-Z0-9_]*=/.test(words[i]) || words[i] === "sudo"))
+        i += 1;
+    const program = (words[i] ?? "").split("/").pop()?.replace(/[^\w.-]/g, "") ?? "";
+    const key = program ? `${tool}:${program}` : tool;
+    return scope ? `${scope}:${key}` : key;
+}
+/** A durable "Always allow" choice is offered only when that exact grant
+ * would be honored on the next identical request. Custom delegates approval
+ * semantics to config.toml, while guards and provider-sandbox changes are
+ * intentionally never bypassed by remembered app grants. */
+export function rememberableApprovalKey(bot, tool, summary, context) {
+    if (!bot ||
+        approvalModeFor(bot) === "custom" ||
+        context.source !== "no-grant" ||
+        context.scope ||
+        context.requiresExplicitApproval) {
+        return undefined;
+    }
+    return approvalKey(tool, summary, context.scope);
+}
+/** The verdict AND its provenance. The decision itself is unchanged from
+ * autoDecision below — this exists so the decision log can record which
+ * rule decided without the call site re-deriving (and eventually
+ * mis-deriving) the match. */
+export function autoVerdict(bot, tool, summary, context) {
+    const mode = approvalModeFor(bot);
+    if (context?.nativeApproval)
+        return { approve: null, source: "native-approval" };
+    // This branch intentionally precedes every guard. Entering Full access is
+    // separately consent-gated by the bot PATCH endpoint, and its promise is
+    // literal: even destructive, sensitive, unattended, and host-computer
+    // permission requests are approved. The request.opened caller invokes this
+    // function for permissions only, never for provider questions.
+    if (mode === "full") {
+        return {
+            approve: `approved ${tool} (full access)`,
+            source: "full-access",
+        };
+    }
+    if (context?.requiresExplicitApproval) {
+        return { approve: null, source: "explicit-approval-block" };
+    }
+    // the guards outrank the grants, so an "always allow" can never widen
+    // into them
+    const destructive = matchFirst(DESTRUCTIVE, summary) ?? matchFirst(DESTRUCTIVE, tool);
+    const sensitive = destructive ? null : matchFirst(SENSITIVE, summary);
+    // The grant is computed even when a hard block will refuse it: the row
+    // worth auditing is "this WOULD have auto-approved, and only the block
+    // stood in the way", which cannot be told apart from an ordinary
+    // "nobody granted this" card without knowing both halves.
+    const key = approvalKey(tool, summary, context?.scope);
+    const grant = destructive || sensitive
+        ? null
+        : mode !== "custom" && bot.alwaysAllow?.includes(key)
+            ? { approve: `auto-approved ${key} (always allowed)`, source: "always-allow", rule: key }
+            : mode === "auto"
+                ? { approve: `auto-approved ${tool}`, source: "auto-mode", rule: undefined }
+                : null;
+    if (context?.unattended) {
+        // Auto mode is something a person switched on for turns they are present
+        // for. A webhook turn begins with nobody watching, on a payload someone
+        // else wrote, so it does not inherit that decision — the guard above is a
+        // pattern list its own comment calls "not a security boundary", and it
+        // must not stand in for a human at 3am. A guard that would have carded
+        // anyway keeps its own name; the block is only the story when it is the
+        // thing that changed the outcome.
+        if (grant)
+            return { approve: null, source: "unattended-block", rule: grant.rule };
+        if (destructive)
+            return { approve: null, source: "destructive-guard", rule: destructive };
+        if (sensitive)
+            return { approve: null, source: "sensitive-guard", rule: sensitive };
+        return { approve: null, source: "no-grant" };
+    }
+    if (context?.scope === "local-computer" && mode !== "auto") {
+        // Host control is not covered by a remembered always-allow grant.
+        // After the Auto-on-this-computer warning, unclassified GUI actions
+        // (click/type) may auto-approve; destructive/sensitive still card.
+        if (grant)
+            return { approve: null, source: "local-computer-block", rule: grant.rule };
+        if (destructive)
+            return { approve: null, source: "destructive-guard", rule: destructive };
+        if (sensitive)
+            return { approve: null, source: "sensitive-guard", rule: sensitive };
+        return { approve: null, source: "no-grant" };
+    }
+    if (destructive)
+        return { approve: null, source: "destructive-guard", rule: destructive };
+    if (sensitive)
+        return { approve: null, source: "sensitive-guard", rule: sensitive };
+    if (grant)
+        return { approve: grant.approve, source: grant.source, rule: grant.rule };
+    return { approve: null, source: "no-grant" };
+}
+/** Why this request may be answered without the human, or null to ask. */
+export function autoDecision(bot, tool, summary, context) {
+    return autoVerdict(bot, tool, summary, context).approve;
+}