feat: generate Cedar policies from natural language in project add policy

[tejaskash]

What

Extracts project add policy --generate from #2121 per review, as a stacked PR (base: feat/project-add-policy). This PR re-adds exactly what #2121 dropped:

• --generate <text> and --gateway <name> on project add policy: generate the Cedar statement from a natural-language description against the deployed engine and gateway, stream progress, print the generated Cedar and every generation finding, then write the policy into the spec.
• PolicyClient core sub-client (src/core/policy.tsx): resolves the deployed engine and gateway by exact service name (via the shared policyEngineResourceName / gatewayResourceName rules that stay in feat: project add/remove policy-engine and policy with natural-language generation #2121), starts the generation, polls with an injectable delay, surfaces statusReasons and findings on failure, accepts both cedar and Dogwood policy definition members.
• CorePolicyClient consumer-owned interface, TestPolicyClient, and the wiring through Core / CoreClient / handler configs.
• Handler-side fail-fast before the multi-minute generation call: engine exists, policy name unique, gateway resolved from the spec (single gateway inferred, multiple demand --gateway).

Testing

• Unit: PolicyClient tested with a fake at the SDK .send() boundary (pagination, poll exhaustion, GENERATE_FAILED reasons, Dogwood members, findings-only assets); handler flows tested through the real root handler with TestPolicyClient.
• Live e2e in us-west-2 (run while this code was part of feat: project add/remove policy-engine and policy with natural-language generation #2121): --generate "forbid IAM principals from calling any tool on this gateway" --gateway tools against a deployed stack produced real Cedar with a DENY_ALL finding printed; the generated policy deployed to ACTIVE and was removed cleanly.

Follow-up

deployed-state.json (#2105) can replace the list-and-match resolution with a state-file read; kept out of this PR to keep the extraction a pure move.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Nice, self-contained addition. A few observations, none blocking:

• PolicyClient mocks at the AWS SDK boundary via control.send with instanceof-based command dispatch, which matches the existing convention in configBundle.test.ts / gateway.test.ts. No excessive mocking.
• Telemetry is done centrally in src/index.ts at the command-run level, so no per-handler instrumentation is needed here.
• Pre-flight validation in handlers/project/add/policy/index.ts (engine exists, no duplicate policy name, gateway resolvable) correctly happens before the ~minute-long generation call, and the write path is only entered after generatePolicy succeeds — so failed generations don't dirty the project spec (verified in the "fails without writing when generation fails" test).
• Poll budget is 3s × 40 = 120s with a clear "may still complete" exhaustion message; the loop also handles the Dogwood definition.policy variant in addition to definition.cedar.
• The service-name resolution correctly reuses policyEngineResourceName / gatewayResourceName, keeping it in sync with the L3 constructs.

Minor things I noticed but wouldn't block on:

• GetGatewayCommand is called with gatewayIdentifier: deployed.gatewayId without a null check; if the List response ever omitted gatewayId for a matched summary, we'd send undefined. Unlikely in practice.
• With pollDelayMs = 0 in tests, the "polling exhausts while still generating" case executes 40 real send calls back-to-back; fine, just a note.

LGTM.

[tejaskash]

Note on the failing e2e check: it is .github/workflows/e2e-tests.yml running via pull_request_target from the default branch, which assumes main's npm layout (package-lock.json, test-artifacts:* scripts) that the bun-based refactor tree doesn't have. It misfires here only because this PR's base is a feature branch (stacked on #2121), so the refactor-base gating doesn't apply. The real e2e for this tree is the AWS CodeBuild agentcore-e2e check, which passes on #2121. Once #2121 merges and this PR retargets refactor, the proper gating applies.

[tejaskash]

Same applies to the failing pr-tarball check: a default-branch pull_request_target workflow that expects main's npm lockfile. Both misfires resolve when this PR retargets refactor after #2121 merges; the refactor-tree CI (build, unit-test, check, CodeQL, CodeBuild e2e) is what gates this code.

[jariy17]

PAUSE FOR STANDUP ASK:

• This is the first time where we have an add project command calling a core client. How should we introduce this? Also, don't you want to confirm the policy before adding to agentcore.json

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.23%. Comparing base (2595b9d) to head (20de140).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files

@@              Coverage Diff              @@
##           refactor    #2127       +/-   ##
=============================================
- Coverage     97.22%   71.23%   -26.00%     
=============================================
  Files           463      115      -348     
  Lines         28160    10591    -17569     
=============================================
- Hits          27378     7544    -19834     
- Misses          782     3047     +2265     

☔ 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.

[agentcore-devx-automation]

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

[jariy17]

Standup discussion:

• We should just make this imperative command for now. The customers will have to call agentcore policy generate and then customers will copy and paste the cedar policy to agentcore add policy --cedar policy. It's two way door.