@yaklabs-ai/plugin-sdk 0.13.5 → 0.13.7

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.7"
   }
 }
 ```
@@ -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.7" },
   "targets": {
     "kay": {
       "agent": {
@@ -116,12 +116,23 @@ naming both versions, instead of loading it and finding no `activate`.
 
 ## Entrypoints
 
-| Import                                 | What it gives you                                                            |
-| -------------------------------------- | ---------------------------------------------------------------------------- |
-| `@bonsai/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface   |
-| `@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 |
+| Import                                  | What it gives you                                                               |
+| --------------------------------------- | ------------------------------------------------------------------------------- |
+| `@bonsai/plugin-sdk/kay-agent`          | Tools, URI modules, search providers, auth — the per-session agent surface      |
+| `@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 run records from 0.13.6               |
+| `@bonsai/plugin-sdk/transcript-review`  | The review fold: a session's spans, tool-call attempts and records, from 0.13.7 |
+| `@bonsai/plugin-sdk/agent-conversation` | How a session's agent-to-agent traffic groups into conversations, from 0.13.7   |
+| `@bonsai/plugin-sdk/app-data`           | The app-data size caps, on an entry with no other import, from 0.13.7           |
+| `@bonsai/plugin-sdk/vendored-mcp`       | The kit for a plugin built on a vendor's hosted MCP server, from 0.13.7         |
+
+A plugin that imports a subpath declares at least the version its row names (`^0.13.7` for the
+last four). `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
+vendor's MCP server itself is a separate host decision, and Bonsai currently makes it only for
+its own bundled plugins.
 
 `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.7",
   "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/agent-conversation.d.ts

@@ -0,0 +1,93 @@
+/** The admitted inbox receipt, not a target guessed from tool arguments or prose. */
+export declare function admittedSendSessionId(details: unknown): string | undefined;
+
+/**
+ * The admitted-spawn stamp, or `undefined` when nothing was started.
+ *
+ * Two generations of stamp exist in durable transcripts and both must parse
+ * forever: version 2 (the messaging contract) writes
+ * `{ version: 2, sessionId, displayName, backgroundTaskId }` and exists only
+ * for admitted spawns (rejections are tool errors and stamp nothing);
+ * version 1 wrote `{ version: 1, accepted, childSessionId, label, … }`, where
+ * `accepted: false` carries no child session.
+ */
+export declare function admittedSpawnSessionId(details: unknown): string | undefined;
+
+export declare type AgentConversationBoundaryReason = "assistant_text" | "user" | "spawn" | "custom" | "surface" | "other";
+
+export declare interface AgentConversationPeerGroup<TRef = unknown> {
+    readonly peerId: string;
+    readonly firstItemId: string;
+    readonly items: readonly AgentConversationSourceConversation<TRef>[];
+}
+
+export declare type AgentConversationResultStatus = RunSettlementOutcome;
+
+export declare interface AgentConversationRun<TRef = unknown> {
+    /** The first conversation item's id: stable while the run grows. */
+    readonly id: string;
+    /** Every conversation item, in canonical source order. */
+    readonly items: readonly AgentConversationSourceConversation<TRef>[];
+    /** Peers in first-appearance order. */
+    readonly peers: readonly AgentConversationPeerGroup<TRef>[];
+    /** Work strictly between two of this run's conversation items. */
+    readonly work: readonly AgentConversationRunWork[];
+}
+
+/** Work a run can own: a tool attempt or a folded narration, in source order. */
+declare type AgentConversationRunWork = AgentConversationSourceActivity | AgentConversationSourceNote;
+
+declare interface AgentConversationSourceActivity {
+    readonly kind: "activity";
+    readonly attemptId: string;
+    readonly rowKey: string;
+}
+
+declare interface AgentConversationSourceBoundary {
+    readonly kind: "boundary";
+    readonly id: string;
+    readonly reason: AgentConversationBoundaryReason;
+}
+
+export declare interface AgentConversationSourceConversation<TRef = unknown> {
+    readonly kind: "conversation";
+    /** Source identity: a tool attempt id (outbound) or message item id. */
+    readonly id: string;
+    readonly peerId: string;
+    readonly direction: "inbound" | "outbound" | "result";
+    readonly status?: AgentConversationResultStatus;
+    readonly rowKey: string;
+    readonly ref: TRef;
+}
+
+export declare type AgentConversationSourceItem<TRef = unknown> = AgentConversationSourceConversation<TRef> | AgentConversationRunWork | AgentConversationSourceBoundary;
+
+/** Narration that paints only inside a folded "Did work" rail. */
+declare interface AgentConversationSourceNote {
+    readonly kind: "note";
+    readonly id: string;
+    readonly rowKey: string;
+}
+
+export declare function groupAgentConversationStream<TRef>(stream: readonly AgentConversationSourceItem<TRef>[]): readonly AgentConversationRun<TRef>[];
+
+export declare function immediateFollowingAgentConversationWave<TAttempt extends {
+    readonly id: string;
+}>(run: AgentConversationRun<unknown>, waves: readonly (readonly TAttempt[])[], stream: readonly AgentConversationSourceItem[], order: ReadonlyMap<string, number>, sources: ReadonlyMap<string, {
+    readonly rowKey: string;
+}>, claimedWaveAttemptIds: ReadonlySet<string>): readonly TAttempt[] | undefined;
+
+/** Whether a run changes today's rendering: a pair (2+ items with one peer) or 2+ peers. */
+export declare function isFoldedAgentConversationRun(run: AgentConversationRun<unknown>): boolean;
+
+/** The received metadata that both work ownership and the conversation renderer recognize. */
+export declare function receivedConversation(customType: string | undefined, details: unknown): {
+    readonly peerId: string;
+    readonly direction: "inbound" | "result";
+    readonly status?: AgentConversationResultStatus;
+} | undefined;
+
+/** Terminal daemon-run outcomes shared by stored records and conversation results. */
+declare type RunSettlementOutcome = "completed" | "interrupted" | "cancelled" | "failed";
+
+export { }

package/dist/agent-conversation.js

@@ -0,0 +1,174 @@
+// packages/plugin-protocol/dist/agent-conversation.js
+function workId(work) {
+  return work.kind === "activity" ? work.attemptId : work.id;
+}
+function freezeRun(run) {
+  const peers = /* @__PURE__ */ new Map();
+  for (const item of run.items) {
+    const items = peers.get(item.peerId);
+    if (items === void 0)
+      peers.set(item.peerId, [item]);
+    else
+      items.push(item);
+  }
+  return {
+    id: run.items[0].id,
+    items: run.items,
+    peers: [...peers].map(([peerId, items]) => ({
+      peerId,
+      firstItemId: items[0].id,
+      items
+    })),
+    work: run.work
+  };
+}
+function groupAgentConversationStream(stream) {
+  const runs = [];
+  const claimed = /* @__PURE__ */ new Set();
+  let active;
+  let queued = [];
+  const close = () => {
+    if (active !== void 0)
+      runs.push(freezeRun(active));
+    active = void 0;
+    queued = [];
+  };
+  for (const item of stream) {
+    if (item.kind === "boundary") {
+      close();
+      continue;
+    }
+    if (item.kind === "activity" || item.kind === "note") {
+      if (active !== void 0)
+        queued.push(item);
+      continue;
+    }
+    if (active === void 0) {
+      active = { items: [item], work: [] };
+      continue;
+    }
+    for (const work of queued) {
+      if (claimed.has(workId(work)))
+        continue;
+      claimed.add(workId(work));
+      active.work.push(work);
+    }
+    queued = [];
+    active.items.push(item);
+  }
+  close();
+  return runs;
+}
+function immediateFollowingAgentConversationWave(run, waves, stream, order, sources, claimedWaveAttemptIds) {
+  if (run.work.length === 0)
+    return void 0;
+  const runIds = new Set(run.items.map((item) => item.id));
+  const end = Math.max(...run.items.map((item) => order.get(item.id) ?? -Infinity));
+  if (!Number.isFinite(end))
+    return void 0;
+  let candidate;
+  let candidateStart = Infinity;
+  for (const wave of waves) {
+    const followingAttempts = wave.filter((attempt) => {
+      const position = order.get(attempt.id);
+      return position !== void 0 && position > end && !claimedWaveAttemptIds.has(attempt.id);
+    });
+    if (followingAttempts.length === 0)
+      continue;
+    if (followingAttempts.some((attempt) => sources.get(attempt.id)?.rowKey !== run.items.at(-1)?.rowKey))
+      continue;
+    const start = Math.min(...followingAttempts.map((attempt) => order.get(attempt.id) ?? Infinity));
+    if (start < candidateStart) {
+      candidate = followingAttempts;
+      candidateStart = start;
+    }
+  }
+  if (candidate === void 0)
+    return void 0;
+  const waveIds = new Set(candidate.map((attempt) => attempt.id));
+  for (const item of stream) {
+    const position = order.get(item.kind === "activity" ? item.attemptId : item.id);
+    if (position === void 0 || position <= end || position >= candidateStart)
+      continue;
+    if (item.kind === "conversation" && !runIds.has(item.id))
+      return void 0;
+    if (item.kind !== "activity" && item.kind !== "conversation")
+      return void 0;
+    if (item.kind === "activity" && !waveIds.has(item.attemptId))
+      return void 0;
+  }
+  return candidate;
+}
+function isFoldedAgentConversationRun(run) {
+  return run.peers.length >= 2 || run.peers.some((peer) => peer.items.length >= 2);
+}
+function admittedSpawnSessionId(details) {
+  if (typeof details !== "object" || details === null)
+    return void 0;
+  const record = details;
+  const sessionId = typeof record["sessionId"] === "string" ? record["sessionId"] : record["accepted"] === true && typeof record["childSessionId"] === "string" ? record["childSessionId"] : void 0;
+  return sessionId === void 0 || sessionId.trim() === "" ? void 0 : sessionId.trim();
+}
+function admittedSendSessionId(details) {
+  if (typeof details !== "object" || details === null)
+    return void 0;
+  const record = details;
+  const sessionId = typeof record["sessionId"] === "string" ? record["sessionId"].trim() : "";
+  return sessionId && typeof record["rowId"] === "string" && record["rowId"] !== "" && typeof record["backgroundTaskId"] === "string" ? sessionId : void 0;
+}
+function receivedConversation(customType, details) {
+  if (typeof details !== "object" || details === null)
+    return void 0;
+  const record = details;
+  if (customType === "collaboration_message") {
+    const provenance2 = record["provenance"];
+    if (typeof record["senderSessionId"] !== "string" || record["kind"] !== "message" && record["kind"] !== "progress" || typeof provenance2 !== "object" || provenance2 === null)
+      return void 0;
+    const source = provenance2;
+    if (source["source"] !== "subagent" || typeof source["sourceId"] !== "string")
+      return void 0;
+    return { peerId: record["senderSessionId"], direction: "inbound" };
+  }
+  if (customType !== "subagent_result")
+    return void 0;
+  const provenance = subagentProvenanceOf(record);
+  const status = record["status"];
+  if (provenance === void 0 || provenance.sourceId === "" || status !== "completed" && status !== "failed" && status !== "cancelled" && status !== "interrupted")
+    return void 0;
+  return { peerId: provenance.sourceId, direction: "result", status };
+}
+function subagentProvenanceOf(record) {
+  const provenance = record["provenance"];
+  if (typeof provenance === "object" && provenance !== null) {
+    const p = provenance;
+    if (p["source"] === "subagent" && typeof p["sourceId"] === "string") {
+      const label = p["label"];
+      return {
+        source: "subagent",
+        sourceId: p["sourceId"],
+        ...typeof label === "string" ? { label } : {}
+      };
+    }
+  }
+  const attribution = record["attribution"];
+  if (typeof attribution === "object" && attribution !== null) {
+    const a = attribution;
+    if (a["kind"] === "subagent" && typeof a["childSessionId"] === "string") {
+      const label = a["label"];
+      return {
+        source: "subagent",
+        sourceId: a["childSessionId"],
+        ...typeof label === "string" ? { label } : {}
+      };
+    }
+  }
+  return void 0;
+}
+export {
+  admittedSendSessionId,
+  admittedSpawnSessionId,
+  groupAgentConversationStream,
+  immediateFollowingAgentConversationWave,
+  isFoldedAgentConversationRun,
+  receivedConversation
+};

package/dist/app-data.d.ts

@@ -0,0 +1,7 @@
+/** Maximum UTF-8 JSON size of one plugin app-data live change. */
+export declare const KAY_APP_DATA_CHANGE_MAX_BYTES: number;
+
+/** Maximum UTF-8 JSON size of one plugin app-data snapshot. */
+export declare const KAY_APP_DATA_SNAPSHOT_MAX_BYTES: number;
+
+export { }

package/dist/app-data.js

@@ -0,0 +1,9 @@
+// packages/plugin-protocol/dist/app-data.js
+var KAY_APP_DATA_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024;
+var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
+var KAY_APP_DATA_READ_REQUEST_MAX_BYTES = 64 * 1024;
+var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
+export {
+  KAY_APP_DATA_CHANGE_MAX_BYTES,
+  KAY_APP_DATA_SNAPSHOT_MAX_BYTES
+};

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.
@@ -4919,6 +4919,30 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         envelope: z.ZodObject<{
             binary: z.ZodString;
         }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"plugin">;
+        slug: z.ZodLiteral<"mcp.host-server">;
+        envelope: z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"plugin">;
+        slug: z.ZodLiteral<"prompt.resident">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"plugin">;
+        slug: z.ZodLiteral<"skills.declared-source">;
+        envelope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            channel: z.ZodLiteral<"git-clone">;
+            locator: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            subdir: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            channel: z.ZodLiteral<"installer">;
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>], "channel">;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodEnum<{
             "kay.agent": "kay.agent";
@@ -5518,8 +5542,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 +10138,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 +10146,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