@plitzi/sdk-mcp 0.38.15 → 0.38.16

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @plitzi/sdk-mcp
 
+## 0.38.16
+
+### Patch Changes
+
+- 9cfdccb: ## Security
+
+  - **A site's credential reads nothing of the space over MCP** (`@plitzi/sdk-mcp`): the `render` token every published
+    page embeds — and a self-hosting `host` key — resolved to a grant naming the space, and the MCP served every read
+    under it: the unpublished draft, the change history with who made each change and every value before and after, the
+    functions' source, the space's private data, its action documents and connectors. Only an `agent` grant attaches a
+    space now; any other is a connection with no space (`plitzi_render` and the public guides), told so in the words
+    `NO_SPACE_ATTACHED` already uses. A deployment whose `getGrant` answered other scopes for reading must issue agent
+    grants for them.
+
+  ## Agents
+  - **`plitzi space watch`** (`@plitzi/cli`): the space read again on every save of `src/space/`, `src/plugins/`,
+    `src/data/` or `public/data/`, and only what changed said — what the save did to the space element by element, the
+    findings and warnings it brought and fixed (one that only moved down its file is the same one), a save that changed
+    nothing, or that the space stopped authoring and why. `--json` is one event a line (`ready`, `pass`, `refused`,
+    `error`), for an agent to run in the background instead of `author` and `space lint` after every edit. Each pass reads
+    the space in a process of its own (`space watch-pass`, hidden). `space lint`'s reading is `spaceFindings`, shared.
+  - **A space's activity, followed** (`@plitzi/sdk-shared`, `@plitzi/sdk-mcp`, `@plitzi/cli`): what happened on a space
+    after a cursor — its draft changed (a person in the builder, an agent, the autofix), a version went out, a server
+    action failed or was refused — and, with nothing yet, waited for, up to 50 s. One vocabulary,
+    `@plitzi/sdk-shared/activity` (`SpaceActivity`, `SpaceActivityPage`, `activityLine`, `isSpaceActivityPage`, the
+    limits); the reader's own writes left out and counted (`skippedMine`), `mine` keeps them.
+    - **`plitzi_activity { after, wait, limit, mine }`** (`@plitzi/sdk-mcp`), on the new `getActivity` adapter
+      (`SSRAdapters`). The listing budget is 78k (was 77k) for it.
+    - **`plitzi space activity [--follow] [--after <cursor>] [--mine] [--limit <n>] [--json]`** (`@plitzi/cli`), over
+      the platform's `GET /spaces/:spaceId/activity`; `--follow` stays, one page a line with `--json`, and asks again
+      when the platform does not answer.
+    - **The people in the builder see the agent work** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`, `@plitzi/sdk-mcp`,
+      `@plitzi/plitzi-builder`): an agent grant carries the application the member connected (`Grant.client`,
+      `StoredSpaceToken.client`, `SSRGrant.client`), and every MCP write `SSRWriteContext.client` — the history's
+      `client` for an agent, which was never set. A collaborator may be an agent (`SubscriptionCollaborator.agent`): the
+      builder draws it as a robot, names it `Claude · for ana` (`collaboratorTitle`) in the header, on the canvas and in
+      its notices. The deployment announces it — Plitzi's joins it on a write, selects what it changed, and lets it go
+      after a minute of nothing. `activityLine` names it the same way (`Claude for ana over the MCP, …`), so
+      `plitzi space activity` says which application wrote.
+    - A tool may declare `documents: false` (`ToolSpec`): the host loads none of the space for it, and passes the call's
+      abort signal through `ToolContext.activity`.
+
+  ## Authoring
+  - **A file that does not parse is said at its line under any loader** (`@plitzi/sdk-authoring`): `moduleProblem` read
+    the first line of the error, and an esbuild transform (tsx, vitest) puts only `Transform failed with 1 error:` there
+    — the file, line and what is wrong are on the next. A line of the message that points at a file of the project is
+    now the problem (`src/space/hero.ts:139: Expected "}" but found ";"`), the project's root matched as given and as it
+    is on disk (`/var/…` and `/private/var/…` on macOS).
+
+  ## Testing
+  - **`unusedPort` is chosen where the system never hands one out** (`@plitzi/sdk-server`): it answered a port the system
+    had just handed out (`listen(0)`), from the ephemeral range every outgoing connection takes its local port from — so
+    another worker's request could take it before the test listened, and CI failed `runtime.test.ts` with `EADDRINUSE`
+    (the page server then ends the process). It is a free port below that range now, at random, checked first.
+
+  ## Docs
+  - **A self-hosted runtime's endpoints go in `data`**, as 0.38.15 moved them: `docs/en/runtimes.md`, the
+    `10-runtime` example and the website still put `served.stage` in `preAuth`, before the cross-site guard.
+  - New: `docs/en/activity.md`; `space watch` in `docs/en/agent-tooling.md`'s loop; the CLI README, the CLI skill, the
+    generated project's `AGENTS.md`, the MCP guide and README.
+
+- Updated dependencies [9cfdccb]
+  - @plitzi/plitzi-sdk@0.38.16
+  - @plitzi/sdk-server@0.38.16
+  - @plitzi/sdk-authoring@0.38.16
+  - @plitzi/sdk-schema@0.38.16
+  - @plitzi/sdk-shared@0.38.16
+  - @plitzi/sdk-style@0.38.16
+
 ## 0.38.15
 
 ### Patch Changes

package/README.md

@@ -66,12 +66,13 @@ The server is stateless: it resolves the space per request and reads and writes
 
 | Adapter | Required | Purpose |
 |---|---|---|
-| `getGrant(req)` | yes | The space this request operates on **and whether the caller may change it** (`{ spaceId, scope, userId?, canWrite }`), decoded from the verified `Authorization` bearer. You own the JWT secret and the authorization model, so both are decided on your side. Return `undefined` for a missing or invalid token. |
+| `getGrant(req)` | yes | The space this request operates on **and whether the caller may change it** (`{ spaceId, scope, userId?, client?, canWrite }` — `client`, the application an agent grant was given to, rides every write as `SSRWriteContext.client`), decoded from the verified `Authorization` bearer. You own the JWT secret and the authorization model, so both are decided on your side. Return `undefined` for a missing or invalid token. |
 | `getSchema(spaceId, env)` | yes | The element schema the tools read and mutate. |
 | `getStyle(spaceId, env)` | yes | The full style document, including `platform`/`mode`. |
 | `saveSchema(spaceId, env, schema)` | for writes | Persist a mutated schema. Without it, `plitzi_apply` reports `persisted: false` and leads its warnings with what was NOT saved. |
 | `saveStyle(spaceId, env, style)` | for writes | Persist a mutated style document. |
 | `getChanges(spaceId, env, query)` | no | The space's change history, for the `plitzi://changes` resources. Writes arrive with an `SSRWriteContext` (`userId`, one `batch` per tool call) so a consumer can record them. |
+| `getActivity(spaceId, query, reader, signal)` | no | What happened on the space after a cursor — the draft changed, a version went out, an action failed (`SpaceActivityPage`, `@plitzi/sdk-shared/activity`) — waiting up to `query.wait` seconds; `reader` is the member the agent acts for with `origin: 'mcp'`, whose own writes are left out unless `mine`, and `signal` ends the wait with the call. Without it there is no `plitzi_activity`. Only an `agent` grant reaches it. |
 | `getOfflineData(spaceId, env, rev)` | for preview | Read side of draft-preview. Only the preview endpoint calls it. |
 | `getComponentCatalog(spaceId, env)` | no | The element types the space's plugins add, for the catalog resources. |
 | `getConnectors` / `saveConnector` / `deleteConnector` | for connectors | The space's connector manifests, read and written by the connector operations. |
@@ -90,7 +91,9 @@ the page server too; a dedicated MCP that keeps its weight down writes those fou
 
 Without a `getGrant` that resolves, the server still answers its public surface — the handshake, the tool list,
 the guide, the CSS-property catalog — and asks for a space only when a tool or resource needs one. A grant that
-resolves with `canWrite: false` reads everything and is refused at every write tool.
+resolves with `canWrite: false` reads the space and is refused at every write tool. Only an `agent` grant attaches a
+space: a site's credential (`scope: 'render'` or `'host'`) names one too, but the draft, its functions' source, its
+private data and who edits it are not a site's to read — it is answered as a connection with no space.
 
 ## Options
 
@@ -123,6 +126,7 @@ createServer({ adapters }, { screenshot: { serviceUrl, renderBaseUrl }, proxy: {
 | `plitzi_look` | read | See a saved page: its accessibility outline (default), its HTML, or a PNG (desktop, mobile or both) |
 | `plitzi_render` | read | Render a self-contained UI widget, offline, with no space |
 | `plitzi_try_function` | write | Run one task of the space's functions against the draft, in the sandbox: its value, logs and error |
+| `plitzi_activity` | read | What happened on the space since a cursor — edits by people and other agents, versions out, actions failing — waited for up to 50 s; the agent's own writes left out and counted |
 
 The server advertises each tool's access as its `readOnlyHint` annotation, so a host can run a read without asking
 and ask before a write.

package/dist/modules/mcp/helpers/guide.js

@@ -2,7 +2,7 @@ import { BUILTIN_TRANSFORMERS, GLOBAL_SOURCES, MOTION_ENTERS, MOTION_LOOPS } fro
 //#region src/modules/mcp/helpers/guide.ts
 var GLOBALS = GLOBAL_SOURCES.map((source) => `\`${source}\``).join(", ");
 var OTHER_TRANSFORMERS = Object.keys(BUILTIN_TRANSFORMERS).filter((action) => action !== "twigTemplate").map((action) => `\`${action}\``).join(", ");
-var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles a quickstart of the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Every element has ONE name and it IS its id ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) — the same name is the runtime wiring key, so a provider source is `<type>_<name>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is plain kebab-case — write shorthands freely (`border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`), they are expanded to longhands for you and STORED that way, so read-back shows the longhands; style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS elements by label/type/attribute and hands you the name to write ops against; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. CMS / API integrations (Strapi, WordPress, Contentful, any REST service) go through a CONNECTOR: a manifest you author declaring the base URL, endpoints and auth template, which the SERVER executes — read plitzi://connector-presets for working ones and plitzi://connectors/{env} for this space’s. You never see or create the credential; the space owner attaches it, and the connector saves without one. An apiContainer reads through it only with runtime:\"server\". Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers). Build pages people can use without sight: screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree, so every control needs words and clicks go on buttons and links — see Accessibility in plitzi://guide, and plitzi_look (its accessibility outline, the default view) to check. Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
+var serverInstructions = "Plitzi AI server: read-then-write editing of a Plitzi space. Reads follow a filesystem model — list cheap, read one item in detail on demand; never fetch a whole tree you do not need. Workflow: (1) read plitzi://primer/{env} once — it bundles a quickstart of the guide, types, css-properties and page/definition/variable summaries in a single call; (2) plitzi_search with include:\"detail\" to jump to elements — each hit then carries its uri, stateVersion AND full style/resolvedStyle, so an edit needs no per-element read; open a page skeleton or element only when you need its tree/detail (the skeleton already lists the style classes of each node, and plitzi_read fetches many uris at once); (3) plitzi_apply with dryRun to preview a batch; (4) plitzi_apply to persist, passing expectedResourceVersions to guard against concurrent edits — apply and search both hand back the versions you need for the next edit. Use patchElement / patchDefinition to change only some props / CSS (the upsert variants replace them all). An element read (and search include:\"detail\") inlines the CSS of the definitions it attaches under resolvedStyle, so you rarely need a separate definition read. Every element has ONE name and it IS its id ([A-Za-z0-9_-] starting with a letter, unique, chosen by you) — the same name is the runtime wiring key, so a provider source is `<type>_<name>.<field>`, visible to the provider’s DESCENDANTS only (bind inside its subtree). CSS is plain kebab-case — write shorthands freely (`border: 1px solid red`, `padding: 8px 16px`, `font: bold 16px/1.5 Arial`), they are expanded to longhands for you and STORED that way, so read-back shows the longhands; style vars are var(--name), schema vars are {{name}}. READERS — do not confuse them: MCP *resources* are the browsable catalog (list them, or open one by URI); plitzi_search FINDS elements by label/type/attribute and hands you the name to write ops against; plitzi_read BATCH-fetches URIs you already hold. Reach for search/read to work; browse resources to discover. CMS / API integrations (Strapi, WordPress, Contentful, any REST service) go through a CONNECTOR: a manifest you author declaring the base URL, endpoints and auth template, which the SERVER executes — read plitzi://connector-presets for working ones and plitzi://connectors/{env} for this space’s. You never see or create the credential; the space owner attaches it, and the connector saves without one. An apiContainer reads through it only with runtime:\"server\". Elements also carry applied style variants + visibility (initialState), data bindings and interaction flows: edit them with patchElement (initialState), upsertBinding/patchBinding/deleteBinding, and upsertInteractionFlow/patchInteractionNode/deleteInteraction. An element read shows all three plus availableVariants (which variant each of its classes offers). Build pages people can use without sight: screen readers and browser agents (Claude in Chrome) work a page through its accessibility tree, so every control needs words and clicks go on buttons and links — see Accessibility in plitzi://guide, and plitzi_look (its accessibility outline, the default view) to check. On a space people edit too, plitzi_activity says — and waits for — what they changed since you last looked. Separately, to SHOW the user a small self-contained widget (offline, no space or backend) instead of editing the space — a card, hero, pricing table, a visual answer — use plitzi_render; read plitzi://render/guide for it.";
 var widgetsOnlyInstructions = "Plitzi widget server (widgets-only connection). This connection carries NO Plitzi space: nothing can be read or edited in one, and the space tools are not offered here — do not look for them. What it does do is build self-contained UI widgets fully offline, with no backend, account or setup: call plitzi_render to SHOW the user a real rendered layout (card, hero, pricing table, checklist, form, gallery) instead of describing one. Read plitzi://render/guide first — the element/prop table, the style model and a worked example; plitzi://render/types lists every element type you can author (plitzi_read fetches both). To change a widget you already rendered, call plitzi_render again with patch:true and its renderId. If the user wants to edit their real Plitzi space from here, that is a reconnection they make: the integration must be re-authorized and granted a space (the consent screen lists theirs) — you cannot do it from this connection, and no retry will change it.";
 var guideQuickstart = `# Plitzi AI MCP — quickstart
 This is the condensed guide; read \`plitzi://guide\` for the full reference (every resource, op and example).
@@ -248,6 +248,12 @@ When you do hold several refs to open (e.g. from a skeleton), read them together
   the way to SEE overflow and misalignment (desktop, mobile or \`both\`); \`"both"\` image and outline. A change not
   saved yet is seen with \`plitzi_apply\`'s \`dryRun\` and \`look\`, the same views. It needs the SSR render service
   (\`PREVIEW_UNAVAILABLE\` without it); without a browser, an image or an outline falls back to the HTML, said.
+- \`plitzi_activity { after, wait }\` — what happened on the space since you last looked: the draft changed (a person
+  in the builder, another agent, the autofix — \`seq\` is its place in \`plitzi://changes/{env}\`), a version went
+  out, a server action failed or was refused. The first call, without \`after\`, answers the latest and a \`cursor\`;
+  pass it back as \`after\` and the call waits up to \`wait\` seconds (45, at most 50) until something happens. Your own
+  writes are left out and counted (\`skippedMine\`; \`mine: true\` keeps them). On a space people edit too, call it
+  before a write that rests on what you read earlier.
 - \`plitzi_render\` — a different job: show the user a self-contained widget built offline. It never touches the space.
 
 ## Suggestions — the same page with fewer elements

package/dist/modules/mcp/helpers/space.js

@@ -280,7 +280,7 @@ var emptySpaceMessage = "Space data not available";
 *  can tell "this connection cannot do that" from "the call failed". */
 var noSpaceErrorCode = "NO_SPACE_ATTACHED";
 var readOnlyGrantErrorCode = "READ_ONLY_GRANT";
-var unauthorizedSpaceMessage = "This connection has no space attached (a guest or widgets-only grant, or a token that carries no space), so NOTHING in a space can be read or edited — every other space tool will fail the same way, do not retry them. Use plitzi_render instead: it builds a self-contained widget offline, with no space, backend or account (read plitzi://render/guide). To edit a real space, the user must reconnect the integration and grant access to one.";
+var unauthorizedSpaceMessage = "This connection has no space attached (a guest or widgets-only grant, a site’s own credential — its render token or host key, which reads its pages and nothing of the space behind them — or a token that carries no space), so NOTHING in a space can be read or edited — every other space tool will fail the same way, do not retry them. Use plitzi_render instead: it builds a self-contained widget offline, with no space, backend or account (read plitzi://render/guide). To edit a real space, the user must reconnect the integration and grant access to one.";
 /** Raised when a space-dependent operation runs on a connection that resolves no spaceId. A type of its own so the
 *  host answers it as a STATE of the connection — a plain result the agent reads — instead of letting it surface as
 *  a failed call, which hosts render to the user as "cannot connect to this server". */
@@ -290,7 +290,7 @@ var NoSpaceError = class extends Error {
 		this.name = "NoSpaceError";
 	}
 };
-var readOnlyGrantMessage = "This connection may READ this space but not change it: its token is a read-only (render) credential, or the member who authorized it no longer has permission to edit this space. Every write tool will fail the same way, do not retry them — reads still work. To edit, the user must reconnect the integration and grant edit access.";
+var readOnlyGrantMessage = "This connection may READ this space but not change it: the member who authorized it no longer has permission to edit this space. Every write tool will fail the same way, do not retry them — reads still work. To edit, the user must reconnect the integration and grant edit access.";
 /** Raised when a write runs under a grant that carries no write authority. Like NoSpaceError this is a STATE of
 *  the connection rather than a failed call, so the host renders it as a result the agent can act on. */
 var ReadOnlyGrantError = class extends Error {

package/dist/modules/mcp/server.js

@@ -18,7 +18,7 @@ var asText = (data) => ({ content: [{
 var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger, renderStreaming = true, proxy }) => {
 	const log = createMcpLog(logger);
 	const grant = await getGrant().catch(() => void 0);
-	const spaceId = grant?.spaceId;
+	const spaceId = grant?.scope === "agent" ? grant.spaceId : void 0;
 	const hasSpace = spaceId !== void 0;
 	const requireSpaceId = () => {
 		if (spaceId === void 0) throw new NoSpaceError();
@@ -53,10 +53,11 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 			...data ? { data } : {}
 		};
 	};
-	const { saveSchema, saveStyle, saveConnector, deleteConnector, saveAction, deleteAction, saveFunctions, tryFunction, saveData } = adapters;
+	const { saveSchema, saveStyle, saveConnector, deleteConnector, saveAction, deleteAction, saveFunctions, tryFunction, saveData, getActivity } = adapters;
 	const write = {
 		userId: grant?.userId,
-		batch: randomUUID()
+		batch: randomUUID(),
+		...grant?.client === void 0 ? {} : { client: grant.client }
 	};
 	const persisters = {
 		schema: saveSchema ? (schema) => saveSchema(requireWritableSpaceId(), MCP_ENV, schema, write) : void 0,
@@ -72,7 +73,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: "0.38.15"
+		version: "0.38.16"
 	}, { instructions: hasSpace ? serverInstructions : widgetsOnlyInstructions });
 	const { getChanges } = adapters;
 	registerResources(server, getSpace, MCP_ENV, log, hasSpace, getChanges ? (query) => getChanges(requireSpaceId(), MCP_ENV, query) : void 0);
@@ -80,15 +81,19 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 		streaming: renderStreaming,
 		proxyEndpoint: proxy?.endpoint
 	});
-	const toolContext = async (tool) => ({
-		space: await getSpace(),
+	const toolContext = async (tool, signal) => ({
+		space: tool.documents === false ? emptySpace() : await getSpace(),
 		env: MCP_ENV,
 		persisters,
 		spaceId: requireSpaceId(),
 		preview,
 		screenshot,
-		proxy: proxyForTool(proxy, tool),
-		...tryFunction ? { tryFunction: (task, params) => tryFunction(requireWritableSpaceId(), task, params, write) } : {}
+		proxy: proxyForTool(proxy, tool.name),
+		...tryFunction ? { tryFunction: (task, params) => tryFunction(requireWritableSpaceId(), task, params, write) } : {},
+		...getActivity ? { activity: (query) => getActivity(requireSpaceId(), query, {
+			userId: grant?.userId,
+			origin: "mcp"
+		}, signal) } : {}
 	});
 	const spacelessContext = (tool) => ({
 		space: emptySpace(),
@@ -100,7 +105,7 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	});
 	const behaviorOf = (tool) => {
 		if (tool.spaceless) return (args) => tool.execute(args, spacelessContext(tool.name));
-		if (hasSpace) return async (args) => tool.execute(args, await toolContext(tool.name));
+		if (hasSpace) return async (args, signal) => tool.execute(args, await toolContext(tool, signal));
 		return tool.executePublic ? (args) => tool.executePublic?.(args, MCP_ENV) : void 0;
 	};
 	const listed = tools.flatMap((tool) => {
@@ -112,10 +117,10 @@ var createMcpServer = async ({ adapters, getGrant, preview, screenshot, logger,
 	});
 	const operationsCarried = listed.some(({ tool }) => tool.carriesOperations);
 	for (const { tool, behavior } of listed) {
-		const run = async (args) => {
+		const run = async (args, { signal }) => {
 			const start = performance.now();
 			try {
-				const result = await behavior(args);
+				const result = await behavior(args, signal);
 				log.toolCall(tool.name, args, performance.now() - start);
 				return isCallToolResult(result) ? result : asText(result);
 			} catch (error) {

package/dist/modules/mcp/tests/activity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/mcp/tests/grants.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/mcp/tools/activity.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { ToolContext } from './shared/tool';
+import { SpaceActivityQuery } from '@plitzi/sdk-shared/activity';
+export declare const activityShape: {
+    after: z.ZodOptional<z.ZodString>;
+    wait: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    mine: z.ZodOptional<z.ZodBoolean>;
+};
+/**
+ * What happened on the space after a cursor — the draft changed, a version went out, an action failed — waited for when
+ * nothing has. How an agent follows a space it works on with others: it learns of a person's edit in the builder, or a
+ * run its flow broke, without reading the space again and again. Its own writes are left out, and counted.
+ */
+export declare const activity: (input: SpaceActivityQuery, ctx: ToolContext) => Promise<unknown>;
+export declare const activityTool: import('.').ToolDef;

package/dist/modules/mcp/tools/activity.js

@@ -0,0 +1,36 @@
+import { defineTool } from "./shared/tool.js";
+import { z } from "zod";
+import { ACTIVITY_LIMIT_MAX, ACTIVITY_WAIT_DEFAULT_SECONDS, ACTIVITY_WAIT_MAX_SECONDS } from "@plitzi/sdk-shared/activity";
+//#region src/modules/mcp/tools/activity.ts
+var activityShape = {
+	after: z.string().optional().describe("The `cursor` last answered. Left out: the latest, at once"),
+	wait: z.number().min(0).max(ACTIVITY_WAIT_MAX_SECONDS).optional().describe(`Seconds to wait for something; default ${String(ACTIVITY_WAIT_DEFAULT_SECONDS)}`),
+	limit: z.number().int().min(1).max(ACTIVITY_LIMIT_MAX).optional(),
+	mine: z.boolean().optional().describe("Include your own writes")
+};
+/**
+* What happened on the space after a cursor — the draft changed, a version went out, an action failed — waited for when
+* nothing has. How an agent follows a space it works on with others: it learns of a person's edit in the builder, or a
+* run its flow broke, without reading the space again and again. Its own writes are left out, and counted.
+*/
+var activity = async (input, ctx) => {
+	if (!ctx.activity) return {
+		read: false,
+		reason: "This deployment keeps no activity for its spaces"
+	};
+	return ctx.activity({
+		...input,
+		wait: input.after === void 0 ? 0 : input.wait ?? ACTIVITY_WAIT_DEFAULT_SECONDS
+	});
+};
+var activityTool = defineTool({
+	name: "plitzi_activity",
+	title: "Space activity",
+	description: "What happened on the space since you last looked — an edit by a person or another agent, a version out, an action failing — waited for. Start without `after`, then pass back `cursor`.",
+	inputShape: activityShape,
+	access: "read",
+	documents: false,
+	run: (input, ctx) => activity(input, ctx)
+});
+//#endregion
+export { activity, activityShape, activityTool };

package/dist/modules/mcp/tools/apply/index.js

@@ -1,11 +1,11 @@
 import { dataFileUri, dataUri, functionFileUri, functionsUri } from "../../helpers/uris.js";
+import { defineTool, imageResult } from "../shared/tool.js";
 import { changedResources, conflictMessage, detectConflicts, resolvedElements } from "./writeResult.js";
 import { environment, operations } from "../operations/index.js";
 import { draftBatch } from "../shared/draftBatch.js";
 import { effectsOf } from "../shared/effects.js";
 import { fullPage, lookAt, pageRef, viewport } from "../shared/look.js";
 import { AGAIN, REPEATED, batchKey, forgetRefused, noteRefused, timesRefused } from "../shared/repeats.js";
-import { defineTool, imageResult } from "../shared/tool.js";
 import { z } from "zod";
 import { generateCache } from "@plitzi/sdk-style/StyleHelper";
 //#region src/modules/mcp/tools/apply/index.ts

package/dist/modules/mcp/tools/describeOperation.js

@@ -1,5 +1,5 @@
-import { OPERATIONS_BY_TYPE } from "./operations/index.js";
 import { defineTool } from "./shared/tool.js";
+import { OPERATIONS_BY_TYPE } from "./operations/index.js";
 import { closest } from "@plitzi/sdk-authoring";
 import { z } from "zod";
 //#region src/modules/mcp/tools/describeOperation.ts

package/dist/modules/mcp/tools/index.js

@@ -1,3 +1,4 @@
+import { activityTool } from "./activity.js";
 import { operation } from "./operations/index.js";
 import "./shared/validator/index.js";
 import { apply, applyShape, applyTool } from "./apply/index.js";
@@ -23,7 +24,8 @@ var tools = [
 	readTool,
 	renderTool,
 	lookTool,
-	tryFunctionTool
+	tryFunctionTool,
+	activityTool
 ];
 //#endregion
 export { apply, applyShape, operation, read, readShape, search, searchShape, tools };

package/dist/modules/mcp/tools/intents.js

@@ -1,6 +1,6 @@
 import { findElementByRef } from "../helpers/space.js";
-import { scalar } from "./operations/schema/shared.js";
 import { defineTool } from "./shared/tool.js";
+import { scalar } from "./operations/schema/shared.js";
 import { apply } from "./apply/index.js";
 import { closest } from "@plitzi/sdk-authoring";
 import { z } from "zod";

package/dist/modules/mcp/tools/look.js

@@ -1,5 +1,5 @@
-import { fullPage, lookAt, pageRef, viewport } from "./shared/look.js";
 import { defineTool, imageResult } from "./shared/tool.js";
+import { fullPage, lookAt, pageRef, viewport } from "./shared/look.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/look.ts
 var lookShape = {

package/dist/modules/mcp/tools/render.js

@@ -1,7 +1,7 @@
 import { iconFontCss } from "../apps/render/styles.js";
 import { RENDER_APP_URI } from "../apps/render/index.js";
-import { compactDocumentOperations } from "./operations/index.js";
 import { defineTool } from "./shared/tool.js";
+import { compactDocumentOperations } from "./operations/index.js";
 import { render, renderWidgetShape } from "./renderWidget.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";

package/dist/modules/mcp/tools/shared/tool.d.ts

@@ -5,6 +5,7 @@ import { PreviewClient, ScreenshotClient, ScreenshotImage, Env, Persisters } fro
 import { McpUiToolMeta } from '@modelcontextprotocol/ext-apps';
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { ActionRunReport } from '@plitzi/sdk-shared';
+import { SpaceActivityPage, SpaceActivityQuery } from '@plitzi/sdk-shared/activity';
 /** Everything a tool needs at call time: the loaded space, the target environment, and the persisters (only the
  *  write tools use them). Built by whoever hosts the tools — the MCP server, or a host calling them in-process — so
  *  a tool's behavior never touches spaceId resolution or adapters directly. `spaceId`, `preview` and `screenshot`
@@ -23,6 +24,8 @@ export interface ToolContext {
     /** Runs one task of the space's functions in the sandbox, for the person behind the connection — when the host
      *  wired it. Only plitzi_try_function uses it. */
     tryFunction?: (task: string, params: Record<string, unknown>) => Promise<ActionRunReport>;
+    /** What happened on the space after a cursor, waited for — when the host wired it. Only plitzi_activity uses it. */
+    activity?: (query: SpaceActivityQuery) => Promise<SpaceActivityPage>;
 }
 /** Build the MCP CallToolResult for an image-returning tool: a text meta block followed by one image block per
  *  PNG, so a vision-capable agent (or MCP client) sees the render directly. */
@@ -47,6 +50,9 @@ export interface ToolSpec<Shape extends ZodRawShape> {
     /** The tool operates on no space (plitzi_render authors a throwaway one), so the host must NOT resolve a spaceId
      *  or load a space for it — that keeps it callable with no auth, on the public surface. */
     spaceless?: boolean;
+    /** The tool reads none of the space's documents (plitzi_activity): the host resolves the space but loads nothing of
+     *  it, and the context's `space` is the empty placeholder. A call that waits must not read the whole space first. */
+    documents?: false;
     /** MCP Apps: link this tool to an interactive UI resource (a `ui://` HTML page the host renders in a sandboxed
      *  iframe, receiving the tool result). Registered as the tool's `_meta.ui` — see registerAppTool. */
     ui?: McpUiToolMeta;
@@ -68,6 +74,7 @@ export interface ToolDef {
     carriesOperations?: boolean;
     compactInputShape?: ZodRawShape;
     spaceless?: boolean;
+    documents?: false;
     ui?: McpUiToolMeta;
     execute: (args: unknown, ctx: ToolContext) => unknown;
     /** Present when the tool degrades to a space-less connection (see ToolSpec.runPublic); its absence is what tells

package/dist/modules/mcp/tools/shared/tool.js

@@ -25,6 +25,7 @@ var defineTool = (spec) => {
 		carriesOperations: spec.carriesOperations,
 		compactInputShape: spec.compactInputShape,
 		spaceless: spec.spaceless,
+		documents: spec.documents,
 		ui: spec.ui,
 		execute: (args, ctx) => spec.run(parse(args), ctx),
 		...runPublic ? { executePublic: (args, env) => runPublic(parse(args), env) } : {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-mcp",
-  "version": "0.38.15",
+  "version": "0.38.16",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -35,12 +35,12 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.32.0",
-    "@plitzi/plitzi-sdk": "0.38.15",
-    "@plitzi/sdk-authoring": "0.38.15",
-    "@plitzi/sdk-schema": "0.38.15",
-    "@plitzi/sdk-server": "0.38.15",
-    "@plitzi/sdk-shared": "0.38.15",
-    "@plitzi/sdk-style": "0.38.15",
+    "@plitzi/plitzi-sdk": "0.38.16",
+    "@plitzi/sdk-authoring": "0.38.16",
+    "@plitzi/sdk-schema": "0.38.16",
+    "@plitzi/sdk-server": "0.38.16",
+    "@plitzi/sdk-shared": "0.38.16",
+    "@plitzi/sdk-style": "0.38.16",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "zod": "^4.6.5"