release: prepare v0.4.0 HTTP transport release

[marmar9615-cloud]

v0.4.0 implementation PR 3 — release polish + lockstep version bump

• HTTP smoke + CLI surface. Brings the v0.4.0 release line into a
  publishable state. Nothing is published; no git tag, no GitHub
  release. Publishing happens through the existing Trusted
  Publishing workflow only after maintainer approval.

Refs #22.

Predecessor PRs

• #23 — design + ADR
• #24 — transport abstraction (createMcpServer() factory)
• #25 — adopter quickstart + manifest patterns
• #26 — OpenAPI converter regression fixtures (merged before this PR opened)
• #27 — HTTP transport + bearer auth implementation
• (this PR) — release polish

Version bump

Lockstep 0.3.0 → 0.4.0 across:

• root package.json
• packages/{core,sdk,scanner,openapi,cli}/package.json
• apps/{mcp-server,demo-app,studio}/package.json
• workspace dep ranges ^0.3.0 → ^0.4.0
• apps/mcp-server/src/server.ts SERVER_VERSION → "0.4.0"
• package-lock.json refreshed via npm install --package-lock-only
• packages/openapi/README.md "method-based in v0.3.0" → "v0.4.0"

Release artifacts added

• docs/releases/v0.4.0.md — full
  release notes (summary, transport, security posture, env vars,
  stdio compat, Codex / Claude / generic notes, OpenAPI fixtures,
  adopter docs, migration, verification, publishing checklist,
  non-goals, PR links, safety invariants explicitly preserved).
• examples/http-client-config/
  — local-dev recipe, curl smoke (missing/wrong/query-token/
  bad-origin/valid), generic hosted-MCP-client JSON, public-bind
  caution. Placeholder token only; no secrets.
• examples/README.md — adds
  http-client-config row without overwriting PR docs: add adopter quickstart and manifest patterns #25/test(openapi): add converter regression fixtures #26 rows.

HTTP smoke wiring

• scripts/http-mcp-smoke.mjs —
  spawns the dist binary in HTTP mode on an ephemeral port and
  verifies:
  • server starts cleanly + stdout empty,
  • missing Authorization → 401,
  • wrong bearer → 401,
  • token in URL query string → 400 (no token in body),
  • unknown Origin → 403,
  • valid bearer + initialize → 200 with serverInfo {agentbridge, 0.4.0},
  • tools/list never leaks the token,
  • shutdown clean,
  • stderr never contains the token,
  • http mode without auth token fails closed at startup,
  • public bind without origin allowlist fails closed at
    startup.
• package.json exposes npm run smoke:http.
• scripts/external-adopter-smoke.mjs
  runs the HTTP smoke as a final step against the freshly-built
  dist inside the temp snapshot, so npm run smoke:external
  exercises both transports end-to-end.

CLI mcp-config

agentbridge mcp-config now prints an
"HTTP transport (experimental, v0.4.0 — opt-in)" block:

• env-var recipe (placeholder token only, never logged),
• generic hosted-client JSON config (transport: "streamable-http",
  url, Authorization: Bearer ${AGENTBRIDGE_HTTP_AUTH_TOKEN}
  placeholder),
• safety reminder updated for outbound vs inbound allowlists,
  query-token rejection, public-bind fail-closed.

packages/cli/src/tests/cli.test.ts
asserts every new line plus a regex assertion that no
real-looking bearer token leaks to stdout.

Docs updated

• README.md — status block now says v0.4.0
  release-prepared on this branch; not yet on npm.
• AGENTS.md — current-state block lists PRs
  docs: design v0.4.0 HTTP MCP transport and auth #23–feat(mcp-server): add opt-in HTTP transport with bearer auth #27 + this PR; HTTP opt-in note.
• CLAUDE.md — references list adds
  docs/releases/v0.4.0.md.
• docs/roadmap.md — v0.4.0 line marked
  release-prepared with file-path commitments and explicit
  remaining gaps.
• docs/v1-readiness.md — criteria build(deps): bump zod from 3.25.76 to 4.3.6 #8
  and build(deps): bump marked from 14.1.4 to 18.0.2 #9 from "design complete" → "implemented opt-in in
  v0.4.0"; status block + transport surface row updated.
• docs/threat-model.md — T14 rewritten
  with concrete v0.4.0 mitigations (bearer auth, no query
  tokens, exact Origin match, loopback bind, public-bind
  fail-closed, stdout hygiene preserved) and explicit remaining
  gaps (OAuth resource server, token rotation, scopes,
  caller-identity propagation, deployment guides).
• apps/mcp-server/README.md and
  apps/mcp-server/src/transports/README.md
  — opening sentence + status / migration plan refreshed.
• CHANGELOG.md — Unreleased content moved
  into a 0.4.0 — release-prepared entry with full
  Added/Changed/Compatibility breakdown.

Verification

npm run typecheck:clean        # green
npm test                       # 185/185 green
                                 (174 prior + 11 openapi-fixtures from PR #26)
npm run build                  # six packages OK; mcp-server bundle 40.3 KB ESM
npm run pack:dry-run           # six tarballs OK at 0.4.0
npm run smoke:http             # 13/13 ok against the built dist
                                 (token never logged)
npm run smoke:external         # PASS — fresh git archive, 42 scanner
                                 checks passed against demo, then
                                 stdio + HTTP smoke green.
node apps/mcp-server/dist/index.js < /dev/null
                               # exit 0
# stdio JSON-RPC subprocess smoke — serverInfo {agentbridge, 0.4.0};
#   stderr empty.
# CLI: version → 0.4.0; mcp-config prints stdio + HTTP blocks (no
#   real token); validate adopter manifests + openapi-regression
#   round-trip → ✓ valid.

Confirmations

• ✅ stdio remains the default. No HTTP listener opens unless AGENTBRIDGE_TRANSPORT=http.
• ✅ HTTP requires AGENTBRIDGE_HTTP_AUTH_TOKEN. Missing/short token fails closed at startup.
• ✅ Tokens in URL query strings rejected with 400. Verified by HTTP smoke.
• ✅ Origin allowlist exact-match; CORS never wildcard with credentials.
• ✅ Public bind requires both auth and Origin allowlist or fails closed at startup.
• ✅ Confirmation gate, origin pinning, target-origin allowlist, idempotency, audit redaction, simulated destructive demo actions — all unchanged.
• ✅ Stdout hygiene preserved. stdio-hygiene.test.ts 3/3 + http-mcp-smoke asserts stdout is empty across the HTTP run.
• ✅ Bearer token never in stdout, stderr, audit, or HTTP error bodies.
• ✅ No npm publish, no git tag, no GitHub release.
• ✅ Dependabot PRs untouched.
• ✅ Codex PR docs: add adopter quickstart and manifest patterns #25 (already on main) untouched. Codex PR test(openapi): add converter regression fixtures #26 (merged before this PR opened) untouched apart from the strict additions to CHANGELOG.md and examples/README.md outlined above.

Test plan

• npm run typecheck:clean green locally.
• npm test — 185/185 green locally.
• npm run build — six packages OK at 0.4.0.
• npm run pack:dry-run — six tarballs OK at 0.4.0.
• npm run smoke:http — 13/13 ok against the built dist.
• npm run smoke:external — PASS against the just-committed branch.
• CLI version / mcp-config / validate / generate openapi all green.
• CI green on Node 20.x and 22.x.
• Main CI green after merge.
• release-check green on main.

Recommended next step

If all CI tracks are green, ask the maintainer for explicit
approval to publish @marmarlabs/agentbridge-*@0.4.0 via the
existing Trusted Publishing workflow. Do not publish without
explicit approval.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b69452424c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Escape env-var placeholder in mcp-config output

The string passed to out.write interpolates ${AGENTBRIDGE_HTTP_AUTH_TOKEN} as a JavaScript identifier, but that variable is not defined in this module. As a result, running agentbridge mcp-config throws a ReferenceError at runtime before the command finishes, so users cannot get the config snippet. Print the placeholder literally (for example, by escaping $) instead of interpolating it.

Useful? React with 👍 / 👎.