feat(project): add policy-engine and policy TUI wizards

[notgitika]

Description

Adds interactive agentcore add policy-engine and agentcore add policy wizards, the next two screens in the project add wizard series (design doc: https://artifactory.amazon.dev/view/agentcore-project-add-wizard-designs). Built directly on refactor; no stacking.

policy-engine (name → gateways → review)

• name — live-validated against PolicyEngineNameSchema and the deployed <project>_<target>_<name> 48-character cap, checked against the longest declared target, so the step reports the real budget rather than the schema's 48.
• gateways — a checklist of the project's Gateways, skipped entirely when the project has none. Checking one reveals the enforcement mode (enforce default / log-only) beneath the list, which is exactly the --attach-mode requires --attach-to-gateways rule; enter moves from the list into the mode rows, enter again continues. Enter with nothing checked continues without attaching.
• review says (none) · attach from a Gateway later when nothing was picked. Success suggests bare agentcore add policy as the next step, which opens the policy wizard (naming the engine with --engine would select the headless path).

policy (engine → name → source → statement → enforcement → review)

• engine — picked from the project's Policy Engines; the empty state points at agentcore add policy-engine.
• source — "type or paste the Cedar statement" continues to a multi-line editor; "load it from a file" opens a path input in place under that row, validated as an existing readable file before the step advances. A file keeps its provenance: the path is recorded as sourceFile, as --statement file://… does.
• enforcement — active (default) / log-only.
• review shows the inferred authorization phase (INITIATE or RETURN_OUTPUT) with a note that it was inferred, since inferAuthorizationPhase is a substring heuristic and the user should see the guess before it is written. A file-sourced statement is loaded when the review mounts, asynchronously and through SourceResolver (the same strict UTF-8 path as --statement file://…), so a Latin-1 file is refused rather than decoded lossily and nothing reads while the path is typed. SourceResolverConfig.stdin became optional for this file-only use.

Both handlers gain a shared builder (toAddPolicyEngineInput, toAddPolicyInput) that the flags and the wizard call, so both paths bound names, attach Gateways, map modes and infer the phase identically. Flag-only, as designed: --description, --encryption-key-arn, --tags on the engine; --description, --validation-mode, --authorization-phase on the policy.

Related Issue

Closes #

Documentation PR

Not applicable: no flags or help text change.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

• I ran bun test
• I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable — TUI-only change, no deployed resources
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check
• I ran bun run build
• If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them

New screen tests for both wizards: the bare engine matching the flag path byte for byte; attaching to checked Gateways in the revealed mode and the resulting policyEngineConfiguration; enter with nothing checked; up from the mode rows back to the list; name pattern and deployed-name budget; the inline policy with the inferred INITIATE on review; a file-sourced policy recording sourceFile and inferring RETURN_OUTPUT; a missing file kept on the step; a non-UTF-8 file refused on review and on submit; an empty statement refused; a multi-line statement kept as typed; both empty states; rejected adds handing the form back; esc to the menu; and TTY/non-TTY/flag/--json dispatch for each command. Also walked the built bundle in a scratch project.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Consistent with the earlier project add … TUI wizards in this series. The two new screens are cleanly factored, and refactoring both handlers to funnel through shared toAddPolicyEngineInput / toAddPolicyInput builders is a nice change — it guarantees the wizard and the flag path share deployed-name budgeting, gateway attachment shape, mode mapping, and phase inference.

Notes from the review (all minor / non-blocking):

• statementOf in policy/screen.tsx calls readFileSync on every render of the review step (via summaryOf). The file was already validated by readableFileSchema on the source step and is read again asynchronously on submit, so the sync read on render is a small unnecessary cost. A useMemo (or reading once when leaving the source step) would tidy this up, but the file is small/local and the schema keeps unreadable files from getting here, so it's fine as is.
• The wizard shows the inferred authorization phase computed from the readFileSync snapshot on the review, but the submit path re-reads the file async and re-infers before writing. If the file changes between review and submit the value written can differ from the value shown; the "inferred from the statement" label makes this reasonable, and --authorization-phase in the flag path lets users override it. Worth being aware of, not worth changing.
• PolicyEngineInput.description/encryptionKeyArn/tags are declared on the shared type but the wizard never populates them (they are flag-only by design). Consider a shorter wizard-facing type if you want to make that intent explicit, but the current shape is fine and keeps the two callsites symmetric.

Tests exercise real project state via temp directories rather than mocks, cover the interesting compound-field navigation (list ↔ mode focus, unchecking everything, up-from-first-mode-row), the deployed-name budget against the longest target, both file/inline source paths, the empty-engine empty state, and TTY/flag/--json dispatch. LGTM to merge.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.24242% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.26%. Comparing base (773cb64) to head (e161a4a).

Files with missing lines	Patch %	Lines
src/handlers/project/add/policy-engine/screen.tsx	98.29%	4 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2462      +/-   ##
============================================
+ Coverage     97.24%   97.26%   +0.02%     
============================================
  Files           617      619       +2     
  Lines         43848    44334     +486     
============================================
+ Hits          42639    43121     +482     
- Misses         1209     1213       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tejaskash]

[P2] Could we use SourceResolver.resolveText for strict UTF-8 decoding in both submission and preview? A Latin-1 Cedar literal "café" is silently saved as "caf�" here, changing what the policy matches, while the review only shows the filename.

[notgitika]

Done. Both the review and the submit now go through SourceResolver.resolveText("statement", "file://…"), so a Latin-1 file is refused with the resolver's own must contain valid UTF-8 message instead of being decoded lossily. That needed SourceResolverConfig.stdin to become optional (a screen has no injected IO and never resolves -); with it omitted, - is refused. Covered by a new test that writes Latin-1 bytes and checks both the review row and the submit.

[tejaskash]

[P2] Could we validate the path first, then load the statement asynchronously and keep it for the summary? summaryOf(values) runs on every render, so typing a named-pipe path freezes the TUI before Enter or readableFileSchema can reject it.

[notgitika]

Done. The sync read in render is gone. The review step is its own component now, PolicyReview, which loads the statement asynchronously when it mounts — so nothing reads while the path is being typed, and only after readableFileSchema has already accepted it (a FIFO fails isFile() there). The row reads reading <path>… until it resolves, then the inferred phase, or the resolver's error if it fails.

[tejaskash]

[P2] Could we suggest bare agentcore add policy here so it opens the wizard and asks for the engine? Passing --engine selects headless mode, so copying this command fails with required option '--name' not specified, even in a TTY.

[notgitika]

Done: the next step is bare agentcore add policy now, with a comment on why --engine would defeat it. The test asserts the flag is absent.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)