@yaklabs-ai/plugin-sdk 0.8.4

package/dist/kay-app.js

@@ -0,0 +1,424 @@
+// packages/plugin-sdk/dist/jev.js
+function createFallbackOnlyWithJev() {
+  return async (_use, fallback, options = {}) => {
+    if (typeof fallback !== "function") {
+      throw new TypeError("withJev requires a `fallback` function as its second argument.");
+    }
+    const { signal, deadlineAt } = options;
+    if (deadlineAt !== void 0 && !Number.isFinite(deadlineAt)) {
+      throw new TypeError("withJev's `deadlineAt` must be a finite epoch-ms timestamp.");
+    }
+    const assertWithinBoundaries = () => {
+      if (signal?.aborted === true) {
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+      }
+      if (deadlineAt !== void 0 && Date.now() >= deadlineAt) {
+        throw new Error("withJev's deadline has passed.");
+      }
+    };
+    assertWithinBoundaries();
+    let timer;
+    let onAbort;
+    const stopped = new Promise((_resolve, reject) => {
+      if (signal !== void 0) {
+        onAbort = () => reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      if (deadlineAt !== void 0) {
+        const checkDeadline = () => {
+          const remaining = deadlineAt - Date.now();
+          if (remaining <= 0) {
+            reject(new Error("withJev's deadline has passed."));
+          } else {
+            timer = setTimeout(checkDeadline, Math.min(remaining, 2147483647));
+          }
+        };
+        checkDeadline();
+      }
+    });
+    try {
+      const result = await Promise.race([
+        Promise.resolve().then(() => {
+          assertWithinBoundaries();
+          return fallback();
+        }),
+        stopped
+      ]);
+      assertWithinBoundaries();
+      return result;
+    } catch (error) {
+      assertWithinBoundaries();
+      throw error;
+    } finally {
+      if (timer !== void 0)
+        clearTimeout(timer);
+      if (signal !== void 0 && onAbort !== void 0) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+
+// packages/plugin-sdk/dist/signals.js
+import { z } from "zod";
+function createFallbackOnlySignals() {
+  const noStore = { status: "unavailable", reason: "no-store" };
+  return {
+    observe: (input) => Promise.resolve(invalidObservation(input) ?? {
+      status: "unavailable",
+      reason: "no-jev-lane",
+      detector: { ...input.detector, rubricDigest: "" },
+      source: input.source,
+      stored: false,
+      deduplicated: false,
+      inputDigest: "",
+      recordedAtMs: Date.now()
+    }),
+    listDetectors: () => Promise.resolve(noStore),
+    list: () => Promise.resolve(noStore)
+  };
+}
+var SIGNAL_TIME_MAX_MS = 864e13;
+var MAX_CHOICE_LABELS = 64;
+var MAX_NAME = 64;
+var MAX_POINTER = 256;
+var MAX_QUESTIONS = 64;
+var DETECTOR_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+var VERSION = /^[A-Za-z0-9]+(?:[._-][A-Za-z0-9]+)*$/u;
+var QUESTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+var POINTER = /^[^\s\p{C}/?#]+$/u;
+var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
+var RUN_ID = /^\P{Cc}+$/u;
+var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
+var ObserveShape = z.looseObject({
+  detector: z.looseObject({ id: z.string(), version: z.string() }),
+  source: z.looseObject({
+    sessionId: z.string(),
+    entryId: z.string(),
+    openerEntryId: z.string().optional(),
+    runId: z.string().optional(),
+    occurredAtMs: z.unknown().optional()
+  }),
+  questions: z.record(z.string(), z.unknown())
+});
+var ChoiceQuestion = z.looseObject({
+  type: z.literal("choice"),
+  criteria: z.record(z.string(), z.unknown())
+});
+var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
+var quoted = (value) => JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}\u2026` : value).replace(/(?! )[\s\p{C}]/gu, (char) => `\\u${char.codePointAt(0).toString(16).padStart(4, "0")}`);
+function grammarProblem(input) {
+  const shape = ObserveShape.safeParse(input);
+  if (!shape.success) {
+    const field = shape.error.issues[0]?.path.join(".") ?? "";
+    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;
+  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.";
+  }
+  if (!fits(detector.version, VERSION)) {
+    return "`detector.version` must be at most 64 characters: letters and digits in parts joined by single `.`, `-`, or `_`.";
+  }
+  for (const [field, grammar, rule] of [
+    ["sessionId", POINTER, POINTER_RULE],
+    ["entryId", POINTER, POINTER_RULE],
+    ["openerEntryId", POINTER, POINTER_RULE],
+    [
+      "runId",
+      RUN_ID,
+      `1 to ${MAX_POINTER} characters with no control character`
+    ]
+  ]) {
+    const id = source[field];
+    if (id !== void 0 && !(id.length <= MAX_POINTER && grammar.test(id))) {
+      return `\`source.${field}\` must be ${rule}.`;
+    }
+  }
+  const occurredAtMs = source.occurredAtMs;
+  if (occurredAtMs !== void 0 && !(typeof occurredAtMs === "number" && Number.isSafeInteger(occurredAtMs) && occurredAtMs >= 0 && occurredAtMs <= SIGNAL_TIME_MAX_MS)) {
+    return `\`source.occurredAtMs\` must be whole epoch milliseconds from 0 to ${SIGNAL_TIME_MAX_MS}.`;
+  }
+  const names = Object.keys(questions);
+  if (names.length === 0 || names.length > MAX_QUESTIONS) {
+    return `\`questions\` must ask 1 to ${MAX_QUESTIONS} questions.`;
+  }
+  for (const name of names) {
+    if (!fits(name, QUESTION_NAME)) {
+      return `The question name ${quoted(name)} must be an identifier of at most 64 characters: letters, digits, and \`_\`, not starting with a digit.`;
+    }
+    const choice = ChoiceQuestion.safeParse(questions[name]);
+    if (!choice.success)
+      continue;
+    const labels = Object.keys(choice.data.criteria);
+    if (labels.length > MAX_CHOICE_LABELS) {
+      return `The choice question \`${name}\` offers ${labels.length} labels; at most ${MAX_CHOICE_LABELS}.`;
+    }
+    const bad = labels.find((label) => !fits(label, LABEL));
+    if (bad !== void 0) {
+      return `The choice question \`${name}\` offers the label ${quoted(bad)}, which a \`where\` filter cannot name: a label is 1 to 64 characters with no \`,\`, \`@\`, or control or invisible character, and no whitespace but single spaces between words.`;
+    }
+  }
+  return void 0;
+}
+var EchoText = z.string().catch("");
+var Echo = z.object({
+  detector: z.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
+}).catch({
+  detector: { id: "", version: "" },
+  source: { sessionId: "", entryId: "" }
+});
+function invalidObservation(input) {
+  const reason = grammarProblem(input);
+  if (reason === void 0)
+    return void 0;
+  const { detector, source } = Echo.parse(input);
+  return {
+    status: "invalid",
+    reason,
+    detector: { ...detector, rubricDigest: "" },
+    source,
+    stored: false,
+    deduplicated: false,
+    inputDigest: "",
+    recordedAtMs: Date.now()
+  };
+}
+
+// packages/herd-uri/dist/errors.js
+var UriError = class extends Error {
+};
+var CONFLICT_MESSAGES = {
+  changed: "This resource changed since this session last read it. Read it again before modifying it.",
+  unwitnessed: "This resource was not read in this session. Read it before modifying it.",
+  unknown: "This resource changed or was not read in this session. Read it again before modifying it."
+};
+var UriConflictError = class extends UriError {
+  _tag = "UriConflictError";
+  reason;
+  constructor(reason) {
+    super(CONFLICT_MESSAGES[reason ?? "unknown"]);
+    this.name = "UriConflictError";
+    this.reason = reason;
+  }
+};
+var UriValidationError = class extends UriError {
+  _tag = "UriValidationError";
+  constructor(message) {
+    super(message);
+    this.name = "UriValidationError";
+  }
+};
+var UriProviderError = class extends UriError {
+  _tag = "UriProviderError";
+  moduleId;
+  operation;
+  uri;
+  status;
+  providerCode;
+  retryable;
+  /** Provider-directed delay before retrying, in milliseconds. */
+  retryAfterMs;
+  constructor(options) {
+    super(options.message);
+    this.name = "UriProviderError";
+    this.moduleId = options.moduleId;
+    this.operation = options.operation;
+    this.uri = options.uri;
+    if (options.status !== void 0)
+      this.status = options.status;
+    if (options.providerCode !== void 0)
+      this.providerCode = options.providerCode;
+    if (options.retryable !== void 0)
+      this.retryable = options.retryable;
+    if (options.retryAfterMs !== void 0) {
+      if (!Number.isInteger(options.retryAfterMs) || options.retryAfterMs < 0) {
+        throw new TypeError("retryAfterMs must be a nonnegative integer.");
+      }
+      this.retryAfterMs = options.retryAfterMs;
+    }
+  }
+};
+var UriNotFoundError = class extends UriError {
+  uri;
+  hint;
+  _tag = "UriNotFoundError";
+  constructor(uri, hint) {
+    super(hint !== void 0 ? `No resource found at '${uri}'. ${hint}` : `No resource found at '${uri}'.`);
+    this.uri = uri;
+    this.hint = hint;
+    this.name = "UriNotFoundError";
+  }
+};
+var UriUnsupportedOperationError = class extends UriError {
+  operation;
+  moduleId;
+  uri;
+  _tag = "UriUnsupportedOperationError";
+  constructor(operation, moduleId, uri, message) {
+    super(message ?? `URI module '${moduleId}' does not support '${operation}' for '${uri}'.`);
+    this.operation = operation;
+    this.moduleId = moduleId;
+    this.uri = uri;
+    this.name = "UriUnsupportedOperationError";
+  }
+};
+
+// packages/herd-uri/dist/operations.js
+import { z as z2 } from "zod";
+var URI_OPERATIONS = [
+  "help",
+  "read",
+  "write",
+  "edit",
+  "list",
+  "search",
+  "delete"
+];
+var UriOperationSchema = z2.enum(URI_OPERATIONS);
+
+// packages/herd-uri/dist/help-schema.js
+import { z as z3 } from "zod";
+var UriContractJsonSchema = z3.record(z3.string(), z3.unknown());
+var UriParameterSchema = z3.strictObject({
+  name: z3.string().min(1),
+  in: z3.enum(["uri", "query", "selector"]),
+  required: z3.boolean(),
+  description: z3.string().optional(),
+  schema: UriContractJsonSchema,
+  examples: z3.array(z3.unknown()).optional()
+});
+var UriPayloadContractSchema = z3.strictObject({
+  name: z3.string().min(1),
+  mediaType: z3.string().optional(),
+  description: z3.string().optional(),
+  schema: UriContractJsonSchema.optional(),
+  semanticConstraints: z3.array(z3.string().min(1)).min(1).optional(),
+  examples: z3.array(z3.unknown()).optional()
+});
+
+// packages/herd-uri/dist/text-edit.js
+import { z as z4 } from "zod";
+var findReplaceArm = z4.strictObject({
+  find: z4.string().min(1),
+  replace: z4.string(),
+  all: z4.boolean().optional()
+});
+var oldNewEntry = z4.strictObject({
+  oldText: z4.string().min(1),
+  newText: z4.string()
+});
+var uriTextEditPayloadArms = z4.union([
+  findReplaceArm,
+  z4.strictObject({ edits: z4.array(oldNewEntry).min(1) }),
+  oldNewEntry,
+  z4.array(oldNewEntry).min(1)
+]);
+
+// packages/herd-uri/dist/schema/to-json-schema.js
+import { z as z5 } from "zod";
+function toJsonSchema(schema) {
+  if (schema instanceof z5.ZodType) {
+    const { $schema: _dialect, ...value } = z5.toJSONSchema(schema, {
+      // `io: "input"` describes what a caller may SEND, which is what a parameter and an
+      // `accepts` payload advertise: a field with a Zod default is optional on the wire even
+      // though the parsed value always carries it. Strictness still survives where the validator
+      // really enforces it — `z.strictObject` emits `additionalProperties: false`, while a plain
+      // `z.object` correctly does not, because it TOLERATES unknown keys and silently strips
+      // them. A `returns` payload derived from a Zod schema is described in the same input terms;
+      // no module does that today, and a faithful output projection would need its own seam.
+      io: "input",
+      // Inline every reused sub-schema rather than emitting `$ref`s into a `$defs` block. A
+      // contract schema is a FRAGMENT: it gets embedded in a payload contract, and callers
+      // legitimately lift one arm of a union out of it. A `$ref` only resolves relative to the
+      // root that carries `$defs`, so the moment the fragment moves, the reference dangles.
+      // Self-contained is worth the repetition at these sizes.
+      reused: "inline",
+      // Recursion (`z.lazy`) has no self-contained form: zod's default is to emit a
+      // `$defs` block with `$ref` pointers, which dangle the moment the fragment is
+      // embedded. Throw instead, so a contract that needs recursion has to disclose a
+      // non-recursive shape (see skill-module's metadata disclosure) rather than ship a
+      // reference nothing can resolve.
+      cycles: "throw"
+    });
+    return value;
+  }
+  return structuredClone(schema);
+}
+
+// packages/herd-uri/dist/schema/helpers.js
+function payload(name, schema, options = {}) {
+  return {
+    name,
+    ...options.mediaType === void 0 ? {} : { mediaType: options.mediaType },
+    ...options.description === void 0 ? {} : { description: options.description },
+    schema: toJsonSchema(schema),
+    ...options.semanticConstraints === void 0 ? {} : { semanticConstraints: options.semanticConstraints },
+    ...options.examples === void 0 ? {} : { examples: options.examples }
+  };
+}
+
+// packages/plugin-sdk/dist/kay-app/transcript-text.js
+function transcriptMessageTexts(entries) {
+  return entries.flatMap((entry) => {
+    if (entry.type !== "message")
+      return [];
+    const role = entry.message.role;
+    if (role !== "user" && role !== "assistant")
+      return [];
+    const text = transcriptMessageText(entry.message);
+    return text === "" ? [] : [{ role, text }];
+  });
+}
+function transcriptMessageText(message) {
+  if (typeof message.content === "string")
+    return message.content.trim();
+  if (!Array.isArray(message.content))
+    return "";
+  return message.content.flatMap((part) => {
+    if (typeof part !== "object" || part === null)
+      return [];
+    const candidate = part;
+    return candidate.type === "text" && typeof candidate.text === "string" ? [candidate.text] : [];
+  }).join("").trim();
+}
+function transcriptRoleLabel(role) {
+  return role === "user" ? "User" : "Assistant";
+}
+
+// packages/plugin-protocol/dist/app-data.js
+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 {
+  KAY_APP_AUTOMATION_CONDITION_KINDS,
+  KAY_APP_DATA_CHANGE_MAX_BYTES,
+  MAX_CHOICE_LABELS,
+  SIGNAL_TIME_MAX_MS,
+  UriConflictError,
+  UriNotFoundError,
+  UriProviderError,
+  UriUnsupportedOperationError,
+  UriValidationError,
+  createFallbackOnlySignals,
+  createFallbackOnlyWithJev,
+  invalidObservation,
+  isRetryable,
+  payload,
+  transcriptMessageText,
+  transcriptMessageTexts,
+  transcriptRoleLabel
+};

package/dist/phase-shift.d.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+
+export declare const PHASE_SHIFT_CUSTOM_TYPE = "ext:kay.phase-shift:observation";
+
+/**
+ * The custom-entry type a SURFACE reads phase shifts from: the derived
+ * {@link PhaseShiftTimelineRecord} stream, one record per accepted check.
+ *
+ * Never written to a session log. The detector records
+ * {@link PHASE_SHIFT_CUSTOM_TYPE} observations, which stay daemon bookkeeping
+ * because a surface cannot validate them: custom entries reach a surface
+ * without their entry ids, a tool call carries no entry id at all, and the
+ * observation's source ids routinely name tool-result entries. The daemon
+ * therefore folds the branch itself and hands a surface only what it can place.
+ */
+export declare const PHASE_SHIFT_TIMELINE_CUSTOM_TYPE = "ext:kay.phase-shift:timeline";
+
+declare type PhaseShiftCost = z.infer<typeof phaseShiftCostSchema>;
+
+/**
+ * What one check cost: the detector's OWN model call, priced by the same
+ * accounting as any other direct completion.
+ *
+ * It lives on the observation because nothing else can carry it. A detector
+ * call is a direct completion, not a turn, so it writes no `herd.cost_fact`
+ * and never reaches the session's usage ledger; the daemon's telemetry knows
+ * it, but a surface reading the session log does not. Recording it here is how
+ * the feature accounts for itself.
+ *
+ * Absent on a record written before the detector accounted for itself, and on
+ * a call no attempt priced — absence means "not recorded", never zero.
+ */
+declare const phaseShiftCostSchema: z.ZodObject<{
+    amountUsd: z.ZodNumber;
+    amountBasis: z.ZodEnum<{
+        unknown: "unknown";
+        measured: "measured";
+        "list-estimate": "list-estimate";
+    }>;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    attempts: z.ZodNumber;
+}, z.core.$strip>;
+
+/** One accepted transition, placed in time. */
+export declare interface PhaseShiftTimelineChange {
+    readonly startEntryId: string;
+    /** When the new work began — the onset entry's own timestamp, not the judgment's. */
+    readonly startedAt: string;
+    readonly relation: "outcome" | "phase";
+    readonly reason: string;
+    readonly purposeAfter: string;
+}
+
+/**
+ * A session's phase-shift timeline, read from its FLAT entry log.
+ *
+ * The one entry point for a consumer holding a whole log rather than a branch:
+ * it walks the tree to the active branch itself (a `leaf` marker moves the
+ * chain, so the last entry is not the branch tip after a rewind), folds the
+ * branch through {@link acceptedPhaseShiftObservations}, and resolves a
+ * version-1 record's source timestamps from the entries it referenced. Those
+ * references are branch-validated by the fold, so the resolution is total.
+ */
+export declare function phaseShiftTimelineFromEntries(entries: readonly TranscriptSourceEntry[]): readonly PhaseShiftTimelineRecord[];
+
+/**
+ * One accepted detector check, as a surface reads it.
+ *
+ * A record is evidence about the span it names and nothing else: time outside
+ * every record's `[windowStartAt, throughAt]` is unobserved, which is not the
+ * same as unchanged. An empty `changes` is the opposite — a check that ran and
+ * found no transition.
+ */
+export declare interface PhaseShiftTimelineRecord {
+    readonly version: 1;
+    readonly detectorVersion: string;
+    /** The model that judged, as resolved after any provider recovery. */
+    readonly modelReference: string;
+    /** When the detector RECOGNIZED this, which can trail the onsets it names. */
+    readonly observedAt: string;
+    readonly windowStartEntryId: string;
+    readonly windowStartAt: string;
+    readonly throughEntryId: string;
+    readonly throughAt: string;
+    /** The purpose standing after this check. */
+    readonly purpose: string;
+    /** Accepted transitions in onset order; empty means none was found. */
+    readonly changes: readonly PhaseShiftTimelineChange[];
+    /**
+     * What running this check cost. Absent means the cost was not recorded (every
+     * record written before the detector accounted for itself, and every version-1
+     * record), which is never the same as a check that cost nothing.
+     */
+    readonly cost?: PhaseShiftCost;
+}
+
+/** The fields the customType selector needs off a session entry. */
+declare interface TranscriptEntry {
+    readonly id: string;
+    readonly type: string;
+    readonly customType?: string;
+    /** Opaque. Never parsed or validated here — a feature's own schema owns that. */
+    readonly data?: unknown;
+}
+
+/**
+ * A tree entry plus the ISO timestamp the timeline projections read alongside
+ * the walk result (`turnSegments`, `phaseShiftTimelineFromEntries`).
+ */
+declare interface TranscriptSourceEntry extends TranscriptTreeEntry {
+    readonly timestamp: string;
+}
+
+/**
+ * A session entry as {@link branchEntryIds} reads it: the fields above plus the
+ * tree links the walk follows to find the active branch. No timestamp: the walk
+ * never reads one, and a live v2 entry carries epoch milliseconds where a raw
+ * v3 log carries an ISO string, so requiring either shape here would force one
+ * class of caller to convert entries it only wants walked.
+ */
+declare interface TranscriptTreeEntry extends TranscriptEntry {
+    readonly parentId?: string | null;
+    readonly targetId?: string | null;
+}
+
+export { }