Skip to content

Commit 35b5bda

Browse files
Cursor plugin: AgentCrush remediation command and hosting/work-graph skill notes.
MCP execute and kernel sync tweaks for closed-loop tenant ops.
1 parent 9a419a7 commit 35b5bda

7 files changed

Lines changed: 38 additions & 6 deletions

File tree

‎MCP_QUICKSTART.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ If Cursor shows the plugin installed but `plugins/cache/agentstack` is empty, se
3737
| **Plugin MCP** (`plugin-agentstack-*` in Cursor) | Marketplace install; click **Connect** (G-A174) | After OAuth Connect on plugin panel |
3838
| **User MCP** (`~/.cursor/mcp.json` → `agentstack`) | Device Code `/agentstack-authorize` or profile API key | Bearer / X-API-Key in headers |
3939

40-
**Common trap:** Cursor agents call **plugin** MCP without Bearer. `/agentstack-authorize` writes `~/.cursor/mcp.json` only — run `node scripts/refresh-cursor-runtime.mjs --fix` (or re-authorize; device-code syncs cache) then **Reload Window** so plugin cache `mcp.json` gets the same Bearer. `mcp_auth` does **not** bridge Device Code. Fallback: Connect (G-A174) or `mcp-execute.mjs` below.
40+
**Common trap:** Cursor agents call **plugin** MCP without OAuth Connect. `/agentstack-authorize` writes Bearer in `~/.cursor/mcp.json` only — plugin runtime stays **URL-only** until Connect (G-A174). Use `mcp-execute.mjs` for Bearer-backed probes, or click **Connect** then Reload Window. `mcp_auth` does **not** bridge Device Code.
4141

4242
OAuth 2.1 Device Code via `/agentstack-authorize` (or `/agentstack-init`) → Bearer in `~/.cursor/mcp.json`.
4343

@@ -56,7 +56,7 @@ node scripts/mcp-execute.mjs --project-id 1 --execution-intent direct --focus-no
5656

5757
Implementation: `scripts/mcp-execute.mjs` + `lib/plugin-kernel/mcpExecuteHttp.mjs`.
5858

59-
**Tenant workspace (OAuth / password):** Connect or Device Code mints a **user-scoped** Bearer (JWT may show ecosystem `project_id=1`). Before tenant **mutations**, run recipe `mcp_session_setup` → set **`context.project_id`** → confirm **`auth.get_profile`** → **`mutation_allowed`** or **`session_ready`**. Call **`auth.switch_project`** only when **`required_client_action`** is **`apply_bearer`** (typical: project-pinned API key). Cursor hook **`pre-mcp-session-handoff.mjs`** runs REST switch only when a batch includes **`auth.switch_project`**. **ChatGPT-only OAuth:** if switch tokens are redacted, Disconnect → Connect after picking workspace, or Device Code.
59+
**Tenant workspace (OAuth / password):** One Bearer, many projects — set **`options.context.project_id`** per execute; **`jwt_project_aligned=false`** with **`mutation_allowed=true`** is normal (JWT often `project_id=1`). Do **not** `auth.switch_project` on every hop. SoT: monorepo `docs/architecture/MCP_UNIFIED_OPERATOR_SESSION.md` + recipe `mcp_session_setup` → **`auth.get_profile`** → **`preflight.check`**. **`auth.switch_project`** only when **`required_client_action=apply_bearer`** (project-pinned API key). Cursor hook **`pre-mcp-session-handoff.mjs`** runs REST switch only when a batch includes **`auth.switch_project`**. **ChatGPT-only OAuth:** if switch tokens are redacted, Disconnect → Connect after picking workspace, or Device Code.
6060

6161
## Lean `~/.cursor/mcp.json` shape
6262

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# AgentCrush remediation (894280)
2+
3+
Playbook: `GET /mcp/prompts/get?name=agentstack_agentcrush_remediation_v1&project_id=894280`
4+
5+
1. Bind `context.project_id=894280`.
6+
2. Run safe cycle: fork → single `env_uuid` batch for `script.*` → diff with active scripts → gates → promote (human gate).
7+
3. Platform doctor (local): `python agentstack-core/scripts/platform_tooling.py ecosystem doctor --json --project-id 894280`
8+
4. UI wire: `docs/plans/AGENTCRUSH_UI_HOSTED_WIRE.md` (tenant App Studio DNA via `ai_builder.source.patch`).
9+
10+
Do **not** promote without Lance approval (`generation.promote` on prod).

‎plugins/agentstack/lib/plugin-kernel/pluginMcpRuntimeSync.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,3 +268,6 @@ export async function pluginCacheBearerDrifted(_userCfg, opts = {}) {
268268
_driftAt = Date.now();
269269
return drifted;
270270
}
271+
272+
/** OAuth-only plugin runtime (clearer name for docs/agents). */
273+
export { syncPluginRuntimeMcpBearerFromUser as ensurePluginMcpOAuthOnly };

‎plugins/agentstack/skills/agentstack-agents-ai/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ Multi-step project goals: prompt `agentstack_closed_loop_autonomy` · genes `cor
219219
| `env_uuid_project_only` | Omit env_uuid or set home=project and retry. self and project_self are the session row and cannot take a sandbox slice. |
220220
| `graph_home_unknown` | home must be project, self, or project_self. Retry agents.plan_get or agents.plan_patch with one of those values. |
221221
| `graph_home_address_required` | Personal home needs a resolved session address. Pass home on the tool and ensure the operator session has user_id before patch. |
222-
| `plan_ops_parent_missing` | add_child parent_id is not in the graph — create the parent first or fix parent_id. |
222+
| `plan_ops_parent_missing` | add_child parent_id is not in the graph — create the parent first or fix parent_id. On an empty project graph (revision 0, no tasks), omit parent_id and send {op:add_child, node:{id, title, kind}} with if_match_revision:0 from plan_get; do not use op set for new ids. |
223223
| `plan_graph_children_exceeded` | Direct children per parent are capped (32). Flat parent_id storage counts siblings under each parent_id — not total graph nodes. Split into sub-groups or use agents.plan_propose decompose_node. |
224224
| `plan_graph_too_large` | The merged graph does not fit the JSON leaf (see graph_limits.inline_write_hard_limit_bytes, typically 512 KiB). Bodies spill near chunk_spill_target_bytes (~400 KiB). For huge prose use node.prompt/detail (not only meta.description), append_storage_ref (stubs inline text), reorder_children {parent_id,child_ids}, or storage file maps in meta.storage_refs. Cards keep ~200-char stubs after spill. Read one node with plan_get detail=body and node_id. Archive completed nodes (op archive) if titles/meta still overflow. Do not retry the same blob. Leaf heal ladder: agents.plan_compaction_preview → agents.plan_heal_leaf dry_run=true → apply. |
225225
| `plan_graph_oversize` | Plan graph exceeds size budget — agents.plan_compaction_preview then agents.plan_heal_leaf (dry_run then apply); archive completed subtrees or split objectives. |

‎plugins/agentstack/skills/agentstack-backend/SKILL.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ AgentStack is a **full backend ecosystem** exposed through ONE MCP tool: `agents
5353

5454
Pick the **primary** bucket first; consult others by reference for multi-step flows.
5555

56+
## MCP error recovery → operator report
57+
58+
When a failed `agentstack.execute` step includes `data.report_suggested`, offer a one-shot follow-up batch: `diagnostics.report` with the provided `prefill` (merge user summary). Distinct from `social.support.send` (tenant product) and `trust.feedback` (AgentNet). CLI: `mcp-execute.mjs` prints a hint when `report_suggested` is present.
59+
5660
**Disambiguation:** project treasury → `agentstack-project-wallet`; personal/commerce wallet → `agentstack-commerce`; inbound Stripe webhook → `agentstack-integrations` (never `@stripe/stripe-js` for AgentStack checkout); **SMTP/Resend email** → `agentstack-messaging` (`messaging.*`); in-app/Web Push → `agentstack-signals` (`notifications.send_push`). Cursor plugin sign-in → `/agentstack-authorize`, not `auth.login`. **Claude asks for scoped API key first** → stop — use MCP Connect (web) or Device Code `--scope-preset=full` per `auth.get_profile.auth_surface.client_auth_ladder`; scoped keys are for CI/automation (`apikeys.create` preset `agent_runner`) only. Product archetype first → `/agentstack-product-flow` or `docs/plugins/PRODUCT_BUILD_FLOW.md`.
5761

5862
## User request → action (hot paths)
@@ -226,7 +230,7 @@ Sync `agentstack.execute` is **60s for the whole batch** (`mcp_batch`) — not a
226230
## MCP guidance
227231

228232
- **Catalog:** `GET https://agentstack.tech/mcp/actions` (or `/agentstack-capability-matrix`) — never hard-code action counts.
229-
- **Execute:** one tool `agentstack.execute`; steps use canonical `action` ids from the catalog.
233+
- **Execute:** `agentstack.execute` for writes; `agentstack.read` for read/evaluate (same batch body, short wire schema). Steps use canonical `action` ids from the catalog.
230234
- **Prompts:** `agentstack_execute_budget`, `agentstack_write_modes`, `agentstack_read_bootstrap` via `GET /mcp/prompts/get`.
231235

232236
## References

‎plugins/agentstack/skills/agentstack-hosting/SKILL.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,9 @@ description: Use when the user wants to publish a static site, deploy HTML or ZI
1212
| "publish site" / "host HTML" / "/host-site" | `hosting.site.quick_start`, `hosting.deploy_files` | Vercel / Netlify one-off |
1313
| "single HTML landing" | recipe `mcp_hosting_static_landing_v1` | deploy_files without recipe |
1414
| "edit one CSS/HTML file on /s/" | `hosting.bucket.file.patch` (`search_replace`); recipe `mcp_hosting_edit_text_file_v1` — no prior GET; response `gzip_sibling: refreshed` + optional `cache_bust` — **never** manual gzip or `bulk_delete` `.gz` | `storage.upload` or full `hosting.deploy_files` |
15-
| "React/Vite dist upload" | `hosting.site.import_archive`, `hosting.site.upload_grant` + HTTP POST, recipe `mcp_hosting_react_dist_v1` | `hosting.deploy_files`, `hosting.storage.import_folder`, MCP npm build |
15+
| "React/Vite dist upload" | `hosting.site.import_archive`, `hosting.site.upload_grant` + grant POST; recipe `mcp_hosting_react_dist_v1` for ready `dist/` ZIP | `hosting.deploy_files`, `hosting.storage.import_folder` |
16+
| "App Studio game / WebGL after Vite build" | `ai_builder.build.enqueue` → `build.status` completed → `hosting.project.status` → **`ai_builder.publish`** — live URL = **`public_url_absolute`** (`https://agentstack.tech/s/{pid}/{slug}/`) | `hosting.site.quick_start` HTML stub for full SPA |
17+
| "React/Vite sources / GitHub URL" | Same `hosting.site.import_archive` (source ZIP or git `source_url`) → poll `hosting.site.build_status` when response has `job_id`; recipe `mcp_hosting_workspace_build_v1` | Client-side `npm run build`; separate `pull_upstream` without import |
1618
| "deploy ZIP" / "static site" | `hosting.site.import_archive` or `hosting.site.upload_grant`; CLI `agentstack hosting deploy --zip` | `hosting.deploy_files` (no unzip), Custom S3 |
1719
| "rollback" / "promote release" | `hosting.release.promote`, `hosting.release.list` | Manual bucket swap |
1820
| "import folder to site" | `hosting.storage.import_folder` | Re-upload all files |
@@ -68,7 +70,8 @@ import { GuidanceClient } from '@agentstack/sdk/guidance';
6870
- **Ladder first:** recipe `mcp_site_growth_v1` → read `hosting.project.status` → follow `next_actions[0]` and `hosting_plane_chooser` (visitor auth, gzip, bucket_id omission rules).
6971
- **No `releases` MCP domain** — publish = `hosting.deploy_files` / `hosting.site.quick_start`; history/rollback = `hosting.release.list` / `hosting.release.promote` (aliases: `hosting.publish`, `releases.list`).
7072
- **Control panel:** `/dev/projects/{id}/storage/sites` (or `/user/...` for user shell) — not legacy `/hosting`.
71-
- **Canonical URL:** `/s/{project_id}/{bucket_name}/` — wait for `edge_ready` before telling the user the site is live.
73+
- **Canonical URL:** `https://agentstack.tech/s/{project_id}/{bucket_name}/` (`public_path` = `/s/{project_id}/{bucket_name}/`) — same as `hosting.project.status` → `sites.primary_public_url`. Wait for `edge_ready` before telling the user the site is live.
74+
- **App Studio publish:** static landing only → `hosting.site.quick_start`; built Vite/game → `ai_builder.publish` after `build.status` = `completed` (omit `bucket_id` when primary site exists).
7275
- **Quota triage:** `hosting.project.status` → `quota.artifact_bytes_used_gate` vs limit; then `hosting.quota.breakdown` (alias `hosting.bucket.usage`); if over limit → `hosting.gc.orphans` dry_run → `hosting.quota.recount` dry_run. Never bulk_delete `assets/` manually — use `hosting.site.prune` when available.
7376
- **Deploy honesty:** if `publish_failed` or `success: false`, read `live_changed` and `next_action`; do not treat step as ✅.
7477
- Site bytes count toward the owner storage pool — `storage.get_quota` + hosting gate fields on storage hub summary.

‎scripts/mcp-execute.mjs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,18 @@ async function main() {
213213
}
214214
const baseUrl = resolveMcpBaseUrl(cfg);
215215
const out = await postAgentstackExecute(baseUrl, authHeaders, anchored);
216+
const steps = out?.data?.steps ?? out?.steps;
217+
if (Array.isArray(steps)) {
218+
for (const step of steps) {
219+
const sug = step?.data?.report_suggested ?? step?.report_suggested;
220+
if (sug?.next_action?.action === 'diagnostics.report') {
221+
console.error(
222+
'Hint: MCP returned report_suggested — run diagnostics.report with the prefill payload.',
223+
);
224+
break;
225+
}
226+
}
227+
}
216228
console.log(JSON.stringify(out, null, 2));
217229
}
218230

0 commit comments

Comments
 (0)