Bundles

Bundles are extension-provided presets. A bundle catalog record describes what an extension can provide; a bundle activation chooses one profile and asks AGH to project its runtime resources.

Use bundles when a feature should install as a coherent unit: channels, automation jobs, triggers, and bridge instances that make sense together.

Activation flow

Rendering diagram...

Bundle activation projects one extension profile into runtime resources and optional network defaults.

Object	What it does
Bundle catalog	Lists extension bundles and profiles available for activation.
Bundle profile	Chooses channels, jobs, triggers, and bridges inside one bundle.
Bundle activation	Records one active profile at global or workspace scope.
Inventory	Lists the resources AGH projected from the activation.
Network settings	Reports declared channels and the effective default network channel.

Operator routes

GET /api/bundles/catalog
POST /api/bundles/preview
GET /api/bundles/activations
POST /api/bundles/activations
GET /api/bundles/activations/:id
PATCH /api/bundles/activations/:id
DELETE /api/bundles/activations/:id
GET /api/bundles/network/settings

These routes are available over HTTP and UDS. The generated OpenAPI file is still catching up to the full bundle surface, so treat this page and the API route map as the release-truth source for bundle route families.

Preview before activation

POST /api/bundles/preview
Content-Type: application/json

{
  "extension_name": "github",
  "bundle_name": "release-workflow",
  "profile_name": "default",
  "scope": "workspace",
  "workspace": "project",
  "bind_primary_channel_as_default": true
}

Preview returns the activation payload AGH would create: channels, jobs, triggers, bridges, and inventory. It does not mutate the runtime.

Activate a profile

POST /api/bundles/activations
Content-Type: application/json

{
  "extension_name": "github",
  "bundle_name": "release-workflow",
  "profile_name": "default",
  "scope": "workspace",
  "workspace": "project",
  "bind_primary_channel_as_default": true
}

Activation creates or updates a bundle.activation resource. Reconcile then projects the owned automation and bridge resources. The response includes the stable activation id and projected inventory so operators can audit what changed.

Scope and default channel rules

Rule	Behavior
Global activation	Applies without a workspace id.
Workspace activation	Requires a workspace id resolved from the `workspace` request field.
Primary channel binding	Can make the profile's primary channel the effective default channel.
Default channel conflict	Only one active activation can claim the effective default at a time.
Extension dependency	The bundle must still exist in the installed extension catalog.

Deactivation

DELETE /api/bundles/activations/act_123

Deactivation removes the activation and lets reconcile remove the owned projected resources. Remove bundle activations before disabling or removing the extension that owns them.

Failure guide

Symptom	Likely cause	First check
`404` on preview or activation	Extension, bundle, profile, or workspace missing.	`GET /api/bundles/catalog` and workspace list.
`409` on activation	Another activation claimed the default channel.	`GET /api/bundles/network/settings`.
Activation exists but resources are absent	Reconcile failed after writing the activation.	Activation inventory and daemon resource health.
Extension cannot be disabled	Active bundle activations still depend on it.	`GET /api/bundles/activations`.
Projected job or bridge should change	Bundle profile changed or activation is stale.	Preview the activation, then update/reactivate.

Extensions explains install, enable, disable, and removal constraints.
Automation explains jobs and triggers after projection.
Bridges explains bridge instances after projection.