@yaklabs-ai/plugin-sdk 0.11.0 → 0.12.3

package/dist/kay-app.js

@@ -1,4 +1,17 @@
 // 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") {
@@ -114,6 +127,10 @@ function grammarProblem(input) {
     return field === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field}\` is missing or has the wrong type.`;
   }
   const { detector, source, questions } = shape.data;
+  const { state } = input;
+  if (typeof state !== "object" || state === null || Array.isArray(state)) {
+    return "`state` must be a JSON object.";
+  }
   if (!fits(detector.id, DETECTOR_ID)) {
     return "`detector.id` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
   }
@@ -316,6 +333,98 @@ var uriTextEditPayloadArms = z4.union([
   z4.array(oldNewEntry).min(1)
 ]);
 
+// packages/herd-uri/dist/line-selector.js
+var RAW_TOKEN = /^raw$/i;
+function parseRangeListToken(token) {
+  if (token.length === 0)
+    return void 0;
+  const ranges = [];
+  for (const part of token.split(",")) {
+    const range = parseSingleRange(part);
+    if (range === void 0)
+      return void 0;
+    ranges.push(range);
+  }
+  return ranges;
+}
+function toInt(value) {
+  if (!/^\d+$/.test(value))
+    return void 0;
+  const n = Number.parseInt(value, 10);
+  return Number.isSafeInteger(n) && n >= 1 ? n : void 0;
+}
+function parseSingleRange(part) {
+  const plus = part.indexOf("+");
+  if (plus >= 0) {
+    const start2 = toInt(part.slice(0, plus));
+    const count = toInt(part.slice(plus + 1));
+    if (start2 === void 0 || count === void 0)
+      return void 0;
+    return { start: start2, end: start2 + count - 1 };
+  }
+  const dash = part.indexOf("-");
+  if (dash >= 0) {
+    const start2 = toInt(part.slice(0, dash));
+    const endRaw = part.slice(dash + 1);
+    if (start2 === void 0)
+      return void 0;
+    if (endRaw.length === 0)
+      return { start: start2, end: Number.POSITIVE_INFINITY };
+    const end = toInt(endRaw);
+    if (end === void 0 || end < start2)
+      return void 0;
+    return { start: start2, end };
+  }
+  const start = toInt(part);
+  if (start === void 0)
+    return void 0;
+  return { start, end: Number.POSITIVE_INFINITY };
+}
+function mergeRanges(ranges) {
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    if (last !== void 0 && range.start <= last.end) {
+      if (range.end > last.end) {
+        merged[merged.length - 1] = { start: last.start, end: range.end };
+      }
+      continue;
+    }
+    merged.push(range);
+  }
+  return merged;
+}
+function parseLineSelector(input) {
+  let address = input;
+  let raw = false;
+  let ranges;
+  for (let i = 0; i < 2; i += 1) {
+    const colon = address.lastIndexOf(":");
+    if (colon < 0)
+      break;
+    const token = address.slice(colon + 1);
+    if (RAW_TOKEN.test(token)) {
+      if (raw)
+        break;
+      raw = true;
+      address = address.slice(0, colon);
+      continue;
+    }
+    const parsed = parseRangeListToken(token);
+    if (parsed === void 0)
+      break;
+    if (ranges !== void 0)
+      break;
+    ranges = parsed;
+    address = address.slice(0, colon);
+  }
+  return {
+    address,
+    selector: { ranges: ranges ? mergeRanges(ranges) : [], raw }
+  };
+}
+
 // packages/herd-uri/dist/schema/to-json-schema.js
 import { z as z5 } from "zod";
 function toJsonSchema(schema) {
@@ -359,6 +468,20 @@ function payload(name, schema, options = {}) {
   };
 }
 
+// packages/plugin-sdk/dist/kay-app/skills.js
+function createUnavailableSkills(message) {
+  const unavailable = {
+    status: "unavailable",
+    reason: "not-available",
+    message
+  };
+  return {
+    list: async () => unavailable,
+    read: async () => unavailable,
+    history: async () => unavailable
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/transcript-text.js
 function transcriptMessageTexts(entries) {
   return entries.flatMap((entry) => {
@@ -414,6 +537,7 @@ var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "delayed-occurrence"
 ];
 export {
+  JevCallError,
   KAY_APP_AUTOMATION_CONDITION_KINDS,
   KAY_APP_DATA_CHANGE_MAX_BYTES,
   KayAppWorkflowFailure,
@@ -426,8 +550,10 @@ export {
   UriValidationError,
   createFallbackOnlySignals,
   createFallbackOnlyWithJev,
+  createUnavailableSkills,
   invalidObservation,
   isRetryable,
+  parseLineSelector,
   payload,
   transcriptMessageText,
   transcriptMessageTexts,

package/dist/signals.d.ts

@@ -1,10 +1,3 @@
-import type { ChoiceResponse } from '@typesafe-ai/sdk';
-import type { NoulResponse } from '@typesafe-ai/sdk';
-import type { Questions } from '@typesafe-ai/sdk';
-import type { ScoreResponse } from '@typesafe-ai/sdk';
-
-export { ChoiceResponse }
-
 /**
  * The `signals` a host with no Jev lane or no signals store binds: `observe` never touches the
  * network, answers `invalid` for an input that breaks the recorded-name grammar exactly as a
@@ -24,6 +17,87 @@ export declare function createFallbackOnlySignals(): KayAppSignals;
  */
 export declare function invalidObservation(input: KayAppSignalsObserveInput): KayAppSignalObservation | undefined;
 
+declare type JevAnswer = JevBoolAnswer | JevChoiceAnswer | JevScoreAnswer;
+
+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. */
+declare interface JevBoolQuestion {
+    readonly type: "bool";
+    readonly instructions: string;
+    readonly criteria?: {
+        readonly true: string;
+        readonly false: string;
+    };
+}
+
+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. */
+declare interface JevChoiceQuestion<L extends string = string> {
+    readonly type: "choice";
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<L, string>>;
+}
+
+declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
+
+/** A rubric: questions keyed by the name each answer comes back under. */
+declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
+
+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. */
+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 (`@kay/agent-runtime`'s `kay/jev/`).
+ * ---
+ *
+ * The vocabulary is Kay'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.
+ */
+declare type JevState = object;
+
 /** One stored signal: the answers exactly as Jev gave them, and where the observed turn is. */
 export declare interface KayAppSignal {
     /** Recording order: a higher id was recorded later. */
@@ -34,7 +108,7 @@ export declare interface KayAppSignal {
     readonly source: KayAppSignalSource;
     readonly recordedAtMs: number;
     /** Keyed by question name, full probability distributions included. */
-    readonly answers: Readonly<Record<string, NoulResponse | ChoiceResponse | ScoreResponse>>;
+    readonly answers: Readonly<Record<string, KayAppSignalAnswer>>;
     /** The inference that produced the answers; absent when the host recorded only part of it. */
     readonly inference?: {
         readonly model: string;
@@ -46,6 +120,9 @@ export declare interface KayAppSignal {
     readonly inputDigest: string;
 }
 
+/** One stored answer: a {@link JevAnswer}, or a yes/no answer recorded before SDK 0.12.0. */
+export declare type KayAppSignalAnswer = JevAnswer | KayAppSignalNoulAnswer;
+
 /** One version of one detector, under one rubric, as the catalog lists it. */
 export declare interface KayAppSignalDetector {
     readonly pluginId: string;
@@ -56,16 +133,26 @@ export declare interface KayAppSignalDetector {
      * version mean the rubric was edited without a version bump.
      */
     readonly rubricDigest: string;
-    readonly questions: Questions;
+    readonly questions: Readonly<Record<string, KayAppSignalRubricQuestion>>;
     readonly firstRecordedAtMs: number;
     readonly lastRecordedAtMs: number;
 }
 
+/**
+ * A yes/no answer as rows recorded before SDK 0.12.0 carry it, in TypeSafe's vocabulary:
+ * `noul` is P(yes). Stored rows are never rewritten, so a reader still meets these.
+ */
+export declare interface KayAppSignalNoulAnswer {
+    readonly type: "noul";
+    readonly noul: number;
+}
+
 /**
  * The result of one observe call. `status` is the only field a caller must switch on:
  *
- * - `classified`: Jev answered; `answers`, `model`, and `usage` are the vendor's verbatim
- *   response, and `stored` says whether the row landed in the durable store.
+ * - `classified`: Jev answered; `answers` (one {@link JevAnswer} per question), `model`, and
+ *   `usage` are what the Jev call returned, and `stored` says whether the row landed in the
+ *   durable store.
  * - `unavailable`: Jev could not answer (no key, refused grant, timeout, vendor error, or a
  *   malformed response), or the host has no signals store at all (`reason: "no-store"`).
  *   `reason` names the host's classification; no row is written, so the same input can be
@@ -116,6 +203,18 @@ export declare interface KayAppSignalPage {
     readonly nextCursor?: string;
 }
 
+/**
+ * One question of a stored rubric, as the recording plugin wrote it. Rubrics recorded before
+ * SDK 0.12.0 use TypeSafe's vocabulary (`noul` for yes/no, and instructions or criteria that
+ * may be JSON rather than text), and a stored rubric is never rewritten, so only `type` is
+ * guaranteed.
+ */
+export declare interface KayAppSignalRubricQuestion {
+    readonly type: string;
+    readonly instructions?: unknown;
+    readonly criteria?: unknown;
+}
+
 /**
  * The plugin's signal door. `observe` runs the fused inference-and-record step; `list` and
  * `listDetectors` read recorded signals back. The plugin id is stamped by the host at the
@@ -238,16 +337,16 @@ export declare interface KayAppSignalsObserveInput {
      * transcript the source points at. So the projection must be a pure function of the
      * transcript and the detector version, or the row's evidence cannot be reproduced.
      */
-    readonly state: unknown;
+    readonly state: JevState;
     /**
-     * The typed questions to answer, as the vendor SDK accepts them. Stored once per digest. A
+     * The typed questions to answer. Stored once per digest. A
      * rubric asks 1 to 64 questions. Each name is an identifier (letters, digits, and `_`, not
      * starting with a digit), at most 64 characters, because a reader types it into a `where`
      * filter. A choice question offers at most {@link MAX_CHOICE_LABELS} labels, each 1 to 64
      * characters with no `,`, `@`, or control or invisible character (`\p{C}`), and no whitespace
      * but single spaces between words, so a reader can copy it back exactly from rendered text.
      */
-    readonly questions: Questions;
+    readonly questions: JevQuestions;
     readonly options?: WithJevOptions;
 }
 
@@ -332,10 +431,6 @@ export declare interface KayAppSignalsSessionQuery {
 /** The most labels a recorded choice question may offer, and so the most one filter names. */
 export declare const MAX_CHOICE_LABELS = 64;
 
-export { NoulResponse }
-
-export { ScoreResponse }
-
 /**
  * The largest epoch-millisecond time a `Date` can hold (about the year 275,760). A time outside
  * 0 to this bound has no date to show, so neither `observe` nor a read window accepts one.

package/dist/signals.js

@@ -53,6 +53,10 @@ function grammarProblem(input) {
     return field === "" ? "`observe` takes an object with `detector`, `source`, `state`, and `questions`." : `\`${field}\` is missing or has the wrong type.`;
   }
   const { detector, source, questions } = shape.data;
+  const { state } = input;
+  if (typeof state !== "object" || state === null || Array.isArray(state)) {
+    return "`state` must be a JSON object.";
+  }
   if (!fits(detector.id, DETECTOR_ID)) {
     return "`detector.id` must be a lowercase slug of at most 64 characters: a-z and 0-9 in words joined by single hyphens.";
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.11.0",
+  "version": "0.12.3",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -51,8 +51,7 @@
     "skills"
   ],
   "dependencies": {
-    "zod": "^4.0.0",
-    "@typesafe-ai/sdk": "0.6.0"
+    "zod": "^4.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",