@devries-cameron20 / composio-1 / commits / e313ee416
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add Dependabot remediation plans

jkomyno committed Aug 3, 2026 at 16:25 UTC e313ee4161fa7e3fccc8d27072b7f311715bafe4
8 files changed +1203
advisor-plans/001-refresh-actions-stale.md new
+128
@@ -0,0 +1,128 @@
1 +# Plan 001: Refresh `actions/stale` without changing repository policy
2 +
3 +> **Executor instructions**: Follow each step and run every verification. Stop
4 +> on any condition listed below; do not improvise. When complete, update this
5 +> plan's row in `advisor-plans/README.md`.
6 +>
7 +> **Drift check (run first)**:
8 +> `git diff --stat 03291bfaa..HEAD -- .github/workflows/stale.yml .github/scripts/check-action-repos.sh`
9 +> If either file changed, compare the live workflow and checker with the state
10 +> below before proceeding.
11 +
12 +## Status
13 +
14 +- **Priority**: P2
15 +- **Effort**: S
16 +- **Risk**: LOW
17 +- **Depends on**: none
18 +- **Category**: maintenance
19 +- **Planned at**: commit `03291bfaa`, 2026-08-03
20 +- **Source PR**: [GitHub #4001](https://github.com/ComposioHQ/composio/pull/4001) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4001))
21 +
22 +## Why this matters
23 +
24 +The v11 action retains the configured inputs and Node 24 runtime while updating
25 +its bundled dependencies. The current Dependabot head is green but predates the
26 +current `next`, and scheduled workflow behavior is not exercised by PR CI.
27 +
28 +## Current state
29 +
30 +- `.github/workflows/stale.yml:18` pins `actions/stale` v10.4.0 at
31 + `1e223db275d687790206a7acac4d1a11bd6fe629`.
32 +- The proposed v11.0.0 revision is
33 + `4391f3da665fdf50b6810c1a66712fb9ba21aa93`.
34 +- Lines 19-46 configure issue and PR thresholds, labels, messages,
35 + `ascending`, `remove-stale-when-updated`, and `debug-only: false`.
36 +- `.github/scripts/check-action-repos.sh` verifies that pinned action commits
37 + and action metadata exist.
38 +- Manual dispatch is unsafe as a test because the workflow has write
39 + permissions and `debug-only` is false.
40 +
41 +## Commands
42 +
43 +| Purpose | Command | Expected result |
44 +| ------------- | -------------------------------------------- | --------------------------------------- |
45 +| Workflow lint | `actionlint .github/workflows/stale.yml` | exit 0, no findings |
46 +| Action pins | `bash .github/scripts/check-action-repos.sh` | exit 0; v11 revision and metadata found |
47 +| Patch hygiene | `git diff --check` | exit 0 |
48 +
49 +## Scope
50 +
51 +**In scope**:
52 +
53 +- `.github/workflows/stale.yml`
54 +
55 +**Out of scope**:
56 +
57 +- Thresholds, labels, messages, permissions, cron schedule, and `debug-only`.
58 +- Any manual or API dispatch of the workflow.
59 +- Other workflow action pins.
60 +
61 +## Git workflow
62 +
63 +- Branch from the latest `origin/next`.
64 +- Commit: `chore(deps): bump actions/stale to v11`
65 +- Do not push, dispatch a workflow, or open a PR unless instructed.
66 +
67 +## Steps
68 +
69 +### Step 1: Refresh and validate the immutable revision
70 +
71 +Confirm that v11.0.0 still resolves to the proposed commit and that its
72 +`action.yml` exposes every input used in `.github/workflows/stale.yml`:
73 +
74 +```bash
75 +gh api repos/actions/stale/git/ref/tags/v11.0.0 --jq '.object.sha'
76 +stale_metadata="$(mktemp)"
77 +gh api 'repos/actions/stale/contents/action.yml?ref=v11.0.0' \
78 + --jq '.content' | base64 --decode > "$stale_metadata"
79 +rg -n 'repo-token|days-before-stale|days-before-close|ascending|stale-issue-label|exempt-issue-labels|stale-issue-message|close-issue-message|stale-pr-label|exempt-pr-labels|stale-pr-message|close-pr-message|remove-stale-when-updated|debug-only' "$stale_metadata"
80 +```
81 +
82 +The first command must print `4391f3da665fdf50b6810c1a66712fb9ba21aa93`.
83 +The `rg` command must print all 14 configured input names from the temporary
84 +metadata file. If the tag moved or an input disappeared, stop.
85 +
86 +### Step 2: Change only the pinned action line
87 +
88 +Replace line 18 with:
89 +
90 +```yaml
91 +uses: actions/stale@4391f3da665fdf50b6810c1a66712fb9ba21aa93 # v11.0.0
92 +```
93 +
94 +**Verify**:
95 +
96 +```bash
97 +git diff -- .github/workflows/stale.yml
98 +```
99 +
100 +Expected: one deletion and one addition on the `uses:` line only.
101 +
102 +### Step 3: Run static checks and obtain a fresh CI result
103 +
104 +Run all commands in the Commands table. After a PR is opened by an authorized
105 +operator, require all repository checks to finish on the rebased head. Observe
106 +the next scheduled run after merge; do not manually dispatch it.
107 +
108 +## Test plan
109 +
110 +No new test is warranted for a one-line immutable action pin. Static metadata
111 +validation, workflow lint, refreshed PR checks, and the next scheduled run are
112 +the regression gates.
113 +
114 +## Done criteria
115 +
116 +- [ ] The workflow pins the verified v11.0.0 commit.
117 +- [ ] No stale-policy input or permission changed.
118 +- [ ] `actionlint` and `check-action-repos.sh` exit 0.
119 +- [ ] Refreshed PR checks pass on the current `next` base.
120 +- [ ] The workflow was not manually dispatched.
121 +- [ ] Only `.github/workflows/stale.yml` changed.
122 +
123 +## STOP conditions
124 +
125 +- The v11.0.0 tag no longer resolves to the recorded commit.
126 +- Any configured input is absent or renamed in v11 metadata.
127 +- The action no longer uses a runner supported by GitHub-hosted runners.
128 +- Validation requires changing stale policy or permissions.
advisor-plans/002-refresh-development-tooling.md new
+141
@@ -0,0 +1,141 @@
1 +# Plan 002: Refresh the seven-package development dependency group
2 +
3 +> **Executor instructions**: Follow each step and run every verification. Stop
4 +> on any condition listed below; do not improvise. When complete, update this
5 +> plan's row in `advisor-plans/README.md`.
6 +>
7 +> **Drift check (run first)**:
8 +> `git diff --stat 03291bfaa..HEAD -- package.json pnpm-lock.yaml ts/examples/mastra/package.json ts/examples/mcp/package.json ts/examples/tool-router/package.json ts/examples/vercel/package.json ts/packages/cli-keyring/package.json ts/packages/cli-local-tools/package.json ts/packages/cli/package.json ts/packages/experimental/package.json ts/packages/json-schema-to-zod/package.json`
9 +> If an in-scope manifest changed, recalculate the target versions from the live
10 +> manifest and registry before proceeding.
11 +
12 +## Status
13 +
14 +- **Priority**: P2
15 +- **Effort**: S
16 +- **Risk**: LOW
17 +- **Depends on**: none
18 +- **Category**: maintenance
19 +- **Planned at**: commit `03291bfaa`, 2026-08-03
20 +- **Source PR**: [GitHub #4003](https://github.com/ComposioHQ/composio/pull/4003) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4003))
21 +
22 +## Why this matters
23 +
24 +The Dependabot head already passed audit, build, typecheck, unit, examples,
25 +CLI scratch, Node, Deno, and Cloudflare checks. Rebuilding it from current
26 +`next` clears seven development updates without publishing runtime dependency
27 +changes; the remaining risk is stale lockfile resolution.
28 +
29 +## Current state
30 +
31 +The source PR proposed these updates:
32 +
33 +| Package | Proposed change | Role |
34 +| --------------------------------- | ---------------- | ---------------------------------------------------------- |
35 +| `@types/node` | 26.1.1 to 26.1.2 | root and seven additional first-party TypeScript manifests |
36 +| `oxlint` | 1.75.0 to 1.76.0 | root linter |
37 +| `oxlint-plugin-eslint` | 1.75.0 to 1.76.0 | must match `oxlint` |
38 +| `turbo` | 2.10.6 to 2.10.7 | workspace task runner |
39 +| `tar` | 7.5.21 to 7.5.22 | CLI ACP archive extraction build path |
40 +| `@earendil-works/pi-coding-agent` | 0.82.0 to 0.82.1 | experimental adapter dev dependency |
41 +| `eve` | 0.27.3 to 0.27.8 | experimental adapter dev dependency |
42 +
43 +Targets may have advanced. Select the newest version that satisfies the same
44 +major line and the root `minimumReleaseAge: 4320` policy. Keep `oxlint` and
45 +`oxlint-plugin-eslint` on the identical version. Do not edit vendor manifests.
46 +
47 +## Commands
48 +
49 +| Purpose | Command | Expected result |
50 +| --------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
51 +| Resolve | `mise exec -- pnpm install --lockfile-only` | exit 0; lockfile generated by pnpm |
52 +| Reproducibility | `CI=true mise exec -- pnpm install --frozen-lockfile` | exit 0, no lockfile drift |
53 +| Lint | `mise exec -- pnpm lint:packages` | exit 0 |
54 +| Build | `mise exec -- pnpm build:packages` | exit 0 |
55 +| Types | `mise exec -- pnpm typecheck` | exit 0 |
56 +| Experimental adapters | `mise exec -- pnpm --filter @composio/experimental test && mise exec -- pnpm --filter @composio/experimental build` | all pass |
57 +| CLI binary | `mise exec -- pnpm build:binary` | exit 0 |
58 +| Tests | `mise exec -- pnpm test` | all pass |
59 +| CLI E2E | `mise exec -- pnpm test:e2e:cli` | all pass |
60 +
61 +## Scope
62 +
63 +**In scope**:
64 +
65 +- `package.json`
66 +- `pnpm-lock.yaml` through pnpm only
67 +- `ts/examples/{mastra,mcp,tool-router,vercel}/package.json`
68 +- `ts/packages/{cli-keyring,cli-local-tools,cli,experimental,json-schema-to-zod}/package.json`
69 +
70 +**Out of scope**:
71 +
72 +- `docs/package.json` and `ts/vendor/**`.
73 +- Production dependencies or source changes.
74 +- Any weakening of `minimumReleaseAge`.
75 +- A Changeset; all changes are development-only and CLI packages are excluded.
76 +
77 +## Git workflow
78 +
79 +- Branch from the latest `origin/next`.
80 +- Commit: `chore(deps-dev): refresh development tooling`
81 +- Do not push or open a PR unless instructed.
82 +
83 +## Steps
84 +
85 +### Step 1: Re-resolve eligible versions
86 +
87 +Query registry version and publication data for all seven packages. Preserve
88 +their current major lines, choose policy-eligible targets, and update only the
89 +listed manifests. Change every first-party occurrence touched by #4003, and
90 +keep the two oxlint package versions equal.
91 +
92 +**Verify**:
93 +
94 +```bash
95 +rg -n '"(@types/node|oxlint|oxlint-plugin-eslint|turbo|tar|@earendil-works/pi-coding-agent|eve)"' \
96 + package.json ts/examples/{mastra,mcp,tool-router,vercel}/package.json \
97 + ts/packages/{cli-keyring,cli-local-tools,cli,experimental,json-schema-to-zod}/package.json
98 +```
99 +
100 +Expected: every intended occurrence shows the chosen version; Pi and Eve peer
101 +ranges remain unchanged.
102 +
103 +### Step 2: Generate and prove the lockfile
104 +
105 +Run the Resolve and Reproducibility commands. Then run:
106 +
107 +```bash
108 +git diff --name-only
109 +```
110 +
111 +Expected: only the in-scope manifests and `pnpm-lock.yaml` are listed.
112 +
113 +### Step 3: Exercise tooling and adapters
114 +
115 +Run the remaining Commands table in order. The CLI binary and CLI E2E gates
116 +exercise the `tar` path; the experimental tests exercise the Pi and Eve
117 +adapters. Obtain a fresh complete CI run after an authorized operator opens or
118 +refreshes the PR.
119 +
120 +## Test plan
121 +
122 +No new tests are required because behavior is unchanged and dedicated Pi, Eve,
123 +CLI binary, and runtime suites already cover the affected contracts.
124 +
125 +## Done criteria
126 +
127 +- [ ] All seven package families use current policy-eligible versions.
128 +- [ ] `oxlint` and its ESLint plugin have identical versions.
129 +- [ ] Frozen install, lint, build, typecheck, tests, binary build, and CLI E2E pass.
130 +- [ ] `pnpm-lock.yaml` was generated by pnpm from current `next`.
131 +- [ ] No Changeset or source file was added.
132 +- [ ] Only in-scope files changed.
133 +
134 +## STOP conditions
135 +
136 +- A target version is younger than the 72-hour policy or requires weakening it.
137 +- Registry metadata requires a major update not named by this plan.
138 +- Oxlint and its plugin cannot resolve at the same version.
139 +- A test failure requires production source changes rather than a compatible
140 + dependency selection.
141 +- The lockfile update changes unrelated direct dependencies.
advisor-plans/003-align-effect-cli-family.md new
+158
@@ -0,0 +1,158 @@
1 +# Plan 003: Align the CLI on one maintained Effect release family
2 +
3 +> **Executor instructions**: Follow each step and run every verification. Stop
4 +> on any condition listed below; do not improvise. When complete, update this
5 +> plan's row in `advisor-plans/README.md`.
6 +>
7 +> **Drift check (run first)**:
8 +> `git diff --stat 03291bfaa..HEAD -- pnpm-workspace.yaml pnpm-lock.yaml ts/packages/cli/package.json .github/dependabot.yml`
9 +> If any in-scope dependency changed, re-check the current peer matrix before
10 +> editing.
11 +
12 +## Status
13 +
14 +- **Priority**: P1
15 +- **Effort**: M
16 +- **Risk**: MED
17 +- **Depends on**: none
18 +- **Category**: migration
19 +- **Planned at**: commit `03291bfaa`, 2026-08-03
20 +- **Source PR**: [GitHub #4004](https://github.com/ComposioHQ/composio/pull/4004) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4004))
21 +
22 +## Why this matters
23 +
24 +`@effect/printer-ansi@1.0.0` is an older package generation despite its higher
25 +semver major. It removes the `@effect/printer-ansi/Ansi` export used by the
26 +current CLI, causing 56 test suites and the CLI binary E2E build to fail. The
27 +safe update is the maintained, coordinated 0.51 family.
28 +
29 +## Current state
30 +
31 +- `pnpm-workspace.yaml` catalogs `@effect/cli ^0.76.0`,
32 + `@effect/platform ^0.97.0`, and `effect ^3.22.0`.
33 +- `ts/packages/cli/package.json` uses `@effect/printer` and
34 + `@effect/printer-ansi ^0.50.0` plus related Effect packages.
35 +- Live npm peer metadata coordinates these targets:
36 +
37 +| Package | Target line |
38 +| ----------------------------------------- | ----------- |
39 +| `@effect/cli` | `^0.77.0` |
40 +| `@effect/printer`, `@effect/printer-ansi` | `^0.51.0` |
41 +| `@effect/platform` | `^0.97.1` |
42 +| `effect` | `^3.22.1` |
43 +| `@effect/cluster` | `^0.60.2` |
44 +| `@effect/experimental` | `^0.61.1` |
45 +| `@effect/platform-bun` | `^0.91.2` |
46 +| `@effect/platform-node-shared` | `^0.61.1` |
47 +| `@effect/rpc` | `^0.76.2` |
48 +| `@effect/sql` | `^0.52.1` |
49 +| `@effect/workflow` | `^0.19.1` |
50 +
51 +Keep `@effect/typeclass` on the compatible 0.41 line. Re-query peer metadata at
52 +execution time and use the newest coordinated, 72-hour-eligible patch set.
53 +
54 +## Commands
55 +
56 +| Purpose | Command | Expected result |
57 +| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
58 +| Resolve | `mise exec -- pnpm install --lockfile-only` | exit 0, no peer errors |
59 +| Reproducibility | `CI=true mise exec -- pnpm install --frozen-lockfile` | exit 0 |
60 +| Dependency graph | `mise exec -- pnpm --filter @composio/cli list @effect/cli @effect/printer @effect/printer-ansi @effect/platform effect --depth 1` | only the coordinated current family; no printer 1.0.0 |
61 +| Types | `mise exec -- pnpm --filter @composio/cli typecheck` | exit 0 |
62 +| Unit tests | `mise exec -- pnpm --filter @composio/cli test` | all pass |
63 +| Package build | `mise exec -- pnpm --filter @composio/cli build` | exit 0 |
64 +| Binary build | `mise exec -- pnpm build:binary` | exit 0 |
65 +| CLI E2E | `mise exec -- pnpm test:e2e:cli` | all pass |
66 +
67 +## Scope
68 +
69 +**In scope**:
70 +
71 +- `pnpm-workspace.yaml`
72 +- `ts/packages/cli/package.json`
73 +- `.github/dependabot.yml`
74 +- `pnpm-lock.yaml` through pnpm only
75 +
76 +**Out of scope**:
77 +
78 +- `ts/vendor/**` and CLI source files.
79 +- Patching missing package exports or adding overrides for obsolete packages.
80 +- Changesets; `@composio/cli` is excluded from Changesets.
81 +
82 +## Git workflow
83 +
84 +- Branch from the latest `origin/next`.
85 +- Commit: `chore(cli): align Effect dependencies`
86 +- Do not push or open a PR unless instructed.
87 +
88 +## Steps
89 +
90 +### Step 1: Confirm the maintained peer matrix
91 +
92 +Query npm metadata for the listed targets. Confirm that the selected
93 +`@effect/cli` version peers on the selected printer, platform, and Effect lines.
94 +Confirm that `@effect/printer-ansi@1.0.0` still peers on legacy `@effect/io` or
95 +`@effect/data`. If upstream republished 1.x for the current generation, stop and
96 +re-plan instead of adding the ignore below.
97 +
98 +### Step 2: Update the coordinated dependency set
99 +
100 +Update catalog entries in `pnpm-workspace.yaml` and direct CLI development
101 +dependencies in `ts/packages/cli/package.json` as one unit. Do not update only
102 +the printer package. Generate the lockfile, prove frozen install, and inspect
103 +the dependency graph with the Commands table.
104 +
105 +**Verify**:
106 +
107 +```bash
108 +rg -n '"@effect/(cluster|experimental|printer|printer-ansi|rpc|sql|typeclass|workflow)"' \
109 + ts/packages/cli/package.json
110 +rg -n "'@effect/(cli|platform|platform-bun|platform-node-shared)'|effect:" pnpm-workspace.yaml
111 +```
112 +
113 +Expected: every entry belongs to the coordinated family and printer 1.0.0 is
114 +absent from `pnpm-lock.yaml`.
115 +
116 +### Step 3: Prevent the invalid major proposal from recurring
117 +
118 +Add this ignore to the npm update block in `.github/dependabot.yml`:
119 +
120 +```yaml
121 +ignore:
122 + - dependency-name: '@effect/printer-ansi'
123 + versions: ['1.0.0']
124 +```
125 +
126 +**Verify**:
127 +
128 +```bash
129 +yq -e '.updates[] | select(.package-ecosystem == "npm") | .ignore[] | select(.dependency-name == "@effect/printer-ansi")' .github/dependabot.yml
130 +```
131 +
132 +Expected: exit 0 and exactly one matching ignore entry.
133 +
134 +### Step 4: Exercise the CLI contract
135 +
136 +Run typecheck, unit tests, package build, binary build, and CLI E2E from the
137 +Commands table. A source change is not part of this dependency maintenance
138 +plan; stop if one appears necessary.
139 +
140 +## Test plan
141 +
142 +No new test is required. The regression is an import and binary-build failure
143 +already covered by CLI unit tests and scratch E2E.
144 +
145 +## Done criteria
146 +
147 +- [ ] The CLI resolves one current, peer-compatible Effect family.
148 +- [ ] Neither printer 1.0.0 nor legacy `@effect/io`/`@effect/data` enters the lockfile.
149 +- [ ] Dependabot ignores only `@effect/printer-ansi@1.0.0`.
150 +- [ ] Frozen install, CLI typecheck, tests, builds, and E2E pass.
151 +- [ ] No vendor, source, or Changeset file changed.
152 +
153 +## STOP conditions
154 +
155 +- Current peer metadata differs from the documented coordinated matrix.
156 +- Resolution introduces printer 1.0.0, `@effect/io`, or `@effect/data`.
157 +- pnpm reports unresolved or incorrectly satisfied Effect peer dependencies.
158 +- Passing the gates requires CLI source edits, an override, or a vendor change.
advisor-plans/004-rebuild-npm-production-rollup.md new
+174
@@ -0,0 +1,174 @@
1 +# Plan 004: Rebuild the npm production rollup on a coherent AI SDK train
2 +
3 +> **Executor instructions**: Follow each step and run every verification. Stop
4 +> on any condition listed below; do not improvise. When complete, update this
5 +> plan's row in `advisor-plans/README.md`.
6 +>
7 +> **Drift check (run first)**:
8 +> `git diff --stat 03291bfaa..HEAD -- pnpm-workspace.yaml pnpm-lock.yaml ts/e2e-tests/runtimes/cloudflare/cf-workers-tool-router-ai/package.json ts/e2e-tests/runtimes/node/claude-agent-sdk/package.json ts/examples/anthropic/package.json ts/examples/langchain/package.json ts/examples/mcp/package.json ts/examples/openai/package.json ts/examples/tool-router/package.json ts/examples/vercel/package.json ts/packages/experimental/package.json ts/packages/providers/anthropic/package.json ts/packages/providers/claude-agent-sdk/package.json ts/packages/providers/openai-agents/package.json`
9 +> Re-audit any changed manifest before selecting versions.
10 +
11 +## Status
12 +
13 +- **Priority**: P1
14 +- **Effort**: M
15 +- **Risk**: MED
16 +- **Depends on**: none
17 +- **Category**: maintenance
18 +- **Planned at**: commit `03291bfaa`, 2026-08-03
19 +- **Source PRs**: [GitHub #4002](https://github.com/ComposioHQ/composio/pull/4002) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4002)); [GitHub #4006](https://github.com/ComposioHQ/composio/pull/4006) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4006))
20 +
21 +## Why this matters
22 +
23 +The grouped production update fails example typechecking because
24 +`@ai-sdk/mcp` and `@ai-sdk/openai` resolve newer internal provider types than
25 +the catalog's `ai` release. Updating unrelated packages in the same failing
26 +commit hides their status. The replacement keeps one coherent AI SDK 7 train,
27 +retains deliberate AI SDK 6 compatibility coverage, and validates the other
28 +package families in small commits.
29 +
30 +## Current state
31 +
32 +PR #4002 proposed these 12 updates; re-query versions because the targets are
33 +already stale:
34 +
35 +| Package | PR target |
36 +| -------------------------------- | ------------ |
37 +| `@anthropic-ai/claude-agent-sdk` | 0.3.220 |
38 +| `@ai-sdk/mcp` | 2.0.18 |
39 +| `@anthropic-ai/sdk` | 0.115.0 |
40 +| `langchain` | 1.5.4 |
41 +| `@openai/agents` | 0.14.0 |
42 +| `@langchain/anthropic` | 1.5.2 |
43 +| `typebox` | 1.3.8 |
44 +| `@ai-sdk/openai` | 4.0.22 |
45 +| `@cloudflare/workers-types` | 5.20260728.1 |
46 +| `@mastra/core` | 1.53.0 |
47 +| `@modelcontextprotocol/sdk` | 1.30.0 |
48 +| `hono` | 4.12.32 |
49 +
50 +At the failed head, `@ai-sdk/mcp@2.0.18` and
51 +`@ai-sdk/openai@4.0.22` use provider 4.0.4/provider-utils 5.0.14 while
52 +`ai@7.0.37` uses 4.0.3/5.0.12. The resulting error is at
53 +`ts/examples/vercel/src/tool-router-ai.ts:73` when assigning MCP tools to
54 +`ToolSet`.
55 +
56 +The six explicit `ai: ^6.0.219` entries in the Mastra Zod 3/4 runtimes,
57 +Anthropic/Mastra examples, and Anthropic/Mastra provider dev dependencies are
58 +intentional compatibility coverage. Keep them. The normal catalog is the AI
59 +SDK 7 lane and must advance with `@ai-sdk/mcp` and `@ai-sdk/openai`.
60 +
61 +`typebox` is a runtime dependency of published `@composio/experimental`, so it
62 +requires a patch Changeset.
63 +
64 +## Commands
65 +
66 +| Purpose | Command | Expected result |
67 +| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
68 +| Resolve | `mise exec -- pnpm install --lockfile-only` | exit 0 |
69 +| Reproducibility | `CI=true mise exec -- pnpm install --frozen-lockfile` | exit 0 |
70 +| AI graph | `mise exec -- pnpm --filter vercel-example list ai @ai-sdk/mcp @ai-sdk/openai @ai-sdk/provider @ai-sdk/provider-utils --depth 4` | AI SDK 7 consumer graph uses compatible provider internals |
71 +| Peer policy | `mise exec -- pnpm check:peer-deps` | exit 0 |
72 +| Changesets | `mise exec -- pnpm validate:changesets` | exit 0 |
73 +| Focused example | `mise exec -- pnpm --filter vercel-example typecheck` | exit 0; no `ToolSet` error |
74 +| AI v6 fixture | `mise exec -- pnpm --filter @e2e-tests/node-vercel-ai-sdk-v6 test:e2e:node` | all pass |
75 +| AI v7 fixture | `mise exec -- pnpm --filter @e2e-tests/node-vercel-ai-sdk-v7 test:e2e:node` | all pass |
76 +| All examples | `mise exec -- pnpm typecheck:examples && mise exec -- pnpm test:examples` | all pass |
77 +| Packages | `mise exec -- pnpm build:packages && mise exec -- pnpm typecheck` | all pass |
78 +| Tests | `mise exec -- pnpm test` | all pass |
79 +| Runtime E2E | `mise exec -- pnpm test:e2e:node && mise exec -- pnpm test:e2e:cloudflare && mise exec -- pnpm test:e2e:cli` | all pass in credentialed CI |
80 +| Audit | `mise exec -- pnpm audit --prod --audit-level=high` | no high/critical production advisory introduced |
81 +
82 +## Scope
83 +
84 +**In scope**:
85 +
86 +- `pnpm-workspace.yaml` and `pnpm-lock.yaml` through pnpm.
87 +- The 12 manifest files listed in the drift check.
88 +- One new `.changeset/*.md` for the `typebox` runtime update.
89 +
90 +**Out of scope**:
91 +
92 +- The six explicit AI SDK 6 compatibility pins named above.
93 +- `ts/e2e-tests/runtimes/node/vercel-ai-sdk-v6/**` and its AI SDK 7 sibling.
94 +- OpenAI Node v7; that public migration is Plan 005.
95 +- Transitive overrides, source casts, or edits that suppress incompatible
96 + `ToolSet` types.
97 +
98 +## Git workflow
99 +
100 +- Branch from the latest `origin/next`.
101 +- Use conventional commits in this order:
102 + 1. `chore(deps): align AI SDK dependencies`
103 + 2. `chore(deps): refresh agent framework dependencies`
104 + 3. `chore(deps): refresh runtime support dependencies`
105 +- Do not push or open a PR unless instructed.
106 +
107 +## Steps
108 +
109 +### Step 1: Select one eligible AI SDK 7 train
110 +
111 +Query versions, publication dates, and dependency metadata for `ai`,
112 +`@ai-sdk/mcp`, and `@ai-sdk/openai`. Choose releases older than 72 hours whose
113 +exact `@ai-sdk/provider` and `@ai-sdk/provider-utils` requirements are mutually
114 +compatible. Add `@ai-sdk/mcp` to the root catalog and replace its repeated
115 +first-party manifest ranges with `catalog:`. Advance the existing `ai` and
116 +`@ai-sdk/openai` catalog entries together.
117 +
118 +Generate the lockfile and run the AI graph, focused example, all-example
119 +typecheck, Vercel v6 fixture, and Vercel v7 fixture before continuing.
120 +
121 +**Verify compatibility pins remain**:
122 +
123 +```bash
124 +rg -n '"ai": "\^6\.0\.219"' \
125 + ts/e2e-tests/runtimes/node/mastra-tool-router-zod-v{3,4}/package.json \
126 + ts/examples/{anthropic,mastra}/package.json \
127 + ts/packages/providers/{anthropic,mastra}/package.json
128 +```
129 +
130 +Expected: six matches.
131 +
132 +### Step 2: Update framework integrations in small commits
133 +
134 +Update the Anthropic, Claude Agent SDK, LangChain, OpenAI Agents, Mastra, and
135 +MCP SDK packages to current policy-eligible versions within the majors named by
136 +#4002. After each framework family, regenerate the lockfile and run its package
137 +tests/build plus affected example typechecks. Do not batch a failing family
138 +with the next one.
139 +
140 +### Step 3: Update TypeBox and support packages
141 +
142 +Update `typebox`, Cloudflare workers types, and Hono. Add a patch Changeset for
143 +`@composio/experimental` describing the TypeBox runtime dependency refresh.
144 +Generate the lockfile and run experimental package tests/build plus Cloudflare
145 +E2E.
146 +
147 +### Step 4: Run the complete regression gates
148 +
149 +Run every command in the Commands table on a clean frozen install. In CI,
150 +require the Claude Agent, Cloudflare Tool Router, Mastra Zod 3/4, Node, Deno,
151 +and CLI scratch jobs that GitHub selects for the changed paths.
152 +
153 +## Test plan
154 +
155 +Do not add tests if compatible dependency selection makes existing example and
156 +runtime gates pass. Add a regression test only if a real first-party public
157 +contract must change; stop first and report that scope expansion.
158 +
159 +## Done criteria
160 +
161 +- [ ] All 12 named production packages use current, policy-eligible targets.
162 +- [ ] The AI SDK 7 catalog resolves compatible provider internals.
163 +- [ ] All six intentional AI SDK 6 manifest pins remain.
164 +- [ ] A valid patch Changeset covers `@composio/experimental`.
165 +- [ ] Frozen install, peer checks, examples, builds, types, tests, E2E, and audit pass.
166 +- [ ] No source cast, transitive override, or unrelated dependency update was added.
167 +
168 +## STOP conditions
169 +
170 +- No 72-hour-eligible AI SDK 7 release train has compatible internal packages.
171 +- Fixing the `ToolSet` error requires a cast or first-party public API change.
172 +- A framework update requires a new major not named by the source PR.
173 +- The Mastra AI SDK 6 lane changes or its Zod 3/4 runtime checks fail.
174 +- The TypeBox runtime update cannot pass without changing experimental behavior.
advisor-plans/005-migrate-openai-v7.md new
+157
@@ -0,0 +1,157 @@
1 +# Plan 005: Migrate published OpenAI consumers to v7 while preserving v6 support
2 +
3 +> **Executor instructions**: Follow each step and run every verification. Stop
4 +> on any condition listed below; do not improvise. When complete, update this
5 +> plan's row in `advisor-plans/README.md`.
6 +>
7 +> **Drift check (run first)**:
8 +> `git diff --stat 03291bfaa..HEAD -- pnpm-workspace.yaml pnpm-lock.yaml ts/packages/core/package.json ts/packages/slim/package.json ts/packages/providers/openai/package.json ts/packages/core/src/provider/OpenAIProvider.ts ts/packages/providers/openai/src/OpenAIResponsesProvider.ts ts/e2e-tests/runtimes/node/openai-zod4-compat`
9 +> Re-audit OpenAI-owned exported types and package metadata if any path changed.
10 +
11 +## Status
12 +
13 +- **Priority**: P1
14 +- **Effort**: M
15 +- **Risk**: HIGH
16 +- **Depends on**: none
17 +- **Category**: migration
18 +- **Planned at**: commit `03291bfaa`, 2026-08-03
19 +- **Source PR**: [GitHub #4005](https://github.com/ComposioHQ/composio/pull/4005) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4005))
20 +
21 +## Why this matters
22 +
23 +The current Dependabot diff changes a runtime dependency of published
24 +`@composio/core` and `@composio/slim`, and changes the published peer major of
25 +`@composio/openai`. OpenAI v7's documented runtime break is Node 22+, which
26 +matches this repository's support floor, but exported OpenAI-owned types and
27 +downstream installation still need dual-major proof. The existing PR ran only
28 +build and generic checks.
29 +
30 +## Current state
31 +
32 +- `pnpm-workspace.yaml:52` catalogs `openai: ^6.49.0`.
33 +- `ts/packages/core/package.json` and `ts/packages/slim/package.json` carry the
34 + catalog entry as a runtime dependency.
35 +- `ts/packages/providers/openai/package.json` uses `catalog:` as its peer range;
36 + changing the catalog directly would drop declared v6 compatibility.
37 +- Core and the dedicated provider export types derived from OpenAI namespaces
38 + in `OpenAIProvider.ts` and `OpenAIResponsesProvider.ts`.
39 +- `ts/e2e-tests/runtimes/node/openai-zod4-compat` pins OpenAI 6, but currently
40 + installs only `@composio/core` with `--legacy-peer-deps`; it does not prove the
41 + dedicated provider's peer contract and has stale `openai@5` assertion labels.
42 +- The Node E2E matrix is 22.22.3, 24.17.0, and 25.9.0, all compatible with
43 + OpenAI v7's Node 22 floor.
44 +
45 +Use the newest OpenAI 7 release permitted by `minimumReleaseAge: 4320`, not the
46 +stale 7.0.0 target from the bot body.
47 +
48 +## Commands
49 +
50 +| Purpose | Command | Expected result |
51 +| ----------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
52 +| Resolve | `mise exec -- pnpm install --lockfile-only` | exit 0 |
53 +| Reproducibility | `CI=true mise exec -- pnpm install --frozen-lockfile` | exit 0 |
54 +| Peer policy | `mise exec -- pnpm check:peer-deps` | exit 0 |
55 +| Changesets | `mise exec -- pnpm validate:changesets` | exit 0 |
56 +| Core | `mise exec -- pnpm --filter @composio/core typecheck && mise exec -- pnpm --filter @composio/core test` | all pass |
57 +| OpenAI provider | `mise exec -- pnpm --filter @composio/openai build && mise exec -- pnpm --filter @composio/openai test` | all pass |
58 +| Examples | `mise exec -- pnpm typecheck:examples && mise exec -- pnpm test:examples` | all pass |
59 +| Packages | `mise exec -- pnpm build:packages && mise exec -- pnpm typecheck` | all pass |
60 +| Unit tests | `mise exec -- pnpm test` | all pass |
61 +| OpenAI v6 fixture | `mise exec -- pnpm --filter @e2e-tests/node-openai-zod4-compat test:e2e:node` | install, typecheck, and runtime assertions pass on Node matrix |
62 +| OpenAI v7 fixture | `mise exec -- pnpm --filter @e2e-tests/node-openai-v7-zod4-compat test:e2e:node` | install, typecheck, and runtime assertions pass on Node matrix |
63 +| Cloudflare | `mise exec -- pnpm test:e2e:cloudflare` | all pass in credentialed CI |
64 +| Audit | `mise exec -- pnpm audit --prod --audit-level=high` | no high/critical production advisory introduced |
65 +
66 +## Scope
67 +
68 +**In scope**:
69 +
70 +- `pnpm-workspace.yaml`, `pnpm-lock.yaml` through pnpm.
71 +- `ts/packages/providers/openai/package.json` for an explicit dual-major peer.
72 +- `ts/e2e-tests/runtimes/node/openai-zod4-compat/**` to make the v6 proof real
73 + and correct stale labels.
74 +- A new `ts/e2e-tests/runtimes/node/openai-v7-zod4-compat/**` sibling fixture.
75 +- One or more `.changeset/*.md` files covering `@composio/core`,
76 + `@composio/slim`, and `@composio/openai`.
77 +
78 +**Out of scope**:
79 +
80 +- Dropping OpenAI 6 support without an explicit product decision.
81 +- Changing the repository's Node support floor.
82 +- Live API calls, real keys, generated SDK surfaces, or OpenAI API behavior.
83 +- Source edits made only to silence incompatible exported types.
84 +
85 +## Git workflow
86 +
87 +- Branch from the latest `origin/next`.
88 +- Commit 1: `test(openai): cover v6 and v7 consumers`
89 +- Commit 2: `chore(deps): migrate OpenAI runtime to v7`
90 +- Do not push or open a PR unless instructed.
91 +
92 +## Steps
93 +
94 +### Step 1: Establish consumer fixtures before the catalog bump
95 +
96 +Strengthen `openai-zod4-compat` so it packs and installs the published
97 +`@composio/openai` package against explicit OpenAI 6 and runs a TypeScript
98 +assignability check for exported tool/response types. Retain its offline
99 +`wrapTool` runtime assertions. Correct all `openai@5` comments and markers to
100 +OpenAI 6.
101 +
102 +Create `openai-v7-zod4-compat` from the same pattern with explicit OpenAI 7.
103 +Both fixtures must install packed packages as consumers receive them; do not
104 +use workspace source imports or `skipLibCheck` to hide peer/type conflicts.
105 +
106 +Run both fixtures before changing the catalog. The v7 fixture may fail at this
107 +point because the provider peer excludes v7; that is the expected baseline.
108 +
109 +### Step 2: Update runtime and peer ranges
110 +
111 +Update the catalog to the selected OpenAI 7 release. Replace the dedicated
112 +provider's `catalog:` peer with an explicit `^6.49.0 || ^7.0.0` range so the
113 +catalog update does not silently drop v6 consumers. Generate the lockfile and
114 +run core and provider typecheck/build/tests.
115 +
116 +Do not alter exported type aliases unless the existing shapes fail under one of
117 +the supported majors. If they do, stop and report the exact incompatible types.
118 +
119 +### Step 3: Add release metadata
120 +
121 +Add a patch Changeset for fixed-group packages `@composio/core` and
122 +`@composio/slim`, describing the runtime dependency refresh. Add a minor
123 +Changeset for `@composio/openai`, following the prior `@composio/vercel` dual
124 +major support precedent, because the published peer contract gains v7 support.
125 +
126 +### Step 4: Run the full regression matrix
127 +
128 +Run every command in the Commands table from a frozen install. Require both
129 +consumer fixtures on all supported Node majors and the existing Cloudflare
130 +tests, because Cloudflare examples also consume the OpenAI catalog entry.
131 +
132 +## Test plan
133 +
134 +- OpenAI 6: packed provider install, exported-type compile check, client
135 + construction with a fake key, `wrapTool`, and no network request.
136 +- OpenAI 7: the same checks against the v7 package.
137 +- Keep Zod 4 in both fixtures to retain the prior peer-resolution regression.
138 +- Existing core/provider unit suites remain authoritative for wrapping behavior.
139 +
140 +## Done criteria
141 +
142 +- [ ] Core and slim resolve a policy-eligible OpenAI 7 runtime.
143 +- [ ] `@composio/openai` declares and proves OpenAI 6 and 7 peers.
144 +- [ ] Both packed consumer fixtures pass on Node 22, 24, and 25 without real keys.
145 +- [ ] Patch changesets cover core/slim; a minor changeset covers the provider.
146 +- [ ] Frozen install, peer, examples, builds, types, tests, E2E, and audit pass.
147 +- [ ] The Node support floor and generated code are unchanged.
148 +
149 +## STOP conditions
150 +
151 +- The selected OpenAI v7 release requires a runtime newer than the supported
152 + Node matrix.
153 +- Exported provider types cannot compile against both OpenAI 6 and 7.
154 +- Supporting both majors requires weakening types, `skipLibCheck`, or duplicate
155 + public APIs.
156 +- Existing OpenAI 6 behavior fails after the runtime dependency update.
157 +- The change needs a product decision to drop v6 or change a public type.
advisor-plans/006-migrate-autogen-provider-to-ag2-v1.md new
+235
@@ -0,0 +1,235 @@
1 +# Plan 006: Migrate the AutoGen provider to AG2 v1
2 +
3 +> **Executor instructions**: Follow each step and run every verification. Stop
4 +> on any condition listed below; do not improvise. When complete, update this
5 +> plan's row in `advisor-plans/README.md`.
6 +>
7 +> **Drift check (run first)**:
8 +> `git diff --stat 03291bfaa..HEAD -- python/providers/autogen python/tests/test_provider.py python/tests/test_type_inference_autogen.py docs/content/docs/providers/autogen.mdx .github/workflows/py.test.yml`
9 +> Re-audit AG2's public imports, tool protocol, and installation metadata if any
10 +> listed path or AG2's latest 1.x release changed.
11 +
12 +## Status
13 +
14 +- **Priority**: P1
15 +- **Effort**: M
16 +- **Risk**: HIGH
17 +- **Depends on**: none
18 +- **Category**: migration
19 +- **Planned at**: commit `03291bfaa`, 2026-08-03
20 +- **Source PR**: [GitHub #4008](https://github.com/ComposioHQ/composio/pull/4008) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4008))
21 +
22 +## Why this matters
23 +
24 +AG2 is the maintained forward package. Version 1 replaces the Classic
25 +`autogen` namespace and two-agent registration API with the `ag2` namespace,
26 +`Agent`, and native tools. Dependabot correctly identifies the major dependency
27 +upgrade, but its metadata-only change installs AG2 1.0.1 while the provider
28 +still imports `autogen`; Python 3.10 therefore fails immediately with
29 +`ModuleNotFoundError`, and the later matrix jobs are cancelled.
30 +
31 +The safe fix is an AG2 v1 provider migration, not a switch to the legacy
32 +`autogen` distribution. Use the [AG2 package](https://pypi.org/project/ag2/)
33 +and its [v1 tool API](https://docs.ag2.ai/docs/user-guide/tools/tools/) as the
34 +upstream contracts.
35 +
36 +## Current state
37 +
38 +- `python/providers/autogen/pyproject.toml:16` and `setup.py:25` declare
39 + `ag2>=0.14,<1.0` plus direct Classic-era `flaml` and `autogen_core`
40 + dependencies.
41 +- `provider.py:6-8` imports `autogen`, `ConversableAgent`, and
42 + `autogen_core.tools.FunctionTool`.
43 +- `provider.py:45-65` registers each tool with separate caller and executor
44 + agents through `autogen.agentchat.register_function`.
45 +- `wrap_tool` already creates a deterministic function name, a schema-derived
46 + Python signature, and an execution closure that restores reserved keywords.
47 + Preserve those Composio-specific behaviors while changing the framework
48 + wrapper.
49 +- `python/tests/test_provider.py` reaches into the Classic tool's private
50 + `_func` attribute, and `test_type_inference_autogen.py` imports the Microsoft
51 + `autogen_core` type. Neither assertion represents AG2 v1.
52 +- The provider README and public docs install `ag2[openai]`, but their examples
53 + still import Classic `AssistantAgent`, `LLMConfig`, and `UserProxyAgent`.
54 +- `python/providers/autogen` is not a root uv workspace member, so this package
55 + change must not alter root `uv.lock`.
56 +
57 +Target AG2 1.0.1 or newer within major version 1. Keep the published
58 +`composio-autogen` package, `composio_autogen` module, and `AutogenProvider`
59 +class names in this migration so existing Composio imports remain valid.
60 +
61 +## Commands
62 +
63 +| Purpose | Command | Expected result |
64 +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
65 +| Focused tests | `cd python && nox -s tst -- tests/test_autogen_provider.py tests/test_provider.py` | all focused tests pass |
66 +| Python checks | `cd python && nox -s chk` | exit 0 |
67 +| Type inference | `cd python && nox -s type_inference` | exit 0 |
68 +| Provider build | `mise exec -- uv build python/providers/autogen` | wheel and sdist build successfully |
69 +| Stale-import guard | `rg -n -e 'from autogen' -e 'import autogen' -e autogen_core -e flaml python/providers/autogen python/tests/test_type_inference_autogen.py` | no matches |
70 +| Docs links | `cd docs && bun run lint:links` | exit 0 |
71 +| Docs build | `cd docs && bun run build` | exit 0 |
72 +| Lockfile guard | `git diff --exit-code -- uv.lock` | exit 0; root lock unchanged |
73 +
74 +## Scope
75 +
76 +**In scope**:
77 +
78 +- `python/providers/autogen/composio_autogen/provider.py`
79 +- `python/providers/autogen/pyproject.toml`
80 +- `python/providers/autogen/setup.py`
81 +- `python/providers/autogen/README.md`
82 +- `python/tests/test_autogen_provider.py` (new)
83 +- `python/tests/test_provider.py`
84 +- `python/tests/test_type_inference_autogen.py`
85 +- `docs/content/docs/providers/autogen.mdx`
86 +
87 +**Out of scope**:
88 +
89 +- Renaming the published package, module, provider class, or docs route.
90 +- Supporting AG2 Classic and AG2 v1 in one provider release.
91 +- Root `uv.lock` or root uv workspace membership.
92 +- Unrelated Python provider migrations or historical changelogs.
93 +- Network model calls, Composio API requests, or real API keys in tests.
94 +
95 +## Git workflow
96 +
97 +- Branch from the latest `origin/next`.
98 +- Commit 1: `test(autogen): characterize AG2 v1 tool contracts`
99 +- Commit 2: `feat(autogen): migrate provider to AG2 v1`
100 +- Commit 3: `docs(autogen): update provider guide for AG2 v1`
101 +- Do not push or open a PR unless instructed.
102 +
103 +## Steps
104 +
105 +### Step 1: Replace private Classic assertions with AG2 v1 contracts
106 +
107 +Create `python/tests/test_autogen_provider.py` using local tool fixtures and a
108 +fake `execute_tool` callback. Update the two existing test files so they import
109 +and assert AG2 v1 types. Cover these contracts offline:
110 +
111 +1. `wrap_tool` returns `ag2.tools.final.FunctionTool`, and
112 + `wrap_tools` returns `list[FunctionTool]` statically and at runtime.
113 +2. `wrapped.schema.function` contains the deterministic name, Composio tool
114 + description, parameter types, required fields, and defaults expected from
115 + the generated signature. Assert the public schema instead of private
116 + framework attributes.
117 +3. `schema_config={"skip_defaults": True}` makes defaulted parameters required
118 + in the AG2 schema; the default configuration preserves their defaults.
119 +4. A reserved Python keyword is exposed under its safe generated parameter and
120 + restored before calling the fake executor.
121 +5. Invoke the wrapped tool through AG2's async `ToolCallEvent` and `Context`
122 + protocol. Assert the original Composio slug, normalized arguments, and
123 + structured result without constructing a real model client.
124 +6. A long tool slug produces the same valid name on repeated wraps and stays at
125 + or below 64 characters.
126 +7. A model-free or stub-configured `ag2.Agent` accepts wrapped tools through
127 + `Agent(..., tools=tools)`, and the migrated `register_tools(agent, tools)`
128 + helper delegates to `Agent.add_tool` for post-construction attachment.
129 +
130 +The initial test commit may fail because the source still uses Classic imports;
131 +record that expected failure before migrating the implementation.
132 +
133 +### Step 2: Migrate wrapping and registration to AG2 v1
134 +
135 +In `provider.py`:
136 +
137 +1. Replace Classic imports with `ag2.Agent`, `ag2.tool`, and the public AG2 v1
138 + `FunctionTool` type.
139 +2. Keep the existing name hashing, schema-to-signature conversion, reserved-key
140 + restoration, argument normalization, and Composio execution closure.
141 +3. Wrap the generated callable with `ag2.tool`, passing the processed name and
142 + description. Let AG2 derive its function schema from the generated signature
143 + so `skip_defaults` continues to control required/defaulted parameters.
144 +4. Replace `register_tools(caller, executor, tools)` with
145 + `register_tools(agent, tools)` implemented through `Agent.add_tool`. Retain
146 + the helper for dynamic attachment while making `Agent(..., tools=tools)` the
147 + primary documented API. Do not preserve the obsolete executor parameter or
148 + depend on Classic runtime objects.
149 +5. Keep tool execution synchronous inside the generated function and rely on
150 + AG2's default `sync_to_thread=True` behavior when the async tool protocol
151 + invokes it.
152 +
153 +The old caller/executor signature is an intentional breaking change caused by
154 +the upstream major version. Document its exact replacement in Step 4 rather
155 +than adding a compatibility dependency on the Classic package.
156 +
157 +### Step 3: Align package metadata with the migrated implementation
158 +
159 +Change both metadata sources to the same `ag2>=1.0.1,<2.0` requirement. Remove
160 +the direct `flaml==2.6.0` and `autogen_core>=0.7.5` requirements after the source
161 +and tests no longer import them. Do not add the `autogen` distribution.
162 +
163 +Build the provider, inspect wheel and sdist metadata, and confirm both artifacts
164 +declare the same AG2 bound with no direct `autogen`, `autogen-core`, or FLAML
165 +requirement. Leave package versioning to the existing Python release workflow.
166 +
167 +### Step 4: Rewrite the quickstart for AG2 v1
168 +
169 +Update the provider README and MDX page to:
170 +
171 +1. Continue installing `composio`, `composio-autogen`, and `ag2[openai]`.
172 +2. Import `Agent` from `ag2` and the current OpenAI model config from
173 + `ag2.config`; do not use Classic `AssistantAgent`, `UserProxyAgent`, or
174 + `LLMConfig`.
175 +3. Pass `session.tools()` to `Agent(..., tools=tools)` and run the current async
176 + AG2 interaction method shown in upstream v1 documentation.
177 +4. Add a short migration note mapping the old caller/executor registration call
178 + to constructor tools or `Agent.add_tool`.
179 +5. Keep the note about deterministic 64-character tool names.
180 +
181 +Validate the example against installed AG2 1.0.1 without sending a model request.
182 +Follow `docs/AGENTS.md`; do not edit generated docs data.
183 +
184 +### Step 5: Prove clean installs on every supported Python version
185 +
186 +After building, run this import check independently for Python 3.10, 3.11, and
187 +3.12:
188 +
189 +```bash
190 +mise exec -- uv run --isolated --no-project --python 3.10 \
191 + --with-editable ./python \
192 + --with-editable ./python/providers/autogen \
193 + python -c "import ag2; import composio_autogen; from ag2 import Agent"
194 +```
195 +
196 +Repeat with `--python 3.11` and `--python 3.12`. On one supported version, add
197 +`--with 'ag2[openai]>=1.0.1,<2.0'` and import the exact model config used by the
198 +quickstart. Expected: every command exits 0, resolves AG2 1.x, and does not need
199 +the Classic `autogen` namespace.
200 +
201 +Then run every command in the Commands table and require the repository's
202 +Python 3.10, 3.11, and 3.12 CI jobs to complete.
203 +
204 +## Test plan
205 +
206 +The focused tests exercise AG2's public schema, execution event, agent tool
207 +registration, and Composio's existing name/default/argument behavior without
208 +network access. Static type inference, fresh-version imports, artifact metadata,
209 +Python checks, and docs builds cover packaging and documentation regressions.
210 +
211 +## Done criteria
212 +
213 +- [ ] Both metadata sources require `ag2>=1.0.1,<2.0` and do not add `autogen`.
214 +- [ ] Provider runtime and type tests use only AG2 v1 public imports.
215 +- [ ] Tool schema, defaults, reserved arguments, long names, execution, and
216 + agent attachment pass focused offline tests.
217 +- [ ] README and public docs use AG2 v1 imports and explain the caller/executor
218 + migration.
219 +- [ ] Fresh imports pass on Python 3.10, 3.11, and 3.12.
220 +- [ ] Wheel and sdist metadata agree and contain no stale direct Classic
221 + dependencies.
222 +- [ ] Root `uv.lock`, package/module/class names, and unrelated providers remain
223 + unchanged.
224 +
225 +## STOP conditions
226 +
227 +- AG2's public 1.x `tool`, `FunctionTool`, `Agent`, or tool-event contract differs
228 + from the interfaces confirmed during the drift check.
229 +- Preserving Composio's `skip_defaults`, reserved-key restoration, or execution
230 + result contract requires AG2 private attributes.
231 +- The current quickstart cannot be constructed without a network call or secret;
232 + replace only the validation technique, not the documented public API.
233 +- Fresh resolution selects AG2 2.x, installs the Classic `autogen` distribution,
234 + or requires a direct dependency not declared by AG2.
235 +- Root `uv.lock` or another provider changes during resolution.
advisor-plans/007-upgrade-tomli-after-crewai.md new
+133
@@ -0,0 +1,133 @@
1 +# Plan 007: Upgrade Tomli after CrewAI permits a newer line
2 +
3 +> **Executor instructions**: This plan is currently blocked. Run the upstream
4 +> trigger check first. If CrewAI still requires Tomli 2.0.x, do not edit the
5 +> repository; leave the plan `BLOCKED` in `advisor-plans/README.md`. Once the
6 +> trigger clears, follow every step and verification below.
7 +>
8 +> **Drift check (run first)**:
9 +> `git diff --stat 03291bfaa..HEAD -- python/pyproject.toml python/noxfile.py python/providers/crewai/pyproject.toml python/providers/crewai/setup.py python/scripts/bump.py uv.lock`
10 +> Re-audit the complete resolved graph if any in-scope dependency changed.
11 +
12 +## Status
13 +
14 +- **Priority**: P3
15 +- **Effort**: S after upstream unblock
16 +- **Risk**: LOW
17 +- **Depends on**: a CrewAI release that no longer requires `tomli~=2.0.2`
18 +- **Category**: maintenance
19 +- **Planned at**: commit `03291bfaa`, 2026-08-03
20 +- **Source PR**: [GitHub #4007](https://github.com/ComposioHQ/composio/pull/4007) ([Glen review](https://app.tryglen.com/review/ComposioHQ/composio/4007))
21 +- **Current status**: BLOCKED — CrewAI 1.15.10 still constrains Tomli to 2.0.x
22 +
23 +## Why this matters
24 +
25 +PR #4007 widens Composio's direct upper bound but cannot update the installed
26 +package: the unified uv workspace includes CrewAI, whose current metadata still
27 +forces Tomli 2.0.x. Merging that diff would claim an update while `uv.lock`
28 +remains on 2.0.2. Waiting for a compatible CrewAI release keeps dependency
29 +metadata truthful and avoids an override.
30 +
31 +## Current state
32 +
33 +- `python/pyproject.toml:36-37` documents CrewAI's constraint and requires
34 + `tomli>=2.0.2,<2.1`.
35 +- `python/providers/crewai/pyproject.toml` and `setup.py` support CrewAI
36 + `>=1.15.7,<2.0.0`; `python/noxfile.py` tests exactly 1.15.7.
37 +- `python/scripts/bump.py` imports Tomli to parse release metadata.
38 +- `uv.lock` resolves Tomli 2.0.2.
39 +- Live PyPI metadata for CrewAI 1.15.10 still includes `tomli~=2.0.2`.
40 +- There is no known high/critical advisory against Tomli 2.0.2 in this usage;
41 + this is maintenance, not an emergency override.
42 +
43 +## Commands
44 +
45 +| Purpose | Command | Expected result |
46 +| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
47 +| Upstream trigger | `curl -fsSL https://pypi.org/pypi/crewai/json | jq -r '.info.version, (.info.requires_dist[]? | select(test("tomli"; "i")))'` | newest version and a Tomli requirement that allows the intended newer line |
48 +| Generate lock | `mise exec -- uv lock` | exit 0; lock generated by uv |
49 +| Lock check | `mise exec -- uv lock --check` | exit 0 |
50 +| Resolution | `mise exec -- uv tree --locked --package tomli --invert` | selected Tomli is newer than 2.0.2 and all dependents are satisfied |
51 +| Parser smoke | `cd python && uv run python -c 'import pathlib, tomli; tomli.loads(pathlib.Path("pyproject.toml").read_text())'` | exit 0 |
52 +| Python checks | `cd python && make chk` | exit 0 |
53 +| Tests | `cd python && make tst` | all pass |
54 +| Sanity | `cd python && make snt` | exit 0 |
55 +
56 +## Scope
57 +
58 +**In scope after the trigger clears**:
59 +
60 +- `python/pyproject.toml`
61 +- `python/noxfile.py`
62 +- `python/providers/crewai/pyproject.toml`
63 +- `python/providers/crewai/setup.py`
64 +- `uv.lock` through uv only
65 +
66 +**Out of scope**:
67 +
68 +- Dependency overrides or patched CrewAI metadata.
69 +- Removing CrewAI from the uv workspace.
70 +- Rewriting the bump script to avoid Tomli.
71 +- Any change while upstream still requires Tomli 2.0.x.
72 +
73 +## Git workflow
74 +
75 +- Branch from the latest `origin/next` only after the trigger clears.
76 +- Commit: `chore(deps-dev): update Tomli and CrewAI baseline`
77 +- Do not push or open a PR unless instructed.
78 +
79 +## Steps
80 +
81 +### Step 1: Prove the upstream block is gone
82 +
83 +Run the Upstream trigger command and inspect the newest stable CrewAI release,
84 +including any split CrewAI Core/CLI distributions it requires. Proceed only if
85 +the full published requirement graph accepts the intended Tomli version without
86 +an override. Record the qualifying CrewAI version in the PR description.
87 +
88 +If the output still contains `tomli~=2.0.2`, stop with no repository changes.
89 +
90 +### Step 2: Raise the tested CrewAI baseline consistently
91 +
92 +Update the CrewAI lower bound in both provider metadata files and the exact
93 +test version in `python/noxfile.py` to the first stable release that relaxes
94 +Tomli. Keep `pyproject.toml` and `setup.py` identical. Do not raise the provider
95 +baseline if the older CrewAI range can coexist with the selected Tomli and the
96 +owner wants to retain it; in that case stop for an explicit compatibility
97 +decision rather than silently narrowing support.
98 +
99 +### Step 3: Select and resolve the newer Tomli line
100 +
101 +Update the direct Tomli range and its comment in `python/pyproject.toml`. Set the
102 +minimum to the selected tested release so the lockfile must actually advance;
103 +choose an upper bound supported by both Tomli and CrewAI metadata. Run `uv lock`
104 +from the repository root and never hand-edit `uv.lock`.
105 +
106 +### Step 4: Prove parsing and the Python graph
107 +
108 +Run the remaining Commands table checks. In CI, require the Python 3.10, 3.11,
109 +and 3.12 matrix because Tomli is especially relevant on Python versions before
110 +the standard-library `tomllib` module.
111 +
112 +## Test plan
113 +
114 +No new test is needed. The package is used by the release bump parser; a direct
115 +parse smoke check plus Python lint, unit, sanity, and version-matrix jobs cover
116 +the changed dependency contract.
117 +
118 +## Done criteria
119 +
120 +- [ ] Upstream CrewAI metadata accepts the selected Tomli line without overrides.
121 +- [ ] Both CrewAI provider metadata sources and the nox baseline agree.
122 +- [ ] `uv.lock` resolves a Tomli version newer than 2.0.2.
123 +- [ ] `uv lock --check`, parser smoke, checks, tests, and sanity pass.
124 +- [ ] No workspace member, override, or bump-script behavior changed.
125 +
126 +## STOP conditions
127 +
128 +- Any current CrewAI distribution still constrains Tomli to 2.0.x.
129 +- Updating Tomli requires a resolver override, removing a workspace member, or
130 + dropping a supported Python version.
131 +- The tested CrewAI baseline cannot be raised without a product compatibility
132 + decision.
133 +- `uv.lock` still resolves Tomli 2.0.2 after the manifest changes.
advisor-plans/README.md new
+77
@@ -0,0 +1,77 @@
1 +# Dependabot remediation plans
2 +
3 +Generated from live GitHub state and `origin/next` on 2026-08-03. The audit
4 +covered all eight open Dependabot pull requests and all 25 dependency updates
5 +named by them. Execute each plan from a fresh branch based on the then-current
6 +`origin/next`; never reuse a stale Dependabot lockfile.
7 +
8 +## Audit result
9 +
10 +All eight pull requests are Git-mergeable and review-blocked. Mergeability is
11 +not approval: four heads have substantive failed checks, two green heads need
12 +only a fresh base and rerun, and two green or partially green heads do not prove
13 +the proposed compatibility change.
14 +
15 +| PR | Packages | Live result | Disposition |
16 +| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
17 +| [#4001](https://github.com/ComposioHQ/composio/pull/4001) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4001)) | `actions/stale` 10.4.0 to 11.0.0 | 10 checks, no failures; scheduled action itself did not run | Refresh and approve through Plan 001 |
18 +| [#4002](https://github.com/ComposioHQ/composio/pull/4002) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4002)) | 12 npm production updates | Examples fail on incompatible AI SDK internal types | Supersede through Plan 004 |
19 +| [#4003](https://github.com/ComposioHQ/composio/pull/4003) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4003)) | 7 npm development updates | 22 checks, no failures | Refresh and approve through Plan 002 |
20 +| [#4004](https://github.com/ComposioHQ/composio/pull/4004) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4004)) | `@effect/printer-ansi` 0.50.0 to 1.0.0 | Unit and CLI E2E fail; 1.0.0 belongs to an obsolete Effect generation | Close and supersede through Plan 003 |
21 +| [#4005](https://github.com/ComposioHQ/composio/pull/4005) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4005)) | `openai` 6.49.0 to 7.x on current `next` | Build is green, but tests, typecheck, examples, peer checks, and changesets did not run | Supersede through Plan 005 |
22 +| [#4006](https://github.com/ComposioHQ/composio/pull/4006) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4006)) | six explicit AI SDK 6 compatibility pins to AI SDK 7 | 11 jobs fail at frozen install because the lockfile was omitted | Close; Plan 004 advances the AI SDK 7 catalog while retaining this intentional v6 lane |
23 +| [#4007](https://github.com/ComposioHQ/composio/pull/4007) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4007)) | `tomli` 2.0.x to `<2.5` | Green, but CrewAI still forces the lock to 2.0.2 | Close; Plan 007 is blocked on CrewAI relaxing its requirement |
24 +| [#4008](https://github.com/ComposioHQ/composio/pull/4008) ([Glen](https://app.tryglen.com/review/ComposioHQ/composio/4008)) | `ag2` 0.x to 1.x | Python 3.10 import fails; 3.11 and 3.12 were cancelled | Supersede with an AG2 v1 provider migration through Plan 006 |
25 +
26 +## Package inventory
27 +
28 +Plan 004 covers the 12 production-group packages: `@anthropic-ai/claude-agent-sdk`,
29 +`@ai-sdk/mcp`, `@anthropic-ai/sdk`, `langchain`, `@openai/agents`,
30 +`@langchain/anthropic`, `typebox`, `@ai-sdk/openai`,
31 +`@cloudflare/workers-types`, `@mastra/core`, `@modelcontextprotocol/sdk`, and
32 +`hono`. It also advances the existing AI SDK 7 catalog dependency in lockstep
33 +with the two `@ai-sdk/*` packages.
34 +
35 +Plan 002 covers the seven development-group packages: `@types/node`, `oxlint`,
36 +`oxlint-plugin-eslint`, `turbo`, `tar`, `@earendil-works/pi-coding-agent`, and
37 +`eve`. Plans 001, 003, 005, 006, and 007 cover `actions/stale`, the coordinated
38 +Effect family, `openai`, AG2 v1, and Tomli respectively.
39 +
40 +## Execution order and status
41 +
42 +| Plan | Title | Priority | Effort | Depends on | Status |
43 +| ---- | ------------------------------------------------------------------------------------- | -------- | ------ | ------------------------ | --------------------------------------------------- |
44 +| 001 | [Refresh `actions/stale` safely](./001-refresh-actions-stale.md) | P2 | S | none | TODO |
45 +| 002 | [Refresh development tooling](./002-refresh-development-tooling.md) | P2 | S | none | TODO |
46 +| 003 | [Align the Effect CLI family](./003-align-effect-cli-family.md) | P1 | M | none | TODO |
47 +| 004 | [Rebuild the npm production rollup](./004-rebuild-npm-production-rollup.md) | P1 | M | none | TODO |
48 +| 005 | [Migrate published OpenAI consumers to v7](./005-migrate-openai-v7.md) | P1 | M | none | TODO |
49 +| 006 | [Migrate the AutoGen provider to AG2 v1](./006-migrate-autogen-provider-to-ag2-v1.md) | P1 | M | none | TODO |
50 +| 007 | [Upgrade Tomli after CrewAI permits it](./007-upgrade-tomli-after-crewai.md) | P3 | S | upstream CrewAI metadata | BLOCKED — CrewAI 1.15.10 still requires Tomli 2.0.x |
51 +
52 +Status values: `TODO`, `IN PROGRESS`, `DONE`, `BLOCKED`, or `REJECTED`.
53 +
54 +## Landing strategy
55 +
56 +- Plans 001 and 002 may share one low-risk rollup PR, with one conventional
57 + commit per plan.
58 +- Plans 003, 004, 005, and 006 should use separate PRs because each has a
59 + distinct compatibility contract and rollback boundary.
60 +- Every TypeScript plan must generate `pnpm-lock.yaml` through pnpm and prove a
61 + frozen install. Never copy the lockfile from an old Dependabot head.
62 +- Do not run the stale workflow manually: its production dispatch can relabel
63 + or close issues and pull requests.
64 +
65 +## Findings considered and rejected
66 +
67 +- Merging #4004 and adding an import patch was rejected. The proposed 1.0.0
68 + package is from the wrong Effect generation; the maintained coordinated line
69 + is 0.51.x.
70 +- Merging #4006 after merely regenerating the lockfile was rejected. The six
71 + explicit AI SDK 6 pins provide Mastra and Zod compatibility coverage; the
72 + normal catalog already exercises AI SDK 7.
73 +- Merging #4007 was rejected. Widening the direct Tomli range does not change
74 + the resolved version while CrewAI requires `tomli~=2.0.2`.
75 +- Replacing AG2 with the Classic `autogen` distribution was rejected. AG2 1.x is
76 + the maintained forward line; the dependency update needs a provider/API
77 + migration because it no longer provides the old `autogen` import path.