@yaklabs-ai/plugin-sdk 0.13.10 → 0.14.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.10"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.14.0"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.13.10" },
+  "compatibility": { "sdk": "^0.14.0" },
   "targets": {
     "kay": {
       "agent": {

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.10",
+  "version": "0.14.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -1690,118 +1690,6 @@ declare function IsUnsafe(value: unknown): value is TUnsafe;
 /** Returns true if the given value is TVoid. */
 declare function IsVoid(value: unknown): value is TVoid;
 
-/** The answer shape one question gets back. */
-declare type JevAnswerFor<Q> = Q extends JevBoolQuestion ? JevBoolAnswer : Q extends JevChoiceQuestion<infer L> ? JevChoiceAnswer<L> : Q extends JevScoreQuestion ? JevScoreAnswer : never;
-
-declare interface JevBoolAnswer {
-    readonly type: "bool";
-    /** P(yes), from 0 to 1. */
-    readonly probability: number;
-}
-
-/** A yes/no question. `criteria` says what yes and what no mean; omit it to leave both open. */
-declare interface JevBoolQuestion {
-    readonly type: "bool";
-    readonly instructions: string;
-    readonly criteria?: {
-        readonly true: string;
-        readonly false: string;
-    };
-}
-
-declare interface JevChoiceAnswer<L extends string = string> {
-    readonly type: "choice";
-    readonly choice: L;
-    readonly confidence: number;
-    /** P(label) for every offered label. */
-    readonly probabilities: Readonly<Record<L, number>>;
-}
-
-/** A choice among labels. Each label maps to what it means; an empty string leaves it open. */
-declare interface JevChoiceQuestion<L extends string = string> {
-    readonly type: "choice";
-    readonly instructions: string;
-    readonly criteria: Readonly<Record<L, string>>;
-}
-
-/** One answered request: every asked question has an answer of its own kind. */
-declare interface JevClassification<Q extends JevQuestions = JevQuestions> {
-    /** The Jev model the host asked. */
-    readonly model: string;
-    readonly answers: {
-        readonly [K in keyof Q]: JevAnswerFor<Q[K]>;
-    };
-    /** Token counts, when the route reported them. */
-    readonly usage?: {
-        readonly inputTokens: number;
-        readonly outputTokens: number;
-    };
-}
-
-declare interface JevClassifyRequest<Q extends JevQuestions = JevQuestions> {
-    readonly state: JevState;
-    readonly questions: Q;
-}
-
-/**
- * The Jev client a `use` body receives. `classify` either resolves with an answer for every
- * asked question, each of its question's kind, or rejects with a {@link JevCallError}; it never
- * resolves with a partial or substituted answer.
- */
-declare interface JevClient {
-    classify<const Q extends JevQuestions>(request: JevClassifyRequest<Q>, options?: {
-        readonly signal?: AbortSignal;
-    }): Promise<JevClassification<Q>>;
-}
-
-declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
-
-/** A rubric: questions keyed by the name each answer comes back under. */
-declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
-
-declare interface JevScoreAnswer {
-    readonly type: "score";
-    /** The expected score, from 0 to the number of rungs minus one. */
-    readonly score: number;
-    readonly confidence: number;
-}
-
-/** A score over ordered rungs: the first criterion scores 0, the next 1, and so on. */
-declare interface JevScoreQuestion {
-    readonly type: "score";
-    readonly instructions: string;
-    readonly criteria: readonly string[];
-}
-
-/**
- * ---
- * responsibility: The plugin-facing CONTRACT for Jev typed-decision inference — the shape of
- *   `api.withJev` on both plugin SDK targets, the {@link JevClient} a `use` body receives, the
- *   question and answer vocabulary it speaks, and the fallback-only implementation a host
- *   without a Jev lane binds.
- * owns:
- *   - {@link WithJev}, {@link WithJevOptions}, {@link createFallbackOnlyWithJev}.
- *   - {@link JevClient}, the {@link JevQuestion} and {@link JevAnswer} vocabulary, and
- *     {@link JevCallError}.
- * does_not_own:
- *   - 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 (`@bonsai/agent-runtime`'s `kay/jev/`).
- * ---
- *
- * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
- * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
- * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
- * criterion is text, and the state is a JSON object.
- */
-/**
- * The state a rubric reads: a JSON object, never text or an array. Every value must survive
- * `JSON.stringify` unchanged (no functions or class instances), because it is sent as JSON.
- * Typed as `object` so a state declared as an interface fits without an index signature.
- */
-declare type JevState = object;
-
 declare type JsonPrimitive = string | number | boolean | null;
 
 declare type JsonSchema = Record<string, unknown>;
@@ -2023,20 +1911,10 @@ declare interface KayAgentPluginApi {
      * {@link KayAgentPluginApi.registerInteractionDriver} to make it drivable by the agent.
      */
     readonly interaction: KayAgentInteractionSurfaces;
-    /**
-     * Jev typed-decision inference, as an OPTIONAL accelerator with a REQUIRED fallback. Each call
-     * is checked against `jev.use` — but a refused grant or no usable Jev provider both
-     * produce the same outcome: your `fallback` runs.
-     *
-     * Always present, on every host. That is the point: with no absent state to feature-detect,
-     * there is no shape of code that reaches Jev without having written the baseline too. Do not
-     * guard it with `if (api.withJev !== undefined)`.
-     */
-    readonly withJev: WithJev;
     /**
      * System One: fast, cheap judgment calls (`decide`) and typed field extraction (`extract`) on
-     * small models (Jev, Clef, Clef Flash, Clairic). Each call is checked against `jev.use`; a call
-     * that cannot be served or is not permitted throws a `SystemOneError` whose `cause.kind` says
+     * small models (Jev, Clef, Clef Flash, Clairic). Each call is checked against `systemOne.use`; a
+     * call that cannot be served or is not permitted throws a `SystemOneError` whose `cause.kind` says
      * why, so put the feature's cheaper path in the call's own `catch`. Always present, on every
      * host; a host with no System One throws `not-served`. Types: `@bonsai/plugin-sdk/system-one`
      * (SDK 0.13.8).
@@ -2059,7 +1937,7 @@ declare interface KayAgentPluginApi {
     readonly userFiles: KayAppUserFiles;
     /**
      * 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 withJev}: there is nothing to
+     * user what the agent just did. Always present, like {@link systemOne}: there is nothing to
      * feature-detect, and a host that composed no events lane drops what is published.
      */
     readonly events: KayAgentEvents;
@@ -9604,53 +9482,6 @@ declare const WithElementList_0: (input: string, result?: unknown[]) => [unknown
 
 declare function WithElementListMapping(input: [unknown, unknown, unknown] | []): unknown;
 
-/**
- * Run `use` against a live Jev client, falling back to `fallback` whenever Jev cannot serve the
- * call. The wrapper exists so a feature can ASK for a typed decision without ever depending on
- * one: `fallback` is required, and it runs whenever no provider in the user's Jev provider
- * order holds a usable credential, the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
- * `use` declines by returning `undefined`. With valid options, this rejects on an explicit
- * `signal` abort, reaching `deadlineAt`, or `fallback` itself throwing.
- *
- * ALWAYS PRESENT on the plugin API, on every host. A host that composed no Jev lane binds
- * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
- * exactly how a fallback gets skipped.
- *
- * `jev` is a {@link JevClient} on the host's Jev model. It is valid only for the duration of
- * the callback: a reference retained past `use`'s scope is refused at the transport, and an
- * in-flight request is aborted when the call stops waiting.
- * The callback itself is ABANDONED, not interrupted — a host cannot stop arbitrary JavaScript
- * that is already running, so `use` must not perform side effects it would mind completing
- * unobserved. The same applies to a running fallback: abort/deadline stops waiting for it but
- * cannot interrupt its JavaScript.
- */
-declare type WithJev = <T>(
-/** Return `undefined` to decline (the fallback runs). A feature whose real result can itself be
- *  `undefined` should return `null` or its own wrapper type instead. */
-use: (jev: JevClient) => T | undefined | PromiseLike<T | undefined>, 
-/** Required. The behaviour the feature has without Jev. */
-fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;
-
-/** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
- *  budget when none is given, so the Jev branch is never unbounded. */
-declare interface WithJevOptions {
-    /**
-     * Explicit cancellation. Always propagates as a rejection; never substituted with `fallback`,
-     * because an aborted call means "stop", not "use the cheaper path".
-     */
-    readonly signal?: AbortSignal;
-    /** Bounds the Jev branch alone, measured from the call. */
-    readonly timeoutMs?: number;
-    /**
-     * Absolute epoch-ms hard deadline for the WHOLE call, `fallback` included. A deadline already
-     * passed rejects (like `signal`); one still ahead derives the Jev branch's budget from it and
-     * keeps a small reserve so `fallback` has a window to run.
-     */
-    readonly deadlineAt?: number;
-    /** Attribution slug for host usage accounting. Never sent to Jev. */
-    readonly purpose?: string;
-}
-
 declare function WithMapping(input: [unknown, unknown] | []): unknown;
 
 declare const WithNull: (input: string) => [unknown, string] | [];

package/dist/disclosure.js

@@ -834,7 +834,6 @@ var INERT_WHITEBOARD = {
     remove: inertResult
   })
 };
-var INERT_WITH_JEV = async (_use, fallback) => fallback();
 function createKayAgentProbeCapabilityHandles() {
   return {
     network: INERT_NETWORK,
@@ -845,7 +844,6 @@ function createKayAgentProbeCapabilityHandles() {
     interaction: unavailableInteractionSurfaces("Interaction surfaces are not available while a plugin is being probed."),
     interceptToolCall: () => {
     },
-    withJev: INERT_WITH_JEV,
     // Throws `not-served` at once, the outcome a plugin's own `catch` already handles.
     systemOne: createUnavailableSystemOneClient(),
     // Fire-and-forget on the real api too, so dropping is the inert shape: nothing to hang on.

package/dist/kay-agent-testing.d.ts

@@ -1046,7 +1046,7 @@ declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unkno
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
 /** The capability handles a `KayAgentPluginApi` always carries — authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "systemOne" | "events" | "time" | "userFiles" | "familyFolder">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "systemOne" | "events" | "time" | "userFiles" | "familyFolder">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -1607,118 +1607,6 @@ declare function IsUnsafe(value: unknown): value is TUnsafe;
 /** Returns true if the given value is TVoid. */
 declare function IsVoid(value: unknown): value is TVoid;
 
-/** The answer shape one question gets back. */
-declare type JevAnswerFor<Q> = Q extends JevBoolQuestion ? JevBoolAnswer : Q extends JevChoiceQuestion<infer L> ? JevChoiceAnswer<L> : Q extends JevScoreQuestion ? JevScoreAnswer : never;
-
-declare interface JevBoolAnswer {
-    readonly type: "bool";
-    /** P(yes), from 0 to 1. */
-    readonly probability: number;
-}
-
-/** A yes/no question. `criteria` says what yes and what no mean; omit it to leave both open. */
-declare interface JevBoolQuestion {
-    readonly type: "bool";
-    readonly instructions: string;
-    readonly criteria?: {
-        readonly true: string;
-        readonly false: string;
-    };
-}
-
-declare interface JevChoiceAnswer<L extends string = string> {
-    readonly type: "choice";
-    readonly choice: L;
-    readonly confidence: number;
-    /** P(label) for every offered label. */
-    readonly probabilities: Readonly<Record<L, number>>;
-}
-
-/** A choice among labels. Each label maps to what it means; an empty string leaves it open. */
-declare interface JevChoiceQuestion<L extends string = string> {
-    readonly type: "choice";
-    readonly instructions: string;
-    readonly criteria: Readonly<Record<L, string>>;
-}
-
-/** One answered request: every asked question has an answer of its own kind. */
-declare interface JevClassification<Q extends JevQuestions = JevQuestions> {
-    /** The Jev model the host asked. */
-    readonly model: string;
-    readonly answers: {
-        readonly [K in keyof Q]: JevAnswerFor<Q[K]>;
-    };
-    /** Token counts, when the route reported them. */
-    readonly usage?: {
-        readonly inputTokens: number;
-        readonly outputTokens: number;
-    };
-}
-
-declare interface JevClassifyRequest<Q extends JevQuestions = JevQuestions> {
-    readonly state: JevState;
-    readonly questions: Q;
-}
-
-/**
- * The Jev client a `use` body receives. `classify` either resolves with an answer for every
- * asked question, each of its question's kind, or rejects with a {@link JevCallError}; it never
- * resolves with a partial or substituted answer.
- */
-declare interface JevClient {
-    classify<const Q extends JevQuestions>(request: JevClassifyRequest<Q>, options?: {
-        readonly signal?: AbortSignal;
-    }): Promise<JevClassification<Q>>;
-}
-
-declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
-
-/** A rubric: questions keyed by the name each answer comes back under. */
-declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
-
-declare interface JevScoreAnswer {
-    readonly type: "score";
-    /** The expected score, from 0 to the number of rungs minus one. */
-    readonly score: number;
-    readonly confidence: number;
-}
-
-/** A score over ordered rungs: the first criterion scores 0, the next 1, and so on. */
-declare interface JevScoreQuestion {
-    readonly type: "score";
-    readonly instructions: string;
-    readonly criteria: readonly string[];
-}
-
-/**
- * ---
- * responsibility: The plugin-facing CONTRACT for Jev typed-decision inference — the shape of
- *   `api.withJev` on both plugin SDK targets, the {@link JevClient} a `use` body receives, the
- *   question and answer vocabulary it speaks, and the fallback-only implementation a host
- *   without a Jev lane binds.
- * owns:
- *   - {@link WithJev}, {@link WithJevOptions}, {@link createFallbackOnlyWithJev}.
- *   - {@link JevClient}, the {@link JevQuestion} and {@link JevAnswer} vocabulary, and
- *     {@link JevCallError}.
- * does_not_own:
- *   - 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 (`@bonsai/agent-runtime`'s `kay/jev/`).
- * ---
- *
- * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
- * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
- * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
- * criterion is text, and the state is a JSON object.
- */
-/**
- * The state a rubric reads: a JSON object, never text or an array. Every value must survive
- * `JSON.stringify` unchanged (no functions or class instances), because it is sent as JSON.
- * Typed as `object` so a state declared as an interface fits without an index signature.
- */
-declare type JevState = object;
-
 declare type JsonPrimitive = string | number | boolean | null;
 
 declare type JsonSchema = Record<string, unknown>;
@@ -1937,20 +1825,10 @@ declare interface KayAgentPluginApi {
      * {@link KayAgentPluginApi.registerInteractionDriver} to make it drivable by the agent.
      */
     readonly interaction: KayAgentInteractionSurfaces;
-    /**
-     * Jev typed-decision inference, as an OPTIONAL accelerator with a REQUIRED fallback. Each call
-     * is checked against `jev.use` — but a refused grant or no usable Jev provider both
-     * produce the same outcome: your `fallback` runs.
-     *
-     * Always present, on every host. That is the point: with no absent state to feature-detect,
-     * there is no shape of code that reaches Jev without having written the baseline too. Do not
-     * guard it with `if (api.withJev !== undefined)`.
-     */
-    readonly withJev: WithJev;
     /**
      * System One: fast, cheap judgment calls (`decide`) and typed field extraction (`extract`) on
-     * small models (Jev, Clef, Clef Flash, Clairic). Each call is checked against `jev.use`; a call
-     * that cannot be served or is not permitted throws a `SystemOneError` whose `cause.kind` says
+     * small models (Jev, Clef, Clef Flash, Clairic). Each call is checked against `systemOne.use`; a
+     * call that cannot be served or is not permitted throws a `SystemOneError` whose `cause.kind` says
      * why, so put the feature's cheaper path in the call's own `catch`. Always present, on every
      * host; a host with no System One throws `not-served`. Types: `@bonsai/plugin-sdk/system-one`
      * (SDK 0.13.8).
@@ -1973,7 +1851,7 @@ declare interface KayAgentPluginApi {
     readonly userFiles: KayAppUserFiles;
     /**
      * 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 withJev}: there is nothing to
+     * user what the agent just did. Always present, like {@link systemOne}: there is nothing to
      * feature-detect, and a host that composed no events lane drops what is published.
      */
     readonly events: KayAgentEvents;
@@ -9527,53 +9405,6 @@ declare const WithElementList_0: (input: string, result?: unknown[]) => [unknown
 
 declare function WithElementListMapping(input: [unknown, unknown, unknown] | []): unknown;
 
-/**
- * Run `use` against a live Jev client, falling back to `fallback` whenever Jev cannot serve the
- * call. The wrapper exists so a feature can ASK for a typed decision without ever depending on
- * one: `fallback` is required, and it runs whenever no provider in the user's Jev provider
- * order holds a usable credential, the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
- * `use` declines by returning `undefined`. With valid options, this rejects on an explicit
- * `signal` abort, reaching `deadlineAt`, or `fallback` itself throwing.
- *
- * ALWAYS PRESENT on the plugin API, on every host. A host that composed no Jev lane binds
- * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
- * exactly how a fallback gets skipped.
- *
- * `jev` is a {@link JevClient} on the host's Jev model. It is valid only for the duration of
- * the callback: a reference retained past `use`'s scope is refused at the transport, and an
- * in-flight request is aborted when the call stops waiting.
- * The callback itself is ABANDONED, not interrupted — a host cannot stop arbitrary JavaScript
- * that is already running, so `use` must not perform side effects it would mind completing
- * unobserved. The same applies to a running fallback: abort/deadline stops waiting for it but
- * cannot interrupt its JavaScript.
- */
-declare type WithJev = <T>(
-/** Return `undefined` to decline (the fallback runs). A feature whose real result can itself be
- *  `undefined` should return `null` or its own wrapper type instead. */
-use: (jev: JevClient) => T | undefined | PromiseLike<T | undefined>, 
-/** Required. The behaviour the feature has without Jev. */
-fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;
-
-/** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
- *  budget when none is given, so the Jev branch is never unbounded. */
-declare interface WithJevOptions {
-    /**
-     * Explicit cancellation. Always propagates as a rejection; never substituted with `fallback`,
-     * because an aborted call means "stop", not "use the cheaper path".
-     */
-    readonly signal?: AbortSignal;
-    /** Bounds the Jev branch alone, measured from the call. */
-    readonly timeoutMs?: number;
-    /**
-     * Absolute epoch-ms hard deadline for the WHOLE call, `fallback` included. A deadline already
-     * passed rejects (like `signal`); one still ahead derives the Jev branch's budget from it and
-     * keeps a small reserve so `fallback` has a window to run.
-     */
-    readonly deadlineAt?: number;
-    /** Attribution slug for host usage accounting. Never sent to Jev. */
-    readonly purpose?: string;
-}
-
 declare function WithMapping(input: [unknown, unknown] | []): unknown;
 
 declare const WithNull: (input: string) => [unknown, string] | [];

package/dist/kay-agent-testing.js

@@ -225,12 +225,6 @@ function fauxKayAgentCapabilities() {
     // surface as `{ ok: false }`, never a throw. A test driving one overrides this handle.
     interaction: { browserPane: UNWIRED_SURFACE, desktop: UNWIRED_SURFACE },
     interceptToolCall: () => void 0,
-    // The one handle that does NOT refuse on use. `withJev`'s contract is that it always produces
-    // the baseline, so a rejecting double would make a plugin's Jev path untestable and teach the
-    // wrong lesson besides: the fallback is the normal outcome, not an error. It reaches no
-    // client, no key, and no network, which is all a double here has to guarantee. A test that
-    // wants a real Jev answer overrides this handle after the spread, like any other.
-    withJev: async (_use, fallback) => fallback(),
     // Throws `not-served`, so the plugin's own `catch` runs. A test that wants answers overrides
     // this handle after the spread.
     systemOne: createUnavailableSystemOneClient(),