agentix-cli 0.27.0 → 0.29.0

package/README.md

@@ -1,157 +1,132 @@
-
-
 <div align="center">
 
-<img src="docs/public/logo.png" alt="AgentX" width="96" />
+<img src="docs/public/agentx-symbol.png" alt="AgentX" width="96" />
 
 # AgentX
 
-**A self-hosted mesh of AI agents for your team — A2A-native, auditable, on your machines.**
+**Put an AI teammate on the tools your team already uses.**
+
+<a href="https://www.producthunt.com/products/agentx-4?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-agentx-5" target="_blank" rel="noopener noreferrer"><img alt="AgentX - AI teammates in the tools your team already uses | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1258056&amp;theme=light&amp;t=1790073592268" /></a>
 
 [![npm](https://img.shields.io/npm/v/agentix-cli?label=npm%20%C2%B7%20agentix-cli)](https://www.npmjs.com/package/agentix-cli)
 [![CI](https://github.com/anis-marrouchi/agentx/actions/workflows/ci.yml/badge.svg)](https://github.com/anis-marrouchi/agentx/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-22.x-brightgreen)](package.json)
-[![A2A](https://img.shields.io/badge/A2A-agent--to--agent%20protocol-blueviolet)](https://github.com/a2aproject/A2A)
 
-[Docs](https://agentx-docs.pages.dev) · [Install](#install) · [Journey (13 chapters)](#docs) · [How it compares](#how-it-compares)
+[See the demo](#see-it-without-an-account) · [Install](#install) · [Read the guide](docs/index.md)
+
+</div>
 
-<!-- HERO: replace with the "One message. Three machines." GIF once filmed -->
-<img src="docs/public/screenshots/mesh.png" alt="Live mesh graph — agents on different machines delegating over A2A" width="820" />
+AgentX routes messages and scheduled jobs to AI agents you host. Connect Telegram, WhatsApp, GitLab, GitHub, or a webhook. Give each agent a clear job. Watch the result in a browser dashboard.
 
-*Agents on different machines discover each other, delegate work, and report back — every dispatch recorded in a replayable ledger.*
+## Current state: usable, experimental, not yet stable
 
-</div>
+AgentX works and can be used today, but it is still an **experimental project, not a stable release**. There is plenty to polish and fix, especially the **Settings experience and configuration flows**. Expect rough edges and changes as people try it in real environments.
 
----
+The current source release is **0.28.0**. Our priority is to learn from actual use: what works, what breaks, and what is confusing to set up or operate.
 
-Most agent tools give you **one agent in one chat app**. AgentX runs a **network**: agents on your laptop, your VPS, and your teammates' machines pair with one link, talk over the open [A2A protocol](https://github.com/a2aproject/A2A) (Linux Foundation), and answer on the channels your team already uses — Telegram, WhatsApp, GitLab, GitHub.
+**Still missing: role-based access control (RBAC) at both mesh and agent levels.** We want to define who can access shared nodes and agents, delegate work, and perform particular actions. This would open up more possibilities for shared teams and multi-user deployments. Existing mesh authentication and tool permissions do not provide this complete role model; RBAC is planned work, not an available feature.
 
-```
-You (Telegram): "@cx CI is red on gitlab — fix it and ship a patch"
-  cx (laptop)   → resolves @builder via the mesh directory
-  builder (vps) → fixes, opens the MR, pipeline green
-  cx            → replies in your Telegram thread with the MR link
-```
+[Try the demo](#see-it-without-an-account), [check the requirements](docs/requirements.md), or [help us test](#help-test-and-improve-agentx).
 
-## Try it in 60 seconds — no keys, no accounts
+![AgentX Monitor showing tasks that need your attention in the current dashboard](docs/public/screenshots/monitor-only-you.png)
 
-```bash
-npx agentix-cli demo
+*The Monitor dashboard in the isolated demo: review tasks that need you, with in-page agent chat. All displayed tasks are fictional.*
+
+## See it without an account
+
+From a built source checkout with Node.js 22.x, run:
+
+```sh
+node dist/cli.js demo
 ```
 
-Boots **three real daemons on your machine**, pairs them into a real A2A mesh, and plays a cross-node scenario — delegation, mesh hop, fix, report-back — live in the dashboards. Only the model is scripted; the daemons, mesh protocol, and ledger are the real thing.
+The demo starts three local AgentX daemons and sends a task between them. Routing, network calls, and the event record are real. Model responses are scripted, so the demo makes no billable model calls. The terminal prints the dashboard addresses. [What to expect](docs/see-it-first.md).
+
+## What it does
+
+- **Answers where your team works.** Connect a channel and assign its messages to an agent.
+- **Runs scheduled work.** Ask an agent for a daily report or another recurring task.
+- **Shows what happened.** Live shows current work; Activity records completed runs; Monitor shows reviewed work that needs a person and work agents can handle.
+- **Offers several ways to interact.** Use [in-page chat](docs/dashboard/chat.md), the [OpenCode-backed TUI](docs/dashboard/tui.md), or the desktop assistant for voice and computer use.
+- **Grows across machines.** Start with one host, then pair another when a job needs its tools or files.
+
+## Describe an automation, get an automation
+
+The Workflows editor has a chat control. Describe the timing, source, and destination in ordinary language. An authoring agent can propose a workflow and show an **Apply to canvas** action. Read the proposed steps before applying them: this replaces the current graph. Real authoring needs a working model. The demo includes a fixed example for **Build the demo report workflow**. [Walk through it](docs/automations/describe-it.md).
+
+![The demo workflow assistant proposing a report](docs/public/screenshots/editor-chat-reply.png)
 
 ## Install
 
-```bash
-npm install -g agentix-cli   # the npm name; the command is `agentx`
-agentx setup                 # web wizard: agents, channels, keys
+A technical teammate needs a terminal for installation, model setup, and starting the services. The web wizard handles the rest of the initial setup; daily inspection is in the browser. AgentX requires **Node.js 22.x**.
+
+```sh
+git clone https://github.com/anis-marrouchi/agentx.git
+cd agentx
+git checkout main
+cp .env.example .env
+docker compose up --build -d
 ```
 
-Or one line — installs the CLI and opens the wizard:
+Open **http://127.0.0.1:4202/setup**. Compose builds this checkout and starts both services; its default image uses an API model rather than a preinstalled model CLI.
+
+Without Docker, install Node 22.x and pnpm 10, then build and open the wizard:
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/anis-marrouchi/agentx/master/install.sh | bash
+```sh
+pnpm install
+pnpm build
+node dist/cli.js setup
 ```
 
-Docker: `git clone https://github.com/anis-marrouchi/agentx.git && cd agentx && docker compose up -d`
-
-Then open the dashboard at **http://127.0.0.1:4202**. Pair a second machine with `agentx connect mesh` — it prints an `agentx-mesh://join/…` link; run it on the other node and you have a mesh. Full guide: [install docs](docs/install.md).
-
-## Why a mesh
-
-- **One agent can't be everywhere.** Your GitLab runner box, your WhatsApp-paired Mac, and your GPU server each run the agents that belong there; the mesh routes `@mentions` to whichever node owns the agent — cross-machine, cross-channel.
-- **A2A-native, not proprietary.** Nodes exchange agent cards and tasks over the Agent2Agent protocol (150+ orgs behind the standard). Your mesh isn't locked to AgentX — anything that speaks A2A can join the conversation.
-- **Auditable by construction.** Every dispatch decision — channel message, mesh hop, cron fire, workflow step — lands in an append-only intent ledger. `agentx ledger replay` reproduces the decision deterministically when you need to know *why* an agent did something.
-- **Secure by default.** The daemon binds to loopback; mesh endpoints verify bearer tokens; agent-to-agent chains are depth-capped; credentials live in env vars and never enter prompts. Threat model: [SECURITY.md](SECURITY.md).
-
-## What you get
-
-- **Channels** — Telegram, WhatsApp (QR pair in the browser), GitLab, GitHub, generic webhooks. Agents reply where they were asked, or push anywhere.
-- **Mesh federation** — pair nodes over Tailscale/VPN with one link; manage any peer's config from one dashboard; GitLab mentions route across nodes with peer-owned tokens.
-- **Agents are folders, not code** — persona, knowledge, and tools in plain Markdown (`CLAUDE.md`, skills, references). Bring Claude Code, Codex CLI, OpenCode with any configured provider, Anthropic/OpenAI APIs, or an OpenAI-compatible endpoint.
-- **Operator surface** — browser setup wizard + 11-page admin dashboard: live activity, Kanban boards synced two-way with GitLab/GitHub issues, token-cost accounting, scoped API tokens.
-- **Scheduled work** — plain-English cron: `agentx schedule "every Monday at 9am" --agent sales`, with failure alerts and auto-disable.
-- **Workflows & procedures** — declarative YAML state machines with a visual editor for the flows that must survive restarts; versioned SOPs agents cite at runtime; deterministic no-LLM handlers for canonical answers.
-- **Compounding memory** — conversations absorb into a shared wiki (typed articles, `[[wikilinks]]`, versioned) that every agent queries — also exposed to Cursor/Claude Code via MCP (`agentx serve --stdio`).
-- **Wearable agents** — `agentx attach <agent>` makes the Claude Code session you already have open answer as that agent, so a Telegram or GitLab message reaches you where you're already working instead of spawning a subprocess. Unclaimed messages fall back to a spawned agent, so it's a preference, never a dependency.
-- **Governance** — intent ledger + replay, PM gating, typed capabilities, delegation-depth caps, destructive-action guardrails that hold even under `bypassPermissions`.
-
-## How it compares
-
-| | **AgentX** | OpenClaw | Hermes Agent | Claude Code |
-|---|---|---|---|---|
-| Agents per install | a mesh of many, across machines | one | one | one session |
-| Cross-machine delegation | ✅ A2A protocol | ❌ | ❌ | ❌ (in-process subagents) |
-| Open interop standard | ✅ A2A (Linux Foundation) | ❌ | ❌ | MCP for tools |
-| Users / operators | team, multi-operator | single-user | single-user | single account |
-| Audit ledger + replay | ✅ append-only, deterministic replay | ❌ | ❌ | ❌ |
-| GitLab-native (boards, MRs, cross-node mentions) | ✅ | ❌ | ❌ | ❌ |
-| Chat channels | 6 + webhooks + plugins | ~24 | multiple | terminal |
-| LLM providers | Claude Code, Codex CLI, OpenCode, Anthropic, OpenAI-compatible | Claude-first | model-agnostic | Claude |
-| Self-hosted, no telemetry | ✅ | ✅ | ✅ | n/a |
-
-*(As of July 2026 — corrections welcome via PR.)*
-
-> **Running solo, just for yourself?** [OpenClaw](https://github.com/openclaw/openclaw) is built for exactly that and has a lighter install. If you outgrow it, we import your config: [Migrate from OpenClaw](docs/migration/from-openclaw.md).
-
-## Use cases
-
-- **Solo founder ops** — run support triage, invoices, and scheduled reports from Telegram ([journey ch. 1–2](docs/journey/01-telegram-qa-bot.md))
-- **Dev team** — GitLab MR review agent + WhatsApp escalation + nightly maintenance across two machines ([mesh federation](docs/journey/08-mesh-federation.md))
-- **Agency / B2B** — one node per client, scoped tokens, per-agent cost accounting ([tokens](docs/reference/tokens.md), [usage](docs/playbooks/tier2-billing.md))
-- **Public-facing service** — citizen/customer intake bot with an auditable trail of every decision ([BPM grant application](docs/journey/12-bpm-grant-application.md))
-
-## Screenshots
-
-| Live activity | Mesh | Boards |
-|---|---|---|
-| ![Live](docs/public/screenshots/live.png) | ![Mesh](docs/public/screenshots/mesh.png) | ![Boards](docs/public/screenshots/boards.png) |
-
-| Admin | Intent graph | Setup wizard |
-|---|---|---|
-| ![Admin](docs/public/screenshots/admin.png) | ![Graph](docs/public/screenshots/graph.png) | ![Setup](docs/public/screenshots/setup.png) |
-
-## Architecture
-
-```mermaid
-graph LR
-  T[Telegram] --> R(Router)
-  W[WhatsApp] --> R
-  G[GitLab] --> R
-  GH[GitHub] --> R
-  C[Cron] --> R
-  H[Webhook] --> R
-  M[Mesh peer · A2A] --> R
-  PL[Plugin channels] --> R
-  R --> LDG[(Intent Ledger<br/>append-only)]
-  LDG --> CTX[Context Engine]
-  CTX --> AG[Agent workspace]
-    AG --> P1[Claude Code]
-    AG --> P2[Codex CLI / OpenCode]
-    AG --> P3[Anthropic / OpenAI-compatible API]
-  AG -.-> MEM[(Wiki + Graph + Memory)]
-  AG -.-> WF[Workflows + Procedures]
-  AG -.-> R
+On a source install, the wizard serves the dashboard and **the daemon is a separate process**. Start it in another terminal, or use the wizard's **Start daemon now** button:
+
+```sh
+node dist/cli.js daemon start --detach
+node dist/cli.js daemon status
 ```
 
-Each agent = a workspace directory (`CLAUDE.md`, `.claude/skills/`, hooks, MCP servers). AgentX decides when and where agents run, records every dispatch in the ledger, and lets plugins extend channels and the event bus. It's the ops layer *above* agent frameworks — if you want a DSL for a single agent, AutoGen/LangGraph/CrewAI are that; AgentX is which agent runs, on which channel, on which machine, at what cost, replayably.
+The npm package is `agentix-cli`; the installed executable is `agentx`. **Published version 0.27.0 has an installation error:** its postinstall script is missing from the package. Version 0.28.0 includes the fix; use 0.28.0 or newer, or build from source/Docker. Follow the [installation guide](docs/install.md) for details.
+
+## One machine is enough to start
 
-## Docs
+When an agent needs to work on another machine, pair the nodes with `agentx connect mesh invite` and `agentx connect mesh join <link>`. A connected agent can pass work to another node. For example:
 
-Full documentation: **[agentx-docs.pages.dev](https://agentx-docs.pages.dev)** — including the worked journey from a one-agent Telegram bot to a hardened multi-node mesh:
-[Telegram Q&A bot](docs/journey/01-telegram-qa-bot.md) → [scheduled reports](docs/journey/02-scheduled-reports.md) → [multi-agent groups](docs/journey/03-multi-agent-group.md) → [cross-channel](docs/journey/04-cross-channel.md) → [hooks](docs/journey/05-hooks-webhooks.md) → [shared wiki](docs/journey/06-shared-wiki.md) → [mesh federation](docs/journey/08-mesh-federation.md) → [deterministic services](docs/journey/09-deterministic-services.md) → [MCP server](docs/journey/10-mcp-server.md) → [production hardening](docs/journey/11-production-hardening.md) → [BPM](docs/journey/12-bpm-grant-application.md) → [wearable agents](docs/journey/14-wearable-agent.md)
+```text
+You:     "@cx CI is red on GitLab — find the cause"
+CX:      sends the build investigation to @builder on another node
+Builder: checks the project and reports the result
+CX:      replies in the original thread
+```
 
-Reference: [CLI](docs/reference/cli.md) · [Config schema](docs/reference/config-schema.md) · [Dashboard](docs/reference/dashboard/) · [Tokens](docs/reference/tokens.md) · [Tailscale](docs/reference/tailscale-setup.md)
+The [second-machine guide](docs/jobs/second-machine.md) covers pairing. You do not need mesh for a one-agent setup.
 
-## Community
+## The dashboard
 
-- **[Share your mesh](../../issues/new?template=share_your_mesh.yml)** — real-world setups shape the roadmap
-- [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) · [Changelog](CHANGELOG.md)
+The six top-level tabs are **Live, Operations, Monitor, Activity, Workflows, and Settings**. [Dashboard guide](docs/dashboard/index.md). The dashboard and daemon must both be running for messages to be handled.
+
+## Channels and models
+
+Telegram and WhatsApp have pairing flows. GitLab, GitHub, and generic webhooks can bring in events. **Slack and Discord are not supported as live channel adapters in this build.** [Channel reference](docs/reference/channels.md).
 
-If AgentX is useful to you, a ⭐ genuinely helps others find it.
+Real agents need a configured model. An API provider needs a key; Claude Code, Codex CLI, and OpenCode need their CLI installed and authenticated on the host. Model-provider charges or subscription terms depend on your chosen provider.
 
-## License
+## Help test and improve AgentX
+
+The most valuable contribution right now is **trying AgentX and reporting what happens**. You do not need to write code to help.
+
+1. **Test and report issues.** Try installation, Settings, model setup, chat, the desktop assistant, the TUI, or a task across nodes. Report failures and confusing steps, including what you expected and what actually happened.
+2. **Help with triage and workflow/pipeline management.** Reproduce reports, identify duplicates, clarify priorities, and help follow issues through fixes, CI, and releases.
+3. **Contribute code and documentation.** Fix bugs, improve setup and Settings, clarify instructions, or help design the missing mesh-level and agent-level RBAC. Discuss larger changes in an issue first.
+
+[Report an issue](https://github.com/anis-marrouchi/agentx/issues/new) with your version, operating system, steps to reproduce, and relevant logs or screenshots. Remove secrets and private data before sharing. Report security vulnerabilities through the [security policy](SECURITY.md).
+
+See [Contributing](CONTRIBUTING.md) for testing, issue triage, and development instructions.
+
+## Help and development
+
+- [Start here](docs/index.md) · [Troubleshooting](docs/help/its-not-answering.md) · [CLI reference](docs/reference/cli.md)
+- [Support and supported environments](.github/SUPPORT.md) · [Ask a question](https://github.com/anis-marrouchi/agentx/discussions)
+- [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) · [Changelog](CHANGELOG.md)
 
-MIT.
+AgentX is released under the [MIT License](LICENSE).

package/apps/mac-helper/Sources/AgentXHelper/AXTree.swift

@@ -0,0 +1,159 @@
+import AppKit
+import ApplicationServices
+
+/// Reads the focused application's accessibility tree.
+///
+/// The tree, not a screenshot, is the primary surface. It gives structured,
+/// verifiable elements with real roles and real frames — so a click can be
+/// confirmed to have hit the control that was chosen, and the candidate set
+/// is ENUMERABLE, which is what lets a decision model pick from it rather
+/// than invent coordinates.
+///
+/// Its honest failure mode is apps that expose nothing: icon-only toolbars,
+/// custom-drawn editors, canvas games. For those the tree comes back thin
+/// and the caller should say so rather than guess — screenshots are the
+/// documented fallback, and are deliberately not in this first cut.
+enum AXTree {
+
+    struct Element: Codable {
+        let id: Int
+        let role: String
+        /// Best human-readable name, from whichever attribute has one.
+        let label: String
+        let value: String?
+        let enabled: Bool
+        let x: Double, y: Double, width: Double, height: Double
+        /// Index of the parent in the same flat array; -1 for the root.
+        let parent: Int
+    }
+
+    struct Snapshot: Codable {
+        let app: String
+        let pid: Int32
+        let window: String?
+        let elements: [Element]
+        let truncated: Bool
+        let note: String?
+    }
+
+    /// Accessibility is TCC-gated and there is no way to ask politely from
+    /// a CLI — the prompt only appears for a bundled, signed app. Report it
+    /// clearly instead of returning an empty tree that looks like an app
+    /// with no controls.
+    static func trusted() -> Bool { AXIsProcessTrusted() }
+
+    static func snapshot(maxElements: Int = 400) -> Snapshot {
+        guard let app = NSWorkspace.shared.frontmostApplication else {
+            return Snapshot(app: "unknown", pid: 0, window: nil, elements: [],
+                            truncated: false, note: "no frontmost application")
+        }
+        let axApp = AXUIElementCreateApplication(app.processIdentifier)
+        var elements: [Element] = []
+        var truncated = false
+
+        // The focused window, not the whole app: an app's tree includes
+        // every window it owns, and pointing at a control in a background
+        // window is worse than useless.
+        var windowRef: CFTypeRef?
+        AXUIElementCopyAttributeValue(axApp, kAXFocusedWindowAttribute as CFString, &windowRef)
+        let root = (windowRef as! AXUIElement?) ?? axApp
+        let windowTitle = string(root, kAXTitleAttribute)
+
+        // Traverse everything, but only SPEND the budget on elements worth
+        // choosing between.
+        //
+        // A modern web page is mostly containers: x.com fills 273 of 400
+        // slots with unlabelled AXGroups before reaching its search field,
+        // so a naive cap returns a tree with no inputs in it and the page
+        // looks like it exposes nothing. Skipped nodes still have their
+        // children walked; `parent` points at the nearest KEPT ancestor, so
+        // the hierarchy stays usable for page-scoping.
+        var queue: [(AXUIElement, Int)] = [(root, -1)]
+        while !queue.isEmpty {
+            if elements.count >= maxElements { truncated = true; break }
+            let (node, parent) = queue.removeFirst()
+
+            var keptIndex = parent
+            if let e = describe(node, id: elements.count, parent: parent), worthKeeping(e) {
+                keptIndex = elements.count
+                elements.append(e)
+            }
+            var childrenRef: CFTypeRef?
+            if AXUIElementCopyAttributeValue(node, kAXChildrenAttribute as CFString, &childrenRef) == .success,
+               let children = childrenRef as? [AXUIElement] {
+                for c in children { queue.append((c, keptIndex)) }
+            }
+        }
+
+        return Snapshot(
+            app: app.localizedName ?? "unknown",
+            pid: app.processIdentifier,
+            window: windowTitle,
+            elements: elements,
+            truncated: truncated,
+            note: elements.count < 3
+                ? "this app exposes almost no accessibility information — the tree is not usable here"
+                : nil)
+    }
+
+    /// Containers earn a slot only when they say something.
+    ///
+    /// The web area itself is always kept — page-scoping needs it as an
+    /// anchor even though it carries no label of its own.
+    private static func worthKeeping(_ e: Element) -> Bool {
+        if e.role == "AXWebArea" { return true }
+        let isContainer = e.role == "AXGroup" || e.role == "AXUnknown"
+            || e.role == "AXSplitGroup" || e.role == "AXScrollArea"
+        if !isContainer { return true }
+        // A labelled group is usually a landmark worth naming; "0" and ""
+        // are the DOM showing through.
+        let label = e.label.trimmingCharacters(in: .whitespaces)
+        return label.count > 1 && label != "0"
+    }
+
+    private static func describe(_ node: AXUIElement, id: Int, parent: Int) -> Element? {
+        guard let role = string(node, kAXRoleAttribute) else { return nil }
+
+        // First attribute that actually names the thing. Title is usually
+        // best, but buttons frequently carry only a description, and menu
+        // items only a value.
+        let label = [kAXTitleAttribute, kAXDescriptionAttribute, kAXLabelValueAttribute,
+                     kAXHelpAttribute, kAXPlaceholderValueAttribute]
+            .compactMap { string(node, $0) }
+            .first(where: { !$0.isEmpty }) ?? ""
+
+        var frame = CGRect.zero
+        var posRef: CFTypeRef?, sizeRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(node, kAXPositionAttribute as CFString, &posRef) == .success,
+           AXUIElementCopyAttributeValue(node, kAXSizeAttribute as CFString, &sizeRef) == .success {
+            var p = CGPoint.zero, s = CGSize.zero
+            AXValueGetValue(posRef as! AXValue, .cgPoint, &p)
+            AXValueGetValue(sizeRef as! AXValue, .cgSize, &s)
+            frame = CGRect(origin: p, size: s)
+        }
+
+        var enabledRef: CFTypeRef?
+        AXUIElementCopyAttributeValue(node, kAXEnabledAttribute as CFString, &enabledRef)
+        let enabled = (enabledRef as? Bool) ?? true
+
+        // Invisible and zero-sized nodes cannot be pointed at, and there
+        // are a great many of them — dropping them keeps the candidate set
+        // small enough to hand to a model.
+        if frame.width < 1 || frame.height < 1 { return nil }
+
+        return Element(id: id, role: role, label: label,
+                       value: string(node, kAXValueAttribute),
+                       enabled: enabled,
+                       x: frame.origin.x, y: frame.origin.y,
+                       width: frame.size.width, height: frame.size.height,
+                       parent: parent)
+    }
+
+    private static func string(_ node: AXUIElement, _ attr: String) -> String? {
+        var ref: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(node, attr as CFString, &ref) == .success else { return nil }
+        if let s = ref as? String { return s.trimmingCharacters(in: .whitespacesAndNewlines) }
+        if let n = ref as? NSNumber { return n.stringValue }
+        return nil
+    }
+}

package/apps/mac-helper/Sources/AgentXHelper/Brand.swift

@@ -0,0 +1,63 @@
+import AppKit
+
+/// Acme design tokens, transcribed for AppKit.
+///
+/// Copied from the design system's `tokens/` rather than eyeballed, so the
+/// widget belongs to the same product as example.com instead of merely
+/// looking tidy. Two rules from that system shape most of what follows:
+///
+///   - Mono is UPPERCASE with 0.06–0.08em tracking, and is reserved for
+///     eyebrows, status and meta. Body stays sentence case.
+///   - No emoji, ever. Texture comes from Unicode punctuation — · → ● ✓ —
+///     and from a single accent colour, not from decoration.
+///
+/// System colours were the obvious default and the wrong one: .systemRed
+/// and .systemGreen are macOS's voice, not Acme's, and they shift under
+/// the user's accent-colour setting.
+enum Brand {
+
+    // Teal accent and deep blue primary — the two colours the whole
+    // identity rests on.
+    static let accent = NSColor(srgbRed: 0.078, green: 0.722, blue: 0.651, alpha: 1)      // #14b8a6
+    static let accentDeep = NSColor(srgbRed: 0.059, green: 0.463, blue: 0.431, alpha: 1)  // #0f766e
+    static let primary = NSColor(srgbRed: 0.118, green: 0.227, blue: 0.541, alpha: 1)     // #1e3a8a
+    static let primaryBright = NSColor(srgbRed: 0.114, green: 0.306, blue: 0.847, alpha: 1) // #1d4ed8
+
+    static let ink = NSColor(srgbRed: 0.043, green: 0.078, blue: 0.075, alpha: 1)         // #0b1413
+    static let paper = NSColor(srgbRed: 0.980, green: 0.980, blue: 0.976, alpha: 1)       // #fafaf9
+
+    /// Amber and rose for states the palette has no token for. Muted to
+    /// sit beside the teal rather than fight it.
+    static let warn = NSColor(srgbRed: 0.851, green: 0.596, blue: 0.180, alpha: 1)
+    static let alert = NSColor(srgbRed: 0.804, green: 0.400, blue: 0.376, alpha: 1)
+
+    enum Radius {
+        static let sm: CGFloat = 6
+        static let base: CGFloat = 10
+        static let md: CGFloat = 12
+        static let lg: CGFloat = 18
+        static let pill: CGFloat = 999
+    }
+
+    /// `--nq-ease` — the single easing curve the system uses everywhere.
+    static let ease = CAMediaTimingFunction(controlPoints: 0.65, 0, 0.35, 1)
+    static let durFast: CFTimeInterval = 0.15
+
+    /// Meta type: mono, uppercase, tracked. Eyebrows and status only.
+    static func meta(size: CGFloat = 10.5) -> [NSAttributedString.Key: Any] {
+        [
+            .font: NSFont.monospacedSystemFont(ofSize: size, weight: .semibold),
+            .kern: size * 0.07,
+        ]
+    }
+
+    static func metaString(_ text: String, size: CGFloat = 10.5, color: NSColor) -> NSAttributedString {
+        var attrs = meta(size: size)
+        attrs[.foregroundColor] = color
+        return NSAttributedString(string: text.uppercased(), attributes: attrs)
+    }
+
+    static func body(size: CGFloat = 13, weight: NSFont.Weight = .medium) -> NSFont {
+        NSFont.systemFont(ofSize: size, weight: weight)
+    }
+}

package/apps/mac-helper/Sources/AgentXHelper/Focus.swift

@@ -0,0 +1,97 @@
+import AppKit
+import ApplicationServices
+
+/// What currently has keyboard focus.
+///
+/// This exists because of a near miss. A lesson located "the search box",
+/// clicked it, and typed. The click landed on a navigation LINK rather
+/// than an input, the page changed underneath, focus ended up somewhere
+/// else entirely, and the next step pressed Return. On a social site the
+/// thing that had focus could have been the compose box — so a search
+/// query was one keystroke from being published.
+///
+/// Synthetic typing goes wherever focus is. It cannot tell a search field
+/// from a post composer from a terminal. So the caller has to look first,
+/// and that means a way to ask.
+enum Focus {
+
+    struct Focused: Codable {
+        let role: String
+        let label: String
+        let value: String?
+        /// True when this can accept typing at all.
+        let editable: Bool
+        /// True when typing here plausibly PUBLISHES something. Heuristic
+        /// and deliberately over-inclusive: the cost of a false alarm is a
+        /// refused step, and the cost of a miss is a public post.
+        let publishRisk: Bool
+        let app: String
+    }
+
+    /// Roles that accept text.
+    private static let editableRoles: Set<String> = [
+        "AXTextField", "AXTextArea", "AXComboBox", "AXSearchField",
+    ]
+
+    /// Words that suggest the field posts, sends or publishes. Checked
+    /// against the label, the placeholder and the nearest container — in
+    /// several languages, because the UI under test is not always English.
+    private static let publishWords = [
+        "post", "tweet", "compose", "reply", "publish", "send", "message",
+        "comment", "status", "quoi de neuf", "publier", "répondre", "envoyer",
+        "tweeter", "message", "commentaire",
+    ]
+
+    static func current() -> Focused? {
+        // Ask the frontmost application directly, the way AXTree does.
+        //
+        // Going through the system-wide element's focused-application
+        // attribute returned nothing here even with a text field focused,
+        // and a focus check that always fails is a gate that blocks
+        // everything — safe, and useless. Force-casting a CFTypeRef that
+        // came back nil also silently yields nil rather than an error,
+        // which is how this hid.
+        guard let app = NSWorkspace.shared.frontmostApplication else { return nil }
+        let axApp = AXUIElementCreateApplication(app.processIdentifier)
+
+        var elementRef: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(axApp, kAXFocusedUIElementAttribute as CFString, &elementRef) == .success,
+              CFGetTypeID(elementRef) == AXUIElementGetTypeID()
+        else { return nil }
+        let element = unsafeBitCast(elementRef, to: AXUIElement.self)
+
+        let role = string(element, kAXRoleAttribute) ?? ""
+        let label = [kAXTitleAttribute, kAXDescriptionAttribute, kAXPlaceholderValueAttribute, kAXHelpAttribute]
+            .compactMap { string(element, $0) }
+            .first(where: { !$0.isEmpty }) ?? ""
+        let value = string(element, kAXValueAttribute)
+
+        // Also consider the enclosing container: a composer's textbox is
+        // often unlabelled while its parent says "Post".
+        var context = "\(label) \(string(element, kAXRoleDescriptionAttribute) ?? "")"
+        var parentRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(element, kAXParentAttribute as CFString, &parentRef) == .success,
+           let parent = parentRef as! AXUIElement? {
+            context += " " + ([kAXTitleAttribute, kAXDescriptionAttribute]
+                .compactMap { string(parent, $0) }.joined(separator: " "))
+        }
+        let haystack = context.lowercased()
+        let risky = publishWords.contains { haystack.contains($0) }
+
+        return Focused(
+            role: role,
+            label: label,
+            value: value,
+            editable: editableRoles.contains(role)
+                || (string(element, kAXRoleDescriptionAttribute)?.lowercased().contains("text") ?? false),
+            publishRisk: risky,
+            app: app.localizedName ?? "unknown")
+    }
+
+    private static func string(_ node: AXUIElement, _ attr: String) -> String? {
+        var ref: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(node, attr as CFString, &ref) == .success else { return nil }
+        if let s = ref as? String { return s.trimmingCharacters(in: .whitespacesAndNewlines) }
+        return nil
+    }
+}