@yaklabs-ai/plugin-sdk 0.54.0 → 0.54.1

package/dist/kay-agent.d.ts

@@ -815,6 +815,9 @@ export declare function createUnavailableEndpoints(message: string): KayAgentEnd
 
 export declare function createUnavailablePluginEndpointCaller(message: string): PluginEndpointCaller;
 
+/** A refusal handle for hosts that have not composed plugin worker execution. */
+export declare function createUnavailablePluginWorkers(): KayPluginWorkers;
+
 export declare function createUnavailableUriCaller(message: string): PluginUriCaller;
 
 /** What the module holds at mutation time: a provider revision, the current content, or both. */
@@ -1073,6 +1076,10 @@ declare const DollarSign = "$";
 
 declare const Dot = ".";
 
+declare type DriverAction<T> = T extends unknown ? {
+    readonly [Key in keyof T]: ReadonlyContract<Exclude<T[Key], undefined>>;
+} : never;
+
 declare type DurationUnit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
 
 declare const Element: (input: string) => [unknown, string] | [];
@@ -1652,78 +1659,300 @@ export declare interface InteractionActed {
     };
 }
 
+export declare type InteractionAction = DriverAction<InteractionAction_2>;
+
 /**
- * One action over a candidate from the latest observation of the same target. `fill` replaces the
- * field's contents unless `append` is set, and presses Enter afterwards when `submit` is set.
+ * One action over a candidate from the latest observation of the same target. `element` is that
+ * candidate, returned whole so the driver resolves its own native identity immediately before
+ * input. `fill` replaces the field's contents unless `append` is set, and presses Enter (Return)
+ * afterwards when `submit` is set.
  */
-export declare type InteractionAction = {
-    readonly kind: "click";
-    readonly element: InteractionCandidate;
-} | {
-    readonly kind: "fill";
-    readonly element: InteractionCandidate;
-    readonly text: string;
-    readonly submit?: boolean;
-    readonly append?: boolean;
-} | {
-    readonly kind: "select";
-    readonly element: InteractionCandidate;
-} | {
-    readonly kind: "activate";
-    readonly element: InteractionCandidate;
-} | {
-    readonly kind: "press";
-    readonly element: InteractionCandidate;
-}
-/**
-* Scroll by `delta` px (positive is down). With `element` (a `scroll` candidate that names a
-* node), the scroll container that candidate scrolls; without, the whole page or window.
-*/
-| {
-    readonly kind: "scroll";
-    readonly delta: number;
-    readonly element?: InteractionCandidate;
-} | {
-    readonly kind: "wait";
-};
+declare const InteractionAction_2: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"click">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"fill">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+    text: z.ZodString;
+    submit: z.ZodOptional<z.ZodBoolean>;
+    append: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"select">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"activate">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"press">;
+    element: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"scroll">;
+    delta: z.ZodNumber;
+    element: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"wait">;
+}, z.core.$strict>], "kind">;
+
+declare type InteractionAction_2 = z.infer<typeof InteractionAction_2>;
+
+export declare type InteractionCandidate = ReadonlyContract<InteractionCandidate_2>;
 
 /**
- * One element (or control) an observation offers, with the kind of action it supports. `id` is
- * the driver's per-observation id; the engine mints its own session-unique ids over it. Extra
- * fields are the driver's native identity (a page node number, an accessibility token), returned
- * to the driver untouched in {@link InteractionAction}.
+ * One element (or control) a driver offers in an {@link InteractionObservation}: a role, a label,
+ * a value, and the kind of action it supports. `id` is the driver's per-observation candidate id
+ * (`e1`, `scroll_down`, `wait`); the Interaction engine mints its own session-unique ids over it.
+ * The driver-native identity rides along as passthrough fields the driver alone reads back in
+ * {@link InteractionAction}: `node` (a page element), `target`/`app` (accessibility tokens),
+ * `key` (a key to press). Nothing here is a selector the model wrote.
  */
-export declare interface InteractionCandidate {
-    readonly id: string;
-    readonly kind: InteractionCandidateKind;
-    readonly label: string;
-    readonly node?: number | undefined;
-    readonly role?: string | undefined;
-    readonly value?: string | undefined;
-    readonly current_value?: string | undefined;
-    readonly checked?: string | undefined;
-    readonly selected?: string | undefined;
-    readonly expanded?: string | undefined;
-    /**
-     * What a page driver found the element to be in the DOM, not what the page calls it: `link` is an
-     * anchor that navigates to another http(s) page; `widget` is an element that is no form control.
-     * Absent means unknown, and the engine then treats the element as any other.
-     */
-    readonly look?: "link" | "widget" | undefined;
-    readonly delta?: number | undefined;
-    /** Where an element outside the visible area sits; absent means on screen. */
-    readonly position?: "above" | "below" | "beside" | undefined;
-    /** A `press` candidate's key (`return`, `escape`, `tab`); its id is `press_<key>` by convention. */
-    readonly key?: string | undefined;
-    /** The region the element sits in; see {@link InteractionRegion}. */
-    readonly region?: InteractionRegion | undefined;
-    /**
-     * The `node` of the scroll container (a list or pane that scrolls on its own) the element sits
-     * in, matching that container's `scroll` candidates; absent when it sits in none.
-     */
-    readonly scroller?: number | undefined;
-    readonly [native: string]: unknown;
-}
+declare const InteractionCandidate_2: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        fill: "fill";
+        activate: "activate";
+        click: "click";
+        select: "select";
+        scroll: "scroll";
+        wait: "wait";
+        press: "press";
+    }>;
+    label: z.ZodString;
+    node: z.ZodOptional<z.ZodNumber>;
+    role: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    current_value: z.ZodOptional<z.ZodString>;
+    checked: z.ZodOptional<z.ZodString>;
+    selected: z.ZodOptional<z.ZodString>;
+    expanded: z.ZodOptional<z.ZodString>;
+    look: z.ZodOptional<z.ZodEnum<{
+        link: "link";
+        widget: "widget";
+    }>>;
+    delta: z.ZodOptional<z.ZodNumber>;
+    position: z.ZodOptional<z.ZodEnum<{
+        above: "above";
+        below: "below";
+        beside: "beside";
+    }>>;
+    region: z.ZodOptional<z.ZodObject<{
+        role: z.ZodString;
+        name: z.ZodString;
+        front: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    scroller: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+
+declare type InteractionCandidate_2 = z.infer<typeof InteractionCandidate_2>;
 
 /** The candidate kinds a driver may offer. */
 export declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
@@ -1777,16 +2006,53 @@ export declare interface InteractionFailure {
     readonly message: string;
 }
 
-/** What a driver sees on one target. */
-export declare interface InteractionObservation {
-    readonly url: string;
-    readonly title: string;
-    /** Visible text, or the whole page's text when the observe asked for `fullText`; capped. */
-    readonly text: string;
-    readonly actions: readonly InteractionCandidate[];
-    /** Candidates the driver dropped to stay within its cap. */
-    readonly omitted_actions: number;
-}
+export declare type InteractionObservation = ReadonlyContract<InteractionObservation_2>;
+
+/** What a driver sees on one target: its address, title, text, and actionable candidates. */
+declare const InteractionObservation_2: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodString;
+    text: z.ZodString;
+    actions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fill: "fill";
+            activate: "activate";
+            click: "click";
+            select: "select";
+            scroll: "scroll";
+            wait: "wait";
+            press: "press";
+        }>;
+        label: z.ZodString;
+        node: z.ZodOptional<z.ZodNumber>;
+        role: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        current_value: z.ZodOptional<z.ZodString>;
+        checked: z.ZodOptional<z.ZodString>;
+        selected: z.ZodOptional<z.ZodString>;
+        expanded: z.ZodOptional<z.ZodString>;
+        look: z.ZodOptional<z.ZodEnum<{
+            link: "link";
+            widget: "widget";
+        }>>;
+        delta: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+            beside: "beside";
+        }>>;
+        region: z.ZodOptional<z.ZodObject<{
+            role: z.ZodString;
+            name: z.ZodString;
+            front: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        scroller: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    omitted_actions: z.ZodNumber;
+}, z.core.$strict>;
+
+declare type InteractionObservation_2 = z.infer<typeof InteractionObservation_2>;
 
 export declare interface InteractionObserved {
     /** The address of the target observed; absent when the default target has no address. */
@@ -1837,17 +2103,21 @@ export declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" |
 /** The interaction surfaces Bonsai itself ships, which plugins drive through `api.interaction`. */
 export declare type InteractionSurfaceName = "browser-pane" | "desktop";
 
+export declare type InteractionTarget = ReadonlyContract<InteractionTarget_2>;
+
 /**
- * One thing a driver can be pointed at. `id` is a driver-owned address, unique across every
- * driver in the session (prefix it with your scheme), that the agent passes back as `target`.
- * `active` marks the driver's default target.
+ * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
+ * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * `active` marks the default target (the page the user is looking at, the front app).
  */
-export declare interface InteractionTarget {
-    readonly id: string;
-    readonly title: string;
-    readonly url?: string;
-    readonly active: boolean;
-}
+declare const InteractionTarget_2: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    active: z.ZodBoolean;
+}, z.core.$strict>;
+
+declare type InteractionTarget_2 = z.infer<typeof InteractionTarget_2>;
 
 /** Creates an Interface using the given heritage and properties. */
 declare function Interface<Heritage extends TSchema[], Properties extends TProperties>(heritage: [...Heritage], properties: Properties, options?: TSchemaOptions): TInterface<Heritage, Properties>;
@@ -2803,8 +3073,11 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  * 0.54.0 adds named UI host grants for shared configuration/auth/account reads, retained connection
  * progress/dismissal and support. Built-in-only page capability scopes are removed; executable
  * pages declare capabilities on apps[].
+ *
+ * 0.54.1 adds manifest-declared plugin workers on both backend targets and exposes the canonical
+ * transcript placement and answer-stretch rules through the SDK.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.54.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.54.1";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -3094,6 +3367,8 @@ export declare interface KayAgentPluginApi {
      * {@link KayAppUserFiles}.
      */
     readonly userFiles: KayAppUserFiles;
+    /** Always present; only modules declared by this plugin may run. SDK 0.54.1. */
+    readonly workers: KayPluginWorkers;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link systemOne}: there is nothing to
@@ -3752,6 +4027,20 @@ export declare interface KayPluginSimulatorOptions {
     readonly stateRoot: string;
 }
 
+/** A declared module exports this function; input and output must be JSON values. */
+export declare interface KayPluginWorkerModule {
+    run(input: unknown): unknown | Promise<unknown>;
+}
+
+/** Run only this plugin's declared modules in a fresh child owned by its hosting process. */
+export declare interface KayPluginWorkers {
+    /** The host terminates the child on deadline, caller abort or plugin disposal. */
+    run<T = unknown>(workerId: string, input: unknown, options: {
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal;
+    }): Promise<T>;
+}
+
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 
@@ -5681,6 +5970,15 @@ export declare interface PluginUriWriteOptions extends PluginUriMutationOptions
     readonly writeSource?: UriSourceDescriptor;
 }
 
+/** A worker refusal or failure; the code is safe to record without its input or output. */
+export declare class PluginWorkerError extends Error {
+    readonly code: PluginWorkerErrorCode;
+    constructor(code: PluginWorkerErrorCode, message?: string);
+}
+
+/** Stable, content-free failure classes for a plugin worker request. */
+export declare type PluginWorkerErrorCode = "undeclared" | "invalid_module" | "invalid_input" | "input_too_large" | "output_too_large" | "timeout" | "aborted" | "spawn_failed" | "child_failed" | "invalid_output";
+
 /**
  * What a run did to a URI. The words match the automation run wire's artifact actions. When one
  * run both creates and updates a URI, the reader reports `created`.
@@ -5877,6 +6175,10 @@ declare function Readonly_2<Type extends TSchema>(type: Type): TAddReadonly<Type
 
 declare const Readonly_3: (input: string) => [unknown, string] | [];
 
+declare type ReadonlyContract<T> = T extends readonly (infer Item)[] ? readonly ReadonlyContract<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: ReadonlyContract<T[Key]>;
+} : T;
+
 declare type ReadonlyKeys<Properties extends TProperties, Result extends PropertyKey = {
     [Key in keyof Properties]: Properties[Key] extends TReadonly<TSchema> ? (Properties[Key] extends TOptional<Properties[Key]> ? never : Key) : never;
 }[keyof Properties]> = Result;

package/dist/kay-agent.js

@@ -1,3 +1,20 @@
+// packages/plugin-sdk/dist/workers.js
+var PluginWorkerError = class extends Error {
+  code;
+  constructor(code, message = `Plugin worker request failed: ${code}`) {
+    super(message);
+    this.code = code;
+    this.name = "PluginWorkerError";
+  }
+};
+function createUnavailablePluginWorkers() {
+  return {
+    async run() {
+      throw new PluginWorkerError("spawn_failed", "Plugin workers are not available on this host.");
+    }
+  };
+}
+
 // packages/herd-uri/dist/claims.js
 var SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
 var CAPTURE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -1742,6 +1759,7 @@ export {
   OSASCRIPT_ENVELOPE_JXA,
   OSASCRIPT_TIMEOUT_MS,
   PluginApiError,
+  PluginWorkerError,
   ProjectDirectory,
   ProjectDirectoryRequest,
   ProjectDirectoryResponse,
@@ -1770,6 +1788,7 @@ export {
   createUnavailableCompiler,
   createUnavailableEndpoints,
   createUnavailablePluginEndpointCaller,
+  createUnavailablePluginWorkers,
   createUnavailableUriCaller,
   declareProducedResources,
   defineAuthedTool,