Ansible/scripts/docs/ADDON_AGENTS.md

AIM add-on development contract

Core 3.3.0rc8; service/wire/event 1.0 (stable additive 1.x); Ansible Core 2.19.11. AIM is the independently usable Source of Truth. Add-ons own presentation, sessions, authorization at their application boundary, approvals, queues and persistence. They never patch Core, scrape terminal output or duplicate inventory/execution rules.

Integration sequence

Use aim.services.v1 or one aimctl request process per JSON-lines request. Discover capabilities, current customers/hosts/hierarchy and catalog. Prepare explicit hosts and declared options, show the normalized request and result contract for review, check readiness under the actual worker identity, acquire a worker slot, collect fresh credentials, and execute using the prepared revision. A stale revision requires review. Omit unchanged options to preserve inventory/role-default precedence.

The published API is in scripts/docs/ADDON_API.md; the complete new result contract is in scripts/docs/OPERATION_RESULTS.md. Current support and qualification are in ADDON_SUPPORT.md and VALIDATION.md. Never infer feature support from product version alone. capabilities.collection_baselines declares collection floors that add-on installers/operators must satisfy; Core does not upgrade them. Unknown optional response fields may be ignored; unknown errors fail safely.

Purposeful output: new in this candidate

Check capabilities.operation_results. Catalog result is null or a declaration with schema, scope, required flag, limits and resolved data_schema. No new execute request field is needed. Reports are available in summary and detail mode through the final RunResult.operation_result and the existing final result event. There is no new raw stdout event. Parse final JSON without scraping PLAY/TASK text or debug bodies.

A result contains hosts[host] with status, schema, data, error, plus optional global. Render data only when status is available. Missing/withheld/invalid/null is not an empty valid report. complete means all declared report slots arrived and passed validation; it does not mean the operation succeeded. Partial native runs can contain useful data from successful or failed targets. Preserve overall status/stage/exit, remote_work_may_have_started, target summary and report availability as separate facts. Never automatically retry a result_validation failure: remote changes may be complete.

Use a generic bounded JSON/table renderer for unknown schemas, with optional richer views for known schemas. Escape text/HTML/Rich markup. Do not treat null versions as zero, pending updates as installed, excluded services as failed starts, or redacted configuration values as absent settings. Config reports expose sections but redact recognized secret/command fields; restrict report visibility and retention accordingly.

Safety and identity

Core checks active OS group membership and filesystem access. This is same-UID local execution, not per-browser-user RBAC or an untrusted-tenant sandbox. The execution account owns its 0600 keys and private staging. service_user is not a local UID switch. runtime.private_key_owner affects new keys only. Do not relax permissions, export keys, add generic sudo wrappers or run the web frontend as root to bypass the boundary.

Hardened service installers must provision both applicable staging locations (process HOME and passwd home) and narrow ReadWritePaths exceptions. Retain ProtectHome/read-only, ProtectSystem/strict and private tmp protections. Run aimctl staging-check inside the actual sandbox. Core does not create accounts, modify units or restart add-on services.

Use OneRunCredentials or a private inherited FD, never passwords in request JSON, argv, environment, URLs, logs, queue records or databases. Queue plans, not secrets. Fresh credentials are required for each attempt. Password inputs are native defaults, not Custom overrides or proof of password-only authentication. Cross-UID execution is not provided by Core; independently managed executors must already have authorized access.

Progress and final outcomes

progress_mode: detail is negotiated before preparation. Correlate play/task IDs, handle withheld names and fixed error hints, and ignore anonymous progress to avoid duplicate rows. Keep bounded queues and responsive sinks. Raw module/exception/debug output remains unsupported. Purposeful data is a separate final schema, not an expansion of host_result. Target outcomes come from Core's final native per-host stats, not task counts. An interrupted/incomplete stream must not become partial success by inference.

Ownership and handoff

Core and add-ons release independently. Core deployment preserves add-on code/state, operator aim.yml, inventories, Vaults and keys; add-ons preserve Core in return. Use ZIP + checksum + the deployer, not Git or patches. Coordinate active jobs before source replacement. Only documented retired Core files are removed on upgrade.

The nine current report schemas are documented in OPERATION_RESULTS.md and advertised by the catalog. This candidate has local regression coverage, not new managed-host certification. Record independent acceptance under your actual identity/sandbox/runtime. Request new schemas/capabilities from Core instead of adding private output workarounds.

OS patch-wave presentation (3.3.0rc8)

Patch options remain catalog-driven. Interfaces should render the advertised reboot message/delay and the Windows-only os_patching_rescan_after_reboot option. Its catalog default is false; do not silently enable "fully patch" behavior in an add-on.

Windows submits the current selected categories as one native win_updates wave with module-managed Windows Update sequencing and reboot: false. AIM evaluates reboot policy after the wave returns; it does not expose or own a per-update scheduler. With post-reboot continuation disabled, an AIM-performed reboot can still be a successful Core run while continuation_required: true tells the operator another patch run is needed. remaining_updates_known: false means the client must not invent or persist a next-wave list. If a final read-only search was performed, remaining_updates_known: true makes pending authoritative for that observation only.

Render failed_updates[].reason/message/native_code_hex instead of parsing fatal text or Windows event logs. install_not_allowed deliberately does not mean "reboot required" by itself. If Core reports blocked_reason: preexisting_reboot_required, that is the separate preflight observation. Never auto-enable reboot, post-reboot continuation, or automatic job replay.