@yaklabs-ai/plugin-sdk 0.13.0 → 0.13.1

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. */
@@ -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.
@@ -944,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.
      */
@@ -1101,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
@@ -1700,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";
@@ -1713,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.
@@ -1952,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.
@@ -2026,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;
     /**
@@ -2689,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}
@@ -2772,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`.
  */
@@ -2815,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>" }`
@@ -2856,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,
@@ -2880,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
@@ -3070,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;
@@ -3304,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. */
@@ -3327,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;
@@ -3545,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.d.ts

@@ -21,7 +21,7 @@ export 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";
@@ -29,7 +29,7 @@ export 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;
@@ -206,7 +206,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. */
@@ -704,7 +704,7 @@ declare interface DelegatedConnectResult {
 
 /**
  * The terminal failure of {@link PluginDelegatedScheme.refresh}: the provider no longer accepts the
- * stored grant (an OAuth `invalid_grant`, say), so only a reconnect helps. Kay marks the account
+ * stored grant (an OAuth `invalid_grant`, say), so only a reconnect helps. Bonsai marks the account
  * as needing a reconnect. Throw any other error for a failure that may pass on its own.
  */
 export declare class DelegatedRefreshRejectedError extends Error {
@@ -972,7 +972,7 @@ export declare interface InteractionCandidate {
 export declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
 
 export 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;
@@ -995,7 +995,7 @@ export 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.
  *
@@ -1008,7 +1008,7 @@ export 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. */
 export declare type InteractionDriverKind = "browser" | "computer-use";
@@ -1067,7 +1067,7 @@ export 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
@@ -1077,7 +1077,7 @@ export declare interface InteractionRegion {
  */
 export declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targets" | "observe" | "act" | "screenshot" | "open">;
 
-/** The interaction surfaces Kay itself ships, which plugins drive through `api.interaction`. */
+/** The interaction surfaces Bonsai itself ships, which plugins drive through `api.interaction`. */
 export declare type InteractionSurfaceName = "browser-pane" | "desktop";
 
 /**
@@ -1224,7 +1224,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.
@@ -1273,7 +1273,7 @@ declare type JsonValue_3 = string | number | boolean | null | JsonValue_3[] | {
 
 declare const JsonValue_3: z.ZodType<JsonValue_3>;
 
-/** A plugin's Kay agent activation — receives only the brokered {@link KayAgentPluginApi}. */
+/** A plugin's Bonsai agent activation — receives only the brokered {@link KayAgentPluginApi}. */
 export declare type KayAgentActivate = (api: KayAgentPluginApi) => void;
 
 export declare type KayAgentAdvertisedApiKeyScheme = WithoutImplementation<PluginApiKeyScheme, "validate">;
@@ -1334,7 +1334,7 @@ export declare interface KayAgentAdvertisementAuthApi {
  * means the host bound no concrete authority. A plugin should surface a `grant` refusal to the user
  * and give up quietly on a `source-class` one. Within `grant`, branch on `code` before wording a
  * prompt: `not-granted` means the user has not consented (or has revoked it), while
- * `grant-read-failed` means Kay could not read its own consent store and refused rather than
+ * `grant-read-failed` means Bonsai could not read its own consent store and refused rather than
  * assume — the second is not something a grant prompt fixes.
  *
  * Broker handles are always present, so presence does not imply a current grant or concrete
@@ -1389,7 +1389,7 @@ export 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.
      */
@@ -1546,7 +1546,7 @@ export 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
@@ -2968,7 +2968,7 @@ export declare function num(record: Record<string, unknown> | undefined, key: st
 export declare function numLike(record: Record<string, unknown> | undefined, key: string): number | undefined;
 
 /**
- * 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";
@@ -2990,7 +2990,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.
@@ -3626,7 +3626,7 @@ export 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.
@@ -3706,7 +3706,7 @@ export 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;
     /**
@@ -3755,7 +3755,7 @@ export declare interface PluginServiceDescriptor {
  * (one record per plugin, not per skill) because a skill's asset tree is everything under
  * `dirname(contribution.path)` by convention — a multi-file `SKILL.md` + `references/` tree
  * belongs to the plugin as a whole, the same way {@link PluginSkillDefinition.content} is the
- * plugin's compiled-in codegen pair of one `SKILL.md`. The Kay runtime materializes this record to real
+ * plugin's compiled-in codegen pair of one `SKILL.md`. The Bonsai runtime materializes this record to real
  * files on disk at daemon composition (`<managed>/plugin-assets/<pluginId>/<packageRelativePath>`)
  * so relative references inside a skill resolve the same way a filesystem skill's do — no plugin
  * declares one today, so this is authoring surface ahead of use, not yet exercised by a bundled
@@ -4437,6 +4437,14 @@ export declare interface ToolDefinition<TParams extends ToolParametersWire = Too
      * 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}
@@ -4528,9 +4536,9 @@ export 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`.
  */
@@ -4571,7 +4579,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>" }`
@@ -4612,7 +4620,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,
@@ -4636,7 +4644,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
@@ -4881,13 +4889,19 @@ export 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;
@@ -5115,7 +5129,15 @@ export 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. */
@@ -5138,7 +5160,9 @@ export 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;
@@ -5412,7 +5436,7 @@ export 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.
      *