@yaklabs-ai/plugin-sdk 0.11.0 → 0.12.2

package/dist/disclosure.js

@@ -730,12 +730,33 @@ async function auditSkillCodegenPairFile(skill, declaration, packageDir) {
   return violations;
 }
 
+// packages/plugin-sdk/dist/kay-agent/interaction.js
+function unavailableInteractionSurface(message) {
+  const refused = async () => ({ ok: false, reason: "unavailable", message });
+  return {
+    isAvailable: async () => false,
+    targets: refused,
+    observe: refused,
+    act: refused,
+    screenshot: refused,
+    open: refused
+  };
+}
+function unavailableInteractionSurfaces(message) {
+  return {
+    browserPane: unavailableInteractionSurface(message),
+    desktop: unavailableInteractionSurface(message)
+  };
+}
+
 // packages/plugin-sdk/dist/disclosure/probe-kay-agent-capabilities.js
 var inertResult = () => new Promise(() => {
 });
 var INERT_FILESYSTEM = {
   readText: inertResult,
   writeText: inertResult,
+  readBytes: inertResult,
+  writeBytes: inertResult,
   mkdir: inertResult,
   readDir: inertResult,
   stat: inertResult,
@@ -778,6 +799,8 @@ function createKayAgentProbeCapabilityHandles() {
     webSession: INERT_WEB_SESSION,
     process: INERT_PROCESS,
     whiteboard: INERT_WHITEBOARD,
+    // Answers `unavailable` at once: a probe must never reach the user's browser or desktop.
+    interaction: unavailableInteractionSurfaces("Interaction surfaces are not available while a plugin is being probed."),
     interceptToolCall: () => {
     },
     withJev: INERT_WITH_JEV,
@@ -801,6 +824,8 @@ function collectUriModulesFromKayAgentActivate(activate) {
     },
     registerSearchProvider: () => {
     },
+    registerInteractionDriver: () => {
+    },
     registerConverter: () => {
     },
     auth: {
@@ -838,6 +863,8 @@ function collectAuthDeclarationsFromKayAgentActivate(activate) {
     },
     registerSearchProvider: () => {
     },
+    registerInteractionDriver: () => {
+    },
     registerConverter: () => {
     },
     auth: {

package/dist/jev.d.ts

@@ -1,9 +1,3 @@
-import { Questions } from '@typesafe-ai/sdk';
-import { SystemOneRequest } from '@typesafe-ai/sdk';
-import { SystemOneResult } from '@typesafe-ai/sdk';
-import { TypeSafeClient } from '@typesafe-ai/sdk';
-import { Usage } from '@typesafe-ai/sdk';
-
 /**
  * The `withJev` a host with no Jev lane binds: `use` is never called, no client is ever built,
  * and no network is ever touched. It keeps the cancellation contract identical to the real
@@ -15,21 +9,155 @@ import { Usage } from '@typesafe-ai/sdk';
  */
 export declare function createFallbackOnlyWithJev(): WithJev;
 
-export { Questions }
+export declare type JevAnswer = JevBoolAnswer | JevChoiceAnswer | JevScoreAnswer;
+
+/** The answer shape one question gets back. */
+export declare type JevAnswerFor<Q> = Q extends JevBoolQuestion ? JevBoolAnswer : Q extends JevChoiceQuestion<infer L> ? JevChoiceAnswer<L> : Q extends JevScoreQuestion ? JevScoreAnswer : never;
+
+export 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. */
+export declare interface JevBoolQuestion {
+    readonly type: "bool";
+    readonly instructions: string;
+    readonly criteria?: {
+        readonly true: string;
+        readonly false: string;
+    };
+}
+
+/**
+ * The one error `classify` rejects with. It carries a classification, never the provider's own
+ * message or body: those can echo the request state, and this error reaches logs.
+ */
+export declare class JevCallError extends Error {
+    readonly transport: JevTransport;
+    readonly kind: JevCallErrorKind;
+    /** The final attempt's HTTP status, when a response arrived. */
+    readonly status: number | undefined;
+    constructor(init: {
+        readonly transport: JevTransport;
+        readonly kind: JevCallErrorKind;
+        readonly status?: number | undefined;
+    });
+}
+
+/**
+ * Why a Jev call failed, as a closed set:
+ *
+ * - `http`: the route answered with an error status (`status` says which).
+ * - `too-large`: the route refused the request's size (413, or a 400 naming the token limit).
+ * - `network`: no response arrived.
+ * - `aborted`: the call was cancelled.
+ * - `invalid-answer`: the route answered, but not with an answer for every asked question.
+ */
+export declare type JevCallErrorKind = "http" | "too-large" | "network" | "aborted" | "invalid-answer";
 
-export { SystemOneRequest }
+export 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. */
+export declare interface JevChoiceQuestion<L extends string = string> {
+    readonly type: "choice";
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<L, string>>;
+}
 
-export { SystemOneResult }
+/** One answered request: every asked question has an answer of its own kind. */
+export 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;
+    };
+}
 
-export { TypeSafeClient }
+export 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.
+ */
+export declare interface JevClient {
+    classify<const Q extends JevQuestions>(request: JevClassifyRequest<Q>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<JevClassification<Q>>;
+}
+
+export declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
+
+/** A rubric: questions keyed by the name each answer comes back under. */
+export declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
+
+export 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. */
+export 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 (`@kay/agent-runtime`'s `kay/jev/`).
+ * ---
+ *
+ * The vocabulary is Kay'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.
+ */
+export declare type JevState = object;
 
-export { Usage }
+/** The route a Jev call took: the user's own TypeSafe key, or Bonsai's hosted gateway. */
+export declare type JevTransport = "direct" | "hosted";
 
 /**
  * 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 host-managed key is saved,
- * the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
+ * 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.
  *
@@ -37,10 +165,9 @@ export { Usage }
  * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
  * exactly how a fallback gets skipped.
  *
- * `jev` is the vendor's own `TypeSafeClient`, configured with the host's default model and base
- * URL. Native `request.model` overrides remain supported. 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.
+ * `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
@@ -49,7 +176,7 @@ export { Usage }
 export 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: TypeSafeClient) => T | undefined | PromiseLike<T | undefined>, 
+use: (jev: JevClient) => T | undefined | PromiseLike<T | undefined>, 
 /** Required. The behaviour the feature has without Jev. */
 fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;
 

package/dist/jev.js

@@ -1,4 +1,17 @@
 // packages/plugin-sdk/dist/jev.js
+var JevCallError = class extends Error {
+  transport;
+  kind;
+  /** The final attempt's HTTP status, when a response arrived. */
+  status;
+  constructor(init) {
+    super(`Jev call failed on the ${init.transport} route: ${init.kind}${init.status === void 0 ? "" : ` (HTTP ${init.status})`}.`);
+    this.name = "JevCallError";
+    this.transport = init.transport;
+    this.kind = init.kind;
+    this.status = init.status;
+  }
+};
 function createFallbackOnlyWithJev() {
   return async (_use, fallback, options = {}) => {
     if (typeof fallback !== "function") {
@@ -59,5 +72,6 @@ function createFallbackOnlyWithJev() {
   };
 }
 export {
+  JevCallError,
   createFallbackOnlyWithJev
 };