@yaklabs-ai/plugin-sdk 0.13.7 → 0.13.9

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

@@ -203,6 +203,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;
@@ -504,6 +510,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;
+}
+
 /** Createsa  uni-directional Codec with Decode only. The Decode function is called on Value.Decode */
 declare function Decode<Type extends TSchema, Callback extends TDecodeCallback<StaticDecode<Type>, unknown>>(type: Type, callback: Callback): TCodec<Type, ReturnType<Callback>>;
 
@@ -597,6 +682,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] | [];
@@ -631,6 +718,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>;
 
@@ -808,9 +907,129 @@ 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;
@@ -827,10 +1046,12 @@ 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" | "events" | "time" | "userFiles" | "familyFolder">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "systemOne" | "events" | "time" | "userFiles" | "familyFolder">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
+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>;
 
@@ -1726,6 +1947,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
@@ -4284,6 +4514,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,
@@ -5340,6 +5640,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/kay-agent-testing.js

@@ -34,6 +34,68 @@ function readProducedResourceDeclarations(details) {
   return { kind: "declared", resources: claimed };
 }
 
+// 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-primitives/dist/is-object.js
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -169,6 +231,9 @@ function fauxKayAgentCapabilities() {
     // 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(),
     // Accepts and drops, like the registrations above: the real `publish` never throws, so a
     // rejecting double would fail tests for a reason production never has. A test asserting what
     // its plugin publishes overrides this handle after the spread.