Skip to content

[AAASM-3530] 📝 (docs): Declare framework compatibility + backfill peerDeps#174

Merged
Chisanan232 merged 5 commits into
masterfrom
v0.0.1/AAASM-3530/docs/compat_node
Jun 22, 2026
Merged

[AAASM-3530] 📝 (docs): Declare framework compatibility + backfill peerDeps#174
Chisanan232 merged 5 commits into
masterfrom
v0.0.1/AAASM-3530/docs/compat_node

Conversation

@Chisanan232

@Chisanan232 Chisanan232 commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

What changed

node-sdk auto-detects and governs 5 agent frameworks but only declared
peerDependencies ranges for 2 of them. This PR:

  • Backfills the 3 missing frameworks as optional peer dependencies in
    package.json (+ peerDependenciesMeta):
    • @langchain/langgraph >=1.0.0
    • ai (Vercel AI SDK) >=5.0.0
    • @mastra/core >=0.20.0
  • Adds a Framework compatibility section to README.md listing all 5
    frameworks, their peer-dependency packages, version ranges, and a link to
    the canonical product-wide matrix at
    https://ai-agent-assembly.github.io/agent-assembly/stable/reference/framework-compatibility.html
    (the /stable/ link 404s until GA by design, consistent with AAASM-3523).

Why

The declared peer-dependency set was incomplete relative to the frameworks the
SDK actually hooks (src/hooks/). Consumers got no resolver signal for
LangGraph, Vercel AI, or Mastra. Marking them optional: true keeps the SDK
installable with zero frameworks present.

Version floors

Floors are the major lines the AAASM-3525 cross-repo live smokes run against
(per the driver fixtures in
agent-assembly-integration-tests/tests/live/drivers/node-frameworks/):
@langchain/langgraph ^1.0.0, ai ^5.0.0, @mastra/core ^0.20.0. Expressed
as >=x floors (no fabricated upper bounds). The two pre-existing floors
(@langchain/core >=0.3.0, @openai/agents >=0.1.0) are unchanged.

How to verify

  • pnpm install resolves; pnpm lint and pnpm typecheck clean.
  • Pre-push hook (full test + typecheck) passed.

Refs AAASM-3530

Chisanan232 and others added 4 commits June 22, 2026 10:16
@Chisanan232 @claude
🔧 (deps): Backfill optional peerDeps for langgraph, ai, mastra
f04a463 
node-sdk auto-detects 5 frameworks but only declared peerDependency ranges
for @langchain/core and @openai/agents. Add @langchain/langgraph (>=1.0.0),
ai (>=5.0.0) and @mastra/core (>=0.20.0) as optional peer deps, using the
major lines the AAASM-3525 cross-repo live smokes run against. Marked optional
so the SDK installs without any framework present.

Refs AAASM-3530

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Chisanan232 @claude
📝 (docs): Document supported framework compatibility matrix
7d77298 
Add a "Framework compatibility" section listing the 5 auto-detected
frameworks, their optional peer-dependency packages, and version floors,
plus a link to the canonical product-wide matrix in the core docs.

Refs AAASM-3530

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Chisanan232 @claude
🐛 (deps): Keep framework peerDeps uninstalled in this repo's env
f7883ca 
The AAASM-3530 peerDeps backfill made pnpm 10 materialize the optional
ai / @langchain/langgraph / @mastra/core peers into this repo's own
node_modules. With the real `ai` ESM module present, initAssembly's
framework detection fires and the Vercel adapter assigns to the frozen
ESM `tool` binding -> `Cannot assign to read only property 'tool'`,
turning ~20 unrelated unit tests red on Node 18/20/22/24.

A peerDependency is a published contract, not an install. Add a
.pnpmfile.cjs readPackage hook that strips those three optional peers
from this project's manifest during resolution, so they stay declared
in package.json (the contract) but are neither recorded in the importer
nor installed here. The lockfile importer is now byte-identical to
master (only a pnpmfileChecksum line is added) and
`pnpm install --frozen-lockfile` stays consistent.

Refs AAASM-3530

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Chisanan232 @claude
🔧 (lint): Lint .pnpmfile.cjs as CommonJS
781a069 
The new pnpm install hook is a CommonJS module; give it `module`/`require`
globals and `sourceType: commonjs` so eslint lints it (mirroring the
existing scripts/**/*.mjs block) instead of flagging `no-undef`.

Refs AAASM-3530

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@codecov

codecov Bot commented Jun 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@Chisanan232

Chisanan232 commented Jun 22, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Claude Code — PR review (record)

CI: ✅ green — the test (18/20/22/24) jobs now pass after the regression fix (was RED). Any remaining coverage-and-analysis/Sonar noise is acceptance, ignored per policy.

Scope vs AAASM-3530 (node part): ✅ covers it. Backfills the 3 missing optional peerDependencies — @langchain/langgraph >=1.0.0, ai >=5.0.0, @mastra/core >=0.20.0 (floors from the AAASM-3525 driver fixtures) — and adds a 5-framework "Framework compatibility" README section linking the canonical core matrix (/stable/ URL).

Regression caught + fixed during review: declaring ai >=5.0.0 made pnpm 10 install ai 6.x, and the Vercel adapter crashed mutating the frozen ESM tool binding at initAssembly → ~20 unrelated unit tests red. Fixed by keeping the framework peerDeps declared-but-uninstalled in this repo's env (.pnpmfile.cjs readPackage hook; lockfile importer now identical to master). Local pnpm test → 326 passed; lint/typecheck/prettier clean.

Filed separately: AAASM-3532 — the frozen-ESM crash is a real consumer-facing adapter bug (same class as the OpenAI-Agents 3528 fix); not fixed here (out of this docs PR's scope).

Verdict: ✅ Ready to approve & merge (AAASM-3530 set). Refs AAASM-3530.

@Chisanan232 @claude
📝 (docs): Document framework compatibility on the docs page (authorit…
90f5a91 
…ative); trim README

Move the 5-framework compatibility table (LangChain.js, LangGraph.js,
Vercel AI SDK, Mastra, OpenAI Agents) to the Docusaurus compatibility
page, which is now the authoritative Node SDK reference. Note the
AAASM-3532 Vercel AI SDK caveat. Trim the README to a short pointer at
the docs page plus the core cross-SDK index/hub, avoiding duplication.

Refs AAASM-3530

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sonarqubecloud

sonarqubecloud Bot commented Jun 22, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@Chisanan232 Chisanan232 merged commit 227ace2 into master Jun 22, 2026
17 checks passed
@Chisanan232 Chisanan232 deleted the v0.0.1/AAASM-3530/docs/compat_node branch June 22, 2026 03:10
@Chisanan232 Chisanan232 mentioned this pull request Jun 22, 2026
Merged
10 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Chisanan232