@yaklabs-ai/plugin-sdk 0.13.2 → 0.13.4

package/dist/kay-agent.js

@@ -1011,7 +1011,7 @@ async function readBodyWithByteCap(response, maxBytes) {
 }
 
 // packages/plugin-sdk/dist/kay-agent/index.js
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // packages/plugin-sdk/dist/kay-agent/http-client.js
 var PluginApiError = class extends Error {
@@ -1164,6 +1164,163 @@ function bytesToBase64(bytes) {
   return output;
 }
 
+// packages/plugin-sdk/dist/kay-agent/osascript.js
+import { z as z6 } from "zod";
+var OSASCRIPT_TIMEOUT_MS = 3e4;
+var OSASCRIPT_ENVELOPE_JXA = `
+function jsonOk(data) {
+  return JSON.stringify({ ok: true, data: data === undefined ? null : data });
+}
+function jsonFail(code, message) {
+  return JSON.stringify({ ok: false, error: { code: String(code), message: String(message) } });
+}
+`;
+var envelopeSchema = z6.discriminatedUnion("ok", [
+  z6.object({ ok: z6.literal(true), data: z6.unknown() }),
+  z6.object({
+    ok: z6.literal(false),
+    error: z6.object({ code: z6.string(), message: z6.string() })
+  })
+]);
+function readOsascriptOutput(stdout) {
+  let json;
+  try {
+    json = JSON.parse(stdout);
+  } catch (error) {
+    return {
+      kind: "invalid",
+      reason: `output that was not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  const envelope = envelopeSchema.safeParse(json);
+  if (!envelope.success) {
+    return {
+      kind: "invalid",
+      reason: "output in a shape Bonsai does not know."
+    };
+  }
+  return envelope.data.ok ? { kind: "data", data: envelope.data.data } : {
+    kind: "refused",
+    code: envelope.data.error.code,
+    message: envelope.data.error.message
+  };
+}
+function osascriptArgs(script, argv) {
+  return ["-l", "JavaScript", "-e", script, "--", ...argv];
+}
+function parseOsascriptArgs(args) {
+  const [language, name, flag, script, separator, ...argv] = args;
+  if (language !== "-l" || name !== "JavaScript" || flag !== "-e" || script === void 0 || separator !== "--") {
+    return void 0;
+  }
+  return { script, argv };
+}
+function withOutcome(call, message) {
+  if (call.outcomeUnknown === void 0)
+    return message;
+  const sentence = /[.!?]$/.test(message) ? message : `${message}.`;
+  return `${sentence} ${call.outcomeUnknown}`;
+}
+function createOsascriptRunner(options) {
+  const failurePrefix = options.failurePrefix ?? `${options.label} automation failed`;
+  const providerError = (call, providerCode, message) => new UriProviderError({
+    moduleId: options.moduleId,
+    operation: call.operation,
+    uri: call.uri,
+    message,
+    providerCode,
+    retryable: false
+  });
+  const requireExternalCli = (ctx, operation, uri) => {
+    const externalCli = ctx.auth?.externalCli;
+    if (externalCli === void 0) {
+      throw new UriProviderError({
+        moduleId: options.moduleId,
+        operation,
+        uri,
+        message: `${options.label} access is not connected. Run service_connect for ${options.serviceId}.`,
+        providerCode: "auth_required"
+      });
+    }
+    return externalCli;
+  };
+  const dispatch = (simulator) => simulator === void 0 ? {
+    requireExternalCli,
+    externalCliOf: (ctx) => ctx.auth?.externalCli
+  } : {
+    requireExternalCli: (ctx, operation, uri) => {
+      requireExternalCli(ctx, operation, uri);
+      return simulator.runnerFor(ctx);
+    },
+    externalCliOf: (ctx) => ctx.auth?.externalCli === void 0 ? void 0 : simulator.runnerFor(ctx)
+  };
+  const scriptFailure = (call, result) => {
+    const detail = (result.stderr.trim() !== "" ? result.stderr : result.stdout).trim();
+    const base = `${failurePrefix}: ${detail !== "" ? detail : "osascript exited with a non-zero status."}`;
+    const denied = options.automationDeniedAdvice;
+    if (denied !== void 0 && (/-1743/.test(detail) || /not authorized/i.test(detail))) {
+      return providerError(call, "automation-denied", withOutcome(call, `${base} ${denied}`));
+    }
+    const notRunning = options.appNotRunning;
+    if (notRunning !== void 0 && (/-60[09]\b/.test(detail) || /isn.t running/i.test(detail))) {
+      return providerError(call, notRunning.code, withOutcome(call, `${base} ${notRunning.advice}`));
+    }
+    return providerError(call, "script-failed", withOutcome(call, base));
+  };
+  const runScript = async (externalCli, script, argv, call) => {
+    let result;
+    try {
+      result = await externalCli.run({
+        args: osascriptArgs(script, argv),
+        timeoutMs: call.timeoutMs ?? OSASCRIPT_TIMEOUT_MS,
+        maxOutputChars: call.maxOutputChars,
+        ...call.signal !== void 0 ? { signal: call.signal } : {}
+      });
+    } catch (error) {
+      if (call.outcomeUnknown === void 0)
+        throw error;
+      throw providerError(call, "script-failed", withOutcome(call, `${failurePrefix}: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    if (result.exitCode !== 0)
+      throw scriptFailure(call, result);
+    if (result.stdoutTruncated === true) {
+      throw providerError(call, "output-truncated", withOutcome(call, `${options.label} script output was truncated; ${call.truncatedAdvice ?? "narrow the request"}.`));
+    }
+    const output = readOsascriptOutput(result.stdout);
+    switch (output.kind) {
+      case "data":
+        return output.data;
+      case "refused":
+        throw providerError(call, output.code, output.message);
+      case "invalid":
+        throw providerError(call, "output-invalid", withOutcome(call, `${options.label} script produced ${output.reason}`));
+    }
+  };
+  return {
+    requireExternalCli,
+    dispatch,
+    runScript,
+    providerError,
+    scriptFailure
+  };
+}
+
+// packages/plugin-sdk/dist/kay-agent/untrusted-text.js
+function lineOf(value) {
+  return (value ?? "").trim().replace(/\s+/g, " ");
+}
+function labelOf(value) {
+  return lineOf((value ?? "").replace(/[\p{Cc}\p{Zl}\p{Zp}]/gu, " ").replace(/\p{Cf}/gu, ""));
+}
+function markdownText(text) {
+  return text.replace(/[\\[\]!<|]/g, (character) => `\\${character}`);
+}
+function fenced(text) {
+  const runs = text.match(/`+/g) ?? [];
+  const fence = "`".repeat(Math.max(3, ...runs.map((run) => run.length + 1)));
+  return [`${fence}text`, text, fence];
+}
+
 // packages/plugin-sdk/dist/kay-agent/advertisement.js
 function defineKayAgentAdvertisement(advertisement) {
   return advertisement;
@@ -1399,6 +1556,8 @@ export {
   KayAgentCapabilityError,
   KayAgentWebSessionError,
   OBSERVATION_MIME,
+  OSASCRIPT_ENVELOPE_JXA,
+  OSASCRIPT_TIMEOUT_MS,
   PluginApiError,
   SearchProviderError,
   URI_TEXT_EDIT_SHAPE_SUMMARY,
@@ -1420,28 +1579,36 @@ export {
   contentResult,
   createFallbackOnlyWithJev,
   createJsonApiClient,
+  createOsascriptRunner,
   declareProducedResources,
   defineAuthedTool,
   defineKayAgentAdvertisement,
   defineTool,
   describeUriTextEditTarget,
+  fenced,
   formatIsoDate,
   formatNumber,
   getBytes,
   isDelegatedRefreshRejected,
   jsonResource,
+  labelOf,
+  lineOf,
   lintUriHelpContracts,
   lintUriTemplate,
   markdownResource,
+  markdownText,
   num,
   numLike,
   observationFromResource,
   observationResource,
+  osascriptArgs,
   parseLineSelector,
+  parseOsascriptArgs,
   parseUriConnectionSelector,
   parseUriTextEditPayload,
   payload,
   readBodyWithByteCap,
+  readOsascriptOutput,
   str,
   textResult,
   toJsonSchema,
@@ -1452,5 +1619,5 @@ export {
   uriTextEditPayloadSchema,
   withResolvedAuth,
   withResolvedSearchProvider,
-  z6 as z
+  z7 as z
 };

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;
@@ -437,6 +441,12 @@ export declare function createUnavailableSkills(message: string): KayAppSkills;
  */
 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;
@@ -765,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`
@@ -1155,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. */
@@ -1927,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
@@ -2677,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.
@@ -2877,6 +2905,16 @@ export declare interface KayAppPluginApi {
      * 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. */
@@ -3090,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;
@@ -3100,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.
  */
@@ -3236,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>;
 }
 
@@ -3734,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.
      */
@@ -4169,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.
@@ -4365,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;
@@ -4398,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. */
@@ -4680,6 +4826,7 @@ export declare interface KayAppWorkflowDefinition {
     }>;
     readonly run: (context: KayAppWorkflowContext) => Promise<{
         readonly summary: KayAppRunSummary;
+        readonly produced?: KayAppRunProduced;
     }>;
 }
 
@@ -4750,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";
@@ -4828,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;
@@ -4836,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";
 
@@ -4847,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.
  *
@@ -5592,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
@@ -7339,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

@@ -538,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;
@@ -580,6 +587,7 @@ export {
   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.2",
+  "version": "0.13.4",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",