@yaklabs-ai/plugin-sdk 0.13.5 → 0.13.6

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
+};

package/dist/transcript.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * The ids on a session's active branch: the leaf chain walked parent-ward from
  * the tip, which a trailing `leaf` marker moves. Empty for an empty log.
@@ -28,6 +30,31 @@ export declare function customEntriesFromEntries<T extends TranscriptSourceEntry
     readonly branch: "active" | "all";
 }): readonly T[];
 
+export declare function matchesWorkBlock(coverage: WorkBlockCoverage, toolResultEntryIds: readonly string[]): boolean;
+
+/**
+ * Tool names the transcript draws as their own surface, or lifts into the reply, instead of
+ * counting them as work in the closed bar (venue `inline` or `turn-tail`, or the parsed
+ * `submit_final`). A call to one of these is not a "visible call". The renderer's built-in tool
+ * registrations are the source of truth; its parity test fails when this list drifts from them.
+ * A tool a plugin registers with a non-activity venue is not listed, so the daemon may count it
+ * (a headline can appear on a turn whose bar shows fewer calls than the cutoff only in that
+ * corner, and the renderer re-checks its own count before displaying anything).
+ */
+export declare const NON_ACTIVITY_TOOL_NAMES: readonly string[];
+
+/**
+ * The daemon's own run-start record. A run's entries begin here, before the
+ * user message that opened it.
+ */
+export declare const RUN_STARTED_CUSTOM_TYPE = "session_run_started";
+
+/**
+ * The daemon's own terminal run record (completed / interrupted / cancelled /
+ * failed). A run's entries end here.
+ */
+export declare const RUN_TERMINAL_CUSTOM_TYPE = "session_run_state";
+
 /** The fields the customType selector needs off a session entry. */
 export declare interface TranscriptEntryLike {
     readonly id: string;
@@ -57,4 +84,86 @@ declare interface TranscriptTreeEntryLike extends TranscriptEntryLike {
     readonly targetId?: string | null;
 }
 
+/**
+ * The fields the turn walk reads. Deliberately narrower and looser than
+ * {@link TranscriptEntryLike}: the walk answers in INDEXES, so it never needs an
+ * `id`, and both callers hold entries typed by their own layer (herd's
+ * `TranscriptEntry`, the daemon's branch rows).
+ */
+export declare interface TurnBoundaryEntry {
+    readonly type?: string;
+    readonly customType?: string;
+    /** Opaque here; only `message.role === "user"` is read, defensively. */
+    readonly message?: unknown;
+}
+
+/** One turn's bounds as {@link turnSegments} reports them, both inclusive. */
+export declare interface TurnSegment {
+    /** The user message entry that opened the turn. A steer never opens one. */
+    readonly openingIndex: number;
+    /**
+     * The entry the turn settled on. Equal to `openingIndex` when nothing
+     * followed the opening message, which is a turn that never settled rather
+     * than a turn with an empty body.
+     */
+    readonly settleIndex: number;
+}
+
+/**
+ * THE definition of a turn, shared by every reader that has to agree about one:
+ * the settled-turn extractors that key a record to a turn, and the replay
+ * publisher that offers a stored session's turns as events. Two readers
+ * disagreeing here means a replayed "turn" is not the turn production would
+ * have extracted.
+ *
+ * **A turn is a run.** The daemon brackets every run in the transcript
+ * ({@link RUN_STARTED_CUSTOM_TYPE} then, at the end,
+ * {@link RUN_TERMINAL_CUSTOM_TYPE}), and the user message that opened the run
+ * opens the turn. A human steering or a queued message admitted mid-flight is
+ * persisted as another `role: "user"` entry INSIDE that bracket, and belongs to
+ * the turn it interrupted: it is a correction to work already under way, not a
+ * new request. Anchoring on the last user entry instead hands an extractor the
+ * steer as the turn's goal and demotes the real request to prior context.
+ *
+ * A transcript with no run brackets at all (a log older than run bookkeeping, a
+ * hand-built fixture) falls back to one turn per user message, which is the
+ * most this function can honestly say: with no record of when a run ended,
+ * nothing distinguishes a steer from a fresh request.
+ *
+ * `throughIndex` bounds the walk for a caller holding only a prefix; segments
+ * are returned oldest first.
+ */
+export declare function turnSegments(entries: readonly TurnBoundaryEntry[], throughIndex?: number): readonly TurnSegment[];
+
+export declare const WORK_HEADLINE_MAX_CHARS = 90;
+
+/** The longest and shortest stored work headline, in characters. Shorter is filler; longer is a sentence. */
+export declare const WORK_HEADLINE_MIN_CHARS = 12;
+
+/**
+ * The fewest VISIBLE tool calls a settled turn needs before it earns a work headline (owner
+ * ruling, 2026-10-14: "it shouldn't do that if it ran 2 commands but could be helpful if it ran
+ * like 15"; the scope card's 10 was accepted). ONE value, read by the writer (the hindsight
+ * `work-headline` handler decides whether to spend a model call) and by the closed work bar's
+ * renderer (decides whether to show a stored headline), so the two can never disagree about which
+ * turns qualify.
+ */
+export declare const WORK_HEADLINE_MIN_VISIBLE_CALLS = 10;
+
+export declare type WorkBlockCoverage = z.infer<typeof WorkBlockCoverageSchema>;
+
+export declare function workBlockCoverage(toolResultEntryIds: readonly string[]): WorkBlockCoverage | undefined;
+
+/**
+ * Exact ordered completed executions, addressed by persisted tool-result entry IDs.
+ * Provider call IDs can repeat across retries and turns; they are never ownership keys.
+ */
+export declare const WorkBlockCoverageSchema: z.ZodObject<{
+    firstToolResultEntryId: z.ZodString;
+    lastToolResultEntryId: z.ZodString;
+    toolResultEntryIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+export declare function workBlockKey(coverage: WorkBlockCoverage): string;
+
 export { }

package/dist/transcript.js

@@ -5,6 +5,22 @@ var WorkBlockCoverageSchema = z.strictObject({
   lastToolResultEntryId: z.string().min(1),
   toolResultEntryIds: z.array(z.string().min(1)).min(1).max(4096)
 }).refine((value) => value.firstToolResultEntryId === value.toolResultEntryIds[0] && value.lastToolResultEntryId === value.toolResultEntryIds.at(-1) && new Set(value.toolResultEntryIds).size === value.toolResultEntryIds.length);
+function workBlockCoverage(toolResultEntryIds) {
+  const parsed = WorkBlockCoverageSchema.safeParse({
+    firstToolResultEntryId: toolResultEntryIds[0],
+    lastToolResultEntryId: toolResultEntryIds.at(-1),
+    toolResultEntryIds
+  });
+  return parsed.success ? parsed.data : void 0;
+}
+function workBlockKey(coverage) {
+  return JSON.stringify(coverage.toolResultEntryIds);
+}
+function matchesWorkBlock(coverage, toolResultEntryIds) {
+  return coverage.toolResultEntryIds.length === toolResultEntryIds.length && coverage.toolResultEntryIds.every((id, index) => id === toolResultEntryIds[index]);
+}
+var RUN_STARTED_CUSTOM_TYPE = "session_run_started";
+var RUN_TERMINAL_CUSTOM_TYPE = "session_run_state";
 function branchEntryIds(entries) {
   const last = entries[entries.length - 1];
   if (last === void 0)
@@ -19,11 +35,77 @@ function branchEntryIds(entries) {
   return onBranch;
 }
 var EMPTY_BRANCH_IDS = /* @__PURE__ */ new Set();
+function isUserMessageEntry(entry) {
+  if (entry.type !== "message")
+    return false;
+  const message = entry.message;
+  return typeof message === "object" && message !== null && message.role === "user";
+}
+function runBoundaryOf(entry) {
+  if (entry.type !== "custom")
+    return void 0;
+  if (entry.customType === RUN_STARTED_CUSTOM_TYPE)
+    return "started";
+  if (entry.customType === RUN_TERMINAL_CUSTOM_TYPE)
+    return "terminal";
+  return void 0;
+}
+function turnSegments(entries, throughIndex = entries.length - 1) {
+  const segments = [];
+  let openingIndex;
+  let runOpen = false;
+  const close = (settleIndex) => {
+    if (openingIndex !== void 0 && settleIndex >= openingIndex) {
+      segments.push({ openingIndex, settleIndex });
+    }
+    openingIndex = void 0;
+  };
+  for (let index = 0; index <= throughIndex; index += 1) {
+    const entry = entries[index];
+    if (entry === void 0)
+      break;
+    const boundary = runBoundaryOf(entry);
+    if (boundary !== void 0) {
+      close(boundary === "terminal" ? index : index - 1);
+      runOpen = boundary === "started";
+      continue;
+    }
+    if (!isUserMessageEntry(entry))
+      continue;
+    if (runOpen && openingIndex !== void 0)
+      continue;
+    close(index - 1);
+    openingIndex = index;
+  }
+  close(throughIndex);
+  return segments;
+}
 function customEntriesFromEntries(entries, customType, options) {
   const onBranch = options.branch === "all" ? null : branchEntryIds(entries);
   return entries.filter((entry) => entry.type === "custom" && entry.customType === customType && (onBranch === null || onBranch.has(entry.id)));
 }
+var WORK_HEADLINE_MIN_VISIBLE_CALLS = 10;
+var NON_ACTIVITY_TOOL_NAMES = [
+  "agent_spawn",
+  "send_message",
+  "service_connect",
+  "ui_render",
+  "submit_final"
+];
+var WORK_HEADLINE_MIN_CHARS = 12;
+var WORK_HEADLINE_MAX_CHARS = 90;
 export {
+  NON_ACTIVITY_TOOL_NAMES,
+  RUN_STARTED_CUSTOM_TYPE,
+  RUN_TERMINAL_CUSTOM_TYPE,
+  WORK_HEADLINE_MAX_CHARS,
+  WORK_HEADLINE_MIN_CHARS,
+  WORK_HEADLINE_MIN_VISIBLE_CALLS,
+  WorkBlockCoverageSchema,
   branchEntryIds,
-  customEntriesFromEntries
+  customEntriesFromEntries,
+  matchesWorkBlock,
+  turnSegments,
+  workBlockCoverage,
+  workBlockKey
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -44,6 +44,10 @@
     "./transcript": {
       "types": "./dist/transcript.d.ts",
       "default": "./dist/transcript.js"
+    },
+    "./time": {
+      "types": "./dist/time.d.ts",
+      "default": "./dist/time.js"
     }
   },
   "files": [
@@ -56,7 +60,8 @@
   ],
   "dependencies": {
     "zod": "^4.0.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@js-temporal/polyfill": "0.5.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skills/directory-plugin-authoring/SKILL.md

@@ -6,7 +6,7 @@ description: "Author, scaffold, debug, or iterate on a Bonsai directory plugin (
 # Directory plugin authoring
 
 A directory plugin is a plugin the user authors in `~/.kay/plugins/<name>/`, outside the Bonsai
-repo. The full authoring guide is [`docs/directory-plugins.md`](../../docs/directory-plugins.md)
+repo. The full authoring guide is [`docs/directory-plugins.md`](../../../docs/directory-plugins.md)
 and the SDK reference is `packages/plugin-sdk/README.md`; this skill is the routing layer that
 keeps an agent on the paved path and out of the known pits.
 
@@ -85,17 +85,17 @@ separates:
   `<namespace>.<localId>` space ACROSS kinds, so a tool and an endpoint both called `inspect`
   collide and the whole plugin is refused (#8936).
 - **Loads, minus something** — a retired `compatibility` / `permissions.byTarget` key the parser
-  strips silently; plus compatibility notes (no declared SDK range).
+  strips silently, or a tool whose `toolName` is not the namespace-derived name (that tool is left
+  out); plus compatibility notes (no declared SDK range).
 
 It never reads the declared files or applies the roster's rules: a missing entrypoint or skill
-file, a `toolName` that is not the namespace-derived name, an `activate()` that throws, the
-disclosure audit, and an id another installed plugin already claims all show only after enabling,
-in `read plugin://<id>`.
+file, an `activate()` that throws, the disclosure audit, and an id another installed plugin already
+claims all show only after enabling, in `read plugin://<id>`.
 
 ## The SDK resolution contract
 
 - Plugin source imports `@bonsai/plugin-sdk/<subpath>` as a **bare specifier**
-  (`@bonsai/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure` — only declared
+  (`@bonsai/plugin-sdk/kay-agent`, `/kay-agent/testing`, `/kay-app`, `/disclosure`, `/time` — only declared
   exports exist).
 - The daemon's plugin loader bundles each declared TypeScript entrypoint and its relative imports.
   It keeps `@bonsai/plugin-sdk` imports external and resolves them to the running app's own built SDK.
@@ -293,7 +293,7 @@ file.
 
 ## Reference map
 
-- [`docs/directory-plugins.md`](../../docs/directory-plugins.md) — the authoring guide:
+- [`docs/directory-plugins.md`](../../../docs/directory-plugins.md) — the authoring guide:
   manifest shape, the enable gate and what it does not gate, trust tiers, diagnostics.
 - `packages/plugin-sdk/README.md` — the SDK surface.
 - `packages/plugin-sdk/PUBLISHED.md` — installing the published SDK outside a Bonsai checkout.