@yaklabs-ai/plugin-sdk 0.15.3 → 0.27.0

package/dist/kay-app.js

@@ -163,6 +163,94 @@ function invalidObservation(input) {
   };
 }
 
+// packages/herd-transcript/dist/record-kinds.js
+var STORED_TRANSCRIPT_MESSAGE_KINDS = [
+  "user",
+  "assistant",
+  "tool_result",
+  "custom_message:*",
+  "compaction",
+  "branch_summary"
+];
+var NAMED_KINDS = /* @__PURE__ */ new Set([
+  "user",
+  "assistant",
+  "tool_result",
+  "compaction",
+  "branch_summary",
+  "other",
+  "unreadable"
+]);
+var ROLE_KINDS = {
+  user: "user",
+  assistant: "assistant",
+  toolResult: "tool_result"
+};
+function storedTranscriptKindOf(record) {
+  if (!("entry" in record))
+    return "unreadable";
+  const entry = record.entry;
+  switch (entry.type) {
+    case "message": {
+      const message = entry.message;
+      if (message.role === "custom") {
+        return `custom_message:${typeof message.customType === "string" ? message.customType : ""}`;
+      }
+      return (typeof message.role === "string" ? ROLE_KINDS[message.role] : void 0) ?? "other";
+    }
+    case "custom":
+      return `custom:${entry.customType}`;
+    case "compaction":
+      return "compaction";
+    case "branch_summary":
+      return "branch_summary";
+    default:
+      return "other";
+  }
+}
+function parseStoredTranscriptKindFilter(tokens) {
+  const exact = /* @__PURE__ */ new Set();
+  const families = /* @__PURE__ */ new Set();
+  let all = false;
+  for (const raw of tokens) {
+    const token = raw.trim();
+    if (token === "all") {
+      all = true;
+    } else if (token === "messages") {
+      for (const kind of STORED_TRANSCRIPT_MESSAGE_KINDS)
+        addToken(kind);
+    } else if (!addToken(token)) {
+      return { ok: false, invalid: raw };
+    }
+  }
+  return {
+    ok: true,
+    filter: {
+      includes: (kind) => all || exact.has(kind) || families.has(kind.slice(0, kind.indexOf(":") + 1))
+    }
+  };
+  function addToken(token) {
+    if (NAMED_KINDS.has(token)) {
+      exact.add(token);
+      return true;
+    }
+    const family = /^(custom|custom_message):(.+)$/.exec(token);
+    if (family === null)
+      return false;
+    if (family[2] === "*")
+      families.add(`${family[1]}:`);
+    else
+      exact.add(token);
+    return true;
+  }
+}
+var STORED_TRANSCRIPT_MESSAGE_FILTER = (() => {
+  const parsed = parseStoredTranscriptKindFilter(STORED_TRANSCRIPT_MESSAGE_KINDS);
+  if (!parsed.ok)
+    throw new Error(`invalid default kinds: ${parsed.invalid}`);
+  return parsed.filter;
+})();
+
 // packages/plugin-sdk/dist/kay-app/index.js
 import { pathToFileURL } from "node:url";
 
@@ -190,6 +278,15 @@ var UriValidationError = class extends UriError {
     this.name = "UriValidationError";
   }
 };
+function requireWriteContent(payload2, uri) {
+  if (payload2 === void 0) {
+    throw new UriValidationError(`Writing ${uri} needs \`content\` (or a \`source\` to copy from): pass the payload this address takes, which its help names.`);
+  }
+  if (payload2 instanceof Uint8Array) {
+    throw new UriValidationError(`${uri} stores text only, so it cannot take raw bytes. Copy the file to an address that accepts bytes.`);
+  }
+  return payload2;
+}
 var UriProviderError = class extends UriError {
   _tag = "UriProviderError";
   moduleId;
@@ -202,6 +299,8 @@ var UriProviderError = class extends UriError {
   retryAfterMs;
   /** See {@link UriProviderErrorOptions.effect}. */
   effect;
+  /** See {@link UriProviderErrorOptions.refusalMessage}. */
+  refusalMessage;
   constructor(options) {
     super(options.message);
     this.name = "UriProviderError";
@@ -222,6 +321,12 @@ var UriProviderError = class extends UriError {
     }
     if (options.effect !== void 0)
       this.effect = options.effect;
+    if (options.refusalMessage !== void 0) {
+      if (options.effect !== "none") {
+        throw new TypeError('refusalMessage requires effect: "none".');
+      }
+      this.refusalMessage = options.refusalMessage;
+    }
   }
 };
 var UriNotFoundError = class extends UriError {
@@ -400,7 +505,7 @@ function toJsonSchema(schema) {
       // `io: "input"` describes what a caller may SEND, which is what a parameter and an
       // `accepts` payload advertise: a field with a Zod default is optional on the wire even
       // though the parsed value always carries it. Strictness still survives where the validator
-      // really enforces it — `z.strictObject` emits `additionalProperties: false`, while a plain
+      // really enforces it - `z.strictObject` emits `additionalProperties: false`, while a plain
       // `z.object` correctly does not, because it TOLERATES unknown keys and silently strips
       // them. A `returns` payload derived from a Zod schema is described in the same input terms;
       // no module does that today, and a faithful output projection would need its own seam.
@@ -440,6 +545,28 @@ function isRetryable(result) {
   return result.status === "not-ready";
 }
 
+// packages/plugin-sdk/dist/kay-app/auth.js
+var KayAppCredentialRejectedError = class extends Error {
+  name = "KayAppCredentialRejectedError";
+};
+async function withCredential(auth, request, use) {
+  const candidates = await auth.resolveCandidates(request);
+  let rejection;
+  for (const credential of candidates) {
+    try {
+      const result = await use(credential);
+      await auth.reportWorked(request, credential.schemeId).catch(() => {
+      });
+      return result;
+    } catch (error) {
+      if (!(error instanceof KayAppCredentialRejectedError))
+        throw error;
+      rejection = error;
+    }
+  }
+  throw rejection ?? new Error(`No credential is resolvable for '${request.serviceId}'.`);
+}
+
 // packages/plugin-sdk/dist/kay-app/automations.js
 var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "time",
@@ -449,6 +576,46 @@ var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "delayed-occurrence"
 ];
 
+// packages/plugin-sdk/dist/log.js
+function createKayPluginLog(write, bound = {}) {
+  const at = (level) => (name, message, details) => {
+    try {
+      write({
+        level,
+        name,
+        message,
+        ...details?.error === void 0 ? {} : { error: details.error },
+        ...details?.sessionId === void 0 ? {} : { sessionId: details.sessionId },
+        attributes: { ...bound, ...details?.attributes }
+      });
+    } catch {
+    }
+  };
+  return {
+    debug: at("debug"),
+    info: at("info"),
+    warn: at("warn"),
+    error: at("error"),
+    child: (attributes) => createKayPluginLog(write, { ...bound, ...attributes })
+  };
+}
+function createConsoleKayPluginLog(pluginId) {
+  const prefix = pluginId === void 0 ? "" : `${pluginId}.`;
+  return createKayPluginLog((line) => {
+    const args = [`[${prefix}${line.name}] ${line.message}`];
+    if (Object.keys(line.attributes).length > 0)
+      args.push(line.attributes);
+    if (line.error !== void 0)
+      args.push(line.error);
+    console[line.level](...args);
+  });
+}
+
+// packages/plugin-sdk/dist/kay-app/model-selection.js
+var KAY_APP_MODEL_SELECTION_START_BOUND_MS = 2e3;
+var KAY_APP_MODEL_SELECTION_RESPONSE_BOUND_MS = 6e3;
+var KAY_APP_MODEL_SELECTION_SEND_BOUND_MS = 4e3;
+
 // packages/plugin-sdk/dist/kay-app/poller.js
 function accountCursors(state) {
   if (state === void 0)
@@ -482,7 +649,7 @@ function plainText(value, max) {
   return text;
 }
 function definePoller(app, localId, options) {
-  const { workflows, auth, events } = app;
+  const { workflows, auth, backgroundAuth, events } = app;
   if (!workflows)
     throw new Error("Poller requires workflows");
   if (!Number.isSafeInteger(options.every) || options.every <= 0) {
@@ -498,6 +665,8 @@ function definePoller(app, localId, options) {
     async run(ctx) {
       if (!auth)
         throw new Error("Poller requires account listing");
+      if (!backgroundAuth)
+        throw new Error("Poller requires background auth");
       const previous = accountCursors(ctx.state);
       const accounts = await ctx.runStep(async () => {
         const listed = await auth.listAccounts({
@@ -523,7 +692,12 @@ function definePoller(app, localId, options) {
           }
           let credential;
           try {
-            credential = await options.resolveCredential(account, ctx.runId);
+            credential = await backgroundAuth.resolveCredential({
+              serviceId: options.serviceId,
+              schemeId: account.schemeId,
+              accountId: account.accountId,
+              jobId: ctx.runId
+            });
           } catch {
             throw new Error("Poller credential resolution failed");
           }
@@ -597,6 +771,15 @@ function definePoller(app, localId, options) {
   });
 }
 
+// packages/plugin-sdk/dist/kay-app/sealing.js
+var KAY_APP_SEALING_MAX_BYTES = 1048576;
+function createUnavailableSealing(message) {
+  return {
+    seal: async () => ({ status: "unavailable", message }),
+    open: async () => ({ status: "unavailable", message })
+  };
+}
+
 // packages/plugin-sdk/dist/kay-app/skills.js
 function createUnavailableSkills(message) {
   const unavailable = {
@@ -605,9 +788,38 @@ function createUnavailableSkills(message) {
     message
   };
   return {
+    propose: async () => {
+      throw new Error(message);
+    },
     list: async () => unavailable,
     read: async () => unavailable,
-    history: async () => unavailable
+    history: async () => unavailable,
+    diff: async () => unavailable,
+    revision: async () => unavailable,
+    writeFile: async () => {
+      throw new Error(message);
+    },
+    install: async () => {
+      throw new Error(message);
+    },
+    delete: async () => {
+      throw new Error(message);
+    },
+    sourceContributors: async () => {
+      throw new Error(message);
+    },
+    setMarketplaceAdded: async () => {
+      throw new Error(message);
+    },
+    shareDestinations: async () => {
+      throw new Error(message);
+    },
+    prepareShare: async () => {
+      throw new Error(message);
+    },
+    confirmShare: async () => {
+      throw new Error(message);
+    }
   };
 }
 
@@ -649,7 +861,8 @@ function transcriptRoleLabel(role) {
 // packages/plugin-sdk/dist/kay-app/usage.js
 function createUnavailableUsage(message) {
   return {
-    uriActivity: async () => ({ status: "unavailable", message })
+    uriActivity: async () => ({ status: "unavailable", message }),
+    skillInvocations: async () => ({ status: "unavailable", message })
   };
 }
 
@@ -677,15 +890,25 @@ export {
   KAY_APP_AUTOMATION_CONDITION_KINDS,
   KAY_APP_DATA_CHANGE_MAX_BYTES,
   KAY_APP_DATA_SNAPSHOT_MAX_BYTES,
+  KAY_APP_MODEL_SELECTION_RESPONSE_BOUND_MS,
+  KAY_APP_MODEL_SELECTION_SEND_BOUND_MS,
+  KAY_APP_MODEL_SELECTION_START_BOUND_MS,
+  KAY_APP_SEALING_MAX_BYTES,
+  KayAppCredentialRejectedError,
   KayAppWorkflowFailure,
   MAX_CHOICE_LABELS,
   SIGNAL_TIME_MAX_MS,
+  STORED_TRANSCRIPT_MESSAGE_FILTER,
+  STORED_TRANSCRIPT_MESSAGE_KINDS,
   UriConflictError,
   UriNotFoundError,
   UriProviderError,
   UriUnsupportedOperationError,
   UriValidationError,
+  createConsoleKayPluginLog,
   createFallbackOnlySignals,
+  createKayPluginLog,
+  createUnavailableSealing,
   createUnavailableSkills,
   createUnavailableTools,
   createUnavailableUsage,
@@ -694,9 +917,13 @@ export {
   invalidObservation,
   isRetryable,
   parseLineSelector,
+  parseStoredTranscriptKindFilter,
   pathToFileURL,
   payload,
+  requireWriteContent,
+  storedTranscriptKindOf,
   transcriptMessageText,
   transcriptMessageTexts,
-  transcriptRoleLabel
+  transcriptRoleLabel,
+  withCredential
 };

package/dist/phase-shift.d.ts

@@ -28,7 +28,7 @@ declare type PhaseShiftCost = z.infer<typeof phaseShiftCostSchema>;
  * the feature accounts for itself.
  *
  * Absent on a record written before the detector accounted for itself, and on
- * a call no attempt priced — absence means "not recorded", never zero.
+ * a call no attempt priced - absence means "not recorded", never zero.
  */
 declare const phaseShiftCostSchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
@@ -45,7 +45,7 @@ declare const phaseShiftCostSchema: z.ZodObject<{
 /** One accepted transition, placed in time. */
 export declare interface PhaseShiftTimelineChange {
     readonly startEntryId: string;
-    /** When the new work began — the onset entry's own timestamp, not the judgment's. */
+    /** When the new work began - the onset entry's own timestamp, not the judgment's. */
     readonly startedAt: string;
     readonly relation: "outcome" | "phase";
     readonly reason: string;
@@ -69,7 +69,7 @@ export declare function phaseShiftTimelineFromEntries(entries: readonly Transcri
  *
  * A record is evidence about the span it names and nothing else: time outside
  * every record's `[windowStartAt, throughAt]` is unobserved, which is not the
- * same as unchanged. An empty `changes` is the opposite — a check that ran and
+ * same as unchanged. An empty `changes` is the opposite - a check that ran and
  * found no transition.
  */
 export declare interface PhaseShiftTimelineRecord {
@@ -100,7 +100,7 @@ declare interface TranscriptEntryLike {
     readonly id: string;
     readonly type: string;
     readonly customType?: string;
-    /** Opaque. Never parsed or validated here — a feature's own schema owns that. */
+    /** Opaque. Never parsed or validated here - a feature's own schema owns that. */
     readonly data?: unknown;
 }
 

package/dist/system-one.d.ts

@@ -231,12 +231,25 @@ export declare interface SystemOneAvailability {
     readonly cause?: SystemOneFailureCause;
 }
 
+/** Structurally the plugin SDK's `KayAppSessionEventCause`: only the fields the host reads. */
+declare interface SystemOneCallCause {
+    readonly kind?: "session-event" | "backfill";
+    readonly handler: string;
+    readonly sourceSessionId: string;
+}
+
 export declare interface SystemOneCallOptions {
     readonly signal?: AbortSignal;
     /** Bounds the whole call, retries included. */
     readonly timeoutMs?: number;
     /** What the call is for, carried to the host's usage accounting. Never sent to a provider. */
     readonly purpose?: string;
+    /**
+     * The session event a plugin's call answers, so the host charges the call to that session.
+     * The host checks the plugin is handling that session's event right now. Never sent to a
+     * provider.
+     */
+    readonly cause?: SystemOneCallCause;
 }
 
 export declare interface SystemOneClient {

package/dist/time.d.ts

@@ -17,7 +17,7 @@ export declare function isValidZone(id: unknown): boolean;
 /**
  * `app.time` / `api.time`: host facts about time. Added to `kay.app` in SDK 0.12.1 and to
  * `kay.agent` with the calendar zone-of-record work: a plugin that calls it declares
- * `compatibility.sdk` `^0.12.1`, so an older Bonsai refuses a directory or repository plugin at
+ * `compatibility.sdk` `^0.19.0`, so an older Bonsai refuses a directory or repository plugin at
  * load instead of the call failing.
  */
 export declare interface KayAppTime {
@@ -27,9 +27,7 @@ export declare interface KayAppTime {
      * Every call asks the host again and returns a new object; nothing is cached. Call it where you
      * need the value (inside a tool, a handler or a workflow step), not inside `activate()`: a value
      * read there is as old as the activation, and the host can run a bundled plugin's `activate()`
-     * against a recording api that has no `time`, so a read there throws. The exception is a
-     * directory plugin that declares a workflow with a cron `timezone`: `workflows.define` is legal
-     * only during `activate()`, so it reads the zone there, and the schedule then keeps that zone.
+     * against a recording api that has no `time`, so a read there throws.
      * Keep the result for as long as you use it, and not across a long wait (a sleep, a timer, a
      * queued run): the zone can change while you wait. On a daemon that runs on the user's machine,
      * a change of the process's `TZ` shows in the next call. A `TZ` that names a zone wins over the

package/dist/transcript-review.d.ts

@@ -152,6 +152,16 @@ export declare interface TranscriptReview {
         readonly start: number;
         readonly end: number;
     } | undefined;
+    /**
+     * The run whose own extent holds this position, the one starting latest; among runs that
+     * start at the same position, the first in run order. Undefined before the first run and at
+     * or after the end.
+     */
+    runAt(position: number): {
+        readonly runId: string;
+        readonly start: number;
+        readonly end: number;
+    } | undefined;
     /** The run input carrying this input id. */
     inputById(inputId: string): TranscriptReviewRunInput | undefined;
     attemptAt(position: number, block: number): ToolCallAttempt | undefined;

package/dist/transcript-review.js

@@ -533,43 +533,98 @@ function createTranscriptReview(options = {}) {
     }
     starts.sort((left, right) => left.boundary - right.boundary);
     const runStarts = [...finalRuns.values()].map((run) => ({ runId: run.runId, boundary: run.boundary })).sort((left, right) => left.boundary - right.boundary);
+    const runEndAt = Array.from({ length: runStarts.length });
+    for (let at = runStarts.length - 1; at >= 0; at -= 1) {
+      const next = runStarts[at + 1];
+      runEndAt[at] = next === void 0 ? endPosition : next.boundary > runStarts[at].boundary ? next.boundary : runEndAt[at + 1];
+    }
+    const runStartIndex = /* @__PURE__ */ new Map();
+    runStarts.forEach((run, at) => runStartIndex.set(run.runId, at));
+    const lastProseBefore = [];
+    let lastProse;
+    for (const record of records) {
+      lastProseBefore.push(lastProse);
+      if (record.hasProse)
+        lastProse = record.position;
+    }
     const previousProse = (before) => {
-      let index = byPosition.get(before);
-      if (index === void 0)
+      const index = byPosition.get(before);
+      return index === void 0 ? void 0 : lastProseBefore[index];
+    };
+    const spanIndexAt = (position) => {
+      if (position >= endPosition)
         return void 0;
-      for (index -= 1; index >= 0; index -= 1) {
-        if (records[index].hasProse)
-          return records[index].position;
+      let low = 0;
+      let high = starts.length - 1;
+      let found;
+      while (low <= high) {
+        const middle = low + high >> 1;
+        if (starts[middle].boundary <= position) {
+          found = middle;
+          low = middle + 1;
+        } else {
+          high = middle - 1;
+        }
       }
-      return void 0;
+      return found;
+    };
+    const ownRunsOf = starts.map(() => ({
+      ids: [],
+      seen: /* @__PURE__ */ new Set()
+    }));
+    const addOwnRun = (span, runId) => {
+      const own = ownRunsOf[span];
+      if (own.seen.has(runId))
+        return;
+      own.seen.add(runId);
+      own.ids.push(runId);
+    };
+    for (const run of runStarts) {
+      const started = finalRuns.get(run.runId).startedPosition;
+      if (started === void 0)
+        continue;
+      const span = spanIndexAt(started);
+      if (span !== void 0)
+        addOwnRun(span, run.runId);
+    }
+    const joinedOf = starts.map(() => []);
+    for (const input of inputs) {
+      if (input.runId === void 0)
+        continue;
+      const span = spanIndexAt(input.position);
+      if (span === void 0)
+        continue;
+      addOwnRun(span, input.runId);
+      if (input.human && !input.opensRun)
+        joinedOf[span].push(input);
+    }
+    const firstInputAtOrAfter = (position) => {
+      let low = 0;
+      let high = inputs.length;
+      while (low < high) {
+        const middle = low + high >> 1;
+        if (inputs[middle].position < position)
+          low = middle + 1;
+        else
+          high = middle;
+      }
+      return low;
     };
     const spans = starts.map((start, index) => {
       const next = starts[index + 1];
       const end = next?.boundary ?? endPosition;
       const closingEnd = next?.opener !== void 0 ? Math.max(end, next.opener.position + 1) : end;
-      const ownRuns = [];
+      const ownRuns = ownRunsOf[index].ids;
       const closingRuns = [];
-      for (const run of runStarts) {
-        const started = finalRuns.get(run.runId).startedPosition;
-        if (started !== void 0 && started >= start.boundary && started < end) {
-          if (!ownRuns.includes(run.runId))
-            ownRuns.push(run.runId);
-        }
-      }
-      const joined = [];
-      for (const input of inputs) {
-        if (input.runId === void 0)
-          continue;
-        if (input.position >= start.boundary && input.position < end) {
-          if (!ownRuns.includes(input.runId))
-            ownRuns.push(input.runId);
-          if (input.human && !input.opensRun)
-            joined.push(input);
-        } else if (input.position >= end && input.position < closingEnd) {
-          if (!closingRuns.includes(input.runId))
-            closingRuns.push(input.runId);
+      const closingSeen = /* @__PURE__ */ new Set();
+      for (let at = firstInputAtOrAfter(end); at < inputs.length && inputs[at].position < closingEnd; at += 1) {
+        const runId = inputs[at].runId;
+        if (runId !== void 0 && !closingSeen.has(runId)) {
+          closingSeen.add(runId);
+          closingRuns.push(runId);
         }
       }
+      const joined = joinedOf[index];
       ownRuns.sort((left, right) => finalRuns.get(left).boundary - finalRuns.get(right).boundary);
       const close = next !== void 0 ? next.opener !== void 0 ? "next-opener" : "next-opener-unresolved" : cutAt !== void 0 ? "time-bound" : "end-of-store";
       const previousAnswer = previousProse(start.boundary);
@@ -626,12 +681,30 @@ function createTranscriptReview(options = {}) {
       },
       spanAt: (position) => position < endPosition ? lastAtOrBefore(spans, position) : void 0,
       runExtent: (runId) => {
-        const run = finalRuns.get(runId);
-        if (run === void 0)
+        const at = runStartIndex.get(runId);
+        return at === void 0 ? void 0 : { start: runStarts[at].boundary, end: runEndAt[at] };
+      },
+      runAt: (position) => {
+        let low = 0;
+        let high = runStarts.length - 1;
+        let found;
+        while (low <= high) {
+          const middle = low + high >> 1;
+          if (runStarts[middle].boundary <= position) {
+            found = middle;
+            low = middle + 1;
+          } else {
+            high = middle - 1;
+          }
+        }
+        if (found === void 0)
+          return void 0;
+        const start = runStarts[found].boundary;
+        while (found > 0 && runStarts[found - 1].boundary === start)
+          found -= 1;
+        if (position >= runEndAt[found])
           return void 0;
-        const at = runStarts.findIndex((candidate) => candidate.runId === runId);
-        const next = runStarts.slice(at + 1).find((candidate) => candidate.boundary > run.boundary);
-        return { start: run.boundary, end: next?.boundary ?? endPosition };
+        return { runId: runStarts[found].runId, start, end: runEndAt[found] };
       },
       inputById: (inputId) => inputById.get(inputId),
       attemptAt: (position, block) => {

package/dist/transcript.d.ts

@@ -15,16 +15,16 @@ export declare const ATTACHMENTS_CUSTOM_TYPE = "attachments";
 export declare function branchEntryIds(entries: readonly TranscriptTreeEntryLike[]): ReadonlySet<string>;
 
 /**
- * Every `type: "custom"` entry of one `customType`, oldest→newest, with every
+ * Every `type: "custom"` entry of one `customType`, oldest->newest, with every
  * field ({@link TranscriptSourceEntryLike}'s id/timestamp/tree links plus the
- * entry's own `data`) preserved unchanged — `data` is returned exactly as it
+ * entry's own `data`) preserved unchanged - `data` is returned exactly as it
  * arrived, opaque and unvalidated, never coerced toward a schema this module
  * cannot know.
  *
  * `options.branch` is required, deliberately: `"active"` filters to
  * {@link branchEntryIds}; `"all"` returns every matching entry in the flat
  * log, rewind-abandoned or not. A silent default would let a caller reach
- * for whichever one it did not mean to — pick `"all"` only when the caller
+ * for whichever one it did not mean to - pick `"all"` only when the caller
  * itself needs to reason about abandoned entries (an audit, a recovery
  * tool); an ordinary reader states `"active"` explicitly.
  */
@@ -53,7 +53,7 @@ declare type ProducedResourceAction = "created" | "updated";
 
 /** One URI a tool call created or updated as a side effect. */
 declare interface ProducedResourceDeclaration {
-    /** A `scheme://…` URI or an absolute local file path, compared as an exact string. */
+    /** A `scheme://...` URI or an absolute local file path, compared as an exact string. */
     readonly uri: string;
     readonly action: ProducedResourceAction;
 }
@@ -92,7 +92,7 @@ export declare interface TranscriptEntryLike {
     readonly id: string;
     readonly type: string;
     readonly customType?: string;
-    /** Opaque. Never parsed or validated here — a feature's own schema owns that. */
+    /** Opaque. Never parsed or validated here - a feature's own schema owns that. */
     readonly data?: unknown;
 }
 
@@ -162,7 +162,9 @@ export declare interface TurnSegment {
  * nothing distinguishes a steer from a fresh request.
  *
  * `throughIndex` bounds the walk for a caller holding only a prefix; segments
- * are returned oldest first.
+ * are returned oldest first. A daemon reader that cannot hold the entry list
+ * looks the run up by run id instead (engine redesign 3.1,
+ * `docs/engine-redesign/decisions/2026-10-28-3.1-turn-definition.md`).
  */
 export declare function turnSegments(entries: readonly TurnBoundaryEntry[], throughIndex?: number): readonly TurnSegment[];