@yaklabs-ai/plugin-sdk 0.13.10 → 0.14.1

package/dist/kay-agent.d.ts

@@ -696,17 +696,6 @@ export declare interface ConvertedArtifact {
  */
 declare function Create(hidden: ObjectLike_2, enumerable: ObjectLike_2, options?: ObjectLike_2): ObjectLike_2;
 
-/**
- * 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
- * wrapper's so a caller's `signal`/`deadlineAt` handling does not change with host composition.
- *
- * Deliberately here rather than in the runtime: this is the DEFAULT for the SDK's own host
- * factory, which cannot import the runtime uphill. The runtime also delegates fallback execution
- * here, so both paths share cancellation, deadline enforcement, and cleanup.
- */
-export declare function createFallbackOnlyWithJev(): WithJev;
-
 /**
  * Build a plugin's JSON API client. Carries **no credentials at construction** — every method
  * takes per-call `headers`, because the kernel resolves tokens per call (refresh-near-expiry,
@@ -1924,150 +1913,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;
 
-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 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>>;
-}
-
-/** 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 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 (`@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.
- */
-export declare type JevState = object;
-
-/** The route a Jev call took: the user's own TypeSafe key, or Bonsai's hosted gateway. */
-export declare type JevTransport = "direct" | "hosted";
-
 /** The frozen `createJsonApiClient` surface — see the module doc for why it stops at these three. */
 export declare interface JsonApiClient {
     getJson<TBody = unknown>(url: string, options?: PluginApiQueryOptions): Promise<PluginApiResponse<TBody>>;
@@ -2380,20 +2225,10 @@ export 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).
@@ -2416,7 +2251,7 @@ export 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;
@@ -3419,6 +3254,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -3513,6 +3349,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -3607,6 +3444,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -4442,9 +4280,10 @@ export declare interface OsascriptFailureAdvice {
 }
 
 /**
- * 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.
+ * The activation options every osascript plugin's agent factory accepted, so the daemon's
+ * simulator roster set each the same way. Absent `simulator`, the plugin is exactly the shipped one.
+ *
+ * @deprecated See {@link OsascriptSimulatorOptions}.
  */
 export declare interface OsascriptKayAgentOptions {
     readonly simulator?: OsascriptSimulatorOptions;
@@ -4481,6 +4320,10 @@ export declare interface OsascriptRunner {
     /**
      * 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.
+     *
+     * @deprecated A Bonsai daemon substitutes the runner itself, so a module uses
+     * {@link requireExternalCli} and `ctx.auth?.externalCli` directly. Kept so a plugin built against
+     * an earlier SDK keeps compiling.
      */
     readonly dispatch: (simulator: OsascriptSimulatedRunner | undefined) => OsascriptDispatch;
     /**
@@ -4526,7 +4369,11 @@ export declare interface OsascriptRunnerOptions {
     readonly appNotRunning?: OsascriptFailureAdvice;
 }
 
-/** A plugin's simulator, as the runner sees it: the runner one dispatch uses in the host's place. */
+/**
+ * A simulated runner, as a module sees it: the runner one dispatch uses in the host's place. A
+ * Bonsai daemon that simulates an osascript plugin hands `runnerFor(ctx)` to the module as
+ * `ctx.auth.externalCli`; `@bonsai/uri-simulator-kit/osascript` builds one.
+ */
 export declare interface OsascriptSimulatedRunner {
     readonly runnerFor: (ctx: UriResolveContext) => UriExternalCliRunner;
 }
@@ -4535,6 +4382,10 @@ export declare interface OsascriptSimulatedRunner {
  * 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.
+ *
+ * @deprecated A Bonsai daemon now hands the module a simulated runner as `ctx.auth.externalCli`,
+ * so a plugin needs no simulator option; no Bonsai plugin sets this. Kept so a plugin built against
+ * an earlier SDK keeps compiling.
  */
 export declare interface OsascriptSimulatorOptions {
     /** The directory holding the simulator's world; the daemon's process config names it. */
@@ -5086,7 +4937,7 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
-        slug: z.ZodLiteral<"jev.use">;
+        slug: z.ZodLiteral<"systemOne.use">;
         envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
@@ -11841,53 +11692,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.
- */
-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: 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. */
-export 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.js

@@ -797,80 +797,6 @@ function capability(spec) {
   return { ...spec };
 }
 
-// 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") {
-      throw new TypeError("withJev requires a `fallback` function as its second argument.");
-    }
-    const { signal, deadlineAt } = options;
-    if (deadlineAt !== void 0 && !Number.isFinite(deadlineAt)) {
-      throw new TypeError("withJev's `deadlineAt` must be a finite epoch-ms timestamp.");
-    }
-    const assertWithinBoundaries = () => {
-      if (signal?.aborted === true) {
-        throw signal.reason ?? new DOMException("Aborted", "AbortError");
-      }
-      if (deadlineAt !== void 0 && Date.now() >= deadlineAt) {
-        throw new Error("withJev's deadline has passed.");
-      }
-    };
-    assertWithinBoundaries();
-    let timer;
-    let onAbort;
-    const stopped = new Promise((_resolve, reject) => {
-      if (signal !== void 0) {
-        onAbort = () => reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
-        signal.addEventListener("abort", onAbort, { once: true });
-      }
-      if (deadlineAt !== void 0) {
-        const checkDeadline = () => {
-          const remaining = deadlineAt - Date.now();
-          if (remaining <= 0) {
-            reject(new Error("withJev's deadline has passed."));
-          } else {
-            timer = setTimeout(checkDeadline, Math.min(remaining, 2147483647));
-          }
-        };
-        checkDeadline();
-      }
-    });
-    try {
-      const result = await Promise.race([
-        Promise.resolve().then(() => {
-          assertWithinBoundaries();
-          return fallback();
-        }),
-        stopped
-      ]);
-      assertWithinBoundaries();
-      return result;
-    } catch (error) {
-      assertWithinBoundaries();
-      throw error;
-    } finally {
-      if (timer !== void 0)
-        clearTimeout(timer);
-      if (signal !== void 0 && onAbort !== void 0) {
-        signal.removeEventListener("abort", onAbort);
-      }
-    }
-  };
-}
-
 // packages/herd-uri-extensions/dist/limits.js
 var MAX_BYTES = 50 * 1024 * 1024;
 var MAX_OUTPUT_CHARS = 5e5;
@@ -1748,7 +1674,6 @@ var KayAgentWebSessionError = class extends Error {
 export {
   DelegatedRefreshRejectedError,
   INTERACTION_CREDENTIAL_GUARD,
-  JevCallError,
   KayAgentCapabilityError,
   KayAgentWebSessionError,
   OBSERVATION_MIME,
@@ -1774,7 +1699,6 @@ export {
   compileUriClaim,
   contentDigest,
   contentResult,
-  createFallbackOnlyWithJev,
   createJsonApiClient,
   createOsascriptRunner,
   declareProducedResources,