@yaklabs-ai/plugin-sdk 0.13.7 → 0.13.9

package/dist/kay-app.d.ts

@@ -248,6 +248,12 @@ declare interface AuthAccount {
     readonly needsReconnect?: boolean;
 }
 
+declare interface Availability {
+    readonly available: boolean;
+    readonly reason?: string;
+    readonly cause?: SystemOneFailureCause;
+}
+
 /**
  * The availability-facts message: who the user is connected as, which auth-gated tools are
  * waiting on a connect, and which installed plugins are not connected. DURABLE and never
@@ -810,6 +816,85 @@ declare type DaemonServiceTurnMessage = CustomMessage<DaemonServiceTurnDetails>
     readonly display: 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>>;
 
@@ -887,6 +972,8 @@ declare interface DroppedContribution {
     readonly reason: "timeout" | "error";
 }
 
+declare type DurationUnit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+
 /**
  * The Dynamic Context message: retrieval-produced context delivered right after human
  * text enters the conversation (prompt, steer, or a drained follow-up batch — one
@@ -989,6 +1076,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>;
 
@@ -1166,13 +1265,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>;
 
@@ -1848,7 +2069,7 @@ declare interface KayAgentWhiteboardUpdateInput {
 }
 
 /**
- * The signed-in Bonsai account. Always present on {@link KayAppPluginApi}.
+ * The signed-in Bonsai account. Always present on `KayAppPluginApi`.
  *
  * Reading the profile is ungated: it exposes the signed-in user's own identity to a plugin they
  * explicitly enabled. The two stronger operations are separate claims, checked per call —
@@ -1907,7 +2128,7 @@ export declare interface KayAppAccount {
      * `profile`/`assertResult`, compare against the last-seen identity, and act only on a
      * real move (kay#8553 is the looping-reconnect bug the looser reading licensed). A gate
      * that re-registers account-scoped sources must also act when a registration reports
-     * {@link KayAppDataSourceRegistration.isRetired}: the host's identity change is not always
+     * `KayAppDataSourceRegistration.isRetired`: the host's identity change is not always
      * one `profile` shows, and a gate reading only the identity leaves the source retired.
      */
     subscribe(listener: () => void): () => void;
@@ -1995,6 +2216,11 @@ export declare type KayAppAccountAssertionResult = {
     readonly status: "signed-out";
 };
 
+/**
+ * The plugin-facing `kay.app` account contract (`app.account`): who is signed in to Bonsai, a
+ * verifiable assertion of that identity, why one is unavailable, and the profile update. Changes to
+ * this contract belong in this module.
+ */
 /**
  * Who is signed in to Bonsai. Metadata only — this carries no secret and cannot be presented to
  * anyone as proof. Derived from the Bonsai product-account record's stored identity.
@@ -2963,7 +3189,7 @@ export declare interface KayAppContextContributor {
 
 /**
  * Raw read access to every stored session's transcript. Always present on
- * {@link KayAppPluginApi}; each read is checked against the `corpus.read` claim, and refused
+ * `KayAppPluginApi`; each read is checked against the `corpus.read` claim, and refused
  * unless the user has granted it. Data is raw and un-redacted — the plugin filters to what it
  * needs. Invocation queries are bounded pages. Transcript reads materialize a whole session
  * before yielding; the iterable does not promise per-entry streaming or an allocation bound.
@@ -3194,6 +3420,11 @@ export declare type KayAppDataSourceSnapshot = {
     readonly reason?: KayAppDataUnavailableReason;
 };
 
+/**
+ * The plugin-facing `kay.app` app-data contract (`app.data`): registering the live definitions
+ * behind manifest-declared data sources, app-wide or per session, and the closed reasons a source
+ * reports no data. Changes to this contract belong in this module.
+ */
 /**
  * Why a source has no data right now — a CLOSED classification, never a message.
  *
@@ -3823,6 +4054,14 @@ export declare interface KayAppPluginApi {
      * `if (app.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. Types: `@bonsai/plugin-sdk/system-one` (SDK 0.13.8).
+     */
+    readonly systemOne: SystemOneClient;
     /**
      * Recorded Jev signals. `observe` runs a Jev inference and records the answer as a durable,
      * provenance-stamped row; each call is checked against `jev.use`, and a refused grant, no
@@ -3874,7 +4113,7 @@ export declare interface KayAppPluginApi {
     /**
      * Register a session tool this plugin's manifest declares under
      * `targets.kay.app.contributes.tools`. Injected into every session under the declared
-     * `toolName`; each call's {@link KayAppToolContext} is host-stamped with the calling session.
+     * `toolName`; each call's `KayAppToolContext` is host-stamped with the calling session.
      * Registering an undeclared `localId`, or one twice, throws and disables the plugin —
      * fail-closed at activation, exactly like {@link registerUriModule}.
      */
@@ -4391,8 +4630,8 @@ export declare interface KayAppSessionRunInput {
     readonly activeToolNames?: readonly KayAppSessionRunHostToolName[] | undefined;
     /**
      * The run's model, as either an exact pin (a provider-qualified reference from
-     * {@link KayAppModels.list}) or a tier word (`small`/`medium`/`large`/`ultra` —
-     * see {@link KayAppModels.listTiers}); absent, the daemon resolves
+     * `KayAppModels.list`) or a tier word (`small`/`medium`/`large`/`ultra` —
+     * see `KayAppModels.listTiers`); absent, the daemon resolves
      * the configured default. A tier word resolves through the same chokepoint every
      * other tier selection does — the daemon picks the concrete model, never the
      * plugin. An unavailable pin fails the run rather than silently substituting.
@@ -5153,6 +5392,11 @@ export declare interface KayAppStorage {
     readonly dataDir?: KayAppDataDirStorage;
 }
 
+/**
+ * The plugin-facing `kay.app` models contract (`app.models`): the plugin-safe model catalog and
+ * tiers, image-model resolution, the direct-completion broker, and the reasoning-effort ladder that
+ * sessions and completions share. Changes to this contract belong in this module.
+ */
 /** Bonsai's reasoning-effort ladder, in ascending order. */
 export declare type KayAppThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
@@ -5244,7 +5488,7 @@ export declare interface KayAppToolContext {
 
 /**
  * A session tool a `kay.app` plugin implements — the tool counterpart of an app-scoped
- * {@link UriModule}: registered once at activation, injected into every session. The kernel
+ * `UriModule`: registered once at activation, injected into every session. The kernel
  * `ToolDefinition` shape minus `name` (the host stamps the manifest-declared `toolName`; a
  * plugin never names its own model-facing tool at registration) and minus `requiresAuth`
  * (extension-auth binding is a `kay.agent` seam; an app tool acts through its granted app
@@ -5991,6 +6235,12 @@ export declare interface KayAppWorkspaceExecuteContext {
     readonly sessionId: string;
 }
 
+/**
+ * The plugin-facing `kay.app` workspace contract (`app.workspace`): the desktop workspace snapshot
+ * and the arrangement commands a plugin may run. This package does not import
+ * `@bonsai/agent-runtime-protocol`, so these types are JSON-safe, hand-copied twins of that
+ * package's workspace shapes. Changes to this contract belong in this module.
+ */
 /**
  * What one pane item shows. A JSON-safe, hand-copied twin of `WorkspacePaneContent` in
  * `@bonsai/agent-runtime-protocol` — this package cannot import that protocol package (see this
@@ -8361,6 +8611,76 @@ declare interface SystemMessage {
     timestamp: number;
 }
 
+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,
@@ -9418,6 +9738,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-app.js

@@ -506,6 +506,19 @@ function payload(name, schema, options = {}) {
   };
 }
 
+// packages/plugin-sdk/dist/kay-app/account.js
+function isRetryable(result) {
+  return result.status === "not-ready";
+}
+
+// packages/plugin-sdk/dist/kay-app/automations.js
+var KAY_APP_AUTOMATION_CONDITION_KINDS = [
+  "time",
+  "uri-change",
+  "occurrence",
+  "delayed-occurrence"
+];
+
 // packages/plugin-sdk/dist/kay-app/skills.js
 function createUnavailableSkills(message) {
   const unavailable = {
@@ -577,17 +590,6 @@ var KAY_APP_DATA_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
 var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
 var KAY_APP_DATA_READ_REQUEST_MAX_BYTES = 64 * 1024;
 var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
-
-// packages/plugin-sdk/dist/kay-app/index.js
-function isRetryable(result) {
-  return result.status === "not-ready";
-}
-var KAY_APP_AUTOMATION_CONDITION_KINDS = [
-  "time",
-  "uri-change",
-  "occurrence",
-  "delayed-occurrence"
-];
 export {
   JevCallError,
   JsonSchema,