@yaklabs-ai/plugin-sdk 0.13.3 → 0.13.5

package/dist/kay-app.js

@@ -258,6 +258,8 @@ var UriProviderError = class extends UriError {
   retryable;
   /** Provider-directed delay before retrying, in milliseconds. */
   retryAfterMs;
+  /** See {@link UriProviderErrorOptions.effect}. */
+  effect;
   constructor(options) {
     super(options.message);
     this.name = "UriProviderError";
@@ -276,6 +278,8 @@ var UriProviderError = class extends UriError {
       }
       this.retryAfterMs = options.retryAfterMs;
     }
+    if (options.effect !== void 0)
+      this.effect = options.effect;
   }
 };
 var UriNotFoundError = class extends UriError {

package/dist/phase-shift.d.ts

@@ -62,7 +62,7 @@ export declare interface PhaseShiftTimelineChange {
  * 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[];
+export declare function phaseShiftTimelineFromEntries(entries: readonly TranscriptSourceEntryLike[]): readonly PhaseShiftTimelineRecord[];
 
 /**
  * One accepted detector check, as a surface reads it.
@@ -96,7 +96,7 @@ export declare interface PhaseShiftTimelineRecord {
 }
 
 /** The fields the customType selector needs off a session entry. */
-declare interface TranscriptEntry {
+declare interface TranscriptEntryLike {
     readonly id: string;
     readonly type: string;
     readonly customType?: string;
@@ -108,7 +108,7 @@ declare interface TranscriptEntry {
  * A tree entry plus the ISO timestamp the timeline projections read alongside
  * the walk result (`turnSegments`, `phaseShiftTimelineFromEntries`).
  */
-declare interface TranscriptSourceEntry extends TranscriptTreeEntry {
+declare interface TranscriptSourceEntryLike extends TranscriptTreeEntryLike {
     readonly timestamp: string;
 }
 
@@ -119,7 +119,7 @@ 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;
 }

package/dist/phase-shift.js

@@ -1,7 +1,13 @@
 // packages/plugin-protocol/dist/phase-shift.js
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // 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 branchEntryIds(entries) {
   const last = entries[entries.length - 1];
   if (last === void 0)
@@ -23,48 +29,48 @@ var PHASE_SHIFT_ENTRY_NAME = "observation";
 var PHASE_SHIFT_CUSTOM_TYPE = `ext:${PHASE_SHIFT_EXTENSION_ID}:${PHASE_SHIFT_ENTRY_NAME}`;
 var PHASE_SHIFT_TIMELINE_CUSTOM_TYPE = `ext:${PHASE_SHIFT_EXTENSION_ID}:timeline`;
 var PHASE_SHIFT_DETECTOR_VERSION = "activity-memory-v1";
-var entryId = z.string().min(1).max(256);
-var purpose = z.string().trim().min(1).max(320);
-var sourceTime = z.iso.datetime();
-var phaseShiftMemorySchema = z.object({
+var entryId = z2.string().min(1).max(256);
+var purpose = z2.string().trim().min(1).max(320);
+var sourceTime = z2.iso.datetime();
+var phaseShiftMemorySchema = z2.object({
   startEntryId: entryId,
   purpose,
-  anchors: z.array(z.object({ entryId, excerpt: z.string().max(250) })).min(1).max(3)
+  anchors: z2.array(z2.object({ entryId, excerpt: z2.string().max(250) })).min(1).max(3)
 });
-var phaseShiftCostSchema = z.object({
-  amountUsd: z.number().nonnegative(),
-  amountBasis: z.enum(["measured", "list-estimate", "unknown"]),
-  inputTokens: z.number().int().nonnegative(),
-  outputTokens: z.number().int().nonnegative(),
+var phaseShiftCostSchema = z2.object({
+  amountUsd: z2.number().nonnegative(),
+  amountBasis: z2.enum(["measured", "list-estimate", "unknown"]),
+  inputTokens: z2.number().int().nonnegative(),
+  outputTokens: z2.number().int().nonnegative(),
   /**
    * The highest provider-attempt ordinal this check accounted for; recovery
    * after a failure makes it more than one. An attempt that threw before
    * reporting usage is invisible to accounting, so this is a lower bound on
    * what the provider was actually asked to do.
    */
-  attempts: z.number().int().positive()
+  attempts: z2.number().int().positive()
 });
 var observationFields = {
-  detectorVersion: z.literal(PHASE_SHIFT_DETECTOR_VERSION),
-  modelReference: z.string().min(1).max(256),
-  observedAt: z.iso.datetime(),
+  detectorVersion: z2.literal(PHASE_SHIFT_DETECTOR_VERSION),
+  modelReference: z2.string().min(1).max(256),
+  observedAt: z2.iso.datetime(),
   throughEntryId: entryId,
-  windowEntryIds: z.array(entryId).min(1).max(40),
+  windowEntryIds: z2.array(entryId).min(1).max(40),
   memory: phaseShiftMemorySchema
 };
 var changeFields = {
   startEntryId: entryId,
-  relation: z.enum(["outcome", "phase"]),
-  reason: z.string().trim().min(1).max(2e3),
+  relation: z2.enum(["outcome", "phase"]),
+  reason: z2.string().trim().min(1).max(2e3),
   purposeAfter: purpose
 };
-var phaseShiftObservationV1Schema = z.object({
-  version: z.literal(1),
+var phaseShiftObservationV1Schema = z2.object({
+  version: z2.literal(1),
   ...observationFields,
-  changes: z.array(z.object(changeFields)).max(39)
+  changes: z2.array(z2.object(changeFields)).max(39)
 });
-var phaseShiftObservationV2Schema = z.object({
-  version: z.literal(2),
+var phaseShiftObservationV2Schema = z2.object({
+  version: z2.literal(2),
   ...observationFields,
   /** Timestamp of the `windowEntryIds[0]` entry: where this check's coverage starts. */
   windowStartAt: sourceTime,
@@ -72,13 +78,13 @@ var phaseShiftObservationV2Schema = z.object({
   throughAt: sourceTime,
   /** What this check cost to run; absent on a record written before it was accounted. */
   cost: phaseShiftCostSchema.optional(),
-  changes: z.array(z.object({
+  changes: z2.array(z2.object({
     ...changeFields,
     /** Timestamp of the `startEntryId` entry: when the new work began. */
     startedAt: sourceTime
   })).max(39)
 });
-var phaseShiftObservationSchema = z.discriminatedUnion("version", [
+var phaseShiftObservationSchema = z2.discriminatedUnion("version", [
   phaseShiftObservationV1Schema,
   phaseShiftObservationV2Schema
 ]);

package/dist/transcript.d.ts

@@ -8,11 +8,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 +24,12 @@ 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[];
 
 /** 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 +41,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,7 +52,7 @@ 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;
 }

package/dist/transcript.js

@@ -1,4 +1,10 @@
 // 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 branchEntryIds(entries) {
   const last = entries[entries.length - 1];
   if (last === void 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",

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

@@ -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; 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, 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>`.
 
 ## 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
   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.