Desired-State Resources

Resources are AGH's desired-state layer for runtime objects that must be extensible and agent-manageable. Instead of letting every subsystem invent its own private storage shape, AGH writes canonical resource records, validates their specs through registered codecs, and reconciles them into runtime state.

Use this page when you need to understand why a tool, MCP server, agent definition, skill, automation job, trigger, bridge instance, or bundle activation can be managed through the same control plane.

Mental model

Rendering diagram...

Desired-state resources pass through validation, storage, and reconcile before they affect runtime subsystems.

Term	Meaning
Kind	Resource family, such as `tool`, `agent`, `automation.job`, or `bundle`.
ID	Stable resource identity inside the kind.
Scope	`global` or `workspace`; workspace scope requires a workspace id.
Owner	Who owns the record, such as daemon control or a bundle activation.
Source	Where the record came from, such as an extension, daemon, or session.
Version	Optimistic mutation version used to prevent blind overwrites.
Spec	Canonical JSON payload for the resource kind.

Registered resource kinds

The daemon registers typed codecs for these resource families at boot:

Kind	Projects into
`hook.binding`	Hook registry bindings.
`tool`	Tool Registry entries.
`mcp_server`	MCP server declarations.
`agent`	Agent catalog definitions.
`skill`	Skill catalog entries.
`automation.job`	Scheduled or claimable automation jobs.
`automation.trigger`	Automation trigger definitions.
`bridge.instance`	Bridge runtime instances.
`bundle`	Extension-provided bundle catalog entries.
`bundle.activation`	Active bundle profiles that project jobs, triggers, bridges, and channels.

Write flow

PUT /api/resources/bundle.activation/release-docs
Content-Type: application/json

{
  "scope": { "kind": "global" },
  "expected_version": 0,
  "spec": {
    "extension_name": "github",
    "bundle_name": "release-workflow",
    "profile_name": "default",
    "bind_primary_channel_default": true
  }
}

What happens:

AGH validates the path kind and id.
AGH validates the scope binding.
If a codec is registered for that kind, AGH canonicalizes the spec.
The record is written with an owner, source, version, and timestamps.
Reconcile is triggered for that kind.

Use expected_version = 0 when creating a new record. Use the returned version on update or delete so stale operators and agents do not overwrite each other silently.

Read and filter

GET /api/resources
GET /api/resources/bundle.activation
GET /api/resources/bundle.activation/release-docs
GET /api/resources/bundle.activation?scope_kind=workspace&scope_id=ws_project

Filters can narrow by kind, scope_kind, scope_id, owner_kind, owner_id, source_kind, source_id, and limit.

Delete

DELETE /api/resources/bundle.activation/release-docs
Content-Type: application/json

{ "expected_version": 3 }

Deletes also trigger reconcile for the kind. If the resource was owned by a bundle activation, remove or update the activation instead of deleting the projected child record by hand.

Failure guide

Symptom	Likely cause	First check
`400` on write	The request body is malformed JSON or cannot be decoded.	Response body and submitted payload.
`422` on write	Invalid kind, scope binding, missing codec, or codec spec validation.	Response body and kind-specific docs.
`409` on update/delete	`expected_version` is stale.	`GET /api/resources/:kind/:id` for the current version.
Record exists but runtime did not change	Reconcile failed or is degraded.	Observe resource/reconcile health and daemon logs.
Projected record reappears	A bundle activation or extension owns it.	`owner` and `source` fields on the resource record.
Workspace write fails	`scope.id` does not name a valid workspace.	`agh workspace list -o json`.

Bundles explains the bundle activation layer built on top of resources.
Extensions explains how installed packages publish resource records.
API Reference lists the current resource and bundle route families.