@recapt/mcp 0.0.14-beta → 0.0.16-beta
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/commands/setup-self-healing-gh.js +1 -1
- package/dist/cli/commands/skill.d.ts +3 -3
- package/dist/cli/commands/skill.js +24 -11
- package/dist/index.js +28 -1
- package/dist/tools/catalog/toolCatalog.json +2080 -0
- package/dist/tools/diagnostic.js +5 -1
- package/dist/tools/healingRun.d.ts +6 -0
- package/dist/tools/healingRun.js +313 -0
- package/dist/tools/triageSessions.js +3 -1
- package/dist/tools/upgradeOptions.d.ts +7 -0
- package/dist/tools/upgradeOptions.js +67 -0
- package/package.json +1 -1
- package/skills/self-healing.md +237 -14
package/skills/self-healing.md
CHANGED
|
@@ -17,6 +17,116 @@ This is a **comprehensive site improvement workflow**. Only use it when the user
|
|
|
17
17
|
- Investigating a specific issue ("why are users rage clicking here?")
|
|
18
18
|
For specific requests, use the appropriate tools directly — let the conversation guide which tools to call.
|
|
19
19
|
|
|
20
|
+
## Run Tracking
|
|
21
|
+
|
|
22
|
+
At the start of each healing session, register the run to track progress and outcomes:
|
|
23
|
+
|
|
24
|
+
- Search: "healing run" → `start_healing_run`, `update_healing_run`, `record_healing_action`
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
const response = await start_healing_run({
|
|
28
|
+
trigger_type: "manual", // or "github_actions", "cron", "api"
|
|
29
|
+
trigger_metadata: { ... }, // optional: branch, actor, etc.
|
|
30
|
+
phases: [
|
|
31
|
+
{ name: "diagnose", status: "pending" },
|
|
32
|
+
{ name: "investigate", status: "pending" },
|
|
33
|
+
{ name: "fix", status: "pending" },
|
|
34
|
+
{ name: "track", status: "pending" }
|
|
35
|
+
]
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
// IMPORTANT: Extract the run ID from the response
|
|
39
|
+
const run_id = response.id; // e.g., "682d1a2b3c4d5e6f7a8b9c0d"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
This creates a run record visible in the Healing Runs UI. **You must update the run as you progress through each phase.**
|
|
43
|
+
|
|
44
|
+
### Phase Progress Updates
|
|
45
|
+
|
|
46
|
+
Update the run status at each phase transition. Always pass the complete phases array with updated statuses:
|
|
47
|
+
|
|
48
|
+
**After starting diagnose:**
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
update_healing_run({
|
|
52
|
+
run_id: "<run_id>",
|
|
53
|
+
phases: [
|
|
54
|
+
{ name: "diagnose", status: "running", startedAt: new Date().toISOString() },
|
|
55
|
+
{ name: "investigate", status: "pending" },
|
|
56
|
+
{ name: "fix", status: "pending" },
|
|
57
|
+
{ name: "track", status: "pending" }
|
|
58
|
+
]
|
|
59
|
+
})
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**After completing diagnose (before investigate):**
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
update_healing_run({
|
|
66
|
+
run_id: "<run_id>",
|
|
67
|
+
phases: [
|
|
68
|
+
{ name: "diagnose", status: "completed", completedAt: new Date().toISOString(), output: { issuesFound: 5, opportunitiesFound: 3 } },
|
|
69
|
+
{ name: "investigate", status: "running", startedAt: new Date().toISOString() },
|
|
70
|
+
{ name: "fix", status: "pending" },
|
|
71
|
+
{ name: "track", status: "pending" }
|
|
72
|
+
],
|
|
73
|
+
summary: { issuesFound: 5 }
|
|
74
|
+
})
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**After completing investigate (before fix):**
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
update_healing_run({
|
|
81
|
+
run_id: "<run_id>",
|
|
82
|
+
phases: [
|
|
83
|
+
{ name: "diagnose", status: "completed", completedAt: "...", output: { ... } },
|
|
84
|
+
{ name: "investigate", status: "completed", completedAt: new Date().toISOString(), output: { issuesInvestigated: 5, issuesValidated: 4 } },
|
|
85
|
+
{ name: "fix", status: "running", startedAt: new Date().toISOString() },
|
|
86
|
+
{ name: "track", status: "pending" }
|
|
87
|
+
]
|
|
88
|
+
})
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**After completing fix (before track):**
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
update_healing_run({
|
|
95
|
+
run_id: "<run_id>",
|
|
96
|
+
phases: [
|
|
97
|
+
{ name: "diagnose", status: "completed", completedAt: "...", output: { ... } },
|
|
98
|
+
{ name: "investigate", status: "completed", completedAt: "...", output: { ... } },
|
|
99
|
+
{ name: "fix", status: "completed", completedAt: new Date().toISOString(), output: { fixesApplied: 3, prsCreated: 2 } },
|
|
100
|
+
{ name: "track", status: "running", startedAt: new Date().toISOString() }
|
|
101
|
+
],
|
|
102
|
+
summary: { issuesFound: 5, issuesFixed: 3, prsCreated: 2 }
|
|
103
|
+
})
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**After completing track (run complete):**
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
update_healing_run({
|
|
110
|
+
run_id: "<run_id>",
|
|
111
|
+
status: "completed",
|
|
112
|
+
completed_at: new Date().toISOString(),
|
|
113
|
+
duration_ms: <elapsed_time>,
|
|
114
|
+
phases: [
|
|
115
|
+
{ name: "diagnose", status: "completed", completedAt: "...", output: { ... } },
|
|
116
|
+
{ name: "investigate", status: "completed", completedAt: "...", output: { ... } },
|
|
117
|
+
{ name: "fix", status: "completed", completedAt: "...", output: { ... } },
|
|
118
|
+
{ name: "track", status: "completed", completedAt: new Date().toISOString(), output: { deploymentsConfirmed: 2 } }
|
|
119
|
+
],
|
|
120
|
+
summary: {
|
|
121
|
+
issuesFound: 5,
|
|
122
|
+
issuesFixed: 3,
|
|
123
|
+
issuesDeferred: 1,
|
|
124
|
+
issuesDismissed: 1,
|
|
125
|
+
prsCreated: 2
|
|
126
|
+
}
|
|
127
|
+
})
|
|
128
|
+
```
|
|
129
|
+
|
|
20
130
|
## Workflow
|
|
21
131
|
|
|
22
132
|
### 0. Check Pending Fixes (if returning)
|
|
@@ -41,8 +151,12 @@ If fixes have sufficient data:
|
|
|
41
151
|
|
|
42
152
|
### 1. Diagnose
|
|
43
153
|
|
|
154
|
+
**Update phase status to "running" before starting.**
|
|
155
|
+
|
|
44
156
|
Start with `run_full_diagnostic` (always available) to get a prioritized list of issues across the site.
|
|
45
157
|
|
|
158
|
+
After diagnosis completes, **update the phase to "completed"** and set `summary.issuesFound`.
|
|
159
|
+
|
|
46
160
|
### 2. Analyze Flows
|
|
47
161
|
|
|
48
162
|
After diagnosing issues, proactively look for flow optimization opportunities — even when nothing is "broken."
|
|
@@ -109,6 +223,8 @@ Present opportunities alongside issues, clearly labeled:
|
|
|
109
223
|
|
|
110
224
|
### 3. Investigate
|
|
111
225
|
|
|
226
|
+
**Update phase status: mark "diagnose" as completed, "investigate" as running.**
|
|
227
|
+
|
|
112
228
|
For each high-priority issue or opportunity, search for investigation tools:
|
|
113
229
|
|
|
114
230
|
- Search: "investigate issue" → `investigate_issue`, `validate_issue`
|
|
@@ -128,6 +244,8 @@ Present findings to the user. Not all detected issues need fixing:
|
|
|
128
244
|
- Some flow patterns may be acceptable (e.g., users comparing options before deciding)
|
|
129
245
|
- Ask the user which issues and opportunities to address before proceeding
|
|
130
246
|
|
|
247
|
+
**After triage, update phase status: mark "investigate" as completed, "fix" as running.**
|
|
248
|
+
|
|
131
249
|
### 5. Fix
|
|
132
250
|
|
|
133
251
|
Implement code changes to address issues and opportunities. After making changes:
|
|
@@ -135,6 +253,24 @@ Implement code changes to address issues and opportunities. After making changes
|
|
|
135
253
|
- Search: "propose fix" → `propose_fix`, `get_similar_fixes`, `get_fix_history`
|
|
136
254
|
- Log the remediation so recapt can track its effectiveness
|
|
137
255
|
|
|
256
|
+
**Note:** `propose_fix` accepts either `issue_id` (for formal issues) or `page_path` + `element_selector` (for element friction fixes without a formal issue).
|
|
257
|
+
|
|
258
|
+
**Record each action in the healing run:**
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
record_healing_action({
|
|
262
|
+
run_id: "<run_id>",
|
|
263
|
+
issue_id: "<issue_id>", // optional - omit for element friction fixes
|
|
264
|
+
action_type: "code_fix", // or "needs_more_data", "dismissed", "marked_intended"
|
|
265
|
+
hypothesis: "The checkout button is unresponsive due to a JS error...",
|
|
266
|
+
expected_improvement: "Fixing the error handler should reduce rage clicks by 50%",
|
|
267
|
+
code_changes: [{ file: "checkout.tsx", diff: "...", linesAdded: 5, linesRemoved: 2 }],
|
|
268
|
+
pr_url: "https://github.com/...",
|
|
269
|
+
pr_number: 123,
|
|
270
|
+
remediation_id: "<remediation_id>" // from propose_fix response.id
|
|
271
|
+
})
|
|
272
|
+
```
|
|
273
|
+
|
|
138
274
|
For flow optimizations, common fixes include:
|
|
139
275
|
|
|
140
276
|
- Adding missing information to reduce backtracking
|
|
@@ -145,10 +281,36 @@ For flow optimizations, common fixes include:
|
|
|
145
281
|
|
|
146
282
|
### 6. Track
|
|
147
283
|
|
|
284
|
+
**Update phase status: mark "fix" as completed, "track" as running.**
|
|
285
|
+
|
|
148
286
|
Mark fixes as deployed so recapt can measure impact:
|
|
149
287
|
|
|
150
288
|
- Search: "deployment" → `confirm_deployment`, `evaluate_fix`, `list_pending_fixes`
|
|
151
289
|
|
|
290
|
+
**Complete the healing run when done:**
|
|
291
|
+
|
|
292
|
+
```
|
|
293
|
+
update_healing_run({
|
|
294
|
+
run_id: "<run_id>",
|
|
295
|
+
status: "completed",
|
|
296
|
+
completed_at: new Date().toISOString(),
|
|
297
|
+
duration_ms: <elapsed_time>,
|
|
298
|
+
phases: [
|
|
299
|
+
{ name: "diagnose", status: "completed", ... },
|
|
300
|
+
{ name: "investigate", status: "completed", ... },
|
|
301
|
+
{ name: "fix", status: "completed", ... },
|
|
302
|
+
{ name: "track", status: "completed", completedAt: new Date().toISOString() }
|
|
303
|
+
],
|
|
304
|
+
summary: {
|
|
305
|
+
issuesFound: 5,
|
|
306
|
+
issuesFixed: 3,
|
|
307
|
+
issuesDeferred: 1,
|
|
308
|
+
issuesDismissed: 1,
|
|
309
|
+
prsCreated: 2
|
|
310
|
+
}
|
|
311
|
+
})
|
|
312
|
+
```
|
|
313
|
+
|
|
152
314
|
### 7. Learn
|
|
153
315
|
|
|
154
316
|
Build site knowledge for future reference:
|
|
@@ -171,17 +333,78 @@ If the user agrees:
|
|
|
171
333
|
|
|
172
334
|
## Tool Discovery Reference
|
|
173
335
|
|
|
174
|
-
| Phase | Search Query | Tools
|
|
175
|
-
| ------------- | ------------------- |
|
|
176
|
-
|
|
|
177
|
-
|
|
|
178
|
-
|
|
|
179
|
-
|
|
|
180
|
-
|
|
|
181
|
-
|
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
336
|
+
| Phase | Search Query | Tools |
|
|
337
|
+
| ------------- | ------------------- | --------------------------------------------------------------------------------------- |
|
|
338
|
+
| Run Tracking | "healing run" | `start_healing_run`, `update_healing_run`, `record_healing_action`, `list_healing_runs` |
|
|
339
|
+
| Check Pending | "pending fixes" | `list_pending_fixes`, `evaluate_fix` |
|
|
340
|
+
| Diagnose | (always available) | `run_full_diagnostic` |
|
|
341
|
+
| Journey | "journey patterns" | `get_journey_patterns` |
|
|
342
|
+
| Funnels | "analyze funnel" | `analyze_funnel` |
|
|
343
|
+
| Flows | "analyze flow" | `analyze_flow`, `get_flow_friction` |
|
|
344
|
+
| Personas | "personas" | `discover_personas` |
|
|
345
|
+
| Compare | "compare cohorts" | `compare_cohorts` |
|
|
346
|
+
| Investigate | "investigate issue" | `investigate_issue`, `validate_issue` |
|
|
347
|
+
| Triage | "dismiss issue" | `dismiss_issue`, `mark_intended_behavior` |
|
|
348
|
+
| Fix | "propose fix" | `propose_fix`, `get_similar_fixes`, `get_fix_history` |
|
|
349
|
+
| Track | "deployment" | `confirm_deployment`, `evaluate_fix`, `list_pending_fixes` |
|
|
350
|
+
| Learn | "site knowledge" | `get_site_knowledge`, `add_site_knowledge` |
|
|
351
|
+
|
|
352
|
+
## Response Formats
|
|
353
|
+
|
|
354
|
+
Healing run tools return objects with an `id` field. Extract and store these IDs for subsequent calls.
|
|
355
|
+
|
|
356
|
+
**Note:** Response formats for `propose_fix` and `add_site_knowledge` are documented in their tool descriptions (discoverable via `search_tools`).
|
|
357
|
+
|
|
358
|
+
### start_healing_run
|
|
359
|
+
|
|
360
|
+
```json
|
|
361
|
+
{
|
|
362
|
+
"id": "682d1a2b3c4d5e6f7a8b9c0d",
|
|
363
|
+
"status": "running",
|
|
364
|
+
"trigger": { "type": "manual", "metadata": {} },
|
|
365
|
+
"phases": [
|
|
366
|
+
{
|
|
367
|
+
"name": "diagnose",
|
|
368
|
+
"status": "pending",
|
|
369
|
+
"startedAt": null,
|
|
370
|
+
"completedAt": null,
|
|
371
|
+
"output": {}
|
|
372
|
+
}
|
|
373
|
+
],
|
|
374
|
+
"summary": {
|
|
375
|
+
"issuesFound": 0,
|
|
376
|
+
"issuesFixed": 0,
|
|
377
|
+
"issuesDeferred": 0,
|
|
378
|
+
"issuesDismissed": 0,
|
|
379
|
+
"prsCreated": 0
|
|
380
|
+
},
|
|
381
|
+
"startedAt": "2026-04-26T19:00:00.000Z",
|
|
382
|
+
"completedAt": null,
|
|
383
|
+
"durationMs": null,
|
|
384
|
+
"createdAt": "2026-04-26T19:00:00.000Z"
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
**Extract:** `response.id` → use as `run_id` in `update_healing_run` and `record_healing_action`
|
|
389
|
+
|
|
390
|
+
### record_healing_action
|
|
391
|
+
|
|
392
|
+
```json
|
|
393
|
+
{
|
|
394
|
+
"id": "682d1a2b3c4d5e6f7a8b9c11",
|
|
395
|
+
"healingRunId": "682d1a2b3c4d5e6f7a8b9c0d",
|
|
396
|
+
"issueId": "682d1a2b3c4d5e6f7a8b9c0f",
|
|
397
|
+
"actionType": "code_fix",
|
|
398
|
+
"outcome": {
|
|
399
|
+
"hypothesis": "...",
|
|
400
|
+
"expectedImprovement": "...",
|
|
401
|
+
"codeChanges": [...],
|
|
402
|
+
"prUrl": "https://github.com/...",
|
|
403
|
+
"prNumber": 123
|
|
404
|
+
},
|
|
405
|
+
"remediationId": "682d1a2b3c4d5e6f7a8b9c0e",
|
|
406
|
+
"createdAt": "2026-04-26T19:45:00.000Z"
|
|
407
|
+
}
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
**Note:** This automatically increments the run's summary counters based on `action_type`.
|