<p align="left"><img src="assets/autodev-team.svg" width="52" alt="Autodev Team"></p>

# CoS Link for Grok Bot

**Your Grok Bot Chief of Staff should be able to coordinate with your partner's Grok Bot Chief of Staff.**

CoS Link proposes a communication protocol specifically for **Grok Bot Chiefs of Staff across separate user accounts**. Its working reference implementation provides owner-approved pairing, limited capability grants, shared messages, and revocation. Each CoS keeps its owner's computer, credentials, and private sources local.

Built by [Autodev Team](https://autodev-team.com) for the Grok Bot use case. The Grok Build and Cursor plugins provide distribution and MCP integration paths; the proposal asks the platform to add native Grok Bot identity and delivery hooks. No Slack account is required. Not affiliated with or endorsed by xAI or Cursor.

[System design](docs/architecture.md) · [Protocol](docs/protocol.md) · [Native feature proposal](docs/native-feature-proposal.md) · [Plugin setup](docs/plugin-setup.md) · [Data handling](PRIVACY.md) · [Security](SECURITY.md)

**Submitted for review:** [Grok Build marketplace PR #707](https://github.com/xai-org/plugin-marketplace/pull/707) and [Cursor publisher application](docs/publisher-application.md). Both await review; no accepted marketplace listing is claimed.

![Owner console with synthetic demo accounts](assets/owner-console.png)

## A shared plan, separate authority

> “Find a time for dinner with my partner next week.”

Your Grok Bot CoS proposes a task to your partner's approved Grok Bot CoS. Their CoS checks their calendar locally and returns candidate windows. One organizer prepares the result for the appropriate owner decision. Private event titles, calendar credentials, and unrelated context do not belong in the exchange.

The current release coordinates **task proposals and availability windows**. It does not execute calendar writes or claim that a peer can approve an action on your behalf.

```mermaid
flowchart LR
  A[Your CoS] <-->|MCP client| S[CoS Link\nauthentication · grants · mailbox]
  B[Their CoS] <-->|MCP client| S
  O[Owners] -->|pair · scope · revoke| S
  C[A2A clients] <-->|A2A 1.0 profile| S
  S --> D[(Durable SQLite storage)]
```

## What works

- Independent owner and agent credentials, with only hashed tokens stored in the mailbox database.
- Intended-recipient invitations, single-use codes, independent acceptance, and inviter verification before activation.
- Asymmetric capability grants, permission changes, per-owner pause/resume, revocation, and agent credential replacement.
- Addressed, structured messages with task correlation, expiry, turn budgets, persistent cursors, and idempotent retries.
- An owner console showing contacts, shared messages, and connection activity.
- An MCP stdio client that talks to a separately hosted service over HTTPS; loopback HTTP is available for development.
- An explicit A2A 1.0 JSON-RPC profile with authenticated discovery, task messages, retrieval, and cancellation. See the [exact supported surface](docs/protocol.md).

Tests exercise owner/agent authority, consent, replay and conflicting keys, concurrency, restart recovery, payload validation, unauthorized task access, revoked disclosure, unrelated-owner directory isolation, and A2A/MCP behavior. A separate live demo starts two real MCP processes against a local HTTP service. The installed Grok Build CLI also validates the manifest and completes an MCP initialization and tool-discovery handshake. See [verification evidence and its limits](docs/verification.md). These checks use synthetic accounts; they do not prove native Grok Bot identity, wakeups, or vendor certification.

## Run locally

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```sh
git clone https://github.com/logan-robbins/cos-link.git
cd cos-link
uv sync --locked
uv run cos-link init
uv run cos-link create-owner --name Alice --credentials-out local/alice.json
uv run cos-link create-owner --name Bob --credentials-out local/bob.json
uv run cos-link serve
```

Open **http://127.0.0.1:8080**. Each owner opens their own console with the `owner_token` from their private credential file. Share the intended owner's `id`, create an invitation, have that owner accept it, and verify their identity before activating the contact. The console keeps the key only in the current tab's memory.

Credential files and the SQLite database live under the ignored `local/` directory. The operator must distribute each owner's credentials securely. Never commit these files or paste an owner/admin key into an agent chat. Agent hosts receive only their own `agent_token`.

For a fast demonstration with no real accounts:

```sh
uv run python examples/two_owners.py
uv run python examples/live_mcp.py
```

The first example exercises the HTTP application. The second launches a temporary HTTP service and two MCP stdio clients, then verifies identities, a request, retries, inbox retrieval, task status, and revocation.

## Connect your agent

Install the `cos-link-mcp` entry point in the host environment, then configure a standard MCP server:

```json
{
  "mcpServers": {
    "cos-link": {
      "command": "cos-link-mcp",
      "env": {
        "COS_LINK_URL": "https://your-mailbox.example",
        "COS_LINK_TOKEN": "<this owner's agent credential>"
      }
    }
  }
}
```

Use the [packaged integration instructions](docs/plugin-setup.md) for Grok Build or Cursor. Their manifests use environment placeholders, never real secrets. The command must already be installed and accessible to the host; the plugin does not silently install runtimes or execute a remote installer.

Ask the agent to list contacts, submit a `task.propose` message, and poll the inbox. Persist cursors after processing and reuse the same idempotency key on retries. A host routine can schedule polling. **MCP does not, by itself, wake an idle Grok Bot.** A supported native wake mechanism remains part of the platform proposal.

## Deploy a shared mailbox

Use one service instance, persistent storage, a private data directory, and an HTTPS reverse proxy. Set `COS_LINK_PUBLIC_URL` to the service's external HTTPS origin so the Agent Card advertises the right endpoint. Restrict provisioning access and add rate limits at the proxy. The service operator can read shared payloads; there is no end-to-end encryption claim.

A container recipe is included:

```sh
docker build -t cos-link .
docker volume create cos-link-data
docker run --rm -v cos-link-data:/data cos-link init
docker run --rm -v cos-link-data:/data cos-link create-owner --name Alice --credentials-out /data/alice.json
docker run --rm -p 127.0.0.1:8080:8080 -v cos-link-data:/data cos-link
```

Retrieve and distribute credential files securely through the operator's deployment workflow. Configure HTTPS before exposing the service remotely. The Dockerfile is a deployment recipe; local Python verification does not constitute a production deployment or container runtime test.

## Why publish this

Grok Bot documents internal Bot handoffs and copied templates. Trusted cross-account contacts need additional product primitives: verified owner/Bot identity, bilateral permissions, authenticated delivery and wakeups, and approval provenance.

This repository makes that discussion concrete. The [native feature proposal](docs/native-feature-proposal.md) describes those primitives; the [submission research](docs/submission-research.md) distinguishes the Grok Build marketplace, Cursor publisher applications, Grok Bot templates, and community feedback routes. Marketplace submission or acceptance would distribute the integration, not implement native account peering.

## Verify and contribute

```sh
uv run ruff check .
uv run pytest -q
uv run python examples/two_owners.py
uv run python examples/live_mcp.py
uv build
```

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the [Apache 2.0 license](LICENSE).