companion_integration: true — what it means and when the Companion runs instead of the cloud

A developer installs @human/connector-applescript from the marketplace, wires it to a muscle, and hits BRIDGE_PLATFORM_UNSUPPORTED on the first call from a Linux-hosted agent. The connector is fine. The OS is wrong. Before companion_integration, the listing looked like Slack or GitHub—and the failure looked like a bug.

The field exists so marketplace, validator, and runtime tell the same honest story.

companion_integration: true,

The problem with “installable connector”

The standard HUMΛN connector model assumes cloud deployment: install, provision credentials, call connector.invoke() from whatever server runs the agent. Network gateway.

AppleScript is a process executor: child_process.execFile('/usr/bin/osascript'). Works on macOS; nowhere else. A cloud-only install will always fail the transport layer. That is architecture, not flakiness.

What `companion_integration: true` signals

To developers: first-class Companion desktop path—for AppleScript, the applescript_run_jxa Tauri command. Tier-gated governance, structured approval card, outcome via POST /v1/events/emit. You need Companion on a Mac for execution.

To the validator: requires deployment.supportedModes to include 'self-hosted'. Cloud-only cannot meaningfully set this flag.

To the marketplace: listing shows “Requires HUMΛN Companion for full capability.” Accurate without panic.

To the muscle: nothing directly. Muscle calls ctx.call.invoke('applescript', …), catches BRIDGE_PLATFORM_UNSUPPORTED, returns a structured intent. Routing stays with the platform. Background: two-layer architecture.

The execution decision tree

When mac.invoke runs:

Is ctx.call.invoke('applescript', 'bridge.invoke') available?
  │
  ├── YES (Path A: macOS agent)
  │     → connector.invoke() → jxa-runner → osascript
  │     → MuscleResult { success: true, data: output }
  │
  └── NO (BRIDGE_PLATFORM_UNSUPPORTED)
        → MacAutomationIntent { requires_companion: true, ... }
        → Companion inbox → MacAutomationProposal
        → User approves → applescript_run_jxa
        → onApprove → POST /v1/events/emit

One muscle deployment works in both environments. The muscle does not pick the path; the platform does.

What `requires_companion: true` means

In the intent block, the flag tells Companion’s inbox (NotificationInbox.tsx) to render MacAutomationProposal instead of a generic approval prompt. That renderer checks device-local grants, builds JXA from the catalog, executes, handles TCC deep-links, and reports outcomes to HumanOS.

A browser or CLI can display the pending action. It cannot execute it. Execution needs a macOS Tauri runtime.

Device-local mac_capability_grants answers: has this device’s user granted or denied this capability ID? It is advisory UX. Canonical provenance lives in HumanOS via ctx.provenance.log. If PermissionStore says “always” but HumanOS policy requires fresh approval for tier 2, the server wins.

Scroll-stopper: A marketplace badge that hides “needs a Mac” is not convenience—it is a support ticket with a delayed fuse.

How to build your own

Manifest: companion_integration: true, 'self-hosted' in deployment.supportedModes
Transport: native invoke; return BRIDGE_PLATFORM_UNSUPPORTED elsewhere
Muscle: catch, return structured intent with your action_type
Companion renderer: wire StructuredRenderer in NotificationInbox
Tauri commands + optional PermissionStore pattern

Field vocabulary (command_id, tier, app_display_name, description) stays consistent so the inbox renders uniformly. Catalog authoring: Writing a JXA catalog entry.

So that…

…builders know when Companion is the executor; marketplace stays honest; and native Mac automation still rides HumanOS governance instead of a side-channel binary.

Go deeper

Product: Companion, Download
Docs: Quickstart, Guides
Community: Two-layer architecture, JXA catalog entry, Companion deployment model

Series: Part 3 of 3 — Mac Automation Reference