@yaklabs-ai/plugin-sdk 0.13.7 → 0.13.9

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.7"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.9"
   }
 }
 ```
@@ -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.7" },
+  "compatibility": { "sdk": "^0.13.9" },
   "targets": {
     "kay": {
       "agent": {
@@ -128,11 +128,16 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@bonsai/plugin-sdk/agent-conversation` | How a session's agent-to-agent traffic groups into conversations, from 0.13.7   |
 | `@bonsai/plugin-sdk/app-data`           | The app-data size caps, on an entry with no other import, from 0.13.7           |
 | `@bonsai/plugin-sdk/vendored-mcp`       | The kit for a plugin built on a vendor's hosted MCP server, from 0.13.7         |
+| `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8    |
+| `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9   |
 
 A plugin that imports a subpath declares at least the version its row names (`^0.13.7` for the
-last four). `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
-vendor's MCP server itself is a separate host decision, and Bonsai currently makes it only for
-its own bundled plugins.
+four from 0.13.7, `^0.13.8` for `system-one`, `^0.13.9` for `zod`). `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
+vendor's MCP server itself is a separate host decision: Bonsai hosts it once a person approves
+the plugin's `mcp.host-server` grant for that server's name and URL. A server that needs an OAuth
+sign-in names one of the plugin's auth services in `authService`; that service must declare exactly
+one `delegated` scheme, which Bonsai uses to sign the person in to the server. Bonsai declares that
+scheme at runtime; the plugin's code must not declare it again.
 
 `kay-agent/host` is intentionally not published; it is Bonsai's own loading
 machinery, not an authoring API.

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.d.ts

@@ -249,6 +249,12 @@ declare interface AuthAccount {
     readonly needsReconnect?: boolean;
 }
 
+declare interface Availability {
+    readonly available: boolean;
+    readonly reason?: string;
+    readonly cause?: SystemOneFailureCause;
+}
+
 declare interface BackgroundTaskAdoptOptions {
     readonly preferredId?: string;
     readonly toolCallId?: string;
@@ -593,6 +599,85 @@ declare function CyclicOptions(type: TCyclic): TSchemaOptions;
 
 declare type CyclicStackLength<Stack extends unknown[], MaxLength extends number, Buffer extends unknown[] = []> = (Stack extends [infer Left, ...infer Right] ? Buffer['length'] extends MaxLength ? false : CyclicStackLength<Right, MaxLength, [...Buffer, Left]> : true);
 
+declare type DecideAnswerFor<Q> = Q extends DecideBoolQuestion ? DecideBoolAnswer : Q extends DecideChoiceQuestion<infer L> ? DecideChoiceAnswer<L> : Q extends DecideScoreQuestion ? DecideScoreAnswer : never;
+
+declare interface DecideBoolAnswer {
+    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 DecideBoolQuestion {
+    readonly type: "bool";
+    readonly instructions: DecideInstructions;
+    readonly criteria?: {
+        readonly true: string;
+        readonly false: string;
+    };
+}
+
+declare interface DecideChoiceAnswer<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 DecideChoiceQuestion<L extends string = string> {
+    readonly type: "choice";
+    readonly instructions: DecideInstructions;
+    readonly criteria: Readonly<Record<L, string>>;
+}
+
+/** What a question asks: text, or a JSON object the client sends as its JSON text. */
+declare type DecideInstructions = string | object;
+
+declare type DecideModelId = "jev" | "clef" | "clef-flash";
+
+declare type DecideQuestion = DecideBoolQuestion | DecideChoiceQuestion | DecideScoreQuestion;
+
+/** Questions keyed by the name each answer comes back under. */
+declare type DecideQuestions = Readonly<Record<string, DecideQuestion>>;
+
+declare interface DecideRequest<Q extends DecideQuestions = DecideQuestions> {
+    /** Defaults to `jev`. */
+    readonly model?: DecideModelId;
+    readonly state: DecideState;
+    readonly questions: Q;
+}
+
+declare interface DecideScoreAnswer {
+    readonly type: "score";
+    /** The expected level, from 0 to the number of levels minus one. */
+    readonly score: number;
+    readonly confidence: number;
+}
+
+/** A score over ordered levels: the first criterion scores 0, the next 1, and so on. */
+declare interface DecideScoreQuestion {
+    readonly type: "score";
+    readonly instructions: DecideInstructions;
+    readonly criteria: readonly string[];
+}
+
+/**
+ * What a decide call reads. A JSON value is sent as JSON; every value must survive
+ * `JSON.stringify` unchanged.
+ */
+declare type DecideState = string | object;
+
+/** Every asked question has an answer of its own kind. */
+declare interface Decision<Q extends DecideQuestions = DecideQuestions> {
+    readonly model: DecideModelId;
+    readonly answers: {
+        readonly [K in keyof Q]: DecideAnswerFor<Q[K]>;
+    };
+    readonly usage?: SystemOneTokenUsage;
+}
+
 /** One skill entry from a plugin's manifest (`targets.kay.agent.contributes.skills`). */
 export declare interface DeclaredSkillContribution {
     readonly localId: string;
@@ -714,6 +799,8 @@ declare const DollarSign = "$";
 
 declare const Dot = ".";
 
+declare type DurationUnit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+
 declare const Element: (input: string) => [unknown, string] | [];
 
 declare const ElementBase: (input: string) => [unknown, string] | [];
@@ -748,6 +835,18 @@ declare function Enum<Values extends TEnumValue[]>(values: readonly [...Values],
 /** Creates an Enum type from a TypeScript enum declaration. */
 declare function Enum<Enum extends TTypeScriptEnumLike>(value: Enum, options?: TSchemaOptions): TEnum<TTypeScriptEnumToEnumValues<Enum>>;
 
+declare interface EstimateDistribution<V> {
+    readonly value: V | null;
+    readonly mean?: V;
+    readonly median?: V;
+    readonly p10?: V;
+    readonly p90?: V;
+    /** P(value < min). */
+    readonly pBelow?: number;
+    /** P(value > max). */
+    readonly pAbove?: number;
+}
+
 /** Applies an Evaluate action to a type. */
 declare function Evaluate<Type extends TSchema>(type: Type, options?: TSchemaOptions): TEvaluate<Type>;
 
@@ -925,13 +1024,135 @@ declare interface ExtensionPaths {
 /** Applies an Extract action using the given types. */
 declare function Extract_2<Left extends TSchema, Right extends TSchema>(left: Left, right: Right, options?: TSchemaOptions): TExtract<Left, Right>;
 
+declare type ExtractAnswerFor<F> = F extends ExtractTextField ? ExtractValueAnswer<"text", string> : F extends ExtractNumberField ? ExtractValueAnswer<"number", number> : F extends ExtractDateTimeField ? ExtractValueAnswer<F["type"], string> : F extends ExtractDurationField ? ExtractValueAnswer<"duration", number> : F extends ExtractListField ? ExtractListAnswer<F["items"] extends "number" ? number : string> : F extends ExtractEstimateField ? ExtractEstimateAnswer<F["min"] extends string ? string : number> : F extends ExtractForecastField ? ExtractForecastAnswer : never;
+
+/** `date` answers are ISO dates, `time` ISO times, `datetime` ISO date-times. */
+declare interface ExtractDateTimeField extends ExtractFieldBase {
+    readonly type: "date" | "time" | "datetime";
+}
+
 /** Creates a deferred Extract action. */
 declare function ExtractDeferred<Left extends TSchema, Right extends TSchema>(left: Left, right: Right, options?: TSchemaOptions): TExtractDeferred<Left, Right>;
 
+declare interface ExtractDurationField extends ExtractFieldBase {
+    readonly type: "duration";
+    /** Seconds when omitted. */
+    readonly unit?: DurationUnit;
+    readonly integer?: boolean;
+    readonly decimals?: number;
+}
+
+declare interface ExtractEstimateAnswer<V = number | string> extends EstimateDistribution<V> {
+    readonly type: "estimate";
+}
+
+/** A distribution over one value. `min`/`max` are numbers, or ISO dates for a date estimate. */
+declare interface ExtractEstimateField extends ExtractFieldBase {
+    readonly type: "estimate";
+    readonly min: number | string;
+    readonly max: number | string;
+    /** Grid step: a positive number (days for a date estimate), `month` or `year`. */
+    readonly step?: number | "month" | "year";
+    readonly scale?: "linear" | "log";
+    readonly unit?: string;
+}
+
+declare type ExtractField = ExtractTextField | ExtractNumberField | ExtractDateTimeField | ExtractDurationField | ExtractListField | ExtractEstimateField | ExtractForecastField;
+
+declare interface ExtractFieldBase {
+    readonly instructions?: string;
+    /** P(null) above which the value is null. Clairic's default is 0.5. */
+    readonly nullThreshold?: number;
+}
+
+/** Fields keyed by name. A name matches `^[A-Za-z_][A-Za-z0-9_.\-]{0,63}$`. */
+declare type ExtractFields = Readonly<Record<string, ExtractField>>;
+
+declare interface ExtractForecastAnswer {
+    readonly type: "forecast";
+    /** One value per step; `null` when the state does not determine the forecast. */
+    readonly value: readonly number[] | null;
+    readonly steps: readonly EstimateDistribution<number>[];
+}
+
+/** One distribution per future step. */
+declare interface ExtractForecastField extends ExtractFieldBase {
+    readonly type: "forecast";
+    readonly min: number;
+    readonly max: number;
+    /** Number of steps, 1 to 64. */
+    readonly horizon: number;
+    readonly interval?: ForecastInterval;
+    readonly scale?: "linear" | "log";
+    readonly unit?: string;
+}
+
+declare interface Extraction<F extends ExtractFields = ExtractFields> {
+    readonly model: ExtractModelId;
+    readonly answers: {
+        readonly [K in keyof F]: ExtractAnswerFor<F[K]>;
+    };
+    /** The state was cut to fit the model's context. */
+    readonly truncated: boolean;
+    readonly usage?: SystemOneTokenUsage;
+}
+
+declare interface ExtractListAnswer<V> {
+    readonly type: "list";
+    readonly value: readonly V[] | null;
+    readonly confidence?: number;
+    /** One per item in `value`. */
+    readonly confidences?: readonly number[];
+    readonly spans?: readonly TextSpan[];
+}
+
+declare interface ExtractListField extends ExtractFieldBase {
+    readonly type: "list";
+    readonly items: "text" | "number" | "date";
+    readonly decimals?: number;
+}
+
+declare type ExtractModelId = "clairic";
+
+declare interface ExtractNumberField extends ExtractFieldBase {
+    readonly type: "number";
+    readonly unit?: string;
+    readonly integer?: boolean;
+    /** 0 to 6. */
+    readonly decimals?: number;
+}
+
+declare interface ExtractRequest<F extends ExtractFields = ExtractFields> {
+    readonly model: ExtractModelId;
+    /** Text only; JSON is not accepted. */
+    readonly state: string;
+    readonly fields: F;
+    /** ISO date that anchors dates written without a year. */
+    readonly referenceDate?: string;
+}
+
+declare interface ExtractTextField extends ExtractFieldBase {
+    readonly type: "text";
+}
+
+declare interface ExtractValueAnswer<T extends "text" | "number" | "date" | "time" | "datetime" | "duration", V> {
+    readonly type: T;
+    /** `null` when the state does not determine the value. */
+    readonly value: V | null;
+    /** The best candidate even when `value` is null. */
+    readonly guess?: V;
+    readonly confidence?: number;
+    readonly pNull?: number;
+    readonly span?: TextSpan;
+    readonly unit?: string;
+}
+
 declare const Factor: (input: string) => [unknown, string] | [];
 
 declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unknown]): unknown;
 
+declare type ForecastInterval = "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+
 /** Creates a Function type. */
 declare function _Function_<Parameters extends TSchema[], ReturnType extends TSchema>(parameters: [...Parameters], returnType: ReturnType, options?: TSchemaOptions): TFunction<Parameters, ReturnType>;
 
@@ -1812,6 +2033,15 @@ declare interface KayAgentPluginApi {
      * 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
+     * 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).
+     */
+    readonly systemOne: SystemOneClient;
     /**
      * The daemon's clock and the time zone the user is in, read together on each `snapshot()` call.
      * Always present and ungated: it confers no authority, since a plugin runs in the daemon's
@@ -4373,6 +4603,76 @@ declare const StringPattern = ".*";
 /** Creates a Symbol type. */
 declare function Symbol_2(options?: TSchemaOptions): TSymbol;
 
+declare interface SystemOneCallOptions {
+    readonly signal?: AbortSignal;
+    /** Bounds the whole call, retries included. */
+    readonly timeoutMs?: number;
+    /** What the call is for, carried to the host's usage accounting. Never sent to a provider. */
+    readonly purpose?: string;
+}
+
+declare interface SystemOneClient {
+    decide<const Q extends DecideQuestions>(request: DecideRequest<Q>, options?: SystemOneCallOptions): Promise<Decision<Q>>;
+    extract<const F extends ExtractFields>(request: ExtractRequest<F>, options?: SystemOneCallOptions): Promise<Extraction<F>>;
+    /** Whether some provider in the current order can serve `(kind, model)`. Never rejects. */
+    availability(kind: SystemOneKind, model?: SystemOneModelId): Promise<Availability>;
+}
+
+/**
+ * Why a call failed or a provider can't serve, as a closed set. Never prose, and never the
+ * vendor's body: bodies can echo the request's state.
+ */
+declare type SystemOneFailureCause = {
+    readonly kind: "no-credential";
+} | {
+    readonly kind: "credential-store";
+} | {
+    readonly kind: "not-served";
+} | {
+    readonly kind: "not-permitted";
+} | {
+    readonly kind: "unknown-model";
+} | {
+    readonly kind: "invalid-request";
+    readonly detail: string;
+} | {
+    readonly kind: "too-large";
+} | {
+    readonly kind: "http";
+    readonly status: number;
+} | {
+    readonly kind: "transport";
+} | {
+    readonly kind: "timeout";
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "invalid-answer";
+};
+
+/**
+ * ---
+ * responsibility: The data shapes of the System One surface: models, the decide and extract
+ *   vocabularies, providers, and the failure causes.
+ * owns:
+ *   - The caller-facing question, field, answer, and result types, in Bonsai's own words
+ *     (`bool` for yes/no, camelCase options). The vendors' words (`noul`, snake_case) appear
+ *     only in `wire.ts`.
+ *   - {@link SystemOneProvider}, the seam a transport implements.
+ * does_not_own:
+ *   - Which models exist (`models.ts`), how answers are checked (`wire.ts`), or how a provider is
+ *     picked (`system-one-client.ts`).
+ * ---
+ */
+declare type SystemOneKind = "decide" | "extract";
+
+declare type SystemOneModelId = DecideModelId | ExtractModelId;
+
+declare interface SystemOneTokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+
 declare namespace T {
     export {
         Codec,
@@ -5417,6 +5717,9 @@ declare type TExtractType<Left extends TSchema, Right extends TSchema, Check ext
 
 declare type TExtractUnion<Left extends TSchema[], Right extends TSchema, Result extends TSchema[] = []> = (Left extends [infer Head extends TSchema, ...infer Tail extends TSchema[]] ? TExtractUnion<Tail, Right, [...Result, ...TExtractType<Head, Right>]> : Result);
 
+/** `[start, end)` character offsets into the state. */
+declare type TextSpan = readonly [number, number];
+
 declare type TFactor<Input extends string> = (TKeyOf<Input> extends [infer _0, infer Input extends string] ? (TBase<Input> extends [infer _1, infer Input extends string] ? (TIndexArray<Input> extends [infer _2, infer Input extends string] ? (TExtends_2<Input> extends [infer _3, infer Input extends string] ? (TWith<Input> extends [infer _4, infer Input extends string] ? [[_0, _1, _2, _3, _4], Input] : []) : []) : []) : []) : []) extends [infer _0 extends [unknown, unknown, unknown, unknown, unknown], infer Input extends string] ? [S.TFactorMapping<_0>, Input] : [];
 
 declare type TFactorExtends<Type extends T.TSchema, Extends extends unknown[]> = (Extends extends [infer Right extends T.TSchema, infer True extends T.TSchema, infer False extends T.TSchema] ? S_2.TConditionalDeferred<Type, Right, True, False> : Type);

package/dist/disclosure.js

@@ -741,6 +741,68 @@ function unavailableInteractionSurfaces(message) {
   };
 }
 
+// packages/system-one/dist/errors.js
+var SystemOneError = class extends Error {
+  cause;
+  kind;
+  model;
+  /** The provider that failed; absent when no provider was tried. */
+  providerId;
+  constructor(init) {
+    super(describe(init));
+    this.name = "SystemOneError";
+    this.cause = init.cause;
+    this.kind = init.kind;
+    this.model = init.model;
+    this.providerId = init.providerId;
+  }
+};
+function describe(init) {
+  const where = init.providerId === void 0 ? "" : ` on provider ${init.providerId}`;
+  const detail = init.cause.kind === "http" ? ` (HTTP ${init.cause.status})` : init.cause.kind === "invalid-request" ? ` (${init.cause.detail})` : "";
+  return `System One ${init.kind} on ${init.model}${where} failed: ${init.cause.kind}${detail}.`;
+}
+
+// packages/system-one/dist/models.js
+var DEFAULT_DECIDE_MODEL = "jev";
+var SYSTEM_ONE_LIMITS = {
+  /** The serialized request body, in bytes. */
+  maxBodyBytes: 64 * 1024,
+  maxQuestions: 64,
+  maxFields: 32,
+  minChoiceOptions: 2,
+  maxChoiceOptions: 255,
+  minScoreLevels: 2,
+  maxScoreLevels: 10,
+  maxForecastHorizon: 64
+};
+
+// packages/system-one/dist/unavailable.js
+var NOT_SERVED = {
+  available: false,
+  reason: "This host has no System One models.",
+  cause: { kind: "not-served" }
+};
+function createUnavailableSystemOneClient() {
+  return {
+    decide(request) {
+      return Promise.reject(new SystemOneError({
+        kind: "decide",
+        model: request.model ?? DEFAULT_DECIDE_MODEL,
+        cause: { kind: "not-served" }
+      }));
+    },
+    extract(request) {
+      return Promise.reject(new SystemOneError({
+        kind: "extract",
+        model: request.model,
+        cause: { kind: "not-served" }
+      }));
+    },
+    availability: () => Promise.resolve(NOT_SERVED)
+  };
+}
+
 // packages/plugin-sdk/dist/disclosure/probe-kay-agent-capabilities.js
 var inertResult = () => new Promise(() => {
 });
@@ -784,6 +846,8 @@ function createKayAgentProbeCapabilityHandles() {
     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.
     events: { publish: () => {
     } },