@yaklabs-ai/plugin-sdk 0.54.0 → 0.54.1

package/dist/disclosure.d.ts

@@ -870,6 +870,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] | [];
@@ -1347,80 +1351,248 @@ declare interface InteractionActed {
 }
 
 /**
- * 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.
- */
-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";
-};
-
-/**
- * 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 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.
  */
-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;
-}
-
-/** The candidate kinds a driver may offer. */
-declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
+declare const InteractionAction: 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 = z.infer<typeof InteractionAction>;
 
 declare interface InteractionDriver {
     /** Unique in the session. `builtin:` is reserved for Bonsai's own drivers. */
@@ -1433,12 +1605,12 @@ declare interface InteractionDriver {
     /** Whether the driver can act at all right now (platform, grants, a live connection). */
     isAvailable(): Promise<boolean>;
     targets(): Promise<InteractionOutcome<{
-        readonly targets: readonly InteractionTarget[];
+        readonly targets: readonly ReadonlyInteractionTarget[];
     }>>;
     observe(target: string | undefined, options?: {
         readonly fullText?: boolean;
     }): Promise<InteractionOutcome<InteractionObserved>>;
-    act(target: string | undefined, action: InteractionAction): Promise<InteractionOutcome<InteractionActed>>;
+    act(target: string | undefined, action: ReadonlyInteractionAction): Promise<InteractionOutcome<InteractionActed>>;
     screenshot(target: string | undefined): Promise<InteractionOutcome<{
         readonly png: Uint8Array;
     }>>;
@@ -1471,21 +1643,56 @@ declare interface InteractionFailure {
     readonly message: string;
 }
 
-/** What a driver sees on one target. */
-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;
-}
+/** What a driver sees on one target: its address, title, text, and actionable candidates. */
+declare const InteractionObservation: 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 = z.infer<typeof InteractionObservation>;
 
 declare interface InteractionObserved {
     /** The address of the target observed; absent when the default target has no address. */
     readonly target?: string;
-    readonly observation: InteractionObservation;
+    readonly observation: ReadonlyInteractionObservation;
     /** Lines the engine shows the agent under the observation (where the target sits, siblings). */
     readonly notes?: readonly string[];
 }
@@ -1503,20 +1710,6 @@ declare type InteractionOutcome<T> = ({
     readonly ok: true;
 } & T) | InteractionFailure;
 
-/**
- * The part of a page or window an element sits in: the open dialog, menu, or sheet it belongs to,
- * else its landmark (navigation, main, a window). `front` marks the overlay covering the rest: a
- * modal dialog (or one held by a full-screen overlay), a sheet, or a floating menu, the last such
- * in the document; elements outside it
- * usually cannot be clicked while it is open. A docked or always-visible dialog or menu is a
- * region but never in front.
- */
-declare interface InteractionRegion {
-    readonly role: string;
-    readonly name: string;
-    readonly front?: boolean | undefined;
-}
-
 /**
  * One surface Bonsai ships, in the driver contract's own shape, so a plugin's driver is the surface
  * plus an identity: `{ id, label, kind, ...api.interaction.desktop }`. Each call is checked
@@ -1529,16 +1722,18 @@ declare interface InteractionRegion {
 declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targets" | "observe" | "act" | "screenshot" | "open">;
 
 /**
- * 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).
  */
-declare interface InteractionTarget {
-    readonly id: string;
-    readonly title: string;
-    readonly url?: string;
-    readonly active: boolean;
-}
+declare const InteractionTarget: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    active: z.ZodBoolean;
+}, z.core.$strict>;
+
+declare type InteractionTarget = z.infer<typeof InteractionTarget>;
 
 /** 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>;
@@ -2470,8 +2665,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"];
 
@@ -2730,6 +2928,8 @@ 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
@@ -3354,6 +3554,15 @@ declare const KayPluginProtocolVersion: z.ZodLiteral<"kay.plugin.v1">;
 
 declare type KayPluginProtocolVersion = z.infer<typeof KayPluginProtocolVersion>;
 
+/** Run only this plugin's declared modules in a fresh child owned by its hosting process. */
+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>;
 
@@ -4679,6 +4888,16 @@ 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 ReadonlyInteractionAction = DriverAction<InteractionAction>;
+
+declare type ReadonlyInteractionObservation = ReadonlyContract<InteractionObservation>;
+
+declare type ReadonlyInteractionTarget = ReadonlyContract<InteractionTarget>;
+
 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/disclosure.js

@@ -920,6 +920,7 @@ function createKayAgentProbeCapabilityHandles() {
     network: INERT_NETWORK,
     webSession: INERT_WEB_SESSION,
     process: INERT_PROCESS,
+    workers: { run: inertResult },
     compiler: { bundleBrowser: inertResult },
     whiteboard: INERT_WHITEBOARD,
     // Answers `unavailable` at once: a probe must never reach the user's browser or desktop.