@yaklabs-ai/plugin-sdk 0.15.3 → 0.26.3

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;
@@ -400,7 +497,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 +537,211 @@ function isRetryable(result) {
   return result.status === "not-ready";
 }
 
+// packages/kay-ui-catalog/dist/message-draft-resource.js
+import { z as z7 } from "zod";
+var MESSAGE_DRAFT_SUBJECT_MAX = 300;
+var MESSAGE_DRAFT_BODY_MAX = 2e4;
+var MESSAGE_DRAFT_RESOURCE_MAX = 8;
+var UI_RENDER_RESULT_MAX_BYTES = 64 * 1024;
+var contextIdSchema = z7.string().min(1).max(2048);
+var gmailDeliveryRequestSchema = z7.strictObject({
+  provider: z7.literal("gmail"),
+  accountId: contextIdSchema,
+  threadId: contextIdSchema.optional(),
+  inReplyTo: contextIdSchema.optional(),
+  references: z7.array(contextIdSchema).max(50).optional()
+});
+var messageDraftDeliveryRequestSchema = z7.discriminatedUnion("provider", [
+  gmailDeliveryRequestSchema,
+  z7.strictObject({
+    provider: z7.literal("slack"),
+    accountId: contextIdSchema,
+    threadTs: contextIdSchema.optional()
+  }),
+  z7.strictObject({
+    provider: z7.literal("teams"),
+    accountId: contextIdSchema,
+    replyTo: contextIdSchema.optional()
+  })
+]);
+var slackInlineDeliveryRequestSchema = z7.strictObject({
+  provider: z7.literal("slack"),
+  accountId: contextIdSchema,
+  /**
+   * The conversation itself: `slack://channels/<id>`, or the same under `slack://@<accountId>/`.
+   * A thread's address is refused unless `threadTs` names the same thread, because the card shows
+   * a reply only from `threadTs`.
+   */
+  conversationUri: contextIdSchema,
+  threadTs: contextIdSchema.optional()
+});
+var messageDraftInlineDeliveryRequestSchema = z7.discriminatedUnion("provider", [gmailDeliveryRequestSchema, slackInlineDeliveryRequestSchema]);
+var messageDraftResourcePropsSchema = z7.strictObject({
+  draftUri: z7.string().min(1).max(2048),
+  editable: z7.boolean().optional(),
+  delivery: messageDraftDeliveryRequestSchema.optional()
+});
+var deliveryResultSchema = z7.discriminatedUnion("status", [
+  z7.strictObject({
+    status: z7.literal("ready"),
+    sessionId: contextIdSchema,
+    // A saved draft's request, or an inline card's. They differ only for Slack, where the inline
+    // form carries `conversationUri`; each strict variant refuses the other's shape.
+    request: z7.union([
+      messageDraftDeliveryRequestSchema,
+      slackInlineDeliveryRequestSchema
+    ]),
+    accountName: z7.string().min(1).max(2048).optional(),
+    /**
+     * Where a chat message lands, named as the provider named it when the card was drawn
+     * (`#engineering`, `Alex Kim <alex@example.com> (direct message)`: a direct message by the
+     * person's name and Slack email, never a display name alone; Slack's module may answer from its
+     * own name cache, up to a day old, never for another conversation). The card shows this instead of the
+     * agent's own `to` label. Absent for email, whose recipients are the card's own props.
+     */
+    destination: z7.string().min(1).max(2048).optional(),
+    writeUri: contextIdSchema
+  }),
+  z7.strictObject({
+    status: z7.literal("unavailable"),
+    reason: z7.enum([
+      "missing-context",
+      "account-unavailable",
+      "invalid-destination",
+      "invalid-content",
+      // The provider could not name the conversation in time, so the card could not show the
+      // person where Send would post.
+      "unnamed-destination"
+    ])
+  })
+]);
+var contentSchema = z7.discriminatedUnion("kind", [
+  z7.strictObject({
+    kind: z7.literal("email"),
+    to: z7.array(z7.string().max(320)).max(50),
+    /** Copy recipients a draft stored in the mail provider carries; a Whiteboard draft has none. */
+    cc: z7.array(z7.string().max(320)).max(50).optional(),
+    bcc: z7.array(z7.string().max(320)).max(50).optional(),
+    subject: z7.string().max(MESSAGE_DRAFT_SUBJECT_MAX),
+    bodyMarkdown: z7.string().max(MESSAGE_DRAFT_BODY_MAX),
+    /**
+     * `plain` when `bodyMarkdown` holds the literal text of a draft stored in the mail provider,
+     * which is sent as written and must not be shown through a Markdown reading. Absent means
+     * Markdown, the Whiteboard draft's format.
+     */
+    bodyFormat: z7.literal("plain").optional(),
+    /** File names a draft stored in the mail provider carries (names only, never content). */
+    attachments: z7.array(z7.string().min(1).max(200)).max(20).optional()
+  }),
+  z7.strictObject({
+    kind: z7.literal("chat"),
+    provider: z7.enum(["slack", "teams"]),
+    conversationUri: z7.string().max(2048).optional(),
+    bodyMarkdown: z7.string().max(MESSAGE_DRAFT_BODY_MAX)
+  })
+]);
+var messageDraftResourceSchema = z7.discriminatedUnion("status", [
+  z7.strictObject({
+    status: z7.literal("available"),
+    draftUri: z7.string().min(1).max(2048),
+    revision: z7.string().min(1).max(256),
+    content: contentSchema,
+    delivery: deliveryResultSchema.optional()
+  }).refine(({ content, delivery }) => delivery?.status !== "ready" || delivery.request.provider === (content.kind === "email" ? "gmail" : content.provider) && // A saved draft names its own conversation; only an inline card's request carries one.
+  messageDraftDeliveryRequestSchema.safeParse(delivery.request).success, "Delivery provider must match the saved content"),
+  z7.strictObject({
+    status: z7.enum([
+      "missing",
+      "unavailable",
+      "invalid",
+      "unsupported-version",
+      "too-large"
+    ]),
+    draftUri: z7.string().max(2048)
+  })
+]);
+var messageDraftResourceSubmissionSchema = z7.strictObject({
+  version: z7.literal(1),
+  approved: z7.literal(true),
+  elementId: z7.string().min(1).max(2048),
+  draftUri: z7.string().min(1).max(2048),
+  revision: z7.string().min(1).max(256),
+  body: z7.string().max(MESSAGE_DRAFT_BODY_MAX),
+  subject: z7.string().max(MESSAGE_DRAFT_SUBJECT_MAX).optional()
+});
+var messageDraftApprovalWriteSchema = z7.strictObject({
+  messageDraftApproval: z7.strictObject({
+    version: z7.literal(1),
+    toolCallId: contextIdSchema
+  })
+});
+var messageDraftSentDetailsSchema = z7.object({
+  version: z7.literal(1),
+  /** The `ui_render` call that drew the card. */
+  reviewToolCallId: z7.string().min(1),
+  /** The MessageDraft element within that render. */
+  elementId: z7.string().min(1),
+  /** The send intent that produced this record. */
+  clientIntentId: z7.string().min(1),
+  provider: z7.enum(["gmail", "slack"]),
+  accountId: z7.string().min(1),
+  accountName: z7.string().min(1).optional(),
+  /** A chat message's conversation as the card named it (`#engineering`); absent for email. */
+  destination: z7.string().min(1).optional(),
+  /** ISO 8601 instant the provider accepted the send. */
+  sentAt: z7.string().min(1),
+  /**
+   * The sent message, addressed under its account (`gmail://@<accountId>/messages/<id>`,
+   * `slack://@<accountId>/channels/<id>/messages/<ts>`), when the provider named it.
+   */
+  sentMessageUri: z7.string().min(1).optional(),
+  subject: z7.string().max(MESSAGE_DRAFT_SUBJECT_MAX).optional(),
+  body: z7.string().max(MESSAGE_DRAFT_BODY_MAX)
+});
+var uiRenderResultDetailsSchema = z7.union([
+  z7.strictObject({
+    version: z7.literal(1),
+    messageDrafts: z7.record(z7.string(), messageDraftResourceSchema).refine((drafts) => Object.keys(drafts).length <= MESSAGE_DRAFT_RESOURCE_MAX).optional(),
+    inlineDeliveries: z7.record(z7.string(), deliveryResultSchema).refine((deliveries) => Object.keys(deliveries).length <= MESSAGE_DRAFT_RESOURCE_MAX).refine((deliveries) => Object.values(deliveries).every((delivery) => delivery.status !== "ready" || messageDraftInlineDeliveryRequestSchema.safeParse(delivery.request).success)).optional()
+  }).refine((details) => details.messageDrafts !== void 0 || details.inlineDeliveries !== void 0).refine((details) => new TextEncoder().encode(JSON.stringify(details)).byteLength <= UI_RENDER_RESULT_MAX_BYTES),
+  z7.strictObject({
+    version: z7.literal(1),
+    error: z7.literal("resource-limit-exceeded")
+  })
+]);
+
+// packages/plugin-sdk/dist/kay-app/approvals.js
+var MessageApprovalPreparationError = class extends Error {
+  reason;
+  constructor(reason) {
+    super(reason);
+    this.reason = reason;
+    this.name = "MessageApprovalPreparationError";
+  }
+};
+
+// 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 +751,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 +824,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 +840,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 +867,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 +946,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 +963,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 +1036,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 +1065,28 @@ 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,
+  MESSAGE_DRAFT_BODY_MAX,
+  MESSAGE_DRAFT_SUBJECT_MAX,
+  MessageApprovalPreparationError,
   SIGNAL_TIME_MAX_MS,
+  STORED_TRANSCRIPT_MESSAGE_FILTER,
+  STORED_TRANSCRIPT_MESSAGE_KINDS,
   UriConflictError,
   UriNotFoundError,
   UriProviderError,
   UriUnsupportedOperationError,
   UriValidationError,
+  createConsoleKayPluginLog,
   createFallbackOnlySignals,
+  createKayPluginLog,
+  createUnavailableSealing,
   createUnavailableSkills,
   createUnavailableTools,
   createUnavailableUsage,
@@ -693,10 +1094,15 @@ export {
   failedRunCause,
   invalidObservation,
   isRetryable,
+  messageDraftResourceSchema,
   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;