@yaklabs-ai/plugin-sdk 0.13.1 → 0.13.3

package/README.md

@@ -13,16 +13,16 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.1"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.3"
   }
 }
 ```
 
 **The alias is not cosmetic.** The package is published as
 `@yaklabs-ai/plugin-sdk`, but Bonsai's daemon resolves the specifier
-`@kay/plugin-sdk` when it loads your entrypoint, so that is the name your source
+`@bonsai/plugin-sdk` when it loads your entrypoint, so that is the name your source
 must import. The alias installs the published package at
-`node_modules/@kay/plugin-sdk`, satisfying both.
+`node_modules/@bonsai/plugin-sdk`, satisfying both.
 
 <details>
 <summary>Installing a release older than 0.8.0</summary>
@@ -48,7 +48,7 @@ this.
 Working with an agent? This package ships the skill that teaches one the whole
 authoring flow — scaffold, the SDK resolution contract, the reload loop, and
 the diagnostics to read when a plugin does not load. Point your agent at
-`node_modules/@kay/plugin-sdk/skills/directory-plugin-authoring/SKILL.md`
+`node_modules/@bonsai/plugin-sdk/skills/directory-plugin-authoring/SKILL.md`
 before it writes any plugin code.
 
 ```ts
@@ -58,7 +58,7 @@ import {
   toolParameters,
   z,
   type KayAgentActivate,
-} from "@kay/plugin-sdk/kay-agent";
+} from "@bonsai/plugin-sdk/kay-agent";
 
 const greet = defineTool({
   name: "widgets_greet",
@@ -79,12 +79,12 @@ export default activate;
 
 ## Entrypoints
 
-| Import                              | What it gives you                                                            |
-| ----------------------------------- | ---------------------------------------------------------------------------- |
-| `@kay/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface   |
-| `@kay/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules             |
-| `@kay/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs     |
-| `@kay/plugin-sdk/disclosure`        | The conformance audit Bonsai gates your plugin with — run it before you ship |
+| Import                                 | What it gives you                                                            |
+| -------------------------------------- | ---------------------------------------------------------------------------- |
+| `@bonsai/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface   |
+| `@bonsai/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules             |
+| `@bonsai/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs     |
+| `@bonsai/plugin-sdk/disclosure`        | The conformance audit Bonsai gates your plugin with — run it before you ship |
 
 `kay-agent/host` is intentionally not published; it is Bonsai's own loading
 machinery, not an authoring API.
@@ -100,7 +100,7 @@ run below is the run Bonsai does.
 import {
   auditPluginDisclosure,
   collectUriModulesFromKayAgentActivate,
-} from "@kay/plugin-sdk/disclosure";
+} from "@bonsai/plugin-sdk/disclosure";
 
 import activate from "../src/kay-agent.ts";
 import manifest from "../kay-plugin.json" with { type: "json" };
@@ -152,7 +152,7 @@ Installing this SDK gives you **types, editor completion, and a runtime you can
 execute in your own tests**. It is not what runs inside Bonsai.
 
 When the daemon loads your plugin, chord bundles its declared target and keeps
-`@kay/plugin-sdk/*` as a host external. Those imports resolve to the SDK
+`@bonsai/plugin-sdk/*` as a host external. Those imports resolve to the SDK
 **bundled with the Bonsai app**. The host's copy always wins. That is deliberate —
 one implementation, the one the daemon is built against — but it has a
 consequence worth stating plainly:

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -271,6 +271,10 @@ declare interface BackgroundTaskCompletion {
     readonly resultDelivery?: BackgroundTaskResultDelivery;
     readonly output?: string;
     readonly error?: string;
+    /** The thrown Error's stack, when a failed task threw one. */
+    readonly errorStack?: string;
+    /** Why a failed AGENT task's run failed, classified from what it threw; absent for other kinds. */
+    readonly failureReason?: RunFailureReason;
 }
 
 declare type BackgroundTaskInspector = () => Promise<string> | string;
@@ -346,14 +350,14 @@ export declare interface CapturedKayAgentAuthDeclarations {
      * Api-key schemes declared this run — the `displayName`/`inputLabel`/`setup`/`validate`
      * runtime declaration a manifest's identity-only scheme row cannot carry. Daemon acquisition
      * composition maps these onto the connect dispatch's api-key roster the same way
-     * `oauthPkceSchemes` maps onto the PKCE arm — see `@kay/agent-runtime`'s `kay/composition/`.
+     * `oauthPkceSchemes` maps onto the PKCE arm — see `@bonsai/agent-runtime`'s `kay/composition/`.
      * Empty for a plugin that declares none.
      */
     readonly apiKeySchemes: readonly CapturedApiKeyDeclaration[];
     /**
      * Delegated schemes declared this run. Daemon acquisition composition maps these onto a
      * delegated connect-roster entry the same way `oauthPkceSchemes` maps onto the PKCE arm — see
-     * `@kay/agent-runtime`'s `kay/composition/`. Empty for a plugin that declares none.
+     * `@bonsai/agent-runtime`'s `kay/composition/`. Empty for a plugin that declares none.
      */
     readonly delegatedSchemes: readonly CapturedDelegatedDeclaration[];
 }
@@ -664,7 +668,7 @@ declare interface ImageContent {
 
 /**
  * The value a Browser Interaction driver sets as `credentialGuard` to declare that every act runs
- * the page-side credential guard from `@kay/interaction-page-scripts` (never type into or click a
+ * the page-side credential guard from `@bonsai/interaction-page-scripts` (never type into or click a
  * sign-in form). The engine refuses to register a browser driver without it.
  */
 declare const INTERACTION_CREDENTIAL_GUARD = "kay.credential-guard/v1";
@@ -969,7 +973,7 @@ declare interface JevScoreQuestion {
  *   - The wire. The host serves `classify` over whichever route the user's Jev provider order
  *     picks; a plugin never sees a vendor client, a vendor type, or a route.
  *   - Credential resolution, the `jev.use` decision, the Jev-branch budget, or usage accounting.
- *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
+ *     Those are host-side (`@bonsai/agent-runtime`'s `kay/jev/`).
  * ---
  *
  * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
@@ -1515,7 +1519,7 @@ declare interface KayAppTimeSnapshot {
      * The time zone the user is in, as an IANA id in the spelling ICU resolves (`America/New_York`).
      * One zone can have two ids, and ICU picks one: `Asia/Kolkata` comes back as `Asia/Calcutta`. So
      * never compare zone ids with `===`. A first-party plugin compares with `sameZone` from
-     * `@kay/time`. A plugin that imports only this SDK and node builtins resolves each id with
+     * `@bonsai/time`. A plugin that imports only this SDK and node builtins resolves each id with
      * `new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone` and compares the
      * results. Pass `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a
      * time for the user.
@@ -2406,6 +2410,28 @@ declare interface ResolveTokenSuccess {
     readonly auth: ResolvedAuth;
 }
 
+/**
+ * Pure, provider-neutral classification of a failed model run.
+ *
+ * This is a leaf module with no runtime imports, because two callers that
+ * cannot share a bundle must reach the same verdict: the kernel failure path
+ * (`run-error.ts`, which reaches Pi and Node) and the browser-safe interactive
+ * reducer that projects an errored message for a surface to render. Routing the
+ * reducer through `run-error.ts` would drag `pi-agent-core` into the renderer
+ * bundle; duplicating the rules there would let the reason a run was *retried
+ * for* drift from the reason a user is *told about*.
+ *
+ * The leaf rule is why {@link readableFailureText} carries its own small HTML
+ * extractor instead of reaching for `core/web/markdown.ts`. That module imports
+ * `@herd/plugin-primitives`, and the browser-safety guard externalizes bare
+ * specifiers, so it could not prove the import stays renderer-safe. It is also
+ * the wrong tool: it emits markdown into what must remain a plain diagnostic,
+ * and it discards `<head>`, where a gateway page puts the one line naming the
+ * failure.
+ */
+/** Provider-neutral factual category for a failed model run. */
+declare type RunFailureReason = "auth" | "content_blocked" | "context_overflow" | "invalid_request" | "model_unavailable" | "network" | "overloaded" | "quota_exhausted" | "rate_limit" | "safeguard_block" | "seat_unpaid" | "server_error" | "stream_interrupted" | "timeout" | "unknown";
+
 /** One all-of arm in an ordered scope requirement. */
 declare interface ScopeAlternative {
     readonly allOf: readonly ScopeNeed[];
@@ -3230,6 +3256,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {
@@ -3909,7 +3941,7 @@ declare interface UriValidationMessage {
  * applies label changes"), never wire mechanics or URI shapes. Verbs the
  * module does not support are omitted; at runtime a supported verb with no
  * entry simply renders undocumented (fail-open metadata) — but for a plugin's
- * `kay.agent` URI modules, `auditPluginDisclosure` (`@kay/plugin-sdk/
+ * `kay.agent` URI modules, `auditPluginDisclosure` (`@bonsai/plugin-sdk/
  * disclosure`) enforces coverage of every supported verb at authoring/load
  * time.
  *

package/dist/fs.js

@@ -156,7 +156,7 @@ function abortError(signal) {
   return assignFields(error, { code: "ABORT_ERR" });
 }
 function unsupported(syscall, what) {
-  return kayError(KAY_FS_UNSUPPORTED, `${what} is not supported by @kay/plugin-sdk/fs`, syscall, void 0);
+  return kayError(KAY_FS_UNSUPPORTED, `${what} is not supported by @bonsai/plugin-sdk/fs`, syscall, void 0);
 }
 function finishedOf(error) {
   return error?.[FINISHED];

package/dist/jev.d.ts

@@ -135,7 +135,7 @@ export declare interface JevScoreQuestion {
  *   - The wire. The host serves `classify` over whichever route the user's Jev provider order
  *     picks; a plugin never sees a vendor client, a vendor type, or a route.
  *   - Credential resolution, the `jev.use` decision, the Jev-branch budget, or usage accounting.
- *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
+ *     Those are host-side (`@bonsai/agent-runtime`'s `kay/jev/`).
  * ---
  *
  * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`

package/dist/kay-agent-testing.d.ts

@@ -225,6 +225,10 @@ declare interface BackgroundTaskCompletion {
     readonly resultDelivery?: BackgroundTaskResultDelivery;
     readonly output?: string;
     readonly error?: string;
+    /** The thrown Error's stack, when a failed task threw one. */
+    readonly errorStack?: string;
+    /** Why a failed AGENT task's run failed, classified from what it threw; absent for other kinds. */
+    readonly failureReason?: RunFailureReason;
 }
 
 declare type BackgroundTaskInspector = () => Promise<string> | string;
@@ -550,7 +554,7 @@ declare interface ImageContent {
 
 /**
  * The value a Browser Interaction driver sets as `credentialGuard` to declare that every act runs
- * the page-side credential guard from `@kay/interaction-page-scripts` (never type into or click a
+ * the page-side credential guard from `@bonsai/interaction-page-scripts` (never type into or click a
  * sign-in form). The engine refuses to register a browser driver without it.
  */
 declare const INTERACTION_CREDENTIAL_GUARD = "kay.credential-guard/v1";
@@ -873,7 +877,7 @@ declare interface JevScoreQuestion {
  *   - The wire. The host serves `classify` over whichever route the user's Jev provider order
  *     picks; a plugin never sees a vendor client, a vendor type, or a route.
  *   - Credential resolution, the `jev.use` decision, the Jev-branch budget, or usage accounting.
- *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
+ *     Those are host-side (`@bonsai/agent-runtime`'s `kay/jev/`).
  * ---
  *
  * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
@@ -1416,7 +1420,7 @@ declare interface KayAppTimeSnapshot {
      * The time zone the user is in, as an IANA id in the spelling ICU resolves (`America/New_York`).
      * One zone can have two ids, and ICU picks one: `Asia/Kolkata` comes back as `Asia/Calcutta`. So
      * never compare zone ids with `===`. A first-party plugin compares with `sameZone` from
-     * `@kay/time`. A plugin that imports only this SDK and node builtins resolves each id with
+     * `@bonsai/time`. A plugin that imports only this SDK and node builtins resolves each id with
      * `new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone` and compares the
      * results. Pass `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a
      * time for the user.
@@ -2304,6 +2308,28 @@ declare interface ResolveTokenSuccess {
     readonly auth: ResolvedAuth;
 }
 
+/**
+ * Pure, provider-neutral classification of a failed model run.
+ *
+ * This is a leaf module with no runtime imports, because two callers that
+ * cannot share a bundle must reach the same verdict: the kernel failure path
+ * (`run-error.ts`, which reaches Pi and Node) and the browser-safe interactive
+ * reducer that projects an errored message for a surface to render. Routing the
+ * reducer through `run-error.ts` would drag `pi-agent-core` into the renderer
+ * bundle; duplicating the rules there would let the reason a run was *retried
+ * for* drift from the reason a user is *told about*.
+ *
+ * The leaf rule is why {@link readableFailureText} carries its own small HTML
+ * extractor instead of reaching for `core/web/markdown.ts`. That module imports
+ * `@herd/plugin-primitives`, and the browser-safety guard externalizes bare
+ * specifiers, so it could not prove the import stays renderer-safe. It is also
+ * the wrong tool: it emits markdown into what must remain a plain diagnostic,
+ * and it discards `<head>`, where a gateway page puts the one line naming the
+ * failure.
+ */
+/** Provider-neutral factual category for a failed model run. */
+declare type RunFailureReason = "auth" | "content_blocked" | "context_overflow" | "invalid_request" | "model_unavailable" | "network" | "overloaded" | "quota_exhausted" | "rate_limit" | "safeguard_block" | "seat_unpaid" | "server_error" | "stream_interrupted" | "timeout" | "unknown";
+
 /** One all-of arm in an ordered scope requirement. */
 declare interface ScopeAlternative {
     readonly allOf: readonly ScopeNeed[];
@@ -3128,6 +3154,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {
@@ -3807,7 +3839,7 @@ declare interface UriValidationMessage {
  * applies label changes"), never wire mechanics or URI shapes. Verbs the
  * module does not support are omitted; at runtime a supported verb with no
  * entry simply renders undocumented (fail-open metadata) — but for a plugin's
- * `kay.agent` URI modules, `auditPluginDisclosure` (`@kay/plugin-sdk/
+ * `kay.agent` URI modules, `auditPluginDisclosure` (`@bonsai/plugin-sdk/
  * disclosure`) enforces coverage of every supported verb at authoring/load
  * time.
  *