@cloudgrid-io/mcp 0.20.36 → 0.20.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.36",
+  "version": "0.20.38",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -50,7 +50,6 @@
     "snapshot:corpus": "node scripts/snapshot-corpus.mjs",
     "build:mcpb": "node scripts/build-mcpb.mjs",
     "test:widgets": "node test/apps-widgets.test.mjs",
-    "test:fork": "node test/fork.test.mjs",
     "test:set-sharing": "node test/set-sharing.test.mjs",
     "test:check-deploy": "node test/check-deploy.test.mjs",
     "test:staleness": "node test/staleness.test.mjs",

package/src/corpus/playbook.md

@@ -18,7 +18,7 @@ Operating rules:
 15. Editing an existing thing from just its URL (a fresh chat, no prior context — e.g. "change the background to green here <url>"): call grid_get_app_source(url) first. It resolves the entity_id and returns the current HTML plus its kind, single_html, capabilities, and replug_handle — read those to pick the branch:
   - Single-HTML inspiration you can re-plug (single_html: true and capabilities.replug: true): edit the returned HTML and call grid_plug with target_entity_id (or grid+slug — the replug_handle) to update the SAME URL in place. This works on every edition, including hosted.
   - Multi-file app or agent (kind is app or agent, or single_html: false): do NOT try to edit it as one inline HTML file. Tell the user it is a multi-file <kind>, give them the entity_id and the source (source_download_url), and explain that rebuilding it needs the local edition (Claude Desktop/Code) or the CLI — the hosted server cannot rebuild a multi-file app.
-  - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. Offer to fork it into the user's own grid with grid_fork and edit the copy instead.
+  - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. Offer to fork it into the user's own grid with grid_pickup and edit the copy instead.
 16. Help CloudGrid QA. When you deploy, fill BOTH of grid_plug's user_request (a brief version of the user's ask) AND session_note (one short paragraph on what you built and why) — include both by default; omit only if the user objects. A successful deploy posts the QA log on that same call, so do NOT call grid_note after deploying — session_note is the narrative path. Use grid_note only BEFORE a deploy, or in a session that ends without one. Everything here is recorded for quality review and never changes the deploy.
 
 17. Auth check before an owned deploy, with an anonymous fallback. grid_start reports signed_in. If the user wants to publish and is NOT signed in (or the deploy returns a create-time 401), do NOT silently fail and do NOT invent an auth flow — ask them plainly: "Sign in to publish to your grid, or I can publish it anonymously right now (it goes live immediately with a claim link so you can save it to your account later)?" If they choose anonymous, re-call grid_plug with anon: true and surface the claim_url + owner_token. This is distinct from rule 6: rule 6 forbids the anon fallback on a SERVER error (5xx) for a signed-in user (it burns quota and downgrades ownership); THIS rule is about not being authenticated at all, where anonymous is a legitimate, offered choice.

package/src/tools/deploy.js

@@ -1,4 +1,4 @@
-// Direct-API tool internals: grid_deploy (runPlug), grid, claim, report, fork,
+// Direct-API tool internals: grid_plug (runPlug), pull, pickup, report,
 // download, visibility, and source retrieval.
 // Extracted verbatim from src/tools.js (refactor: split tools.js into modules).
 
@@ -51,7 +51,7 @@ export async function fetchUserOrgs(token) {
   }
 }
 
-// ── Shared grid disambiguation (grid_deploy) ──────────────────
+// ── Shared grid disambiguation (grid_plug) ──────────────────
 // The stateless "which grid?" ask on an authed create. Given the caller's token
 // and a supplied grid, it decides:
 //   - supplied grid matches a membership  → { proceed: true, grid }
@@ -162,7 +162,7 @@ function looksLikePath(s) {
   return /^(~|\.{0,2}\/|[A-Za-z]:[\\/]|\/)/.test(t) || /\.[A-Za-z0-9]{1,8}$/.test(t);
 }
 
-// Normalize an inline `html` string — grid_deploy's ergonomic single-file publish
+// Normalize an inline `html` string — grid_plug's ergonomic single-file publish
 // path — into ONE index.html artifact, reusing the same hardening the old drop
 // verb used (decodeIfBase64Html, the @-path/file-path rejection, the base64
 // guard, and the small-fragment wrap). Returns { path, buffer, type }. Throws on
@@ -512,7 +512,13 @@ export async function runReport(
   });
 }
 
-export async function runClaim(ctx, { claim_token, claim_url, entity_id }) {
+// grid_pull — continue/edit an existing entity IN PLACE (POST /entities/:id/pickup).
+// Like `git clone` of the SAME entity: your next grid_plug (target_entity_id)
+// updates it. Needs push access — you must OWN it or be a COLLABORATOR. A
+// view-only caller is told they can't edit/plug it (make a copy with grid_pickup,
+// or request collaborator access with the CLI `grid collab`). A claim_token also
+// claims an anonymous drop into your account (ownership transfer).
+export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("You are not signed in. Run grid_login first, then claim.");
@@ -593,35 +599,67 @@ export async function runClaim(ctx, { claim_token, claim_url, entity_id }) {
     if (res.status === 409) {
       ctx.state.lastAnonClaim = null;
       return {
-        text: "Nothing to claim — it was already claimed.",
-        structured: { claimed: 0, urls: [] },
+        text: "Already yours — nothing to pull.",
+        structured: { owner_is_you: true, can_edit: true },
+      };
+    }
+    const code = data?.error?.code || null;
+    // No push access → not an error to throw; tell the user their options.
+    if (res.status === 403 || code === "NOT_ALLOWLISTED" || code === "PICKUP_DISABLED" || code === "FORBIDDEN_ROLE") {
+      return {
+        text:
+          `You don't have push access to this entity, so you can't edit or plug it. Two options: ` +
+          `make your own separate copy with grid_pickup, or ask the owner for collaborator access with the CLI ` +
+          `\`grid collab <entity>\` (rolling out soon) and pull again once granted.`,
+        structured: { can_edit: false, owner_is_you: false, access: "view_only" },
       };
     }
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
-    throw new Error(`Claim failed (HTTP ${res.status}): ${msg}`);
+    throw new Error(`Pull failed (HTTP ${res.status}): ${msg}`);
   }
 
   ctx.state.lastAnonClaim = null;
-  // The entity is authed-owned now — the anon owner token is dead weight (a
-  // claimed drop can no longer be edited anonymously). Future re-drops of it
-  // must ride the authed wire.
+  // A claimed anon drop is authed-owned now — its anon owner token is dead weight.
   if (ctx.state.lastDrop?.entity_id === targetId) {
     ctx.state.lastDrop.owner_token = null;
   }
   const url = data?.url || data?.redirect_url || ctx.state.lastDrop?.url || null;
-  const lines = ["Claimed 1, now yours:"];
-  lines.push(`${url ?? ""}${data?.new_expires_at ? ` (expires ${data.new_expires_at})` : ""}`.trim());
+  const slug = data?.slug || targetId;
+  const where = data?.grid ? ` in ${data.grid}` : "";
+  // A claim_token transfers ownership to you; otherwise read the pickup contract.
+  const ownerIsYou = data?.owner?.is_you === true || Boolean(claimToken);
+  const canReplug = data?.capabilities?.replug === true;
+  let head, canEdit;
+  if (ownerIsYou) {
+    head = `${slug}${where} is yours — your next grid_plug (with target_entity_id) updates it in place.`;
+    canEdit = true;
+  } else if (canReplug) {
+    head = `You have collaborator push access to ${slug}${where} — your next grid_plug (target_entity_id) updates the SHARED entity; the team sees the new version and can roll it back.`;
+    canEdit = true;
+  } else {
+    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own copy with grid_pickup, or request collaborator access with the CLI \`grid collab ${slug}\` (rolling out soon), then pull again.`;
+    canEdit = false;
+  }
+  const lines = [head];
+  if (url) lines.push(`URL: ${url}`);
+  if (canEdit && data?.entity_id) {
+    lines.push(`Re-plug handle: entity_id=${data.entity_id} — pass it as grid_plug's target_entity_id to update in place.`);
+  }
   return {
     text: lines.join("\n"),
     structured: {
-      claimed: 1,
-      urls: url ? [url] : [],
+      ...(data?.entity_id ? { entity_id: data.entity_id } : {}),
+      ...(slug ? { slug } : {}),
+      grid: data?.grid ?? null,
+      ...(url ? { url } : {}),
+      owner_is_you: ownerIsYou,
+      can_edit: canEdit,
     },
   };
 }
 
 
-// ── grid_deploy — the unified create/re-plug verb (spec v2 §3) ──────────────
+// ── grid_plug — the unified create/re-plug verb (spec v2 §3) ──────────────
 
 // Total upload budget mirrors the server's multipart cap (100 MB).
 const PLUG_MAX_TOTAL_BYTES = 100 * 1024 * 1024;
@@ -964,7 +1002,7 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
   if (status === 401) {
     return isEdit
       ? "That did not authorize this entity (wrong entity, expired, or already claimed). Sign in if you own it (grid_login), pass its owner_token for an anonymously-created drop, or omit target_entity_id to create a new entity."
-      : "Not signed in. Ask the user: sign in (grid_login) to publish to their grid, OR publish anonymously now (re-call grid_deploy with anon: true) - it goes live immediately with a claim_url + owner_token to claim into their account later. Do not silently fail; offer both.";
+      : "Not signed in. Ask the user: sign in (grid_login) to publish to their grid, OR publish anonymously now (re-call grid_plug with anon: true) - it goes live immediately with a claim_url + owner_token to claim into their account later. Do not silently fail; offer both.";
   }
   if (status === 403) {
     return "You lack the role to plug this target. To re-plug someone else's entity, pick it up first (grid_edit_existing_app / grid_claim_anonymous_deploy).";
@@ -1507,11 +1545,20 @@ export async function runPlug(ctx, input, deps = {}) {
     if (looksRuntime) {
       const gridSlug = data.grid ?? grid ?? null;
       const eid = data.entity_id ?? targetEntityId ?? null;
+      // The disk CLI is the reliable route for a multi-file app — BUT it only
+      // works where the CLI is already SIGNED IN: a terminal or Claude Code
+      // where `grid login` was run once. Do NOT tell the agent to `grid login`
+      // inside an ephemeral chat sandbox — that login is a long-lived poll (up
+      // to 5 min) and the sandbox is time-bounded + non-persistent, so it won't
+      // complete or won't survive to the next command (observed live). If this
+      // was inline-only, the fix is to move to a signed-in shell OR ask the
+      // user — never silently drop large files.
+      const replug = eid
+        ? `npx -y @cloudgrid-io/cli plug --existing ${eid}${gridSlug ? ` --grid ${gridSlug}` : ""} --verbose`
+        : "npx -y @cloudgrid-io/cli plug";
       cliSteer =
-        "For a multi-file app the local CLI is more reliable — it reads from disk, so lockfiles and binaries can't truncate the way inline copying can. " +
-        (eid
-          ? `If you have the folder: \`cd <app> && npx -y @cloudgrid-io/cli plug\`. If not, pick it up first: \`npx -y @cloudgrid-io/cli pickup ${gridSlug ? `${gridSlug}/` : ""}<slug> --force\` then \`cd <slug> && npx -y @cloudgrid-io/cli plug\`. Or re-plug directly: \`npx -y @cloudgrid-io/cli plug --existing ${eid}${gridSlug ? ` --grid ${gridSlug}` : ""} --verbose\`.`
-          : "Prefer `npx -y @cloudgrid-io/cli plug` from the app folder over inlining files.");
+        "Heads-up: this went in INLINE. For a multi-file app the disk-based CLI is more reliable (lockfiles/binaries can't truncate), but it must run where the CLI is already signed in — a terminal or Claude Code that has done `grid login` once. Do NOT try `grid login` inside a chat sandbox: its login poll is long-lived and the sandbox is ephemeral, so it won't stick. " +
+        `If you had to leave any files out to make this inline deploy safe, tell the user — offer the complete deploy from Claude Code or a terminal (\`${replug}\`), or confirm they accept the reduced version. Do not drop files silently.`;
     }
   }
 
@@ -1613,7 +1660,7 @@ async function authedApiCall(ctx, { method, pathName, body, verb }) {
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
     const codeStr = data?.error?.code || null;
     const err = new Error(`${verb} failed (HTTP ${res.status}${codeStr ? ` ${codeStr}` : ""}): ${msg}`);
-    // Expose the structured status/code so callers can branch (e.g. runFork's
+    // Expose the structured status/code so callers can branch (e.g. runPickup's
     // NOT_A_RUNTIME → inspiration-route fallback). Additive: existing callers
     // only read `.message`.
     err.status = res.status;
@@ -1623,63 +1670,13 @@ async function authedApiCall(ctx, { method, pathName, body, verb }) {
   return data;
 }
 
-// Fork: start a NEW entity from an existing source, copy-on-write with lineage.
-// Kind-aware (one fork verb, mirrors the CLI `fork` command): the caller may
-// not know the source's kind, so try the runtime route first and, when the
-// server reports the target is an inspiration (`400 NOT_A_RUNTIME`, emitted by
-// requireEntityAccess before the runtime handler runs), retry the inspiration
-// route. The inspiration remix lands in the caller's active grid, so no
-// `into_org_slug`; `source_version_id` has no meaning for inspirations.
-export async function runFork(ctx, { id, into_org_slug, name, source_version_id }) {
-  let data;
-  try {
-    data = await authedApiCall(ctx, {
-      method: "POST",
-      pathName: `/api/v2/runtimes/${encodeURIComponent(id)}/fork`,
-      body: {
-        ...(into_org_slug ? { into_org_slug } : {}),
-        ...(name ? { name } : {}),
-        ...(source_version_id ? { source_version_id } : {}),
-      },
-      verb: "Fork",
-    });
-  } catch (err) {
-    if (err && err.code === "NOT_A_RUNTIME") {
-      data = await authedApiCall(ctx, {
-        method: "POST",
-        pathName: `/api/v2/inspirations/${encodeURIComponent(id)}/fork`,
-        body: { ...(name ? { name } : {}) },
-        verb: "Fork",
-      });
-    } else {
-      throw err;
-    }
-  }
-  const gridSlug = data?.grid_slug ?? data?.org?.slug ?? null;
-  const lines = [
-    `Forked: ${data?.name ?? id} (entity_id=${data?.entity_id ?? "?"})${gridSlug ? ` in grid ${gridSlug}` : ""}`,
-    `Lineage: forked_from=${data?.forked_from ?? "?"}${data?.forked_from_version_id ? ` @ ${data.forked_from_version_id}` : ""}`,
-  ];
-  return {
-    text: lines.join("\n"),
-    structured: {
-      entity_id: data?.entity_id ?? null,
-      name: data?.name ?? null,
-      kind: data?.kind ?? null,
-      grid_slug: gridSlug,
-      forked_from: data?.forked_from ?? null,
-      forked_from_version_id: data?.forked_from_version_id ?? null,
-      current_version_id: data?.current_version_id ?? null,
-    },
-  };
-}
-
-// Remix: cross-grid "make my own copy". Unlike fork (same-grid, byte-carrying),
-// remix mints a NEW entity in ANY grid the caller can build in, keeps lineage
-// back to the source, and strips the source's secrets/connection credentials —
-// the remixer supplies their own before plugging. Hits POST
-// /api/v2/runtimes/:id/remix.
-export async function runRemix(ctx, { id, into_org_slug, name, source_version_id }) {
+// grid_pickup — "make your own copy" (like a git fork). Mints a NEW entity in a
+// grid you can build in, keeps lineage back to the source, and strips the
+// source's secrets/connection credentials — you set your own before plugging.
+// Plugging your copy creates/updates YOUR entity; the original is untouched.
+// Hits POST /api/v2/runtimes/:id/remix (the copy route). Mirrors the CLI's
+// `grid pickup`. To edit the ORIGINAL in place, that's grid_pull, not this.
+export async function runPickup(ctx, { id, into_org_slug, name, source_version_id }) {
   const data = await authedApiCall(ctx, {
     method: "POST",
     pathName: `/api/v2/runtimes/${encodeURIComponent(id)}/remix`,
@@ -1688,12 +1685,13 @@ export async function runRemix(ctx, { id, into_org_slug, name, source_version_id
       ...(name ? { name } : {}),
       ...(source_version_id ? { source_version_id } : {}),
     },
-    verb: "Remix",
+    verb: "Pickup",
   });
   const gridSlug = data?.grid_slug ?? data?.org?.slug ?? null;
   const lines = [
-    `Remixed: ${data?.name ?? id} (entity_id=${data?.entity_id ?? "?"})${gridSlug ? ` in grid ${gridSlug}` : ""}`,
-    `Lineage: forked_from=${data?.forked_from ?? "?"}. Secrets were not copied — set your own before you plug.`,
+    `Picked up a copy: ${data?.name ?? id} (entity_id=${data?.entity_id ?? "?"})${gridSlug ? ` in grid ${gridSlug}` : ""}.`,
+    "This is a NEW entity — plug it (with this entity_id as target_entity_id) to create/update YOUR copy; the original is untouched.",
+    `Lineage kept (forked_from=${data?.forked_from ?? "?"}). The source's secrets were NOT copied — set your own before you plug.`,
   ];
   return {
     text: lines.join("\n"),
@@ -1709,30 +1707,6 @@ export async function runRemix(ctx, { id, into_org_slug, name, source_version_id
   };
 }
 
-// Download: signed, time-limited (15-minute) source-bundle URLs. No entity is
-// created and no registry state changes.
-export async function runDownload(ctx, { id, version }) {
-  const qs = version ? `?version=${encodeURIComponent(version)}` : "";
-  const data = await authedApiCall(ctx, {
-    method: "GET",
-    pathName: `/api/v2/runtimes/${encodeURIComponent(id)}/source${qs}`,
-    verb: "Download",
-  });
-  const services = data?.services && typeof data.services === "object" ? data.services : {};
-  const lines = [`Source bundle URLs for ${data?.name ?? id} (valid ~15 minutes):`];
-  for (const [svc, u] of Object.entries(services)) lines.push(`  ${svc}: ${u}`);
-  if (Object.keys(services).length === 0) lines.push("  (no services returned)");
-  return {
-    text: lines.join("\n"),
-    structured: {
-      entity_id: data?.entity_id ?? null,
-      name: data?.name ?? null,
-      services,
-      domain: data?.domain ?? null,
-    },
-  };
-}
-
 // Change an entity's visibility — inspiration OR runtime app/agent. Authed,
 // direct API — works on the hosted edition where the CLI-wrapping share tool is
 // unavailable. Kind-aware routing (see below). Defaults to the drop made in this
@@ -1796,7 +1770,7 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
   // Route order. `space` is inspiration-only; a known runtime kind goes straight
   // to the entities route; a known inspiration goes straight to the inspiration
   // route; an unknown kind tries the runtime route first and falls back to the
-  // inspiration route on a not-found (mirrors runFork).
+  // inspiration route on a not-found (mirrors runPickup).
   let order;
   if (vis === "space") order = ["inspiration"];
   else if (isRuntimeKind) order = ["runtime"];
@@ -1966,7 +1940,7 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
   });
   if (!target) {
     throw new Error(
-      "No build to check. Pass poll_url from a grid_deploy result, or deploy something first in this session. (Instant inspiration deploys are live on return and have no build to poll.)",
+      "No build to check. Pass poll_url from a grid_plug result, or deploy something first in this session. (Instant inspiration deploys are live on return and have no build to poll.)",
     );
   }
   const verdict = await fetchDeployTrace(ctx, { pollUrl: target, grid: gridSlug });
@@ -2078,7 +2052,7 @@ async function readInspirationSourceViaApi(ctx, { entityId, slug, grid }) {
 
 // Resolve a public URL / grid+slug to a REAL entity_id (+ edition metadata) via
 // the deployed pickup contract (POST /api/v2/entities/:target/pickup — the same
-// endpoint runClaim uses). Used by runSource when a bare URL arrives with no
+// endpoint runPull uses). Used by runSource when a bare URL arrives with no
 // session entity_id (a fresh chat): the contract returns
 //   { entity_id, slug, grid, kind, single_html, capabilities, replug_handle,
 //     source_download_url, ... }

package/src/tools/register.js

@@ -20,11 +20,9 @@ import {
   resolveGridOrAsk,
   detectSourceManifest,
   runReport,
-  runClaim,
+  runPull,
   runPlug,
-  runFork,
-  runRemix,
-  runDownload,
+  runPickup,
   runVisibility,
   runSource,
   runCheckDeploy,
@@ -120,28 +118,68 @@ export function registerTools(server, ctx) {
 
   // ── Direct-API tools (both editions) ──────────────────────────────────────
 
-  // Pickup — both editions. Adopts an entity into the signed-in account's active
-  // grid (ownership transfer via POST /api/v2/entities/:id/pickup). Pass an
-  // anonymous drop's owner token as `claim_token` to take over something you
-  // dropped anonymously — that path replaces the old standalone "claim" verb.
+  // ── Copy / adopt verbs (both editions) — mirror the CLI: ──────────────────
+  //   grid_pickup = make YOUR OWN COPY (git-fork style) → POST /runtimes/:id/remix
+  //   grid_pull   = continue/edit the SAME entity in place (push access needed)
+  //                 → POST /entities/:id/pickup
+  // (The CLI verbs `download`, `fork`, `remix`, `link` were retired; no MCP tool
+  // targets them.)
+
+  // grid_pickup — make your own copy of any app you can see.
   reg(
     "grid_pickup",
     {
-      description: "Pick up (adopt) an entity into the signed-in account's active grid — an ownership transfer, keeping the same public URL. Use it to take over an entity you have access to, or to keep an anonymous drop you created: pass the drop's `claim_token` and it becomes owned and stops expiring on the anonymous schedule. Requires sign-in (grid_login). Calls the API directly, so it works on every edition. (This is the direct-API adopt; on the local edition grid_edit_existing_app additionally downloads the source and links the folder for editing.)",
+      description: "Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
+      inputSchema: {
+        id: z.string().describe("The source app to copy: a canonical UUID or <grid-slug>/<entity-slug>."),
+        into_org_slug: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
+        name: z.string().optional().describe("Slug for your copy. Omit to derive one from the source."),
+        source_version_id: z.string().optional().describe("Copy an older version instead of HEAD, e.g. v_a1b2c3d."),
+      },
+      outputSchema: {
+        entity_id: z.string().nullable().describe("Your copy's entity id — pass as grid_plug's target_entity_id to update it."),
+        name: z.string().nullable().describe("Your copy's slug."),
+        kind: z.string().nullable().describe("app | agent."),
+        grid_slug: z.string().nullable().describe("The grid your copy landed in."),
+        forked_from: z.string().nullable().describe("Source entity_id (lineage)."),
+        forked_from_version_id: z.string().nullable().describe("Source version, when a specific one was copied."),
+        current_version_id: z.string().nullable().describe("Your copy's current version id."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
+        return okResult(await runPickup(ctx, input));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // grid_pull — continue/edit the SAME entity in place (push access required).
+  reg(
+    "grid_pull",
+    {
+      description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so and tell the user they can make their own copy with grid_pickup, or request collaborator access with the CLI `grid collab <entity>` (rolling out soon). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
-        entity_id: z.string().optional().describe("The entity id to pick up. Defaults to this session's last anonymous drop."),
-        claim_token: z.string().optional().describe("For an anonymous drop: its owner token (the owner_token in the drop result, also embedded in claim_url). Passing it takes over that drop."),
-        claim_url: z.string().optional().describe("Alternative to claim_token for an anonymous drop — the claim_url from the drop result; the token is read from it."),
+        entity_id: z.string().optional().describe("The entity id to pull. Defaults to this session's last anonymous drop."),
+        claim_token: z.string().optional().describe("Anonymous drop only: its owner token — claims that drop into your account (ownership transfer)."),
+        claim_url: z.string().optional().describe("Alternative to claim_token for an anonymous drop — the claim_url; the token is read from it."),
       },
       outputSchema: {
-        claimed: z.number().describe("Number of entities picked up."),
-        urls: z.array(z.string()).describe("Public URLs of the picked-up entities."),
+        entity_id: z.string().optional().describe("The entity you pulled."),
+        slug: z.string().optional().describe("Its slug."),
+        grid: z.string().nullable().optional().describe("Its grid."),
+        url: z.string().optional().describe("Its public URL."),
+        owner_is_you: z.boolean().optional().describe("True if you own it."),
+        can_edit: z.boolean().optional().describe("True if you can plug/update it (owner or collaborator). False = view-only."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
     async (input) => {
       try {
-        return okResult(await runClaim(ctx, input || {}));
+        return okResult(await runPull(ctx, input || {}));
       } catch (err) {
         return fail(err.message);
       }
@@ -276,13 +314,17 @@ export function registerTools(server, ctx) {
         "If you need to edit a page but don't have its HTML, call grid_get_app_source first, then deploy with " +
         "target_entity_id. " +
         // Suggestion 1: steer multi-file runtime apps to the CLI up front — inline
-        // copying truncates large lockfiles/binaries and silently fails the build.
+        // copying truncates large lockfiles/binaries and silently fails the build —
+        // but only where the CLI is actually signed in (see the login caveat).
         "RELIABILITY: `html` and `artifact_files` are sent INLINE (copied through this call), which can " +
         "truncate large files (lockfiles, binaries) on a multi-file app. For a real framework (Next.js, etc.), " +
-        "a lockfile, or binary assets — and for re-plugging an existing runtime app — prefer the local CLI, " +
-        "which reads from disk: `npx -y @cloudgrid-io/cli plug` in the app folder (pick it up first with " +
-        "`npx -y @cloudgrid-io/cli pickup <grid>/<slug> --force` if you don't have it locally). Reserve inline " +
-        "for a single page or a few small text files. (CloudGrid calls this operation 'plug'.)",
+        "a lockfile, or binary assets — and for re-plugging an existing runtime app — the disk-based CLI is more " +
+        "reliable: `npx -y @cloudgrid-io/cli plug` in the app folder. BUT it only works where the CLI is already " +
+        "signed in — a terminal or Claude Code that ran `grid login` once. Do NOT attempt `grid login` inside a " +
+        "chat sandbox: its login is a long poll and the sandbox is ephemeral, so it will not complete. If you can " +
+        "only deploy inline here and would have to omit large files, do NOT drop them silently — tell the user " +
+        "and offer to run the full deploy from Claude Code or a terminal (same entity_id). Reserve inline for a " +
+        "single page or a few small text files. (CloudGrid calls this operation 'plug'.)",
       inputSchema: plugInputSchema,
       outputSchema: {
         entity_id: z.string().optional().describe("Globally unique — pass back as target_entity_id to re-plug."),
@@ -428,111 +470,6 @@ export function registerTools(server, ctx) {
   // "publish"/"ship"/"make live" live in grid_plug's description, so
   // deploy-intent routing lands there without a second listed name.
 
-  // ── grid_fork / grid_remix / grid_download — direct-API copy/source verbs ──────
-  // fork = same-grid byte-carrying copy; remix = cross-grid copy with secrets
-  // stripped; download = signed source-bundle URLs. All direct-API (both editions).
-  reg(
-    "grid_fork",
-    {
-      description:
-        "Fork an entity: start a NEW entity from an existing one (copy-on-write, lineage recorded), carrying " +
-        "the source bytes. Lands in the source's home grid by default; cross-grid only for system templates " +
-        "or forkable:'public' sources — for a general cross-grid copy use grid_remix instead. Requires sign-in. " +
-        "Kind-aware: forks a runtime (app/agent) OR an inspiration — tries POST /api/v2/runtimes/:id/fork and " +
-        "falls back to /api/v2/inspirations/:id/fork.",
-      inputSchema: {
-        id: z.string().describe("The source entity: a canonical UUID or <grid-slug>/<entity-slug>."),
-        into_org_slug: z.string().optional().describe("Destination grid slug. Required only when you belong to more than one grid."),
-        name: z.string().optional().describe("Slug for the new entity. Omit to derive one from the source."),
-        source_version_id: z.string().optional().describe("Fork an older version instead of HEAD, e.g. v_a1b2c3d."),
-      },
-      outputSchema: {
-        entity_id: z.string().nullable().describe("The new entity's id."),
-        name: z.string().nullable().describe("The new entity's slug."),
-        kind: z.string().nullable().describe("app | agent | inspiration."),
-        grid_slug: z.string().nullable().describe("The grid the fork landed in."),
-        forked_from: z.string().nullable().describe("Source entity_id."),
-        forked_from_version_id: z.string().nullable().describe("Source version, when a specific one was forked."),
-        current_version_id: z.string().nullable().describe("The fork's current version id."),
-      },
-      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    },
-    async (input) => {
-      try {
-        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
-        return okResult(await runFork(ctx, input));
-      } catch (err) {
-        return fail(err.message);
-      }
-    },
-  );
-
-  reg(
-    "grid_remix",
-    {
-      description:
-        "Remix an app: make your own copy of any app you can SEE (link/public/authenticated, or a grid you " +
-        "belong to) into ANY grid you can build in — cross-grid is allowed. Mints a NEW entity with lineage " +
-        "back to the source, WITHOUT the source's secrets or connection credentials (set your own before you " +
-        "plug). Distinct from grid_fork, which is same-grid and byte-carrying. Requires sign-in. Calls POST " +
-        "/api/v2/runtimes/:id/remix.",
-      inputSchema: {
-        id: z.string().describe("The source app: a canonical UUID or <grid-slug>/<entity-slug>."),
-        into_org_slug: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
-        name: z.string().optional().describe("Slug for your copy. Omit to derive one from the source."),
-        source_version_id: z.string().optional().describe("Remix an older version instead of HEAD, e.g. v_a1b2c3d."),
-      },
-      outputSchema: {
-        entity_id: z.string().nullable().describe("Your copy's entity id."),
-        name: z.string().nullable().describe("Your copy's slug."),
-        kind: z.string().nullable().describe("app | agent."),
-        grid_slug: z.string().nullable().describe("The grid your copy landed in."),
-        forked_from: z.string().nullable().describe("Source entity_id."),
-        forked_from_version_id: z.string().nullable().describe("Source version, when a specific one was remixed."),
-        current_version_id: z.string().nullable().describe("Your copy's current version id."),
-      },
-      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    },
-    async (input) => {
-      try {
-        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
-        return okResult(await runRemix(ctx, input));
-      } catch (err) {
-        return fail(err.message);
-      }
-    },
-  );
-
-  reg(
-    "grid_download",
-    {
-      description:
-        "Download an entity's source: the bundle last deployed for a runtime, as one signed, time-limited " +
-        "(15-minute) read URL per service tarball. No entity is created and no registry state changes (unlike " +
-        "grid_pickup/grid_fork/grid_remix, which adopt or copy). Requires sign-in. Calls GET " +
-        "/api/v2/runtimes/:id/source directly.",
-      inputSchema: {
-        id: z.string().describe("The runtime to download: a canonical UUID or <grid-slug>/<entity-slug>."),
-        version: z.string().optional().describe("Download an older version's bundle instead of HEAD, e.g. v_a1b2c3d."),
-      },
-      outputSchema: {
-        entity_id: z.string().nullable().describe("The runtime's entity id."),
-        name: z.string().nullable().describe("The runtime's slug."),
-        services: z.record(z.string()).describe("Service name → signed read URL (valid ~15 minutes)."),
-        domain: z.string().nullable().optional().describe("The runtime's domain, if any."),
-      },
-      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    },
-    async (input) => {
-      try {
-        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
-        return okResult(await runDownload(ctx, input));
-      } catch (err) {
-        return fail(err.message);
-      }
-    },
-  );
-
   // Source — both editions. Fetches a drop's current deployed HTML inline so an
   // agent that lost the content can edit it and re-plug in place.
   reg(
@@ -546,9 +483,9 @@ export function registerTools(server, ctx) {
         "entity_id via the pickup contract and also returns the entity's kind, single_html, capabilities " +
         "(replug/fork), and replug_handle — read those to decide whether to edit in place (single-HTML + " +
         "capabilities.replug), fall back for a multi-file app/agent (use source_download_url + the local " +
-        "edition/CLI), or offer a fork when it isn't yours. For multi-file or runtime (app/agent) source " +
-        "bundles, use grid_download (signed tarball URLs). Reads the HTML from the API server-side; " +
-        "read-only, creates nothing.",
+        "edition/CLI), or offer a copy (grid_pickup) when it isn't yours. For a multi-file or runtime " +
+        "(app/agent) source, use source_download_url, or grid_pull to get the files and link the folder. " +
+        "Reads the HTML from the API server-side; read-only, creates nothing.",
       inputSchema: {
         entity_id: z.string().optional().describe("The drop's durable id. Defaults to this session's last drop."),
         url: z.string().optional().describe("The public URL of the drop (e.g. https://<grid>.cloudgrid.io/<slug>). Defaults to this session's last drop URL."),
@@ -1126,23 +1063,27 @@ export function registerTools(server, ctx) {
     cliTool(({ grid }) => ["describe", "grid", grid, "--json"]),
   );
 
+  // Local (CLI-wrapping) counterpart of the direct-API grid_pull: downloads the
+  // source + cloudgrid.yaml and links the folder, so the next `grid plug` updates
+  // the SAME entity in place. Wraps `grid pull` (NOT `grid pickup` — pickup now
+  // makes a separate copy). Push access required; a view-only entity can't be
+  // pulled — use grid_pickup to copy it, or `grid collab` to request access.
   regTool(
     "grid_edit_existing_app",
-    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `grid pickup`.",
+    "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy instead, use grid_pickup.",
     {
-      name: z.string().describe("Entity slug or id to pick up."),
-      target_dir: z.string().optional().describe("Directory to pick up into (relative to cwd). Defaults to the entity name."),
+      name: z.string().describe("Entity slug or id to pull."),
+      target_dir: z.string().optional().describe("Directory to pull into (relative to cwd). Defaults to the entity name."),
       grid: z.string().optional().describe("Grid to resolve the entity in. Defaults to the active grid."),
-      version: z.string().optional().describe("Pick up an older version's source instead of HEAD."),
-      force: z.boolean().optional().describe("Pick up into a non-empty directory."),
+      version: z.string().optional().describe("Pull an older version's source instead of HEAD."),
+      force: z.boolean().optional().describe("Pull into a non-empty directory."),
       no_bind: z.boolean().optional().describe("Download source only — skip cloudgrid.yaml and the link."),
       cwd: z.string().optional().describe("Working directory the CLI runs in. The download lands here; pass an explicit, writable directory."),
     },
     { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     cliTool(({ name, target_dir, grid, version, force, no_bind }) => {
-      const args = ["pickup", name];
+      const args = ["pull", name];
       if (target_dir) args.push(target_dir);
-      // CLI 0.12's pickup exposes `--grid <slug>` (was legacy `--org`).
       if (grid) args.push("--grid", grid);
       if (version) args.push("--version", version);
       if (force) args.push("--force");

package/src/tools.js

@@ -33,7 +33,8 @@ export {
   parseCliPlugUrl,
   plugViaCliFallback,
   runPlug,
-  runFork,
+  runPickup,
+  runPull,
   runSource,
   runVisibility,
   runCheckDeploy,