You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/superpowers/plans/2026-07-08-client-tools-m6-agent-bridge-plan.md
+56-15Lines changed: 56 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -112,15 +112,17 @@ Discovery result: the inspected provider exposes a stateful chat/resource API pl
112
112
**Files:**
113
113
- Modify this plan or add contract notes if the decision is made before implementation.
114
114
115
-
-[]**Step 1: Choose package boundary**
115
+
-[x]**Step 1: Choose package boundary**
116
116
117
117
Pick one:
118
118
119
119
- new published adapter package, if consumers should import it directly;
120
120
- private/internal adapter, if this is only a migration bridge;
121
121
- no code, if provider APIs are unstable or unavailable.
122
122
123
-
-[ ]**Step 2: Decide public API shape**
123
+
Decision: add a private/internal adapter proof under `libs/chat` first. Do not create a new published package or public export until the package boundary is approved.
124
+
125
+
-[x]**Step 2: Decide public API shape**
124
126
125
127
If public, mirror existing adapter ergonomics:
126
128
@@ -132,7 +134,9 @@ injectAgent(ref?)
132
134
133
135
Use a provider-specific prefix internally if needed to avoid collisions with existing adapter types, but keep the consumer mental model aligned with AG-UI and LangGraph.
134
136
135
-
- [ ] **Step 3: Decide client-tools mapping**
137
+
Decision: no public API in the adapter-proof PR. A future public package should mirror `toAgent(source, options?)` and DI provider ergonomics only after API shape review.
Only map browser-executed tools into Threadplane `action`/`view`/`ask` when the provider supplies stable pending-call identifiers and a result-return API.
144
148
149
+
Decision: do not map provider tools into `ClientToolsCapability` in the adapter-proof PR. The inspected source exposes provider-owned tool execution without a stable browser result-return API for Threadplane client tools.
150
+
145
151
## Task 3: Contract Tests First
146
152
147
153
**Files:**
148
154
- Add: adapter conformance spec path TBD.
149
155
- Add: provider fake/test fixture path TBD.
150
156
151
-
- [] **Step 1: Build a scriptable provider fake**
157
+
- [x] **Step 1: Build a scriptable provider fake**
152
158
153
159
Create a test-only fake from the captured event contract. It must support:
154
160
@@ -157,7 +163,9 @@ Create a test-only fake from the captured event contract. It must support:
157
163
- message/tool history inspection;
158
164
- branch-on-tool-result behavior if the provider supports continuation.
Implementation note: the first adapter-proof PR uses a scriptable signal-resource fake scoped to the observed public resource surface, not transport-frame scripts.
- regenerate trims at the selected assistant message and reruns;
172
180
- custom events flow through `events$` or adapter-specific signal if supported.
173
181
174
-
- [] **Step 3: Write client-tools bridge tests only if supported**
182
+
- [x] **Step 3: Write client-tools bridge tests only if supported**
175
183
176
184
If provider has stable browser tool primitives, cover:
177
185
@@ -184,16 +192,20 @@ If provider has stable browser tool primitives, cover:
184
192
185
193
Do not implement client-tools mapping if the provider lacks stable tool-call IDs or result APIs.
186
194
195
+
Decision: not supported for this proof. The adapter tests cover tool-call projection only; no client-tools bridge tests are added.
196
+
187
197
## Task 4: Minimal Adapter Implementation
188
198
189
199
**Files:**
190
200
- Add/modify only after Tasks 1-3 pass their decision gates.
191
201
192
-
- [] **Step 1: Implement event reduction**
202
+
- [x] **Step 1: Implement event reduction**
193
203
194
204
Prefer the AG-UI reducer path if compatible. Otherwise implement only the reducer cases proven by fixtures. Unknown events must be ignored or surfaced as neutral custom events; they must not crash the stream.
195
205
196
-
- [ ] **Step 2: Implement actions**
206
+
Implementation note: the proof uses resource-state projection rather than event reduction because the inspected public API exposes resource state, not a public event subscriber.
207
+
208
+
- [x] **Step 2: Implement actions**
197
209
198
210
Map:
199
211
@@ -204,11 +216,13 @@ Map:
204
216
205
217
to provider APIs only where semantics match the existing `Agent` contract. Throwing is acceptable for programmer misuse, but normal unsupported provider features should be absent or no-op only if that matches existing adapter precedent.
206
218
207
-
- [] **Step 3: Add Angular provider wiring**
219
+
- [x] **Step 3: Add Angular provider wiring**
208
220
209
221
If public or DI-supported, mirror the existing typed `AgentRef` overloads and factory config pattern from AG-UI/LangGraph.
210
222
211
-
- [ ] **Step 4: Add public exports and docs only after approval**
223
+
Decision: not applicable to the private proof. No DI/provider helper is added.
224
+
225
+
- [x] **Step 4: Add public exports and docs only after approval**
212
226
213
227
If the adapter is public:
214
228
@@ -218,16 +232,24 @@ npm run generate-api-docs
218
232
219
233
Expected: generated API docs include the new bridge types. Commit generated docs with the public export.
220
234
235
+
Decision: not applicable to the private proof. No public export is added, so API docs are unchanged.
236
+
221
237
## Task 5: Verification
222
238
223
239
**Files:**
224
240
- No additional files.
225
241
226
-
- [] **Step 1: Run focused adapter tests**
242
+
- [x] **Step 1: Run focused adapter tests**
227
243
228
244
Run the new adapter test target or focused Vitest spec.
229
245
230
-
- [ ] **Step 2: Run affected existing adapter/chat tests**
Before committing code, run a staged diff scan excluding `docs/superpowers/**` and confirm no forbidden external framework names appear in code, comments, commit text, or PR text.
249
286
250
-
- [ ] **Step 5: Diff audit**
287
+
Verified with a staged diff scan excluding `docs/superpowers/**`; no forbidden references appeared in code or comments.
288
+
289
+
- [x] **Step 5: Diff audit**
251
290
252
291
Confirm the diff contains no unrelated refactors, no package dependency changes unless explicitly approved, and no behavior changes to existing AG-UI or LangGraph adapters.
253
292
293
+
Verified: diff is limited to the private adapter proof, its tests, and this plan status update.
0 commit comments