# car-automation

macOS automation bridges for the Common Agent Runtime.

CAR already integrates the heavy macOS surfaces (Foundation Models,
Accessibility, NSWorkspace, Speech, Vision capture). This crate fills the
*action* layer — the primitives an agent uses to make existing apps do
things without reimplementing each app's domain.

## Modules

| Module        | Backend                  | Purpose                                                           |
|---------------|--------------------------|-------------------------------------------------------------------|
| `applescript` | `osascript` subprocess   | Run AppleScript or JavaScript-for-Automation against any scriptable Mac app (Mail, Finder, Office, Adobe, Music, …). |
| `shortcuts`   | `shortcuts(1)` CLI       | Enumerate and invoke macOS Shortcuts — the universal automation bus. Reaches every app that donates `AppShortcuts` *and* every workflow the user authored. **This is also CAR's App Intents bridge**: the shortcuts CLI surfaces both equally, so a separate App Intents framework binding adds no capability. `Shortcut::tool_slug` / `tool_description` / `parameters_schema` produce tool-registration metadata for use with `car-engine`'s `register_tool_schema`. |

## Why subprocess, not framework bindings

Both backends are *intentionally* shell-outs. The `osascript` and
`shortcuts` CLIs are stable Apple-shipped tools that already handle
the framework integration, sandboxing, and TCC prompts. A direct
binding to OSAKit / `Shortcuts.framework` would be more code, more
permissions surface, and more brittle across macOS versions, with
no real performance win for the call frequencies an agent uses.

## Platform support

macOS only. On Linux and Windows every entry point returns
`AutomationError::PlatformUnsupported` so callers can branch cleanly
without `cfg`. No cargo features — `cfg(target_os = "macos")` gates
the implementation.

## Permissions

- AppleScript controlling another app the first time triggers a TCC
  Automation prompt for the *parent* of `osascript` (typically your
  binary). Use `car-permissions` to preflight and surface a friendly
  message before the first call.
- Shortcuts inherit the permissions of the actions they contain;
  invoking `shortcuts run` may itself prompt.
