@yaklabs-ai/plugin-sdk 0.13.1 → 0.13.3

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.
@@ -2811,6 +2824,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
         minKayVersion: z.ZodOptional<z.ZodString>;
         sdk: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
+    ownedByBonsai: z.ZodOptional<z.ZodBoolean>;
     dependencies: z.ZodOptional<z.ZodObject<{
         plugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
@@ -2822,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;
@@ -2839,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
@@ -3275,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. */
@@ -3422,6 +3648,10 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"skills.read">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"tools.describe">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
@@ -3884,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.
@@ -3998,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. */
@@ -4939,6 +5194,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 {
@@ -5797,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.
  *

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
 };