integration-plugins

Integration, Issue, Pull-Request, And Repository Plugins

Integration plugins in `packages/plugins/src/integrations/` own service metadata, auth method descriptors, credential schemas, and credential verification. Issue plugins in `packages/plugins/src/issues/` reference an integration by `integrationId` and own issue operations. Pull-request plugins in `packages/plugins/src/pull-requests/` do the same for PR/MR operations. Repository plugins in `packages/plugins/src/repository/` own hosted-repository operations and host detection. GitHub follows the same plugin contracts as the other integrations.

Issue Context During Task Creation

Task creation retrieves details for providers that support issue context before enabling creation with the default context setting. Loading and errors are visible; errors offer a retry. Changing or clearing the selection discards stale query results. Enrichment preserves edited context and a removed issue mention. Turning off the default issue-context setting skips this retrieval.

Authentication Contract

`capabilities.auth` is a serializable descriptor for connection UI: form fields, OAuth, device flow, CLI import, and whether an account label is required. Executable code belongs in `behavior.auth`, which must register both:

• `credentialsSchema`: the provider's Zod parser for its JSON credential payload. Use the

same schema in the provider's client factory and verifier. Parsing is local validation and normalization; it does not prove that a credential is accepted by the remote API.

• `verify`: checks credentials against the provider and returns canonical credentials on

success, together with optional stable account identity and display metadata. Persist the returned credentials, never fall back to the submitted form values.

Three behaviors are optional:

• `credentialsFromOAuthToken({ accessToken, expiresAt?, host })`: required when the descriptor

declares an `oauth` method (sign-in through the Emdash auth server). It maps an access token issued by the server into the provider's credential shape. The server keeps the refresh token.

• `startDeviceAuthorization`: required when the descriptor declares an `oauth-device` method.

It returns the user code, verification URL, and lifetime, plus `complete(signal)`, which polls until the user approves and resolves with credentials for `verify`. Build it with `startDeviceAuthorizationSession` from `integrations/helpers/oauth-device.ts` (RFC 8628); every request times out after 30 seconds, and polling retries network failures and 5xx responses until the code expires.

• `refreshCredentials(host, credentials, now)`: renews credentials the integration issued itself

(e.g. by device sign-in) with their refresh token. It returns replacement credentials, or `undefined` when these credentials cannot be refreshed.

Credentials that expire carry `expiresAt` (epoch milliseconds); `credentialsExpireAt` reads it.

Sign-in through the Emdash auth server (`oauth`)

The desktop runs the browser PKCE flow against the auth server for any integration whose descriptor declares `{ kind: 'oauth', providerId }`. Emdash accounts are created and signed into only with `EMDASH_SIGN_IN_PROVIDER` (GitHub); the auth server enforces this too. When signed in, the desktop links the provider account (`account-link/start?provider_id=...`). When signed out, it signs in with GitHub for GitHub itself; for any other provider (GitLab) it signs in with GitHub first and then links, so another provider never creates an Emdash account. The exchange returns the provider access token, its expiry, and the account identity. `IntegrationOAuthTokens` (`core/features/integrations/node/integration-oauth-tokens.ts`) maps the token with `credentialsFromOAuthToken`, verifies it with the plugin's `verify` (so an account has the same identity whichever method connected it), checks that it belongs to the account the server named, and saves it through `connectVerified` with credential source `emdash_oauth`. Reconnecting an account passes its `accountId` through sign-in or linking, so a token for another identity is not saved. GitHub and GitLab use this path; there is no per-provider adapter.

Renewing expiring credentials

`IntegrationAccountStore.getAccount` is the only credential read path. When stored credentials expire within five minutes (`CREDENTIAL_RENEWAL_SKEW_MS`), it renews them before returning the account. The store decides when; the account's current credential source decides how. Both are reread under the account lock, because a reconnect can replace them during a read:

• `emdash_oauth`: the renewer registered with `setRenewer` asks the auth server for the linked

account's current token (`POST /api/v1/auth/electron/provider-token` with the Emdash session). The server refreshes tokens that expire within ten minutes, so it always returns a token that outlives the desktop window. Every client of an Emdash account shares that token, and GitLab revokes the previous token pair on refresh.

• any other source: the integration's `refreshCredentials`, if it has one.
• no `expiresAt` (access tokens, GitHub OAuth tokens): never renewed.

Renewals are serialized per account and the new credentials are written (secret only; metadata unchanged) before they are returned, because rotating refresh tokens are single-use. A failed renewal logs and returns the stored credentials with `renewalError`; the provider's 401 then fails the API call, and the connection status shows `renewalError` (for example, "Sign in to Emdash to keep GitLab connected."). A renewal the provider or server rejected (`auth_failed`, or an account no longer linked to the Emdash account) is not retried until the credentials change (for example on reconnect) or, for `emdash_oauth`, until the user signs in or out of Emdash, since another Emdash account may have the provider account linked. Other failures, including a missing or expired Emdash session, are retr