@yaklabs-ai/plugin-sdk 0.12.5 → 0.13.1

package/README.md

@@ -1,7 +1,7 @@
 # @yaklabs-ai/plugin-sdk
 
-The SDK for authoring a **Kay directory plugin** — a plugin you write in a
-repository and add to Kay through an approved plugin repository source.
+The SDK for authoring a **Bonsai directory plugin** — a plugin you write in a
+repository and add to Bonsai through an approved plugin repository source.
 
 Published to the public npm registry under the MIT licence.
 
@@ -13,13 +13,13 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.5"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.1"
   }
 }
 ```
 
 **The alias is not cosmetic.** The package is published as
-`@yaklabs-ai/plugin-sdk`, but Kay's daemon resolves the specifier
+`@yaklabs-ai/plugin-sdk`, but Bonsai's daemon resolves the specifier
 `@kay/plugin-sdk` when it loads your entrypoint, so that is the name your source
 must import. The alias installs the published package at
 `node_modules/@kay/plugin-sdk`, satisfying both.
@@ -79,22 +79,22 @@ export default activate;
 
 ## Entrypoints
 
-| Import                              | What it gives you                                                          |
-| ----------------------------------- | -------------------------------------------------------------------------- |
-| `@kay/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface |
-| `@kay/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules           |
-| `@kay/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs   |
-| `@kay/plugin-sdk/disclosure`        | The conformance audit Kay gates your plugin with — run it before you ship  |
+| Import                              | What it gives you                                                            |
+| ----------------------------------- | ---------------------------------------------------------------------------- |
+| `@kay/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface   |
+| `@kay/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules             |
+| `@kay/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs     |
+| `@kay/plugin-sdk/disclosure`        | The conformance audit Bonsai gates your plugin with — run it before you ship |
 
-`kay-agent/host` is intentionally not published; it is Kay's own loading
+`kay-agent/host` is intentionally not published; it is Bonsai's own loading
 machinery, not an authoring API.
 
 ## Check yourself against the gate that can reject you
 
-Kay runs `auditPluginDisclosure` against your `kay.agent` target **at load,
+Bonsai runs `auditPluginDisclosure` against your `kay.agent` target **at load,
 fail-closed**: one violation and the whole target fails — no tools, no URI
 modules, no skills. It is the same function this entrypoint exports, so the
-run below is the run Kay does.
+run below is the run Bonsai does.
 
 ```ts
 import {
@@ -128,7 +128,7 @@ Pass the loader's inputs, not a subset — the audit judges what it is given:
 - `commandBoundSkillIds` — the `localId` of every skill bound to a declared
   command (`contributes.commands[].handler.kind === "skill"`). Omit it when
   you have such commands and you will see `skill-link-missing-scheme`
-  violations Kay itself would not report.
+  violations Bonsai itself would not report.
 
 `auditSkillCodegenPairs({ declaredSkills, exportedSkills, packageDir })` is the
 companion check for a bundled-skill plugin. It compares the decoded YAML
@@ -138,7 +138,7 @@ Both return violations rather than asserting, so any runner works. Both read fro
 and call your own `help()`, so run them in Node, and keep `activate` free of
 side effects: the probe calls it.
 
-`PLUGIN_DISCLOSURE_CONTRACT` names the floor this SDK enforces. Kay's load
+`PLUGIN_DISCLOSURE_CONTRACT` names the floor this SDK enforces. Bonsai's load
 failure names the floor **it** enforces. Different numbers mean the rules
 moved, not your code — update this package and re-run.
 
@@ -149,47 +149,51 @@ someone remembering to cut one. If the numbers differ, a newer version exists.
 ## What this package is, and is not, at runtime
 
 Installing this SDK gives you **types, editor completion, and a runtime you can
-execute in your own tests**. It is not what runs inside Kay.
+execute in your own tests**. It is not what runs inside Bonsai.
 
 When the daemon loads your plugin, chord bundles its declared target and keeps
 `@kay/plugin-sdk/*` as a host external. Those imports resolve to the SDK
-**bundled with the Kay app**. The host's copy always wins. That is deliberate —
+**bundled with the Bonsai app**. The host's copy always wins. That is deliberate —
 one implementation, the one the daemon is built against — but it has a
 consequence worth stating plainly:
 
-> If your installed SDK is newer than your Kay app, code that typechecks against
+> If your installed SDK is newer than your Bonsai app, code that typechecks against
 > a newly-added API can still fail at load time, because the running host does
 > not have it.
 
 Importing an entire subpath the host does not know about fails loudly and
 specifically (a `target-load` diagnostic naming the subpath, shown on the
-Plugins page). A _symbol_ that exists here but not in the host's older copy is
-not caught that way. Keep the SDK version in step with the Kay app you run.
+App Store on the app's detail page). A _symbol_ that exists here but not in the host's older copy is
+not caught that way. Keep the SDK version in step with the Bonsai app you run.
 
 The same skew applies to the conformance floor, and in the direction that
-bites: if your Kay app is **newer** than this package, it can enforce a rule
+bites: if your Bonsai app is **newer** than this package, it can enforce a rule
 your copy of the audit does not know about, so a green local run is not a
 promise the host will load you. That is why the load failure names its
 contract number — compare it against `PLUGIN_DISCLOSURE_CONTRACT` here, and if
 they differ, update before you debug your code.
 
-## Install the plugin in Kay
+## Install the plugin in Bonsai
 
 The fastest route is the local plugin root. Put the plugin directory in
-`~/.kay/plugins/<your-plugin>/` and turn it on in **Settings → Plugins**. That
-root is already consented, so there is no repository to stage and no Trust step,
-and your edits load without restarting Kay.
+`~/.kay/plugins/<your-plugin>/` and enable it in **App Store → Installed**.
+That root is already consented, so there is no repository to stage and no Trust
+step. Commit your edits to load them without restarting Bonsai; uncommitted edits
+never execute.
 
 To share a plugin with someone who does not have your files, commit it to a Git
-repository and have them add it under **Settings → Plugins → Plugin sources →
-Add repository source**. They stage the source, Trust it, and enable the plugin;
-Trust and activation are separate gates.
+repository and have them add it under **App Store → Sources → Add source**.
+They stage and Trust the source, then add the plugin: **Get** in
+**App Store → Browse** for a marketplace catalog, or **Turn on** on the
+source's page under **App Store → Sources** for a plain Git repository.
+Either action installs and enables that plugin; source Trust does not install
+every item it contains.
 
 A plugin executes as a trusted in-process Node module with the daemon's own
 authority. **The SDK does not provide a sandbox.** Putting code in the local
-plugin root is itself the decision to run it, with no prompt in between — so
-treat that directory exactly as carefully as you would Trust an unfamiliar
-repository.
+plugin root makes it discoverable without a source Trust prompt; enabling its install
+row is still required. Treat that directory exactly as carefully as you would
+Trust an unfamiliar repository.
 
 ## Requirements
 
@@ -200,8 +204,8 @@ checkout script is not the standalone path. The SDK's `kay-app` declarations
 use `node:sqlite`, which TypeScript cannot resolve without the Node 24
 typings.
 
-When Kay loads your plugin, chord bundles the declared entrypoint and its
+When Bonsai loads your plugin, chord bundles the declared entrypoint and its
 relative imports. Multi-file entrypoints are supported, and TypeScript syntax
 that native stripping cannot execute, such as enums, namespaces, constructor
 parameter properties, and decorators, is compiled into the bundle. The host
-SDK remains external and is supplied by the running Kay app.
+SDK remains external and is supplied by the running Bonsai app.

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.5",
+  "version": "0.13.1",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -20,7 +20,7 @@ declare interface AccountIdentity {
     readonly displayName?: string;
     /** Absolute URL of the account's avatar. */
     readonly avatarUrl?: string;
-    /** Issuer-asserted beta-tester flag; only Kay's product-account service sets it. */
+    /** Issuer-asserted beta-tester flag; only Bonsai's product-account service sets it. */
     readonly betaTester?: boolean;
     readonly activeOrganizationId?: string;
     readonly organizationSelectionState?: "selected" | "unresolved";
@@ -28,7 +28,7 @@ declare interface AccountIdentity {
     /**
      * Provider-native session id claim (WorkOS's `sid`), needed to call the provider's own
      * session-revocation endpoint at sign-out (`POST /user_management/sessions/revoke`, not yet
-     * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Kay's WorkOS
+     * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Bonsai's WorkOS
      * product-account exchange/refresh sets it; every other provider leaves it absent.
      */
     readonly providerSessionId?: string;
@@ -164,7 +164,7 @@ declare interface ApiKeyAuthSchemeField {
     readonly label: string;
 }
 
-/** Provider-owned instructions for creating a credential outside Kay. */
+/** Provider-owned instructions for creating a credential outside Bonsai. */
 declare interface ApiKeyAuthSchemeSetup {
     readonly instructions: string;
     /** Absolute HTTPS page where the user can create or manage the credential. */
@@ -755,7 +755,7 @@ declare interface InteractionCandidate {
 declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
 
 declare interface InteractionDriver {
-    /** Unique in the session. `builtin:` is reserved for Kay's own drivers. */
+    /** Unique in the session. `builtin:` is reserved for Bonsai's own drivers. */
     readonly id: string;
     /** Human-readable name the agent sees beside the driver's targets. */
     readonly label: string;
@@ -778,7 +778,7 @@ declare interface InteractionDriver {
 }
 
 /**
- * The Interaction driver contract: what a plugin implements to let Kay's agent drive something
+ * The Interaction driver contract: what a plugin implements to let Bonsai's agent drive something
  * on the user's machine (a browser, an app, a remote screen) through the harness-owned
  * Interaction engine.
  *
@@ -791,7 +791,7 @@ declare interface InteractionDriver {
  * every tool work on every driver.
  *
  * Shape mirrors `SearchProvider` behind `web_search`: one tool set owned by the harness, many
- * backends registered per session, the `builtin:` id namespace reserved for Kay's own.
+ * backends registered per session, the `builtin:` id namespace reserved for Bonsai's own.
  */
 /** "Browser Interaction" drives web pages; "Computer Use Interaction" drives native apps. */
 declare type InteractionDriverKind = "browser" | "computer-use";
@@ -850,7 +850,7 @@ declare interface InteractionRegion {
 }
 
 /**
- * One surface Kay ships, in the driver contract's own shape, so a plugin's driver is the surface
+ * One surface Bonsai ships, in the driver contract's own shape, so a plugin's driver is the surface
  * plus an identity: `{ id, label, kind, ...api.interaction.desktop }`. Each call is checked
  * against the plugin's `interaction.surface {surface}` grant, and then against the session's
  * permissions exactly as the agent's `interaction_*` tools are: an act is judged as the plugin
@@ -972,7 +972,7 @@ declare interface JevScoreQuestion {
  *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
  * ---
  *
- * The vocabulary is Kay's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
+ * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
  * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
  * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
  * criterion is text, and the state is a JSON object.
@@ -1004,7 +1004,7 @@ declare const JsonValue_2: z.ZodType<JsonValue_2>;
 
 declare type JsonValue_3 = null | boolean | number | string | readonly JsonValue_3[] | JsonObject;
 
-/** A plugin's Kay agent activation — receives only the brokered {@link KayAgentPluginApi}. */
+/** A plugin's Bonsai agent activation — receives only the brokered {@link KayAgentPluginApi}. */
 declare type KayAgentActivate = (api: KayAgentPluginApi) => void;
 
 /**
@@ -1024,52 +1024,14 @@ declare interface KayAgentEvents {
     publish(localId: string, payload: unknown): void;
 }
 
-/**
- * Claim-checked filesystem operations. Paths are root-relative; canonical host paths never cross
- * the seam. Writes are atomic: readers see the old file or the new one, never a partial write. A
- * replace keeps the file's mode but makes a new file, so owner and extended attributes are not
- * carried over. On a volume without hard links an exclusive create can briefly show an empty file.
- */
-declare interface KayAgentFilesystem {
-    readText(location: KayAgentFilesystemLocation): Promise<string>;
-    writeText(location: KayAgentFilesystemLocation, content: string, options?: KayAgentFilesystemWriteOptions): Promise<void>;
-    /** The whole file, or the requested window of it. */
-    readBytes(location: KayAgentFilesystemLocation, range?: KayAgentFilesystemByteRange): Promise<Uint8Array>;
-    writeBytes(location: KayAgentFilesystemLocation, bytes: Uint8Array, options?: KayAgentFilesystemWriteOptions): Promise<void>;
-    mkdir(location: KayAgentFilesystemLocation): Promise<void>;
-    readDir(location: KayAgentFilesystemLocation): Promise<readonly KayAgentFilesystemEntry[]>;
-    stat(location: KayAgentFilesystemLocation): Promise<KayAgentFilesystemStat>;
-    rename(from: KayAgentFilesystemLocation, to: KayAgentFilesystemLocation): Promise<void>;
-    /** Returns the canonical path relative to the selected grant root. */
-    realpath(location: KayAgentFilesystemLocation): Promise<string>;
-}
-
-/** A byte window of a file; `maxBytes` is capped by the host. */
-declare interface KayAgentFilesystemByteRange {
-    readonly offset: number;
-    readonly maxBytes: number;
-}
-
-declare interface KayAgentFilesystemEntry {
-    readonly name: string;
-    readonly kind: "file" | "directory" | "symlink" | "other";
-}
-
-declare interface KayAgentFilesystemLocation {
-    /** Exact `root` selector the host bound for this target, plus a path relative to it. */
-    readonly root: string;
-    readonly path: string;
-}
-
-declare interface KayAgentFilesystemStat {
-    readonly kind: "file" | "directory" | "other";
-    readonly size: number;
-    readonly modifiedAtMs: number;
-}
-
-declare interface KayAgentFilesystemWriteOptions {
-    /** Fail with `already_exists` instead of replacing a file already at the location. */
-    readonly exclusive?: boolean;
+/** This plugin's folder in the session family's shared Whiteboard. */
+declare interface KayAgentFamilyFolder {
+    /**
+     * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
+     * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
+     * Undefined outside a session.
+     */
+    path(): Promise<string | undefined>;
 }
 
 declare interface KayAgentInteractionSurfaces {
@@ -1081,7 +1043,7 @@ declare interface KayAgentInteractionSurfaces {
     readonly browserPane: InteractionSurface;
     /**
      * The user's desktop through the platform's accessibility APIs: native apps as targets
-     * (`app://<bundle id>`), their windows' controls as elements. On macOS Kay drives it with its
+     * (`app://<bundle id>`), their windows' controls as elements. On macOS Bonsai drives it with its
      * bundled accessibility worker under the app's Accessibility permission; on a platform with no
      * backend it reports itself unavailable.
      */
@@ -1211,11 +1173,8 @@ declare interface KayAgentPluginApi {
         /** Register a whole URI module (a scheme handler that owns its address space, e.g. `drive://`). */
         registerModule(module: UriExtensionModule): void;
     };
-    /**
-     * Always present; each call is checked against `filesystem.read {root}` / `filesystem.write
-     * {root}` for the root it touches, and against the host's binding for that root.
-     */
-    readonly filesystem: KayAgentFilesystem;
+    /** This plugin's folder in the session family's shared Whiteboard, created on first use. Undefined outside a session. */
+    readonly familyFolder: KayAgentFamilyFolder;
     /** Absent unless the `knowledgeSearch` grant is requested and effectively granted. */
     readonly knowledgeSearch?: KayAgentKnowledgeSearch;
     /** Absent unless the `knownResources` grant is requested and effectively granted. */
@@ -1241,7 +1200,7 @@ declare interface KayAgentPluginApi {
      */
     readonly process: KayAgentProcess;
     /**
-     * Always present; the interaction surfaces Kay ships (its browser pane, and the desktop through
+     * Always present; the interaction surfaces Bonsai ships (its browser pane, and the desktop through
      * the platform accessibility APIs), each call checked against `interaction.surface {surface}`
      * and the session's permissions (see {@link InteractionSurface}).
      * Wrap one in an {@link InteractionDriver} and register it with
@@ -1268,9 +1227,8 @@ declare interface KayAgentPluginApi {
     readonly time: KayAppTime;
     /**
      * File I/O in user folders, run by the host on its own worker threads under a deadline and
-     * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
-     * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
-     * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
+     * answered as a typed result. Always present and ungated: it takes absolute paths and checks no
+     * grant, because it adds no authority a plugin's `node:fs` does not already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
      * {@link KayAppUserFiles}.
      */
     readonly userFiles: KayAppUserFiles;
@@ -1841,7 +1799,7 @@ declare type ModelPromptCache = Partial<Record<Exclude<CacheRetention, "none">,
 declare type ModelThinkingLevel = "off" | ThinkingLevel;
 
 /**
- * Who may supply the OAuth client for a scheme: Kay's embedded client, or one the user pastes in
+ * Who may supply the OAuth client for a scheme: Bonsai's embedded client, or one the user pastes in
  * (BYOOC). An UNORDERED SET — list order carries no meaning (nothing reads it as a preference).
  */
 declare type OAuthClientSupplier = "kay" | "user";
@@ -1854,7 +1812,7 @@ declare interface OAuthRedirectResult {
 
 /**
  * The two client-supply axes, structured so the illegal cell is unrepresentable: a `confidential`
- * exchange's secret may only ever be Kay's (held by the host's broker, never pasted by a
+ * exchange's secret may only ever be Bonsai's (held by the host's broker, never pasted by a
  * customer), so `confidential` types `clientSuppliers` as `readonly ["kay"]` — `confidential ×
  * user` is a compile-time impossibility in v1, not a runtime refusal. `pkce`'s `clientSuppliers`
  * is a non-empty set; {@link createOAuthPkceAuthScheme} dedupes it and refuses empty.
@@ -2037,7 +1995,7 @@ declare interface OpenRouterRouting {
  * {@link PLUGIN_DISCLOSURE_RULES} changes, and never for anything else.
  *
  * Two readers, and the second is why a number beats a changelog entry. A plugin author compares it
- * against the Kay build they target. The daemon's loader NAMES it in the
+ * against the Bonsai build they target. The daemon's loader NAMES it in the
  * `disclosure-conformance-failed` diagnostic, so a plugin that passed its own suite against an
  * older SDK and then failed at load says "this host enforces contract N, you audited against
  * something older" instead of leaving the author to guess whether their code or their SDK moved.
@@ -2126,7 +2084,7 @@ declare interface PluginDelegatedScheme {
     readonly connect: (ctx: PluginDelegatedConnectContext) => Promise<PluginDelegatedConnectResult>;
     /**
      * Mint fresh material from the current (expiring) material, including the `data` the last
-     * connect or refresh returned. Kay calls this only inside its credential authority, which holds
+     * connect or refresh returned. Bonsai calls this only inside its credential authority, which holds
      * the refresh lease and saves the result; this hook performs the exchange and nothing else.
      * Returned `data` replaces the stored `data`; omitted `data` keeps it. Returned `expiresAt`
      * replaces the stored expiry; omitted `expiresAt` means the new material does not expire.
@@ -2203,7 +2161,7 @@ declare type PluginOAuthPkceScheme = PluginOAuthSchemeClientAxes & {
     readonly summary?: string;
     readonly authorizationUrl: string;
     readonly tokenUrl: string;
-    /** The Kay-supplied embedded client id; omit for a `confidential` scheme or a `pkce` scheme
+    /** The Bonsai-supplied embedded client id; omit for a `confidential` scheme or a `pkce` scheme
      *  the host ships no client for. */
     readonly clientId?: string;
     /**
@@ -2833,6 +2791,14 @@ declare interface ToolDefinition<TParams extends ToolParametersWire = ToolParame
      * explicit Stop.
      */
     durationClass?: "fast" | "long";
+    /**
+     * Set only for a tool whose rerun with the same arguments is harmless, such
+     * as one keyed on its own call: after a crash cuts a call off, a pi-durable
+     * session may rerun it with its recorded arguments (without `before_tool`)
+     * instead of ending it as an interrupted error. Absent: never rerun. Ignored
+     * on pi 0.99.1.
+     */
+    replaySafe?: true;
     /**
      * Optional capability⇄scheme binding. When present this tool is auth-gated: discoverable when
      * unauthed, callable once the binding is satisfied. The SDK's {@link withResolvedAuth}
@@ -2916,9 +2882,9 @@ declare type ToolParametersWire = unknown;
  *
  * The host is trusted to supply honest values; a declared `kind` of `read` moves a call below
  * the protected-path hard-deny (which only fires for non-read kinds), so a tool that could
- * touch protected config must NOT declare `read`. Kay's embedded-experience tools never touch
+ * touch protected config must NOT declare `read`. Bonsai's embedded-experience tools never touch
  * `configDir`, so this is safe for them. `read` is also what every capability surface reports as
- * "read-only" (Kay's Permissions page groups and defaults on it), so it is a claim about what the
+ * "read-only" (Bonsai's Permissions page groups and defaults on it), so it is a claim about what the
  * tool DOES — never a way to buy silence. A tool that should raise no ask on its own account
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
@@ -2959,7 +2925,7 @@ declare interface ToolPermissionHint {
      * because the same tool can read on one input and execute on another, which a static `kind`
      * cannot express.
      *
-     * Exemplar — Kay's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
+     * Exemplar — Bonsai's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
      * `{ kind: "read" }` (metadata lookups), while `call` derives
      * `{ kind: "execute", ruleKey: "mcp:<server>::<tool>", scheme: "<server>" }`, so a
      * `{ scheme: "<server>" }` rule gates a whole server and a `{ ruleKey: "mcp:<server>::<tool>" }`
@@ -3000,7 +2966,7 @@ declare interface ToolPermissionHint {
      * really had — not that the result is always stricter than the target's. How much gate is left
      * on such a call is exactly how much the CARRIER carries: an `execute` carrier is stricter than
      * a `read` target and equal to a `mutate`/`destructive` one outside allow mode, while a
-     * {@link quiet} carrier (Kay's own `call_tool`) contributes no mode default at all, so the
+     * {@link quiet} carrier (Bonsai's own `call_tool`) contributes no mode default at all, so the
      * fallback leaves nothing but the carrier's rules and the protected-path deny — and the carrier
      * names no path, so that deny has nothing to fire on. This is why a carrier must refuse a target
      * that is itself a carrier: no chain long or circular enough to reach the fallback can be built,
@@ -3024,7 +2990,7 @@ declare interface ToolPermissionHint {
      * whose only effect is invoking the target the gate is already classifying beside it: the
      * target's kind, rules, resources and the protected-path deny all still decide, so a proxied
      * call is gated exactly like the direct one — no more, and no ask the direct call would never
-     * have raised. Kay's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
+     * have raised. Bonsai's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
      * 2026-08-18): honest about everything it can reach, silent on its own account.
      *
      * Quiet is not ungated, but it IS nearly all the gate a lone carrier has. On a call that
@@ -3214,13 +3180,19 @@ declare interface UriExtensionModule extends Omit<UriModule, "verbs"> {
     readonly permissionDefaults?: UriPermissionDefaults;
     /** Requires a resolved URI connection before any verb handler runs. */
     readonly requiresConnection?: boolean;
-    /** Pure route-aware permission facts; may only strengthen the verb default. */
+    /** Pure route-aware permission facts; see {@link UriExtensionOperationPermissionPolicy}. */
     readonly permission?: UriExtensionOperationPermissionPolicy;
     /** False rejects generic write-tool `source` copies before source fetch. */
     readonly acceptsSourceCopy?: boolean;
 }
 
 declare interface UriExtensionOperationPermissionPolicy {
+    /**
+     * Classify one canonical route, purely. `write`/`edit`/`delete` may only be made stricter
+     * than the verb default; `help`/`read`/`list`/`search` must stay `"read"` (a `ruleKey` is
+     * allowed), because the kernel reruns a crash-interrupted read without asking again. Any
+     * other answer, or a throw, fails the call closed.
+     */
     classifyOperation(request: {
         readonly operation: UriOperation;
         readonly uri: string;
@@ -3448,7 +3420,15 @@ declare interface UriModule {
     normalize?(input: string, ctx: UriResolveContext): UriNormalizeResult | undefined;
     describe?(input: string, ctx: UriDescribeContext): UriResourceDescription | undefined;
     locate?(input: string, ctx: UriLocateContext): Promise<UriLocateResult>;
+    /**
+     * `read`, `help`, `list` and `search` observe; they never change the resource or anything
+     * outside the host. Repeating one with the same input must be harmless: the kernel reruns a
+     * call of these verbs that a crash cut off, with the same input, without asking the user
+     * again. Idempotent bookkeeping (a cache fill, an index of what was read, a usage count) is
+     * fine; a send, a mark-as-read or a create is not, and belongs on a mutating verb.
+     */
     read(input: string, ctx: UriResolveContext): Promise<RawResource>;
+    /** Observes only; see {@link read}. */
     help?(input: string, ctx: UriResolveContext): Promise<UriHelp>;
     write?(input: string, content: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult | void>;
     /** Opt-in structured write with one or more host-resolved resources delivered beside the content. */
@@ -3471,7 +3451,9 @@ declare interface UriModule {
      */
     writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
     edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
+    /** Observes only; see {@link read}. */
     list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
+    /** Observes only; see {@link read}. */
     search?(input: string, params: UriSearchParams, ctx: UriResolveContext): Promise<UriSearchResult>;
     delete?(input: string, ctx: UriResolveContext): Promise<UriMutationResult>;
     toMarkdown?(input: UriMarkdownRenderInput, ctx: UriResolveContext): string | undefined;
@@ -3689,7 +3671,7 @@ declare interface UriResolveContext {
      * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller — so a module
      * writing to a store it owns can record the actor without the agent being able to choose one.
      *
-     * Free text minted by the host's own runtime (Kay's form is `user`, `subagent`,
+     * Free text minted by the host's own runtime (Bonsai's form is `user`, `subagent`,
      * `system/<surface>`, `followup/<surface>`) rather than a closed union: the surface half is the
      * host's vocabulary, and a second enumeration of it here would drift from the first.
      *

package/dist/disclosure.js

@@ -765,17 +765,6 @@ function unavailableInteractionSurfaces(message) {
 // packages/plugin-sdk/dist/disclosure/probe-kay-agent-capabilities.js
 var inertResult = () => new Promise(() => {
 });
-var INERT_FILESYSTEM = {
-  readText: inertResult,
-  writeText: inertResult,
-  readBytes: inertResult,
-  writeBytes: inertResult,
-  mkdir: inertResult,
-  readDir: inertResult,
-  stat: inertResult,
-  rename: inertResult,
-  realpath: inertResult
-};
 var INERT_NETWORK = {
   fetch: inertResult
 };
@@ -807,7 +796,6 @@ var INERT_WHITEBOARD = {
 var INERT_WITH_JEV = async (_use, fallback) => fallback();
 function createKayAgentProbeCapabilityHandles() {
   return {
-    filesystem: INERT_FILESYSTEM,
     network: INERT_NETWORK,
     webSession: INERT_WEB_SESSION,
     process: INERT_PROCESS,
@@ -825,7 +813,7 @@ function createKayAgentProbeCapabilityHandles() {
     time: {
       snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
     },
-    // Inert like the filesystem broker: a probe must never touch the user's disk.
+    // Inert like the process broker: a probe must never touch the user's disk.
     userFiles: {
       stat: inertResult,
       readText: inertResult,
@@ -835,7 +823,9 @@ function createKayAgentProbeCapabilityHandles() {
       writeText: inertResult,
       mkdir: inertResult,
       rename: inertResult
-    }
+    },
+    // A probe runs outside any session, and must not create a folder on the user's disk.
+    familyFolder: { path: async () => void 0 }
   };
 }