feat(add): scaffold runtime docs instead of code in add runtime

[notgitika]

Description

agentcore add runtime stops generating agent code. Users (or their coding agent) write the code; the CLI documents exactly what it needs and keeps agentcore.json in sync with it.

add runtime

• Creates app/<name>/ with README.md and AGENTS.md, rendered for the chosen language and protocol: the expected entry file, the AgentCore runtime contract (ports, /invocations, /ping, /mcp, agent card, session headers), pyproject.toml (uv) / package.json (npm), env vars injected by memory/gateway/credentials, and the container flow. Points to the AgentCore SDKs and samples repo.
• Never overwrites: if app/<name>/ exists, the user's files are kept and only missing docs are added. Rollback only removes files this command wrote (or the folder if it created it). Refuses a folder already owned by another runtime, harness or evaluator.
• Writes a complete runtime entry with starting values: build: CodeZip, latest runtimeVersion for --language, entrypoint main.py / main.js, protocol, plus any infra flags. No dependency install.

dev / build / deploy keep agentcore.json in sync with the code (new ProjectManager.syncRuntimeBuilds, before synth / before starting dev):

• A Dockerfile in the code folder switches the runtime to Container (one-way; a Container runtime whose Dockerfile disappears fails the precheck instead of silently flipping).
• requires-python / engines.node constrain runtimeVersion: an allowed current value is kept; only a version the range excludes is replaced with the highest allowed one. No churn for existing projects (tested for every template, import, harness export and BMA).
• Entrypoint from [tool.agentcore] entrypoint (Python) or package.json "main" (CodeZip TS; only main.ts/main.js honoured since the bundler always builds main.ts, others are warned and ignored).
• Only changed fields are patched in the raw file (unknown fields and key order kept), each change is printed, v0 projects are skipped, and prechecks fail early with a pointer to the runtime's README.

There are no changes in the L3 CDK.

Testing

1. basic add runtime --name flow

And I then went in read the readme and agents.md and told my agent: I want to add myslef a simple runtime agent here in this folder which I can then do local dev and deploy with agentcore cli. I want a bot that answers as though it is in a randomly selected year. use a random tool to calculate an appropriate year. GO!

I confirmed it read the agents.md and used the python SDK and strands.

Then my agent created:

Implemented ChronoBot in main.py (main.py) with dependencies in pyproject.toml (pyproject.toml).

- Random year from 1900–current year, fixed per session
- Bedrock Nova Micro by default; override with MODEL_ID
- AgentCore /ping and /invocations verified
- uv sync, ARM64 dependency resolution, local invocation, and agentcore build passed
- No Dockerfile, secrets, or manual agentcore.json edits

Run it:

agentcore dev --agent realone

Then:

agentcore invoke --runtime realone --local \
  --session-id chronobotlocalsession000000000000001 \
  --payload '{"prompt":"What technology is exciting right now?"}'

Deploy when ready:

agentcore deploy

I tested dev a bunch. Then I changed my requies_python value in pyproject.toml and that also updated the schema. I got this note in dev: realone: runtimeVersion PYTHON_3_14 -> PYTHON_3_12 (requires-python ">=3.10,<3.13" in app/realone/pyproject.toml) and it updated my agentcore.json

Next, changed entrypoint file and also updated:
realone: entrypoint main.py -> app.py ([tool.agentcore] entrypoint in app/realone/pyproject.toml)

deployed and invoke also worked:

[agentcore-devx-automation]

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

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

This is a sizeable but careful refactor. I did a focused pass on the files actually touched by this PR and didn't find anything that needs changing before merge.

Highlights worth calling out positively:

• syncRuntimeBuild in src/core/project/runtimeBuild.ts is well scoped, patches the raw JSON (preserving unknown fields and key order), validates with the Zod schema before writing, and funnels every change through describeChange for consistent CLI output.
• The rollback story in addResource for docs-only runtimes (src/core/project/manager.tsx ~L794–820) correctly distinguishes between "folder existed" and "we created it", tracks written as files are written, and never clobbers user files (skipExisting: true + wx flag in FsTreeNode.write). The ownership check via appFolderOwner prevents collisions with other runtimes/harnesses/evaluators.
• prepareRuntimes aggregates problems across runtimes before throwing — nicer UX than failing on the first bad runtime — and every message points at app/<name>/README.md.
• The hand-rolled TOML parser is intentionally minimal and limited to a documented single-line [tool.agentcore] entrypoint = "..." / [project] requires-python = "..." form. Non-matching shapes (tool.agentcore.entrypoint = ..., agentcore = { ... }) are detected and warned rather than silently ignored.
• The dev file-watcher reentrancy flag (ownWritePending in src/handlers/project/dev/index.ts) is a reasonable fix for the "our own write triggers another reload" cycle; a rapid double external edit could still print one spurious "Reloaded…" line, but that's purely cosmetic.
• Tests in runtimeBuild.test.ts, manager.test.ts ("docs-only runtimes"), and templates/runtime.test.ts use real temp directories (mkdtemp + rm) rather than fs mocks, which matches the repo guidance.

No required changes from me.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 98.36449% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.59%. Comparing base (3fb8f16) to head (a180375).
⚠️ Report is 1 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/core/project/runtimeBuild.ts	98.35%	7 Missing ⚠️
src/core/project/manager.tsx	97.20%	4 Missing ⚠️
src/handlers/project/dev/index.ts	94.11%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2605      +/-   ##
============================================
+ Coverage     96.58%   96.59%   +0.01%     
============================================
  Files           700      702       +2     
  Lines         57639    58290     +651     
============================================
+ Hits          55673    56308     +635     
- Misses         1966     1982      +16     

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

[agentcore-devx-automation]

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