@yaklabs-ai/plugin-sdk 0.13.1 → 0.13.3

package/dist/kay-app.d.ts

@@ -224,6 +224,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;
@@ -431,6 +435,18 @@ export declare function createFallbackOnlyWithJev(): WithJev;
  */
 export declare function createUnavailableSkills(message: string): KayAppSkills;
 
+/**
+ * The `app.tools` a host that cannot describe tools binds: every call answers `not-available`, so
+ * a plugin's code path never depends on host composition.
+ */
+export declare function createUnavailableTools(): KayAppTools;
+
+/**
+ * A `KayAppUsage` that answers `unavailable` to every call: what a host with no telemetry lane
+ * binds, so `app.usage` stays present on every host.
+ */
+export declare function createUnavailableUsage(message: string): KayAppUsage;
+
 declare interface CustomEntry extends EntryBase {
     type: "custom";
     customType: string;
@@ -759,7 +775,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`
@@ -1149,6 +1165,24 @@ export declare interface KayAppAgentDefinition {
      * position: the two are separately compared, so moving a rule between them is a different claim.
      */
     readonly permissionsFallback?: readonly PluginAgentDefinitionPermissionRule[];
+    /**
+     * The URI schemes this definition's runs MAINTAIN, e.g. `["memory"]` for a job that curates,
+     * prunes or rewrites the memory notebook. Bare scheme names, lowercase, no `://`.
+     *
+     * What it changes, and only this: a READ under a declared scheme, made by a session of this
+     * definition or by any session in that session's family (its subagents, keyed by root), is not
+     * counted as use of the resource in Bonsai's per-resource read activity (the `uriReadActivity`
+     * metric, `analytics://memory`, and `app.usage`'s answers). A job that keeps a notebook tidy
+     * reads old and irrelevant notes as a matter of course, and counting those reads would make
+     * every note it touches look used. Reads by every other session, including other background
+     * jobs, still count: a job that reads a note to do its own work found the note useful.
+     *
+     * It confers no authority and removes none. The host re-reads it from the live definition at
+     * every activation, like {@link permissions}, and stamps it on the session's activation row.
+     * Adding or removing one scheme here is the whole switch for moving a job between the excluded
+     * and the counted side. Absent means the job maintains nothing. SDK 0.13.3.
+     */
+    readonly maintains?: readonly string[];
 }
 
 /** The inert session-config subset a plugin-authored agent definition may contribute. */
@@ -1921,8 +1955,8 @@ export declare interface KayAppConfig {
 /**
  * Where a folded config value's winner was defined: the config LEVEL that won and the absolute
  * path of the winning file. A JSON-safe twin of the runtime's `KayConfigValueOrigin`
- * (`@kay/product-catalog`) — this SDK cannot import that package, so the shape is re-declared
- * here and an assignability test in `@kay/agent-runtime` pins the two together. The level union
+ * (`@bonsai/product-catalog`) — this SDK cannot import that package, so the shape is re-declared
+ * here and an assignability test in `@bonsai/agent-runtime` pins the two together. The level union
  * is the closed, protocol-owned fold precedence stack (`baseline < learned < global < project`).
  * `"baseline"` names a host-composed, in-memory, build/channel-scoped default with no file
  * behind it (`KayConfigStoreOptions.baselineDefaults`) — a plugin can still be handed one as a
@@ -2671,8 +2705,8 @@ export declare interface KayAppPermissions {
 export declare interface KayAppPhaseShiftSessionEvent extends KayAppSessionEventBase {
     readonly type: "phase-shift";
     /**
-     * The accepted observation, in the SURFACE-FRIENDLY resolved shape (`@kay/plugin-protocol`'s
-     * `PhaseShiftTimelineRecord`, re-exported from `@kay/plugin-sdk/phase-shift`) rather than the
+     * The accepted observation, in the SURFACE-FRIENDLY resolved shape (`@bonsai/plugin-protocol`'s
+     * `PhaseShiftTimelineRecord`, re-exported from `@bonsai/plugin-sdk/phase-shift`) rather than the
      * raw validated one: source timestamps already resolved, total and pure, no entry read needed
      * to place it in time. Re-validate its onsets against the branch you actually read — a rewind
      * can race between publish and read — the same discipline `resolveClosedPhase` already applies.
@@ -2863,6 +2897,24 @@ export declare interface KayAppPluginApi {
      * present, like {@link signals}.
      */
     readonly skills: KayAppSkills;
+    /**
+     * What a live session's tools and addresses say to the agent, where each comes from, and whether
+     * each is one of Bonsai's own. Each call is checked against `tools.describe`; a refused grant or
+     * a session that is not live resolves to `{ status: "unavailable" }`, never a rejection, while
+     * the plugin is enabled. After it is disabled, a kept handle's methods throw synchronously.
+     * Always present, like {@link skills}.
+     */
+    readonly tools: KayAppTools;
+    /**
+     * Read and change activity for the resources under this plugin's OWN URI schemes, counted under
+     * Bonsai's read rule (reads by a job that declares it maintains the scheme never count). Each
+     * call checks, against the live registry, that the asked prefix is under a scheme this plugin's
+     * registered URI modules serve; any other prefix resolves to `{ status: "refused" }`. A host
+     * with no telemetry lane, or a scan that cannot complete, resolves to `{ status: "unavailable" }`.
+     * No call rejects while the plugin is enabled; after it is disabled, a kept handle's method
+     * throws synchronously. Always present, like {@link skills}.
+     */
+    readonly usage: KayAppUsage;
     /** The app-wide endpoint bus (register handlers a consuming surface invokes). */
     readonly endpoints: KayAppEndpoints;
     /** Publish one event declared by this plugin's `kay.app` manifest target. */
@@ -3076,6 +3128,17 @@ export declare interface KayAppResolvedCredential {
     readonly fields?: Readonly<Record<string, string>>;
 }
 
+/**
+ * What one run produced, as named counts: `{ suggestions: 2, pullRequests: 0 }`. Optional, and
+ * read by Bonsai's own analytics, not shown to a person.
+ *
+ * Keys are your own names, in camelCase (a letter first, then letters and digits, at most 40
+ * characters), at most 16 per run; values are whole numbers of zero or more. Report a zero rather
+ * than leaving a key out: "made nothing" is the answer a reader is usually asking about. A result
+ * that breaks these rules is dropped whole, with the run otherwise recorded as usual.
+ */
+export declare type KayAppRunProduced = Readonly<Record<string, number>>;
+
 export declare interface KayAppRunSummary {
     /** One plain-text line, at most 100 characters. */
     readonly headline: string;
@@ -3086,8 +3149,8 @@ export declare interface KayAppRunSummary {
 
 /**
  * The session provenance vocabulary, as the plugin protocol declares it. These used to be spelled
- * out here because the canonical schemas lived in `@kay/agent-runtime-protocol`, which this
- * package may not import; they now live in `@kay/plugin-protocol` (so artifact writers and the
+ * out here because the canonical schemas lived in `@bonsai/agent-runtime-protocol`, which this
+ * package may not import; they now live in `@bonsai/plugin-protocol` (so artifact writers and the
  * daemon share one shape), and a mirror here would be exactly the second declaration the
  * placement law forbids. Each name is kept as an alias so existing plugin code keeps compiling.
  */
@@ -3222,6 +3285,12 @@ export declare interface KayAppSessionEventsSubscribeOptions {
      * immediately.
      */
     readonly serialize?: boolean;
+    /**
+     * Your own name for this handler (the id you would grep a log for). The host names it, with
+     * your plugin id, on the record it writes when the handler throws, so a failure says whose it
+     * was. Optional; unnamed handlers are recorded without it.
+     */
+    readonly handlerId?: string;
     readonly handler: (event: KayAppSessionEvent, context: KayAppSessionEventContext) => void | Promise<void>;
 }
 
@@ -3720,7 +3789,7 @@ export declare type KayAppSignalsAnswerFilter = {
  */
 export declare interface KayAppSignalsDetectorInput {
     /**
-     * Stable identifier, e.g. `memory-curator-gate`: a lowercase slug (a-z and 0-9 in words joined
+     * Stable identifier, e.g. `memory-packet`: a lowercase slug (a-z and 0-9 in words joined
      * by single hyphens), at most 64 characters, plugin-scoped. It becomes a `signals://` path
      * segment.
      */
@@ -4155,7 +4224,7 @@ export 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.
@@ -4202,6 +4271,21 @@ export declare type KayAppToolDefinition<TParams extends ToolParametersWire = To
     execute(toolCallId: string, params: ToolExecutionAwareParams<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: KayAppToolContext): Promise<AgentToolResult<TDetails>>;
 };
 
+export declare interface KayAppToolDescription {
+    readonly ref: KayAppToolRef;
+    /** `false`: no such tool is registered, or no module owns that address, in this session. */
+    readonly found: boolean;
+    /**
+     * For a tool, its own registered description. For an address, its help rendered as `help <uri>`
+     * renders it for the agent; for `mcp://<server>`, that is the server's tool list in the server's
+     * own words.
+     */
+    readonly description?: string;
+    readonly origin?: KayAppToolOrigin;
+    /** Whether this is one of Bonsai's own tools or addresses. `false` when not found. */
+    readonly ownedByBonsai: boolean;
+}
+
 /**
  * The fine-grained, app-wide per-tool event stream (every session's tool executions). Carries the
  * redaction caveat: raw tool args/results are OFF in packaged builds, so a handler must treat
@@ -4214,6 +4298,20 @@ export declare interface KayAppToolEvents {
     subscribe(handler: (event: unknown) => void): () => void;
 }
 
+/** Where a described tool or address comes from. */
+export declare type KayAppToolOrigin = 
+/** The agent kernel's own (`bash`, `read`, `help`, `skill://`). */
+    {
+    readonly kind: "core";
+}
+/** Bonsai's host, outside any plugin (`task_status`, `config://`). */
+| {
+    readonly kind: "host";
+} | {
+    readonly kind: "plugin";
+    readonly pluginId: string;
+};
+
 /**
  * `app.permissions` — the plugin-facing seam through which a `kay.app` target advertises the
  * permission rows for tools it gates DYNAMICALLY, so they show in Bonsai's permission ledger with
@@ -4264,6 +4362,52 @@ export declare interface KayAppToolPermissionSource {
     readonly list: () => readonly KayAppToolPermissionDeclaration[] | Promise<readonly KayAppToolPermissionDeclaration[]>;
 }
 
+/**
+ * The plugin-facing `kay.app` tools contract: for the tools and addresses a live session can use,
+ * the text the agent sees for each, where each comes from, and whether each is one of Bonsai's own.
+ *
+ * Every call is checked against the `tools.describe` claim at the call, so a grant or revocation
+ * takes effect on the next one. Like `app.skills`, the member is ALWAYS present and no call rejects
+ * while the plugin is enabled: a refused grant or a session that is not live resolves to
+ * `{ status: "unavailable" }`. After the plugin is disabled, a kept handle's methods throw
+ * synchronously.
+ *
+ * `ownedByBonsai` is a fact declared where each surface is defined (a bundled plugin's manifest, or
+ * the host's own registration), never a list kept by the host. What a plugin does with it is the
+ * plugin's call.
+ */
+/** A tool or an address to describe. */
+export declare type KayAppToolRef = 
+/** A registered tool by name, e.g. `bash`, `read`, `mcp`, `submit_final`. */
+    {
+    readonly kind: "tool";
+    readonly name: string;
+}
+/** A URI address whose `help` is wanted, e.g. `gmail://` or `mcp://linear`. */
+| {
+    readonly kind: "address";
+    readonly uri: string;
+};
+
+/** `app.tools`: what a live session's tools and addresses say, each call checked against `tools.describe`. */
+export declare interface KayAppTools {
+    describe(sessionId: string, refs: readonly KayAppToolRef[]): Promise<KayAppToolsDescribeResult>;
+}
+
+/**
+ * `not-granted`: the user has not granted `tools.describe`. `no-session`: the session is not live
+ * on this host (only live sessions are described). `not-available`: this host cannot describe
+ * tools.
+ */
+export declare type KayAppToolsDescribeResult = {
+    readonly status: "ok";
+    /** One per ref, in the order of the refs. */
+    readonly tools: readonly KayAppToolDescription[];
+} | {
+    readonly status: "unavailable";
+    readonly reason: "not-granted" | "no-session" | "not-available";
+};
+
 /** An eligible settled turn — the generic door's root event. */
 export declare interface KayAppTurnSettledSessionEvent extends KayAppSessionEventBase {
     readonly type: "turn-settled";
@@ -4276,7 +4420,7 @@ export declare interface KayAppTurnSettledSessionEvent extends KayAppSessionEven
      *
      * Optional on this SDK-facing type only for fixture leniency (a handcrafted test event may omit
      * it); the daemon's own emitter always populates it for a genuine settle — see
-     * `TurnSettledSessionEvent.runId` (`@kay/agent-runtime`'s internal twin of this event, which
+     * `TurnSettledSessionEvent.runId` (`@bonsai/agent-runtime`'s internal twin of this event, which
      * DOES require it) for the producer side of that guarantee.
      */
     readonly runId?: string;
@@ -4309,6 +4453,97 @@ export declare interface KayAppUiActionSessionEvent extends KayAppSessionEventBa
     readonly toolCallId: string;
 }
 
+/** How one resource under the asked prefix has been read and changed. */
+export declare interface KayAppUriActivity {
+    /** The canonical URI as the read or change recorded it. */
+    readonly uri: string;
+    /** One entry per window, in `KayAppUriActivityAnswer.windowDays` order. */
+    readonly windows: readonly KayAppUriActivityWindow[];
+    /** The newest counted read, ISO-8601 UTC; absent when none fell inside the scan. */
+    readonly lastReadAt?: string;
+    /** The newest change, ISO-8601 UTC; absent when none fell inside the scan. */
+    readonly lastChangedAt?: string;
+}
+
+export declare type KayAppUriActivityAnswer = {
+    readonly status: "ok";
+    /** The instant the windows are measured back from, ISO-8601 UTC. */
+    readonly asOf: string;
+    /** The windows every resource reports, in order. */
+    readonly windowDays: readonly number[];
+    /**
+     * Every resource under the prefix the scan saw read or changed. One read only by a
+     * maintaining job is listed with zero counts and no `lastReadAt`.
+     */
+    readonly resources: readonly KayAppUriActivity[];
+} | {
+    /** The prefix is not under a scheme this plugin's registered URI modules serve. */
+    readonly status: "refused";
+    readonly message: string;
+} | {
+    /** No telemetry lane on this host, or the scan could not complete. */
+    readonly status: "unavailable";
+    readonly message: string;
+};
+
+/**
+ * The plugin-facing `kay.app` usage contract: how the resources under a plugin's OWN URI schemes
+ * have been read and changed, as Bonsai's telemetry records it. SDK 0.13.3; a plugin that calls it
+ * declares `compatibility.sdk` `^0.13.3`.
+ *
+ * Scoped, not gated. A plugin may ask only about a prefix under a scheme one of its own registered
+ * URI modules serves; that check runs at every call against the live registry, and a prefix under
+ * any other scheme answers `{ status: "refused" }`. The member is ALWAYS present and no call
+ * rejects while the plugin is enabled: no telemetry lane on this host, a query that could not
+ * complete, or an answer too large to return all resolve to `{ status: "unavailable" }`. After the
+ * plugin is disabled, a kept handle's method throws synchronously.
+ *
+ * ## What counts as a read
+ *
+ * Every executed read counts, from any session (a person's conversation and its subagents,
+ * automations, loops, watches, Dream passes, any other job), EXCEPT a read made by a session whose
+ * agent definition declares that it maintains the read's scheme (`KayAppAgentDefinition.maintains`)
+ * or by any session in that session's family. Each counted read is split by who it serves:
+ * `personReads` when its session tree was started by a person, `jobReads` otherwise. Changes
+ * (writes and edits) count from every session, maintainers included.
+ *
+ * Reads recorded before the host build that stamps the declaration follow the earlier rule until
+ * they leave the 90-day window: such a read counts only when a person started the session that made it (a person's subagents
+ * did not count under that rule).
+ *
+ * ## Zero and unavailable are different answers
+ *
+ * An `ok` answer describes a complete scan: a resource absent from `resources` was neither read
+ * nor changed inside the scan, so it has zero counted reads. When the scan could not complete the answer is `unavailable`,
+ * never a list of zeros, because "nothing read this" and "nothing could tell" are different facts.
+ */
+/** One window's activity for one resource. */
+export declare interface KayAppUriActivityWindow {
+    /** The span, in days, measured back from the answer's `asOf`. */
+    readonly windowDays: number;
+    /** Counted reads: `personReads + jobReads`. */
+    readonly reads: number;
+    /** Counted reads whose session tree a person started. */
+    readonly personReads: number;
+    /** Counted reads by every other session tree (automations, Dream passes, other jobs). */
+    readonly jobReads: number;
+    /** Distinct session trees (keyed by root session) behind the counted reads. */
+    readonly sessions: number;
+    /** Writes and edits of any origin, maintainers included. */
+    readonly changes: number;
+}
+
+export declare interface KayAppUsage {
+    /**
+     * Read and change activity for every resource whose URI starts with `prefix`, for example
+     * `memory://` or `memory://projects/`. The prefix must name a scheme (`<scheme>://`) that one of
+     * this plugin's registered URI modules serves.
+     */
+    uriActivity(input: {
+        readonly prefix: string;
+    }): Promise<KayAppUriActivityAnswer>;
+}
+
 export declare interface KayAppUserFileEntry {
     readonly name: string;
     /** From the directory entry itself: a symlink is reported as `symlink`, never followed. */
@@ -4591,6 +4826,7 @@ export declare interface KayAppWorkflowDefinition {
     }>;
     readonly run: (context: KayAppWorkflowContext) => Promise<{
         readonly summary: KayAppRunSummary;
+        readonly produced?: KayAppRunProduced;
     }>;
 }
 
@@ -4661,7 +4897,7 @@ export declare interface KayAppWorkspace {
 /**
  * The full workspace arrangement verb catalog: tab lifecycle/reorder/grouping, pane split/close/
  * focus/maximize/restore/place, shell panel toggles, and opening a session. A JSON-safe twin of
- * `KayWorkspaceCommand` in `@kay/agent-runtime-protocol`.
+ * `KayWorkspaceCommand` in `@bonsai/agent-runtime-protocol`.
  */
 export declare type KayAppWorkspaceCommand = {
     verb: "tabs.open";
@@ -4739,7 +4975,14 @@ export declare type KayAppWorkspaceCommand = {
     verb: "shell.togglePanel";
 } | {
     verb: "shell.toggleInspector";
-} | {
+}
+/**
+* Open a session without taking the user's focus. A session no pane shows gets a tab of its own
+* in the background (`opened`); one some pane already shows is left as it is (`applied`). The
+* active tab and every focus stay as they were. The wire's `reveal` flag, which asks for a
+* sidebar-click-style open, is not offered here: it is for Bonsai Desktop's own menus.
+*/
+| {
     verb: "sessions.open";
     sessionId: string;
     title?: string | undefined;
@@ -4747,7 +4990,7 @@ export declare type KayAppWorkspaceCommand = {
 
 /**
  * The one outcome grammar every {@link KayAppWorkspaceCommand} resolves to. A JSON-safe twin of
- * `WorkspaceCommandOutcome` in `@kay/agent-runtime-protocol`.
+ * `WorkspaceCommandOutcome` in `@bonsai/agent-runtime-protocol`.
  */
 export declare type KayAppWorkspaceCommandOutcome = "applied" | "opened" | "focused-existing" | "no-room" | "no-window" | "not-found" | "invalid";
 
@@ -4758,8 +5001,8 @@ export declare interface KayAppWorkspaceExecuteContext {
 
 /**
  * What one pane item shows. A JSON-safe, hand-copied twin of `WorkspacePaneContent` in
- * `@kay/agent-runtime-protocol` — this package cannot import that protocol package (see this
- * module's own doc comment), so the shape is re-declared here. A parity check in `@kay/agent-runtime`
+ * `@bonsai/agent-runtime-protocol` — this package cannot import that protocol package (see this
+ * module's own doc comment), so the shape is re-declared here. A parity check in `@bonsai/agent-runtime`
  * asserts `app.workspace` (the runtime's `KayWorkspaceCapability`, built from the protocol types)
  * stays structurally assignable to {@link KayAppWorkspace} below.
  *
@@ -5503,14 +5746,14 @@ declare interface ScopeRequirement {
  * this list. Two consequences worth knowing:
  *
  * - `sessions.create` and `sessions.run` are the two separately-granted plugin doors
- *   (`@kay/plugin-protocol`'s `permissions.ts`: `create` mints a persisted user-visible session,
+ *   (`@bonsai/plugin-protocol`'s `permissions.ts`: `create` mints a persisted user-visible session,
  *   `run` executes a hidden headless one). Each names ITSELF at the site that mints the session;
  *   neither is inferred from the surface string, which cannot tell them apart.
  * - `sessions.create` stamps a plugin creator only for a create that declares a plugin-surfaced
  *   `system` origin. The SDK `create` door passes no origin today, so its sessions read as the
  *   ordinary chats they are; the value is still the honest one for that door when it does.
  * - `agents.run` (G1, 2026-09) is the generic session-event run door
- *   (`app.agents.run(ref, input, cause, {fork?})`, `@kay/plugin-sdk`'s `kay-app/agents.ts`): a
+ *   (`app.agents.run(ref, input, cause, {fork?})`, `@bonsai/plugin-sdk`'s `kay-app/agents.ts`): a
  *   plugin's `app.sessionEvents.subscribe` handler spins up a bounded agent run in response to a
  *   published session event. `callerSessionId` carries the cause's `sourceSessionId` — the session
  *   whose event caused this run — and {@link SessionProvenanceRecord.causedByEvent} carries the
@@ -6427,6 +6670,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 {
@@ -7244,7 +7493,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/kay-app.js

@@ -503,6 +503,13 @@ function createUnavailableSkills(message) {
   };
 }
 
+// packages/plugin-sdk/dist/kay-app/tools.js
+function createUnavailableTools() {
+  return {
+    describe: async () => ({ status: "unavailable", reason: "not-available" })
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/transcript-text.js
 function transcriptMessageTexts(entries) {
   return entries.flatMap((entry) => {
@@ -531,6 +538,13 @@ function transcriptRoleLabel(role) {
   return role === "user" ? "User" : "Assistant";
 }
 
+// packages/plugin-sdk/dist/kay-app/usage.js
+function createUnavailableUsage(message) {
+  return {
+    uriActivity: async () => ({ status: "unavailable", message })
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/workflows.js
 var KayAppWorkflowFailure = class extends Error {
   summary;
@@ -572,6 +586,8 @@ export {
   createFallbackOnlySignals,
   createFallbackOnlyWithJev,
   createUnavailableSkills,
+  createUnavailableTools,
+  createUnavailableUsage,
   invalidObservation,
   isRetryable,
   parseLineSelector,

package/dist/signals.d.ts

@@ -86,7 +86,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`
@@ -301,7 +301,7 @@ export declare type KayAppSignalsAnswerFilter = {
  */
 export declare interface KayAppSignalsDetectorInput {
     /**
-     * Stable identifier, e.g. `memory-curator-gate`: a lowercase slug (a-z and 0-9 in words joined
+     * Stable identifier, e.g. `memory-packet`: a lowercase slug (a-z and 0-9 in words joined
      * by single hyphens), at most 64 characters, plugin-scoped. It becomes a `signals://` path
      * segment.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",

package/skills/directory-plugin-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: directory-plugin-authoring
-description: "Author, scaffold, debug, or iterate on a Bonsai directory plugin (one the user writes in ~/.kay/plugins/<name>). Use when creating a new local plugin, when a plugin does not appear in Bonsai after installation, when enabling it fails with 'pluginActivation names a plugin that is not installed', when Settings → Plugins shows 'failed to load' with no toggle, when @kay/plugin-sdk imports fail to resolve, when a plugin declares a ui.tsx that nothing typechecks, or when changes to a plugin do not take effect. For installing plugins from a git repository source, use the manage-plugins skill instead; for first-party bundled plugins under plugins/ in the kay repo, use the bundled-plugin guidance there."
+description: "Author, scaffold, debug, or iterate on a Bonsai directory plugin (one the user writes in ~/.kay/plugins/<name>). Use when creating a new local plugin, when a plugin does not appear in Bonsai after installation, when enabling it fails with 'pluginActivation names a plugin that is not installed', when Settings → Plugins shows 'failed to load' with no toggle, when @bonsai/plugin-sdk imports fail to resolve, when a plugin declares a ui.tsx that nothing typechecks, or when changes to a plugin do not take effect. For installing plugins from a git repository source, use the manage-plugins skill instead; for first-party bundled plugins under plugins/ in the kay repo, use the bundled-plugin guidance there."
 ---
 
 # Directory plugin authoring
@@ -14,7 +14,7 @@ keeps an agent on the paved path and out of the known pits.
 
 `pnpm create-plugin` writes absolute type paths (`tsconfig.json`, `package.json`) pointing at
 whichever Bonsai checkout invoked it, with no staleness warning. A checkout far behind `origin/main`
-— one was 752 commits behind — typechecks the new plugin against stale `@kay/plugin-sdk` types,
+— one was 752 commits behind — typechecks the new plugin against stale `@bonsai/plugin-sdk` types,
 and it looks clean: every wrong shape it produced (a `content` object instead of
 `run`/`openBeside` on `PaneActionDescriptor`, `SearchField`'s `onChange` instead of
 `onValueChange`, wrong `PageState` props) typechecked fine against the old types it was
@@ -27,7 +27,7 @@ git -C <kay-checkout> fetch origin && git -C <kay-checkout> rev-list --count HEA
 ```
 
 A nonzero count means update that checkout first, or scaffold from a fresh `origin/main` worktree
-and rebuild `@kay/plugin-sdk` there. A green typecheck against stale types is evidence of nothing.
+and rebuild `@bonsai/plugin-sdk` there. A green typecheck against stale types is evidence of nothing.
 The scaffold does the second half of this for you: it prints a warning when the checkout trails
 its last-fetched `origin/main`, and stamps the checkout's commit into the generated
 `tsconfig.json` header. It never fetches, so the `fetch` above is still yours to run; a checkout
@@ -36,7 +36,7 @@ that has not fetched in a week reads as current to the scaffold.
 ## Scaffold, never hand-roll
 
 ```
-pnpm --filter @kay/plugin-sdk build   # once per checkout, if not built
+pnpm --filter @bonsai/plugin-sdk build   # once per checkout, if not built
 pnpm create-plugin --id com.example.widgets
 ```
 
@@ -44,14 +44,14 @@ Run from the root of a Bonsai checkout. It writes a working plugin (manifest, en
 README) that already typechecks and loads; `--tier starter` adds a URI module, a bundled skill,
 and a standalone `node --test` test to copy from. Add `--ui` (either tier) when the plugin needs a
 page: it writes `ui.tsx`, declares the `kay.ui` entrypoint, and generates the UI typecheck config
-described below. `--ui` also needs `pnpm --filter @kay/ui build` once per checkout; the scaffold
+described below. `--ui` also needs `pnpm --filter @bonsai/ui build` once per checkout; the scaffold
 stops and says so when that build is missing.
 
 Never hand-build a plugin as a tsc-compiled package and copy the output into `~/.kay/plugins/`.
-That path produces a plugin whose built `dist/` imports `@kay/plugin-sdk` through ordinary
+That path produces a plugin whose built `dist/` imports `@bonsai/plugin-sdk` through ordinary
 `node_modules` resolution, which cannot work from outside the monorepo — it shipped a
 failed-to-load plugin and a misfiled bug (#7732). The load fails with `ERR_MODULE_NOT_FOUND`,
-and symlinking `node_modules/@kay` into the copy does not rescue it either: pnpm's `.pnpm`
+and symlinking `node_modules/@bonsai` into the copy does not rescue it either: pnpm's `.pnpm`
 layout does not expose workspace packages that way. The scaffold exists precisely so this
 cannot happen.
 
@@ -62,7 +62,7 @@ pnpm plugin:check ~/.kay/plugins/widgets
 ```
 
 Run from the root of a Bonsai checkout, against the plugin directory. It runs the daemon's OWN
-manifest schema and contract resolver (imported from `@kay/plugin-protocol`, not re-implemented),
+manifest schema and contract resolver (imported from `@bonsai/plugin-protocol`, not re-implemented),
 so it answers "would Kay accept this manifest?" in about a second instead of after a load cycle.
 Run it after every manifest edit, and before concluding a plugin is broken for some deeper reason.
 
@@ -82,13 +82,13 @@ disclosure audit, or an id another installed plugin already claims.
 
 ## The SDK resolution contract
 
-- Plugin source imports `@kay/plugin-sdk/<subpath>` as a **bare specifier**
-  (`@kay/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure` — only declared
+- Plugin source imports `@bonsai/plugin-sdk/<subpath>` as a **bare specifier**
+  (`@bonsai/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure` — only declared
   exports exist).
 - The daemon's chord loader bundles each declared TypeScript entrypoint and its relative imports.
-  It keeps `@kay/plugin-sdk` imports external and resolves them to the running app's own built SDK.
+  It keeps `@bonsai/plugin-sdk` imports external and resolves them to the running app's own built SDK.
   Multi-file plugins are supported, and no plugin-local build is needed for Bonsai to load them.
-- Corollary: **bare `node` outside the daemon cannot resolve `@kay/plugin-sdk`** from the plugin
+- Corollary: **bare `node` outside the daemon cannot resolve `@bonsai/plugin-sdk`** from the plugin
   directory unless the plugin has its own SDK dependency. That failure says nothing about whether
   the plugin will load in Bonsai. The `starter` tier's test setup creates the symlink needed for its
   standalone test; a published SDK dependency is the other standalone option.
@@ -106,7 +106,7 @@ entrypoint may import other files in the plugin; `kay.agent` runs in the daemon
 self-contained module: unlike the daemon targets, `ui.tsx` cannot import sibling files. A
 plugin UI contributes through `api.slots` (`registerPage`, `registerSidebarItem`,
 `registerPaneAction`, and the rest of `buildSlots` in
-`apps/kay/src/renderer/src/extension-loader/build-extension-api.ts`). A page gets its own
+`packages/kay-renderer/src/renderer/src/extension-loader/build-extension-api.ts`). A page gets its own
 activity-rail button when a `registerSidebarItem({ pageId, placement: "activityRail" })` from the
 same plugin points at it.
 
@@ -119,17 +119,17 @@ and its rail item borrow each other's glyph, so one declaration covers the desti
 precedence: `packages/kay-frontend-sdk/ARCHITECTURE.md`, "Plugin icon".
 
 `ui.tsx` has no `node_modules` of its own. The renderer bundles it and rewrites its `react` and
-`@kay/*` imports to the host's `__KAY_UI_RUNTIME__` singletons, so the agent `tsconfig.json`
+`@bonsai/*` imports to the host's `__KAY_UI_RUNTIME__` singletons, so the agent `tsconfig.json`
 cannot cover it, and a plugin whose UI nothing typechecks has shipped three wrong API shapes at
 once. `pnpm create-plugin --ui` generates `tsconfig.ui.json` for exactly this: its `paths` are
-derived from the bundler's own shim set (`uiRuntimeShimModules` in `@kay/ui-app-bundler`), each
+derived from the bundler's own shim set (`uiRuntimeShimModules` in `@bonsai/ui-app-bundler`), each
 specifier mapped to the type entry the renderer binds it to, and `npm run typecheck` runs both
 configs. Do not hand-write the map; when the bundler's set changes, the scaffold's test fails and
 the generated config follows.
 
 Two facts about that config worth knowing when you read errors from it:
 
-- The bare `@kay/frontend-sdk` is typed against the SDK's `ui-runtime` facade, because that is
+- The bare `@bonsai/frontend-sdk` is typed against the SDK's `ui-runtime` facade, because that is
   what the renderer binds it to. The facade carries the SDK's whole type surface, so
   `KayUiExtensionApi` and every descriptor type import fine; a **value** only the package's main
   entry exports fails to compile there (TS1362, "exported using export type"), which is the
@@ -210,9 +210,9 @@ a failure class the load would otherwise be the first thing to surface:
 
 1. **Run `pnpm plugin:check <dir>`** from a Bonsai checkout. It validates `kay-plugin.json` against
    `KayPluginManifestV1` and resolves its contributions with the daemon's own resolver (both from
-   `@kay/plugin-protocol`), not just "it is valid JSON": that schema and resolver are the gate the
+   `@bonsai/plugin-protocol`), not just "it is valid JSON": that schema and resolver are the gate the
    scan actually runs. A non-zero exit means the plugin would be refused.
-2. **Run the disclosure audit yourself**: `auditPluginDisclosure` from `@kay/plugin-sdk/disclosure`.
+2. **Run the disclosure audit yourself**: `auditPluginDisclosure` from `@bonsai/plugin-sdk/disclosure`.
    It is not redundant with typecheck. A plugin shipped a `search` verb with no `verbDocs` entry
    that typechecked clean and would have failed the whole `kay.agent` target.
 3. **Typecheck every target**: `npm run typecheck` runs the agent config and, for a `--ui`