@yaklabs-ai/plugin-sdk 0.13.2 → 0.13.4

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.2"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.4"
   }
 }
 ```
 
 **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.2",
+  "version": "0.13.4",
   "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[];
@@ -3915,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[];
@@ -3813,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.
  *

package/dist/kay-agent.d.ts

@@ -244,7 +244,7 @@ export declare function asArray(value: unknown): readonly unknown[];
  *   - {@link asRecord}, {@link asArray}, {@link str}, {@link num}, {@link numLike}.
  * does_not_own:
  *   - Schema-shaped validation. **Idiom-routing rule (read before reaching for these):** `z`
- *     (re-exported from this same `@kay/plugin-sdk/kay-agent` module) is the default for
+ *     (re-exported from this same `@bonsai/plugin-sdk/kay-agent` module) is the default for
  *     anything shape-contractual — a tool's own `parameters` (via `toolParameters`), and any
  *     upstream response you're going to treat as a stable contract going forward. Reach for these
  *     readers only for **tolerant salvage**: pulling one or two fields out of a response whose
@@ -315,6 +315,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;
@@ -611,6 +615,9 @@ export declare interface CreateJsonApiClientOptions {
     readonly fetch?: typeof fetch;
 }
 
+/** One plugin's runner: its module, its label, and the app-specific failures it names. */
+export declare function createOsascriptRunner(options: OsascriptRunnerOptions): OsascriptRunner;
+
 /** What the module holds at mutation time: a provider revision, the current content, or both. */
 export declare interface CurrentResourceState {
     readonly revision?: string;
@@ -831,6 +838,12 @@ declare interface ExtensionPaths {
     readonly dataDir: string;
 }
 
+/**
+ * Several lines of text inside a code fence none of its lines can close, so a message body or an
+ * invitation's notes cannot pass for a heading or a field of the read around them.
+ */
+export declare function fenced(text: string): readonly string[];
+
 export declare function formatIsoDate(value?: string | number | Date): string;
 
 export declare function formatNumber(n: number): string;
@@ -881,7 +894,7 @@ declare type InferToolInput<TParams extends ToolParametersWire> = TParams extend
 
 /**
  * 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.
  */
 export declare const INTERACTION_CREDENTIAL_GUARD = "kay.credential-guard/v1";
@@ -1221,7 +1234,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`
@@ -1875,7 +1888,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.
@@ -2823,6 +2836,35 @@ declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai
 
 declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
 
+/**
+ * A one-line label the host prints verbatim, such as an approval card's target. Line breaks,
+ * other control characters, and line or paragraph separators become spaces, and invisible format
+ * characters go: a zero-width joiner inside an emoji, a soft hyphen, a direction mark, a
+ * zero-width space. The host refuses a target holding any of them, and drops the whole approval
+ * card with it (`admitDescription` in herd-agent's `action-summary.ts`).
+ */
+export declare function labelOf(value: string | null | undefined): string;
+
+/**
+ * ---
+ * responsibility: The flat authoring-helper layer's untrusted-text surface (decision 002,
+ *   kay#11957): render text someone else wrote (a shared calendar's name, a contact card synced
+ *   from another account, an email body) into a plugin's Markdown output or an approval card
+ *   without it forging structure around it. Apple Mail, Calendar, and Contacts had each grown a
+ *   copy.
+ * owns:
+ *   - {@link lineOf}, {@link labelOf}, {@link markdownText}, {@link fenced}.
+ * does_not_own:
+ *   - Deciding which fields are untrusted. Every value the user does not control is; the plugin
+ *     routes each one through these before it reaches output.
+ * ---
+ */
+/**
+ * A one-line field: every whitespace run, newlines included, becomes one space, so a value can
+ * never open a line of its own (one that passes for an `Account:` line, for instance).
+ */
+export declare function lineOf(value: string | null | undefined): string;
+
 declare interface LineRange {
     readonly start: number;
     readonly end: number;
@@ -2840,6 +2882,17 @@ export declare function lintUriTemplate(template: UriTemplate): readonly UriTemp
 
 export declare function markdownResource(uri: string, md: string, notes?: string[]): RawResource;
 
+/**
+ * Text placed mid-line, after a label, that cannot forge a link, an image, an HTML tag, or a
+ * field: a backslash goes before `[`, `]`, `!`, and `<`; before `|`, which a plugin may use to
+ * separate the fields of a one-line summary; and before a backslash, so no escape can be undone.
+ *
+ * It does not neutralize everything Markdown does. Line-start syntax (`#`, `>`, `-`, `1.`),
+ * emphasis, code spans, and bare-URL autolinks still render, so keep the value off the start of a
+ * line (behind a label, after {@link lineOf}) or use {@link fenced} for whole blocks.
+ */
+export declare function markdownText(text: string): string;
+
 /**
  * The execute-time surface a tool sees. These are the only fields a {@link ToolDefinition.execute}
  * body can read. Runtime-optionals are absent without a live session: a tool invoked from a
@@ -3276,11 +3329,183 @@ declare interface OpenRouterRouting {
     };
 }
 
+/**
+ * The JXA half of the envelope: paste it into a script's source, then end `run(argv)` with
+ * `return jsonOk(data)` or `return jsonFail(code, message)`. {@link readOsascriptOutput} reads
+ * exactly what these print. Both are total: `jsonOk()` with no value answers `null` (JSON drops an
+ * `undefined` key, which the reader would refuse), and `jsonFail` turns its code and message into
+ * strings, so a thrown non-Error or an Error object passed as the message still reaches the
+ * caller as this script's refusal, under its own code.
+ */
+export declare const OSASCRIPT_ENVELOPE_JXA = "\nfunction jsonOk(data) {\n  return JSON.stringify({ ok: true, data: data === undefined ? null : data });\n}\nfunction jsonFail(code, message) {\n  return JSON.stringify({ ok: false, error: { code: String(code), message: String(message) } });\n}\n";
+
+/** The runner's kill deadline when a call names none. */
+export declare const OSASCRIPT_TIMEOUT_MS = 30000;
+
+/**
+ * The argv for one script run: JavaScript, the script as a fixed `-e` constant, then `--` and the
+ * dynamic values. `--` ends osascript's own option parsing: without it, a value in the first argv
+ * slot that starts with `-` (a search for "-budget", a folder named "-Archive") is taken as an
+ * option and the script never runs (the Apple Notes plugin verified this live). User values only
+ * ever travel here, never in the script source: that is the injection boundary.
+ */
+export declare function osascriptArgs(script: string, argv: readonly string[]): readonly string[];
+
+/** One script run: what the error names, and the bounds the runner enforces. */
+export declare interface OsascriptCall {
+    readonly operation: UriOperation;
+    readonly uri: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly maxOutputChars: number;
+    /** The runner's kill deadline; absent means {@link OSASCRIPT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** What to do when the output is too large; absent means "narrow the request". */
+    readonly truncatedAdvice?: string;
+    /**
+     * Set for a script that changes the app: the sentence that ends the error when its run fails
+     * before Bonsai reads its answer, such as "The event may have been created: search
+     * apple-calendar://events before trying again." The script may have saved before the runner
+     * failed, osascript stopped (a timeout or a cancel), or its output became unreadable. A refusal
+     * the script returns itself (`jsonFail`) does not end with this sentence: a script refuses
+     * before it changes anything.
+     */
+    readonly outcomeUnknown?: string;
+}
+
+/** The runner a module's verbs use, with a simulator in the host's place when one is set. */
+export declare interface OsascriptDispatch {
+    /**
+     * {@link OsascriptRunner.requireExternalCli}, then the simulator's runner in the host's place.
+     * The host's runner is required either way: its absence is how a not-connected service fails.
+     */
+    readonly requireExternalCli: (ctx: UriResolveContext, operation: UriOperation, uri: string) => UriExternalCliRunner;
+    /**
+     * The runner for a path that tolerates its absence (an approval card's lookup): `undefined`
+     * when the host injected none, the simulator's when one is set, the host's otherwise.
+     */
+    readonly externalCliOf: (ctx: UriResolveContext) => UriExternalCliRunner | undefined;
+}
+
+/** A failure the plugin names: its own code, and the advice that ends the message. */
+export declare interface OsascriptFailureAdvice {
+    readonly code: string;
+    readonly advice: string;
+}
+
+/**
+ * The activation options every osascript plugin's agent factory accepts
+ * (`createAppleCalendarKayAgent(options)`), so the daemon's simulator roster sets each the same
+ * way. Absent `simulator`, the plugin is exactly the shipped one.
+ */
+export declare interface OsascriptKayAgentOptions {
+    readonly simulator?: OsascriptSimulatorOptions;
+}
+
+/** What a script's stdout says, once read. */
+export declare type OsascriptOutput = 
+/** `jsonOk(data)`. `data` is unchecked: validate it against the script's own shape. */
+    {
+    readonly kind: "data";
+    readonly data: unknown;
+}
+/** `jsonFail(code, message)`: the script refused on its own terms. */
+| {
+    readonly kind: "refused";
+    readonly code: string;
+    readonly message: string;
+}
+/**
+* Not JSON, or JSON that is not an envelope (`null`, `{}`, `42`, `{"ok":false}`, and
+* `{"ok":true}` with no `data` key, which {@link OSASCRIPT_ENVELOPE_JXA}'s `jsonOk` never prints).
+*/
+| {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+
+export declare interface OsascriptRunner {
+    /**
+     * The host-injected runner, or the `auth_required` error the host classifies as not
+     * connected: the in-handler twin of the host's pre-dispatch auth resolution.
+     */
+    readonly requireExternalCli: (ctx: UriResolveContext, operation: UriOperation, uri: string) => UriExternalCliRunner;
+    /**
+     * The runners a module's verbs use: the host's exactly when `simulator` is absent, or the
+     * simulator's in its place, per dispatch, after the host's connection gate.
+     */
+    readonly dispatch: (simulator: OsascriptSimulatedRunner | undefined) => OsascriptDispatch;
+    /**
+     * Run `script` with `argv` and return the data it answered (unchecked: validate it). Every
+     * other outcome throws a `UriProviderError`, except a runner that throws on its own: that
+     * error passes through unchanged unless the call sets `outcomeUnknown`.
+     */
+    readonly runScript: (externalCli: UriExternalCliRunner, script: string, argv: readonly string[], call: OsascriptCall) => Promise<unknown>;
+    /** A `UriProviderError` from this plugin's module, never retryable. */
+    readonly providerError: (call: Pick<OsascriptCall, "operation" | "uri">, providerCode: string, message: string) => UriProviderError;
+    /**
+     * The error for a run that exited non-zero, for a caller that reads the runner's result
+     * itself (a send path that reads progress markers from stderr). Ends with the call's
+     * `outcomeUnknown` sentence when it has one.
+     */
+    readonly scriptFailure: (call: OsascriptCall, result: Pick<UriExternalCliRunResult, "stderr" | "stdout">) => UriProviderError;
+}
+
+export declare interface OsascriptRunnerOptions {
+    /** The URI module every error names. */
+    readonly moduleId: string;
+    /** The service a missing runner tells the agent to connect. */
+    readonly serviceId: string;
+    /** The product name that opens each message, such as "Apple Calendar". */
+    readonly label: string;
+    /**
+     * What opens the message of a failed run; absent means "<label> automation failed". A plugin
+     * that scripts no app (its JXA calls a framework directly) says "<label> script failed".
+     */
+    readonly failurePrefix?: string;
+    /**
+     * Advice for macOS refusing the Apple Event (`-1743`, "not authorized"): the Automation grant
+     * is missing or revoked. Set, such a run fails `automation-denied` with this advice; absent,
+     * it is an ordinary `script-failed`.
+     */
+    readonly automationDeniedAdvice?: string;
+    /**
+     * The plugin's code and advice for its app quitting mid-run: `-600` (application isn't
+     * running) before the script's first Apple Event, `-609` (connection is invalid) after it.
+     * Absent, such a run is an ordinary `script-failed`. The check a script makes itself
+     * (`running()`, then `jsonFail`) is the plugin's, and comes back as that refusal.
+     */
+    readonly appNotRunning?: OsascriptFailureAdvice;
+}
+
+/** A plugin's simulator, as the runner sees it: the runner one dispatch uses in the host's place. */
+export declare interface OsascriptSimulatedRunner {
+    readonly runnerFor: (ctx: UriResolveContext) => UriExternalCliRunner;
+}
+
+/**
+ * How a plugin is told to serve its module from its simulator instead of osascript: the one
+ * option shape every osascript plugin's agent factory accepts as `simulator`. Only the daemon's
+ * URI simulator roster sets it, for evals and dev; an ordinary install never does.
+ */
+export declare interface OsascriptSimulatorOptions {
+    /** The directory holding the simulator's world; the daemon's process config names it. */
+    readonly stateDir: string;
+}
+
 export declare function parseLineSelector(input: string): {
     address: string;
     selector: LineSelector;
 };
 
+/**
+ * The script and argv of a request {@link osascriptArgs} built, or `undefined` for any other
+ * argv. A simulated runner reads requests through this, so the argv layout has one owner.
+ */
+export declare function parseOsascriptArgs(args: readonly string[]): {
+    readonly script: string;
+    readonly argv: readonly string[];
+} | undefined;
+
 export declare function parseUriConnectionSelector(input: string): UriConnectionSelectorParse;
 
 /** Parse either dialect into the normalized replacement list. */
@@ -3889,6 +4114,9 @@ declare interface RawResourceMetadata {
  */
 export declare function readBodyWithByteCap(response: Response, maxBytes: number): Promise<ByteCapReadResult | undefined>;
 
+/** Read a script's stdout. Never throws: anything but a well-formed envelope is `invalid`. */
+export declare function readOsascriptOutput(stdout: string): OsascriptOutput;
+
 /**
  * The capability⇄service auth binding. A registration carrying this is gated on `serviceId`'s
  * connectivity; the runtime answers "is this capability authorized?" from this plus vault state.
@@ -4003,6 +4231,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";
+
 export declare type SchemaInput = z.ZodType | JsonSchema;
 
 /** One all-of arm in an ordered scope requirement. */
@@ -5808,7 +6058,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.
  *