> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Connectors Work

> The CLI contract, JSON output format, permission model, and discovery system behind AOS connectors.

## The CLI Contract

Every AOS connector is a Python CLI tool that implements a standard interface. The contract is defined in the [Harness Spec](https://github.com/ArgentAIOS/argentos) and enforced at runtime.

### Global Flags

Every connector must support these flags:

| Flag            | Purpose                                               |
| --------------- | ----------------------------------------------------- |
| `--json`        | Output structured JSON instead of human-readable text |
| `--mode <tier>` | Set the permission tier for this invocation           |
| `--verbose`     | Enable detailed output                                |
| `--version`     | Print version and exit                                |

### Required Commands

Every connector must implement three built-in commands:

| Command               | Purpose                                                               |
| --------------------- | --------------------------------------------------------------------- |
| `capabilities --json` | Self-describe: tool name, version, supported modes, full command list |
| `health --json`       | Report readiness: `healthy`, `needs_setup`, `degraded`, or `error`    |
| `config show --json`  | Show current configuration with secrets redacted                      |

## JSON Output Envelope

All connector output follows a standard envelope format:

### Success

```json theme={null}
{
  "ok": true,
  "tool": "aos-github",
  "command": "issue.list",
  "data": {
    "issues": [
      { "number": 42, "title": "Fix login bug", "state": "open" }
    ]
  },
  "meta": {
    "mode": "readonly",
    "duration_ms": 234,
    "timestamp": "2026-03-31T12:00:00Z",
    "version": "1.0.0"
  }
}
```

### Error

```json theme={null}
{
  "ok": false,
  "tool": "aos-github",
  "command": "issue.delete",
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Command requires mode=admin",
    "details": {
      "required_mode": "admin",
      "actual_mode": "readonly"
    }
  },
  "meta": {
    "mode": "readonly",
    "duration_ms": 3,
    "timestamp": "2026-03-31T12:00:01Z",
    "version": "1.0.0"
  }
}
```

### Exit Codes

| Code | Meaning                   |
| ---- | ------------------------- |
| `0`  | Success                   |
| `2`  | Invalid usage / arguments |
| `3`  | Permission denied         |
| `4`  | Auth / config error       |
| `5`  | Backend unavailable       |
| `6`  | Not found                 |
| `10` | Internal error            |

## Permission Model

Connectors enforce a four-tier permission model via the `--mode` flag:

| Mode       | Access Level                    | Examples                                       |
| ---------- | ------------------------------- | ---------------------------------------------- |
| `readonly` | Read-only queries, no mutations | List issues, search contacts, view invoices    |
| `write`    | Create and update operations    | Create ticket, send message, update record     |
| `full`     | All operations including bulk   | Bulk update, batch operations, imports         |
| `admin`    | Destructive and configuration   | Delete records, revoke access, modify settings |

Permission enforcement happens **inside the command execution path**, not just at the documentation level. Every command is mapped to a minimum mode in `permissions.json`:

```json theme={null}
{
  "commands": {
    "issue.list": "readonly",
    "issue.create": "write",
    "issue.delete": "admin",
    "health": "readonly",
    "config.show": "readonly"
  }
}
```

If you call a `write` command with `--mode readonly`, the connector returns a structured error with exit code 3 (permission denied).

## Discovery System

ArgentOS discovers connectors automatically from multiple sources:

### 1. Vendored connectors (`tools/aos/`)

Shipped with the ArgentOS repository. These are the 61 built-in connectors.

### 2. User connectors (`~/.argentos/connectors/`)

Installed by the user or downloaded from the marketplace.

### 3. PATH executables

Any binary on your system PATH that starts with `aos-` is discovered automatically.

### 4. Custom directories

Set `ARGENT_CONNECTOR_REPOS` environment variable to a comma-separated list of directories to scan.

### Discovery Process

```mermaid theme={null}
flowchart TD
    A["Gateway startup"] --> B["Scan discovery paths"]
    B --> C{"Found aos-* directory?"}
    C -->|Yes| D["Read connector.json"]
    C -->|No| E["Check PATH for aos-* binary"]
    D --> F["Read permissions.json"]
    F --> G["Probe: capabilities --json"]
    G --> H["Probe: health --json"]
    H --> I["Register in connector catalog"]
    E --> G
```

Each discovered connector gets an `installState`:

| State         | Meaning                                                                 |
| ------------- | ----------------------------------------------------------------------- |
| `ready`       | Binary found, capabilities parsed, health check passed                  |
| `needs-setup` | Binary works but health check reports missing configuration             |
| `repo-only`   | Connector directory exists but no runnable binary (needs `pip install`) |
| `error`       | Binary exists but capabilities or health probe failed                   |

## The `connector.json` Manifest

Every connector has a `connector.json` file that describes its metadata, commands, auth requirements, and UI field definitions:

```json theme={null}
{
  "tool": "aos-github",
  "backend": "github-api",
  "manifest_schema_version": "1.0.0",
  "connector": {
    "label": "GitHub",
    "category": "developer-tools",
    "categories": ["developer-tools", "source-control", "ci-cd"],
    "resources": ["repo", "issue", "pr", "branch"]
  },
  "auth": {
    "kind": "service-key",
    "required": true,
    "service_keys": ["GITHUB_TOKEN"],
    "interactive_setup": [
      "Create a GitHub personal access token with repo scope.",
      "Add GITHUB_TOKEN in API Keys before enabling live reads."
    ]
  },
  "commands": [
    {
      "id": "issue.list",
      "summary": "List issues in a repository",
      "required_mode": "readonly",
      "supports_json": true,
      "resource": "issue",
      "action_class": "read"
    }
  ]
}
```

## Security Baseline

All connectors must follow these security rules:

* No shell execution of unsanitized user input
* Path-based tools must enforce root allowlist boundaries
* `config show` must redact secrets (API keys, tokens, passwords)
* Error messages must not leak credentials
* Write operations must respect the permission tier
* Destructive operations (`delete`, `revoke`) require `admin` mode

## Integration with ArgentOS

When ArgentOS discovers a connector, it:

1. Registers it in the **connector catalog** (`src/connectors/catalog.ts`)
2. Makes its commands available as **agent tools** (`src/connectors/tools.ts`)
3. Shows it in the **dashboard Systems panel** with setup status
4. Allows it to be used in **Workflows** as action nodes
5. Makes it available to the **execution worker** for autonomous task processing