@fias/create-fias-plugin 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.26.0 -->
+<!-- fias-sdk-guide-version: 2.27.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -283,6 +283,121 @@ Why this and not `createCollection` at startup: the runtime op is capped at **10
 
 Re-publishing is safe: existing collections are left alone, a stricter role floor is applied, a looser one is refused, and a collection you stop declaring is kept (never deleted — it may hold user data). Keep using `createCollection` for collections whose names you only know at runtime.
 
+### Letting agents use your data (`agentAccess`)
+
+**Permission:** `data:agents` (requires `data:store`)
+
+Your plugin can share some of its collections with AI agents — the platform's Fias AI assistant, and agents a user connects over MCP (Claude Code and others) — **while your plugin is closed**. Agents never run your code: they read and change documents through a fixed set of platform tools (`plugin_apps_list`, `plugin_app_describe`, `plugin_data_query`, `plugin_data_get`, `plugin_data_put`, `plugin_data_patch`, `plugin_data_delete`). Declare what you share in `fias-plugin.json`:
+
+```jsonc
+"permissions": ["data:store", "data:agents"],
+"collections": [
+  { "name": "scenes", "scope": "user" },
+  { "name": "render_requests", "scope": "user" },
+  { "name": "previews", "scope": "user" }
+],
+"agentAccess": {
+  "description": "Puppet cut scenes: a cast, scene-frames and spoken lines.",
+  "collections": {
+    "scenes": {
+      "access": "read_write",
+      "description": "One cut scene per document, keyed by scene id.",
+      "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }
+    },
+    "render_requests": {
+      "access": "read_write",
+      "description": "Ask the open app for stills of a scene at chosen times.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "scene": { "type": "string", "maxLength": 100 },
+          "times": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 1, "maxItems": 12 },
+          "width": { "type": "integer", "minimum": 64, "maximum": 800 },
+          "status": { "enum": ["pending", "working", "done", "failed"] },
+          "error": { "type": "string", "maxLength": 2000 },
+          "previews": { "type": "integer", "minimum": 0, "maximum": 12 }
+        },
+        "required": ["scene", "times", "status"],
+        "additionalProperties": false
+      }
+    },
+    "previews": { "access": "read", "description": "Stills the open app rendered.", "images": ["/image"] }
+  }
+}
+```
+
+Rules (checked by `fias-dev validate` and at publish):
+
+- `data:agents` and the `agentAccess` block go together: declaring the permission without a block is an error.
+- Only collections you declare in `collections`, with `user` or `shared` scope. `read_write` only on `user` scope (a write to a `shared` collection would land in every user's copy), and it needs a `schema` — every agent write is validated against it. `workspace` collections can't be shared with agents yet.
+- Schemas use a restricted JSON Schema 2020-12: `type`, `properties`, `required`, `additionalProperties`, `items`, `prefixItems`, `enum`, `const`, min/max bounds, `anyOf`/`oneOf`/`allOf`/`not`, `title`, `description`, `default`, `examples`, `format` (annotation only), and `$ref` to your own `#/$defs/…`. **No `pattern`** (regular expressions), no `propertyNames`, and no remote `$ref`. `uniqueItems` only on arrays whose `items` have a scalar `type`. A `$ref` may recurse only through `properties` / `items` / `additionalProperties` (a tree), never straight back to itself. ≤ 16 KB per schema, depth ≤ 12. If you generate schemas with Zod, note that `z.record()` emits `propertyNames` and `z.email()` / `z.uuid()` / `z.regex()` emit `pattern` — neither is accepted.
+- Descriptions describe your data — they are not instructions to an AI. The publish review flags text that tells an agent what to do, links, and mentions of other apps.
+- `images` names fields holding `{ "mimeType": "image/png" | "image/jpeg" | "image/webp", "data": "<base64>" }` (≤ 96 KB, ≤ 2000 px a side; every image is fully decoded before an agent sees it, and one that doesn't decode is replaced by an error). Agents receive them as pictures and can never write them — so in a `read_write` collection an image field must be optional, never `required`.
+
+What agents can do: **Fias AI** acts as the signed-in user on what you declare. An **external agent** reaches your app only through an API key the user allowed to use it, collection by collection, read or read and change — and if you later share more, nothing new is reachable until the user allows it again. Every agent write is conditional on the version it read, so it can't silently overwrite a change made in your open UI; deletes always need the user's confirmation in Fias.
+
+**Your obligation for `read_write` collections: validate what you load.** An agent — or text an agent was shown — may have written it. Treat those documents like any untrusted input; never evaluate or render a field as code or HTML.
+
+**Answering an agent while open (previews).** Agents can't run your code, but your open plugin can do work for them through data. Watch a requests collection, do the work, and write the answer back:
+
+```tsx
+const dataStore = useFiasDataStore();
+const answerPending = useCallback(async () => {
+  const { documents } = await dataStore.query<RenderRequest>('render_requests', {
+    filters: [{ field: 'status', op: 'eq', value: 'pending' }],
+    limit: 5,
+  });
+  for (const req of documents) {
+    // Claim it first, so two open tabs never both do it.
+    const claimed = await dataStore
+      .batch(
+        [
+          {
+            op: 'put',
+            collection: 'render_requests',
+            key: req.key,
+            data: { ...req.data, status: 'working' },
+          },
+        ],
+        {
+          preconditions: [
+            { kind: 'version', collection: 'render_requests', key: req.key, version: req.version },
+          ],
+        },
+      )
+      .then(
+        () => true,
+        () => false,
+      );
+    if (!claimed) continue;
+    const stills = await renderStills(req.data); // your own code, bounded by your schema
+    for (const [i, image] of stills.entries()) {
+      await dataStore.put('previews', `${req.key}-${i}`, {
+        request: req.key,
+        t: req.data.times[i],
+        image,
+      });
+    }
+    await dataStore.put('render_requests', req.key, {
+      ...req.data,
+      status: 'done',
+      previews: stills.length,
+    });
+  }
+}, [dataStore]);
+useDataSubscription('render_requests', answerPending); // changes arrive at most once —
+useEffect(() => {
+  // so also check on open and every ~10 s
+  void answerPending();
+  const timer = setInterval(answerPending, 10_000);
+  return () => clearInterval(timer);
+}, [answerPending]);
+```
+
+The agent writes a request, waits on it with `plugin_data_get` (`afterVersion` + `waitSeconds`), and reads the stills back as images. Keep requests bounded in your schema (e.g. `"times": { "maxItems": 12 }`), prune old previews, and report failures in the request (e.g. `status: "failed"` with errors) so the agent can fix what it wrote. **Give both the requests and the results collections `user` scope** — in a `shared` collection any user of your app could plant a "result" that another user's agent then reads.
+
+**Testing:** in the dev harness's Fias AI window, the read tools see your local `agentAccess` block against your dev data — ask "what scenes do I have?" to see what an agent sees before you publish.
+
 **Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `batch` 30, `createCollection` 10
 
 **Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.26.0 -->
+<!-- fias-sdk-guide-version: 2.27.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -283,6 +283,121 @@ Why this and not `createCollection` at startup: the runtime op is capped at **10
 
 Re-publishing is safe: existing collections are left alone, a stricter role floor is applied, a looser one is refused, and a collection you stop declaring is kept (never deleted — it may hold user data). Keep using `createCollection` for collections whose names you only know at runtime.
 
+### Letting agents use your data (`agentAccess`)
+
+**Permission:** `data:agents` (requires `data:store`)
+
+Your plugin can share some of its collections with AI agents — the platform's Fias AI assistant, and agents a user connects over MCP (Claude Code and others) — **while your plugin is closed**. Agents never run your code: they read and change documents through a fixed set of platform tools (`plugin_apps_list`, `plugin_app_describe`, `plugin_data_query`, `plugin_data_get`, `plugin_data_put`, `plugin_data_patch`, `plugin_data_delete`). Declare what you share in `fias-plugin.json`:
+
+```jsonc
+"permissions": ["data:store", "data:agents"],
+"collections": [
+  { "name": "scenes", "scope": "user" },
+  { "name": "render_requests", "scope": "user" },
+  { "name": "previews", "scope": "user" }
+],
+"agentAccess": {
+  "description": "Puppet cut scenes: a cast, scene-frames and spoken lines.",
+  "collections": {
+    "scenes": {
+      "access": "read_write",
+      "description": "One cut scene per document, keyed by scene id.",
+      "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }
+    },
+    "render_requests": {
+      "access": "read_write",
+      "description": "Ask the open app for stills of a scene at chosen times.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "scene": { "type": "string", "maxLength": 100 },
+          "times": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 1, "maxItems": 12 },
+          "width": { "type": "integer", "minimum": 64, "maximum": 800 },
+          "status": { "enum": ["pending", "working", "done", "failed"] },
+          "error": { "type": "string", "maxLength": 2000 },
+          "previews": { "type": "integer", "minimum": 0, "maximum": 12 }
+        },
+        "required": ["scene", "times", "status"],
+        "additionalProperties": false
+      }
+    },
+    "previews": { "access": "read", "description": "Stills the open app rendered.", "images": ["/image"] }
+  }
+}
+```
+
+Rules (checked by `fias-dev validate` and at publish):
+
+- `data:agents` and the `agentAccess` block go together: declaring the permission without a block is an error.
+- Only collections you declare in `collections`, with `user` or `shared` scope. `read_write` only on `user` scope (a write to a `shared` collection would land in every user's copy), and it needs a `schema` — every agent write is validated against it. `workspace` collections can't be shared with agents yet.
+- Schemas use a restricted JSON Schema 2020-12: `type`, `properties`, `required`, `additionalProperties`, `items`, `prefixItems`, `enum`, `const`, min/max bounds, `anyOf`/`oneOf`/`allOf`/`not`, `title`, `description`, `default`, `examples`, `format` (annotation only), and `$ref` to your own `#/$defs/…`. **No `pattern`** (regular expressions), no `propertyNames`, and no remote `$ref`. `uniqueItems` only on arrays whose `items` have a scalar `type`. A `$ref` may recurse only through `properties` / `items` / `additionalProperties` (a tree), never straight back to itself. ≤ 16 KB per schema, depth ≤ 12. If you generate schemas with Zod, note that `z.record()` emits `propertyNames` and `z.email()` / `z.uuid()` / `z.regex()` emit `pattern` — neither is accepted.
+- Descriptions describe your data — they are not instructions to an AI. The publish review flags text that tells an agent what to do, links, and mentions of other apps.
+- `images` names fields holding `{ "mimeType": "image/png" | "image/jpeg" | "image/webp", "data": "<base64>" }` (≤ 96 KB, ≤ 2000 px a side; every image is fully decoded before an agent sees it, and one that doesn't decode is replaced by an error). Agents receive them as pictures and can never write them — so in a `read_write` collection an image field must be optional, never `required`.
+
+What agents can do: **Fias AI** acts as the signed-in user on what you declare. An **external agent** reaches your app only through an API key the user allowed to use it, collection by collection, read or read and change — and if you later share more, nothing new is reachable until the user allows it again. Every agent write is conditional on the version it read, so it can't silently overwrite a change made in your open UI; deletes always need the user's confirmation in Fias.
+
+**Your obligation for `read_write` collections: validate what you load.** An agent — or text an agent was shown — may have written it. Treat those documents like any untrusted input; never evaluate or render a field as code or HTML.
+
+**Answering an agent while open (previews).** Agents can't run your code, but your open plugin can do work for them through data. Watch a requests collection, do the work, and write the answer back:
+
+```tsx
+const dataStore = useFiasDataStore();
+const answerPending = useCallback(async () => {
+  const { documents } = await dataStore.query<RenderRequest>('render_requests', {
+    filters: [{ field: 'status', op: 'eq', value: 'pending' }],
+    limit: 5,
+  });
+  for (const req of documents) {
+    // Claim it first, so two open tabs never both do it.
+    const claimed = await dataStore
+      .batch(
+        [
+          {
+            op: 'put',
+            collection: 'render_requests',
+            key: req.key,
+            data: { ...req.data, status: 'working' },
+          },
+        ],
+        {
+          preconditions: [
+            { kind: 'version', collection: 'render_requests', key: req.key, version: req.version },
+          ],
+        },
+      )
+      .then(
+        () => true,
+        () => false,
+      );
+    if (!claimed) continue;
+    const stills = await renderStills(req.data); // your own code, bounded by your schema
+    for (const [i, image] of stills.entries()) {
+      await dataStore.put('previews', `${req.key}-${i}`, {
+        request: req.key,
+        t: req.data.times[i],
+        image,
+      });
+    }
+    await dataStore.put('render_requests', req.key, {
+      ...req.data,
+      status: 'done',
+      previews: stills.length,
+    });
+  }
+}, [dataStore]);
+useDataSubscription('render_requests', answerPending); // changes arrive at most once —
+useEffect(() => {
+  // so also check on open and every ~10 s
+  void answerPending();
+  const timer = setInterval(answerPending, 10_000);
+  return () => clearInterval(timer);
+}, [answerPending]);
+```
+
+The agent writes a request, waits on it with `plugin_data_get` (`afterVersion` + `waitSeconds`), and reads the stills back as images. Keep requests bounded in your schema (e.g. `"times": { "maxItems": 12 }`), prune old previews, and report failures in the request (e.g. `status: "failed"` with errors) so the agent can fix what it wrote. **Give both the requests and the results collections `user` scope** — in a `shared` collection any user of your app could plant a "result" that another user's agent then reads.
+
+**Testing:** in the dev harness's Fias AI window, the read tools see your local `agentAccess` block against your dev data — ask "what scenes do I have?" to see what an agent sees before you publish.
+
 **Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `batch` 30, `createCollection` 10
 
 **Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.