Agents Plugin

Machine-readable readiness/discovery API and governed control-plane plugin for Craft CMS and Commerce.

Current plugin version: 0.3.9

Purpose

This plugin gives external/internal agents a stable interface for:

• health checks for automation (/agents/v1/health)
• readiness summaries (/agents/v1/readiness)
• auth introspection for token diagnostics (/agents/v1/auth/whoami)
• product snapshot browsing (/agents/v1/products)
• control policies/approvals/execution ledger/audit (/agents/v1/control/*)
• read-only CLI discovery commands (craft agents/*)

The API now includes:

• read surfaces for diagnostics and discovery
• sign-and-control primitives for governed machine actions:
  • policy evaluation
  • approval gates
  • idempotent execution ledger
  • immutable audit events

It also exposes proposal-oriented discovery files at root-level endpoints:

• GET /llms.txt
• GET /commerce.txt

Installation

Requirements:

• PHP ^8.2
• Craft CMS ^5.0

After Plugin Store publication:

composer require klick/agents:^0.3.9
php craft plugin/install agents

For monorepo development, the package can also be installed via path repository at plugins/agents.

Recommended local workflow:

• develop in a dedicated Craft sandbox (not production-bound project roots)
• link plugin via local Composer path repo only in that sandbox
• use the scripted bootstrap/fixture/smoke/release steps in DEVELOPMENT.md
• restore production-bound projects to store-backed versions after local debugging

Configuration

Environment variables:

• PLUGIN_AGENTS_ENABLED (true/false)
• PLUGIN_AGENTS_API_TOKEN (required when token enforcement is enabled)
• PLUGIN_AGENTS_API_CREDENTIALS (JSON credential set with optional per-credential scopes)
• PLUGIN_AGENTS_REQUIRE_TOKEN (default: true)
• PLUGIN_AGENTS_ALLOW_INSECURE_NO_TOKEN_IN_PROD (default: false, keep false)
• PLUGIN_AGENTS_ALLOW_QUERY_TOKEN (default: false)
• PLUGIN_AGENTS_FAIL_ON_MISSING_TOKEN_IN_PROD (default: true)
• PLUGIN_AGENTS_TOKEN_SCOPES (comma/space list, default scoped read set)
• PLUGIN_AGENTS_REDACT_EMAIL (default: true, applied when sensitive scope is missing)
• PLUGIN_AGENTS_RATE_LIMIT_PER_MINUTE (default: 60)
• PLUGIN_AGENTS_RATE_LIMIT_WINDOW_SECONDS (default: 60)
• PLUGIN_AGENTS_WEBHOOK_URL (optional HTTPS endpoint for change notifications)
• PLUGIN_AGENTS_WEBHOOK_SECRET (required when webhook URL is set; used for HMAC signature)
• PLUGIN_AGENTS_WEBHOOK_TIMEOUT_SECONDS (default: 5)
• PLUGIN_AGENTS_WEBHOOK_MAX_ATTEMPTS (default: 3, max queue retry attempts)
• PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL (default: false; enables refund-approval/control surfaces)

These are documented in .env.example.

Enablement precedence:

• If PLUGIN_AGENTS_ENABLED is set, it overrides CP/plugin setting state.
• If PLUGIN_AGENTS_ENABLED is not set, CP/plugin setting enabled controls runtime on/off.

Support

• Docs: https://github.com/klick/agents
• Issues: https://github.com/klick/agents/issues
• Source: https://github.com/klick/agents

API Access

By default, v1 routes require token-based access (PLUGIN_AGENTS_REQUIRE_TOKEN=true). Fail-closed behavior in production is enabled by default (PLUGIN_AGENTS_FAIL_ON_MISSING_TOKEN_IN_PROD=true). If PLUGIN_AGENTS_REQUIRE_TOKEN=false is set in production, the plugin will still enforce token auth unless PLUGIN_AGENTS_ALLOW_INSECURE_NO_TOKEN_IN_PROD=true is explicitly enabled.

Credential sources:

• PLUGIN_AGENTS_API_CREDENTIALS (strict JSON credential objects with per-credential scopes)
• PLUGIN_AGENTS_API_TOKEN (legacy single-token fallback)
• Control Panel managed credentials (API Keys tab: create/edit scopes/rotate/revoke/delete with last-used metadata)

Managed credentials are stored in plugin DB tables and participate in runtime auth alongside env credentials.

Credential lifecycle permission keys (CP):

• agents-viewCredentials
• agents-manageCredentials (create + edit scopes/display name)
• agents-rotateCredentials
• agents-revokeCredentials
• agents-deleteCredentials

Control-plane permission keys (CP):

• agents-viewControlPlane
• agents-manageControlPolicies
• agents-manageControlApprovals
• agents-executeControlActions

Supported token transports:

• Authorization: Bearer <token> (default)
• X-Agents-Token: <token> (default)
• ?apiToken=<token> only when PLUGIN_AGENTS_ALLOW_QUERY_TOKEN=true

Example credential JSON:

[
  {"id":"integration-a","token":"token-a","scopes":["health:read","readiness:read","products:read"]},
  {"id":"integration-b","token":"token-b","scopes":"orders:read orders:read_sensitive"}
]

Object-map credential JSON is also supported:

{
  "integration-a": {"token":"token-a","scopes":["health:read","readiness:read"]},
  "integration-b": {"token":"token-b","scopes":"orders:read orders:read_sensitive"}
}

Validation notes:

• Single-object shape is accepted when it includes token (or value) and optional id/scopes.
• Scalar values in keyed-object mode are ignored to avoid accidental token expansion from malformed JSON.

Endpoints

Base URL (this project): /agents/v1

Read/discovery endpoints:

• GET /health
• GET /readiness
• GET /auth/whoami
• GET /products
• GET /orders
• GET /orders/show (requires exactly one of id or number)
• GET /entries
• GET /entries/show (requires exactly one of id or slug)
• GET /changes
• GET /sections
• GET /capabilities
• GET /openapi.json

Control-plane endpoints (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true):

• GET /control/policies
• POST /control/policies/upsert
• GET /control/approvals
• POST /control/approvals/request
• POST /control/approvals/decide
• GET /control/executions
• POST /control/actions/execute
• GET /control/audit

Root-level discovery files:

• GET /llms.txt (public when enabled)
• GET /commerce.txt (public when enabled)
• Discovery aliases:
  • GET /capabilities -> GET /agents/v1/capabilities
  • GET /openapi.json -> GET /agents/v1/openapi.json

Scope catalog

Read scopes:

• health:read
• readiness:read
• auth:read
• products:read
• orders:read
• orders:read_sensitive
• entries:read
• entries:read_all_statuses
• changes:read
• sections:read
• capabilities:read
• openapi:read
• control:policies:read (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:approvals:read (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:executions:read (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:audit:read (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)

Write scopes:

• control:policies:write (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:approvals:request (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:approvals:decide (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:approvals:write (legacy combined scope, backward-compatible; only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
• control:actions:execute (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)

CLI Commands

Craft-native command routes:

• craft agents/product-list
• craft agents/order-list
• craft agents/order-show
• craft agents/entry-list
• craft agents/entry-show
• craft agents/section-list
• craft agents/discovery-prewarm
• craft agents/auth-check
• craft agents/discovery-check
• craft agents/readiness-check
• craft agents/smoke

Examples:

# Product discovery (text output)
php craft agents/product-list --status=live --limit=10

# Product discovery (JSON output)
php craft agents/product-list --status=all --search=emboss --limit=5 --json=1

# Low stock view
php craft agents/product-list --low-stock=1 --low-stock-threshold=10 --limit=25

# Orders from last 14 days
php craft agents/order-list --status=shipped --last-days=14 --limit=20

# Show a single order
php craft agents/order-show --number=A1B2C3D4
php craft agents/order-show --resource-id=12345

# Entries
php craft agents/entry-list --section=termsConditionsB2b --status=live --limit=20
php craft agents/entry-show --slug=shipping-information
php craft agents/entry-show --resource-id=123

# Sections
php craft agents/section-list

# Prewarm llms.txt + commerce.txt cache
php craft agents/discovery-prewarm
php craft agents/discovery-prewarm --target=llms --json=1

# Auth posture check
php craft agents/auth-check
php craft agents/auth-check --strict=1 --json=1

# Discovery/readiness/smoke checks
php craft agents/discovery-check --json=1
php craft agents/readiness-check --json=1
php craft agents/smoke --json=1

CLI output defaults to human-readable text. Add --json=1 for machine consumption.

Identifier notes for show commands:

• agents/order-show: use exactly one of --number or --resource-id.
• agents/entry-show: use exactly one of --slug or --resource-id.

Products endpoint parameters

• q (search text)
• status (live|pending|disabled|expired|all, default live)
• sort (updatedAt|createdAt|title, default updatedAt)
• limit (1..200, default 50)
• cursor (opaque cursor; legacy pagination + incremental continuation)
• updatedSince (RFC3339 timestamp bootstrap for incremental mode, for example 2026-02-24T12:00:00Z)

Orders endpoint parameters

• /orders: status (handle or all), lastDays (default 30), limit (1..200)
• /orders incremental: cursor (opaque), updatedSince (RFC3339). When incremental params are used and lastDays is omitted, the default window is 0 (no date-created cutoff).
• /orders/show: exactly one of id or number

Entries endpoint parameters

• /entries: section, type, status, search (or q), limit (1..200)
• /entries incremental: cursor (opaque), updatedSince (RFC3339)
• /entries/show: exactly one of id or slug; optional section when using slug

Changes endpoint parameters

• /changes: types (optional comma list: products,orders,entries), updatedSince (RFC3339 bootstrap), cursor (opaque continuation), limit (1..200)
• /changes returns normalized data[] items with:
  • resourceType (product|order|entry)
  • resourceId (string)
  • action (created|updated|deleted)
  • updatedAt (RFC3339 UTC)
  • snapshot (minimal object for created|updated, null for deleted tombstones)

Control endpoint parameters and behavior

• POST /control/policies/upsert body:
  • handle (required)
  • actionPattern (required, wildcard-compatible)
  • displayName, riskLevel, enabled, requiresApproval, config
• GET /control/approvals query: status, actionType, limit
• POST /control/approvals/request body:
  • actionType (required)
  • actionRef, reason, payload, metadata
  • metadata.source, metadata.agentId, metadata.traceId are required (agent provenance)
  • idempotency via X-Idempotency-Key header (or idempotencyKey body field)
• POST /control/approvals/decide body:
  • approvalId (required)
  • decision (approved|rejected)
  • decisionReason
• GET /control/executions query: status, actionType, limit
• POST /control/actions/execute body:
  • actionType (required)
  • idempotencyKey (required, header or body)
  • actionRef, approvalId, payload
  • response may include idempotentReplay=true when the key was already processed
• GET /control/audit query: category, actorId, limit

Incremental sync rules

• cursor takes precedence over updatedSince when both are provided.
• Incremental mode uses deterministic ordering: updatedAt, then id.
• Incremental responses include page.syncMode=incremental, page.hasMore, page.nextCursor, and snapshot window metadata.
• Cursor tokens are opaque and may expire; restart from a recent updatedSince checkpoint if needed.
• /changes cursor continuity also preserves the selected types filter.
• Invalid updatedSince/cursor inputs return 400 INVALID_REQUEST with stable error payload fields.

Webhook Delivery

Webhook notifications are optional and are enabled only when both PLUGIN_AGENTS_WEBHOOK_URL and PLUGIN_AGENTS_WEBHOOK_SECRET are configured.

Behavior:

• Events are queued asynchronously on product|order|entry create/update/delete changes.
• Event payload mirrors /changes items: resourceType, resourceId, action, updatedAt, snapshot.
• Retry behavior uses queue retries up to PLUGIN_AGENTS_WEBHOOK_MAX_ATTEMPTS.
• Variant changes are emitted as product updated events.

Request headers:

• X-Agents-Webhook-Id: unique event id
• X-Agents-Webhook-Timestamp: unix timestamp
• X-Agents-Webhook-Signature: sha256=<hex hmac>

Signature verification:

• signed string: <timestamp>.<raw-request-body>
• algorithm: HMAC-SHA256
• secret: PLUGIN_AGENTS_WEBHOOK_SECRET

Queue note:

• Webhooks are delivered by Craft queue workers; ensure php craft queue/run or php craft queue/listen is active in environments where webhook delivery is required.

Discoverability endpoints

• /capabilities: machine-readable list of supported endpoints + CLI commands.
• /openapi.json: OpenAPI 3.1 descriptor for this API surface.

Discovery file behavior:

• llms.txt / commerce.txt are generated dynamically as plain text.
• They include ETag + Last-Modified headers and support 304 Not Modified.
• Output is cached and invalidated on relevant content/product updates.

Example:

curl -H "Authorization: Bearer $PLUGIN_AGENTS_API_TOKEN" \
  "https://example.com/agents/v1/products?status=live&sort=title&limit=2"

Response style

• JSON only
• All API responses include X-Request-Id.
• Guarded JSON/error responses set Cache-Control: no-store, private.
• Products response includes:
  • data[] with minimal product fields (id, title, slug, status, updatedAt, url, etc.)
  • page with nextCursor, limit, count
• Changes response includes:
  • data[] normalized change items (resourceType, resourceId, action, updatedAt, snapshot)
  • page with nextCursor, hasMore, limit, count, updatedSince, snapshotEnd
• Health/readiness include plugin, environment, and readiness score fields.
• Error responses use a stable schema:

{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid token.",
  "status": 401,
  "requestId": "agents-9fd2b20abec4a65f"
}

Security and reliability

• Rate limiting headers are returned on each guarded request:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
• Rate limiting is applied before and after auth checks to throttle invalid-token attempts.
• Exceeded limits return HTTP 429 with RATE_LIMIT_EXCEEDED.
• Missing/invalid credentials return HTTP 401.
• Missing required scope returns HTTP 403 with FORBIDDEN.
• Read/discovery endpoints are GET/HEAD only.
• Control-plane write endpoints accept POST and are token-authenticated API actions.
• Misconfigured production token setup returns HTTP 503 with SERVER_MISCONFIGURED.
• Disabled runtime state returns HTTP 503 with SERVICE_DISABLED.
• Invalid request payload/params return HTTP 400 with INVALID_REQUEST.
• Missing resource lookups return HTTP 404 with NOT_FOUND.
• Unexpected server errors return HTTP 500 with INTERNAL_ERROR.
• Query-token auth is disabled by default to reduce token leakage risk.
• Credential parsing is strict for PLUGIN_AGENTS_API_CREDENTIALS (credential objects only) and ignores malformed scalar entries.
• Sensitive order fields are scope-gated; email is redacted by default unless orders:read_sensitive is granted.
• Entry access to non-live statuses is scope-gated by entries:read_all_statuses.
• Endpoint is not meant for frontend/public user flows; token is the intended control plane.

Note: llms.txt and commerce.txt are public discovery surfaces and are not guarded by the API token.

Troubleshooting Flow

1. Capture X-Request-Id from the failing response.
2. Confirm the error status + error code pair.
3. Match the code to the fix path:
   • UNAUTHORIZED (401): token missing/invalid or wrong transport.
   • FORBIDDEN (403): token missing required scope.
   • INVALID_REQUEST (400): malformed query or invalid identifier combination.
   • NOT_FOUND (404): requested resource does not exist.
   • METHOD_NOT_ALLOWED (405): endpoint does not support the HTTP method used.
   • RATE_LIMIT_EXCEEDED (429): respect X-RateLimit-* and retry after reset.
   • SERVICE_DISABLED (503): plugin runtime disabled by env/CP setting.
   • SERVER_MISCONFIGURED (503): token/security env configuration invalid.
   • INTERNAL_ERROR (500): unexpected server-side failure.
4. Correlate by X-Request-Id in server logs for root-cause details.

Discovery Text Config (config/agents.php)

These values can be overridden from your project via config/agents.php:

<?php

return [
    'enableLlmsTxt' => true,
    'enableCommerceTxt' => true,
    'llmsTxtCacheTtl' => 86400,
    'commerceTxtCacheTtl' => 3600,
    'llmsSiteSummary' => 'Product and policy discovery for assistants.',
    'llmsIncludeAgentsLinks' => true,
    'llmsIncludeSitemapLink' => true,
    'llmsLinks' => [
        ['label' => 'Support', 'url' => '/support'],
        ['label' => 'Contact', 'url' => '/contact'],
    ],
    'commerceSummary' => 'Commerce metadata for discovery workflows.',
    'commerceCatalogUrl' => '/agents/v1/products?status=live&limit=200',
    'commercePolicyUrls' => [
        'shipping' => '/shipping-information',
        'returns' => '/returns',
        'payment' => '/payment-options',
    ],
    'commerceSupport' => [
        'email' => 'support@example.com',
        'phone' => '+1-555-0100',
        'url' => '/contact',
    ],
    'commerceAttributes' => [
        'currency' => 'USD',
        'region' => 'US',
    ],
];

CP views

• Agents section now uses 3 primary subnav views by default:
  • agents/dashboard/overview (Dashboard)
  • agents/settings (Settings)
  • agents/credentials (API Keys)
• Optional experimental subnav view (enabled via PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true):
  • agents/control (Return Requests)
• Dashboard includes top tabs:
  • Overview (agents/dashboard/overview)
  • Readiness (agents/dashboard/readiness)
  • Discovery (agents/dashboard/discovery)
  • Security (agents/dashboard/security)
• Legacy CP paths remain valid and resolve to Dashboard tabs:
  • agents -> dashboard/overview
  • agents/overview -> dashboard/overview
  • agents/readiness -> dashboard/readiness
  • agents/discovery -> dashboard/discovery
  • agents/security -> dashboard/security
  • agents/health -> dashboard/readiness
• Dashboard/Overview:
  • runtime enabled/disabled state and source (env vs CP setting)
  • env-lock aware runtime toggle
  • quick endpoint links + discovery refresh entrypoint
  • ownership split guidance (CP vs config/agents.php vs .env)
• Dashboard/Readiness:
  • readiness score, criterion breakdown, component checks, warnings
  • health/readiness diagnostic JSON snapshots
• Dashboard/Discovery:
  • read-only llms.txt/commerce.txt status, metadata, preview snippets
  • operator actions: refresh (all|llms|commerce) and clear cache
• Dashboard/Security:
  • read-only effective auth/rate-limit/redaction/webhook posture
  • centralized warning output from shared security policy logic
• Return Requests (agents/control, experimental flag required):
  • queue-first operator flow for requests waiting on human decision
  • clear split between decision queue, runs needing follow-up, and historical activity
  • agent-first model: CP request form is disabled by default
  • optional manual fallback can be enabled in Settings (allowCpApprovalRequests)
  • rule-aware execution guardrails (disabled rule blocks, approval linkage checks)
  • immutable audit trail with optional advanced snapshot JSON
• API Keys:
  • managed credential lifecycle (create/edit scopes/rotate/revoke/delete)
  • one-time token reveal on create/rotate

CP rollout regression checklist

1. Verify Dashboard subnav loads and each top tab (overview, readiness, discovery, security) switches correctly.
2. Verify legacy aliases (agents, agents/overview, agents/readiness, agents/discovery, agents/security, agents/health) still resolve to the expected Dashboard tab.
3. Verify runtime lightswitch is disabled when PLUGIN_AGENTS_ENABLED is set.
4. Verify discovery actions work:
   • refresh all
   • refresh llms
   • refresh commerce
   • clear discovery cache
5. Verify security tab shows posture without exposing token/secret values.
6. When PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true, verify Return Requests flows:
   • create/update policy
   • request approval via API (agent token) with provenance metadata
   • approve/reject approval in CP
   • execute action with idempotency key
   • audit event appears for each state transition
7. Verify API and CLI behavior remains unchanged except expected SERVICE_DISABLED when runtime is off.

Namespace migration

• PHP namespace root is now Klick\\Agents (for example Klick\\Agents\\Plugin).
• Plugin handle stays agents (CP nav, routes, and CLI command prefixes remain unchanged).

Security Rollout Checklist

1. Set PLUGIN_AGENTS_API_TOKEN to a strong secret and keep PLUGIN_AGENTS_REQUIRE_TOKEN=true.
2. Prefer PLUGIN_AGENTS_API_CREDENTIALS for per-integration token/scope separation.
3. Keep PLUGIN_AGENTS_FAIL_ON_MISSING_TOKEN_IN_PROD=true.
4. Keep PLUGIN_AGENTS_ALLOW_INSECURE_NO_TOKEN_IN_PROD=false.
5. Keep PLUGIN_AGENTS_ALLOW_QUERY_TOKEN=false unless legacy clients require it temporarily.
6. Start with default scopes; only add elevated scopes when required:
   • orders:read_sensitive
   • entries:read_all_statuses
   • control:policies:write (experimental flag only)
   • control:approvals:request (experimental flag only)
   • control:approvals:decide (experimental flag only)
   • control:approvals:write (legacy compatibility; experimental flag only)
   • control:actions:execute (experimental flag only)
7. Verify capabilities/openapi.json outputs reflect active auth transport/settings.
8. Run scripts/security-regression-check.sh against your environment before promotion.

Scope Migration Notes

• Prior behavior effectively granted broad read access to any valid token.
• New default scopes intentionally exclude elevated permissions.
• To preserve legacy broad reads temporarily, set:
  • PLUGIN_AGENTS_TOKEN_SCOPES=\"health:read readiness:read products:read orders:read orders:read_sensitive entries:read entries:read_all_statuses changes:read sections:read capabilities:read openapi:read\"
  • If PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true, optionally append control read scopes: control:policies:read control:approvals:read control:executions:read control:audit:read

Secure Deployment Verification

# 1) Missing token should fail
curl -i "https://example.com/agents/v1/health"

# 2) Query token should fail by default
curl -i "https://example.com/agents/v1/health?apiToken=$PLUGIN_AGENTS_API_TOKEN"

# 3) Header token should pass
curl -i -H "Authorization: Bearer $PLUGIN_AGENTS_API_TOKEN" \
  "https://example.com/agents/v1/health"

# 4) Non-live entries should require elevated scope
curl -i -H "Authorization: Bearer $PLUGIN_AGENTS_API_TOKEN" \
  "https://example.com/agents/v1/entries?status=all&limit=1"

# 5) Control policy list (only when PLUGIN_AGENTS_REFUND_APPROVALS_EXPERIMENTAL=true)
curl -i -H "Authorization: Bearer $PLUGIN_AGENTS_API_TOKEN" \
  "https://example.com/agents/v1/control/policies"

# 6) Run local regression script
./scripts/security-regression-check.sh https://example.com "$PLUGIN_AGENTS_API_TOKEN"

Roadmap

Planned improvements include:

• Expanded filtering and pagination controls for existing read-only endpoints.
• Additional diagnostics for operational readiness and integration health.
• Broader OpenAPI coverage and schema detail improvements.
• Optional export/report formats for automation workflows.
• Action-adapter integration for control-plane execution side effects.
• Continued hardening of auth, rate limiting, and observability.

Incremental Sync Contract (v0.2.0)

The formal contract for checkpoint-based sync is documented in INCREMENTAL_SYNC_CONTRACT.md.

Highlights:

• cursor-first continuation semantics with updatedSince bootstrap support.
• Deterministic ordering (updatedAt, then id) and at-least-once replay model.
• Tombstone/delete signaling through GET /agents/v1/changes.