@yaklabs-ai/plugin-sdk 0.13.5 → 0.13.7

package/dist/transcript.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * The ids on a session's active branch: the leaf chain walked parent-ward from
  * the tip, which a trailing `leaf` marker moves. Empty for an empty log.
@@ -28,6 +30,31 @@ export declare function customEntriesFromEntries<T extends TranscriptSourceEntry
     readonly branch: "active" | "all";
 }): readonly T[];
 
+export declare function matchesWorkBlock(coverage: WorkBlockCoverage, toolResultEntryIds: readonly string[]): boolean;
+
+/**
+ * Tool names the transcript draws as their own surface, or lifts into the reply, instead of
+ * counting them as work in the closed bar (venue `inline` or `turn-tail`, or the parsed
+ * `submit_final`). A call to one of these is not a "visible call". The renderer's built-in tool
+ * registrations are the source of truth; its parity test fails when this list drifts from them.
+ * A tool a plugin registers with a non-activity venue is not listed, so the daemon may count it
+ * (a headline can appear on a turn whose bar shows fewer calls than the cutoff only in that
+ * corner, and the renderer re-checks its own count before displaying anything).
+ */
+export declare const NON_ACTIVITY_TOOL_NAMES: readonly string[];
+
+/**
+ * The daemon's own run-start record. A run's entries begin here, before the
+ * user message that opened it.
+ */
+export declare const RUN_STARTED_CUSTOM_TYPE = "session_run_started";
+
+/**
+ * The daemon's own terminal run record (completed / interrupted / cancelled /
+ * failed). A run's entries end here.
+ */
+export declare const RUN_TERMINAL_CUSTOM_TYPE = "session_run_state";
+
 /** The fields the customType selector needs off a session entry. */
 export declare interface TranscriptEntryLike {
     readonly id: string;
@@ -57,4 +84,86 @@ declare interface TranscriptTreeEntryLike extends TranscriptEntryLike {
     readonly targetId?: string | null;
 }
 
+/**
+ * The fields the turn walk reads. Deliberately narrower and looser than
+ * {@link TranscriptEntryLike}: the walk answers in INDEXES, so it never needs an
+ * `id`, and both callers hold entries typed by their own layer (herd's
+ * `TranscriptEntry`, the daemon's branch rows).
+ */
+export declare interface TurnBoundaryEntry {
+    readonly type?: string;
+    readonly customType?: string;
+    /** Opaque here; only `message.role === "user"` is read, defensively. */
+    readonly message?: unknown;
+}
+
+/** 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. */
+    readonly openingIndex: number;
+    /**
+     * The entry the turn settled on. Equal to `openingIndex` when nothing
+     * followed the opening message, which is a turn that never settled rather
+     * than a turn with an empty body.
+     */
+    readonly settleIndex: number;
+}
+
+/**
+ * THE definition of a turn, shared by every reader that has to agree about one:
+ * the settled-turn extractors that key a record to a turn, and the replay
+ * publisher that offers a stored session's turns as events. Two readers
+ * disagreeing here means a replayed "turn" is not the turn production would
+ * have extracted.
+ *
+ * **A turn is a run.** The daemon brackets every run in the transcript
+ * ({@link RUN_STARTED_CUSTOM_TYPE} then, at the end,
+ * {@link RUN_TERMINAL_CUSTOM_TYPE}), and the user message that opened the run
+ * opens the turn. A human steering or a queued message admitted mid-flight is
+ * persisted as another `role: "user"` entry INSIDE that bracket, and belongs to
+ * the turn it interrupted: it is a correction to work already under way, not a
+ * new request. Anchoring on the last user entry instead hands an extractor the
+ * steer as the turn's goal and demotes the real request to prior context.
+ *
+ * A transcript with no run brackets at all (a log older than run bookkeeping, a
+ * hand-built fixture) falls back to one turn per user message, which is the
+ * most this function can honestly say: with no record of when a run ended,
+ * nothing distinguishes a steer from a fresh request.
+ *
+ * `throughIndex` bounds the walk for a caller holding only a prefix; segments
+ * are returned oldest first.
+ */
+export declare function turnSegments(entries: readonly TurnBoundaryEntry[], throughIndex?: number): readonly TurnSegment[];
+
+export declare const WORK_HEADLINE_MAX_CHARS = 90;
+
+/** The longest and shortest stored work headline, in characters. Shorter is filler; longer is a sentence. */
+export declare const WORK_HEADLINE_MIN_CHARS = 12;
+
+/**
+ * The fewest VISIBLE tool calls a settled turn needs before it earns a work headline (owner
+ * ruling, 2026-10-14: "it shouldn't do that if it ran 2 commands but could be helpful if it ran
+ * like 15"; the scope card's 10 was accepted). ONE value, read by the writer (the hindsight
+ * `work-headline` handler decides whether to spend a model call) and by the closed work bar's
+ * renderer (decides whether to show a stored headline), so the two can never disagree about which
+ * turns qualify.
+ */
+export declare const WORK_HEADLINE_MIN_VISIBLE_CALLS = 10;
+
+export declare type WorkBlockCoverage = z.infer<typeof WorkBlockCoverageSchema>;
+
+export declare function workBlockCoverage(toolResultEntryIds: readonly string[]): WorkBlockCoverage | undefined;
+
+/**
+ * Exact ordered completed executions, addressed by persisted tool-result entry IDs.
+ * Provider call IDs can repeat across retries and turns; they are never ownership keys.
+ */
+export declare const WorkBlockCoverageSchema: z.ZodObject<{
+    firstToolResultEntryId: z.ZodString;
+    lastToolResultEntryId: z.ZodString;
+    toolResultEntryIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+
+export declare function workBlockKey(coverage: WorkBlockCoverage): string;
+
 export { }

package/dist/transcript.js

@@ -5,6 +5,22 @@ var WorkBlockCoverageSchema = z.strictObject({
   lastToolResultEntryId: z.string().min(1),
   toolResultEntryIds: z.array(z.string().min(1)).min(1).max(4096)
 }).refine((value) => value.firstToolResultEntryId === value.toolResultEntryIds[0] && value.lastToolResultEntryId === value.toolResultEntryIds.at(-1) && new Set(value.toolResultEntryIds).size === value.toolResultEntryIds.length);
+function workBlockCoverage(toolResultEntryIds) {
+  const parsed = WorkBlockCoverageSchema.safeParse({
+    firstToolResultEntryId: toolResultEntryIds[0],
+    lastToolResultEntryId: toolResultEntryIds.at(-1),
+    toolResultEntryIds
+  });
+  return parsed.success ? parsed.data : void 0;
+}
+function workBlockKey(coverage) {
+  return JSON.stringify(coverage.toolResultEntryIds);
+}
+function matchesWorkBlock(coverage, toolResultEntryIds) {
+  return coverage.toolResultEntryIds.length === toolResultEntryIds.length && coverage.toolResultEntryIds.every((id, index) => id === toolResultEntryIds[index]);
+}
+var RUN_STARTED_CUSTOM_TYPE = "session_run_started";
+var RUN_TERMINAL_CUSTOM_TYPE = "session_run_state";
 function branchEntryIds(entries) {
   const last = entries[entries.length - 1];
   if (last === void 0)
@@ -19,11 +35,77 @@ function branchEntryIds(entries) {
   return onBranch;
 }
 var EMPTY_BRANCH_IDS = /* @__PURE__ */ new Set();
+function isUserMessageEntry(entry) {
+  if (entry.type !== "message")
+    return false;
+  const message = entry.message;
+  return typeof message === "object" && message !== null && message.role === "user";
+}
+function runBoundaryOf(entry) {
+  if (entry.type !== "custom")
+    return void 0;
+  if (entry.customType === RUN_STARTED_CUSTOM_TYPE)
+    return "started";
+  if (entry.customType === RUN_TERMINAL_CUSTOM_TYPE)
+    return "terminal";
+  return void 0;
+}
+function turnSegments(entries, throughIndex = entries.length - 1) {
+  const segments = [];
+  let openingIndex;
+  let runOpen = false;
+  const close = (settleIndex) => {
+    if (openingIndex !== void 0 && settleIndex >= openingIndex) {
+      segments.push({ openingIndex, settleIndex });
+    }
+    openingIndex = void 0;
+  };
+  for (let index = 0; index <= throughIndex; index += 1) {
+    const entry = entries[index];
+    if (entry === void 0)
+      break;
+    const boundary = runBoundaryOf(entry);
+    if (boundary !== void 0) {
+      close(boundary === "terminal" ? index : index - 1);
+      runOpen = boundary === "started";
+      continue;
+    }
+    if (!isUserMessageEntry(entry))
+      continue;
+    if (runOpen && openingIndex !== void 0)
+      continue;
+    close(index - 1);
+    openingIndex = index;
+  }
+  close(throughIndex);
+  return segments;
+}
 function customEntriesFromEntries(entries, customType, options) {
   const onBranch = options.branch === "all" ? null : branchEntryIds(entries);
   return entries.filter((entry) => entry.type === "custom" && entry.customType === customType && (onBranch === null || onBranch.has(entry.id)));
 }
+var WORK_HEADLINE_MIN_VISIBLE_CALLS = 10;
+var NON_ACTIVITY_TOOL_NAMES = [
+  "agent_spawn",
+  "send_message",
+  "service_connect",
+  "ui_render",
+  "submit_final"
+];
+var WORK_HEADLINE_MIN_CHARS = 12;
+var WORK_HEADLINE_MAX_CHARS = 90;
 export {
+  NON_ACTIVITY_TOOL_NAMES,
+  RUN_STARTED_CUSTOM_TYPE,
+  RUN_TERMINAL_CUSTOM_TYPE,
+  WORK_HEADLINE_MAX_CHARS,
+  WORK_HEADLINE_MIN_CHARS,
+  WORK_HEADLINE_MIN_VISIBLE_CALLS,
+  WorkBlockCoverageSchema,
   branchEntryIds,
-  customEntriesFromEntries
+  customEntriesFromEntries,
+  matchesWorkBlock,
+  turnSegments,
+  workBlockCoverage,
+  workBlockKey
 };