@yaklabs-ai/plugin-sdk 0.13.5 → 0.13.7

package/dist/kay-app.js

@@ -1,3 +1,16 @@
+// packages/plugin-protocol/dist/json.js
+import { z } from "zod";
+var JsonValue = z.lazy(() => z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(JsonValue),
+  z.record(z.string(), JsonValue)
+]));
+var JsonObject = z.record(z.string(), JsonValue);
+var JsonSchema = z.record(z.string(), JsonValue);
+
 // packages/plugin-sdk/dist/jev.js
 var JevCallError = class extends Error {
   transport;
@@ -73,7 +86,7 @@ function createFallbackOnlyWithJev() {
 }
 
 // packages/plugin-sdk/dist/signals.js
-import { z } from "zod";
+import { z as z2 } from "zod";
 function createFallbackOnlySignals() {
   const noStore = { status: "unavailable", reason: "no-store" };
   return {
@@ -103,23 +116,23 @@ 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() }),
-  subject: z.looseObject({ kind: z.string(), key: z.string().optional() }).optional(),
-  after: z.looseObject({ observationId: z.unknown() }).optional(),
-  reuse: z.looseObject({ maxAgeMs: z.unknown() }).optional(),
-  source: z.looseObject({
-    sessionId: z.string(),
-    entryId: z.string(),
-    openerEntryId: z.string().optional(),
-    runId: z.string().optional(),
-    occurredAtMs: z.unknown().optional()
+var ObserveShape = z2.looseObject({
+  detector: z2.looseObject({ id: z2.string(), version: z2.string() }),
+  subject: z2.looseObject({ kind: z2.string(), key: z2.string().optional() }).optional(),
+  after: z2.looseObject({ observationId: z2.unknown() }).optional(),
+  reuse: z2.looseObject({ maxAgeMs: z2.unknown() }).optional(),
+  source: z2.looseObject({
+    sessionId: z2.string(),
+    entryId: z2.string(),
+    openerEntryId: z2.string().optional(),
+    runId: z2.string().optional(),
+    occurredAtMs: z2.unknown().optional()
   }),
-  questions: z.record(z.string(), z.unknown())
+  questions: z2.record(z2.string(), z2.unknown())
 });
-var ChoiceQuestion = z.looseObject({
-  type: z.literal("choice"),
-  criteria: z.record(z.string(), z.unknown())
+var ChoiceQuestion = z2.looseObject({
+  type: z2.literal("choice"),
+  criteria: z2.record(z2.string(), z2.unknown())
 });
 var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
 var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
@@ -199,10 +212,10 @@ function grammarProblem(input) {
   }
   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: "" })
+var EchoText = z2.string().catch("");
+var Echo = z2.object({
+  detector: z2.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z2.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
 }).catch({
   detector: { id: "", version: "" },
   source: { sessionId: "", entryId: "" }
@@ -308,7 +321,7 @@ var UriUnsupportedOperationError = class extends UriError {
 };
 
 // packages/herd-uri/dist/operations.js
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var URI_OPERATIONS = [
   "help",
   "read",
@@ -318,44 +331,44 @@ var URI_OPERATIONS = [
   "search",
   "delete"
 ];
-var UriOperationSchema = z2.enum(URI_OPERATIONS);
+var UriOperationSchema = z3.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(),
+import { z as z4 } from "zod";
+var UriContractJsonSchema = z4.record(z4.string(), z4.unknown());
+var UriParameterSchema = z4.strictObject({
+  name: z4.string().min(1),
+  in: z4.enum(["uri", "query", "selector"]),
+  required: z4.boolean(),
+  description: z4.string().optional(),
   schema: UriContractJsonSchema,
-  examples: z3.array(z3.unknown()).optional()
+  examples: z4.array(z4.unknown()).optional()
 });
-var UriPayloadContractSchema = z3.strictObject({
-  name: z3.string().min(1),
-  mediaType: z3.string().optional(),
-  description: z3.string().optional(),
+var UriPayloadContractSchema = z4.strictObject({
+  name: z4.string().min(1),
+  mediaType: z4.string().optional(),
+  description: z4.string().optional(),
   schema: UriContractJsonSchema.optional(),
-  semanticConstraints: z3.array(z3.string().min(1)).min(1).optional(),
-  examples: z3.array(z3.unknown()).optional()
+  semanticConstraints: z4.array(z4.string().min(1)).min(1).optional(),
+  examples: z4.array(z4.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()
+import { z as z5 } from "zod";
+var findReplaceArm = z5.strictObject({
+  find: z5.string().min(1),
+  replace: z5.string(),
+  all: z5.boolean().optional()
 });
-var oldNewEntry = z4.strictObject({
-  oldText: z4.string().min(1),
-  newText: z4.string()
+var oldNewEntry = z5.strictObject({
+  oldText: z5.string().min(1),
+  newText: z5.string()
 });
-var uriTextEditPayloadArms = z4.union([
+var uriTextEditPayloadArms = z5.union([
   findReplaceArm,
-  z4.strictObject({ edits: z4.array(oldNewEntry).min(1) }),
+  z5.strictObject({ edits: z5.array(oldNewEntry).min(1) }),
   oldNewEntry,
-  z4.array(oldNewEntry).min(1)
+  z5.array(oldNewEntry).min(1)
 ]);
 
 // packages/herd-uri/dist/line-selector.js
@@ -451,10 +464,10 @@ function parseLineSelector(input) {
 }
 
 // packages/herd-uri/dist/schema/to-json-schema.js
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function toJsonSchema(schema) {
-  if (schema instanceof z5.ZodType) {
-    const { $schema: _dialect, ...value } = z5.toJSONSchema(schema, {
+  if (schema instanceof z6.ZodType) {
+    const { $schema: _dialect, ...value } = z6.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
@@ -577,8 +590,11 @@ var KAY_APP_AUTOMATION_CONDITION_KINDS = [
 ];
 export {
   JevCallError,
+  JsonSchema,
+  JsonValue,
   KAY_APP_AUTOMATION_CONDITION_KINDS,
   KAY_APP_DATA_CHANGE_MAX_BYTES,
+  KAY_APP_DATA_SNAPSHOT_MAX_BYTES,
   KayAppWorkflowFailure,
   MAX_CHOICE_LABELS,
   SIGNAL_TIME_MAX_MS,

package/dist/time.d.ts

@@ -0,0 +1,157 @@
+import { Temporal as Temporal_2 } from '@js-temporal/polyfill';
+
+/**
+ * The id ICU resolves for an IANA time-zone id, or `undefined` when `id` is not one.
+ *
+ * Accepts `UTC`, `GMT`, and any id that contains `/` and that ICU resolves. Rejects
+ * abbreviations and slash-less legacy ids (`EST`, `CET`, `EST5EDT`), offsets (`+05:30`,
+ * `UTC+2`), the empty string, strings over 64 characters and non-strings. ICU maps link
+ * names to its own canonical id (`Asia/Kolkata` to `Asia/Calcutta`), and which spelling is
+ * canonical depends on the engine, so compare zones with {@link sameZone}, never with `===`.
+ */
+export declare function canonicalZone(id: unknown): string | undefined;
+
+/** True when {@link canonicalZone} accepts `id`. */
+export declare function isValidZone(id: unknown): boolean;
+
+/**
+ * `app.time` / `api.time`: host facts about time. Added to `kay.app` in SDK 0.12.1 and to
+ * `kay.agent` with the calendar zone-of-record work: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.1`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+export declare interface KayAppTime {
+    /**
+     * Reads the daemon's clock and the user's time zone now.
+     *
+     * Every call asks the host again and returns a new object; nothing is cached. Call it where you
+     * need the value (inside a tool, a handler or a workflow step), not inside `activate()`: a value
+     * read there is as old as the activation, and the host can run a bundled plugin's `activate()`
+     * against a recording api that has no `time`, so a read there throws. The exception is a
+     * directory plugin that declares a workflow with a cron `timezone`: `workflows.define` is legal
+     * only during `activate()`, so it reads the zone there, and the schedule then keeps that zone.
+     * Keep the result for as long as you use it, and not across a long wait (a sleep, a timer, a
+     * queued run): the zone can change while you wait. On a daemon that runs on the user's machine,
+     * a change of the process's `TZ` shows in the next call. A `TZ` that names a zone wins over the
+     * operating system's zone, so a change of the operating-system zone does not show while the
+     * process has one. When `TZ` is unset or does not name a zone, a change of the operating-system
+     * zone is meant to show, but none has been seen on a real machine yet.
+     *
+     * A zone the host cannot determine is an answer (`zoneSource: "utc-fallback"`), not an error.
+     *
+     * Use this to find the zone, not `Intl.DateTimeFormat().resolvedOptions().timeZone`, which can
+     * keep a zone the runtime read earlier, or `process.env.TZ`, which is often unset or not a zone.
+     * Neither says that the zone is unknown.
+     *
+     * It does not use `this`, so it is safe to destructure.
+     */
+    readonly snapshot: () => KayAppTimeSnapshot;
+}
+
+/**
+ * The plugin-facing time contract: the daemon's clock and the time zone the user is in,
+ * read together in one call.
+ *
+ * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
+ * daemon's process and can already read the clock. What the door adds is the daemon's answer
+ * for the USER's zone, and a label for the case where that answer is unknown.
+ *
+ * This is a leaf module. It lives beside both target SDKs (rather than inside `kay-app`) so the
+ * `kay.agent` SDK can expose the same door without importing the `kay.app` surface, which pulls
+ * that surface into every agent-facing bundle.
+ */
+/** One reading of the daemon's clock and the user's time zone. Each call returns a new object. */
+export declare interface KayAppTimeSnapshot {
+    /** The daemon's clock when the snapshot was read: milliseconds since the Unix epoch. */
+    readonly nowMs: number;
+    /**
+     * The time zone the user is in, as an IANA id in the spelling ICU resolves (`America/New_York`).
+     * One zone can have two ids, and ICU picks one: `Asia/Kolkata` comes back as `Asia/Calcutta`. So
+     * never compare zone ids with `===`: compare with `sameZone` from `@bonsai/plugin-sdk/time`. Pass
+     * `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a time for the
+     * user.
+     *
+     * When `zoneSource` is `utc-fallback` the zone is unknown, and this value is `UTC` only because a
+     * value is required.
+     */
+    readonly zone: string;
+    /**
+     * How the daemon found `zone`.
+     * - `host`: the daemon runs on the user's machine, and `zone` is the zone the daemon process
+     *   runs in, read for this call: the process's `TZ` when that names a zone, otherwise the
+     *   operating system's zone.
+     * - `utc-fallback`: the daemon does not know the user's zone. It runs on another machine (a remote
+     *   daemon), or the machine's zone could not be read or is not an IANA id. `zone` is `UTC`, which
+     *   here is a placeholder and not a fact about the user: do not show it to the user as their zone.
+     */
+    readonly zoneSource: "host" | "utc-fallback";
+}
+
+/** True when both ids are valid and ICU resolves them to the same zone. */
+export declare function sameZone(a: unknown, b: unknown): boolean;
+
+/**
+ * The Temporal API of this process: the engine's own `globalThis.Temporal` when it has one
+ * (Electron's runtime does, Node 24 does not), and `@js-temporal/polyfill`'s otherwise.
+ * `temporalImplementation` says which.
+ *
+ * It is a value and, through the namespace below, a type namespace: `Temporal.Instant` and
+ * `Temporal.ZonedDateTime` name both the classes and their instance types.
+ */
+export declare const Temporal: TemporalApi;
+
+/**
+ * The types of `@js-temporal/polyfill`'s `Temporal` namespace, so code can write
+ * `Temporal.Instant` as a type. `Now` and `DateTimeFormat` are left out on purpose: time
+ * that logic depends on comes from a `Clock`, and the polyfill's `Intl` export is not part of
+ * this API. `test/temporal.test.ts` fails when a new polyfill version adds a type that this
+ * list lacks.
+ */
+export declare namespace Temporal {
+    export type ComparisonResult = Temporal_2.ComparisonResult;
+    export type RoundingMode = Temporal_2.RoundingMode;
+    export type AssignmentOptions = Temporal_2.AssignmentOptions;
+    export type DurationOptions = Temporal_2.DurationOptions;
+    export type ToInstantOptions = Temporal_2.ToInstantOptions;
+    export type ZonedDateTimeAssignmentOptions = Temporal_2.ZonedDateTimeAssignmentOptions;
+    export type ArithmeticOptions = Temporal_2.ArithmeticOptions;
+    export type DateUnit = Temporal_2.DateUnit;
+    export type TimeUnit = Temporal_2.TimeUnit;
+    export type DateTimeUnit = Temporal_2.DateTimeUnit;
+    export type PluralUnit<T extends Temporal_2.DateTimeUnit> = Temporal_2.PluralUnit<T>;
+    export type LargestUnit<T extends Temporal_2.DateTimeUnit> = Temporal_2.LargestUnit<T>;
+    export type SmallestUnit<T extends Temporal_2.DateTimeUnit> = Temporal_2.SmallestUnit<T>;
+    export type TotalUnit<T extends Temporal_2.DateTimeUnit> = Temporal_2.TotalUnit<T>;
+    export type ToStringPrecisionOptions = Temporal_2.ToStringPrecisionOptions;
+    export type ShowCalendarOption = Temporal_2.ShowCalendarOption;
+    export type CalendarTypeToStringOptions = Temporal_2.CalendarTypeToStringOptions;
+    export type ZonedDateTimeToStringOptions = Temporal_2.ZonedDateTimeToStringOptions;
+    export type InstantToStringOptions = Temporal_2.InstantToStringOptions;
+    export type DifferenceOptions<T extends Temporal_2.DateTimeUnit> = Temporal_2.DifferenceOptions<T>;
+    export type RoundTo<T extends Temporal_2.DateTimeUnit> = Temporal_2.RoundTo<T>;
+    export type DurationRoundTo = Temporal_2.DurationRoundTo;
+    export type DurationTotalOf = Temporal_2.DurationTotalOf;
+    export type DurationArithmeticOptions = Temporal_2.DurationArithmeticOptions;
+    export type TransitionDirection = Temporal_2.TransitionDirection;
+    export type DurationLike = Temporal_2.DurationLike;
+    export type Duration = Temporal_2.Duration;
+    export type Instant = Temporal_2.Instant;
+    export type CalendarLike = Temporal_2.CalendarLike;
+    export type PlainDateLike = Temporal_2.PlainDateLike;
+    export type PlainDate = Temporal_2.PlainDate;
+    export type PlainDateTimeLike = Temporal_2.PlainDateTimeLike;
+    export type PlainDateTime = Temporal_2.PlainDateTime;
+    export type PlainMonthDayLike = Temporal_2.PlainMonthDayLike;
+    export type PlainMonthDay = Temporal_2.PlainMonthDay;
+    export type PlainTimeLike = Temporal_2.PlainTimeLike;
+    export type PlainTime = Temporal_2.PlainTime;
+    export type TimeZoneLike = Temporal_2.TimeZoneLike;
+    export type PlainYearMonthLike = Temporal_2.PlainYearMonthLike;
+    export type PlainYearMonth = Temporal_2.PlainYearMonth;
+    export type ZonedDateTimeLike = Temporal_2.ZonedDateTimeLike;
+    export type ZonedDateTime = Temporal_2.ZonedDateTime;
+}
+
+declare type TemporalApi = typeof Temporal_2;
+
+export { }

package/dist/time.js

@@ -0,0 +1,37 @@
+// packages/time/dist/temporal.js
+import { Temporal as Polyfill } from "@js-temporal/polyfill";
+var engineTemporal = Reflect.get(globalThis, "Temporal");
+var Temporal = engineTemporal ?? Polyfill;
+
+// packages/time/dist/zones.js
+var MAX_ZONE_ID_LENGTH = 64;
+function hasIanaShape(id) {
+  if (id.length > MAX_ZONE_ID_LENGTH)
+    return false;
+  if (id.includes("/"))
+    return true;
+  const upper = id.toUpperCase();
+  return upper === "UTC" || upper === "GMT";
+}
+function canonicalZone(id) {
+  if (typeof id !== "string" || !hasIanaShape(id))
+    return void 0;
+  try {
+    return new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone;
+  } catch {
+    return void 0;
+  }
+}
+function isValidZone(id) {
+  return canonicalZone(id) !== void 0;
+}
+function sameZone(a, b) {
+  const left = canonicalZone(a);
+  return left !== void 0 && left === canonicalZone(b);
+}
+export {
+  Temporal,
+  canonicalZone,
+  isValidZone,
+  sameZone
+};