@yaklabs-ai/plugin-sdk 0.12.5 → 0.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,7 +21,7 @@ export declare interface AccountIdentity {
21
21
  readonly displayName?: string;
22
22
  /** Absolute URL of the account's avatar. */
23
23
  readonly avatarUrl?: string;
24
- /** Issuer-asserted beta-tester flag; only Kay's product-account service sets it. */
24
+ /** Issuer-asserted beta-tester flag; only Bonsai's product-account service sets it. */
25
25
  readonly betaTester?: boolean;
26
26
  readonly activeOrganizationId?: string;
27
27
  readonly organizationSelectionState?: "selected" | "unresolved";
@@ -29,7 +29,7 @@ export declare interface AccountIdentity {
29
29
  /**
30
30
  * Provider-native session id claim (WorkOS's `sid`), needed to call the provider's own
31
31
  * session-revocation endpoint at sign-out (`POST /user_management/sessions/revoke`, not yet
32
- * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Kay's WorkOS
32
+ * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Bonsai's WorkOS
33
33
  * product-account exchange/refresh sets it; every other provider leaves it absent.
34
34
  */
35
35
  readonly providerSessionId?: string;
@@ -206,7 +206,7 @@ declare interface ApiKeyAuthSchemeField {
206
206
  readonly label: string;
207
207
  }
208
208
 
209
- /** Provider-owned instructions for creating a credential outside Kay. */
209
+ /** Provider-owned instructions for creating a credential outside Bonsai. */
210
210
  declare interface ApiKeyAuthSchemeSetup {
211
211
  readonly instructions: string;
212
212
  /** Absolute HTTPS page where the user can create or manage the credential. */
@@ -704,7 +704,7 @@ declare interface DelegatedConnectResult {
704
704
 
705
705
  /**
706
706
  * The terminal failure of {@link PluginDelegatedScheme.refresh}: the provider no longer accepts the
707
- * stored grant (an OAuth `invalid_grant`, say), so only a reconnect helps. Kay marks the account
707
+ * stored grant (an OAuth `invalid_grant`, say), so only a reconnect helps. Bonsai marks the account
708
708
  * as needing a reconnect. Throw any other error for a failure that may pass on its own.
709
709
  */
710
710
  export declare class DelegatedRefreshRejectedError extends Error {
@@ -972,7 +972,7 @@ export declare interface InteractionCandidate {
972
972
  export declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
973
973
 
974
974
  export declare interface InteractionDriver {
975
- /** Unique in the session. `builtin:` is reserved for Kay's own drivers. */
975
+ /** Unique in the session. `builtin:` is reserved for Bonsai's own drivers. */
976
976
  readonly id: string;
977
977
  /** Human-readable name the agent sees beside the driver's targets. */
978
978
  readonly label: string;
@@ -995,7 +995,7 @@ export declare interface InteractionDriver {
995
995
  }
996
996
 
997
997
  /**
998
- * The Interaction driver contract: what a plugin implements to let Kay's agent drive something
998
+ * The Interaction driver contract: what a plugin implements to let Bonsai's agent drive something
999
999
  * on the user's machine (a browser, an app, a remote screen) through the harness-owned
1000
1000
  * Interaction engine.
1001
1001
  *
@@ -1008,7 +1008,7 @@ export declare interface InteractionDriver {
1008
1008
  * every tool work on every driver.
1009
1009
  *
1010
1010
  * Shape mirrors `SearchProvider` behind `web_search`: one tool set owned by the harness, many
1011
- * backends registered per session, the `builtin:` id namespace reserved for Kay's own.
1011
+ * backends registered per session, the `builtin:` id namespace reserved for Bonsai's own.
1012
1012
  */
1013
1013
  /** "Browser Interaction" drives web pages; "Computer Use Interaction" drives native apps. */
1014
1014
  export declare type InteractionDriverKind = "browser" | "computer-use";
@@ -1067,7 +1067,7 @@ export declare interface InteractionRegion {
1067
1067
  }
1068
1068
 
1069
1069
  /**
1070
- * One surface Kay ships, in the driver contract's own shape, so a plugin's driver is the surface
1070
+ * One surface Bonsai ships, in the driver contract's own shape, so a plugin's driver is the surface
1071
1071
  * plus an identity: `{ id, label, kind, ...api.interaction.desktop }`. Each call is checked
1072
1072
  * against the plugin's `interaction.surface {surface}` grant, and then against the session's
1073
1073
  * permissions exactly as the agent's `interaction_*` tools are: an act is judged as the plugin
@@ -1077,7 +1077,7 @@ export declare interface InteractionRegion {
1077
1077
  */
1078
1078
  export declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targets" | "observe" | "act" | "screenshot" | "open">;
1079
1079
 
1080
- /** The interaction surfaces Kay itself ships, which plugins drive through `api.interaction`. */
1080
+ /** The interaction surfaces Bonsai itself ships, which plugins drive through `api.interaction`. */
1081
1081
  export declare type InteractionSurfaceName = "browser-pane" | "desktop";
1082
1082
 
1083
1083
  /**
@@ -1224,7 +1224,7 @@ export declare interface JevScoreQuestion {
1224
1224
  * Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
1225
1225
  * ---
1226
1226
  *
1227
- * The vocabulary is Kay's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
1227
+ * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
1228
1228
  * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
1229
1229
  * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
1230
1230
  * criterion is text, and the state is a JSON object.
@@ -1273,15 +1273,7 @@ declare type JsonValue_3 = string | number | boolean | null | JsonValue_3[] | {
1273
1273
 
1274
1274
  declare const JsonValue_3: z.ZodType<JsonValue_3>;
1275
1275
 
1276
- /**
1277
- * The root selector the host binds to the session family's shared Whiteboard folder. The plugin
1278
- * that owns the Whiteboard gets the whole folder; every other plugin gets its own
1279
- * `plugins/<plugin-id>/` folder inside it. Calls on it are claims on
1280
- * `filesystem.read`/`filesystem.write` with this `root`, decided like any other.
1281
- */
1282
- export declare const KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT = "family-whiteboard";
1283
-
1284
- /** A plugin's Kay agent activation — receives only the brokered {@link KayAgentPluginApi}. */
1276
+ /** A plugin's Bonsai agent activation — receives only the brokered {@link KayAgentPluginApi}. */
1285
1277
  export declare type KayAgentActivate = (api: KayAgentPluginApi) => void;
1286
1278
 
1287
1279
  export declare type KayAgentAdvertisedApiKeyScheme = WithoutImplementation<PluginApiKeyScheme, "validate">;
@@ -1342,12 +1334,11 @@ export declare interface KayAgentAdvertisementAuthApi {
1342
1334
  * means the host bound no concrete authority. A plugin should surface a `grant` refusal to the user
1343
1335
  * and give up quietly on a `source-class` one. Within `grant`, branch on `code` before wording a
1344
1336
  * prompt: `not-granted` means the user has not consented (or has revoked it), while
1345
- * `grant-read-failed` means Kay could not read its own consent store and refused rather than
1337
+ * `grant-read-failed` means Bonsai could not read its own consent store and refused rather than
1346
1338
  * assume — the second is not something a grant prompt fixes.
1347
1339
  *
1348
- * Structurally parallel to {@link KayAgentFilesystemError}: broker handles are declaration-gated,
1349
- * so presence does not imply a current grant or concrete binding. This error says which ordered
1350
- * policy layer refused one specific call.
1340
+ * Broker handles are always present, so presence does not imply a current grant or concrete
1341
+ * binding. This error says which ordered policy layer refused one specific call.
1351
1342
  */
1352
1343
  export declare class KayAgentCapabilityError extends Error {
1353
1344
  readonly refusal: PluginCapabilityRefusalV1;
@@ -1371,59 +1362,14 @@ export declare interface KayAgentEvents {
1371
1362
  publish(localId: string, payload: unknown): void;
1372
1363
  }
1373
1364
 
1374
- /**
1375
- * Claim-checked filesystem operations. Paths are root-relative; canonical host paths never cross
1376
- * the seam. Writes are atomic: readers see the old file or the new one, never a partial write. A
1377
- * replace keeps the file's mode but makes a new file, so owner and extended attributes are not
1378
- * carried over. On a volume without hard links an exclusive create can briefly show an empty file.
1379
- */
1380
- export declare interface KayAgentFilesystem {
1381
- readText(location: KayAgentFilesystemLocation): Promise<string>;
1382
- writeText(location: KayAgentFilesystemLocation, content: string, options?: KayAgentFilesystemWriteOptions): Promise<void>;
1383
- /** The whole file, or the requested window of it. */
1384
- readBytes(location: KayAgentFilesystemLocation, range?: KayAgentFilesystemByteRange): Promise<Uint8Array>;
1385
- writeBytes(location: KayAgentFilesystemLocation, bytes: Uint8Array, options?: KayAgentFilesystemWriteOptions): Promise<void>;
1386
- mkdir(location: KayAgentFilesystemLocation): Promise<void>;
1387
- readDir(location: KayAgentFilesystemLocation): Promise<readonly KayAgentFilesystemEntry[]>;
1388
- stat(location: KayAgentFilesystemLocation): Promise<KayAgentFilesystemStat>;
1389
- rename(from: KayAgentFilesystemLocation, to: KayAgentFilesystemLocation): Promise<void>;
1390
- /** Returns the canonical path relative to the selected grant root. */
1391
- realpath(location: KayAgentFilesystemLocation): Promise<string>;
1392
- }
1393
-
1394
- /** A byte window of a file; `maxBytes` is capped by the host. */
1395
- export declare interface KayAgentFilesystemByteRange {
1396
- readonly offset: number;
1397
- readonly maxBytes: number;
1398
- }
1399
-
1400
- export declare interface KayAgentFilesystemEntry {
1401
- readonly name: string;
1402
- readonly kind: "file" | "directory" | "symlink" | "other";
1403
- }
1404
-
1405
- export declare class KayAgentFilesystemError extends Error {
1406
- readonly code: KayAgentFilesystemErrorCode;
1407
- constructor(code: KayAgentFilesystemErrorCode, message: string);
1408
- }
1409
-
1410
- export declare type KayAgentFilesystemErrorCode = "denied" | "invalid_path" | "not_found" | "already_exists" | "not_directory" | "is_directory" | "io_error";
1411
-
1412
- export declare interface KayAgentFilesystemLocation {
1413
- /** Exact `root` selector the host bound for this target, plus a path relative to it. */
1414
- readonly root: string;
1415
- readonly path: string;
1416
- }
1417
-
1418
- export declare interface KayAgentFilesystemStat {
1419
- readonly kind: "file" | "directory" | "other";
1420
- readonly size: number;
1421
- readonly modifiedAtMs: number;
1422
- }
1423
-
1424
- export declare interface KayAgentFilesystemWriteOptions {
1425
- /** Fail with `already_exists` instead of replacing a file already at the location. */
1426
- readonly exclusive?: boolean;
1365
+ /** This plugin's folder in the session family's shared Whiteboard. */
1366
+ export declare interface KayAgentFamilyFolder {
1367
+ /**
1368
+ * The folder's absolute path, created on first use. The plugin that owns the Whiteboard gets
1369
+ * the whole family folder; every other plugin gets its own `plugins/<plugin-id>/` inside it.
1370
+ * Undefined outside a session.
1371
+ */
1372
+ path(): Promise<string | undefined>;
1427
1373
  }
1428
1374
 
1429
1375
  /**
@@ -1443,7 +1389,7 @@ export declare interface KayAgentInteractionSurfaces {
1443
1389
  readonly browserPane: InteractionSurface;
1444
1390
  /**
1445
1391
  * The user's desktop through the platform's accessibility APIs: native apps as targets
1446
- * (`app://<bundle id>`), their windows' controls as elements. On macOS Kay drives it with its
1392
+ * (`app://<bundle id>`), their windows' controls as elements. On macOS Bonsai drives it with its
1447
1393
  * bundled accessibility worker under the app's Accessibility permission; on a platform with no
1448
1394
  * backend it reports itself unavailable.
1449
1395
  */
@@ -1573,11 +1519,8 @@ export declare interface KayAgentPluginApi {
1573
1519
  /** Register a whole URI module (a scheme handler that owns its address space, e.g. `drive://`). */
1574
1520
  registerModule(module: UriExtensionModule): void;
1575
1521
  };
1576
- /**
1577
- * Always present; each call is checked against `filesystem.read {root}` / `filesystem.write
1578
- * {root}` for the root it touches, and against the host's binding for that root.
1579
- */
1580
- readonly filesystem: KayAgentFilesystem;
1522
+ /** This plugin's folder in the session family's shared Whiteboard, created on first use. Undefined outside a session. */
1523
+ readonly familyFolder: KayAgentFamilyFolder;
1581
1524
  /** Absent unless the `knowledgeSearch` grant is requested and effectively granted. */
1582
1525
  readonly knowledgeSearch?: KayAgentKnowledgeSearch;
1583
1526
  /** Absent unless the `knownResources` grant is requested and effectively granted. */
@@ -1603,7 +1546,7 @@ export declare interface KayAgentPluginApi {
1603
1546
  */
1604
1547
  readonly process: KayAgentProcess;
1605
1548
  /**
1606
- * Always present; the interaction surfaces Kay ships (its browser pane, and the desktop through
1549
+ * Always present; the interaction surfaces Bonsai ships (its browser pane, and the desktop through
1607
1550
  * the platform accessibility APIs), each call checked against `interaction.surface {surface}`
1608
1551
  * and the session's permissions (see {@link InteractionSurface}).
1609
1552
  * Wrap one in an {@link InteractionDriver} and register it with
@@ -1630,9 +1573,8 @@ export declare interface KayAgentPluginApi {
1630
1573
  readonly time: KayAppTime;
1631
1574
  /**
1632
1575
  * File I/O in user folders, run by the host on its own worker threads under a deadline and
1633
- * answered as a typed result. Always present and ungated: unlike {@link filesystem} it takes
1634
- * absolute paths and checks no grant, because it adds no authority a plugin's `node:fs` does not
1635
- * already have. What it adds is that a slow or unresponsive folder never blocks the daemon. See
1576
+ * answered as a typed result. Always present and ungated: it takes absolute paths and checks no
1577
+ * 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
1636
1578
  * {@link KayAppUserFiles}.
1637
1579
  */
1638
1580
  readonly userFiles: KayAppUserFiles;
@@ -2118,16 +2060,8 @@ declare const KayPluginManifestV1: z.ZodObject<{
2118
2060
  localId: z.ZodString;
2119
2061
  schemes: z.ZodArray<z.ZodString>;
2120
2062
  displayName: z.ZodOptional<z.ZodString>;
2121
- filesystemBacking: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
2063
+ filesystemBacking: z.ZodOptional<z.ZodObject<{
2122
2064
  root: z.ZodLiteral<"dataDir">;
2123
- }, z.core.$strict>, z.ZodObject<{
2124
- root: z.ZodLiteral<"filesystem">;
2125
- selector: z.ZodString;
2126
- }, z.core.$strict>], "root">>;
2127
- verbs: z.ZodOptional<z.ZodObject<{
2128
- writable: z.ZodOptional<z.ZodBoolean>;
2129
- editable: z.ZodOptional<z.ZodBoolean>;
2130
- deletable: z.ZodOptional<z.ZodBoolean>;
2131
2065
  }, z.core.$strict>>;
2132
2066
  authService: z.ZodOptional<z.ZodString>;
2133
2067
  knownResources: z.ZodOptional<z.ZodLiteral<true>>;
@@ -3034,7 +2968,7 @@ export declare function num(record: Record<string, unknown> | undefined, key: st
3034
2968
  export declare function numLike(record: Record<string, unknown> | undefined, key: string): number | undefined;
3035
2969
 
3036
2970
  /**
3037
- * Who may supply the OAuth client for a scheme: Kay's embedded client, or one the user pastes in
2971
+ * Who may supply the OAuth client for a scheme: Bonsai's embedded client, or one the user pastes in
3038
2972
  * (BYOOC). An UNORDERED SET — list order carries no meaning (nothing reads it as a preference).
3039
2973
  */
3040
2974
  declare type OAuthClientSupplier = "kay" | "user";
@@ -3056,7 +2990,7 @@ declare interface OAuthRedirectResult {
3056
2990
 
3057
2991
  /**
3058
2992
  * The two client-supply axes, structured so the illegal cell is unrepresentable: a `confidential`
3059
- * exchange's secret may only ever be Kay's (held by the host's broker, never pasted by a
2993
+ * exchange's secret may only ever be Bonsai's (held by the host's broker, never pasted by a
3060
2994
  * customer), so `confidential` types `clientSuppliers` as `readonly ["kay"]` — `confidential ×
3061
2995
  * user` is a compile-time impossibility in v1, not a runtime refusal. `pkce`'s `clientSuppliers`
3062
2996
  * is a non-empty set; {@link createOAuthPkceAuthScheme} dedupes it and refuses empty.
@@ -3469,18 +3403,6 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
3469
3403
  origin: z.ZodString;
3470
3404
  pathPrefix: z.ZodString;
3471
3405
  }, z.core.$strict>;
3472
- }, z.core.$strict>, z.ZodObject<{
3473
- target: z.ZodLiteral<"kay.agent">;
3474
- slug: z.ZodLiteral<"filesystem.read">;
3475
- envelope: z.ZodObject<{
3476
- root: z.ZodString;
3477
- }, z.core.$strict>;
3478
- }, z.core.$strict>, z.ZodObject<{
3479
- target: z.ZodLiteral<"kay.agent">;
3480
- slug: z.ZodLiteral<"filesystem.write">;
3481
- envelope: z.ZodObject<{
3482
- root: z.ZodString;
3483
- }, z.core.$strict>;
3484
3406
  }, z.core.$strict>, z.ZodObject<{
3485
3407
  target: z.ZodLiteral<"kay.agent">;
3486
3408
  slug: z.ZodLiteral<"process.spawn">;
@@ -3704,7 +3626,7 @@ export declare interface PluginDelegatedScheme {
3704
3626
  readonly connect: (ctx: PluginDelegatedConnectContext) => Promise<PluginDelegatedConnectResult>;
3705
3627
  /**
3706
3628
  * Mint fresh material from the current (expiring) material, including the `data` the last
3707
- * connect or refresh returned. Kay calls this only inside its credential authority, which holds
3629
+ * connect or refresh returned. Bonsai calls this only inside its credential authority, which holds
3708
3630
  * the refresh lease and saves the result; this hook performs the exchange and nothing else.
3709
3631
  * Returned `data` replaces the stored `data`; omitted `data` keeps it. Returned `expiresAt`
3710
3632
  * replaces the stored expiry; omitted `expiresAt` means the new material does not expire.
@@ -3784,7 +3706,7 @@ export declare type PluginOAuthPkceScheme = PluginOAuthSchemeClientAxes & {
3784
3706
  readonly summary?: string;
3785
3707
  readonly authorizationUrl: string;
3786
3708
  readonly tokenUrl: string;
3787
- /** The Kay-supplied embedded client id; omit for a `confidential` scheme or a `pkce` scheme
3709
+ /** The Bonsai-supplied embedded client id; omit for a `confidential` scheme or a `pkce` scheme
3788
3710
  * the host ships no client for. */
3789
3711
  readonly clientId?: string;
3790
3712
  /**
@@ -3833,7 +3755,7 @@ export declare interface PluginServiceDescriptor {
3833
3755
  * (one record per plugin, not per skill) because a skill's asset tree is everything under
3834
3756
  * `dirname(contribution.path)` by convention — a multi-file `SKILL.md` + `references/` tree
3835
3757
  * belongs to the plugin as a whole, the same way {@link PluginSkillDefinition.content} is the
3836
- * plugin's compiled-in codegen pair of one `SKILL.md`. The Kay runtime materializes this record to real
3758
+ * plugin's compiled-in codegen pair of one `SKILL.md`. The Bonsai runtime materializes this record to real
3837
3759
  * files on disk at daemon composition (`<managed>/plugin-assets/<pluginId>/<packageRelativePath>`)
3838
3760
  * so relative references inside a skill resolve the same way a filesystem skill's do — no plugin
3839
3761
  * declares one today, so this is authoring surface ahead of use, not yet exercised by a bundled
@@ -4515,6 +4437,14 @@ export declare interface ToolDefinition<TParams extends ToolParametersWire = Too
4515
4437
  * explicit Stop.
4516
4438
  */
4517
4439
  durationClass?: "fast" | "long";
4440
+ /**
4441
+ * Set only for a tool whose rerun with the same arguments is harmless, such
4442
+ * as one keyed on its own call: after a crash cuts a call off, a pi-durable
4443
+ * session may rerun it with its recorded arguments (without `before_tool`)
4444
+ * instead of ending it as an interrupted error. Absent: never rerun. Ignored
4445
+ * on pi 0.99.1.
4446
+ */
4447
+ replaySafe?: true;
4518
4448
  /**
4519
4449
  * Optional capability⇄scheme binding. When present this tool is auth-gated: discoverable when
4520
4450
  * unauthed, callable once the binding is satisfied. The SDK's {@link withResolvedAuth}
@@ -4606,9 +4536,9 @@ export declare type ToolParametersWire = unknown;
4606
4536
  *
4607
4537
  * The host is trusted to supply honest values; a declared `kind` of `read` moves a call below
4608
4538
  * the protected-path hard-deny (which only fires for non-read kinds), so a tool that could
4609
- * touch protected config must NOT declare `read`. Kay's embedded-experience tools never touch
4539
+ * touch protected config must NOT declare `read`. Bonsai's embedded-experience tools never touch
4610
4540
  * `configDir`, so this is safe for them. `read` is also what every capability surface reports as
4611
- * "read-only" (Kay's Permissions page groups and defaults on it), so it is a claim about what the
4541
+ * "read-only" (Bonsai's Permissions page groups and defaults on it), so it is a claim about what the
4612
4542
  * tool DOES — never a way to buy silence. A tool that should raise no ask on its own account
4613
4543
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
4614
4544
  */
@@ -4649,7 +4579,7 @@ declare interface ToolPermissionHint {
4649
4579
  * because the same tool can read on one input and execute on another, which a static `kind`
4650
4580
  * cannot express.
4651
4581
  *
4652
- * Exemplar — Kay's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
4582
+ * Exemplar — Bonsai's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
4653
4583
  * `{ kind: "read" }` (metadata lookups), while `call` derives
4654
4584
  * `{ kind: "execute", ruleKey: "mcp:<server>::<tool>", scheme: "<server>" }`, so a
4655
4585
  * `{ scheme: "<server>" }` rule gates a whole server and a `{ ruleKey: "mcp:<server>::<tool>" }`
@@ -4690,7 +4620,7 @@ declare interface ToolPermissionHint {
4690
4620
  * really had — not that the result is always stricter than the target's. How much gate is left
4691
4621
  * on such a call is exactly how much the CARRIER carries: an `execute` carrier is stricter than
4692
4622
  * a `read` target and equal to a `mutate`/`destructive` one outside allow mode, while a
4693
- * {@link quiet} carrier (Kay's own `call_tool`) contributes no mode default at all, so the
4623
+ * {@link quiet} carrier (Bonsai's own `call_tool`) contributes no mode default at all, so the
4694
4624
  * fallback leaves nothing but the carrier's rules and the protected-path deny — and the carrier
4695
4625
  * names no path, so that deny has nothing to fire on. This is why a carrier must refuse a target
4696
4626
  * that is itself a carrier: no chain long or circular enough to reach the fallback can be built,
@@ -4714,7 +4644,7 @@ declare interface ToolPermissionHint {
4714
4644
  * whose only effect is invoking the target the gate is already classifying beside it: the
4715
4645
  * target's kind, rules, resources and the protected-path deny all still decide, so a proxied
4716
4646
  * call is gated exactly like the direct one — no more, and no ask the direct call would never
4717
- * have raised. Kay's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
4647
+ * have raised. Bonsai's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
4718
4648
  * 2026-08-18): honest about everything it can reach, silent on its own account.
4719
4649
  *
4720
4650
  * Quiet is not ungated, but it IS nearly all the gate a lone carrier has. On a call that
@@ -4959,13 +4889,19 @@ export declare interface UriExtensionModule extends Omit<UriModule, "verbs"> {
4959
4889
  readonly permissionDefaults?: UriPermissionDefaults;
4960
4890
  /** Requires a resolved URI connection before any verb handler runs. */
4961
4891
  readonly requiresConnection?: boolean;
4962
- /** Pure route-aware permission facts; may only strengthen the verb default. */
4892
+ /** Pure route-aware permission facts; see {@link UriExtensionOperationPermissionPolicy}. */
4963
4893
  readonly permission?: UriExtensionOperationPermissionPolicy;
4964
4894
  /** False rejects generic write-tool `source` copies before source fetch. */
4965
4895
  readonly acceptsSourceCopy?: boolean;
4966
4896
  }
4967
4897
 
4968
4898
  declare interface UriExtensionOperationPermissionPolicy {
4899
+ /**
4900
+ * Classify one canonical route, purely. `write`/`edit`/`delete` may only be made stricter
4901
+ * than the verb default; `help`/`read`/`list`/`search` must stay `"read"` (a `ruleKey` is
4902
+ * allowed), because the kernel reruns a crash-interrupted read without asking again. Any
4903
+ * other answer, or a throw, fails the call closed.
4904
+ */
4969
4905
  classifyOperation(request: {
4970
4906
  readonly operation: UriOperation;
4971
4907
  readonly uri: string;
@@ -5193,7 +5129,15 @@ export declare interface UriModule {
5193
5129
  normalize?(input: string, ctx: UriResolveContext): UriNormalizeResult | undefined;
5194
5130
  describe?(input: string, ctx: UriDescribeContext): UriResourceDescription | undefined;
5195
5131
  locate?(input: string, ctx: UriLocateContext): Promise<UriLocateResult>;
5132
+ /**
5133
+ * `read`, `help`, `list` and `search` observe; they never change the resource or anything
5134
+ * outside the host. Repeating one with the same input must be harmless: the kernel reruns a
5135
+ * call of these verbs that a crash cut off, with the same input, without asking the user
5136
+ * again. Idempotent bookkeeping (a cache fill, an index of what was read, a usage count) is
5137
+ * fine; a send, a mark-as-read or a create is not, and belongs on a mutating verb.
5138
+ */
5196
5139
  read(input: string, ctx: UriResolveContext): Promise<RawResource>;
5140
+ /** Observes only; see {@link read}. */
5197
5141
  help?(input: string, ctx: UriResolveContext): Promise<UriHelp>;
5198
5142
  write?(input: string, content: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult | void>;
5199
5143
  /** Opt-in structured write with one or more host-resolved resources delivered beside the content. */
@@ -5216,7 +5160,9 @@ export declare interface UriModule {
5216
5160
  */
5217
5161
  writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
5218
5162
  edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
5163
+ /** Observes only; see {@link read}. */
5219
5164
  list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
5165
+ /** Observes only; see {@link read}. */
5220
5166
  search?(input: string, params: UriSearchParams, ctx: UriResolveContext): Promise<UriSearchResult>;
5221
5167
  delete?(input: string, ctx: UriResolveContext): Promise<UriMutationResult>;
5222
5168
  toMarkdown?(input: UriMarkdownRenderInput, ctx: UriResolveContext): string | undefined;
@@ -5490,7 +5436,7 @@ export declare interface UriResolveContext {
5490
5436
  * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller — so a module
5491
5437
  * writing to a store it owns can record the actor without the agent being able to choose one.
5492
5438
  *
5493
- * Free text minted by the host's own runtime (Kay's form is `user`, `subagent`,
5439
+ * Free text minted by the host's own runtime (Bonsai's form is `user`, `subagent`,
5494
5440
  * `system/<surface>`, `followup/<surface>`) rather than a closed union: the surface half is the
5495
5441
  * host's vocabulary, and a second enumeration of it here would drift from the first.
5496
5442
  *
package/dist/kay-agent.js CHANGED
@@ -1374,15 +1374,6 @@ var DelegatedRefreshRejectedError = class extends Error {
1374
1374
  function isDelegatedRefreshRejected(error) {
1375
1375
  return typeof error === "object" && error !== null && error[DELEGATED_REFRESH_REJECTED] === true;
1376
1376
  }
1377
- var KayAgentFilesystemError = class extends Error {
1378
- code;
1379
- constructor(code, message) {
1380
- super(message);
1381
- this.name = "KayAgentFilesystemError";
1382
- this.code = code;
1383
- }
1384
- };
1385
- var KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT = "family-whiteboard";
1386
1377
  var KayAgentCapabilityError = class extends Error {
1387
1378
  refusal;
1388
1379
  constructor(refusal, message) {
@@ -1405,9 +1396,7 @@ export {
1405
1396
  DelegatedRefreshRejectedError,
1406
1397
  INTERACTION_CREDENTIAL_GUARD,
1407
1398
  JevCallError,
1408
- KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT,
1409
1399
  KayAgentCapabilityError,
1410
- KayAgentFilesystemError,
1411
1400
  KayAgentWebSessionError,
1412
1401
  OBSERVATION_MIME,
1413
1402
  PluginApiError,