@yaklabs-ai/plugin-sdk 0.52.1 → 0.54.0

package/dist/kay-app.js

@@ -308,6 +308,31 @@ function createUnavailableUriCaller(message) {
   };
 }
 
+// packages/plugin-protocol/dist/project-directories.js
+import { z as z5 } from "zod";
+var PluginProjectDirectories = z5.strictObject({
+  /** An endpoint this plugin's app target declares; called with a {@link ProjectDirectoryRequest}. */
+  endpoint: z5.string().min(1),
+  /** A scheme this plugin's URI modules serve; a project is addressed as `<scheme>://<id>`. */
+  scheme: z5.string().min(1)
+});
+var ProjectDirectoryRequest = z5.strictObject({
+  /** The project's stable id. */
+  id: z5.string().min(1)
+});
+var ProjectDirectory = z5.strictObject({
+  id: z5.string().min(1),
+  /** Absolute path of the project's folder. */
+  path: z5.string().min(1),
+  /** Absolute path a new session in this project starts in. */
+  defaultCwd: z5.string().min(1),
+  /** Ancestor project ids, root first. */
+  ancestorIds: z5.array(z5.string().min(1))
+});
+var ProjectDirectoryResponse = z5.strictObject({
+  project: ProjectDirectory.nullable()
+});
+
 // packages/plugin-sdk/dist/endpoints.js
 function createUnavailablePluginEndpointCaller(message) {
   return {
@@ -374,41 +399,48 @@ function isCredentialShapedText(value) {
   return CREDENTIAL_VALUE_PATTERNS.some((pattern) => pattern.test(value));
 }
 
+// packages/plugin-protocol/dist/resource-invocation-cursor.js
+import { z as z6 } from "zod";
+var CorpusResourceInvocationCursor = z6.strictObject({
+  at: z6.iso.datetime({ offset: true }),
+  eventId: z6.string().min(1)
+});
+
 // packages/plugin-protocol/dist/json.js
-import { z as z5 } from "zod";
-var JsonValue = z5.lazy(() => z5.union([
-  z5.string(),
-  z5.number(),
-  z5.boolean(),
-  z5.null(),
-  z5.array(JsonValue),
-  z5.record(z5.string(), JsonValue)
+import { z as z7 } from "zod";
+var JsonValue = z7.lazy(() => z7.union([
+  z7.string(),
+  z7.number(),
+  z7.boolean(),
+  z7.null(),
+  z7.array(JsonValue),
+  z7.record(z7.string(), JsonValue)
 ]));
-var JsonObject = z5.record(z5.string(), JsonValue);
-var JsonSchema = z5.record(z5.string(), JsonValue);
+var JsonObject = z7.record(z7.string(), JsonValue);
+var JsonSchema = z7.record(z7.string(), JsonValue);
 
 // packages/plugin-protocol/dist/shell-commands.js
-import { z as z6 } from "zod";
-var PluginShellCommand = z6.strictObject({
-  name: z6.string().regex(/^[a-z][a-z0-9-]*$/),
-  aliases: z6.array(z6.string().regex(/^[a-z][a-z0-9-]*$/)).optional(),
-  endpoint: z6.string().min(1),
-  usage: z6.string().min(1)
+import { z as z8 } from "zod";
+var PluginShellCommand = z8.strictObject({
+  name: z8.string().regex(/^[a-z][a-z0-9-]*$/),
+  aliases: z8.array(z8.string().regex(/^[a-z][a-z0-9-]*$/)).optional(),
+  endpoint: z8.string().min(1),
+  usage: z8.string().min(1)
 });
-var ShellCommandOutcome = z6.strictObject({
-  exitCode: z6.number().int(),
+var ShellCommandOutcome = z8.strictObject({
+  exitCode: z8.number().int(),
   envelope: JsonValue,
   result: JsonValue.optional()
 });
-var ShellCommandRequest = z6.strictObject({
-  argv: z6.array(z6.string()),
-  cwd: z6.string(),
-  outcomes: z6.array(ShellCommandOutcome).max(3)
+var ShellCommandRequest = z8.strictObject({
+  argv: z8.array(z8.string()),
+  cwd: z8.string(),
+  outcomes: z8.array(ShellCommandOutcome).max(3)
 });
-var ShellCommandStep = z6.discriminatedUnion("kind", [
-  z6.strictObject({
-    kind: z6.literal("invoke"),
-    toolName: z6.enum([
+var ShellCommandStep = z8.discriminatedUnion("kind", [
+  z8.strictObject({
+    kind: z8.literal("invoke"),
+    toolName: z8.enum([
       "read",
       "list",
       "search",
@@ -417,13 +449,13 @@ var ShellCommandStep = z6.discriminatedUnion("kind", [
       "delete",
       "help"
     ]),
-    input: z6.record(z6.string(), JsonValue),
-    flags: z6.record(z6.string(), z6.string())
+    input: z8.record(z8.string(), JsonValue),
+    flags: z8.record(z8.string(), z8.string())
   }),
-  z6.strictObject({
-    kind: z6.literal("finish"),
-    exitCode: z6.number().int(),
-    stdout: z6.string()
+  z8.strictObject({
+    kind: z8.literal("finish"),
+    exitCode: z8.number().int(),
+    stdout: z8.string()
   })
 ]);
 
@@ -487,7 +519,7 @@ function submit(label) {
 }
 
 // packages/plugin-sdk/dist/signals.js
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 function createFallbackOnlySignals() {
   const noStore = { status: "unavailable", reason: "no-store" };
   return {
@@ -517,23 +549,23 @@ var POINTER = /^[^\s\p{C}/?#]+$/u;
 var LABEL = /^[^\s,@\p{C}]+(?: [^\s,@\p{C}]+)*$/u;
 var RUN_ID = /^\P{Cc}+$/u;
 var POINTER_RULE = `1 to ${MAX_POINTER} characters with no whitespace, \`/\`, \`?\`, \`#\`, or control or invisible character`;
-var ObserveShape = z7.looseObject({
-  detector: z7.looseObject({ id: z7.string(), version: z7.string() }),
-  subject: z7.looseObject({ kind: z7.string(), key: z7.string().optional() }).optional(),
-  after: z7.looseObject({ observationId: z7.unknown() }).optional(),
-  reuse: z7.looseObject({ maxAgeMs: z7.unknown() }).optional(),
-  source: z7.looseObject({
-    sessionId: z7.string(),
-    entryId: z7.string(),
-    openerEntryId: z7.string().optional(),
-    runId: z7.string().optional(),
-    occurredAtMs: z7.unknown().optional()
+var ObserveShape = z9.looseObject({
+  detector: z9.looseObject({ id: z9.string(), version: z9.string() }),
+  subject: z9.looseObject({ kind: z9.string(), key: z9.string().optional() }).optional(),
+  after: z9.looseObject({ observationId: z9.unknown() }).optional(),
+  reuse: z9.looseObject({ maxAgeMs: z9.unknown() }).optional(),
+  source: z9.looseObject({
+    sessionId: z9.string(),
+    entryId: z9.string(),
+    openerEntryId: z9.string().optional(),
+    runId: z9.string().optional(),
+    occurredAtMs: z9.unknown().optional()
   }),
-  questions: z7.record(z7.string(), z7.unknown())
+  questions: z9.record(z9.string(), z9.unknown())
 });
-var ChoiceQuestion = z7.looseObject({
-  type: z7.literal("choice"),
-  criteria: z7.record(z7.string(), z7.unknown())
+var ChoiceQuestion = z9.looseObject({
+  type: z9.literal("choice"),
+  criteria: z9.record(z9.string(), z9.unknown())
 });
 var fits = (value, grammar) => value.length <= MAX_NAME && grammar.test(value);
 var isWhole = (value, min) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= SIGNAL_TIME_MAX_MS;
@@ -613,10 +645,10 @@ function grammarProblem(input) {
   }
   return void 0;
 }
-var EchoText = z7.string().catch("");
-var Echo = z7.object({
-  detector: z7.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
-  source: z7.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
+var EchoText = z9.string().catch("");
+var Echo = z9.object({
+  detector: z9.object({ id: EchoText, version: EchoText }).catch({ id: "", version: "" }),
+  source: z9.object({ sessionId: EchoText, entryId: EchoText }).catch({ sessionId: "", entryId: "" })
 }).catch({
   detector: { id: "", version: "" },
   source: { sessionId: "", entryId: "" }
@@ -1121,6 +1153,7 @@ 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 {
+  CorpusResourceInvocationCursor,
   JsonSchema,
   JsonValue,
   KAY_APP_AUTOMATION_CONDITION_KINDS,
@@ -1140,6 +1173,9 @@ export {
   PLUGIN_SIGNAL_RELATED_KEYS,
   PLUGIN_SIGNAL_SNIPPET_MAX,
   PLUGIN_SIGNAL_TITLE_MAX,
+  ProjectDirectory,
+  ProjectDirectoryRequest,
+  ProjectDirectoryResponse,
   SIGNAL_TIME_MAX_MS,
   STORED_TRANSCRIPT_MESSAGE_FILTER,
   STORED_TRANSCRIPT_MESSAGE_KINDS,

package/dist/text-diff.d.ts

@@ -0,0 +1,106 @@
+/** What changed between the texts the card showed and the texts the person sent. */
+export declare function diffDraft(before: DraftTexts, after: DraftTexts): DraftChange;
+
+declare interface DiffSegment {
+    readonly kind: DiffSegmentKind;
+    readonly text: string;
+}
+
+declare type DiffSegmentKind = "same" | "removed" | "added";
+
+/** Compare two texts word by word. Callers normalize first; this compares what it is given. */
+export declare function diffWords(before: string, after: string): WordDiff;
+
+export declare interface DraftChange {
+    /** The normalized subject or body differ. A change in whitespace alone counts. */
+    readonly edited: boolean;
+    readonly subjectChanged: boolean;
+    readonly bodyChanged: boolean;
+    /** Words across subject and body; zero for an edit that only moved whitespace. */
+    readonly wordsAdded: number;
+    readonly wordsRemoved: number;
+    /**
+     * Words across subject and body of the draft as proposed and of the message as sent, counted the
+     * way `wordsRemoved` and `wordsAdded` are. `(beforeWords - wordsRemoved) / beforeWords` is the
+     * share of the proposed draft that was kept.
+     */
+    readonly beforeWords: number;
+    readonly afterWords: number;
+    readonly beforeChars: number;
+    readonly afterChars: number;
+    /**
+     * Either part's changed span was too long to align, so it counts as one removed block and one
+     * added block: `wordsRemoved` is then an upper bound and the share kept a lower bound.
+     */
+    readonly coarse: boolean;
+    readonly subjectDiff: WordDiff | undefined;
+    readonly bodyDiff: WordDiff | undefined;
+}
+
+export declare interface DraftTexts {
+    readonly subject: string | undefined;
+    readonly body: string;
+}
+
+/** Both ends of a text too long to show whole, and how much lay between them. */
+export declare interface HeadAndTail {
+    readonly head: string;
+    readonly tail: string;
+    /** UTF-16 units left out between `head` and `tail`; `0` when the text fit and `head` is all of it. */
+    readonly omitted: number;
+}
+
+/**
+ * The first `headMax` and the last `tailMax` UTF-16 units of `text`, each cut on a character
+ * boundary. Text that fits in `headMax + tailMax` comes back whole as `head`, with nothing omitted.
+ *
+ * For text whose ASK sits at the end (a reply that closes on a question) as well as its framing at
+ * the start: a head-only cut keeps the framing and loses the ask.
+ */
+export declare function headAndTailChars(text: string, headMax: number, tailMax: number): HeadAndTail;
+
+/** At most `max` UTF-16 units from the start of `text`, never ending inside a surrogate pair. */
+export declare function headChars(text: string, max: number): string;
+
+/** The most cells the alignment table may hold (about 2,000 tokens a side, 16 MB of Uint32). */
+export declare const MAX_LCS_CELLS = 4000000;
+
+/**
+ * Line endings, trailing whitespace on each line and trailing blank lines are not edits: a text
+ * area and a saved file disagree on them without the person touching a word.
+ */
+export declare function normalizeDraftBody(text: string): string;
+
+/** A subject is one line: any whitespace run is one space and the ends are trimmed. */
+export declare function normalizeDraftSubject(subject: string | undefined): string | undefined;
+
+/**
+ * The diff as one marked text: `[-removed-]` and `{+added+}` inside the unchanged words around
+ * them, with a long unchanged stretch collapsed to its edges and an ellipsis. The unmarked parts
+ * are the original wording, so the result reads as the final text with the edits shown.
+ */
+export declare function renderWordDiff(diff: WordDiff, options?: {
+    readonly contextWords?: number;
+    readonly maxChars?: number;
+}): {
+    readonly text: string;
+    readonly truncated: boolean;
+};
+
+/** The end index of a head that does not end inside a surrogate pair. */
+export declare function safeHeadEnd(text: string, end: number): number;
+
+/** The start index of a tail that does not begin inside a surrogate pair. */
+export declare function safeTailStart(text: string, start: number): number;
+
+export declare interface WordDiff {
+    /** Non-whitespace words present before and gone after. */
+    readonly wordsRemoved: number;
+    /** Non-whitespace words present after and not before. */
+    readonly wordsAdded: number;
+    readonly segments: readonly DiffSegment[];
+    /** The middle was too large to align, so it is one removed block and one added block. */
+    readonly coarse: boolean;
+}
+
+export { }

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. */