# Integrations and Connections

**Status:** Approved target-state baseline  
**First realization:** I0 seam; product UX deepens I2

## Target State

External systems are represented through reusable user/global `Connection` objects, narrow project bindings and provider adapters.

```text
ProviderAdapter
   ↑
Connection ── CredentialReference ── SecretStore
   │
   └─ ProjectConnectionBinding
          │
          └─ Plan/Task/Run may select or narrow

ConnectionRequirement
  records missing/deferred access and the gate that needs it
```

AWP never assumes one account per provider. Multiple GitHub, model, cloud and other accounts are normal.

## Invariants From Day 1

- `Connection` is reusable/global identity/account access, not project ownership;
- project bindings grant only specific capabilities/resources;
- Plan/Task/Run may narrow but not broaden project bindings;
- raw secrets never live on Connection/Project/Plan/Task/Run records;
- connection identity, account/resource/capabilities and health are inspectable;
- provider availability/auth/permission/resource-selection/reauth/outage are distinct states;
- OAuth/external redirects preserve exact return target and interrupted Planning/operation context;
- cancellation returns without losing state;
- deferred requirements block only at declared lifecycle gate.

## Core Primitives

### Connection

Represents authenticated relationship with provider/account/tenant. Tracks provider, account identity, credential reference, status, discovered capabilities/resources and health metadata.

### ProjectConnectionBinding

Project-local allowed subset:

```text
connectionId
allowedCapabilities[]
allowedResources[]
policy constraints
createdBy/at
```

### ConnectionRequirement

Durable missing-access requirement:

```text
provider/capability/resource need
reason
requiredByGate
status
owner
deferredUntil/revisit trigger
consequence
return target
```

### ProviderAdapter

Normalizes provider mechanics, identity, capabilities, health, resource discovery, events and operations into AWP contracts.

## Credential Lifecycle

Credentials may rotate/expire without changing Connection identity. Secret versions are referenced; reauth updates the secret reference/metadata. Execution gets short-lived projections where possible.

## Connection Onboarding Flow

```text
need detected
  -> choose existing Connection or connect new
  -> authenticate
  -> confirm provider identity/account
  -> discover/select resources
  -> choose least required capability scope
  -> bind to Project
  -> verify health/capability
  -> return exactly to interrupted context
  -> re-evaluate blocked requirement
```

## Provider Health

Connection health separates credential validity from provider outage and insufficient permissions. Automated retries are appropriate for transient provider degradation but not for missing user authorization.

## Increment Realization

| Increment | Integration realization |
|---|---|
| I0 | Connection/CredentialReference/SecretStore/provider-adapter seam; minimum Git/model/K8s access. |
| I1 | GitHub/model accounts used by live Factory, attempt-scoped projections. |
| I2 | full connection onboarding interruption/resume UX in Planning and project settings. |
| I5/I6 | CI/deployment provider capabilities and resources. |
| I7 | machine/cluster provider integration. |
| I9 | enterprise connectors/directory/org provider concerns. |

## Current Implementation State

The architecture is provider-neutral. Existing local tool credentials may be imported once into SecretStore/Connection semantics but do not remain a parallel authority.

## Deferred Realization

Broad plugin marketplace/general connector SDK productization may wait until external consumers; adapter interfaces are specified now.

## Temporary Dogfood Behavior

OpenCode/OpenRouter test credentials may be bootstrapped from owner-controlled local configuration once. Live runs do not scrape/copy the key repeatedly; the canonical secret remains behind CredentialReference.

## Decisions / ADRs

Changing global-vs-project connection ownership or permitting raw secret storage requires security Decision review.