@plasm_lang/vercel-agent 0.3.121 → 0.3.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasm_lang/vercel-agent",
-  "version": "0.3.121",
+  "version": "0.3.124",
   "description": "Catalog-native TypeScript agent framework (Plasm CGS/CML, Vercel AI SDK, Nitro-oriented)",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -65,7 +65,7 @@
   "dependencies": {
     "@ai-sdk/otel": "1.0.14",
     "@opentelemetry/api": "^1.9.0",
-    "@plasm_lang/engine": "^0.3.121",
+    "@plasm_lang/engine": "^0.3.124",
     "@vercel/blob": "^0.27.3",
     "@vercel/connect": "^0.2.6",
     "@vercel/kv": "^3.0.0",

package/src/nitro/copy-vercel-function-assets.ts

@@ -23,7 +23,10 @@ export async function copyVercelFunctionAssets(options: {
     return;
   }
 
-  await cp(options.agentRoot, path.join(funcDir, "agent"), { recursive: true });
+  await cp(options.agentRoot, path.join(funcDir, "agent"), {
+    recursive: true,
+    dereference: true,
+  });
 
   await copyNativeEnginePackages(options.projectRoot, funcDir);
 

package/templates/mcp-radar/agent/catalogs/proof/README.md

@@ -0,0 +1,108 @@
+# Proof catalog (Plasm)
+
+This package targets the **Proof agent HTTP surface** described in [EveryInc/proof-sdk](https://github.com/EveryInc/proof-sdk) (`AGENT_CONTRACT.md`, `docs/agent-docs.md`). The SDK documents many routes under `/documents/:slug/…`; **hosted `www.proofeditor.ai` serves those agent operations under `/api/agent/:slug/…`** (plain `/documents/:slug/…` often returns **404** HTML). Share flows still use **`GET /d/:slug`** (JSON / markdown); **`POST /share/markdown`** creates a new shared doc. **`POST /api/bridge/report_bug`** is product bug intake.
+
+Author and maintain **`mappings.yaml`** directly (paths, query, headers, body CML). Validate after edits:
+
+```bash
+cargo run -p plasm-cli --bin plasm -- schema validate apis/proof
+```
+
+## Local Proof SDK
+
+From a clone of proof-sdk:
+
+```bash
+npm install
+npm run serve   # API default http://127.0.0.1:4000 (see proof-sdk README)
+```
+
+Point Plasm at that origin (overrides `domain.yaml` `http_backend` for the session):
+
+```bash
+export PROOF_API_TOKEN=   # if PROOF_SHARE_MARKDOWN_AUTH_MODE=api_key
+cargo run -p plasm --bin plasm-mcp -- --schema apis/proof --http --port 3000 --backend http://127.0.0.1:4000
+```
+
+If your local SDK does not mirror **`/api/agent/:slug/*`**, adjust **`mappings.yaml`** paths for that backend (hosted **`www.proofeditor.ai`** is the default `http_backend` target).
+
+## curl smoke tests
+
+Create a document (JSON):
+
+```bash
+curl -sS -X POST http://127.0.0.1:4000/documents \
+  -H 'Content-Type: application/json' \
+  -d '{"markdown":"# Hello\n\nfrom curl.","title":"smoke"}' | jq .
+```
+
+Share preview `GET /d/:slug` (`document_get` and `document_get_markdown` both use **`Accept: application/json`** in Plasm mappings so responses decode as JSON rows; query `token` when using link access):
+
+```bash
+SLUG=…
+TOKEN=…   # optional; maps to Plasm `share_token`
+curl -sS -H 'Accept: application/json' "http://127.0.0.1:4000/d/$SLUG?token=$TOKEN" | jq .
+```
+
+Optional SDK-only raw body (not used by the Plasm catalog):
+
+```bash
+curl -sS -H 'Accept: text/markdown' "http://127.0.0.1:4000/d/$SLUG?token=$TOKEN"
+```
+
+Agent state + snapshot (canonical `documents` tree):
+
+```bash
+curl -sS -H "Authorization: Bearer $PROOF_API_TOKEN" -H 'Accept: application/json' \
+  "http://127.0.0.1:4000/documents/$SLUG/state" | jq .
+curl -sS -H "Authorization: Bearer $PROOF_API_TOKEN" -H 'Accept: application/json' \
+  "http://127.0.0.1:4000/documents/$SLUG/snapshot" | jq .
+```
+
+## Domain ↔ SDK notes
+
+- **Optimistic locking:** block-level mutations use Proof SDK **`baseRevision`** (integer) from `GET …/snapshot` — typed in teaching table via shared `values.nv_proof_int` on `EditorState.revision`. Structured `POST …/edit` paths that surface **`baseUpdatedAt`** should use the same short-string primitive (`values.nv_proof_str`) when that parameter is modeled on the capability.
+- **Share token:** optional capability parameter `share_token` is wired as query **`token`** on requests that support link-style access.
+- **Session bind (HTTP/MCP execute):** call **`document_share_bind`** once per document with the share URL (`…/d/{slug}?token=…`) or explicit `share_token`; the host keeps Bearer + mirrored `?token=` in execute session material so later lines stay token-free — see [instance-share-auth.md](../../../docs/instance-share-auth.md).
+- **`baseToken` / `/ops`:** after **`editor_state_get`**, the host stores **`baseToken`** in the same execute session and merges it into CML as **`base_token`** for **`/ops`** bodies (optional **`base_token=`** on a line overrides once). Re-run **`editor_state_get`** after stale-precondition errors; **`document_share_bind`** clears the stored token — see [instance-share-auth.md](../../../docs/instance-share-auth.md#proof-mutation-precondition-basetoken).
+- **Agent identity:** `agent_id` is sent as **`X-Agent-Id`** on mutating routes.
+- **Idempotency:** explicit capability parameter `idempotency_key` is sent as **`Idempotency-Key`** when set. On HTTP/MCP execute, Plasm also injects CML env keys `plasm_execute_prompt_hash` and `plasm_execute_session_id`; the generated **`document_edit_*`** mappings derive a default `Idempotency-Key` from those plus mutation fields (`baseRevision`, refs, text, …) when the caller omits `idempotency_key`. Align with Proof rollout: read `contract.idempotencyRequired` and `contract.mutationStage` from `GET …/state` — during required stages the wire must still carry a key (host-derived or explicit). Same key with a different payload hash yields `IDEMPOTENCY_KEY_REUSED`.
+- **`document_edit_find_replace_in_doc`:** CML currently emits a single structured `replace` op; optional sweep fields in the domain are not yet mapped — extend `mappings.yaml` when you confirm the live JSON shape.
+- **Bug intake:** mappings use **`POST /api/bridge/report_bug`** with **`Accept: application/json`** (hosted `www.proofeditor.ai` and apex `proofeditor.ai`). Older **`POST /report/bug`** returned **404** in production probes — do not revert without re-verifying. **`bug_report_submit`** and **`document_bug_report_submit`** require a **`report`** field in the JSON body (markdown-sized bug text); **`document_bug_report_submit`** also sends **`slug`** plus optional share **`token`** query when `share_token` is set — do not create a throwaway document solely to carry the report; pass **`report=`** on the invoke line.
+- **Suggestions (hosted `www.proofeditor.ai`):** use **`POST /api/agent/:slug/ops`** with **`type: suggestion.add`** / **`suggestion.accept`** / **`suggestion.reject`** (see proof-sdk `docs/agent-docs.md`). **`POST …/bridge/suggestions`** and **`…/bridge/marks/{accept,reject}`** return **404** on production probes — the Plasm mappings follow **`/ops`**. Capabilities **`annotation_suggestion_insert`**, **`annotation_suggestion_delete`**, and **`annotation_suggestion_replace`** use normal **`agent_id=` / `by=` / `quote=` / …** dotted-call args (no root union payload).
+- **Comments (hosted):** **`annotation_comment_add`**, **`annotation_comment_reply`**, and **`annotation_comment_resolve`** use **`POST /api/agent/:slug/ops`** (`comment.add` / `comment.reply` / `comment.resolve`) — not **`…/bridge/comments`**, which hosted rejects for agent slugs. **`collaboration_event_query`** rows decode from **`events/pending`** (`type`, `createdAt`, `data`, `actor`, ack metadata).
+- **`annotation_comment_unresolve`** / **`annotation_comment_batch_apply`** / other **`/ops`** shapes remain **best-effort** — verify against your Proof revision if the server returns 4xx.
+
+## Hosted production checks (manual)
+
+Probed **2026-05** with anonymous requests (no doc secrets):
+
+| Check | Result |
+| ----- | ------ |
+| `GET https://proofeditor.ai/` vs `https://www.proofeditor.ai/` | **200** / **200** |
+| `GET …/documents/{slug}/state` vs `…/api/agent/{slug}/state` on **www** (unknown slug, no token) | **404** HTML vs **401/404 JSON** — hosted slug-scoped reads use **`/api/agent/…`** in this catalog |
+| `POST https://www.proofeditor.ai/report/bug` | **404** |
+| `POST https://www.proofeditor.ai/api/bridge/report_bug` | **200** with JSON validation envelope (`needs_more_info` on minimal `{}` body) |
+
+**Presence:** use **`POST /api/agent/:slug/presence`** with **`Authorization: Bearer`** + **`X-Agent-Id`** and JSON **`{ "status": "online" }`** (default when `presence_status` is omitted). On **`www.proofeditor.ai`**, **`POST /documents/:slug/presence`** returns **404** — Plasm maps **`presence_update`** to **`/api/agent/…`** only. **`…/bridge/presence`** is for the desktop/SDK bridge — it does **not** substitute for agent join on hosted collab UIs.
+
+## Incremental teaching waves (execute / MCP)
+
+To keep prompts small and monotonic (`e#` / `m#` / `p#`), open sessions with a **tight seed list** and expand in waves ([incremental-teaching-prompts.md](../../../docs/incremental-teaching-prompts.md)):
+
+1. **Wave 1 — `Document` and/or `ShareLink`:** seed `{api: proof, entity: ShareLink}` when the program calls **`share_link_create`** — the teaching table always includes that create (and any query/get on ShareLink) even when the stable `intent` omits “share link” tokens. Document-only seeds expose Document reads/creates on the seeded entity; relation closure does not add ShareLink without a seed or relation.
+2. **Wave 2 — `EditorState`:** `editor_state_get` for revision / contract / marks before mutating.
+3. **Wave 3 — `Block`:** `block_query` + `document_edit_v2` for structural edits.
+4. **Wave 4 — `CollaborationEvent`:** `collaboration_event_query` + `collaboration_event_ack` for polling.
+
+Federation and exact seed lists follow host tooling (`plasm_context` seeds, HTTP execute entities).
+
+## Eval cases (form coverage)
+
+```bash
+cargo run -p plasm-eval -- coverage --schema apis/proof --cases apis/proof/eval/cases.yaml
+```
+
+## Hosted Proof
+
+The default `http_backend` in `domain.yaml` is `https://www.proofeditor.ai`. **`mappings.yaml` uses `/api/agent/:slug/…`** for slug-scoped reads/edits/ops/events/presence (anything that used to hit `/documents/:slug/…` on the local SDK). **`document_get`**, **`document_get_markdown`**, and **`document_share_bind`** stay on **`GET /d/:slug`**. **`share_link_create`** maps to **`POST /share/markdown`**. Bug intake uses **`/api/bridge/report_bug`** as above.