feat: compile-time feature flag for preview/GA consolidation by jesseturner21 · Pull Request #1341 · aws/agentcore-cli

jesseturner21 · 2026-05-21T13:24:33Z

Summary

Consolidates the main and preview branches into a single branch using a compile-time feature flag. npm run bundle now produces two tarballs from the same source:

GA tarball — public customers, all harness features stripped via dead code elimination
Preview tarball — preview customers, full harness functionality enabled

This eliminates the merge-conflict-prone dual-branch workflow while ensuring GA customers never see unreleased features.

Also merges in main-branch work: datasets feature, feedback command, and version 0.15.0.

How it works

src/cli/feature-flags.ts exports isPreviewEnabled() backed by a __PREVIEW__ constant
esbuild's define block replaces __PREVIEW__ with true or false at bundle time
When false, esbuild's minifier eliminates all dead code paths — GA bundles contain zero harness logic
All harness command registrations, TUI screens, deploy paths, and invoke options are gated behind the flag

Changes

Feature flag infrastructure

src/cli/feature-flags.ts — wrapper function for compile-time constant
esbuild.config.mjs — define: { __PREVIEW__: process.env.BUILD_PREVIEW === '1' ? 'true' : 'false' }
vitest.config.ts — matching define for test environments
scripts/bundle.mjs — produces dual tarballs (GA build, then BUILD_PREVIEW=1 rebuild)

Command gating

invoke/command.tsx — 13 harness options (--harness, --harness-arn, --model-id, etc.) conditionally registered
create/command.tsx — 8 harness options (--model-id, --api-key-arn, --truncation-strategy, etc.) conditionally registered
cli.ts — add tool / remove tool commands gated
primitives/registry.ts — harnessPrimitive conditionally instantiated

TUI gating

useCreateFlow.ts — type selector (Harness/Agent/Skip) only shown in preview
useInvokeFlow.ts — harness targets only displayed in preview
dev/command.tsx — harness deploy + invoke flow gated

Imperative deployment (harnesses)

src/cli/operations/deploy/imperative/ — plugin-based deployment manager that runs deployers by phase, separate from CDK pipeline
harness-deployer.ts — creates/updates/deletes harness resources via API
harness-mapper.ts — maps local harness config to API request shape
change-detection.ts — hashes harness config to skip redundant deploys in dev mode

Structured deploy messages

handleDeploy now passes the full DeployMessage object (with code, level, timestamp) instead of plain strings
useDevDeploy hook receives structured messages directly — no more re-wrapping with hardcoded level: 'info'
Enables the TUI to render deploy output with proper severity coloring

Dev mode (harness support)

useDevDeploy hook auto-deploys harnesses before dev server start, with change-detection to skip redundant deploys
Browser UI /api/resources and /api/status endpoints include harness info
harness-invocation.ts routes dev-mode invocations to deployed harness endpoints

Invoke enhancements

resolve-agent-context.ts disambiguates between local agents, deployed agents, and harnesses
--harness / --harness-arn flags for direct harness invocation

Bug fixes (found during testing)

Orphaned memory on harness removal — remove harness now also removes the associated <name>Memory entry
Deploy preflight rejected harness-only projects — added hasHarnesses to the resource check
TUI dev mode skipped deployment — auto-deploy before harness invoke
Deploy-to-harness transition didn't re-render — use queueMicrotask + setMode
Harness teardown on stack destroy — imperative deletion before CFN stack removal
Invoke hint rendering — isHint check after isExec to preserve magenta exec styling
DeployMessage re-wrapping — removed unnecessary string→object→string round-trip in useDevDeploy

Tests

src/cli/__tests__/preview-flag.test.ts — verifies dead code elimination in both builds
integ-tests/add-remove-harness.test.ts — harness lifecycle + memory cleanup + re-add after removal
Unit tests for resolve-agent, change-detection, harness-mapper, harness invocation, status handlers
Harness integration/e2e tests properly skip in GA builds (BUILD_PREVIEW=1 guard)

Reviewer guidance

Feature flag correctness — All harness code paths must be gated behind isPreviewEnabled(). The DCE test validates at the bundle level, but check no harness UI leaks through ungated paths.
Imperative deploy manager — New deployment paradigm alongside CDK. Review the phase/plugin architecture for extensibility and error handling.
Change detection — Dev mode skips deploy if config hash matches. Verify the hash covers all relevant inputs.
Structured DeployMessage — Latest commit changes from string to DeployMessage flowing to the TUI. Check typing is consistent end-to-end.
Schema additions — New harness schemas in src/schema/schemas/primitives/. Check alignment with agentcore.schema.v1.json.

Verification

Scenario	Result
GA: `invoke --help` shows no harness options	✅
GA: `create --help` shows no harness options	✅
GA: `add --help` shows no harness/tool subcommands	✅
GA: `BUILD_PREVIEW=1` env var cannot bypass flag	✅
GA: TUI create goes straight to project name (no type selector)	✅
Preview: full harness TUI wizard	✅
Preview: `agentcore create` project	✅
Preview: `agentcore dev` starts server	✅
Preview: `agentcore dev -b` TUI deploy + dev	✅
Preview: `agentcore deploy` to AWS	✅
Preview: `agentcore invoke` harness	✅
Preview: `agentcore status` shows harness state	✅
Preview: remove harness cleans up memory	✅
Preview: re-add harness after removal	✅
All unit tests pass	✅
All harness integration tests pass (BUILD_PREVIEW=1)	✅
CI: build, lint, format, typecheck, e2e, CodeQL all green	✅

…lidation Replace the dual-branch (main/preview) workflow with a single branch using a compile-time __PREVIEW__ constant. esbuild's define block replaces the constant at build time, enabling dead code elimination for GA builds while keeping all harness/preview code in the same source tree. Key changes: - Add src/cli/feature-flags.ts with isPreviewEnabled() wrapper - Configure esbuild define block and vitest define for __PREVIEW__ - Gate harness commands (add tool, remove tool/harness) behind isPreviewEnabled() - Gate harness UI screens and create flow behind the flag - Add globalThis shim in index.ts for tsx dev mode - Update bundle.mjs to produce dual tarballs (GA + preview) - Support ESBUILD_OUTFILE env var for isolated test builds - Port all harness-related source files from preview branch - Add preview-flag.test.ts verifying dead code elimination

github-actions · 2026-05-21T13:25:35Z

Package Tarball

aws-agentcore-0.15.0.tgz

How to install

gh release download pr-1341-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.15.0.tgz

agentcore-devx-automation · 2026-05-21T13:26:50Z

Claude Security Review: the review run failed before completing. See the run for details.

Prettier requires unquoted object keys when valid identifiers.

agentcore-devx-automation · 2026-05-21T13:30:43Z

Claude Security Review: the review run failed before completing. See the run for details.

github-actions · 2026-05-21T13:31:51Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.65%	10526 / 24112
🔵	Statements	42.89%	11188 / 26085
🔵	Functions	40.53%	1806 / 4455
🔵	Branches	39.81%	6728 / 16900

Generated in workflow #3295 for commit 7141bf7 by the Vitest Coverage Report Action

Harness features are gated behind BUILD_PREVIEW=1 and eliminated from GA bundles. Integration and e2e tests that exercise harness commands must skip when running against the default (GA) build.

agentcore-devx-automation · 2026-05-21T13:40:48Z

Claude Security Review: the review run failed before completing. See the run for details.

…mory cleanup - Wrap harness-related CLI options in invoke command behind isPreviewEnabled() so they don't leak into GA build's --help output - Wrap harness-related CLI options in create command behind isPreviewEnabled() - Fix remove harness leaving orphaned memory entries in agentcore.json - Fix deploy preflight rejecting harness-only projects - Add integration test for harness re-add after removal

The keepNames:true esbuild option (added for better error stacks) preserves class/function name strings even in dead code paths. Adjust assertions to check for harness-only module markers that are fully tree-shaken, rather than name strings that survive. Confidence: high Scope-risk: narrow

agentcore-devx-automation · 2026-05-25T22:26:43Z

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

…rings The dev deploy hook was re-wrapping string messages into DeployMessage objects with hardcoded values. Now the real message (with actual level, code, timestamp) flows through directly from CDK.

agentcore-devx-automation · 2026-05-26T14:12:43Z

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

Includes EPISODIC reflectionNamespaces in the retrieval config so the harness runtime searches all relevant memory namespaces at inference time. Also incorporates memorySpec into the deploy hash so namespace changes trigger a harness update. Cherry-picked from #1374.

agentcore-devx-automation · 2026-05-26T15:40:04Z

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

agentcore-devx-automation · 2026-05-26T18:13:23Z

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

…actor The merge conflict resolution left duplicated code blocks and mismatched braces. Rebuilt from main's withCommandRunTelemetry+recorder pattern and re-applied preview feature flag gates (harness support, skip-deploy, TUI picker).

agentcore-devx-automation · 2026-05-26T18:21:15Z

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

jariy17

.

jariy17

Looks good overall. only blocker is workflow bugs.

- Remove unnecessary `as unknown as` cast in agentcore-control.ts (SDK already has IndexedKey type) - Optimize preview build to only re-run esbuild (not full tsc + assets) - Delete dead code: poll.ts and its test (nothing imports it) - Error when harness enters FAILED state after create/update instead of silently returning success - Add unit tests for harness-deployer (create, update, skip, teardown, FAILED status, role resolution, retry, polling)

agentcore-devx-automation · 2026-05-26T20:42:35Z

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

- release.yml: set BUILD_PREVIEW=1 for preview builds - release-main-and-preview.yml: rewrite as single-PR flow using preview-version.json for the preview version track (no separate preview branch needed) - Remove sync-preview.yml (no preview branch to sync) - Update preview-version.json to match current npm state (1.0.0-preview.9) Constraint: preview and GA are both built from main, differentiated by BUILD_PREVIEW env var at esbuild time Confidence: high Scope-risk: narrow

agentcore-devx-automation · 2026-05-26T20:56:53Z

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

Allows running the release workflow for just main-only, preview-only, or both together. Jobs are conditionally skipped based on the selection. Confidence: high Scope-risk: narrow

agentcore-devx-automation · 2026-05-26T21:07:27Z

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

Allows triggering the release workflow from any branch via the GitHub UI branch selector, instead of hardcoding main. Confidence: high Scope-risk: narrow

agentcore-devx-automation · 2026-05-26T21:13:53Z

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

Preview releases are handled by release-main-and-preview.yml. Confidence: high Scope-risk: narrow

agentcore-devx-automation · 2026-05-26T21:23:22Z

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

jariy17

LGTM

jesseturner21 requested a review from a team May 21, 2026 13:24

github-actions Bot added the size/xl PR size: XL label May 21, 2026

jesseturner21 had a problem deploying to e2e-testing May 21, 2026 13:24 — with GitHub Actions Failure

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

github-actions Bot added the agentcore-harness-reviewing AgentCore Harness review in progress label May 21, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

fix: remove unnecessary quotes around __PREVIEW__ key in esbuild config

5f909ee

Prettier requires unquoted object keys when valid identifiers.

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels May 21, 2026

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

jesseturner21 had a problem deploying to e2e-testing May 21, 2026 13:29 — with GitHub Actions Failure

github-actions Bot removed the agentcore-harness-reviewing AgentCore Harness review in progress label May 21, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

fix: skip harness integration and e2e tests in GA builds

9808478

Harness features are gated behind BUILD_PREVIEW=1 and eliminated from GA bundles. Integration and e2e tests that exercise harness commands must skip when running against the default (GA) build.

github-actions Bot removed the size/xl PR size: XL label May 21, 2026

jesseturner21 temporarily deployed to e2e-testing May 21, 2026 13:38 — with GitHub Actions Inactive

github-actions Bot added the size/xl PR size: XL label May 21, 2026

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

github-actions Bot added size/xl PR size: XL and removed size/xl PR size: XL labels May 21, 2026

jesseturner21 temporarily deployed to e2e-testing May 21, 2026 15:45 — with GitHub Actions Inactive

agentcore-devx-automation Bot added the claude-security-reviewing Claude Code /security-review in progress label May 21, 2026

fix: pass structured DeployMessage through to TUI instead of plain st…

bcb1020

…rings The dev deploy hook was re-wrapping string messages into DeployMessage objects with hardcoded values. Now the real message (with actual level, code, timestamp) flows through directly from CDK.

Merge branch 'main' into feature/preview-feature-flag

59dba1c

jariy17 reviewed May 26, 2026

View reviewed changes

Comment thread src/cli/aws/agentcore-control.ts Outdated

Comment thread src/cli/aws/agentcore-harness.ts

Comment thread scripts/bundle.mjs

jariy17 mentioned this pull request May 26, 2026

Change detection skips Dockerfile changes in dev mode #1380

Open

jariy17 reviewed May 26, 2026

View reviewed changes

Comment thread src/cli/aws/poll.ts Outdated

Comment thread src/cli/aws/api-client.ts

This was referenced May 26, 2026

Add unit tests for HarnessDeployer #1381

Closed

Partial deploy failure loses harness state — can create duplicate resources #1382

Open

jariy17 requested changes May 26, 2026

View reviewed changes

jesseturner21 mentioned this pull request May 26, 2026

Migrate harness CRUD to SDK commands and remove api-client.ts #1383

Open

feat: add release_target input to select main, preview, or both

6b45ebc

Allows running the release workflow for just main-only, preview-only, or both together. Jobs are conditionally skipped based on the selection. Confidence: high Scope-risk: narrow

fix: use github.ref_name for release branch selection

98052fb

Allows triggering the release workflow from any branch via the GitHub UI branch selector, instead of hardcoding main. Confidence: high Scope-risk: narrow

chore: remove unused BUILD_PREVIEW env from release.yml

7141bf7

Preview releases are handled by release-main-and-preview.yml. Confidence: high Scope-risk: narrow

jariy17 approved these changes May 26, 2026

View reviewed changes

jesseturner21 mentioned this pull request May 26, 2026

fix(ci): upload both GA and preview tarballs in prerelease workflow #1386

Merged

5 tasks

Conversation

jesseturner21 commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Changes

Feature flag infrastructure

Command gating

TUI gating

Imperative deployment (harnesses)

Structured deploy messages

Dev mode (harness support)

Invoke enhancements

Bug fixes (found during testing)

Tests

Reviewer guidance

Verification

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package Tarball

How to install

Uh oh!

agentcore-devx-automation Bot commented May 21, 2026

Uh oh!

agentcore-devx-automation Bot commented May 21, 2026

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

agentcore-devx-automation Bot commented May 21, 2026

Uh oh!

agentcore-devx-automation Bot commented May 25, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

jariy17 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jariy17 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

agentcore-devx-automation Bot commented May 26, 2026

Uh oh!

jariy17 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

jesseturner21 commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading

jariy17 left a comment •

edited

Loading