Lifecycle Events

Beyond provider webhooks, auto emits its own auto.* events when platform state changes: a resource apply starts or finishes, a connection becomes usable in a project, a session binding transitions, an onboarding run advances. Agents use these to continue work on facts instead of polling or asking a human to say “done”. This page catalogs each event, what emits it, and the trigger shapes that consume it. auto.* triggers need no connection: — the events are internal and routed per project through the same pipeline as every other event. Payload placeholders render against the bare payload ({{apply.operationId}}, {{provider}}), and where filters address it with $. paths, exactly as on provider events.

Apply lifecycle

`auto.project_resource_apply.{started,completed,failed}`

Emitted by the apply workflow for every non-dry-run apply of project resources — whether it came from GitHub Sync after a merge or from an apply the platform ran outside Sync. Dry runs emit nothing. Each event is deduplicated on the apply’s operation id plus status, so one apply produces at most one started and one terminal completed or failed. The payload’s stable core is the apply object:

{
  "type": "auto.project_resource_apply.completed",
  "artifact": {
    "type": "github.pull_request",
    "externalId": "github:12345:acme/widgets:pull/12"
  },
  "apply": {
    "operationId": "github-sync:push:binding-id:abc123",
    "status": "completed",
    "auditAction": "github_sync.apply",
    "dryRun": false,
    "prune": true,
    "source": "inline",
    "request": {
      "counts": { "resources": 2, "delete": 0, "assets": 0 },
      "resources": [
        { "kind": "agent", "name": "coder" },
        { "kind": "environment", "name": "agent-runtime" }
      ],
      "delete": []
    },
    "plan": {
      "counts": {
        "create": 1, "update": 2, "archive": 0, "unchanged": 4,
        "pruned": 0, "diagnostics": 0, "triggers": 3
      },
      "changedResources": [
        { "action": "create", "kind": "agent", "name": "coder" }
      ],
      "changedResourcesOmitted": 0,
      "createdAgentNames": ["coder"]
    }
  },
  "project": {
    "organizationId": "org_...",
    "projectId": "proj_..."
  }
}

Field notes:

apply.auditAction is github_sync.apply for Sync-driven applies and project_resources.apply for applies that ran outside Sync — the filter that separates “a merge landed” from every other apply path.
apply.plan is present only on completed; apply.error { name, message } is present only on failed (with a structured diagnostic attached for validation failures). started carries the request summary but no plan.
apply.plan.changedResources is a bounded preview (up to 50 changed resources, with changedResourcesOmitted counting the rest). apply.plan.createdAgentNames is the complete sorted list of agents the apply created — use it, not the preview, for exact first-install routing like $.apply.plan.createdAgentNames: { contains: "coder" }.
The top-level artifact is present when the apply carries one. GitHub Sync resolves the merged pull request for production-branch pushes (with a merge-commit fallback for the async commit→PR association), so a Sync apply event usually carries the merged PR’s artifact — which means bind routing can deliver it straight back to the session that owns that PR.

Placeholders: {{apply.operationId}}, {{apply.plan.counts.create}}, {{apply.plan.counts.update}}, {{apply.error.message}}. The canonical consumer is a session that shipped a .auto/ change by PR and wants to resume the moment Sync applies it:

triggers:
  - event: auto.project_resource_apply.completed
    where:
      $.apply.auditAction: github_sync.apply
    message: |
      GitHub Sync applied project resources.

      Operation: {{apply.operationId}}
      Created: {{apply.plan.counts.create}}
      Updated: {{apply.plan.counts.update}}
      Archived: {{apply.plan.counts.archive}}

      Verify the deployed resources and continue the workflow without
      asking the user to confirm the merge.
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop

For applies without an artifact (applies outside Sync, or the rare Sync apply whose PR could not be resolved), use a project-scoped route instead — deliver with routeBy: { kind: allLiveSessions } and a narrow where, or spawn. For failed events, surface {{apply.error.message}} first, then use apply.request.resources and apply.request.delete to identify which file or delete operation needs repair.

Connection lifecycle

`auto.connection.established` / `auto.connection.removed`

A connection event fires exactly when the set of connections usable by a project changes. established means “this connection just became usable here”; removed means it no longer is. Nothing a project can observe changed — a token refresh, a repeat allow, a same-account re-auth — means no event. established fires once per grant × project when:

a provider OAuth flow completes with the project allowed (Slack, Linear, built-in MCP providers, …)
a GitHub App installation is connected to the project
a Telegram manager bot or model-provider API token is connected with the project allowed
an existing org-level connection is allowed into the project
an agent-tool MCP OAuth connection completes

removed fires once per grant × project when availability ends: reason: "revoked" when the grant is removed, reason: "replaced" when a replace flow retires the old grant (the replacement then fires established with reestablished: true). Internal platform grants never emit either event, and agent-tool MCP connections currently have no removal path — they only emit established. Two payload shapes, discriminated by kind. Provider grants:

{
  "type": "auto.connection.established",
  "kind": "provider",
  "provider": "slack",
  "connection": "slack",
  "providerGrantId": "pg_...",
  "credentialKind": "oauth",
  "externalAccount": {
    "providerAccountId": "T0123ABC",
    "loginOrName": "acme",
    "accountType": "workspace"
  },
  "scopes": ["chat:write"],
  "resourceSelection": { "kind": "all" },
  "requester": { "kind": "user", "userId": "user_..." },
  "reestablished": false,
  "project": { "organizationId": "org_...", "projectId": "proj_..." }
}

Agent-tool MCP connections:

{
  "type": "auto.connection.established",
  "kind": "mcp",
  "provider": "mcp",
  "connection": "my-linear-mcp",
  "tool": "linear",
  "serverUrl": "https://mcp.linear.app/sse",
  "credentialKind": "oauth",
  "scopes": ["read", "write"],
  "reestablished": false,
  "project": { "organizationId": "org_...", "projectId": "proj_..." }
}

removed payloads drop scopes, resourceSelection, reestablished, and requester and carry reason instead. On established, requester is present when the flow had an authenticated actor: { kind: "user", userId } for an auto user, { kind: "provider", provider, externalId, displayName, accountRef } for a provider identity.

Select connections with where: filters on the payload — never with the trigger-level connection: binding. That binding resolves a connection name to a grant at apply time, which cannot work for a connection that does not exist yet, the exact situation this event exists for.

A working consumer from this repo’s own production config — an observer that announces each new connection in Slack (trimmed):

.auto/agents/connection-observer.yaml

name: connection-observer
session:
  archiveAfterInactive:
    seconds: 3600
displayTitle: "Connection feed: {{provider}} / {{connection}}"
systemPrompt: |
  You report newly established project connections to Slack and do
  nothing else. Send exactly one concise message per delivery, then
  archive your session. Never include credentials, tokens, scopes,
  server URLs, or the raw event payload.
tools:
  auto:
    kind: local
    implementation: auto
  chat:
    kind: local
    implementation: chat
    auth:
      kind: connection
      provider: slack
      connection: slack
      optional: true
triggers:
  - event: auto.connection.established
    message: |
      Report this newly established project connection to Slack.

      - Kind: {{kind}}
      - Provider: {{provider}}
      - Connection: {{connection}}
      - External account: {{externalAccount.loginOrName}}
      - Tool: {{tool}}
      - Re-established: {{reestablished}}
    routing:
      kind: spawn

To watch one provider, add where: { $.provider: slack }. This composes with optional: true connection-bound triggers: an agent whose Slack triggers are marked optional (so apply skips them while Slack is absent) can carry an auto.connection.established trigger that wakes it to bootstrap the moment Slack arrives — and in a Sync-enabled project, an established event also schedules a regating Sync run automatically, so those optional triggers activate without a new commit. Semantics worth knowing:

Forward-looking only. Triggers fire on changes after they exist. An agent applied after the connection was made gets no synthetic catch-up event; check auto.connections.list at first run for “on connect or already connected” behavior.
Delivery is per project. An org-level grant allowed into three projects fires three events, each visible only to that project’s agents.
Dedup is durable. Events dedup on the grant × project access-row lifetime, so retried flows and repeat allows cannot double-fire; removing and re-allowing mints a fresh row and fires again.
Emission is fail-safe. A connection flow never fails because event dispatch did; a dispatch failure after the record is written is retried by the pending-event sweeper.

`auto.connection.authorization_attempt.finished` (not authorable)

When a session starts an OAuth flow through the runtime auto tools, the platform binds that session to the authorization attempt and delivers the terminal outcome — completed, failed, or expired — straight back to it. This continuation is automatic: agents do not declare a trigger for this event, and it answers “what happened to the authorization my session started?” rather than “what connections changed in this project?”. A session that also declares an auto.connection.established trigger receives both messages, clearly distinct.

Session-binding lifecycle

`auto.session.binding.{bound,updated,unbound}`

Emitted transactionally on every binding transition: a session claims a target (a PR, an issue, a thread, an agent slot), a binding’s context updates, or a binding releases. The payload describes the holder session and the transition:

session — the holder: { id, agentResourceId, agent, projectId, bindingRevision }
binding — { id, revision, target { type, externalId }, source, releasePolicy, continuity, metadata, context, boundAt }, plus releasedBy and unboundAt on unbound
transition — { kind, cause, context }, with previousContext, previousHolderSessionId, or nextHolderSessionId when applicable

transition.cause records what drove the transition: manual_bind, manual_unbind, manual_update, attributed_event, mention, observed_binding_event, session_spawn, trigger_spawn, chat_send, trigger_release, archive, takeover, rollover, or system. Useful filters: $.binding.target.type: github.pull_request, $.transition.kind: bound, $.transition.cause: trigger_spawn. These events route to the holder session as an auto.session bind target, which makes their consumer shape unusual: the listener is an observer agent whose sessions are bound to the sessions they watch (for example, a coordinator observing the workers it spawned — spawned-session observation is on by default via the agent’s session.observeSpawnedSessions). The observer declares a bind route over target: auto.session, and can mirror the observed session’s claims with observedTarget:

triggers:
  - event: auto.session.binding.bound
    where:
      $.binding.target.type: github.pull_request
      $.transition.cause: trigger_spawn
    message: |
      Observed session {{session.id}} ({{session.agent}}) bound
      {{binding.target.type}} {{binding.target.externalId}}.
      Track this pull request as part of the work you coordinate.
    routing:
      kind: bind
      target: auto.session
      onUnmatched: drop
      observedTarget:
        action: bind

observedTarget: { action: bind } claims the observed event’s own binding.target for the observer session, so later events about that PR also reach the coordinator; action: unbind releases the observer’s claim. observedTarget is legal only on bind routes over target: auto.session listening on these three event keys.

Onboarding

`auto.onboarding.phase_changed`

Emitted transactionally whenever a project onboarding run’s state changes. Payload: project { organizationId, projectId }, run { id, teamId, commission, phase, evidence, revision, completedAt }, transition { previousPhase, phase, changed { phase, commission, evidence, completed } }, and session { id, agent } identifying the writer. Deduplicated per run revision. Useful filters: $.transition.phase, $.run.teamId. Routing: project-scoped deliver or spawn — the event carries no bind target. Most teams never author triggers on this event; it exists for onboarding orchestration agents.

Quick reference

Event key	Emitted when	Bind target
`auto.project_resource_apply.started`	A non-dry-run apply begins	`github.pull_request` when the apply carries a PR artifact
`auto.project_resource_apply.completed`	The apply succeeds	same
`auto.project_resource_apply.failed`	The apply fails	same
`auto.connection.established`	A connection becomes usable in a project	—
`auto.connection.removed`	A connection stops being usable (`reason: revoked \| replaced`)	—
`auto.session.binding.bound` / `.updated` / `.unbound`	A session binding transitions	`auto.session` (the holder)
`auto.onboarding.phase_changed`	An onboarding run advances	—
`auto.connection.authorization_attempt.finished`	A session-started OAuth attempt ends	platform-held; not authorable

For provider events see GitHub events, Slack events, and Linear events; for schedules and custom webhooks see Cron and webhooks.

Get Started

Concepts

Examples

Reference

Lifecycle Events

Apply lifecycle

`auto.project_resource_apply.{started,completed,failed}`

Connection lifecycle

`auto.connection.established` / `auto.connection.removed`

`auto.connection.authorization_attempt.finished` (not authorable)

Session-binding lifecycle

`auto.session.binding.{bound,updated,unbound}`

Onboarding

`auto.onboarding.phase_changed`

Quick reference

​Apply lifecycle

​auto.project_resource_apply.{started,completed,failed}

​Connection lifecycle

​auto.connection.established / auto.connection.removed

​auto.connection.authorization_attempt.finished (not authorable)

​Session-binding lifecycle

​auto.session.binding.{bound,updated,unbound}

​Onboarding

​auto.onboarding.phase_changed

​Quick reference

Apply lifecycle

`auto.project_resource_apply.{started,completed,failed}`

Connection lifecycle

`auto.connection.established` / `auto.connection.removed`

`auto.connection.authorization_attempt.finished` (not authorable)

Session-binding lifecycle

`auto.session.binding.{bound,updated,unbound}`

Onboarding

`auto.onboarding.phase_changed`

Quick reference