@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.
- package/README.md +37 -33
- package/THIRD-PARTY-INVENTORY.json +1 -1
- package/dist/disclosure.d.ts +59 -77
- package/dist/disclosure.js +4 -14
- package/dist/fs.d.ts +156 -0
- package/dist/fs.js +895 -0
- package/dist/jev.d.ts +1 -1
- package/dist/kay-agent-testing.d.ts +58 -76
- package/dist/kay-agent-testing.js +4 -12
- package/dist/kay-agent.d.ts +65 -119
- package/dist/kay-agent.js +0 -11
- package/dist/kay-app.d.ts +156 -61
- package/dist/kay-app.js +22 -1
- package/dist/signals.d.ts +175 -1
- package/dist/signals.js +141 -2
- package/package.json +5 -1
- package/skills/directory-plugin-authoring/SKILL.md +18 -17
package/dist/kay-agent.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
*
|
|
1349
|
-
*
|
|
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
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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:
|
|
1634
|
-
*
|
|
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.
|
|
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:
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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`.
|
|
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" (
|
|
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 —
|
|
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 (
|
|
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.
|
|
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;
|
|
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 (
|
|
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,
|