@yaklabs-ai/plugin-sdk 0.53.0 → 0.54.0

package/dist/text-diff.js

@@ -0,0 +1,223 @@
+// packages/plugin-sdk/dist/text-clip.js
+function safeTailStart(text, start) {
+  const code = text.charCodeAt(start);
+  return code >= 56320 && code <= 57343 ? start + 1 : start;
+}
+function safeHeadEnd(text, end) {
+  const code = text.charCodeAt(end - 1);
+  return end > 0 && code >= 55296 && code <= 56319 ? end - 1 : end;
+}
+function headChars(text, max) {
+  return text.length <= max ? text : text.slice(0, safeHeadEnd(text, max));
+}
+function headAndTailChars(text, headMax, tailMax) {
+  if (text.length <= headMax + tailMax) {
+    return { head: text, tail: "", omitted: 0 };
+  }
+  const headEnd = safeHeadEnd(text, headMax);
+  const tailStart = safeTailStart(text, text.length - tailMax);
+  return {
+    head: text.slice(0, headEnd),
+    tail: text.slice(tailStart),
+    omitted: tailStart - headEnd
+  };
+}
+
+// packages/plugin-sdk/dist/text-diff.js
+var MAX_LCS_CELLS = 4e6;
+var isSpaceOrTab = (code) => code === 32 || code === 9;
+var isNewline = (code) => code === 10;
+function trimEndWhile(text, drop) {
+  let end = text.length;
+  while (end > 0 && drop(text.charCodeAt(end - 1)))
+    end -= 1;
+  return text.slice(0, end);
+}
+function normalizeDraftBody(text) {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n").map((line) => trimEndWhile(line, isSpaceOrTab));
+  return trimEndWhile(lines.join("\n"), isNewline);
+}
+function normalizeDraftSubject(subject) {
+  return subject === void 0 ? void 0 : subject.replace(/\s+/g, " ").trim();
+}
+function tokensOf(text) {
+  return text.match(/\s+|\S+/g) ?? [];
+}
+function wordCount(text) {
+  return text.split(/\s+/).filter((word) => word !== "").length;
+}
+function alignTokens(a, b) {
+  const rows = a.length;
+  const cols = b.length;
+  if (rows === 0 || cols === 0)
+    return [];
+  if ((rows + 1) * (cols + 1) > MAX_LCS_CELLS)
+    return void 0;
+  const width = cols + 1;
+  const table = new Uint32Array((rows + 1) * width);
+  for (let row2 = rows - 1; row2 >= 0; row2 -= 1) {
+    for (let col2 = cols - 1; col2 >= 0; col2 -= 1) {
+      table[row2 * width + col2] = a[row2] === b[col2] ? table[(row2 + 1) * width + col2 + 1] + 1 : Math.max(table[(row2 + 1) * width + col2], table[row2 * width + col2 + 1]);
+    }
+  }
+  const pairs = [];
+  let row = 0;
+  let col = 0;
+  while (row < rows && col < cols) {
+    if (a[row] === b[col]) {
+      pairs.push([row, col]);
+      row += 1;
+      col += 1;
+    } else if (table[(row + 1) * width + col] >= table[row * width + col + 1]) {
+      row += 1;
+    } else {
+      col += 1;
+    }
+  }
+  return pairs;
+}
+function pushSegment(segments, kind, text) {
+  if (text === "")
+    return;
+  const last = segments.at(-1);
+  if (last?.kind === kind) {
+    segments[segments.length - 1] = { kind, text: last.text + text };
+  } else {
+    segments.push({ kind, text });
+  }
+}
+function diffWords(before, after) {
+  const a = tokensOf(before);
+  const b = tokensOf(after);
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) {
+    start += 1;
+  }
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA -= 1;
+    endB -= 1;
+  }
+  const middleA = a.slice(start, endA);
+  const middleB = b.slice(start, endB);
+  const pairs = alignTokens(middleA, middleB);
+  const segments = [];
+  pushSegment(segments, "same", a.slice(0, start).join(""));
+  if (pairs === void 0) {
+    pushSegment(segments, "removed", middleA.join(""));
+    pushSegment(segments, "added", middleB.join(""));
+  } else {
+    let row = 0;
+    let col = 0;
+    for (const [matchedRow, matchedCol] of pairs) {
+      pushSegment(segments, "removed", middleA.slice(row, matchedRow).join(""));
+      pushSegment(segments, "added", middleB.slice(col, matchedCol).join(""));
+      pushSegment(segments, "same", middleA[matchedRow]);
+      row = matchedRow + 1;
+      col = matchedCol + 1;
+    }
+    pushSegment(segments, "removed", middleA.slice(row).join(""));
+    pushSegment(segments, "added", middleB.slice(col).join(""));
+  }
+  pushSegment(segments, "same", a.slice(endA).join(""));
+  let wordsRemoved = 0;
+  let wordsAdded = 0;
+  for (const segment of segments) {
+    if (segment.kind === "removed")
+      wordsRemoved += wordCount(segment.text);
+    if (segment.kind === "added")
+      wordsAdded += wordCount(segment.text);
+  }
+  return { wordsRemoved, wordsAdded, segments, coarse: pairs === void 0 };
+}
+function diffDraft(before, after) {
+  const beforeBody = normalizeDraftBody(before.body);
+  const afterBody = normalizeDraftBody(after.body);
+  const beforeSubject = normalizeDraftSubject(before.subject);
+  const afterSubject = normalizeDraftSubject(after.subject);
+  const subjectChanged = (beforeSubject ?? "") !== (afterSubject ?? "");
+  const bodyChanged = beforeBody !== afterBody;
+  const subjectDiff = subjectChanged ? diffWords(beforeSubject ?? "", afterSubject ?? "") : void 0;
+  const bodyDiff = bodyChanged ? diffWords(beforeBody, afterBody) : void 0;
+  return {
+    edited: subjectChanged || bodyChanged,
+    subjectChanged,
+    bodyChanged,
+    wordsAdded: (subjectDiff?.wordsAdded ?? 0) + (bodyDiff?.wordsAdded ?? 0),
+    wordsRemoved: (subjectDiff?.wordsRemoved ?? 0) + (bodyDiff?.wordsRemoved ?? 0),
+    beforeWords: wordCount(beforeSubject ?? "") + wordCount(beforeBody),
+    afterWords: wordCount(afterSubject ?? "") + wordCount(afterBody),
+    beforeChars: (beforeSubject ?? "").length + beforeBody.length,
+    afterChars: (afterSubject ?? "").length + afterBody.length,
+    coarse: subjectDiff?.coarse === true || bodyDiff?.coarse === true,
+    subjectDiff,
+    bodyDiff
+  };
+}
+function visible(text) {
+  if (text.trim() === "") {
+    return text.replace(/\n/g, "\u23CE").replace(/\t/g, "\u21E5").replace(/ /g, "\u2423");
+  }
+  return text.replace(/\n/g, "\u23CE\n");
+}
+function wordSpans(text) {
+  return [...text.matchAll(/\S+/g)].map((match) => ({
+    start: match.index ?? 0,
+    end: (match.index ?? 0) + match[0].length
+  }));
+}
+function contextOf(text, words, where) {
+  const spans = wordSpans(text);
+  if (spans.length <= words)
+    return { text, cut: false };
+  return where === "head" ? { text: text.slice(0, spans[words - 1].end), cut: true } : { text: text.slice(spans[spans.length - words].start), cut: true };
+}
+function renderWordDiff(diff, options = {}) {
+  const contextWords = options.contextWords ?? 8;
+  const maxChars = options.maxChars ?? 3e3;
+  if (diff.segments.every((segment) => segment.kind === "same")) {
+    return {
+      text: "(no word changed; only whitespace differs)",
+      truncated: false
+    };
+  }
+  const lastIndex = diff.segments.length - 1;
+  const parts = diff.segments.map((segment, index) => {
+    if (segment.kind === "removed")
+      return `[-${visible(segment.text)}-]`;
+    if (segment.kind === "added")
+      return `{+${visible(segment.text)}+}`;
+    const words = wordSpans(segment.text).length;
+    if (index === 0) {
+      const tail2 = contextOf(segment.text, contextWords, "tail");
+      return tail2.cut ? `\u2026 ${tail2.text}` : tail2.text;
+    }
+    if (index === lastIndex) {
+      const head2 = contextOf(segment.text, contextWords, "head");
+      return head2.cut ? `${head2.text} \u2026` : head2.text;
+    }
+    if (words <= contextWords * 2)
+      return segment.text;
+    const head = contextOf(segment.text, contextWords, "head").text;
+    const tail = contextOf(segment.text, contextWords, "tail").text;
+    return `${head} \u2026 ${tail}`;
+  });
+  const rendered = parts.join("");
+  return rendered.length <= maxChars ? { text: rendered, truncated: false } : {
+    text: `${headChars(rendered, maxChars)}\u2026`,
+    truncated: true
+  };
+}
+export {
+  MAX_LCS_CELLS,
+  diffDraft,
+  diffWords,
+  headAndTailChars,
+  headChars,
+  normalizeDraftBody,
+  normalizeDraftSubject,
+  renderWordDiff,
+  safeHeadEnd,
+  safeTailStart
+};

package/dist/transcript.d.ts

@@ -45,6 +45,17 @@ export declare function matchesWorkBlock(coverage: WorkBlockCoverage, toolResult
  */
 export declare const NON_ACTIVITY_TOOL_NAMES: readonly string[];
 
+/**
+ * The person's messages that precede a packet's opener on the same branch: the last `count`
+ * human-verified `role: "user"` messages before it, oldest first. Openers and steers of earlier
+ * turns both count; a message the transcript cannot attribute to a person does not.
+ *
+ * This is the rolling context a detector reads when it must interpret the opener in light of
+ * what the person said before (a rule amended in one message that was set in an earlier one).
+ * Pure, like {@link turnPacket}: the caller passes the same entries it built the packet from.
+ */
+export declare function precedingPersonMessages(entries: readonly TurnPacketEntry[], packet: TurnPacket, count: number): readonly TurnPacketMessage[];
+
 /**
  * What a run did to a URI. The words match the automation run wire's artifact actions. When one
  * run both creates and updates a URI, the reader reports `created`.
@@ -87,6 +98,36 @@ export declare const RUN_STARTED_CUSTOM_TYPE = "session_run_started";
  */
 export declare const RUN_TERMINAL_CUSTOM_TYPE = "session_run_state";
 
+export declare type SkillSuggestionEvidenceItem = SkillSuggestionEvidenceRef | {
+    readonly kind: "text";
+    readonly text: string;
+};
+
+export declare function skillSuggestionEvidenceItems(evidence: unknown, options?: SkillSuggestionEvidenceOptions): readonly SkillSuggestionEvidenceItem[];
+
+export declare interface SkillSuggestionEvidenceOptions {
+    readonly sessionIds?: readonly string[];
+}
+
+export declare type SkillSuggestionEvidenceRef = {
+    readonly kind: "message";
+    readonly sessionId: string;
+    readonly entryId: string;
+    readonly raw: string;
+} | {
+    readonly kind: "session";
+    readonly sessionId: string;
+    readonly raw: string;
+} | {
+    readonly kind: "friction";
+    readonly reference: string;
+    readonly raw: string;
+} | {
+    readonly kind: "uri";
+    readonly uri: string;
+    readonly raw: string;
+};
+
 /** The fields the customType selector needs off a session entry. */
 export declare interface TranscriptEntryLike {
     readonly id: string;
@@ -128,6 +169,83 @@ export declare interface TurnBoundaryEntry {
     readonly message?: unknown;
 }
 
+/**
+ * What the transcript can say about who wrote a message.
+ *
+ * Two values, not three: an earlier draft also declared `session-root` ("the session is a
+ * person-started root"), but nothing ever derived it, so the union advertised an answer this
+ * helper cannot give. A consumer needing session-level provenance reads the session's own
+ * stamps instead of a message's.
+ */
+export declare type TurnMessageOrigin = 
+/** The message carries both `clientIntentId` and `details.deliveryId`: a person typed it. */
+"human-verified"
+/** Neither the session nor the message establishes human authorship. */
+| "unknown";
+
+/**
+ * Who wrote one message, read from what the transcript carries: `clientIntentId` AND
+ * `details.deliveryId` mean a person typed it. The one definition the turn packet and every other
+ * reader of a message's authorship share.
+ */
+export declare function turnMessageOrigin(entry: Pick<TurnPacketEntry, "message">): TurnMessageOrigin;
+
+export declare interface TurnPacket {
+    /** The message that opened the turn. */
+    readonly personMessage: TurnPacketMessage;
+    /** Human steering messages that landed inside the run, oldest first. */
+    readonly personSteers: readonly TurnPacketMessage[];
+    /** The assistant's prose replies in order. Tool calls and results are excluded. */
+    readonly assistantReplies: readonly TurnPacketMessage[];
+    /** The settle anchor the caller supplied, so a consumer can re-derive the same packet. */
+    readonly settleEntryId: string;
+    /** The session's provenance tier, as the caller established it from the log's own stamps. */
+    readonly sessionTier: "root" | "spawned" | "unknown";
+}
+
+/**
+ * Shape the turn that settled at `settleEntryId` out of the raw entries on its branch.
+ *
+ * The walk is branch-aware: entries the active-branch walk excludes (rewound or abandoned
+ * forks) are never included. The settle anchor is folded onto the run it follows when it is a
+ * trailing bookkeeping entry, which is what a settle event points at. If the anchor names an
+ * entry the branch walk cannot reach, the packet is built from the branch's last message
+ * instead, and the anchor is preserved on the result for a consumer to notice the mismatch.
+ */
+export declare function turnPacket(entries: readonly TurnPacketEntry[], settleEntryId: string, options?: {
+    readonly sessionTier?: "root" | "spawned" | "unknown";
+}): TurnPacket | undefined;
+
+/** The fields the packet reads off one raw entry. Deliberately narrower than any repo type. */
+export declare interface TurnPacketEntry {
+    readonly id: string;
+    readonly parentId?: string | null;
+    readonly type: string;
+    readonly customType?: string;
+    /** Epoch milliseconds (pi's `EntryBase.timestamp`). */
+    readonly timestamp: number;
+    /**
+     * Typed as loosely as pi's own message union is wide: `content` is a string or a parts
+     * array depending on the role, and `details` is opaque JSON that the daemon stamps a
+     * `deliveryId` into. The packet reads both through guards rather than asking every caller
+     * to narrow first.
+     */
+    readonly message?: {
+        readonly role?: string;
+        readonly content?: unknown;
+        readonly clientIntentId?: unknown;
+        readonly details?: unknown;
+    };
+}
+
+export declare interface TurnPacketMessage {
+    readonly entryId: string;
+    /** Epoch milliseconds, as the transcript entry carries it. */
+    readonly timestamp: number;
+    readonly text: string;
+    readonly origin: TurnMessageOrigin;
+}
+
 /** 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. */

package/dist/transcript.js

@@ -133,6 +133,268 @@ function readProducedResourceDeclarations(details) {
     return MALFORMED;
   return { kind: "declared", resources: claimed };
 }
+
+// packages/plugin-protocol/dist/turn-packet.js
+var RUN_STARTED = "session_run_started";
+function textOf(entry) {
+  const content = entry.message?.content;
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content))
+    return "";
+  return content.map((part) => typeof part === "object" && part !== null && part.type === "text" && typeof part.text === "string" ? part.text : "").join("");
+}
+function turnMessageOrigin(entry) {
+  const m = entry.message;
+  if (m === void 0 || typeof m.clientIntentId !== "string")
+    return "unknown";
+  const details = m.details;
+  const deliveryId = typeof details === "object" && details !== null ? details.deliveryId : void 0;
+  return typeof deliveryId === "string" ? "human-verified" : "unknown";
+}
+function turnPacket(entries, settleEntryId, options = {}) {
+  const branch = branchEntryIds(entries);
+  const live = entries.filter((e) => branch.has(e.id));
+  const anchorIndex = live.findIndex((e) => e.id === settleEntryId);
+  const searchFrom = anchorIndex === -1 ? live.length - 1 : anchorIndex;
+  let runStart = -1;
+  for (let i = searchFrom; i >= 0; i -= 1) {
+    if (live[i]?.type === "custom" && live[i]?.customType === RUN_STARTED) {
+      runStart = i;
+      break;
+    }
+  }
+  let spanStart = runStart;
+  if (runStart === -1) {
+    spanStart = 0;
+    for (let i = searchFrom; i >= 0; i -= 1) {
+      if (live[i]?.type === "message" && live[i]?.message?.role === "user") {
+        spanStart = i;
+        break;
+      }
+    }
+  }
+  const span = live.slice(spanStart, searchFrom + 1);
+  const messages = span.filter((e) => e.type === "message" && e.message?.role !== void 0);
+  const people = messages.filter((e) => e.message?.role === "user");
+  const assistants = messages.filter((e) => e.message?.role === "assistant");
+  const opener = people[0];
+  if (opener === void 0)
+    return void 0;
+  const toPacket = (entry) => ({
+    entryId: entry.id,
+    timestamp: entry.timestamp,
+    text: textOf(entry),
+    origin: turnMessageOrigin(entry)
+  });
+  return {
+    personMessage: toPacket(opener),
+    personSteers: people.slice(1).map(toPacket),
+    assistantReplies: assistants.filter((e) => textOf(e).trim().length > 0).map(toPacket),
+    settleEntryId,
+    sessionTier: options.sessionTier ?? "unknown"
+  };
+}
+function precedingPersonMessages(entries, packet, count) {
+  if (count <= 0)
+    return [];
+  const branch = branchEntryIds(entries);
+  const live = entries.filter((e) => branch.has(e.id));
+  const openerIndex = live.findIndex((e) => e.id === packet.personMessage.entryId);
+  if (openerIndex === -1)
+    return [];
+  const found = [];
+  for (let i = openerIndex - 1; i >= 0 && found.length < count; i -= 1) {
+    const e = live[i];
+    if (e === void 0)
+      continue;
+    if (e.type !== "message" || e.message?.role !== "user")
+      continue;
+    if (turnMessageOrigin(e) !== "human-verified")
+      continue;
+    found.push({
+      entryId: e.id,
+      timestamp: e.timestamp,
+      text: textOf(e),
+      origin: "human-verified"
+    });
+  }
+  return found.reverse();
+}
+
+// packages/plugin-protocol/dist/skill-suggestion-evidence.js
+var UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+var UUID_ID = new RegExp(`^${UUID}$`, "i");
+var ENTRY = "[a-z0-9_-]+";
+var ENTRY_ID = new RegExp(`^${ENTRY}$`, "i");
+var FRICTION_URI = /^friction:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+var normalizeId = (value) => UUID_ID.test(value) ? value.toLowerCase() : value;
+function sessionPattern(options) {
+  const known = (options.sessionIds ?? []).filter((id) => ENTRY_ID.test(id) && !UUID_ID.test(id)).map((id) => id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return `(?:${[UUID, ...new Set(known)].join("|")})`;
+}
+function sessionRef(sessionId, entryId, raw) {
+  return entryId === void 0 ? { kind: "session", sessionId: normalizeId(sessionId), raw } : {
+    kind: "message",
+    sessionId: normalizeId(sessionId),
+    entryId: normalizeId(entryId),
+    raw
+  };
+}
+function parseToken(raw, sessions) {
+  if (/^sessions?:\/\//i.test(raw)) {
+    const match = /^sessions?:\/\/([^/?#]+)([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/i.exec(raw);
+    if (match === null)
+      return void 0;
+    const sessionId = match[1].replace(/\.jsonl$/i, "");
+    if (!new RegExp(`^${sessions}$`, "i").test(sessionId))
+      return void 0;
+    const path = match[2];
+    if (path !== "" && path !== "/" && !new RegExp(`^/${ENTRY}$`, "i").test(path))
+      return void 0;
+    const query = new URLSearchParams(match[3]);
+    const entryId = query.get("entry") ?? query.get("span") ?? query.get("from") ?? (path.length > 1 ? path.slice(1) : match[4]);
+    if (entryId !== void 0 && !ENTRY_ID.test(entryId))
+      return void 0;
+    return sessionRef(sessionId, entryId, raw);
+  }
+  if (/^friction:\/\//i.test(raw)) {
+    const reference = FRICTION_URI.exec(raw)?.[1];
+    return reference === void 0 || reference === "summary" ? void 0 : { kind: "friction", reference, raw };
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    return { kind: "uri", uri: raw, raw };
+  }
+  const message = new RegExp(`^(${sessions})(?:\\.jsonl)?(?:[/#](${ENTRY})(?:#[0-9]+)?)?$`, "i").exec(raw);
+  return message === null ? void 0 : sessionRef(message[1], message[2], raw);
+}
+function findSkillSuggestionCitations(text, options = {}) {
+  const sessions = sessionPattern(options);
+  const tokens = new RegExp(`(?<![\\w/.:#-])(?:[a-z][a-z0-9+.-]*://[^\\s<>\`"'|\\[\\]()]+|${sessions}(?:\\.jsonl)?(?:[/#]${ENTRY}(?:#[0-9]+)?)?(?![\\w/#-]))`, "gi");
+  const citations = [];
+  for (const match of text.matchAll(tokens)) {
+    const raw = match[0].replace(/[.,;:!?]+$/u, "");
+    if (new RegExp(`^${UUID}(?:#[0-9]+)?$`, "i").test(raw) && /\b(?:call|result)(?:\s*:\s*|\s+)$/i.test(text.slice(0, match.index)))
+      continue;
+    const ref = parseToken(raw, sessions);
+    if (ref !== void 0)
+      citations.push({
+        start: match.index,
+        end: match.index + raw.length,
+        ref
+      });
+  }
+  const sessionIds = new Set(citations.flatMap(({ ref }) => ref.kind === "message" || ref.kind === "session" && ref.raw.indexOf("://") >= 0 ? [ref.sessionId] : []));
+  if (sessionIds.size === 1) {
+    const sessionId = [...sessionIds][0];
+    const relative = new RegExp(`\\b(?:call|result)(?:\\s*:\\s*|\\s+)((?:${UUID}|[0-9a-f]{8,32}|[0-9]+)|${ENTRY}(?=#[0-9]+))(?:#[0-9]+)?(?![\\w/#-])`, "gi");
+    for (const match of text.matchAll(relative)) {
+      const start = match.index;
+      const end = start + match[0].length;
+      if (citations.some((item) => start < item.end && end > item.start))
+        continue;
+      citations.push({
+        start,
+        end,
+        ref: sessionRef(sessionId, match[1], match[0])
+      });
+    }
+  }
+  return citations.sort((a, b) => a.start - b.start);
+}
+function skillSuggestionEvidenceKey(item) {
+  switch (item.kind) {
+    case "message":
+      return `message:${item.sessionId}/${item.entryId}`;
+    case "session":
+      return `session:${item.sessionId}`;
+    case "friction":
+      return `friction:${item.reference}`;
+    case "uri":
+      return `uri:${item.uri}`;
+    case "text":
+      return `text:${item.text.trim()}`;
+  }
+}
+function skillSuggestionEvidenceItems(evidence, options = {}) {
+  const items = [];
+  const keys = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new WeakSet();
+  const add = (item) => {
+    const key = skillSuggestionEvidenceKey(item);
+    if (keys.has(key))
+      return;
+    keys.add(key);
+    items.push(item);
+  };
+  const text = (value) => {
+    const citations = findSkillSuggestionCitations(value, options);
+    if (citations.length === 0) {
+      if (value.trim() !== "")
+        add({ kind: "text", text: value });
+      return;
+    }
+    let cursor = 0;
+    const rest = [];
+    for (const citation of citations) {
+      rest.push(value.slice(cursor, citation.start));
+      cursor = citation.end;
+    }
+    rest.push(value.slice(cursor));
+    const note = rest.join(" ").trim();
+    if (citations.every(({ ref }) => ref.kind === "uri") && /[\p{L}\p{N}]/u.test(note)) {
+      add({ kind: "text", text: value });
+      return;
+    }
+    for (const citation of citations)
+      add(citation.ref);
+    if (/[\p{L}\p{N}]/u.test(note.replace(/\b(?:call|result|view|pointer|and)\b/gi, "")))
+      add({ kind: "text", text: note.replace(/^[\s|,;`]+|[\s|,;`]+$/g, "") });
+  };
+  const visit = (value, depth) => {
+    if (value === null || value === void 0)
+      return;
+    if (typeof value === "string")
+      return text(value);
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+      return text(String(value));
+    if (typeof value !== "object" || visited.has(value))
+      return;
+    visited.add(value);
+    if (depth >= 32) {
+      add({ kind: "text", text: "[evidence nested too deeply]" });
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const entry of value)
+        visit(entry, depth + 1);
+      return;
+    }
+    const object = value;
+    const sessionId = object.sessionId;
+    const entryId = object.entryId ?? object.messageId;
+    if (typeof sessionId === "string" && ENTRY_ID.test(sessionId) && (entryId === void 0 || typeof entryId === "string" && ENTRY_ID.test(entryId))) {
+      add(sessionRef(sessionId, entryId, `sessions://${sessionId}${entryId === void 0 ? "" : `/${entryId}`}`));
+      return;
+    }
+    if (object.kind === "text" && typeof object.text === "string") {
+      text(object.text);
+      return;
+    }
+    if (object.kind === "friction" && typeof object.reference === "string") {
+      text(`friction://${object.reference}`);
+      return;
+    }
+    if (object.kind === "uri" && typeof object.uri === "string") {
+      text(object.uri);
+      return;
+    }
+    for (const entry of Object.values(object))
+      visit(entry, depth + 1);
+  };
+  visit(evidence, 0);
+  return items;
+}
 export {
   ATTACHMENTS_CUSTOM_TYPE,
   NON_ACTIVITY_TOOL_NAMES,
@@ -145,7 +407,11 @@ export {
   branchEntryIds,
   customEntriesFromEntries,
   matchesWorkBlock,
+  precedingPersonMessages,
   readProducedResourceDeclarations,
+  skillSuggestionEvidenceItems,
+  turnMessageOrigin,
+  turnPacket,
   turnSegments,
   workBlockCoverage,
   workBlockKey

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -33,6 +33,10 @@
       "types": "./dist/fs.d.ts",
       "default": "./dist/fs.js"
     },
+    "./text-diff": {
+      "types": "./dist/text-diff.d.ts",
+      "default": "./dist/text-diff.js"
+    },
     "./kay-agent/testing": {
       "types": "./dist/kay-agent-testing.d.ts",
       "default": "./dist/kay-agent-testing.js"