@yaklabs-ai/plugin-sdk 0.13.4 → 0.13.6

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.
@@ -8,11 +10,11 @@
  * moment it revisits an id, so a cycle yields the cycle's own ids rather than
  * looping forever.
  */
-export declare function branchEntryIds(entries: readonly TranscriptTreeEntry[]): ReadonlySet<string>;
+export declare function branchEntryIds(entries: readonly TranscriptTreeEntryLike[]): ReadonlySet<string>;
 
 /**
  * Every `type: "custom"` entry of one `customType`, oldest→newest, with every
- * field ({@link TranscriptSourceEntry}'s id/timestamp/tree links plus the
+ * field ({@link TranscriptSourceEntryLike}'s id/timestamp/tree links plus the
  * entry's own `data`) preserved unchanged — `data` is returned exactly as it
  * arrived, opaque and unvalidated, never coerced toward a schema this module
  * cannot know.
@@ -24,12 +26,37 @@ export declare function branchEntryIds(entries: readonly TranscriptTreeEntry[]):
  * itself needs to reason about abandoned entries (an audit, a recovery
  * tool); an ordinary reader states `"active"` explicitly.
  */
-export declare function customEntriesFromEntries<T extends TranscriptSourceEntry = TranscriptSourceEntry>(entries: readonly T[], customType: string, options: {
+export declare function customEntriesFromEntries<T extends TranscriptSourceEntryLike = TranscriptSourceEntryLike>(entries: readonly T[], customType: string, options: {
     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 TranscriptEntry {
+export declare interface TranscriptEntryLike {
     readonly id: string;
     readonly type: string;
     readonly customType?: string;
@@ -41,7 +68,7 @@ export declare interface TranscriptEntry {
  * A tree entry plus the ISO timestamp the timeline projections read alongside
  * the walk result (`turnSegments`, `phaseShiftTimelineFromEntries`).
  */
-export declare interface TranscriptSourceEntry extends TranscriptTreeEntry {
+export declare interface TranscriptSourceEntryLike extends TranscriptTreeEntryLike {
     readonly timestamp: string;
 }
 
@@ -52,9 +79,91 @@ export declare interface TranscriptSourceEntry extends TranscriptTreeEntry {
  * 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 {
+declare interface TranscriptTreeEntryLike extends TranscriptEntryLike {
     readonly parentId?: string | null;
     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

@@ -1,4 +1,26 @@
 // packages/plugin-protocol/dist/transcript.js
+import { z } from "zod";
+var WorkBlockCoverageSchema = z.strictObject({
+  firstToolResultEntryId: z.string().min(1),
+  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)
@@ -13,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.4",
+  "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.
 
@@ -55,37 +55,49 @@ and symlinking `node_modules/@bonsai` into the copy does not rescue it either: p
 layout does not expose workspace packages that way. The scaffold exists precisely so this
 cannot happen.
 
+The entrypoint default-exports the function Bonsai calls with the plugin API:
+`export default function activate(api: KayAgentPluginApi): void`, and the same with
+`KayAppPluginApi` for `kay.app`. An older plugin's named `activate` export still loads. Set the
+manifest's `entrypoint.export` only to run a different export, such as one module serving both
+daemon targets. Bonsai reads the default export from plugin SDK 0.13.5 on. The scaffold's
+`compatibility.sdk` range makes an older Bonsai refuse the plugin ("needs plugin SDK ^0.13.5");
+a hand-written manifest with no range loads there and then fails with "has no 'activate' export".
+
 ## Check the manifest before you wait for a load
 
 ```
 pnpm plugin:check ~/.kay/plugins/widgets
 ```
 
-Run from the root of a Bonsai checkout, against the plugin directory. It runs the daemon's OWN
-manifest schema and contract resolver (imported from `@bonsai/plugin-protocol`, not re-implemented),
-so it answers "would Kay accept this manifest?" in about a second instead of after a load cycle.
-Run it after every manifest edit, and before concluding a plugin is broken for some deeper reason.
-
-It prints the resolved global contribution ids, exits non-zero when the plugin would be refused,
-and separates the two outcomes that look alike from outside:
-
-- **Refused outright** — schema-invalid manifest, a reserved `kay.*` / `herd.*` id, a declared
-  path escaping the plugin directory, or contributions that do not resolve. Every contribution
-  shares ONE flat `<namespace>.<localId>` space ACROSS kinds, so a tool and an endpoint both
-  called `inspect` collide and the whole plugin is refused (#8936).
+Run from the root of a Bonsai checkout, against the plugin directory. It prints the verdict the
+daemon's directory scan reaches, from the same function (`judgeKayPluginDirectory`,
+`@bonsai/plugin-protocol`), judged against that checkout's plugin SDK, whose version it prints. So
+it answers "would Bonsai refuse this plugin?" in about a second instead of after a load cycle. Run
+it after every manifest edit, and before concluding a plugin is broken for some deeper reason.
+
+It prints the resolved global contribution ids, exits non-zero unless the plugin would load, and
+separates:
+
+- **Refused outright** — an SDK range or protocol this Bonsai does not support (checked before
+  the schema, so a manifest for another SDK names the version, not its unknown key), a
+  schema-invalid manifest, a reserved `kay.*` / `herd.*` id, a declared path escaping the plugin
+  directory, or contributions that do not resolve. Every contribution shares ONE flat
+  `<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, a `toolName` that is not the namespace-derived name (that tool is excluded and
-  nothing tells the user), a missing entrypoint or skill file.
+  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 reads the manifest only. A clean verdict says nothing about `activate()` throwing, the
-disclosure audit, or an id another installed plugin already claims.
+It never reads the declared files or applies the roster's rules: a missing entrypoint or skill
+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 chord loader bundles each declared TypeScript entrypoint and its relative imports.
+- 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.
   Multi-file plugins are supported, and no plugin-local build is needed for Bonsai to load them.
 - Corollary: **bare `node` outside the daemon cannot resolve `@bonsai/plugin-sdk`** from the plugin
@@ -94,7 +106,7 @@ disclosure audit, or an id another installed plugin already claims.
   standalone test; a published SDK dependency is the other standalone option.
 - Typecheck with `npm run typecheck` inside the plugin directory; the scaffold's generated
   tsconfig maps the SDK's types via `paths`.
-- Chord compiles TypeScript syntax that native type stripping cannot execute, including `enum`,
+- The loader compiles TypeScript syntax that native type stripping cannot execute, including `enum`,
   `namespace` blocks, constructor parameter properties, and decorators. Typecheck before enabling
   the plugin; a bundle error is reported as a target-load diagnostic.
 
@@ -208,10 +220,10 @@ list` names the exact local root — because writing into the wrong one produces
 The commit is the activation boundary, so run these against the working tree first. Each catches
 a failure class the load would otherwise be the first thing to surface:
 
-1. **Run `pnpm plugin:check <dir>`** from a Bonsai checkout. It validates `kay-plugin.json` against
-   `KayPluginManifestV1` and resolves its contributions with the daemon's own resolver (both from
-   `@bonsai/plugin-protocol`), not just "it is valid JSON": that schema and resolver are the gate the
-   scan actually runs. A non-zero exit means the plugin would be refused.
+1. **Run `pnpm plugin:check <dir>`** from a Bonsai checkout. It prints the verdict of the function
+   the daemon's directory scan runs (`judgeKayPluginDirectory`): SDK compatibility, the manifest
+   schema, reserved ids, contract resolution and path containment, not just "it is valid JSON". A
+   non-zero exit means the plugin would be refused.
 2. **Run the disclosure audit yourself**: `auditPluginDisclosure` from `@bonsai/plugin-sdk/disclosure`.
    It is not redundant with typecheck. A plugin shipped a `search` verb with no `verbDocs` entry
    that typechecked clean and would have failed the whole `kay.agent` target.
@@ -281,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.