Companion integration manifest

# Companion integration manifest

Some capabilities cannot run entirely in HUMΛN Cloud — they need the user's device, native APIs, or local consent. Mark those connectors with companion_integration: true in the connector manifest so marketplace, runtime, and Companion know to route through the desktop/local path.

Overview

companion_integration is not a marketing badge. It signals:

Marketplace — show “Requires HUMΛN Companion for full capability.”

Validator — requires companion_tier and deployment.supportedModes including 'self-hosted'.

Runtime split — cloud muscle may return BRIDGE_PLATFORM_UNSUPPORTED; Companion renders a proposal; user approves; Tauri/native executes; outcome returns via POST /v1/events/emit.

Canon field definition: packages/connector-sdk/src/types.ts (ConnectorManifest.companion_integration).

Manifest requirements

import type { ConnectorManifest } from '@human/connector-sdk';
export const manifest: ConnectorManifest = {
  kind: 'humanos.connector.v1',
  id: 'human.connector.applescript.mac',
  name: 'macOS Automation (JXA)',
  version: '1.0.0',
  companion_integration: true,
  companion_tier: 'gold', // silver | gold | platinum — required when companion_integration: true
  deployment: {
    supportedModes: ['self-hosted'], // required — cloud-only cannot set companion_integration
  },
  capabilities: ['mac.automation.run'],
  // … auth, operations, provenance …
};

Validator rules (packages/connector-sdk/src/manifest-validator.ts):

companion_integration: true → companion_tier required

companion_integration: true → deployment.supportedModes must include 'self-hosted'

Execution paths

┌─────────────────┐     cloud agent      ┌──────────────────┐
│  Agent / Muscle │ ───────────────────► │ HUMΛN API        │
└────────┬────────┘                      └────────┬─────────┘
         │ BRIDGE_PLATFORM_UNSUPPORTED             │
         ▼                                         │
┌─────────────────┐   proposal + HITL   ┌─────────▼─────────┐
│ Companion       │ ◄────────────────── │ Structured intent │
│ (desktop/local) │                     │ (MacAutomation…)  │
└────────┬────────┘                     └───────────────────┘
         │ user approves
         ▼
   Native / JXA / Tauri execute
         │
         ▼
   POST /v1/events/emit (provenance)

Path A — self-hosted agent on macOS: connector runs in-process when the bridge is available.

Path B — cloud agent: muscle returns intent; Companion on the user's machine runs the action after approval.

Try it — publish a companion-aware connector

After install, invoke via agent muscle or Companion — cloud callers receive structured intents when the bridge is unavailable.

CIO companion tiers (summary)

Tier gates are enforced server-side — clients cannot upgrade autonomy.

Use cases

macOS JXA catalog entries — cloud proposes; Companion executes locally.

1Password / Keychain — secrets never leave device; companion_integration: true.

Native calendar / mail — same split for OS APIs unavailable in cloud workers.

Security considerations

See also

Embed Companion in proxy mode

Human-in-the-Loop

Community: Mac automation Path B

Guide: Companion as platform

Same route in the other SDKs

The TypeScript tab above is the contract. These calls hit that same route.