# Cortex: connect an existing Hybrid ID agent

This bridge checks the identity and current representation of an **existing**
workload agent. Cortex keeps its existing private presentation record, name,
picture, role labels and planned tasks. Connecting it does not enroll another
agent, issue a key, change a wallet binding or grant execution authority.

Implementation: `HYBRID_CORTEX_AGENT_AUTHORITY_V1`. Deployment status and release
receipts are recorded in `docs/cortex-agent-bridge-handoff.md` in the Hybrid ID
website repository. Do not infer activation just from this contract.

## Endpoint and consent

The confidential Cortex backend calls the existing Identity provider through its
private Core backchannel:

`POST http://127.0.0.1:3152/hybrid/cortex-agents`

Use `Content-Type: application/x-www-form-urlencoded` and HTTP Basic authentication
with Cortex's registered client ID and current client secret. Keep both the app
secret and user OIDC access token server-side. Public ingress returns 404.
Do not call this from a browser or reuse the trusted native admin inventory API.

Request `openid cortex:agents` during OIDC authorization. Company representation
also requires the independently consented `cortex:companies` scope. The configured
Cortex app alone can request this scope; other registrations do not acquire it.
The user must see and approve the new consent. Old access tokens/approvals are not
silently upgraded. Use the existing app's Authorization Code + PKCE flow and verify
its ID token; `subject` below is that token's exact pairwise `sub`.

The bridge rechecks client status/secret, access token, grant, durable consent and
native login on every request and again after the authority lookup. Company mode
also checks current canonical `company:manage` permission and the agent's existing
workspace assignment. A company title or Cortex role label grants no authority.

## Inventory

Form fields (no additional fields):

```json
{
  "operation": "list",
  "access_token": "<current Cortex OIDC access token>",
  "subject": "<validated Cortex pairwise sub>",
  "workspace": "",
  "offset": "0"
}
```

An empty workspace selects agents controlled by the current identity. A canonical
company workspace UUID selects its assigned workload agents, only with current
company-management authority. The response has up to 50 items and `nextOffset`
(integer or null). Send the returned offset as a string. Pagination is a live view,
not a frozen snapshot: deduplicate by `agent_id` and check the chosen record afresh.

```json
{
  "schema": "HYBRID_CORTEX_AGENT_AUTHORITY_V1",
  "subject": "<Cortex pairwise sub>",
  "workspace": null,
  "checkedAt": 1791320000000,
  "expiresAt": 1791320010000,
  "items": [{
    "agent_id": "0123456789abcdef0123456789abcdef",
    "name": "Existing arbitrage bot",
    "status": "ACTIVE",
    "controller_subject": "<controller's Cortex pairwise sub>",
    "representation": "personal",
    "workspace": null
  }],
  "nextOffset": null
}
```

Examples are illustrative, not the owner's actual bot or a currently valid receipt.
No native user identifier, workload key/client credential, wallet, balance, trading
scope, strategy, budget or execution configuration is returned. A controller's
pairwise subject is an opaque identity reference, not a display name or email.

## Verify the selection and subsequent use

```json
{
  "operation": "check",
  "access_token": "<current Cortex OIDC access token>",
  "subject": "<validated Cortex pairwise sub>",
  "workspace": "",
  "agent_id": "0123456789abcdef0123456789abcdef",
  "controller_subject": "<controller reference saved from inventory>"
}
```

The response repeats schema, subject, workspace and freshness fields, then returns
`agent_id`, `allowed` (boolean), and `agent` (the inventory projection or null).
Unknown/unowned agents fail closed without revealing another user's inventory.
A revoked agent or changed controller returns `allowed: false`. Company removal
can instead return 403 when the user no longer has workspace authority.

Cortex must obtain a **new check** before saving the reviewed link and before each
subsequent authorized use. Accept only `allowed: true`, the same authenticated
subject, selected workspace, agent and saved controller; require a current result
with at most ten seconds between `checkedAt` and `expiresAt` (Unix milliseconds).
Never use an old inventory response, stale success, label or browser-supplied ID as
ownership proof. These private authenticated responses are online authority
observations, not offline-verifiable signed credentials or public KYC evidence.

The link write belongs in Cortex. Keep the existing presentation-record ID. Show
its selected agent and representation to the user; require explicit confirmation.
Protect the write with the current Cortex session and CSRF protection, an expected
record revision and an idempotency key bound to the complete selected reference.
Persist the issuer, user subject, agent ID, controller subject and workspace in one
transaction after the current check. A retry of the same confirmed operation may
return the same link; a different selection must require a new review. Read/check
operations themselves issue no one-time approval, machine credential or grant.

## Stable identity, naming and revocation

- `agent_id` is the existing Identity agent registry's `public_id`. A missing alias
  is assigned once; this does not create another workload or publish anything.
- The supported workload key-rotation API updates the **same** `client_id` row and
  revokes its old access tokens. Its signing-key reference changes, but agent ID,
  workload scopes and existing wallet associations are preserved. Replacing a
  client with a newly registered client is not key rotation and is not auto-linked.
- `name` reflects the current Identity workload label. Cortex names, optional
  pictures, role descriptions and task selections remain local overrides. Renaming
  a Cortex profile must not rename/recreate the workload. This bridge has no global
  name/picture write API, controller-transfer or agent-creation operation.
- Company assignment is the existing workload workspace, checked against current
  company authority. The bridge cannot assign a personally scoped bot to another
  company. An unauthorized or mismatched assignment is denied, not inferred.
- Withdrawing Cortex consent or disabling its client denies this bridge without
  revoking the trading workload, its keys or its wallet. Cortex must enforce that
  denial on its own actions. Signing out or switching accounts cannot reuse the
  previous subject's link authority.
- Central workload revocation denies subsequent checks and its workload tokens;
  domain wallet policies, pending actions and completed trades retain their own
  controls. No promise is made to reverse completed actions or cancel pending ones.
- Deleting a Cortex presentation/link affects Cortex only. Canonical transfer and
  deletion are not exposed here. Any externally changed controller invalidates the
  saved controller binding and requires a new reviewed connection.
- Multiple separately enrolled workload clients are not automatically one logical
  agent. This contract discovers an existing identity; it does not issue a new
  per-component runtime credential. Cortex execution requires its own separately
  approved capability and human-review controls.

All returned data is private to the approved app context. This consent does **not**
authorize public publishing of controller/agent/workspace relationships. Retain the
Agent badge, but require separate owner approval before public disclosure; do not
present an ownership check as KYC, trading permission or public publication proof.

## Errors and reconnect behavior

400: malformed/extra fields. 401: wrong/inactive app or secret. 403: missing,
expired or revoked user consent/session/authority. 405: use POST. 503: unavailable
or unverified service result. Responses are `Cache-Control: no-store`.

For 403, stop the protected action and offer an explicit reconnect/review. For 503,
retain the private profile but mark authority unavailable and retry; never treat an
outage as permission or delete the prepared profile. A 200 with `allowed: false`
is also a denial. Existing OIDC access-token lifetime applies; the bridge neither
adds refresh grants nor extends the native sign-in session.

OpenAPI: [cortex-agents.openapi.json](https://hybrid-id.com/integrations/cortex-agents.openapi.json).

## Separate execution integration

Durable execution requires the separately approved [Cortex execution contract](cortex-execution.md). Creation/linking remains non-executing. See its deployment receipt (contact the integration team) and [OpenAPI](cortex-execution.openapi.json) for current availability.


## Delegated private Cortex linking

The [private automation owner-mapping contract](cortex-agent-owner.md) provides the
current account mapping without a browser session. It grants no Cortex write permission;
Cortex must separately enforce an explicit linking delegation and its own atomic setup/link
transaction. Existing signed-in linking remains supported. Never create replacements.
