Eternet.Agents.Control.Abstractions 2.0.21

Eternet.Agents.Control.Abstractions

Stable contracts for EAC plugin packages.

Plugins reference this package to expose diagnostics, deterministic code fixes, transformers, and guidance without taking a dependency on Eternet.Agents.Control.Core or the eac CLI host.

The package targets netstandard2.0 so repo-local and global plugin packages can stay independent from the host runtime as long as they only use the public abstractions.

Plugin code-fix contracts can declare eligibility metadata, required diagnostic properties, cascade diagnostics, and dry-run plan scope so the host can keep batching, safety gates, and verification host-owned while plugins contribute the domain-specific remediation logic.

Plugin CLI output contracts

Plugin CLI aliases should use the contract that matches the output shape.

• EacPluginCliQueryableOutput is for row-oriented results that benefit from dataset querying. V2 commands should declare a stable DefaultDatasetId, bounded DefaultColumns, and any MaxTop or cache hints the host needs to keep the default response compact.
• EacPluginCliNonQueryableOutput is for bounded summary or preview results. Use preview only when the contract has an explicit positive preview item limit.
• If a command really needs nested-object summary / page / full behavior, keep that behavior on a host-owned disclosure surface instead of trying to overload plugin dataset flags. full still means the richest bounded page, not an unlimited inline payload.

The paging families are intentionally separate:

• disclosure and simple list paging use --skip / --take;
• dataset querying uses --dataset, --select, --filter, --orderby, --skip, and --top;
• --top is not a disclosure alias, and --take is not a dataset alias.
• host-owned alias options stay reserved in plugin manifests: do not declare or shadow --workspace, --format, --apply, --detail, --search, --skip, --take, --dataset, --select, --filter, --orderby, --top, --count, --persist-result, or --result-id.
• host-side output normalization does not require plugin-side changes as long as the plugin remains ABI-compatible with the installed EAC CLI and abstractions package. ABI mismatch errors still require rebuilding and reinstalling the plugin against the current package.
• when one inline page still exceeds the budget, the host emits bounded budgetInfo / partialInfo, continuation hints, and artifact references instead of the raw oversized payload body.

EacPluginRenderHints remains the DTO for compact dataset previews: default dataset id, default columns, preview row count, and preferred renderer hints all stay explicit in the contract.

Guidance provider content

IEacGuidanceProvider returns full EacGuidanceDocument instances, and the host derives section metadata from ContentMarkdown. Guidance providers should therefore author stable section markers inside the markdown instead of assuming callers will always load the entire document or bypass paging with a legacy flag.

Recommended marker shape:

## Quick Start

Guidance packs should keep section ids stable, provide summaries for migrated sections, and use lowercase comma-separated tags. The host then keeps guidance search and guidance toc metadata-first, guidance show compact by default, and guidance show --detail full as the richest projection for the current bounded page. Legacy guidance show --full remains a compatibility alias for the same bounded behavior.

Workspace edit contracts

IEacWorkspaceEditProvider is the preferred additive contract for providers that can describe repository edits without writing files directly.

• BuildEditSetAsync(...) returns an EacWorkspaceEditSet with concrete TextEdits and DeleteEdits collections so the contract stays DTO-only and round-trips cleanly for netstandard2.0 consumers.
• RelativePath values are workspace-relative paths only. Providers should not emit rooted paths or paths that escape the workspace.
• ExpectedOriginalContentHashSha256 is an optional optimistic-concurrency token for the original file text before Core applies the edit.
• EacCodeFixApplicationResult.WorkspaceMutation carries authoritative mutation evidence when the host computes it. Legacy ChangedFiles remains available as a compatibility mirror during migration waves.

EacWorkspaceTextOutput remains in the package only as a legacy compatibility helper while the Core-owned mutation boundary and first-party plugin migrations complete. New provider work should prefer IEacWorkspaceEditProvider, and first-party repos now guard new raw System.IO write exceptions with focused policy tests instead of growing new productive EacWorkspaceTextOutput call sites.