@yaklabs-ai/plugin-sdk 0.12.5 → 0.13.1

package/dist/jev.d.ts

@@ -138,7 +138,7 @@ export 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.

package/dist/kay-agent-testing.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. */
@@ -531,7 +531,7 @@ declare interface ExtensionPaths {
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
 /** The capability handles a `KayAgentPluginApi` always carries — authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time" | "userFiles">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time" | "userFiles" | "familyFolder">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -641,7 +641,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;
@@ -664,7 +664,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.
  *
@@ -677,7 +677,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";
@@ -736,7 +736,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
@@ -876,7 +876,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.
@@ -925,52 +925,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 {
@@ -982,7 +944,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.
      */
@@ -1112,11 +1074,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. */
@@ -1142,7 +1101,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
@@ -1169,9 +1128,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;
@@ -1742,7 +1700,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";
@@ -1755,7 +1713,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.
@@ -1994,7 +1952,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.
@@ -2068,7 +2026,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;
     /**
@@ -2731,6 +2689,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}
@@ -2814,9 +2780,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`.
  */
@@ -2857,7 +2823,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>" }`
@@ -2898,7 +2864,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,
@@ -2922,7 +2888,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
@@ -3112,13 +3078,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;
@@ -3346,7 +3318,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. */
@@ -3369,7 +3349,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;
@@ -3587,7 +3569,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/kay-agent-testing.js

@@ -147,17 +147,6 @@ var USER_FILE_METHODS = [
 ];
 function fauxKayAgentCapabilities() {
   return {
-    filesystem: {
-      readText: unwired("filesystem.readText"),
-      writeText: unwired("filesystem.writeText"),
-      readBytes: unwired("filesystem.readBytes"),
-      writeBytes: unwired("filesystem.writeBytes"),
-      mkdir: unwired("filesystem.mkdir"),
-      readDir: unwired("filesystem.readDir"),
-      stat: unwired("filesystem.stat"),
-      rename: unwired("filesystem.rename"),
-      realpath: unwired("filesystem.realpath")
-    },
     network: { fetch: unwired("network.fetch") },
     webSession: {
       request: unwired("webSession.request"),
@@ -210,7 +199,10 @@ function fauxKayAgentCapabilities() {
         kind: "error",
         detail: `userFiles.${name} is not wired in this test double`
       })
-    ]))
+    ])),
+    // A test double runs outside any session, so it has no family folder — the same answer the
+    // real capability gives. A test that exercises one overrides this handle after the spread.
+    familyFolder: { path: async () => void 0 }
   };
 }
 function defaultTestToolContext() {