@yaklabs-ai/plugin-sdk 0.13.7 → 0.13.9

package/dist/kay-agent.d.ts

@@ -293,6 +293,12 @@ export declare type AuthBoundToolDefinition<TParams extends ToolParametersWire =
     readonly requiresAuth: RequiresAuth;
 };
 
+declare interface Availability {
+    readonly available: boolean;
+    readonly reason?: string;
+    readonly cause?: SystemOneFailureCause;
+}
+
 declare interface BackgroundTaskAdoptOptions {
     readonly preferredId?: string;
     readonly toolCallId?: string;
@@ -737,6 +743,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;
+}
+
 /**
  * Declare the URIs a tool call created or updated as a side effect, on the result it returns.
  *
@@ -901,6 +986,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] | [];
@@ -935,6 +1022,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>;
 
@@ -1112,9 +1211,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;
@@ -1125,6 +1344,8 @@ declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unkno
  */
 export declare function fenced(text: string): readonly string[];
 
+declare type ForecastInterval = "step" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+
 export declare function formatIsoDate(value?: string | number | Date): string;
 
 export declare function formatNumber(n: number): string;
@@ -2169,6 +2390,15 @@ export 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
@@ -6247,6 +6477,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,
@@ -7293,6 +7593,9 @@ declare type TExtractUnion<Left extends TSchema[], Right extends TSchema, Result
 
 export declare function textResult<TDetails = undefined>(text: string, details: TDetails): AgentToolResult<TDetails>;
 
+/** `[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);