things-api 0.18.0 → 0.19.0

package/dist/audit/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8EzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}

package/dist/capability.d.ts

@@ -0,0 +1,160 @@
+import { type HostAccessDeps, type HostApp } from "./host-access.ts";
+export { fdaGranted, type FdaVerdict, type HostApp, hostApp, hostDisplayName, tccDbPath, } from "./host-access.ts";
+/** The Things application's bundle identifier — the Automation grant's target. */
+export declare const THINGS_BUNDLE_ID = "com.culturedcode.ThingsMac";
+/** How reads may reach the live library, if at all. */
+export type ReadCapabilityMode = 
+/** A caller-supplied database path — outside the doctrine entirely (Article VI). */
+"explicit-db"
+/** Reads ride the sandboxed reader; the read itself is the capability check. */
+ | "helpers"
+/** The helpers are expected here but cannot serve — refuse, never fall back. */
+ | "helpers-unavailable"
+/** No helpers, but the host app holds Full Disk Access. */
+ | "direct-fda"
+/** A ceremony witnessed an app-data grant that is still live for this app instance. */
+ | "session-grant"
+/** Nothing can open the container — the caller must run a setup ceremony. */
+ | "none";
+/** How GUI-driving may be delivered, if at all (Article IV). */
+export type UiCapabilityMode = 
+/** The helper pair holds Accessibility + Automation→System Events. */
+"helpers"
+/** The lab's documented in-guest escape (see {@link UI_DIRECT_ESCAPE_ENV}). */
+ | "direct-escape"
+/** GUI-driving is switched off in config — nothing has been asked for yet. */
+ | "config-disabled"
+/** No deputy answers, so there is no identity that could hold the grants. */
+ | "helpers-missing"
+/** The deputy answers but the `--gui` tier is incomplete. */
+ | "tier-incomplete";
+/** How app automation may be delivered, if at all. */
+export type WriteCapabilityMode = 
+/** The deputy is onboarded; Apple Events are sent under the helper identity. */
+"deputy"
+/** macOS records an Automation grant for the host app against Things. */
+ | "direct-granted"
+/** macOS records a REFUSAL. It will not re-ask; the human must re-arm it. */
+ | "direct-denied"
+/** No record either way, or none readable — never resolved by prompting. */
+ | "direct-unknown";
+export interface Capability<Mode> {
+    mode: Mode;
+    /** One sentence of provenance, for `doctor` and for refusal copy. */
+    detail: string;
+    /**
+     * The remediation lines a refusal prints, in the order they should be
+     * offered. Empty when the capability is present.
+     */
+    remediation: string[];
+    /** The identity a direct-mode grant would attach to. */
+    host: HostApp;
+}
+export type ReadCapability = Capability<ReadCapabilityMode>;
+export type WriteCapability = Capability<WriteCapabilityMode>;
+export type UiCapability = Capability<UiCapabilityMode>;
+/** True when this verdict permits opening the live container. */
+export declare function readAllowed(capability: ReadCapability): boolean;
+/** True when this verdict permits driving the Things window. */
+export declare function uiAllowed(capability: UiCapability): boolean;
+/** True when app automation may be dispatched. */
+export declare function writeAllowed(capability: WriteCapability): boolean;
+/**
+ * Injection seams. Every one of these defaults to a real, prompt-free probe;
+ * tests replace them so no test ever touches the host's TCC state.
+ */
+export interface CapabilityDeps extends HostAccessDeps {
+    /** Are this process's database reads actually being served by the reader? */
+    helpersServing?: () => boolean;
+    /** Are the helpers expected on this machine (enabled, and installed under auto)? */
+    helpersExpected?: () => boolean;
+    /** Why the helpers are not serving, for the loud refusal. */
+    helpersReason?: () => string | null;
+    /** The deputy's `automation.things` standing, from its handshake. */
+    deputyAutomation?: () => string | undefined;
+    /**
+     * The deputy's GUI-driving standing, from the same handshake: whether it is
+     * Accessibility-trusted and where its Automation→System Events grant stands.
+     * `null` means no deputy answered at all.
+     */
+    deputyGuiStanding?: () => {
+        axTrusted: boolean | undefined;
+        systemEvents: string | undefined;
+    } | null;
+    /** Is GUI-driving switched on in config (`ui-enabled`)? */
+    uiEnabled?: () => boolean;
+    /**
+     * Read one Automation row out of TCC.db. Returns the raw `auth_value`, or
+     * null when there is no row / the file cannot be read.
+     */
+    automationAuthValue?: (client: string, target: string) => number | null;
+    /** Resolve a running app's display name from its bundle id (LaunchServices). */
+    lookupAppName?: (bundleId: string) => string | null;
+}
+/**
+ * Can this process read the live Things library, and on whose authority?
+ *
+ * Stateless: every call re-derives the verdict, because a grant can appear or
+ * vanish between one invocation and the next and a cached "yes" would be a
+ * stored onboarding flag by another name. The common case costs one `open(2)`.
+ */
+export declare function readCapability(options?: {
+    dbPath?: string;
+}, deps?: CapabilityDeps): ReadCapability;
+/** Thrown when a read is refused for want of capability (Article II). */
+export declare class ReadCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: ReadCapability;
+    constructor(capability: ReadCapability);
+}
+/**
+ * May this process drive Things over Apple Events, and on whose authority?
+ *
+ * The deputy wins when it is onboarded (its own handshake reports the grant it
+ * holds). Otherwise the host app's own Automation record is read out of TCC —
+ * granted, denied, or, when there is no record at all, `direct-unknown`. That
+ * last state is deliberately NOT resolved here: resolving it means sending a
+ * real Apple Event, which is what raises the dialog, and Article I reserves
+ * that for `things setup`.
+ */
+export declare function writeCapability(deps?: CapabilityDeps): WriteCapability;
+/** Thrown when app automation is refused for want of capability (Article II). */
+export declare class WriteCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: WriteCapability;
+    constructor(capability: WriteCapability);
+}
+/**
+ * The LAB's escape hatch, and deliberately not consumer surface. The VM lab and
+ * the guest e2e bundle drive the UI vector DIRECT — the in-guest Accessibility
+ * grant is held by the runner's own processes (the AXVM1 layer), there is no
+ * helper bundle in a disposable clone, and there is nobody to answer a dialog
+ * either. Setting this to `1` restores direct UI-vector availability for that
+ * one situation. It is documented in docs/lab/harness.md and exported by the
+ * lab's guest environment; nothing consumer-facing mentions it, and it does not
+ * bypass `ui.enabled` — a lab clone still sets that key explicitly.
+ */
+export declare const UI_DIRECT_ESCAPE_ENV = "THINGS_API_UI_DIRECT";
+/**
+ * May this process drive the Things WINDOW, and on whose authority?
+ *
+ * Article IV admits exactly one provenance: the helper pair. Accessibility on a
+ * general-purpose host app (a terminal, an agent harness, an MCP host) has a
+ * blast radius far beyond Things, churns with every host update, and has no
+ * sane story at all over ssh — so direct AX is unsupported, and a refusal here
+ * names the config knob and `things helpers setup --gui` rather than raising an
+ * Accessibility prompt against whatever happens to be running us.
+ *
+ * Every answer is prompt-free: the config key is a file read, and the deputy's
+ * `hello` carries `AXIsProcessTrusted()` plus its own `AEDeterminePermission`
+ * verdict for System Events.
+ */
+export declare function uiCapability(deps?: CapabilityDeps): UiCapability;
+/** Thrown when GUI-driving is refused for want of capability (Article IV). */
+export declare class UiCapabilityError extends Error {
+    readonly remediation: string[];
+    readonly capability: UiCapability;
+    constructor(capability: UiCapability);
+}
+/** Test seam: forget the one memo this module keeps (the host's display name). */
+export declare function resetCapabilityForTests(): void;

package/dist/capability.js

@@ -0,0 +1,416 @@
+/**
+ * Prompt-free capability detection (docs/design/permissions-doctrine.md,
+ * Articles I–III).
+ *
+ * Every entry point must know what it is allowed to do BEFORE it touches the
+ * live library, and it must find out without putting a macOS consent dialog on
+ * screen. This module is the single place that answers that question, so the
+ * read gate, the write gate, `things doctor`, and the `things setup` ceremony
+ * all quote the same verdict.
+ *
+ * Read capability is GROUND TRUTH per invocation, never a stored flag. Nothing
+ * here is memoized across calls and nothing is persisted except the one marker
+ * that records a live-instance fact (./session-grant.ts). The whole preflight
+ * is a single `open(2)` in the common case.
+ *
+ * The paths, in the order they are consulted:
+ *
+ *  1. an explicit database path — outside the doctrine entirely (Article VI);
+ *  2. the helpers — when the reader is serving this process's reads, the READ
+ *     ITSELF is the check. The reader resolves its security-scoped bookmark on
+ *     every verb and answers `not-granted` / `not-found` as typed errors, so
+ *     there is nothing to pre-probe and no hello round-trip is added here. When
+ *     the helpers are expected but cannot serve, the read FAILS LOUDLY — a
+ *     silent fall-through to direct would move consent back onto the terminal,
+ *     which is the exact churn the helpers exist to end;
+ *  3. Full Disk Access — one read-open of the user TCC database. FDA-class
+ *     files never raise a dialog: the open either works or fails with a silent
+ *     EPERM;
+ *  4. a witnessed session app-data grant — see ./session-grant.ts;
+ *  5. otherwise: refuse, naming both setup ceremonies.
+ *
+ * Step 2 asks nothing of this host's grants. Since helpers 1.3.0 the reader's
+ * socket and token live in `<state>/reader` — launchd owns the socket, install
+ * mints the token, and both are ordinary files this user owns — so "is the
+ * reader serving?" is answerable identically from every host app, with no
+ * consent class in play. (Before 1.3.0 they sat in the reader's App Sandbox
+ * container and that question was itself a cross-app container access.)
+ *
+ * The Things group container is NEVER opened as a probe (Article I corollary):
+ * the open is itself what raises the app-data consent, so "try it and see" is
+ * forbidden — except inside `things setup`, which provokes it deliberately.
+ *
+ * On the direct WRITE probe — why TCC introspection and not the AppleEvents
+ * API. The doctrine names `AEDeterminePermissionToAutomateTarget(askUserIfNeeded:
+ * false)` as the direct-path Automation probe, which is exactly what the deputy
+ * calls (deputy/src/tcc.swift). From a JXA/ObjC host that call is NOT reachable:
+ * JavaScriptCore's bridge cannot marshal an `AEDesc` struct. MEASURED 2026-08-24
+ * on macOS 24.6 — `AECreateDesc` fills an untyped `Ref()`, but passing that Ref
+ * to any function taking `^{AEDesc=…}` throws "Ref has incompatible type", and
+ * the one spelling the bridge accepts (`ref[0]`, a dereferenced copy) arrives
+ * zeroed: `AEGetDescDataSize` reports 0 bytes for a 36-byte bundle id, and every
+ * target then answers -50 paramErr. A probe that returns the same wrong answer
+ * for every input is worse than no probe, so it is not shipped. Reading the
+ * Automation row out of TCC.db is the other introspection the Article I
+ * corollary names, it is exactly as prompt-free, and it costs nothing extra:
+ * direct mode's floor is FDA anyway, so a process that can act at all can
+ * already read that file. Where the row cannot be read the verdict is an honest
+ * "unknown", which the write gate refuses on rather than resolving with a dialog.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { loadConfig } from "./config.js";
+import { deputyRouting, deputyRoutesDb, helpersExpected } from "./deputy/routing.js";
+import { fdaGranted, hostApp, hostDisplayName, resetHostAccessForTests, tccDbPath, } from "./host-access.js";
+import { sessionGrantValid } from "./session-grant.js";
+export { fdaGranted, hostApp, hostDisplayName, tccDbPath, } from "./host-access.js";
+/** The Things application's bundle identifier — the Automation grant's target. */
+export const THINGS_BUNDLE_ID = "com.culturedcode.ThingsMac";
+/** True when this verdict permits opening the live container. */
+export function readAllowed(capability) {
+    return capability.mode !== "none" && capability.mode !== "helpers-unavailable";
+}
+/** True when this verdict permits driving the Things window. */
+export function uiAllowed(capability) {
+    return capability.mode === "helpers" || capability.mode === "direct-escape";
+}
+/** True when app automation may be dispatched. */
+export function writeAllowed(capability) {
+    return capability.mode === "deputy" || capability.mode === "direct-granted";
+}
+// ── The prompt-free probes ───────────────────────────────────────────────────
+/**
+ * One Automation row from TCC.db: the `auth_value` macOS records for `client`
+ * driving `target`, or null when there is no row (never asked) or the file is
+ * unreadable (no FDA). Read-only, prompt-free, and defensive — the schema is
+ * Apple's private business, so ANY failure degrades to null rather than
+ * throwing into a caller that asked a yes/no question.
+ */
+function automationAuthValueDefault(env, client, target) {
+    let db;
+    try {
+        db = new DatabaseSync(tccDbPath(env), { readOnly: true });
+        const row = db
+            .prepare("SELECT auth_value FROM access WHERE service = 'kTCCServiceAppleEvents' " +
+            "AND client = ? AND indirect_object_identifier = ? LIMIT 1")
+            .get(client, target);
+        const value = row?.auth_value;
+        return typeof value === "number" ? value : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // A close failure cannot change the answer we already have.
+        }
+    }
+}
+// ── Read capability (Article I + II) ─────────────────────────────────────────
+/**
+ * Errnos that mean a plain "no" rather than something worth telling the user
+ * about. EPERM is the FDA denial proper; EACCES is its sandboxed cousin; ENOENT
+ * simply means this account has no TCC database yet. Anything else is an
+ * anomaly and gets named, so a genuinely odd failure is never silently folded
+ * into "you lack permission".
+ */
+const ORDINARY_DENIALS = new Set(["EPERM", "EACCES", "ENOENT"]);
+/** The ways a machine can earn read capability, phrased for a human. */
+function readRemediation(hostName) {
+    return [
+        "run `things helpers setup` — reads then flow through a helper that holds its own durable grant",
+        `or grant Full Disk Access to ${hostName} in System Settings ▸ Privacy & Security ▸ Full Disk Access`,
+        "or run `things setup`, which walks through both",
+    ];
+}
+/**
+ * Can this process read the live Things library, and on whose authority?
+ *
+ * Stateless: every call re-derives the verdict, because a grant can appear or
+ * vanish between one invocation and the next and a cached "yes" would be a
+ * stored onboarding flag by another name. The common case costs one `open(2)`.
+ */
+export function readCapability(options = {}, deps = {}) {
+    const env = deps.env ?? process.env;
+    const host = hostApp(deps);
+    // Article VI — a path the caller already owns gets plain file semantics.
+    if (options.dbPath !== undefined || (env["THINGS_DB"] ?? "") !== "") {
+        return {
+            mode: "explicit-db",
+            detail: "an explicit database path was supplied — plain file semantics apply",
+            remediation: [],
+            host,
+        };
+    }
+    // The helpers path. Reads that ride the reader are not pre-checked here: the
+    // reader resolves its bookmark on every verb, so the read IS the check and a
+    // probe would only add latency and a second answer to disagree with.
+    const serving = (deps.helpersServing ?? (() => deputyRoutesDb(options, env)))();
+    if (serving) {
+        return {
+            mode: "helpers",
+            detail: "database reads are served by the sandboxed reader",
+            remediation: [],
+            host,
+        };
+    }
+    // No silent fall-through: a machine that asked for the helpers and cannot
+    // have them is refused, not quietly downgraded onto the terminal's own grants.
+    // Nothing gates this question any more — the rendezvous is ours, so whether
+    // the helpers are expected and whether they are serving are both answerable
+    // from every host app alike.
+    const expected = (deps.helpersExpected ?? (() => helpersExpected(env)))();
+    if (expected) {
+        const why = (deps.helpersReason ?? (() => null))();
+        return {
+            mode: "helpers-unavailable",
+            detail: `the helpers are enabled on this machine but are not serving reads${why !== null ? ` (${why})` : ""}`,
+            remediation: [
+                "run `things helpers setup` to finish onboarding them",
+                "or `things helpers status` to see which half is unhealthy",
+                "or `things --no-helpers …` to run this one invocation directly",
+            ],
+            host,
+        };
+    }
+    const fda = fdaGranted(deps);
+    if (fda.granted) {
+        return {
+            mode: "direct-fda",
+            detail: `Full Disk Access is held by ${hostDisplayName(deps)}${host.bundleId !== null ? ` (${host.bundleId})` : ""}`,
+            remediation: [],
+            host,
+        };
+    }
+    // The sub-FDA tier: a grant a ceremony witnessed, still live for this very
+    // app instance. Only consulted when FDA has already said no.
+    const session = sessionGrantValid(host.bundleId, deps);
+    if (session.valid) {
+        return {
+            mode: "session-grant",
+            detail: `${hostDisplayName(deps)} was granted access to the Things data folder for as long as it stays open`,
+            remediation: [],
+            host,
+        };
+    }
+    return {
+        mode: "none",
+        detail: `${hostDisplayName(deps)} cannot open the Things data folder — ${session.reason}` +
+            (fda.code !== null && !ORDINARY_DENIALS.has(fda.code)
+                ? ` (the access check ended in ${fda.code})`
+                : ""),
+        remediation: readRemediation(hostDisplayName(deps)),
+        host,
+    };
+}
+/** Thrown when a read is refused for want of capability (Article II). */
+export class ReadCapabilityError extends Error {
+    remediation;
+    capability;
+    constructor(capability) {
+        super(`the Things database cannot be read: ${capability.detail}. ` +
+            `${capability.remediation.join("; ")}.`);
+        this.name = "ReadCapabilityError";
+        this.remediation = capability.remediation;
+        this.capability = capability;
+    }
+}
+// ── Write capability (Article I + II) ────────────────────────────────────────
+/**
+ * macOS `auth_value` for an Automation record. 0 is a refusal; 2 (allowed) and
+ * 3 both mean the event will be delivered.
+ */
+function classifyAuthValue(value) {
+    if (value === null)
+        return "unknown";
+    if (value === 0)
+        return "denied";
+    if (value >= 2)
+        return "granted";
+    return "unknown";
+}
+/**
+ * May this process drive Things over Apple Events, and on whose authority?
+ *
+ * The deputy wins when it is onboarded (its own handshake reports the grant it
+ * holds). Otherwise the host app's own Automation record is read out of TCC —
+ * granted, denied, or, when there is no record at all, `direct-unknown`. That
+ * last state is deliberately NOT resolved here: resolving it means sending a
+ * real Apple Event, which is what raises the dialog, and Article I reserves
+ * that for `things setup`.
+ */
+export function writeCapability(deps = {}) {
+    const env = deps.env ?? process.env;
+    const host = hostApp(deps);
+    const deputyThings = (deps.deputyAutomation ?? (() => deputyRouting(env).hello?.automation?.things))();
+    if (deputyThings === "granted") {
+        return {
+            mode: "deputy",
+            detail: "the deputy is onboarded and holds app control for Things",
+            remediation: [],
+            host,
+        };
+    }
+    if (host.bundleId === null) {
+        return {
+            mode: "direct-unknown",
+            detail: "this process does not descend from an application bundle, so macOS has no identity " +
+                "to record app control against",
+            remediation: [
+                "run `things helpers setup` — app control then attaches to a helper that always has an identity",
+            ],
+            host,
+        };
+    }
+    const authValue = (deps.automationAuthValue ??
+        ((client, target) => automationAuthValueDefault(env, client, target)))(host.bundleId, THINGS_BUNDLE_ID);
+    const hostName = hostDisplayName(deps);
+    switch (classifyAuthValue(authValue)) {
+        case "granted":
+            return {
+                mode: "direct-granted",
+                detail: `${hostName} (${host.bundleId}) holds app control for Things`,
+                remediation: [],
+                host,
+            };
+        case "denied":
+            return {
+                mode: "direct-denied",
+                detail: `macOS records a refusal of app control for ${hostName} (${host.bundleId}) — it will not ask again`,
+                remediation: [
+                    `turn on Things3 for ${hostName} under System Settings ▸ Privacy & Security ▸ Automation`,
+                    `or re-arm the request with \`tccutil reset AppleEvents ${host.bundleId}\`, then run \`things setup\``,
+                ],
+                host,
+            };
+        default:
+            return {
+                mode: "direct-unknown",
+                detail: `macOS has no app-control record for ${hostName} (${host.bundleId}) yet`,
+                remediation: [
+                    "run `things setup` — it asks for app control once, while you are at the machine",
+                    "or run `things helpers setup` to attach the grant to a helper instead",
+                ],
+                host,
+            };
+    }
+}
+/** Thrown when app automation is refused for want of capability (Article II). */
+export class WriteCapabilityError extends Error {
+    remediation;
+    capability;
+    constructor(capability) {
+        super(`Things cannot be driven: ${capability.detail}. ${capability.remediation.join("; ")}.`);
+        this.name = "WriteCapabilityError";
+        this.remediation = capability.remediation;
+        this.capability = capability;
+    }
+}
+// ── UI capability (Article IV) ───────────────────────────────────────────────
+/**
+ * The LAB's escape hatch, and deliberately not consumer surface. The VM lab and
+ * the guest e2e bundle drive the UI vector DIRECT — the in-guest Accessibility
+ * grant is held by the runner's own processes (the AXVM1 layer), there is no
+ * helper bundle in a disposable clone, and there is nobody to answer a dialog
+ * either. Setting this to `1` restores direct UI-vector availability for that
+ * one situation. It is documented in docs/lab/harness.md and exported by the
+ * lab's guest environment; nothing consumer-facing mentions it, and it does not
+ * bypass `ui.enabled` — a lab clone still sets that key explicitly.
+ */
+export const UI_DIRECT_ESCAPE_ENV = "THINGS_API_UI_DIRECT";
+/** The command that gathers the GUI-driving tier, named in every UI refusal. */
+const GUI_SETUP_COMMAND = "run `things helpers setup --gui` to grant GUI-driving to the helpers";
+function deputyGuiStandingDefault(env) {
+    const hello = deputyRouting(env).hello;
+    if (hello === undefined || hello === null)
+        return null;
+    return { axTrusted: hello.axTrusted, systemEvents: hello.automation?.systemEvents };
+}
+/**
+ * May this process drive the Things WINDOW, and on whose authority?
+ *
+ * Article IV admits exactly one provenance: the helper pair. Accessibility on a
+ * general-purpose host app (a terminal, an agent harness, an MCP host) has a
+ * blast radius far beyond Things, churns with every host update, and has no
+ * sane story at all over ssh — so direct AX is unsupported, and a refusal here
+ * names the config knob and `things helpers setup --gui` rather than raising an
+ * Accessibility prompt against whatever happens to be running us.
+ *
+ * Every answer is prompt-free: the config key is a file read, and the deputy's
+ * `hello` carries `AXIsProcessTrusted()` plus its own `AEDeterminePermission`
+ * verdict for System Events.
+ */
+export function uiCapability(deps = {}) {
+    const env = deps.env ?? process.env;
+    const host = hostApp(deps);
+    const enabled = (deps.uiEnabled ?? (() => loadConfig(env).ui.enabled))();
+    if (!enabled) {
+        return {
+            mode: "config-disabled",
+            detail: "GUI-driving is switched off on this machine (`ui-enabled` is false)",
+            remediation: [
+                "run `things config set ui-enabled true` to opt in",
+                `then ${GUI_SETUP_COMMAND}`,
+            ],
+            host,
+        };
+    }
+    if ((env[UI_DIRECT_ESCAPE_ENV] ?? "") === "1") {
+        return {
+            mode: "direct-escape",
+            detail: `${UI_DIRECT_ESCAPE_ENV}=1 — GUI-driving runs directly under this process (lab escape)`,
+            remediation: [],
+            host,
+        };
+    }
+    const standing = (deps.deputyGuiStanding ?? (() => deputyGuiStandingDefault(env)))();
+    if (standing === null) {
+        return {
+            mode: "helpers-missing",
+            detail: "GUI-driving is granted only to the helpers, and no helper is answering on this machine",
+            remediation: [GUI_SETUP_COMMAND, "or `things helpers status` to see which half is unhealthy"],
+            host,
+        };
+    }
+    const missing = [];
+    if (standing.axTrusted !== true) {
+        missing.push(standing.axTrusted === undefined
+            ? "Accessibility (these helpers predate the permission handshake — rebuild)"
+            : "Accessibility");
+    }
+    if (standing.systemEvents !== "granted") {
+        missing.push(`automation → System Events (${standing.systemEvents ?? "unknown"})`);
+    }
+    if (missing.length === 0) {
+        return {
+            mode: "helpers",
+            detail: "the helpers hold Accessibility and app control for System Events",
+            remediation: [],
+            host,
+        };
+    }
+    return {
+        mode: "tier-incomplete",
+        detail: `the helpers are onboarded but the GUI-driving tier is incomplete — missing ${missing.join("; ")}`,
+        remediation: [GUI_SETUP_COMMAND],
+        host,
+    };
+}
+/** Thrown when GUI-driving is refused for want of capability (Article IV). */
+export class UiCapabilityError extends Error {
+    remediation;
+    capability;
+    constructor(capability) {
+        super(`the Things window cannot be driven: ${capability.detail}. ${capability.remediation.join("; ")}.`);
+        this.name = "UiCapabilityError";
+        this.remediation = capability.remediation;
+        this.capability = capability;
+    }
+}
+/** Test seam: forget the one memo this module keeps (the host's display name). */
+export function resetCapabilityForTests() {
+    resetHostAccessForTests();
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EACL,UAAU,EAGV,OAAO,EACP,eAAe,EACf,uBAAuB,EACvB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EACL,UAAU,EAGV,OAAO,EACP,eAAe,EACf,SAAS,GACV,MAAM,kBAAkB,CAAC;AAE1B,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AA0D7D,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,UAA0B;IACpD,OAAO,UAAU,CAAC,IAAI,KAAK,MAAM,IAAI,UAAU,CAAC,IAAI,KAAK,qBAAqB,CAAC;AACjF,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,SAAS,CAAC,UAAwB;IAChD,OAAO,UAAU,CAAC,IAAI,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,KAAK,eAAe,CAAC;AAC9E,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,YAAY,CAAC,UAA2B;IACtD,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,KAAK,gBAAgB,CAAC;AAC9E,CAAC;AAmCD,gFAAgF;AAEhF;;;;;;GAMG;AACH,SAAS,0BAA0B,CACjC,GAAsB,EACtB,MAAc,EACd,MAAc;IAEd,IAAI,EAA4B,CAAC;IACjC,IAAI,CAAC;QACH,EAAE,GAAG,IAAI,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,EAAE;aACX,OAAO,CACN,yEAAyE;YACvE,2DAA2D,CAC9D;aACA,GAAG,CAAC,MAAM,EAAE,MAAM,CAAwC,CAAC;QAC9D,MAAM,KAAK,GAAG,GAAG,EAAE,UAAU,CAAC;QAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,EAAE,EAAE,KAAK,EAAE,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;IACH,CAAC;AACH,CAAC;AAED,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEhE,wEAAwE;AACxE,SAAS,eAAe,CAAC,QAAgB;IACvC,OAAO;QACL,gGAAgG;QAChG,gCAAgC,QAAQ,6DAA6D;QACrG,iDAAiD;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,UAA+B,EAAE,EACjC,OAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,yEAAyE;IACzE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC;QACpE,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,qEAAqE;YAC7E,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,6EAA6E;IAC7E,6EAA6E;IAC7E,qEAAqE;IACrE,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,mDAAmD;YAC3D,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,+EAA+E;IAC/E,4EAA4E;IAC5E,4EAA4E;IAC5E,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO;YACL,IAAI,EAAE,qBAAqB;YAC3B,MAAM,EAAE,oEACN,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,EAC/B,EAAE;YACF,WAAW,EAAE;gBACX,sDAAsD;gBACtD,2DAA2D;gBAC3D,gEAAgE;aACjE;YACD,IAAI;SACL,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,+BAA+B,eAAe,CAAC,IAAI,CAAC,GAC1D,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EACnD,EAAE;YACF,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,2EAA2E;IAC3E,6DAA6D;IAC7D,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO;YACL,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,4EAA4E;YAC5G,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM,EACJ,GAAG,eAAe,CAAC,IAAI,CAAC,yCAAyC,OAAO,CAAC,MAAM,EAAE;YACjF,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;gBACnD,CAAC,CAAC,+BAA+B,GAAG,CAAC,IAAI,GAAG;gBAC5C,CAAC,CAAC,EAAE,CAAC;QACT,WAAW,EAAE,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI;KACL,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,WAAW,CAAW;IACtB,UAAU,CAAiB;IACpC,YAAY,UAA0B;QACpC,KAAK,CACH,uCAAuC,UAAU,CAAC,MAAM,IAAI;YAC1D,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1C,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,gFAAgF;AAEhF;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAoB;IAC7C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAAuB,EAAE;IACvD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,YAAY,GAAG,CACnB,IAAI,CAAC,gBAAgB,IAAI,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAC9E,EAAE,CAAC;IACJ,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,0DAA0D;YAClE,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,gBAAgB;YACtB,MAAM,EACJ,qFAAqF;gBACrF,+BAA+B;YACjC,WAAW,EAAE;gBACX,gGAAgG;aACjG;YACD,IAAI;SACL,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,CAChB,IAAI,CAAC,mBAAmB;QACxB,CAAC,CAAC,MAAc,EAAE,MAAc,EAAE,EAAE,CAAC,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CACtF,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,QAAQ,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,KAAK,SAAS;YACZ,OAAO;gBACL,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,GAAG,QAAQ,KAAK,IAAI,CAAC,QAAQ,gCAAgC;gBACrE,WAAW,EAAE,EAAE;gBACf,IAAI;aACL,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,8CAA8C,QAAQ,KAAK,IAAI,CAAC,QAAQ,2BAA2B;gBAC3G,WAAW,EAAE;oBACX,uBAAuB,QAAQ,0DAA0D;oBACzF,0DAA0D,IAAI,CAAC,QAAQ,+BAA+B;iBACvG;gBACD,IAAI;aACL,CAAC;QACJ;YACE,OAAO;gBACL,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,uCAAuC,QAAQ,KAAK,IAAI,CAAC,QAAQ,OAAO;gBAChF,WAAW,EAAE;oBACX,iFAAiF;oBACjF,uEAAuE;iBACxE;gBACD,IAAI;aACL,CAAC;IACN,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,WAAW,CAAW;IACtB,UAAU,CAAkB;IACrC,YAAY,UAA2B;QACrC,KAAK,CAAC,4BAA4B,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9F,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D,gFAAgF;AAChF,MAAM,iBAAiB,GAAG,sEAAsE,CAAC;AAEjG,SAAS,wBAAwB,CAC/B,GAAsB;IAEtB,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IACvC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvD,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,KAAK,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,OAAuB,EAAE;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;IACzE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,IAAI,EAAE,iBAAiB;YACvB,MAAM,EAAE,qEAAqE;YAC7E,WAAW,EAAE;gBACX,mDAAmD;gBACnD,QAAQ,iBAAiB,EAAE;aAC5B;YACD,IAAI;SACL,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC;QAC9C,OAAO;YACL,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,GAAG,oBAAoB,gEAAgE;YAC/F,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,GAAG,EAAE,CAAC,wBAAwB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,iBAAiB;YACvB,MAAM,EACJ,wFAAwF;YAC1F,WAAW,EAAE,CAAC,iBAAiB,EAAE,2DAA2D,CAAC;YAC7F,IAAI;SACL,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CACV,QAAQ,CAAC,SAAS,KAAK,SAAS;YAC9B,CAAC,CAAC,0EAA0E;YAC5E,CAAC,CAAC,eAAe,CACpB,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,+BAA+B,QAAQ,CAAC,YAAY,IAAI,SAAS,GAAG,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,kEAAkE;YAC1E,WAAW,EAAE,EAAE;YACf,IAAI;SACL,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,8EAA8E,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC1G,WAAW,EAAE,CAAC,iBAAiB,CAAC;QAChC,IAAI;KACL,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,WAAW,CAAW;IACtB,UAAU,CAAe;IAClC,YAAY,UAAwB;QAClC,KAAK,CACH,uCAAuC,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAClG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,UAAU,uBAAuB;IACrC,uBAAuB,EAAE,CAAC;AAC5B,CAAC"}