@yaklabs-ai/plugin-sdk 0.13.5 → 0.13.6

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.5"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.13.6"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.13.5" },
+  "compatibility": { "sdk": "^0.13.6" },
   "targets": {
     "kay": {
       "agent": {
@@ -122,6 +122,8 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@bonsai/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules             |
 | `@bonsai/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs     |
 | `@bonsai/plugin-sdk/disclosure`        | The conformance audit Bonsai gates your plugin with — run it before you ship |
+| `@bonsai/plugin-sdk/time`              | `Temporal` (Bonsai's own instance) and the time-zone helpers, from 0.13.6    |
+| `@bonsai/plugin-sdk/transcript`        | The active-branch walk, the turn walk and the run records of a session log   |
 
 `kay-agent/host` is intentionally not published; it is Bonsai's own loading
 machinery, not an authoring API.

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.13.5",
+  "version": "0.13.6",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [
@@ -50,6 +50,13 @@
       "source": "https://github.com/eemeli/yaml",
       "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
       "versionRange": "^2.9.0"
+    },
+    {
+      "name": "@js-temporal/polyfill",
+      "license": "ISC",
+      "source": "https://github.com/js-temporal/temporal-polyfill",
+      "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
+      "versionRange": "0.5.1"
     }
   ]
 }

package/dist/disclosure.d.ts

@@ -2109,11 +2109,9 @@ declare interface KayAppTimeSnapshot {
     /**
      * 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 `===`. A first-party plugin compares with `sameZone` from
-     * `@bonsai/time`. A plugin that imports only this SDK and node builtins resolves each id with
-     * `new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone` and compares the
-     * results. Pass `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a
-     * time for the user.
+     * 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.
@@ -3696,8 +3694,8 @@ declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?:
  * owns:
  *   - {@link RunFailureReason}.
  * does_not_own:
- *   - Classifying a failure into a reason (`@herd/herd-agent`'s
- *     `core/recovery/run-failure-reason.ts`).
+ *   - Classifying a failure into a reason (`./run-failure-classifier.ts`), or the engine's
+ *     run-error mapping and recovery policy (`@herd/herd-agent`).
  * ---
  */
 /** Provider-neutral factual category for a failed model run. */

package/dist/kay-agent-testing.d.ts

@@ -481,6 +481,19 @@ declare interface ConvertedArtifact {
  */
 declare function Create(hidden: ObjectLike_2, enumerable: ObjectLike_2, options?: ObjectLike_2): ObjectLike_2;
 
+/**
+ * A {@link TestClock} starting at `startMs`. Without a `zone` it answers the zone as unknown, like
+ * {@link fauxKayAgentCapabilities}; with one it answers that zone as the user's. Use it as
+ * `{ ...fauxKayAgentCapabilities(), time: createTestClock(0) }`.
+ *
+ * Throws `RangeError` for a non-finite time, and for a `zone` the host could never answer: the
+ * host answers an IANA id in the spelling ICU resolves (`Asia/Calcutta`, not `Asia/Kolkata`), so
+ * an alias, an abbreviation such as `EST` or a typo would make a test pass that production fails.
+ */
+export declare function createTestClock(startMs: number, options?: {
+    readonly zone?: string;
+}): TestClock;
+
 /** Creates a Cyclic type. */
 declare function Cyclic<Defs extends TProperties, Ref extends string>($defs: Defs, $ref: Ref, options?: TSchemaOptions): TCyclic<Defs, Ref>;
 
@@ -2010,11 +2023,9 @@ declare interface KayAppTimeSnapshot {
     /**
      * 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 `===`. A first-party plugin compares with `sameZone` from
-     * `@bonsai/time`. A plugin that imports only this SDK and node builtins resolves each id with
-     * `new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone` and compares the
-     * results. Pass `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a
-     * time for the user.
+     * 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.
@@ -3594,8 +3605,8 @@ declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?:
  * owns:
  *   - {@link RunFailureReason}.
  * does_not_own:
- *   - Classifying a failure into a reason (`@herd/herd-agent`'s
- *     `core/recovery/run-failure-reason.ts`).
+ *   - Classifying a failure into a reason (`./run-failure-classifier.ts`), or the engine's
+ *     run-error mapping and recovery policy (`@herd/herd-agent`).
  * ---
  */
 /** Provider-neutral factual category for a failed model run. */
@@ -5077,6 +5088,18 @@ declare type TEscape0<Index extends string> = Index extends `${infer Left}~0${in
 
 declare type TEscape1<Index extends string> = Index extends `${infer Left}~1${infer Right}` ? `${Left}/${TEscape<Right>}` : Index;
 
+/**
+ * A time door (`api.time` / `app.time`) whose clock moves only when the test moves it. It also
+ * answers `nowMs()`, so it replaces `createTestClock` from `@bonsai/time/testing` unchanged.
+ */
+export declare interface TestClock extends KayAppTime {
+    nowMs(): number;
+    /** Moves the clock forward (or backward, for a negative value) by `ms`. */
+    advance(ms: number): void;
+    /** Jumps the clock to an absolute epoch-millisecond value. */
+    set(ms: number): void;
+}
+
 /** Applies an Evaluate action to a type. */
 declare type TEvaluate<Type extends TSchema> = (TEvaluateAction<Type>);
 

package/dist/kay-agent-testing.js

@@ -193,6 +193,42 @@ function fauxKayAgentCapabilities() {
     familyFolder: { path: async () => void 0 }
   };
 }
+function createTestClock(startMs, options = {}) {
+  let nowMs = finiteMs(startMs, "startMs");
+  const { zone } = options;
+  if (zone !== void 0)
+    requireResolvedZone(zone);
+  return {
+    nowMs: () => nowMs,
+    snapshot: () => zone === void 0 ? { nowMs, zone: "UTC", zoneSource: "utc-fallback" } : { nowMs, zone, zoneSource: "host" },
+    advance(ms) {
+      nowMs += finiteMs(ms, "ms");
+    },
+    set(ms) {
+      nowMs = finiteMs(ms, "ms");
+    }
+  };
+}
+function requireResolvedZone(zone) {
+  let resolved;
+  try {
+    resolved = new Intl.DateTimeFormat("en-US", {
+      timeZone: zone
+    }).resolvedOptions().timeZone;
+  } catch {
+    resolved = void 0;
+  }
+  const ianaShaped = zone.includes("/") || zone === "UTC";
+  if (!ianaShaped || resolved !== zone) {
+    throw new RangeError(`createTestClock: zone ${JSON.stringify(zone)} is not a zone the host answers` + (resolved !== void 0 && ianaShaped ? `; the host spells it ${JSON.stringify(resolved)}` : ""));
+  }
+}
+function finiteMs(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`createTestClock: ${name} must be a finite number, got ${String(value)}`);
+  }
+  return value;
+}
 function defaultTestToolContext() {
   return { cwd: "/tmp", model: void 0 };
 }
@@ -209,6 +245,7 @@ function producedResourcesForTest(result) {
   return read;
 }
 export {
+  createTestClock,
   fauxAuthContext,
   fauxKayAgentCapabilities,
   invokeToolForTest,

package/dist/kay-agent.d.ts

@@ -551,6 +551,8 @@ declare const CompareResultLeftInside = 2;
 
 declare const CompareResultRightInside = 3;
 
+export declare function compileUriClaim(claim: UriClaim): UriCompiledClaim;
+
 /** Applies a Conditional action to the given types. */
 declare function Conditional<Left extends TSchema, Right extends TSchema, True extends TSchema, False extends TSchema>(left: Left, right: Right, true_: True, false_: False, options?: TSchemaOptions): TConditional<Left, Right, True, False>;
 
@@ -2478,11 +2480,9 @@ declare interface KayAppTimeSnapshot {
     /**
      * 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 `===`. A first-party plugin compares with `sameZone` from
-     * `@bonsai/time`. A plugin that imports only this SDK and node builtins resolves each id with
-     * `new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone` and compares the
-     * results. Pass `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a
-     * time for the user.
+     * 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.
@@ -5518,8 +5518,8 @@ declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?:
  * owns:
  *   - {@link RunFailureReason}.
  * does_not_own:
- *   - Classifying a failure into a reason (`@herd/herd-agent`'s
- *     `core/recovery/run-failure-reason.ts`).
+ *   - Classifying a failure into a reason (`./run-failure-classifier.ts`), or the engine's
+ *     run-error mapping and recovery policy (`@herd/herd-agent`).
  * ---
  */
 /** Provider-neutral factual category for a failed model run. */
@@ -10114,7 +10114,7 @@ export declare interface UriCapabilitySpec {
     readonly returns?: UriPayloadContract;
 }
 
-declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
+export declare type UriClaim = UriSchemeClaim | UriPatternClaim | UrlPatternClaim;
 
 declare interface UriCommonFlow {
     readonly label: string;
@@ -10122,6 +10122,17 @@ declare interface UriCommonFlow {
     readonly example: string;
 }
 
+export declare interface UriCompiledClaim {
+    readonly claim: UriClaim;
+    match(input: string): UriCompiledClaimMatch | undefined;
+}
+
+export declare interface UriCompiledClaimMatch {
+    readonly claimKind: UriClaim["kind"];
+    readonly captures?: Record<string, string>;
+    readonly normalizedUri?: string;
+}
+
 /**
  * A source changed (or was never witnessed) before a mediated mutation. Thrown by a
  * module or by the host tool; the host renders it as a normal "not applied" tool

package/dist/kay-agent.js

@@ -1,3 +1,197 @@
+// packages/herd-uri/dist/claims.js
+var SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
+var CAPTURE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var REST_CAPTURE_RE = /^:([A-Za-z_][A-Za-z0-9_]*)\*$/;
+var CONSTRAINED_CAPTURE_RE = /^([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/;
+var MAX_CAPTURE_CONSTRAINT_LENGTH = 64;
+function compileUriClaim(claim) {
+  if (claim.kind === "scheme") {
+    const scheme = normalizeProtocol(claim.scheme);
+    return {
+      claim,
+      match(input) {
+        const actual = SCHEME_RE.exec(input.trim())?.[1]?.toLowerCase();
+        if (actual !== scheme)
+          return void 0;
+        return { claimKind: claim.kind };
+      }
+    };
+  }
+  const pattern = compileRoutePattern(claim.pattern);
+  return {
+    claim,
+    match(input) {
+      const parsed = parsePatternInput(input);
+      if (parsed === void 0)
+        return void 0;
+      const captures = matchRoute(pattern, parsed);
+      if (captures === void 0)
+        return void 0;
+      return {
+        claimKind: claim.kind,
+        ...Object.keys(captures).length > 0 ? { captures } : {},
+        ...claim.normalizeTo !== void 0 ? {
+          normalizedUri: withInputSearch(claim, pattern, parsed, interpolateNormalizeTo(claim.normalizeTo, captures, pattern.restCaptures ?? []))
+        } : {}
+      };
+    }
+  };
+}
+function normalizeProtocol(value) {
+  return value.replace(/:$/, "").toLowerCase();
+}
+function parsePatternInput(input) {
+  try {
+    const url = new URL(input.trim());
+    return {
+      protocol: normalizeProtocol(url.protocol),
+      hostname: url.hostname.toLowerCase(),
+      pathname: url.pathname,
+      search: url.search.startsWith("?") ? url.search.slice(1) : url.search
+    };
+  } catch {
+    return void 0;
+  }
+}
+function compileRoutePattern(pattern) {
+  const pathname = pattern.pathname !== void 0 ? compileParts(pattern.pathname, "/", { allowRest: true }) : void 0;
+  return {
+    ...pattern.protocol !== void 0 ? { protocol: normalizeProtocol(pattern.protocol) } : {},
+    ...pattern.hostname !== void 0 ? { hostname: compileParts(pattern.hostname.toLowerCase(), ".") } : {},
+    ...pathname !== void 0 ? { pathname } : {},
+    ...pathname !== void 0 ? {
+      restCaptures: pathname.filter((part) => part.rest === true).map((part) => part.capture)
+    } : {},
+    ...pattern.search !== void 0 ? { search: compileParts(pattern.search.replace(/^\?/, ""), "&") } : {}
+  };
+}
+function compileParts(value, separator, options = {}) {
+  if (value === "")
+    return [];
+  const parts = value.split(separator);
+  return parts.map((part, index) => {
+    const restMatch = REST_CAPTURE_RE.exec(part);
+    if (restMatch !== null) {
+      if (options.allowRest !== true || index !== parts.length - 1) {
+        throw new Error("URI claim rest captures must be final pathname segments.");
+      }
+      return { capture: restMatch[1], rest: true };
+    }
+    if (part.startsWith(":")) {
+      const rawCapture = part.slice(1);
+      const match = CONSTRAINED_CAPTURE_RE.exec(rawCapture);
+      if (match === null) {
+        throw new Error(`Invalid URI claim capture ':${rawCapture}'.`);
+      }
+      const capture = match[1];
+      if (!CAPTURE_RE.test(capture)) {
+        throw new Error(`Invalid URI claim capture ':${rawCapture}'.`);
+      }
+      const constraint = match[2];
+      if (constraint !== void 0)
+        assertSupportedConstraint(constraint);
+      return {
+        capture,
+        ...constraint !== void 0 ? { constraint: new RegExp(`^(?:${constraint})$`) } : {}
+      };
+    }
+    return { literal: part };
+  });
+}
+function assertSupportedConstraint(constraint) {
+  if (constraint.length > MAX_CAPTURE_CONSTRAINT_LENGTH || /[()|]/.test(constraint)) {
+    throw new Error("URI claim capture constraints must be short segment regexes without grouping or alternation.");
+  }
+}
+function matchRoute(pattern, input) {
+  if (pattern.protocol !== void 0 && pattern.protocol !== input.protocol) {
+    return void 0;
+  }
+  const captures = {};
+  if (pattern.hostname !== void 0 && !matchParts(pattern.hostname, input.hostname, ".", captures)) {
+    return void 0;
+  }
+  if (pattern.pathname !== void 0 && !matchParts(pattern.pathname, input.pathname, "/", captures)) {
+    return void 0;
+  }
+  if (pattern.search !== void 0 && !matchParts(pattern.search, input.search, "&", captures)) {
+    return void 0;
+  }
+  return captures;
+}
+function matchParts(pattern, value, separator, captures) {
+  const parts = value.split(separator);
+  let partIndex = 0;
+  for (let i = 0; i < pattern.length; i += 1) {
+    const expected = pattern[i];
+    if (expected.rest === true) {
+      const remaining = parts.slice(partIndex);
+      if (remaining.every((part) => part === ""))
+        return false;
+      captures[expected.capture] = remaining.join(separator);
+      return true;
+    }
+    if (partIndex >= parts.length)
+      return false;
+    const actual = parts[partIndex];
+    if (expected.capture !== void 0) {
+      const decoded = safeDecode(actual);
+      if (expected.constraint !== void 0 && !expected.constraint.test(decoded)) {
+        return false;
+      }
+      captures[expected.capture] = decoded;
+      partIndex += 1;
+      continue;
+    }
+    if (expected.literal !== actual)
+      return false;
+    partIndex += 1;
+  }
+  return partIndex === parts.length;
+}
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function withInputSearch(claim, pattern, input, normalized) {
+  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || pattern.search !== void 0 || input.search.length === 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
+    return normalized;
+  }
+  return `${normalized}?${input.search}`;
+}
+function templateProtocol(template) {
+  return SCHEME_RE.exec(template)?.[1]?.toLowerCase();
+}
+function interpolateNormalizeTo(template, captures, restCaptures) {
+  return template.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (full, name, offset) => {
+    const value = captures[name];
+    if (value === void 0)
+      return full;
+    return encodeCaptureValue({
+      template,
+      offset,
+      value,
+      rest: restCaptures.includes(name)
+    });
+  });
+}
+function encodeCaptureValue({ template, offset, value, rest }) {
+  const normalized = isAuthorityCapture(template, offset) ? value.toLowerCase() : value;
+  if (!rest)
+    return encodeURIComponent(normalized);
+  return normalized.split("/").join("/");
+}
+function isAuthorityCapture(template, offset) {
+  const prefix = template.slice(0, offset);
+  const schemeIndex = prefix.lastIndexOf("://");
+  if (schemeIndex === -1)
+    return false;
+  return !/[/?#]/.test(prefix.slice(schemeIndex + 3));
+}
+
 // packages/herd-uri/dist/errors.js
 var UriError = class extends Error {
 };
@@ -142,10 +336,10 @@ function isProducedResourceDeclaration(value) {
 // packages/herd-uri/dist/template-route.js
 var PLACEHOLDER_RE = /<([^<>]+)>/g;
 var REST_SUFFIX = "...";
-var SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):(?:\/\/)?(.*)$/s;
+var SCHEME_RE2 = /^([a-zA-Z][a-zA-Z0-9+.-]*):(?:\/\/)?(.*)$/s;
 function parseRoute(address) {
   const trimmed = address.trim();
-  const match = SCHEME_RE.exec(trimmed);
+  const match = SCHEME_RE2.exec(trimmed);
   const scheme = match?.[1]?.toLowerCase() ?? "";
   const rest = match?.[2] ?? trimmed;
   const [rawPath = "", rawQuery] = splitQuery(rest);
@@ -1577,6 +1771,7 @@ export {
   bytesToBase64,
   capability,
   collectKayAgentAdvertisement,
+  compileUriClaim,
   contentDigest,
   contentResult,
   createFallbackOnlyWithJev,