@granular-software/sdk 0.4.58 → 0.4.60

package/dist/index.mjs

@@ -3989,6 +3989,1285 @@ var init_wrapper = __esm({
     wrapper_default = import_websocket.default;
   }
 });
+
+// src/feed.ts
+function requirePositiveFeedPosition(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+    throw new Error("Invalid feed chronology.");
+  }
+  return value;
+}
+function mergeFeedItemsBySequence(...collections) {
+  const bySequence = /* @__PURE__ */ new Map();
+  const sequenceById = /* @__PURE__ */ new Map();
+  for (const collection of collections) {
+    let priorSequence = 0;
+    for (const item of collection) {
+      const sequence = requirePositiveFeedPosition(item.sequence);
+      if (sequence <= priorSequence || priorSequence > 0 && sequence !== priorSequence + 1) {
+        throw new Error("Invalid feed chronology.");
+      }
+      priorSequence = sequence;
+      const id = String(item.id || "");
+      const knownSequence = sequenceById.get(id);
+      const existing = bySequence.get(sequence);
+      if (!id || knownSequence !== void 0 && knownSequence !== sequence || existing && existing.id !== id) {
+        throw new Error("Invalid feed chronology.");
+      }
+      if (existing && !sameDurableItem(existing, item)) {
+        throw new Error(
+          "Invalid feed chronology: immutable occurrence collision."
+        );
+      }
+      sequenceById.set(id, sequence);
+      if (!existing) bySequence.set(sequence, item);
+    }
+  }
+  return [...bySequence.entries()].sort(([left], [right]) => left - right).map(([, item]) => item);
+}
+function orderTransientFeedItems(items) {
+  const byId = /* @__PURE__ */ new Map();
+  const ordinalById = /* @__PURE__ */ new Map();
+  const idByOrdinal = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const id = String(item.id || "");
+    const ordinal = requirePositiveFeedPosition(item.ordinal);
+    const knownOrdinal = ordinalById.get(id);
+    const ordinalOwner = idByOrdinal.get(ordinal);
+    if (!id || knownOrdinal !== void 0 && knownOrdinal !== ordinal || ordinalOwner && ordinalOwner !== id) {
+      throw new Error("Invalid feed chronology.");
+    }
+    ordinalById.set(id, ordinal);
+    idByOrdinal.set(ordinal, id);
+    const existing = byId.get(id);
+    if (existing && item.revision === existing.revision && stableValueFingerprint(item) !== stableValueFingerprint(existing)) {
+      throw new Error(
+        "Invalid feed chronology: conflicting transient revision."
+      );
+    }
+    if (!existing || item.revision > existing.revision) byId.set(id, item);
+  }
+  return [...byId.values()].sort((left, right) => left.ordinal - right.ordinal);
+}
+var GRANULAR_FEED_DIAGNOSTIC_EVENT = "granular:feed-diagnostic";
+function normalizeFeedDiagnosticKind(kind) {
+  return /^[a-z][a-z0-9_]{0,63}$/.test(kind) ? kind : "invalid_unknown_kind";
+}
+function normalizeFeedDiagnostic(diagnostic) {
+  if (diagnostic.type !== "unknown_kind") return diagnostic;
+  const kind = normalizeFeedDiagnosticKind(diagnostic.kind);
+  return kind === diagnostic.kind ? diagnostic : { ...diagnostic, kind };
+}
+function emitFeedDiagnosticToDefaultSink(diagnostic, target = globalThis) {
+  try {
+    const normalized = normalizeFeedDiagnostic(diagnostic);
+    const EventConstructor = target.CustomEvent || globalThis.CustomEvent;
+    if (typeof target.dispatchEvent !== "function" || typeof EventConstructor !== "function") {
+      return;
+    }
+    target.dispatchEvent(
+      new EventConstructor(GRANULAR_FEED_DIAGNOSTIC_EVENT, {
+        detail: Object.freeze({ ...normalized })
+      })
+    );
+  } catch {
+  }
+}
+function emitFeedDiagnostic(diagnostic, listener) {
+  const normalized = normalizeFeedDiagnostic(diagnostic);
+  emitFeedDiagnosticToDefaultSink(normalized);
+  if (!listener) return;
+  try {
+    listener(normalized);
+  } catch {
+    console.warn("[Granular] Session feed diagnostic listener failed");
+  }
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function isSafeInteger(value, minimum = 0) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+}
+function finiteInteger(value, fallback, minimum = 0) {
+  return isSafeInteger(value, minimum) ? value : fallback;
+}
+function cloneAndFreeze(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const object = value;
+  const cached = seen.get(object);
+  if (cached) {
+    return cached;
+  }
+  if (Array.isArray(value)) {
+    const result2 = [];
+    seen.set(object, result2);
+    for (const entry of value) {
+      result2.push(cloneAndFreeze(entry, seen));
+    }
+    return Object.freeze(result2);
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  seen.set(object, result);
+  for (const [key, entry] of Object.entries(value)) {
+    result[key] = cloneAndFreeze(entry, seen);
+  }
+  return Object.freeze(result);
+}
+function snapshotWith(snapshot, patch) {
+  return Object.freeze({ ...snapshot, ...patch });
+}
+function emptyFeedSnapshot(isHydrated = false) {
+  return Object.freeze({
+    tail: Object.freeze([]),
+    transients: Object.freeze([]),
+    revision: 0,
+    documentEpoch: 0,
+    documentRevision: 0,
+    lastSequence: 0,
+    archivedThroughSequence: 0,
+    hasOlder: false,
+    isHydrated,
+    isRepairing: false,
+    error: null
+  });
+}
+function hasCanonicalSessionFeedActivation(document) {
+  const documentRecord = asRecord(document);
+  const feed = asRecord(documentRecord?.feed);
+  const activation = asRecord(feed?.activation);
+  return activation?.mode === "canonical";
+}
+function isCanonicalSessionFeedDocument(document) {
+  return hasCanonicalSessionFeedActivation(document);
+}
+function canonicalSessionFeedStructureError(document) {
+  if (!hasCanonicalSessionFeedActivation(document)) return null;
+  const documentRecord = asRecord(document);
+  const feed = asRecord(documentRecord?.feed);
+  const activation = asRecord(feed?.activation);
+  if (feed?.schemaVersion !== 1) {
+    return new Error("Canonical feed schemaVersion must be 1.");
+  }
+  if (!isSafeInteger(activation?.activatedAt)) {
+    return new Error("Canonical feed activation timestamp is invalid.");
+  }
+  if (!Array.isArray(feed.tail)) {
+    return new Error("Canonical feed tail is not an array.");
+  }
+  if (!asRecord(feed.transientById)) {
+    return new Error("Canonical feed transientById is not an object.");
+  }
+  if ([
+    feed.revision,
+    feed.lastSequence,
+    feed.archivedThroughSequence,
+    feed.lastTransientOrdinal,
+    documentRecord?.documentEpoch,
+    documentRecord?.documentRevision
+  ].some((value) => !isSafeInteger(value))) {
+    return new Error("Canonical feed chronology scalar is invalid.");
+  }
+  if (!isSafeInteger(documentRecord?.documentEpoch, 1)) {
+    return new Error("Canonical feed documentEpoch must be positive.");
+  }
+  return null;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isKnownDurableFeedKind(kind) {
+  return kind === "message" || kind === "feedback" || kind === "objects" || kind === "table" || kind === "artifact" || kind === "file" || kind === "action_suggestion" || kind === "prompt";
+}
+function hasValidKnownFeedPayload(kind, value) {
+  const payload = asRecord(value);
+  if (!payload) return false;
+  switch (kind) {
+    case "message":
+      return (payload.role === "user" || payload.role === "assistant" || payload.role === "system") && typeof payload.text === "string";
+    case "feedback":
+      return typeof payload.text === "string" && payload.audience === "customer" && (payload.tone === "info" || payload.tone === "working" || payload.tone === "awaiting" || payload.tone === "success" || payload.tone === "warning" || payload.tone === "error");
+    case "objects":
+      return Array.isArray(payload.refs) && payload.refs.every((value2) => {
+        const ref = asRecord(value2);
+        return ref?.type === "entry" && isNonEmptyString(ref.path) || ref?.type === "list" && isNonEmptyString(ref.name) || ref?.type === "variable" && isNonEmptyString(ref.name);
+      });
+    case "table":
+      return isNonEmptyString(payload.tableId) && Array.isArray(payload.columns) && Array.isArray(payload.rows);
+    case "artifact": {
+      const fallback = asRecord(payload.fallback);
+      return isNonEmptyString(payload.artifactId) && Boolean(fallback) && isNonEmptyString(fallback?.label) && (fallback?.kind === "effect" || fallback?.kind === "batch" || fallback?.kind === "state_path");
+    }
+    case "file": {
+      const fallback = asRecord(payload.fallback);
+      return isNonEmptyString(payload.fileId) && Boolean(fallback) && isNonEmptyString(fallback?.filename);
+    }
+    case "action_suggestion":
+      return isNonEmptyString(payload.suggestionId) && isNonEmptyString(payload.label);
+    case "prompt":
+      return isNonEmptyString(payload.promptId) && (payload.type === "choice" || payload.type === "confirm" || payload.type === "input") && typeof payload.title === "string" && typeof payload.message === "string" && typeof payload.openedAt === "number" && Number.isFinite(payload.openedAt);
+    default:
+      return true;
+  }
+}
+function normalizeFeedItem(value) {
+  const item = asRecord(value);
+  if (!item || typeof item.id !== "string" || !item.id || !isSafeInteger(item.sequence, 1) || typeof item.kind !== "string" || !item.kind || typeof item.occurredAt !== "number" || !Number.isFinite(item.occurredAt) || !isNonEmptyString(item.operationId) || !isSafeInteger(item.batchIndex) || !hasValidKnownFeedPayload(item.kind, item.payload)) {
+    return null;
+  }
+  return cloneAndFreeze(item);
+}
+function normalizeTransientFeedItem(value) {
+  const item = asRecord(value);
+  const payload = asRecord(item?.payload);
+  if (!item || typeof item.id !== "string" || !item.id || item.kind !== "message" && item.kind !== "feedback" || !isSafeInteger(item.ordinal, 1) || !isSafeInteger(item.revision, 1) || typeof item.createdAt !== "number" || !Number.isFinite(item.createdAt) || typeof item.updatedAt !== "number" || !Number.isFinite(item.updatedAt) || !payload || typeof payload.text !== "string" || item.kind === "message" && (payload.role !== "assistant" || !isSafeInteger(item.producerRevision, 0)) || item.kind === "feedback" && (Object.prototype.hasOwnProperty.call(item, "producerRevision") || payload.audience !== "customer" || !isFeedTransientFeedbackTone(payload.tone))) {
+    return null;
+  }
+  return cloneAndFreeze(item);
+}
+var FEED_TRANSIENT_FEEDBACK_TONES = /* @__PURE__ */ new Set(["info", "working", "awaiting", "warning", "error"]);
+function isFeedTransientFeedbackTone(value) {
+  return typeof value === "string" && FEED_TRANSIENT_FEEDBACK_TONES.has(value);
+}
+function normalizeFeedItems(values) {
+  if (!Array.isArray(values)) {
+    return {
+      items: [],
+      error: new Error("Canonical feed tail is not an array.")
+    };
+  }
+  const items = [];
+  const ids = /* @__PURE__ */ new Map();
+  const sequences = /* @__PURE__ */ new Map();
+  const itemBySequence = /* @__PURE__ */ new Map();
+  let error = null;
+  for (const value of values) {
+    const item = normalizeFeedItem(value);
+    if (!item) {
+      error ||= new Error("Canonical feed contains an invalid durable item.");
+      continue;
+    }
+    const idSequence = ids.get(item.id);
+    const sequenceId = sequences.get(item.sequence);
+    if (idSequence !== void 0 && idSequence !== item.sequence || sequenceId !== void 0 && sequenceId !== item.id) {
+      error ||= new Error(
+        `Canonical feed identity conflict at sequence ${item.sequence}.`
+      );
+      continue;
+    }
+    if (idSequence === item.sequence || sequenceId === item.id) {
+      const duplicate = itemBySequence.get(item.sequence);
+      if (duplicate && !sameDurableItem(duplicate, item)) {
+        error ||= new Error(
+          `Immutable feed item ${item.id} has conflicting payloads.`
+        );
+      }
+      continue;
+    }
+    ids.set(item.id, item.sequence);
+    sequences.set(item.sequence, item.id);
+    itemBySequence.set(item.sequence, item);
+    items.push(item);
+  }
+  items.sort((left, right) => left.sequence - right.sequence);
+  return { items: Object.freeze(items), error };
+}
+function normalizeTransients(values) {
+  const record = asRecord(values);
+  if (!record) {
+    return {
+      items: [],
+      error: new Error("Canonical feed transientById is not an object.")
+    };
+  }
+  let error = null;
+  const byId = /* @__PURE__ */ new Map();
+  const idByOrdinal = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(record)) {
+    const item = normalizeTransientFeedItem(value);
+    if (!item || item.id !== key) {
+      error ||= new Error("Canonical feed contains an invalid transient item.");
+      continue;
+    }
+    const ordinalOwner = idByOrdinal.get(item.ordinal);
+    if (ordinalOwner && ordinalOwner !== item.id) {
+      error ||= new Error(
+        `Canonical feed transient ordinal ${item.ordinal} is not unique.`
+      );
+    } else {
+      idByOrdinal.set(item.ordinal, item.id);
+    }
+    const current = byId.get(item.id);
+    if (!current || item.revision > current.revision) {
+      byId.set(item.id, item);
+    }
+  }
+  const items = [...byId.values()].sort(
+    (left, right) => left.ordinal - right.ordinal || left.id.localeCompare(right.id)
+  );
+  return {
+    items: Object.freeze(items),
+    error
+  };
+}
+function readSessionFeedSnapshot(document, options = {}) {
+  const isHydrated = options.isHydrated ?? true;
+  if (!hasCanonicalSessionFeedActivation(document)) {
+    return snapshotWith(emptyFeedSnapshot(isHydrated), {
+      isRepairing: options.isRepairing || false,
+      error: options.error || (isHydrated ? new Error("Canonical session feed-v1 is required.") : null)
+    });
+  }
+  const documentRecord = asRecord(document);
+  const feed = asRecord(documentRecord.feed);
+  const structureError = canonicalSessionFeedStructureError(document);
+  if (structureError) {
+    const lastSequence2 = finiteInteger(feed.lastSequence, 0);
+    const archivedThroughSequence2 = finiteInteger(
+      feed.archivedThroughSequence,
+      0
+    );
+    return snapshotWith(emptyFeedSnapshot(isHydrated), {
+      revision: finiteInteger(feed.revision, 0),
+      documentEpoch: finiteInteger(documentRecord.documentEpoch, 0),
+      documentRevision: finiteInteger(documentRecord.documentRevision, 0),
+      lastSequence: lastSequence2,
+      archivedThroughSequence: archivedThroughSequence2,
+      hasOlder: archivedThroughSequence2 > 0,
+      isRepairing: options.isRepairing || false,
+      error: options.error || structureError
+    });
+  }
+  const normalizedTail = normalizeFeedItems(feed.tail);
+  const normalizedTransients = normalizeTransients(feed.transientById);
+  const lastSequence = finiteInteger(feed.lastSequence, 0);
+  const archivedThroughSequence = finiteInteger(
+    feed.archivedThroughSequence,
+    0
+  );
+  let error = options.error || normalizedTail.error || normalizedTransients.error;
+  let expected = archivedThroughSequence + 1;
+  for (const item of normalizedTail.items) {
+    if (item.sequence !== expected) {
+      error ||= new Error(
+        `Canonical feed tail has a sequence gap before ${item.sequence}; expected ${expected}.`
+      );
+      break;
+    }
+    expected += 1;
+  }
+  const tailLastSequence = normalizedTail.items[normalizedTail.items.length - 1]?.sequence || archivedThroughSequence;
+  if (tailLastSequence !== lastSequence) {
+    error ||= new Error(
+      `Canonical feed tail ends at ${tailLastSequence}, but lastSequence is ${lastSequence}.`
+    );
+  }
+  if (archivedThroughSequence > lastSequence) {
+    error ||= new Error(
+      "Canonical feed archivedThroughSequence exceeds lastSequence."
+    );
+  }
+  return Object.freeze({
+    tail: normalizedTail.items,
+    transients: normalizedTransients.items,
+    revision: finiteInteger(feed.revision, 0),
+    documentEpoch: finiteInteger(documentRecord.documentEpoch, 0),
+    documentRevision: finiteInteger(documentRecord.documentRevision, 0),
+    lastSequence,
+    archivedThroughSequence,
+    hasOlder: archivedThroughSequence > 0,
+    isHydrated,
+    isRepairing: options.isRepairing || false,
+    error
+  });
+}
+function validateFeedListOptions(options) {
+  if (options.afterSequence !== void 0 && options.beforeSequence !== void 0) {
+    throw new RangeError(
+      "Feed list accepts afterSequence or beforeSequence, not both."
+    );
+  }
+  for (const [name, value] of [
+    ["afterSequence", options.afterSequence],
+    ["beforeSequence", options.beforeSequence]
+  ]) {
+    if (value !== void 0 && !isSafeInteger(value)) {
+      throw new RangeError(`${name} must be a non-negative integer.`);
+    }
+  }
+  if (options.limit !== void 0 && (!isSafeInteger(options.limit, 1) || options.limit > 500)) {
+    throw new RangeError("Feed list limit must be an integer from 1 to 500.");
+  }
+  return { ...options };
+}
+function normalizeFeedPage(value) {
+  const page = asRecord(value);
+  if (!page) {
+    throw new Error("Feed list transport returned an invalid page.");
+  }
+  const normalized = normalizeFeedItems(page.items);
+  if (normalized.error) {
+    throw normalized.error;
+  }
+  const first = normalized.items[0]?.sequence || null;
+  const last = normalized.items[normalized.items.length - 1]?.sequence || null;
+  for (let index = 1; index < normalized.items.length; index += 1) {
+    if (normalized.items[index].sequence !== normalized.items[index - 1].sequence + 1) {
+      throw new Error("Feed list page contains a sequence gap.");
+    }
+  }
+  if (first === null && (page.firstSequence !== null || page.lastSequence !== null) || first !== null && (!isSafeInteger(page.firstSequence, 1) || !isSafeInteger(page.lastSequence, 1) || page.firstSequence !== first || page.lastSequence !== last) || typeof page.hasMoreBefore !== "boolean" || typeof page.hasMoreAfter !== "boolean") {
+    throw new Error(
+      "Feed list page sequence metadata does not match its items."
+    );
+  }
+  return Object.freeze({
+    items: normalized.items,
+    firstSequence: first,
+    lastSequence: last,
+    hasMoreBefore: page.hasMoreBefore,
+    hasMoreAfter: page.hasMoreAfter
+  });
+}
+function stableValueFingerprint(value, ancestors = /* @__PURE__ */ new WeakSet()) {
+  if (!value || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (ancestors.has(value)) return '"[circular]"';
+  ancestors.add(value);
+  const result = Array.isArray(value) ? `[${value.map((entry) => stableValueFingerprint(entry, ancestors)).join(",")}]` : `{${Object.keys(value).sort().map(
+    (key) => `${JSON.stringify(key)}:${stableValueFingerprint(
+      value[key],
+      ancestors
+    )}`
+  ).join(",")}}`;
+  ancestors.delete(value);
+  return result;
+}
+function sameDurableItem(left, right) {
+  return stableValueFingerprint(left) === stableValueFingerprint(right);
+}
+function contiguousLocalTailWatermark(snapshot) {
+  let watermark = 0;
+  for (const item of snapshot.tail) {
+    if (item.sequence !== watermark + 1) break;
+    watermark = item.sequence;
+  }
+  return watermark;
+}
+var SessionFeedController = class {
+  snapshot;
+  canonical;
+  canonicalStructureValid;
+  deliveredThrough;
+  knownBySequence = /* @__PURE__ */ new Map();
+  sequenceById = /* @__PURE__ */ new Map();
+  subscribers = /* @__PURE__ */ new Set();
+  listTransport;
+  repairGeneration = 0;
+  repairPromise = null;
+  repairRetryHandle = null;
+  repairRetryToken = 0;
+  repairFailureAttempt = 0;
+  scheduleRepairRetryCallback;
+  cancelRepairRetryCallback;
+  initialRepairRetryDelayMs;
+  maxRepairRetryDelayMs;
+  disposed = false;
+  diagnosticListener;
+  diagnosticNow;
+  observedUnknownPositions = /* @__PURE__ */ new Set();
+  constructor(initialDocument, options = {}) {
+    this.diagnosticListener = options.onDiagnostic || null;
+    this.diagnosticNow = options.now || Date.now;
+    this.scheduleRepairRetryCallback = options.scheduleRepairRetry || ((callback, delayMs) => setTimeout(callback, delayMs));
+    this.cancelRepairRetryCallback = options.cancelRepairRetry || ((handle) => clearTimeout(handle));
+    this.initialRepairRetryDelayMs = Math.max(
+      1,
+      options.initialRepairRetryDelayMs ?? 500
+    );
+    this.maxRepairRetryDelayMs = Math.max(
+      this.initialRepairRetryDelayMs,
+      options.maxRepairRetryDelayMs ?? 1e4
+    );
+    this.canonical = hasCanonicalSessionFeedActivation(initialDocument);
+    this.canonicalStructureValid = this.canonical && canonicalSessionFeedStructureError(initialDocument) === null;
+    this.snapshot = readSessionFeedSnapshot(initialDocument, {
+      isHydrated: options.isHydrated ?? this.canonical
+    });
+    this.listTransport = options.listTransport || null;
+    this.deliveredThrough = contiguousLocalTailWatermark(this.snapshot);
+    const identityError = this.remember(this.snapshot.tail);
+    const needsRepair = this.canonicalStructureValid && this.deliveredThrough < this.snapshot.lastSequence;
+    if (identityError || needsRepair) {
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: needsRepair && Boolean(this.listTransport),
+        error: identityError || this.snapshot.error
+      });
+    }
+    if (needsRepair) {
+      this.startRepair(this.snapshot.lastSequence);
+    }
+  }
+  setListTransport(transport) {
+    if (this.disposed) return;
+    if (transport !== this.listTransport) {
+      this.cancelScheduledRepairRetry();
+      this.repairFailureAttempt = 0;
+      this.repairGeneration += 1;
+      this.repairPromise = null;
+    }
+    this.listTransport = transport;
+    if (transport && this.canonical && this.canonicalStructureValid && this.deliveredThrough < this.snapshot.lastSequence) {
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: true,
+        error: null
+      });
+      this.startRepair(this.snapshot.lastSequence);
+    }
+  }
+  getSnapshot() {
+    return this.snapshot;
+  }
+  /**
+   * Stop background archive work when its owning Session is replaced or
+   * explicitly disconnected. Late transport completions are quarantined by
+   * the generation check and cannot update subscribers.
+   */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.cancelScheduledRepairRetry();
+    this.repairGeneration += 1;
+    this.repairPromise = null;
+    this.listTransport = null;
+    this.subscribers.clear();
+  }
+  async list(options = {}) {
+    const validated = validateFeedListOptions(options);
+    if (!this.listTransport) {
+      throw new Error(
+        "Historical feed transport is unavailable for this Session."
+      );
+    }
+    const page = normalizeFeedPage(await this.listTransport(validated));
+    this.observeUnknownKinds(page.items);
+    return page;
+  }
+  subscribe(listener, options = {}) {
+    const afterSequence = options.afterSequence;
+    if (afterSequence !== void 0 && !isSafeInteger(afterSequence)) {
+      throw new RangeError(
+        "Feed afterSequence must be a non-negative safe integer."
+      );
+    }
+    this.subscribers.add(listener);
+    if (afterSequence !== void 0 && afterSequence < this.snapshot.lastSequence) {
+      const items = this.snapshot.tail.filter(
+        (item) => item.sequence > afterSequence
+      );
+      if (items.length > 0 && items[0].sequence === afterSequence + 1 && items[items.length - 1].sequence === this.snapshot.lastSequence) {
+        listener({ type: "append", items });
+        if (this.snapshot.transients.length > 0) {
+          listener({
+            type: "transients",
+            items: this.snapshot.transients,
+            revision: this.snapshot.revision
+          });
+        }
+      } else {
+        listener({ type: "reset", snapshot: this.snapshot });
+      }
+    } else {
+      listener({ type: "reset", snapshot: this.snapshot });
+    }
+    return () => {
+      this.subscribers.delete(listener);
+    };
+  }
+  /**
+   * Accept the latest synced document. Calls may arrive out of order after a
+   * reconnect; freshness watermarks prevent an older snapshot from regressing
+   * durable positions or transient state.
+   */
+  updateDocument(document, options = {}) {
+    if (this.disposed) return;
+    const nextCanonical = hasCanonicalSessionFeedActivation(document);
+    const next = readSessionFeedSnapshot(document, { isHydrated: true });
+    if (!nextCanonical) {
+      if (!this.canonical) {
+        this.snapshot = next;
+        this.emit({ type: "reset", snapshot: this.snapshot });
+        return;
+      }
+      this.rejectSnapshotRegression("canonical_deactivation", next);
+      return;
+    }
+    const nextStructureError = canonicalSessionFeedStructureError(document);
+    if (nextStructureError) {
+      if (!this.canonical) {
+        this.canonical = true;
+        this.canonicalStructureValid = false;
+        this.cancelScheduledRepairRetry();
+        this.repairFailureAttempt = 0;
+        this.repairGeneration += 1;
+        this.repairPromise = null;
+        this.deliveredThrough = 0;
+        this.knownBySequence.clear();
+        this.sequenceById.clear();
+        this.observedUnknownPositions.clear();
+        this.snapshot = next;
+        this.emit({ type: "reset", snapshot: this.snapshot });
+        return;
+      }
+      this.rejectSnapshotRegression("invalid_canonical_document", next);
+      if (!this.canonicalStructureValid) {
+        const current2 = this.snapshot;
+        const incomingIsNewer = next.documentEpoch > current2.documentEpoch || next.documentEpoch === current2.documentEpoch && next.documentRevision >= current2.documentRevision;
+        if (incomingIsNewer && next.lastSequence >= current2.lastSequence) {
+          this.snapshot = next;
+        }
+      } else {
+        this.snapshot = snapshotWith(this.snapshot, {
+          error: nextStructureError
+        });
+      }
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    if (!this.canonical || options.forceReset) {
+      this.acceptReset(next);
+      return;
+    }
+    if (!this.canonicalStructureValid) {
+      const current2 = this.snapshot;
+      if (next.documentEpoch < current2.documentEpoch) {
+        this.rejectSnapshotRegression("older_document_epoch", next);
+        return;
+      }
+      if (next.lastSequence < current2.lastSequence) {
+        this.rejectSnapshotRegression("last_sequence_regression", next);
+        return;
+      }
+      if (next.documentEpoch === current2.documentEpoch && next.documentRevision < current2.documentRevision) {
+        this.rejectSnapshotRegression("document_revision_regression", next);
+        return;
+      }
+      if (next.documentEpoch === current2.documentEpoch && next.revision < current2.revision) {
+        this.rejectSnapshotRegression("feed_revision_regression", next);
+        return;
+      }
+      this.acceptReset(next);
+      return;
+    }
+    const current = this.snapshot;
+    if (next.documentEpoch < current.documentEpoch) {
+      this.rejectSnapshotRegression("older_document_epoch", next);
+      return;
+    }
+    if (next.documentEpoch > current.documentEpoch) {
+      if (next.lastSequence < current.lastSequence) {
+        this.rejectSnapshotRegression("last_sequence_regression", next);
+        return;
+      }
+      const identityError2 = this.findIdentityConflict(next.tail);
+      if (identityError2) {
+        this.rejectSnapshotRegression("identity_conflict", next);
+        this.snapshot = snapshotWith(current, { error: identityError2 });
+        this.emit({ type: "reset", snapshot: this.snapshot });
+        return;
+      }
+      this.acceptReset(next);
+      return;
+    }
+    if (next.lastSequence < current.lastSequence) {
+      this.rejectSnapshotRegression("last_sequence_regression", next);
+      if (next.documentRevision > current.documentRevision) {
+        this.emit({
+          type: "resource_refresh",
+          documentRevision: next.documentRevision
+        });
+        this.snapshot = snapshotWith(current, {
+          documentRevision: next.documentRevision
+        });
+      }
+      return;
+    }
+    const previousDocumentRevision = current.documentRevision;
+    const previousRevision = current.revision;
+    if (next.lastSequence > current.lastSequence && next.revision <= previousRevision) {
+      this.rejectSnapshotRegression("last_sequence_without_revision", next);
+      const documentRevision = Math.max(
+        previousDocumentRevision,
+        next.documentRevision
+      );
+      this.snapshot = snapshotWith(current, {
+        documentRevision,
+        error: new Error(
+          "Feed lastSequence advanced without a newer feed revision."
+        )
+      });
+      if (next.documentRevision > previousDocumentRevision) {
+        this.emit({
+          type: "resource_refresh",
+          documentRevision: next.documentRevision
+        });
+      }
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    const previousTransients = current.transients;
+    const transientIdentityError = next.revision === previousRevision && !sameTransientSet(previousTransients, next.transients) ? new Error("Transient feed changed without a newer feed revision.") : null;
+    const transientSelection = this.selectNewerTransients(current, next);
+    const mergedTransients = transientSelection.items;
+    const identityError = transientIdentityError || transientSelection.error || this.remember(next.tail);
+    if (identityError) {
+      this.rejectSnapshotRegression("identity_conflict", next);
+      this.snapshot = snapshotWith(current, {
+        documentRevision: Math.max(
+          previousDocumentRevision,
+          next.documentRevision
+        ),
+        error: identityError
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    const keepCurrentFeedState = next.lastSequence === current.lastSequence && next.revision < current.revision;
+    if (keepCurrentFeedState) {
+      this.rejectSnapshotRegression("feed_revision_regression", next);
+    }
+    let nextSnapshot = snapshotWith(keepCurrentFeedState ? current : next, {
+      transients: mergedTransients,
+      revision: Math.max(previousRevision, next.revision),
+      documentRevision: Math.max(
+        previousDocumentRevision,
+        next.documentRevision
+      )
+    });
+    const appended = next.lastSequence > this.deliveredThrough ? this.drainContiguous(next.lastSequence) : [];
+    const needsRepair = this.deliveredThrough < next.lastSequence;
+    const incomingAdvanced = next.documentEpoch > current.documentEpoch || next.documentRevision > current.documentRevision || next.revision > current.revision || next.lastSequence > current.lastSequence;
+    if (incomingAdvanced || !needsRepair) {
+      this.cancelScheduledRepairRetry();
+      this.repairFailureAttempt = 0;
+    }
+    nextSnapshot = snapshotWith(nextSnapshot, {
+      isRepairing: needsRepair,
+      error: nextSnapshot.error
+    });
+    this.snapshot = nextSnapshot;
+    if (appended.length > 0) {
+      this.emit({ type: "append", items: appended });
+    }
+    if (!sameTransientSet(previousTransients, mergedTransients) && next.revision > previousRevision) {
+      this.emit({
+        type: "transients",
+        items: mergedTransients,
+        revision: this.snapshot.revision
+      });
+    }
+    if (next.documentRevision > previousDocumentRevision) {
+      this.emit({
+        type: "resource_refresh",
+        documentRevision: next.documentRevision
+      });
+    }
+    if (needsRepair) {
+      this.startRepair(next.lastSequence);
+    }
+  }
+  /**
+   * Quarantine a canonical replacement rejected by the document transport.
+   * The notice deliberately contains no replacement document, so accepted
+   * feed history remains the only data visible to subscribers during repair.
+   *
+   * @internal
+   */
+  quarantineCanonicalReplacement(quarantine) {
+    if (this.disposed) return;
+    const incoming = snapshotWith(emptyFeedSnapshot(true), {
+      documentEpoch: quarantine.documentEpoch,
+      documentRevision: quarantine.documentRevision,
+      isRepairing: true,
+      error: quarantine.error
+    });
+    if (!this.canonical) {
+      this.canonical = true;
+      this.canonicalStructureValid = false;
+      this.repairGeneration += 1;
+      this.repairPromise = null;
+      this.cancelScheduledRepairRetry();
+      this.repairFailureAttempt = 0;
+      this.deliveredThrough = 0;
+      this.knownBySequence.clear();
+      this.sequenceById.clear();
+      this.observedUnknownPositions.clear();
+      this.snapshot = incoming;
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    this.rejectSnapshotRegression("invalid_canonical_document", incoming);
+    this.repairGeneration += 1;
+    this.repairPromise = null;
+    this.cancelScheduledRepairRetry();
+    this.repairFailureAttempt = 0;
+    if (!this.canonicalStructureValid) {
+      const current = this.snapshot;
+      const incomingIsNewer = incoming.documentEpoch > current.documentEpoch || incoming.documentEpoch === current.documentEpoch && incoming.documentRevision >= current.documentRevision;
+      if (incomingIsNewer) {
+        this.snapshot = incoming;
+      } else {
+        this.snapshot = snapshotWith(current, {
+          isRepairing: true,
+          error: quarantine.error
+        });
+      }
+    } else {
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: true,
+        error: quarantine.error
+      });
+    }
+    this.emit({ type: "reset", snapshot: this.snapshot });
+  }
+  acceptReset(snapshot) {
+    this.cancelScheduledRepairRetry();
+    this.repairFailureAttempt = 0;
+    this.repairGeneration += 1;
+    this.repairPromise = null;
+    this.canonical = true;
+    this.canonicalStructureValid = true;
+    this.knownBySequence.clear();
+    this.sequenceById.clear();
+    this.observedUnknownPositions.clear();
+    this.deliveredThrough = contiguousLocalTailWatermark(snapshot);
+    const identityError = this.remember(snapshot.tail);
+    const needsRepair = this.deliveredThrough < snapshot.lastSequence;
+    this.snapshot = snapshotWith(snapshot, {
+      isRepairing: needsRepair && Boolean(this.listTransport),
+      error: identityError || snapshot.error
+    });
+    this.emit({ type: "reset", snapshot: this.snapshot });
+    if (needsRepair) {
+      this.startRepair(snapshot.lastSequence);
+    }
+  }
+  emitDiagnostic(diagnostic) {
+    emitFeedDiagnostic(diagnostic, this.diagnosticListener);
+  }
+  rejectSnapshotRegression(reason, incoming) {
+    const current = this.snapshot;
+    this.emitDiagnostic({
+      type: "snapshot_regression_rejected",
+      reason,
+      currentDocumentEpoch: current.documentEpoch,
+      incomingDocumentEpoch: incoming.documentEpoch,
+      currentDocumentRevision: current.documentRevision,
+      incomingDocumentRevision: incoming.documentRevision,
+      currentFeedRevision: current.revision,
+      incomingFeedRevision: incoming.revision,
+      currentLastSequence: current.lastSequence,
+      incomingLastSequence: incoming.lastSequence
+    });
+  }
+  observeUnknownKinds(items) {
+    for (const item of items) {
+      const runtimeKind = String(item.kind);
+      if (isKnownDurableFeedKind(runtimeKind)) continue;
+      const diagnosticKind = normalizeFeedDiagnosticKind(runtimeKind);
+      const position = `${item.sequence}:${diagnosticKind}`;
+      if (this.observedUnknownPositions.has(position)) continue;
+      this.observedUnknownPositions.add(position);
+      this.emitDiagnostic({
+        type: "unknown_kind",
+        kind: diagnosticKind,
+        sequence: item.sequence,
+        consumer: "sdk"
+      });
+    }
+  }
+  selectNewerTransients(current, next) {
+    if (next.revision <= current.revision) {
+      return { items: current.transients, error: null };
+    }
+    let newestById;
+    try {
+      newestById = new Map(
+        orderTransientFeedItems([
+          ...current.transients,
+          ...next.transients
+        ]).map((item) => [item.id, item])
+      );
+    } catch {
+      return {
+        items: current.transients,
+        error: new Error(
+          "Transient feed changed immutable identity or revision."
+        )
+      };
+    }
+    const currentById = new Map(
+      current.transients.map((item) => [item.id, item])
+    );
+    const selected = [];
+    for (const incoming of next.transients) {
+      const previous = currentById.get(incoming.id);
+      if (previous && previous.kind !== incoming.kind) {
+        return {
+          items: current.transients,
+          error: new Error(
+            `Transient feed item ${incoming.id} changed its immutable kind.`
+          )
+        };
+      }
+      if (previous?.kind === "message" && incoming.kind === "message" && incoming.revision > previous.revision && incoming.producerRevision < previous.producerRevision) {
+        selected.push(previous);
+        continue;
+      }
+      selected.push(newestById.get(incoming.id) || incoming);
+    }
+    return {
+      items: orderTransientFeedItems(selected),
+      error: null
+    };
+  }
+  remember(items) {
+    const stagedBySequence = /* @__PURE__ */ new Map();
+    const stagedSequenceById = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const knownSequence = stagedSequenceById.get(item.id) ?? this.sequenceById.get(item.id);
+      const knownItem = stagedBySequence.get(item.sequence) || this.knownBySequence.get(item.sequence);
+      if (knownSequence !== void 0 && knownSequence !== item.sequence || knownItem && knownItem.id !== item.id) {
+        return new Error(
+          `Feed identity changed at sequence ${item.sequence}; a reset is required.`
+        );
+      }
+      if (knownItem && !sameDurableItem(knownItem, item)) {
+        return new Error(
+          `Immutable feed item ${item.id} changed at sequence ${item.sequence}.`
+        );
+      }
+      stagedSequenceById.set(item.id, item.sequence);
+      stagedBySequence.set(item.sequence, item);
+    }
+    for (const item of stagedBySequence.values()) {
+      this.sequenceById.set(item.id, item.sequence);
+      this.knownBySequence.set(item.sequence, item);
+    }
+    this.observeUnknownKinds([...stagedBySequence.values()]);
+    return null;
+  }
+  findIdentityConflict(items) {
+    for (const item of items) {
+      const knownSequence = this.sequenceById.get(item.id);
+      const knownItem = this.knownBySequence.get(item.sequence);
+      if (knownSequence !== void 0 && knownSequence !== item.sequence || knownItem && knownItem.id !== item.id) {
+        return new Error(
+          `Feed identity changed at sequence ${item.sequence}; the checkpoint was rejected.`
+        );
+      }
+      if (knownItem && !sameDurableItem(knownItem, item)) {
+        return new Error(
+          `Immutable feed item ${item.id} changed at sequence ${item.sequence}.`
+        );
+      }
+    }
+    return null;
+  }
+  drainContiguous(targetSequence) {
+    const appended = [];
+    let sequence = this.deliveredThrough + 1;
+    while (sequence <= targetSequence) {
+      const item = this.knownBySequence.get(sequence);
+      if (!item) break;
+      appended.push(item);
+      this.deliveredThrough = sequence;
+      sequence += 1;
+    }
+    return Object.freeze(appended);
+  }
+  startRepair(targetSequence) {
+    if (this.disposed || this.repairPromise || this.repairRetryHandle !== null) {
+      return;
+    }
+    if (!this.listTransport) {
+      this.emitDiagnostic({
+        type: "gap_detected",
+        expectedSequence: this.deliveredThrough + 1,
+        targetSequence,
+        repairAvailable: false
+      });
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: false,
+        error: this.snapshot.error || new Error(
+          "Feed sequence gap cannot be repaired without history transport."
+        )
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    this.emitDiagnostic({
+      type: "gap_detected",
+      expectedSequence: this.deliveredThrough + 1,
+      targetSequence,
+      repairAvailable: true
+    });
+    const generation = ++this.repairGeneration;
+    this.repairPromise = this.repair(targetSequence, generation).finally(() => {
+      if (generation === this.repairGeneration) {
+        this.repairPromise = null;
+        if (this.deliveredThrough < this.snapshot.lastSequence) {
+          if (this.snapshot.error) {
+            this.scheduleQuietRepairRetry();
+          } else {
+            this.snapshot = snapshotWith(this.snapshot, { isRepairing: true });
+            this.startRepair(this.snapshot.lastSequence);
+          }
+        } else {
+          this.repairFailureAttempt = 0;
+        }
+      }
+    });
+  }
+  cancelScheduledRepairRetry() {
+    if (this.repairRetryHandle === null) return;
+    const handle = this.repairRetryHandle;
+    this.repairRetryHandle = null;
+    this.repairRetryToken += 1;
+    this.cancelRepairRetryCallback(handle);
+  }
+  scheduleQuietRepairRetry() {
+    if (this.disposed || this.repairRetryHandle !== null || this.repairPromise || !this.listTransport || this.deliveredThrough >= this.snapshot.lastSequence) {
+      return;
+    }
+    this.repairFailureAttempt += 1;
+    const delayMs = Math.min(
+      this.maxRepairRetryDelayMs,
+      this.initialRepairRetryDelayMs * 2 ** Math.min(30, Math.max(0, this.repairFailureAttempt - 1))
+    );
+    const retryToken = ++this.repairRetryToken;
+    let handle;
+    handle = this.scheduleRepairRetryCallback(() => {
+      if (retryToken !== this.repairRetryToken || this.repairRetryHandle !== handle) {
+        return;
+      }
+      this.repairRetryHandle = null;
+      if (this.disposed) return;
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: true,
+        error: null
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      this.startRepair(this.snapshot.lastSequence);
+    }, delayMs);
+    this.repairRetryHandle = handle;
+  }
+  async repair(targetSequence, generation) {
+    const startedAt = this.diagnosticNow();
+    let pageCount = 0;
+    let outcome = "success";
+    try {
+      let attempts = 0;
+      while (generation === this.repairGeneration && this.deliveredThrough < targetSequence) {
+        if (++attempts > 100) {
+          throw new Error("Feed gap repair exceeded its page limit.");
+        }
+        const page = await this.list({
+          afterSequence: this.deliveredThrough,
+          limit: 500
+        });
+        pageCount += 1;
+        if (generation !== this.repairGeneration) {
+          outcome = "cancelled";
+          return;
+        }
+        if (page.items.length === 0) {
+          throw new Error(
+            `Feed gap repair returned no item after sequence ${this.deliveredThrough}.`
+          );
+        }
+        const deliveredBeforePage = this.deliveredThrough;
+        const identityError = this.remember(page.items);
+        if (identityError) throw identityError;
+        const appended = this.drainContiguous(targetSequence);
+        const reachedTarget = this.deliveredThrough >= targetSequence;
+        if (reachedTarget) {
+          this.snapshot = snapshotWith(this.snapshot, {
+            isRepairing: this.deliveredThrough < this.snapshot.lastSequence,
+            error: null
+          });
+        }
+        if (appended.length > 0) {
+          this.emit({ type: "append", items: appended });
+        }
+        if (this.deliveredThrough === deliveredBeforePage) {
+          throw new Error(
+            `Feed gap repair did not return expected sequence ${deliveredBeforePage + 1}.`
+          );
+        }
+        if (this.deliveredThrough < targetSequence && !page.hasMoreAfter && (page.lastSequence || 0) < targetSequence) {
+          throw new Error(
+            `Feed gap remains after sequence ${this.deliveredThrough}.`
+          );
+        }
+      }
+      if (generation !== this.repairGeneration) {
+        outcome = "cancelled";
+        return;
+      }
+    } catch (error) {
+      if (generation !== this.repairGeneration) {
+        outcome = "cancelled";
+        return;
+      }
+      outcome = "failure";
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: false,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+    } finally {
+      this.emitDiagnostic({
+        type: "gap_repair",
+        outcome,
+        durationMs: Math.max(0, this.diagnosticNow() - startedAt),
+        pageCount,
+        repairedThroughSequence: this.deliveredThrough,
+        targetSequence
+      });
+    }
+  }
+  emit(change) {
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber(change);
+      } catch (error) {
+        console.error("[Granular] Session feed subscriber failed", error);
+      }
+    }
+  }
+};
+function sameTransientSet(left, right) {
+  return stableValueFingerprint(left) === stableValueFingerprint(right);
+}
+function operationId(prefix) {
+  const randomUuid = globalThis.crypto?.randomUUID?.();
+  return randomUuid ? `${prefix}_${randomUuid}` : `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+function unwrapPublishedItem(value) {
+  const record = asRecord(value);
+  const directItems = Array.isArray(record?.items) ? record.items : [];
+  const durable = asRecord(record?.durable);
+  const durableItems = Array.isArray(durable?.items) ? durable.items : [];
+  return record?.item || directItems[0] || durableItems[0] || value;
+}
+function requireFeedbackItem(value) {
+  const item = normalizeFeedItem(unwrapPublishedItem(value));
+  if (!item || item.kind !== "feedback") {
+    throw new Error("Feed publisher returned an invalid feedback item.");
+  }
+  return item;
+}
+function requireTransientFeedbackItem(value) {
+  const item = normalizeTransientFeedItem(unwrapPublishedItem(value));
+  if (!item || item.kind !== "feedback") {
+    throw new Error(
+      "Feed publisher returned an invalid transient feedback item."
+    );
+  }
+  return item;
+}
+function createFeedPublisher(publish) {
+  const makeHandle = (initial) => {
+    let current = initial;
+    let mutationQueue = Promise.resolve();
+    const enqueueMutation = (mutation) => {
+      const result = mutationQueue.then(mutation);
+      mutationQueue = result.then(
+        () => void 0,
+        () => void 0
+      );
+      return result;
+    };
+    const handle = {
+      get id() {
+        return current.id;
+      },
+      get ordinal() {
+        return current.ordinal;
+      },
+      get revision() {
+        return current.revision;
+      },
+      update(text, options = {}) {
+        const reservedOperationId = options.operationId || operationId("feed_transient_update");
+        const reservedOptions = { ...options };
+        return enqueueMutation(async () => {
+          const response = await publish("feed.transient.update", {
+            transientId: current.id,
+            expectedRevision: current.revision,
+            text,
+            ...reservedOptions,
+            operationId: reservedOperationId
+          });
+          current = requireTransientFeedbackItem(response);
+          return handle;
+        });
+      },
+      settle(text, options = {}) {
+        const reservedOperationId = options.operationId || operationId("feed_transient_settle");
+        const reservedOptions = { ...options };
+        return enqueueMutation(async () => {
+          const response = await publish("feed.transient.settle", {
+            transientId: current.id,
+            expectedRevision: current.revision,
+            ...text === void 0 ? {} : { text },
+            ...reservedOptions,
+            operationId: reservedOperationId
+          });
+          const responseRecord = asRecord(response);
+          const durable = asRecord(responseRecord?.durable);
+          const durableItems = Array.isArray(durable?.items) ? durable.items : [];
+          const rawItem = responseRecord?.item ?? responseRecord?.durableItem ?? durableItems[0];
+          if (rawItem === null || rawItem === void 0) {
+            return null;
+          }
+          return requireFeedbackItem(rawItem);
+        });
+      }
+    };
+    return handle;
+  };
+  return {
+    async feedback(text, options = {}) {
+      return requireFeedbackItem(
+        await publish("feed.feedback", {
+          text,
+          ...options,
+          operationId: options.operationId || operationId("feed_feedback")
+        })
+      );
+    },
+    async transientFeedback(text, options = {}) {
+      const item = requireTransientFeedbackItem(
+        await publish("feed.transient.create", {
+          text,
+          ...options,
+          operationId: options.operationId || operationId("feed_transient_create")
+        })
+      );
+      return makeHandle(item);
+    }
+  };
+}
+
+// src/ws-client.ts
 var GlobalWebSocket = void 0;
 if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
   GlobalWebSocket = globalThis.WebSocket;
@@ -4002,8 +5281,42 @@ var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
 var EFFECT_CONTROL_RPC_TIMEOUT_MS = 12e4;
 var HARNESS_RUN_RPC_TIMEOUT_MS = 6e5;
+var HEARTBEAT_RPC_TIMEOUT_MS = 15e3;
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
 var DEFAULT_RECONNECT_DELAY_MS = 3e3;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
+var DOCUMENT_RESYNC_CLOSE_CODE = 4e3;
+var DOCUMENT_RESYNC_CLOSE_REASON = "Document resync required";
+function documentVersion(document) {
+  const record = document;
+  const epochValue = record.documentEpoch;
+  const revisionValue = record.documentRevision;
+  const epoch = epochValue === void 0 ? 0 : epochValue;
+  const revision = revisionValue === void 0 ? 0 : revisionValue;
+  if (!Number.isSafeInteger(epoch) || Number(epoch) < 0 || !Number.isSafeInteger(revision) || Number(revision) < 0) {
+    throw new Error("Session document version metadata is invalid");
+  }
+  return {
+    epoch: Number(epoch),
+    revision: Number(revision)
+  };
+}
+function stableDocumentFingerprint(value) {
+  if (value === null) return "null";
+  if (value === void 0) return '"[undefined]"';
+  if (typeof value !== "object") return JSON.stringify(value) ?? String(value);
+  if (value instanceof Date) return `date:${value.toISOString()}`;
+  if (value instanceof Uint8Array) {
+    return `bytes:${Array.from(value).join(",")}`;
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableDocumentFingerprint).join(",")}]`;
+  }
+  const record = value;
+  return `{${Object.keys(record).sort().map(
+    (key) => `${JSON.stringify(key)}:${stableDocumentFingerprint(record[key])}`
+  ).join(",")}}`;
+}
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
@@ -4015,6 +5328,7 @@ function rpcTimeoutMsForMethod(method) {
     case "domain.getSummary":
       return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
     case "client.heartbeat":
+      return HEARTBEAT_RPC_TIMEOUT_MS;
     case "effects.publishCatalog":
     case "effects.resetCatalog":
     case "effects.addCatalog":
@@ -4034,12 +5348,11 @@ var WSClient = class {
   sessionId;
   token;
   messageQueue = [];
-  syncHandlers = [];
   rpcHandlers = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
+  canonicalDocumentQuarantineHandlers = /* @__PURE__ */ new Set();
   nextRpcId = 1;
   doc = Automerge.init();
-  syncState = Automerge.initSyncState();
   reconnectTimer = null;
   tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
@@ -4047,6 +5360,8 @@ var WSClient = class {
   connectPromise = null;
   connectionEpoch = 0;
   cancelConnectAttempt = null;
+  documentRepairRequired = false;
+  canonicalDocumentActivated = false;
   options;
   constructor(options) {
     this.options = options;
@@ -4065,8 +5380,12 @@ var WSClient = class {
       return;
     }
     try {
-      this.doc = document instanceof Uint8Array ? Automerge.load(document) : Automerge.from(document);
-      this.syncState = Automerge.initSyncState();
+      const replacement = document instanceof Uint8Array ? Automerge.load(document) : Automerge.from(document);
+      if (!this.canAcceptDocumentReplacement(replacement, false)) {
+        return;
+      }
+      this.doc = replacement;
+      this.rememberCanonicalActivation(replacement);
       this.emit("sync", this.doc);
     } catch (error) {
       console.warn("[Granular] Failed to seed cached session document", error);
@@ -4197,6 +5516,26 @@ var WSClient = class {
       }
     }
   }
+  /**
+   * Mark the current transport as unusable and schedule the normal reconnect
+   * path. Browser WebSockets can remain in OPEN state after a proxy/worker
+   * restart, so a timed-out heartbeat must revoke the stale socket explicitly.
+   */
+  reportTransportFailure(reason = "WebSocket transport failed") {
+    if (this.isExplicitlyDisconnected) return;
+    const socket = this.ws;
+    this.connectionEpoch += 1;
+    this.ws = null;
+    try {
+      socket?.close(4001, "Transport failure");
+    } catch {
+    }
+    this.handleDisconnect({
+      code: 4001,
+      reason: reason instanceof Error ? reason.message : String(reason),
+      wasClean: false
+    });
+  }
   async connectAttempt(signal) {
     if (signal?.aborted) throw new Error("WebSocket connect aborted");
     const token = await this.resolveTokenForConnect();
@@ -4228,10 +5567,17 @@ var WSClient = class {
     this.ws = socket;
     return new Promise((resolve, reject) => {
       let settled = false;
+      const configuredConnectTimeoutMs = this.options.connectTimeoutMs;
+      const connectTimeoutMs = typeof configuredConnectTimeoutMs === "number" && Number.isFinite(configuredConnectTimeoutMs) && configuredConnectTimeoutMs > 0 ? configuredConnectTimeoutMs : DEFAULT_CONNECT_TIMEOUT_MS;
+      let connectTimeout = null;
       const isCurrent = () => this.connectionEpoch === epoch && this.ws === socket;
       const finish = (error) => {
         if (settled) return;
         settled = true;
+        if (connectTimeout) {
+          clearTimeout(connectTimeout);
+          connectTimeout = null;
+        }
         if (this.cancelConnectAttempt === handleAbort) {
           this.cancelConnectAttempt = null;
         }
@@ -4296,6 +5642,17 @@ var WSClient = class {
           wasClean: close.wasClean
         });
       };
+      connectTimeout = setTimeout(() => {
+        if (!isCurrent()) return;
+        this.connectionEpoch += 1;
+        this.ws = null;
+        closeStaleSocket();
+        finish(
+          new Error(
+            `WebSocket connect timed out after ${connectTimeoutMs}ms`
+          )
+        );
+      }, connectTimeoutMs);
       signal?.addEventListener("abort", handleAbort, { once: true });
       const nodeSocket = socket;
       if (typeof nodeSocket.on === "function") {
@@ -4334,11 +5691,12 @@ var WSClient = class {
     });
     this.messageQueue = [];
   }
-  emitReconnectErrorMessage(error) {
+  emitReconnectErrorMessage(error, terminal = false) {
     const reconnectInfo = {
       error,
       sessionId: this.sessionId,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      terminal
     };
     this.emit("reconnect_error", reconnectInfo);
     if (this.options.onReconnectError) {
@@ -4358,7 +5716,8 @@ var WSClient = class {
     const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
     if (this.reconnectAttempts >= maxReconnectAttempts) {
       this.emitReconnectErrorMessage(
-        `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`
+        `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`,
+        true
       );
       return null;
     }
@@ -4388,6 +5747,190 @@ var WSClient = class {
     const suffix = details ? ` (${details})` : "";
     return new Error(`WebSocket disconnected${suffix}`);
   }
+  decodeDocumentBytes(payload, envelopeType) {
+    if (typeof payload === "string") {
+      const binaryString = atob(payload);
+      const bytes = new Uint8Array(binaryString.length);
+      for (let index = 0; index < binaryString.length; index += 1) {
+        bytes[index] = binaryString.charCodeAt(index);
+      }
+      return bytes;
+    }
+    if (payload instanceof Uint8Array) {
+      return payload;
+    }
+    if (Array.isArray(payload) && payload.every(
+      (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 255
+    )) {
+      return new Uint8Array(payload);
+    }
+    throw new Error(`${envelopeType} payload is not valid byte data`);
+  }
+  rememberCanonicalActivation(document) {
+    if (isCanonicalSessionFeedDocument(document)) {
+      this.canonicalDocumentActivated = true;
+    }
+  }
+  canAcceptDocumentReplacement(replacement, strictlyNewer) {
+    const replacementCanonical = isCanonicalSessionFeedDocument(replacement);
+    const currentCanonical = isCanonicalSessionFeedDocument(this.doc);
+    if (replacementCanonical) {
+      this.canonicalDocumentActivated = true;
+    }
+    if (this.canonicalDocumentActivated && !replacementCanonical) {
+      debugWs(
+        "[Granular DEBUG] Rejected session document replacement that would deactivate the canonical feed."
+      );
+      return false;
+    }
+    const current = documentVersion(this.doc);
+    const incoming = documentVersion(replacement);
+    if (incoming.epoch < current.epoch) {
+      debugWs(
+        `[Granular DEBUG] Rejected stale session document epoch ${incoming.epoch}; current epoch is ${current.epoch}.`
+      );
+      return false;
+    }
+    if (incoming.epoch === current.epoch) {
+      const minimumRevision = strictlyNewer ? current.revision + 1 : current.revision;
+      if (incoming.revision < minimumRevision) {
+        debugWs(
+          `[Granular DEBUG] Rejected stale session document revision ${incoming.revision}; current revision is ${current.revision}.`
+        );
+        return false;
+      }
+    }
+    if (replacementCanonical) {
+      const incomingSnapshot = readSessionFeedSnapshot(replacement);
+      if (incomingSnapshot.error) {
+        this.documentRepairRequired = true;
+        this.exposeCanonicalQuarantine(
+          replacement,
+          currentCanonical,
+          incomingSnapshot.error
+        );
+        debugWs(
+          `[Granular DEBUG] Rejected malformed canonical snapshot: ${incomingSnapshot.error.message}`
+        );
+        return false;
+      }
+    }
+    const canonicalError = this.canonicalReplacementError(replacement);
+    if (canonicalError) {
+      debugWs(`[Granular DEBUG] Rejected session snapshot: ${canonicalError}`);
+      return false;
+    }
+    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && !readSessionFeedSnapshot(this.doc).error && stableDocumentFingerprint(Automerge.toJS(replacement)) !== stableDocumentFingerprint(Automerge.toJS(this.doc))) {
+      debugWs(
+        "[Granular DEBUG] Rejected divergent canonical snapshot at the accepted document version."
+      );
+      return false;
+    }
+    return true;
+  }
+  exposeCanonicalQuarantine(replacement, currentCanonical, error) {
+    const version = documentVersion(replacement);
+    if (currentCanonical) {
+      const quarantine2 = Object.freeze({
+        documentEpoch: version.epoch,
+        documentRevision: version.revision,
+        error: new Error(error.message)
+      });
+      for (const handler of this.canonicalDocumentQuarantineHandlers) {
+        handler(quarantine2);
+      }
+      return;
+    }
+    const accepted = Automerge.toJS(this.doc);
+    const quarantine = Automerge.from({
+      ...accepted,
+      documentEpoch: version.epoch,
+      documentRevision: version.revision,
+      feed: {
+        activation: { mode: "canonical" }
+      }
+    });
+    this.doc = quarantine;
+    this.emit("sync", this.doc);
+    debugWs(
+      `[Granular DEBUG] Canonical activation quarantined pending repair: ${error.message}`
+    );
+  }
+  canonicalReplacementError(replacement) {
+    if (!isCanonicalSessionFeedDocument(replacement)) return null;
+    const incoming = readSessionFeedSnapshot(replacement);
+    if (incoming.error) {
+      return `canonical feed is invalid: ${incoming.error.message}`;
+    }
+    if (!this.canonicalDocumentActivated) return null;
+    const current = readSessionFeedSnapshot(this.doc);
+    if (current.error) {
+      return null;
+    }
+    if (incoming.lastSequence < current.lastSequence) {
+      return `canonical lastSequence ${incoming.lastSequence} regresses accepted ${current.lastSequence}`;
+    }
+    const currentBySequence = new Map(
+      current.tail.map((item) => [item.sequence, item])
+    );
+    for (const item of incoming.tail) {
+      const accepted = currentBySequence.get(item.sequence);
+      if (accepted && stableDocumentFingerprint(item) !== stableDocumentFingerprint(accepted)) {
+        return `canonical occurrence ${item.sequence} conflicts with accepted history`;
+      }
+    }
+    return null;
+  }
+  assertIncrementalDocumentIsSafe(replacement) {
+    const missingDependencies = Automerge.getMissingDeps(replacement, []);
+    if (missingDependencies.length > 0) {
+      throw new Error(
+        `Incremental session update is missing ${missingDependencies.length} causal dependency/dependencies`
+      );
+    }
+    if (this.canonicalDocumentActivated && !isCanonicalSessionFeedDocument(replacement)) {
+      throw new Error(
+        "Incremental session update would deactivate the canonical feed"
+      );
+    }
+    const current = documentVersion(this.doc);
+    const incoming = documentVersion(replacement);
+    if (incoming.epoch < current.epoch || incoming.epoch === current.epoch && incoming.revision < current.revision) {
+      throw new Error("Incremental session update regressed document version");
+    }
+    const canonicalError = this.canonicalReplacementError(replacement);
+    if (canonicalError) {
+      throw new Error(canonicalError);
+    }
+    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && stableDocumentFingerprint(Automerge.toJS(replacement)) !== stableDocumentFingerprint(Automerge.toJS(this.doc))) {
+      throw new Error(
+        "Incremental session update diverged without advancing document revision"
+      );
+    }
+  }
+  requireDocumentResync(envelopeType, error) {
+    this.documentRepairRequired = true;
+    console.warn(
+      `[Granular] ${envelopeType} could not be applied; reconnecting for a fresh session snapshot.`,
+      error
+    );
+    const socket = this.ws;
+    if (!socket) {
+      this.scheduleReconnectAttempt();
+      return;
+    }
+    this.connectionEpoch += 1;
+    this.ws = null;
+    try {
+      socket.close(DOCUMENT_RESYNC_CLOSE_CODE, DOCUMENT_RESYNC_CLOSE_REASON);
+    } catch {
+    }
+    this.handleDisconnect({
+      code: DOCUMENT_RESYNC_CLOSE_CODE,
+      reason: DOCUMENT_RESYNC_CLOSE_REASON,
+      wasClean: false
+    });
+  }
   handleDisconnect(close = {}) {
     const unexpected = !this.isExplicitlyDisconnected;
     const info = {
@@ -4406,11 +5949,11 @@ var WSClient = class {
     }
     if (unexpected) {
       const disconnectError = this.buildDisconnectError(info);
-      this.rejectPending(disconnectError);
-      this.emit("disconnect", info);
       const reconnectDelayMs = this.scheduleReconnectAttempt();
       info.reconnectScheduled = reconnectDelayMs !== null;
       if (reconnectDelayMs !== null) info.reconnectDelayMs = reconnectDelayMs;
+      this.rejectPending(disconnectError);
+      this.emit("disconnect", info);
       if (this.options.onUnexpectedClose) {
         try {
           this.options.onUnexpectedClose(info);
@@ -4430,100 +5973,109 @@ var WSClient = class {
       JSON.stringify(message).slice(0, 500)
     );
     if ("type" in message && message.type === "sync") {
-      const syncMessage = message;
-      let bytes;
+      this.requireDocumentResync(
+        "Unsupported Automerge sync envelope",
+        new Error("Use snapshot, snapshot_reset, or change.")
+      );
+      return;
+    }
+    if ("type" in message && message.type === "snapshot_reset") {
+      const resetMessage = message;
       try {
-        const payload = syncMessage.message || syncMessage.data;
-        if (typeof payload === "string") {
-          const binaryString = atob(payload);
-          const len = binaryString.length;
-          bytes = new Uint8Array(len);
-          for (let i = 0; i < len; i++) {
-            bytes[i] = binaryString.charCodeAt(i);
-          }
-        } else if (Array.isArray(payload)) {
-          bytes = new Uint8Array(payload);
-        } else if (payload instanceof Uint8Array) {
-          bytes = payload;
-        } else {
-          return;
+        if (!Number.isSafeInteger(resetMessage.documentEpoch) || resetMessage.documentEpoch <= 0 || !Number.isSafeInteger(resetMessage.documentRevision) || resetMessage.documentRevision < 0 || !Array.isArray(resetMessage.data)) {
+          throw new Error("snapshot_reset metadata is invalid");
         }
-        debugWs("[Granular DEBUG] Applying sync bytes:", bytes.length);
-        const [newDoc, newSyncState] = Automerge.receiveSyncMessage(
-          this.doc,
-          this.syncState,
-          bytes
+        const replacement = Automerge.load(
+          this.decodeDocumentBytes(
+            resetMessage.data,
+            "Automerge snapshot_reset"
+          )
         );
-        this.doc = newDoc;
-        this.syncState = newSyncState;
-        const docAny = this.doc;
-        if (docAny.catalog) {
-          debugWs(
-            "[Granular DEBUG] Doc catalog sync applied. Keys in catalog:",
-            Object.keys(docAny.catalog || {})
-          );
-          debugWs(
-            "[Granular DEBUG] RawToolCatalogs:",
-            Object.keys(docAny.catalog.rawToolCatalogs || {})
-          );
-        } else {
-          debugWs(
-            "[Granular DEBUG] Doc synced but no catalog yet. Keys in doc:",
-            Object.keys(docAny)
+        const replacementVersion = documentVersion(replacement);
+        const replacementEpoch = replacementVersion.epoch;
+        const replacementRevision = replacementVersion.revision;
+        if (replacementEpoch !== resetMessage.documentEpoch || replacementRevision !== resetMessage.documentRevision) {
+          throw new Error(
+            "snapshot_reset metadata does not match the saved document"
           );
         }
-        this.emit("sync", this.doc);
-      } catch (e) {
-        try {
-          debugWs(
-            "[Granular DEBUG] receiveSyncMessage failed, trying applyChanges..."
-          );
-          const [newDoc] = Automerge.applyChanges(this.doc, [bytes]);
-          this.doc = newDoc;
-          this.emit("sync", this.doc);
-          debugWs(
-            "[Granular DEBUG] applyChanges succeeded. Doc:",
-            JSON.stringify(Automerge.toJS(this.doc))
-          );
-        } catch (applyError) {
-          console.warn(
-            "[Granular] Failed to apply sync message (both sync & applyChanges)",
-            e,
-            applyError
-          );
+        if (!this.canAcceptDocumentReplacement(replacement, true)) {
+          if (this.documentRepairRequired) {
+            this.requireDocumentResync(
+              "Stale Automerge snapshot_reset during document repair",
+              new Error("Replacement reset did not advance accepted state")
+            );
+          }
+          return;
         }
+        this.doc = replacement;
+        this.documentRepairRequired = false;
+        this.rememberCanonicalActivation(replacement);
+        this.emit("snapshot_reset", {
+          documentEpoch: replacementEpoch,
+          documentRevision: replacementRevision
+        });
+        this.emit("sync", this.doc);
+      } catch (error) {
+        this.requireDocumentResync("Automerge snapshot_reset", error);
       }
       return;
     }
     if ("type" in message && message.type === "snapshot") {
       const snapshotMessage = message;
       try {
-        const bytes = new Uint8Array(snapshotMessage.data);
+        const bytes = this.decodeDocumentBytes(
+          snapshotMessage.data,
+          "Automerge snapshot"
+        );
         debugWs(
           "[Granular DEBUG] Loading Automerge session snapshot bytes:",
           bytes.length
         );
-        this.doc = Automerge.load(bytes);
+        const replacement = Automerge.load(bytes);
+        if (!this.canAcceptDocumentReplacement(replacement, false)) {
+          if (this.documentRepairRequired) {
+            this.requireDocumentResync(
+              "Stale Automerge snapshot during document repair",
+              new Error("Replacement snapshot regressed accepted state")
+            );
+          }
+          return;
+        }
+        this.doc = replacement;
+        this.documentRepairRequired = false;
+        this.rememberCanonicalActivation(replacement);
         this.emit("sync", this.doc);
         debugWs(
           "[Granular DEBUG] Automerge session snapshot loaded. Doc:",
           JSON.stringify(Automerge.toJS(this.doc))
         );
-      } catch (e) {
-        console.warn("[Granular] Failed to load snapshot message", e);
+      } catch (error) {
+        this.requireDocumentResync("Automerge snapshot", error);
       }
       return;
     }
     if ("type" in message && message.type === "change") {
+      if (this.documentRepairRequired) {
+        debugWs(
+          "[Granular DEBUG] Ignoring raw change while a replacement snapshot is required."
+        );
+        return;
+      }
       const changeMessage = message;
       try {
-        const bytes = new Uint8Array(changeMessage.data);
+        const bytes = this.decodeDocumentBytes(
+          changeMessage.data,
+          "Automerge change"
+        );
         const [newDoc] = Automerge.applyChanges(this.doc, [bytes]);
+        this.assertIncrementalDocumentIsSafe(newDoc);
         this.doc = newDoc;
+        this.rememberCanonicalActivation(newDoc);
         this.emit("change", changeMessage);
         this.emit("sync", this.doc);
-      } catch (e) {
-        console.warn("[Granular] Failed to apply change message", e);
+      } catch (error) {
+        this.requireDocumentResync("Automerge change message", error);
       }
       return;
     }
@@ -4642,6 +6194,18 @@ var WSClient = class {
     }
     this.eventHandlers.get(event).push(handler);
   }
+  /**
+   * Subscribe to rejected canonical replacement metadata without exposing the
+   * malformed document through the public sync stream.
+   *
+   * @internal Session uses this to quarantine only its feed projection.
+   */
+  onCanonicalDocumentQuarantine(handler) {
+    this.canonicalDocumentQuarantineHandlers.add(handler);
+    return () => {
+      this.canonicalDocumentQuarantineHandlers.delete(handler);
+    };
+  }
   /**
    * Register an RPC handler for incoming server requests
    * @param {string} method - RPC method name
@@ -4699,7 +6263,7 @@ var WSClient = class {
 };
 
 // src/prompt-utils.ts
-function asRecord(value) {
+function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
@@ -4714,7 +6278,7 @@ function parseJsonPromptChoiceOption(option) {
   if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
   try {
     const parsed = JSON.parse(trimmed);
-    return asRecord(parsed);
+    return asRecord2(parsed);
   } catch {
     return null;
   }
@@ -4776,33 +6340,37 @@ function normalizePromptType(raw) {
   if (kind === "confirm" || kind === "choice" || kind === "input") return kind;
   if (promptType === "confirm" || promptType === "choice" || promptType === "input")
     return promptType;
-  return "input";
+  return null;
 }
 function normalizePrompt(rawValue) {
-  const raw = asRecord(rawValue);
+  const raw = asRecord2(rawValue);
   if (!raw) return null;
-  const promptRecord = asRecord(raw.prompt);
+  const promptRecord = asRecord2(raw.prompt);
   const source = promptRecord || raw;
   const id = typeof source.id === "string" ? source.id : typeof raw.id === "string" ? raw.id : typeof raw.promptId === "string" ? raw.promptId : "";
   if (!id) return null;
   const jobId = typeof source.jobId === "string" && source.jobId.trim() ? source.jobId.trim() : typeof raw.jobId === "string" && raw.jobId.trim() ? raw.jobId.trim() : void 0;
   const turnId = typeof source.turnId === "string" && source.turnId.trim() ? source.turnId.trim() : typeof raw.turnId === "string" && raw.turnId.trim() ? raw.turnId.trim() : void 0;
+  const type = normalizePromptType(
+    source === raw ? raw : { ...raw, ...source }
+  );
+  if (!type) return null;
   return {
     id,
     ...jobId ? { jobId } : {},
     ...turnId ? { turnId } : {},
-    type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
+    type,
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
     options: Array.isArray(source.options) ? source.options.map(
-      (option) => typeof option === "string" || asRecord(option) ? normalizePromptChoiceOption(
+      (option) => typeof option === "string" || asRecord2(option) ? normalizePromptChoiceOption(
         option
       ) : option
     ) : void 0,
     defaultValue: source.defaultValue,
     placeholder: typeof source.placeholder === "string" ? source.placeholder : void 0,
     allowEmpty: typeof source.allowEmpty === "boolean" ? source.allowEmpty : void 0,
-    metadata: asRecord(source.metadata) || void 0
+    metadata: asRecord2(source.metadata) || void 0
   };
 }
 function resolvePromptAnswer(prompt, answer) {
@@ -4830,23 +6398,36 @@ function resolvePromptAnswer(prompt, answer) {
 }
 
 // src/session.ts
-var PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS = 5e3;
 function toPascalCase(value) {
   return value.split(/[_:\-\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
-function withPromptTranscriptTimeout(promise) {
-  let timeout = null;
-  return Promise.race([
-    promise,
-    new Promise((_, reject) => {
-      timeout = setTimeout(() => {
-        reject(new Error("Timed out appending prompt answer transcript."));
-      }, PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS);
-    })
-  ]).finally(() => {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
+function reserveUserMessageId() {
+  const randomUuid = globalThis.crypto?.randomUUID?.();
+  return randomUuid ? `message_${randomUuid}` : `message_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+function normalizeUserMessageIdentity(value, field) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`User message ${field} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+function recordFromUnknown(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function promptSnapshotFingerprint(prompt) {
+  return JSON.stringify({
+    id: prompt.id,
+    jobId: prompt.jobId || null,
+    turnId: prompt.turnId || null,
+    type: prompt.type,
+    title: prompt.title,
+    message: prompt.message,
+    options: prompt.options || null,
+    defaultValue: prompt.defaultValue,
+    placeholder: prompt.placeholder || null,
+    allowEmpty: prompt.allowEmpty,
+    metadata: prompt.metadata || null
   });
 }
 var Session = class {
@@ -4854,7 +6435,6 @@ var Session = class {
   clientId;
   initialQuota;
   jobsMap = /* @__PURE__ */ new Map();
-  pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
   /** Tracks which tools are instance methods (className set, not static) */
@@ -4871,10 +6451,23 @@ var Session = class {
   domainPackagePartCache = /* @__PURE__ */ new Map();
   domainPackagePartPromises = /* @__PURE__ */ new Map();
   domainPackageFetchQueue = Promise.resolve();
+  feedController;
+  feed;
   constructor(client, clientId, options = {}) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
     this.initialQuota = options.initialQuota || null;
+    this.feedController = new SessionFeedController(this.client.doc, {
+      listTransport: (feedOptions) => this.client.call(
+        "feed.list",
+        feedOptions
+      )
+    });
+    this.feed = Object.freeze({
+      getSnapshot: () => this.feedController.getSnapshot(),
+      list: (feedOptions = {}) => this.feedController.list(feedOptions),
+      subscribe: (listener, subscribeOptions = {}) => this.feedController.subscribe(listener, subscribeOptions)
+    });
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
     this.currentDomainRevision = this.extractDomainRevisionFromDoc(
@@ -4893,34 +6486,160 @@ var Session = class {
     }
     return null;
   }
-  buildLegacyEffectContext() {
+  /**
+   * Prompt delivery is deliberately event-driven while a socket is live, but
+   * an existing session can be attached from a fresh tab/client after the
+   * event was originally sent. Rebuild that client's prompt cache from the
+   * canonical document on every sync so an open durable prompt remains
+   * actionable after reconnect without manufacturing a second prompt.
+   */
+  reconcilePromptCacheFromCanonicalDocument(doc) {
+    const jobsById = recordFromUnknown(recordFromUnknown(doc)?.jobs)?.byId;
+    const jobs = recordFromUnknown(jobsById) || {};
+    const openPromptIds = /* @__PURE__ */ new Set();
+    for (const [jobId, jobValue] of Object.entries(jobs)) {
+      const prompts = recordFromUnknown(recordFromUnknown(jobValue)?.prompts);
+      if (!prompts) continue;
+      for (const [promptId, promptValue] of Object.entries(prompts)) {
+        const persisted = recordFromUnknown(promptValue);
+        if (!persisted || persisted.status !== "open") continue;
+        const prompt = normalizePrompt({
+          promptId,
+          jobId,
+          kind: persisted.kind,
+          type: persisted.type,
+          title: persisted.title,
+          message: persisted.message,
+          options: persisted.options,
+          defaultValue: persisted.defaultValue,
+          placeholder: persisted.placeholder,
+          allowEmpty: persisted.allowEmpty,
+          metadata: persisted.metadata
+        });
+        if (!prompt) continue;
+        openPromptIds.add(prompt.id);
+        if (this.hiddenPromptIds.has(prompt.id)) continue;
+        const previous = this.promptCache.get(prompt.id);
+        this.promptCache.set(prompt.id, prompt);
+        if (!previous || promptSnapshotFingerprint(previous) !== promptSnapshotFingerprint(prompt)) {
+          this.emit("prompt", prompt);
+        }
+      }
+    }
+    for (const promptId of this.promptCache.keys()) {
+      if (!openPromptIds.has(promptId)) {
+        this.promptCache.delete(promptId);
+      }
+    }
+  }
+  buildDirectedInvocationEffectContext(params, feedbackContext) {
     return {
       effectClientId: this.clientId,
-      sandboxId: "",
-      environmentId: "",
-      sessionId: "",
+      sandboxId: params.sandboxId || "",
+      environmentId: params.environmentId || "",
+      invocationId: params.callId,
+      jobId: params.jobId,
+      sessionId: params.sessionId || this.client.currentSessionId,
       user: {
         granularId: "",
         userId: "",
         subjectId: ""
-      }
+      },
+      ...feedbackContext ? {
+        feedback: feedbackContext.feedback,
+        transientFeedback: feedbackContext.transientFeedback
+      } : {}
     };
   }
-  stringifyConversationValue(value) {
-    if (typeof value === "string") {
-      return value;
-    }
-    if (typeof value === "boolean") {
-      return value ? "Confirmed" : "Canceled";
-    }
-    if (value === void 0) {
-      return "";
-    }
-    try {
-      return JSON.stringify(value, null, 2);
-    } catch {
-      return String(value);
-    }
+  createDirectedInvocationFeedbackContext(params) {
+    if (!params.feedbackCapability) return null;
+    const publications = [];
+    let nextOperationOrdinal = 0;
+    const nextOperationId = (kind) => `${kind}:${nextOperationOrdinal++}`;
+    const track = (publication) => {
+      const tracked = Promise.resolve(publication);
+      publications.push(tracked);
+      void tracked.catch(() => void 0);
+      return tracked;
+    };
+    const methodMap = {
+      "feed.feedback": "tool.feedback",
+      "feed.transient.create": "tool.transient.create",
+      "feed.transient.update": "tool.transient.update",
+      "feed.transient.settle": "tool.transient.settle"
+    };
+    const publisher = createFeedPublisher((method, publishParams) => {
+      const directedFeedbackMethod = methodMap[method];
+      if (!directedFeedbackMethod) {
+        throw new Error(`Unsupported directed feedback method: ${method}`);
+      }
+      return this.client.call(directedFeedbackMethod, {
+        ...publishParams,
+        callId: params.callId,
+        feedbackCapability: params.feedbackCapability
+      });
+    });
+    const wrapTransientHandle = (initial) => {
+      let current = initial;
+      const wrapped = {
+        get id() {
+          return current.id;
+        },
+        get ordinal() {
+          return current.ordinal;
+        },
+        get revision() {
+          return current.revision;
+        },
+        async update(text, options = {}) {
+          current = await track(
+            current.update(text, {
+              ...options,
+              operationId: options.operationId || nextOperationId("transient-update")
+            })
+          );
+          return wrapped;
+        },
+        settle(text, options = {}) {
+          return track(
+            current.settle(text, {
+              ...options,
+              operationId: options.operationId || nextOperationId("transient-settle")
+            })
+          );
+        }
+      };
+      return wrapped;
+    };
+    return {
+      feedback: (text, options = {}) => track(
+        publisher.feedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("feedback")
+        })
+      ),
+      transientFeedback: (text, options = {}) => track(
+        publisher.transientFeedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("transient-create")
+        }).then(wrapTransientHandle)
+      ),
+      async flush() {
+        let cursor = 0;
+        let firstError;
+        while (cursor < publications.length) {
+          const batch = publications.slice(cursor);
+          cursor = publications.length;
+          const results = await Promise.allSettled(batch);
+          for (const result of results) {
+            if (result.status === "rejected" && firstError === void 0) {
+              firstError = result.reason;
+            }
+          }
+        }
+        if (firstError !== void 0) throw firstError;
+      }
+    };
   }
   // --- Public API ---
   get document() {
@@ -5050,17 +6769,8 @@ var Session = class {
       code,
       domainRevision: revision,
       createdAt: Date.now()
-    });
-    this.jobsMap.set(result.jobId, job);
-    const pendingAgentMessages = this.pendingAgentMessagesByJobId.get(
-      result.jobId
-    );
-    if (pendingAgentMessages && pendingAgentMessages.length > 0) {
-      this.pendingAgentMessagesByJobId.delete(result.jobId);
-      for (const message of pendingAgentMessages) {
-        job.replayAgentMessage(message);
-      }
-    }
+    });
+    this.jobsMap.set(result.jobId, job);
     return job;
   }
   /**
@@ -5081,50 +6791,44 @@ var Session = class {
   async answerPrompt(promptId, answer) {
     const prompt = this.promptCache.get(promptId);
     const resolvedAnswer = resolvePromptAnswer(prompt, answer);
+    const response = await this.client.call("prompt.answer", {
+      promptId,
+      answer: resolvedAnswer,
+      value: resolvedAnswer
+    });
+    if (response && typeof response === "object" && "ok" in response && response.ok === false) {
+      const rejected = response;
+      const errorMessage = typeof rejected.error === "string" ? rejected.error : "Prompt answer was rejected.";
+      throw new Error(errorMessage);
+    }
     this.promptCache.delete(promptId);
     this.hiddenPromptIds.add(promptId);
     this.emit("prompt:answered", {
       ...prompt || { id: promptId },
       id: promptId,
+      answer: resolvedAnswer,
       status: "answered"
     });
-    try {
-      const response = await this.client.call("prompt.answer", {
-        promptId,
-        answer: resolvedAnswer,
-        value: resolvedAnswer
-      });
-      if (response && typeof response === "object" && "ok" in response && response.ok === false) {
-        const rejected = response;
-        const errorMessage = typeof rejected.error === "string" ? rejected.error : "Prompt answer was rejected.";
-        throw new Error(errorMessage);
-      }
-    } catch (error) {
-      this.hiddenPromptIds.delete(promptId);
-      if (prompt) {
-        this.promptCache.set(promptId, prompt);
-      }
-      throw error;
-    }
-    try {
-      const content = this.stringifyConversationValue(resolvedAnswer);
-      if (content.trim()) {
-        await withPromptTranscriptTimeout(
-          this.appendConversationMessage({
-            role: "user",
-            content,
-            promptId
-          })
-        );
-      }
-    } catch {
-    }
   }
-  async appendConversationMessage(input) {
-    return this.client.call(
-      "conversation.append",
-      input
+  async appendUserMessage(input) {
+    const requestedId = normalizeUserMessageIdentity(input.id, "id");
+    const requestedOperationId = normalizeUserMessageIdentity(
+      input.operationId,
+      "operationId"
     );
+    const id = requestedId || (requestedOperationId ? void 0 : reserveUserMessageId());
+    const operationId2 = requestedOperationId || `conversation.append:${id}`;
+    const {
+      id: _ignoredInputId,
+      operationId: _ignoredInputOperationId,
+      ...message
+    } = input;
+    return this.client.call("conversation.append", {
+      ...message,
+      role: "user",
+      ...id ? { id } : {},
+      operationId: operationId2
+    });
   }
   /**
    * Get the current list of available effects.
@@ -5507,6 +7211,7 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
    * Close the session and disconnect from the sandbox
    */
   async disconnect() {
+    this.disposeSessionFeed();
     try {
       await this.client.call("client.goodbye", {
         clientId: this.clientId,
@@ -5516,6 +7221,10 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     }
     this.client.disconnect();
   }
+  /** Stop feed repair work without detaching a reconnectable transport. */
+  disposeSessionFeed() {
+    this.feedController.dispose();
+  }
   // --- Event Handling ---
   /**
    * Subscribe to session events
@@ -5540,9 +7249,14 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     }
   }
   // --- Internal ---
+  setFeedListTransport(transport) {
+    this.feedController.setListTransport(transport);
+  }
   setupToolInvokeHandler() {
     this.client.registerRpcHandler("tool.invoke", async (params) => {
-      const { callId, toolName, input } = params;
+      const invocation = params;
+      const { callId, toolName, input, feedbackCapability } = invocation;
+      const capabilityResultParams = feedbackCapability ? { feedbackCapability } : {};
       this.emit("effect:invoke", {
         callId,
         effectKey: toolName,
@@ -5554,6 +7268,7 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
       if (!handler) {
         await this.client.call("tool.result", {
           callId,
+          ...capabilityResultParams,
           error: {
             code: "TOOL_NOT_FOUND",
             message: `Tool handler not found: ${toolName}`
@@ -5563,21 +7278,45 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
       }
       try {
         let result;
-        const invocationContext = this.buildLegacyEffectContext();
-        if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
-          const { _objectId, ...restParams } = input;
-          result = await handler(
-            _objectId,
-            restParams,
-            invocationContext
-          );
-        } else {
-          result = await handler(input, invocationContext);
+        const feedbackContext = this.createDirectedInvocationFeedbackContext(invocation);
+        const invocationContext = this.buildDirectedInvocationEffectContext(
+          invocation,
+          feedbackContext
+        );
+        let handlerError;
+        let handlerFailed = false;
+        try {
+          if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
+            const { _objectId, ...restParams } = input;
+            result = await handler(
+              _objectId,
+              restParams,
+              invocationContext
+            );
+          } else {
+            result = await handler(input, invocationContext);
+          }
+        } catch (error) {
+          handlerFailed = true;
+          handlerError = error;
         }
+        let feedbackError;
+        let feedbackFailed = false;
+        if (feedbackContext) {
+          try {
+            await feedbackContext.flush();
+          } catch (error) {
+            feedbackFailed = true;
+            feedbackError = error;
+          }
+        }
+        if (handlerFailed) throw handlerError;
+        if (feedbackFailed) throw feedbackError;
         this.emit("effect:result", { callId, effectKey: toolName, result });
         this.emit("tool:result", { callId, result });
         await this.client.call("tool.result", {
           callId,
+          ...capabilityResultParams,
           result
         });
       } catch (error) {
@@ -5590,6 +7329,7 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
         this.emit("tool:result", { callId, error: errorMessage });
         await this.client.call("tool.result", {
           callId,
+          ...capabilityResultParams,
           error: { code: "TOOL_EXECUTION_FAILED", message: errorMessage }
         });
       }
@@ -5602,9 +7342,14 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     );
     this.client.on("sync", (doc) => {
       this.currentDomainRevision = this.extractDomainRevisionFromDoc(doc);
+      this.feedController.updateDocument(doc);
+      this.reconcilePromptCacheFromCanonicalDocument(doc);
       this.emit("sync", doc);
       this.checkForToolChanges();
     });
+    this.client.onCanonicalDocumentQuarantine?.((quarantine) => {
+      this.feedController.quarantineCanonicalReplacement(quarantine);
+    });
     const emitPrompt = (payload) => {
       const prompt = normalizePrompt(payload);
       if (!prompt) return;
@@ -5637,23 +7382,6 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     this.client.on("harness.text_response.delta", (data) => {
       this.emit("harness:text_response_delta", data);
     });
-    this.client.on("job.agent_message", (data) => {
-      const normalized = normalizeJobAgentMessageEnvelope(data);
-      if (!normalized) return;
-      this.emit("job:agent_message", normalized);
-      if (this.jobsMap.has(normalized.jobId)) return;
-      const pending = this.pendingAgentMessagesByJobId.get(normalized.jobId) || [];
-      if (normalized.message.messageId && pending.some(
-        (message) => message.messageId === normalized.message.messageId
-      )) {
-        return;
-      }
-      pending.push(normalized.message);
-      this.pendingAgentMessagesByJobId.set(
-        normalized.jobId,
-        pending.slice(-25)
-      );
-    });
     this.client.on("exec.completed", (data) => {
       this.emit("exec:completed", data);
     });
@@ -5778,24 +7506,6 @@ function sanitizeFeedbackValue(value, depth = 0, seen = /* @__PURE__ */ new Weak
   }
   return truncateFeedbackString(String(value));
 }
-function normalizeJobAgentMessageEnvelope(data) {
-  const d = data;
-  if (typeof d?.jobId !== "string" || !d.jobId) {
-    return null;
-  }
-  return {
-    jobId: d.jobId,
-    ...typeof d.turnId === "string" && d.turnId.trim() ? { turnId: d.turnId.trim() } : {},
-    message: {
-      messageId: d.messageId,
-      kind: d.kind === "artifacts" ? "artifacts" : "text",
-      reply: typeof d.reply === "string" ? d.reply : "",
-      show: d.show,
-      actions: Array.isArray(d.actions) ? d.actions : void 0,
-      timestamp: d.timestamp || Date.now()
-    }
-  };
-}
 var JobImplementation = class {
   id;
   client;
@@ -5804,8 +7514,6 @@ var JobImplementation = class {
   _resolveResult;
   _rejectResult;
   eventListeners = /* @__PURE__ */ new Map();
-  bufferedAgentMessages = [];
-  bufferedAgentMessageIds = /* @__PURE__ */ new Set();
   resultSettled = false;
   metadata;
   constructor(id, client, initialState) {
@@ -5964,439 +7672,119 @@ var JobImplementation = class {
           timestamp: d.timestamp
         });
       }
-    });
-    this.client.on("job.agent_message", (data) => {
-      const normalized = normalizeJobAgentMessageEnvelope(data);
-      if (normalized?.jobId === id) {
-        this.captureAgentMessage(normalized.message);
-      }
-    });
-  }
-  get result() {
-    return this._resultPromise;
-  }
-  async leaveFeedback(input) {
-    const sentiment = input.sentiment;
-    if (sentiment !== "good" && sentiment !== "bad") {
-      throw new Error('Job feedback sentiment must be "good" or "bad".');
-    }
-    const comment = typeof input.comment === "string" ? input.comment.trim() : "";
-    const response = await this.client.call("job.feedback", {
-      jobId: this.id,
-      sentiment,
-      comment: comment || void 0,
-      metadata: this.buildFeedbackMetadata()
-    });
-    this.emit("feedback", response);
-    return response;
-  }
-  on(event, handler) {
-    if (!this.eventListeners.has(event)) {
-      this.eventListeners.set(event, []);
-    }
-    this.eventListeners.get(event).push(handler);
-    if (event === "agentMessage" && this.bufferedAgentMessages.length > 0) {
-      for (const message of this.bufferedAgentMessages) {
-        handler(message);
-      }
-    }
-    return () => {
-      const handlers = this.eventListeners.get(event);
-      if (!handlers) {
-        return;
-      }
-      this.eventListeners.set(
-        event,
-        handlers.filter((current) => current !== handler)
-      );
-    };
-  }
-  replayAgentMessage(message) {
-    this.captureAgentMessage(message);
-  }
-  buildFeedbackMetadata() {
-    const startedAt = this.metadata.startedAt;
-    const completedAt = this.metadata.completedAt;
-    return {
-      ...this.metadata,
-      durationMs: typeof startedAt === "number" && typeof completedAt === "number" ? completedAt - startedAt : this.metadata.durationMs ?? null,
-      stdout: [...this.metadata.stdout],
-      stderr: [...this.metadata.stderr],
-      toolCalls: this.metadata.toolCalls.slice(0, MAX_FEEDBACK_TOOL_CALLS).map((call) => ({ ...call }))
-    };
-  }
-  markStarted(timestamp = Date.now()) {
-    if (!this.metadata.startedAt) {
-      this.metadata.startedAt = timestamp;
-    }
-    if (this.status === "queued") {
-      this.status = "running";
-    }
-    if (this.metadata.status === "queued") {
-      this.metadata.status = "running";
-    }
-  }
-  finalize(status, result, error, options = {}) {
-    if (!this.metadata.startedAt) {
-      this.metadata.startedAt = Date.now();
-    }
-    this.status = status;
-    this.metadata.status = status;
-    this.metadata.completedAt = this.metadata.completedAt || Date.now();
-    this.metadata.durationMs = this.metadata.completedAt - this.metadata.startedAt;
-    if (!this.resultSettled && (options.hasResult || result !== void 0)) {
-      this.metadata.result = sanitizeFeedbackValue(result);
-      this.resultSettled = true;
-      this._resolveResult(result);
-    }
-    if (!this.resultSettled && (error !== void 0 || status === "failed" || status === "timeout" || status === "canceled")) {
-      const fallbackError = new Error(`Job ${this.id} ${status}.`);
-      const cause = error ?? fallbackError;
-      const message = cause instanceof Error ? cause.message : String(cause);
-      this.metadata.error = truncateFeedbackString(message);
-      this.resultSettled = true;
-      this._rejectResult(cause);
-    }
-  }
-  upsertToolCall(next) {
-    const callId = next.callId || `tool-call-${Date.now()}`;
-    const existingIndex = this.metadata.toolCalls.findIndex(
-      (entry) => entry.callId === callId
-    );
-    const existing = existingIndex >= 0 ? this.metadata.toolCalls[existingIndex] : void 0;
-    const merged = {
-      ...existing,
-      ...next,
-      callId,
-      toolName: next.toolName || existing?.toolName
-    };
-    if (merged.durationMs === void 0 && typeof merged.startedAt === "number" && typeof merged.completedAt === "number") {
-      merged.durationMs = merged.completedAt - merged.startedAt;
-    }
-    if (existingIndex >= 0) {
-      const updated = [...this.metadata.toolCalls];
-      updated[existingIndex] = merged;
-      return updated.slice(-MAX_FEEDBACK_TOOL_CALLS);
-    }
-    return [...this.metadata.toolCalls, merged].slice(-MAX_FEEDBACK_TOOL_CALLS);
-  }
-  emit(event, data) {
-    const handlers = this.eventListeners.get(event);
-    if (handlers) {
-      handlers.forEach((h) => h(data));
-    }
-  }
-  captureAgentMessage(message) {
-    if (message.messageId && this.bufferedAgentMessageIds.has(message.messageId)) {
-      return;
-    }
-    if (message.messageId) {
-      this.bufferedAgentMessageIds.add(message.messageId);
-    }
-    this.bufferedAgentMessages = [...this.bufferedAgentMessages, message].slice(
-      -25
-    );
-    this.emit("agentMessage", message);
-  }
-};
-
-// src/job-presentation.ts
-var RESPONSE_KEYS = [
-  "reply",
-  "response",
-  "text",
-  "message",
-  "summary",
-  "answer"
-];
-var ENTRY_KEY_CANDIDATES = ["entryPath", "path"];
-var ENTRY_ARRAY_KEY_CANDIDATES = ["entryPaths", "paths"];
-var LIST_KEY_CANDIDATES = ["listName"];
-var LIST_ARRAY_KEY_CANDIDATES = ["listNames"];
-var VARIABLE_KEY_CANDIDATES = ["variableName"];
-var VARIABLE_ARRAY_KEY_CANDIDATES = ["variableNames"];
-var UI_CONTAINER_KEYS = ["show", "display", "present", "ui"];
-function asRecord2(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value;
-}
-function normalizeText(value) {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-  if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]")) {
-    return null;
-  }
-  return trimmed;
-}
-function humanTextFromStdout(stdout) {
-  for (const line of [...stdout].reverse()) {
-    const normalized = normalizeText(line);
-    if (!normalized) continue;
-    if (/^[A-Z_]+:/.test(normalized)) continue;
-    return normalized;
-  }
-  return null;
-}
-function responseTextFromAgentMessages(agentMessages) {
-  for (const message of [...agentMessages].reverse()) {
-    const record = asRecord2(message);
-    if (!record) continue;
-    for (const key of RESPONSE_KEYS) {
-      const normalized = normalizeText(record[key]);
-      if (normalized) return normalized;
-    }
-  }
-  return null;
-}
-function pushString(target, value) {
-  if (typeof value === "string" && value.trim()) {
-    target.add(value.trim());
-  }
-}
-function pushStringArray(target, value) {
-  if (!Array.isArray(value)) return;
-  for (const item of value) {
-    pushString(target, item);
-  }
-}
-function collectReferencesFromRecord(record, refs) {
-  for (const key of ENTRY_KEY_CANDIDATES)
-    pushString(refs.entryPaths, record[key]);
-  for (const key of ENTRY_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.entryPaths, record[key]);
-  for (const key of LIST_KEY_CANDIDATES)
-    pushString(refs.listNames, record[key]);
-  for (const key of LIST_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.listNames, record[key]);
-  for (const key of VARIABLE_KEY_CANDIDATES)
-    pushString(refs.variableNames, record[key]);
-  for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.variableNames, record[key]);
-}
-function stringValue(record, keys) {
-  for (const key of keys) {
-    const value = record[key];
-    if (typeof value === "string" && value.trim()) {
-      return value.trim();
-    }
-  }
-  return null;
-}
-function findEntryPathForRecord(record, heap) {
-  const directPath = stringValue(record, ["entryPath", "path"]);
-  if (directPath && heap.entriesByPath?.[directPath]) {
-    return directPath;
-  }
-  const id = stringValue(record, ["id", "_id", "recordId", "objectId"]);
-  if (!id) {
-    return null;
-  }
-  const className = stringValue(record, [
-    "className",
-    "_className",
-    "__className",
-    "prototype",
-    "type"
-  ]);
-  const entries = Object.values(heap.entriesByPath || {});
-  const exact = entries.find(
-    (entry) => entry.id === id && (!className || entry.className === className || entry.prototypes?.includes(className))
-  );
-  if (exact?.path) {
-    return exact.path;
-  }
-  const idOnlyMatches = entries.filter((entry) => entry.id === id);
-  return idOnlyMatches.length === 1 ? idOnlyMatches[0].path : null;
-}
-function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
-  if (value === null || value === void 0 || depth > 4 || seen.has(value))
-    return;
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (heap.entriesByPath?.[trimmed]) refs.entryPaths.add(trimmed);
-    if (heap.listsByName?.[trimmed]) refs.listNames.add(trimmed);
-    if (heap.variablesByName?.[trimmed]) refs.variableNames.add(trimmed);
-    return;
+    });
   }
-  if (Array.isArray(value)) {
-    seen.add(value);
-    for (const item of value.slice(0, 24)) {
-      scanForHeapReferences(item, heap, refs, depth + 1, seen);
+  get result() {
+    return this._resultPromise;
+  }
+  async leaveFeedback(input) {
+    const sentiment = input.sentiment;
+    if (sentiment !== "good" && sentiment !== "bad") {
+      throw new Error('Job feedback sentiment must be "good" or "bad".');
     }
-    return;
+    const comment = typeof input.comment === "string" ? input.comment.trim() : "";
+    const response = await this.client.call("job.feedback", {
+      jobId: this.id,
+      sentiment,
+      comment: comment || void 0,
+      metadata: this.buildFeedbackMetadata()
+    });
+    this.emit("feedback", response);
+    return response;
   }
-  const record = asRecord2(value);
-  if (!record) return;
-  seen.add(value);
-  const entryPath = findEntryPathForRecord(record, heap);
-  if (entryPath) refs.entryPaths.add(entryPath);
-  collectReferencesFromRecord(record, refs);
-  for (const key of UI_CONTAINER_KEYS) {
-    const nested = asRecord2(record[key]);
-    if (nested) collectReferencesFromRecord(nested, refs);
+  on(event, handler) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, []);
+    }
+    this.eventListeners.get(event).push(handler);
+    return () => {
+      const handlers = this.eventListeners.get(event);
+      if (!handlers) {
+        return;
+      }
+      this.eventListeners.set(
+        event,
+        handlers.filter((current) => current !== handler)
+      );
+    };
   }
-  for (const nested of Object.values(record).slice(0, 24)) {
-    scanForHeapReferences(nested, heap, refs, depth + 1, seen);
+  buildFeedbackMetadata() {
+    const startedAt = this.metadata.startedAt;
+    const completedAt = this.metadata.completedAt;
+    return {
+      ...this.metadata,
+      durationMs: typeof startedAt === "number" && typeof completedAt === "number" ? completedAt - startedAt : this.metadata.durationMs ?? null,
+      stdout: [...this.metadata.stdout],
+      stderr: [...this.metadata.stderr],
+      toolCalls: this.metadata.toolCalls.slice(0, MAX_FEEDBACK_TOOL_CALLS).map((call) => ({ ...call }))
+    };
   }
-}
-function resolveVariablesToReferences(variableNames, heap, refs) {
-  for (const variableName of variableNames) {
-    const variable = heap.variablesByName?.[variableName];
-    if (!variable) continue;
-    if (variable.kind === "entry" && variable.entryPath) {
-      refs.entryPaths.add(variable.entryPath);
+  markStarted(timestamp = Date.now()) {
+    if (!this.metadata.startedAt) {
+      this.metadata.startedAt = timestamp;
     }
-    if (variable.kind === "list" && variable.listName) {
-      refs.listNames.add(variable.listName);
+    if (this.status === "queued") {
+      this.status = "running";
+    }
+    if (this.metadata.status === "queued") {
+      this.metadata.status = "running";
     }
   }
-}
-function sortEntries(entries) {
-  return [...entries].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-}
-function sortLists(lists) {
-  return [...lists].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-}
-function dedupeEntries(entries) {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const entry of entries) {
-    if (!entry?.path || seen.has(entry.path)) continue;
-    seen.add(entry.path);
-    result.push(entry);
-  }
-  return result;
-}
-function dedupeLists(lists) {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const list of lists) {
-    if (!list?.name || seen.has(list.name)) continue;
-    seen.add(list.name);
-    result.push(list);
-  }
-  return result;
-}
-function extractResponseText(result, stdout) {
-  const directText = normalizeText(result);
-  if (directText) return directText;
-  const record = asRecord2(result);
-  if (record) {
-    for (const key of RESPONSE_KEYS) {
-      const normalized = normalizeText(record[key]);
-      if (normalized) return normalized;
+  finalize(status, result, error, options = {}) {
+    if (!this.metadata.startedAt) {
+      this.metadata.startedAt = Date.now();
     }
-    for (const containerKey of UI_CONTAINER_KEYS) {
-      const nested = asRecord2(record[containerKey]);
-      if (!nested) continue;
-      for (const key of RESPONSE_KEYS) {
-        const normalized = normalizeText(nested[key]);
-        if (normalized) return normalized;
-      }
+    this.status = status;
+    this.metadata.status = status;
+    this.metadata.completedAt = this.metadata.completedAt || Date.now();
+    this.metadata.durationMs = this.metadata.completedAt - this.metadata.startedAt;
+    if (!this.resultSettled && (options.hasResult || result !== void 0)) {
+      this.metadata.result = sanitizeFeedbackValue(result);
+      this.resultSettled = true;
+      this._resolveResult(result);
     }
-  }
-  return humanTextFromStdout(stdout);
-}
-function fallbackResponseText(entries, lists) {
-  if (entries.length > 0) {
-    return entries.length === 1 ? "I found one relevant record." : `I found ${entries.length} relevant records.`;
-  }
-  if (lists.length > 0) {
-    const emptyOnly = lists.every((list) => (list.paths || []).length === 0);
-    if (emptyOnly) {
-      return lists.length === 1 ? "I saved one empty result set." : `I saved ${lists.length} empty result sets.`;
+    if (!this.resultSettled && (error !== void 0 || status === "failed" || status === "timeout" || status === "canceled")) {
+      const fallbackError = new Error(`Job ${this.id} ${status}.`);
+      const cause = error ?? fallbackError;
+      const message = cause instanceof Error ? cause.message : String(cause);
+      this.metadata.error = truncateFeedbackString(message);
+      this.resultSettled = true;
+      this._rejectResult(cause);
     }
-    return lists.length === 1 ? "I saved one result set." : `I saved ${lists.length} result sets.`;
   }
-  return null;
-}
-function getJobRelatedEntries(heap, jobId) {
-  return sortEntries(
-    Object.values(heap.entriesByPath || {}).filter(
-      (entry) => entry.relatedJobIds?.includes(jobId)
-    )
-  );
-}
-function getJobRelatedLists(heap, jobId) {
-  return sortLists(
-    Object.values(heap.listsByName || {}).filter(
-      (list) => list.relatedJobIds?.includes(jobId)
-    )
-  );
-}
-function entriesFromLists(lists, heap) {
-  const entries = [];
-  for (const list of lists) {
-    for (const path of list.paths || []) {
-      const entry = heap.entriesByPath?.[path];
-      if (entry) entries.push(entry);
+  upsertToolCall(next) {
+    const callId = next.callId || `tool-call-${Date.now()}`;
+    const existingIndex = this.metadata.toolCalls.findIndex(
+      (entry) => entry.callId === callId
+    );
+    const existing = existingIndex >= 0 ? this.metadata.toolCalls[existingIndex] : void 0;
+    const merged = {
+      ...existing,
+      ...next,
+      callId,
+      toolName: next.toolName || existing?.toolName
+    };
+    if (merged.durationMs === void 0 && typeof merged.startedAt === "number" && typeof merged.completedAt === "number") {
+      merged.durationMs = merged.completedAt - merged.startedAt;
+    }
+    if (existingIndex >= 0) {
+      const updated = [...this.metadata.toolCalls];
+      updated[existingIndex] = merged;
+      return updated.slice(-MAX_FEEDBACK_TOOL_CALLS);
     }
+    return [...this.metadata.toolCalls, merged].slice(-MAX_FEEDBACK_TOOL_CALLS);
   }
-  return entries;
-}
-function resolveJobPresentation({
-  jobId,
-  result,
-  stdout = [],
-  agentMessages = [],
-  sessionHeap,
-  allowExplicitArtifacts = true
-}) {
-  const refs = {
-    entryPaths: /* @__PURE__ */ new Set(),
-    listNames: /* @__PURE__ */ new Set(),
-    variableNames: /* @__PURE__ */ new Set()
-  };
-  if (allowExplicitArtifacts) {
-    scanForHeapReferences(result, sessionHeap, refs);
-    resolveVariablesToReferences(refs.variableNames, sessionHeap, refs);
+  emit(event, data) {
+    const handlers = this.eventListeners.get(event);
+    if (handlers) {
+      handlers.forEach((h) => h(data));
+    }
   }
-  const referencedLists = sortLists(
-    [...refs.listNames].map((name) => sessionHeap.listsByName?.[name]).filter((list) => Boolean(list))
-  );
-  const referencedEntries = sortEntries(
-    [...refs.entryPaths].map((path) => sessionHeap.entriesByPath?.[path]).filter((entry) => Boolean(entry))
-  );
-  const jobLists = getJobRelatedLists(sessionHeap, jobId);
-  const jobEntries = getJobRelatedEntries(sessionHeap, jobId);
-  const changedEntries = dedupeEntries([
-    ...jobEntries,
-    ...entriesFromLists(jobLists, sessionHeap)
-  ]);
-  const explicitLists = dedupeLists(referencedLists);
-  const explicitEntries = dedupeEntries([
-    ...referencedEntries,
-    ...entriesFromLists(referencedLists, sessionHeap)
-  ]);
-  const hasExplicitArtifacts = allowExplicitArtifacts && (explicitEntries.length > 0 || explicitLists.length > 0);
-  const lists = hasExplicitArtifacts ? explicitLists : jobLists;
-  const entries = hasExplicitArtifacts ? explicitEntries : changedEntries;
-  const responseText = extractResponseText(result, stdout) || responseTextFromAgentMessages(agentMessages) || fallbackResponseText(entries, lists);
-  return {
-    responseText,
-    entries,
-    lists,
-    changedEntries,
-    changedLists: jobLists,
-    hasExplicitArtifacts
-  };
-}
+};
 
 // src/session-transcript.ts
-var EMPTY_HEAP = {
-  entriesByPath: {},
-  listsByName: {},
-  variablesByName: {}};
 function asRecord3(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value;
-}
-function asArray(value) {
-  return Array.isArray(value) ? value : [];
-}
-function asNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function asString(value) {
   return typeof value === "string" ? value : void 0;
@@ -6417,142 +7805,17 @@ function compactJson(value, maxLength = 320) {
 function artifactRecordsById(liveDoc) {
   const artifacts = asRecord3(liveDoc?.artifacts);
   const byId = asRecord3(artifacts?.byId) || {};
-  return Object.fromEntries(
-    Object.entries(byId).map(([artifactId, value]) => {
-      const record = asRecord3(value);
-      return record ? [artifactId, record] : null;
-    }).filter(
-      (entry) => Boolean(entry)
-    )
-  );
-}
-function normalizeShowRefs(value) {
-  const record = asRecord3(value);
-  if (!record) return void 0;
-  const normalizeRefs = (input) => {
-    if (!Array.isArray(input)) return void 0;
-    const refs = Array.from(
-      new Set(
-        input.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean)
-      )
-    );
-    return refs.length > 0 ? refs : void 0;
-  };
-  const show = {
-    entryPaths: normalizeRefs(record.entryPaths),
-    listNames: normalizeRefs(record.listNames),
-    variableNames: normalizeRefs(record.variableNames),
-    fileIds: normalizeRefs(record.fileIds),
-    sessionArtifactIds: normalizeRefs(record.sessionArtifactIds),
-    actionSuggestions: normalizeActionSuggestions(record.actionSuggestions),
-    tables: Array.isArray(record.tables) ? record.tables.filter(
-      (table) => Boolean(
-        table && typeof table === "object" && !Array.isArray(table) && Array.isArray(table.columns) && Array.isArray(table.rows)
-      )
-    ) : void 0
-  };
-  return show.entryPaths || show.listNames || show.variableNames || show.fileIds || show.sessionArtifactIds || show.actionSuggestions || show.tables ? show : void 0;
-}
-function normalizeActionSuggestions(value) {
-  if (!Array.isArray(value)) return void 0;
-  const suggestions = [];
-  for (const item of value) {
-    const record = asRecord3(item);
-    if (!record) continue;
-    const label = trimString(record.label);
-    if (!label) continue;
-    const suggestionId = trimString(record.suggestionId) || trimString(record.id) || label;
-    suggestions.push({
-      suggestionId,
-      label,
-      ...typeof record.description === "string" ? { description: record.description } : {},
-      ...asRecord3(record.artifact) ? { artifact: asRecord3(record.artifact) } : {},
-      ...asRecord3(record.target) ? { target: asRecord3(record.target) } : {},
-      ...asRecord3(record.metadata) ? { metadata: asRecord3(record.metadata) } : {}
-    });
-  }
-  return suggestions.length ? suggestions : void 0;
-}
-var TRANSCRIPT_MESSAGE_PART_LIMIT = 128;
-var TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT = 2e5;
-var TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT = 1e3;
-var TRANSCRIPT_MESSAGE_ACTION_LIMIT = 64;
-function normalizeConversationMessageActions(value) {
-  if (!Array.isArray(value) || value.length === 0) return void 0;
-  const actions = [];
-  for (const item of value.slice(0, TRANSCRIPT_MESSAGE_ACTION_LIMIT)) {
-    const record = asRecord3(item);
-    const kind = record?.kind;
-    const label = trimString(record?.label ?? record?.title);
-    const status = record?.status;
-    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
-      continue;
-    }
-    actions.push({
-      kind,
-      label,
-      ...status === "done" || status === "queued" || status === "failed" ? { status } : {}
-    });
-  }
-  return actions.length ? actions : void 0;
-}
-function normalizeConversationMessageParts(value, canonicalContent, canonicalActions) {
-  if (!Array.isArray(value) || value.length === 0 || value.length > TRANSCRIPT_MESSAGE_PART_LIMIT) {
-    return void 0;
-  }
-  const parts = [];
-  const canonicalActionsById = new Map(
-    (canonicalActions || []).map((action) => [
-      `${action.kind}:${action.label}`,
-      action
-    ])
-  );
-  const seenActionIds = /* @__PURE__ */ new Set();
-  let textLength = 0;
-  for (const item of value) {
-    const record = asRecord3(item);
-    if (!record) return void 0;
-    if (record.type === "text") {
-      if (typeof record.text !== "string" || record.text.length === 0) {
-        return void 0;
-      }
-      textLength += record.text.length;
-      if (textLength > TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT) return void 0;
-      parts.push({ type: "text", text: record.text });
-      continue;
-    }
-    if (record.type !== "action") return void 0;
-    const action = asRecord3(record.action);
-    const kind = action?.kind;
-    const label = trimString(action?.label);
-    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
-      return void 0;
-    }
-    const actionId = `${kind}:${label}`;
-    const canonicalAction = canonicalActionsById.get(actionId);
-    if (!canonicalAction) return void 0;
-    if (seenActionIds.has(actionId)) continue;
-    seenActionIds.add(actionId);
-    parts.push({
-      type: "action",
-      action: canonicalAction
-    });
-  }
-  const orderedText = parts.filter(
-    (part) => part.type === "text"
-  ).map((part) => part.text).join("");
-  return orderedText === canonicalContent ? parts : void 0;
+  return Object.fromEntries(
+    Object.entries(byId).map(([artifactId, value]) => {
+      const record = asRecord3(value);
+      return record ? [artifactId, record] : null;
+    }).filter((entry) => Boolean(entry))
+  );
 }
 function stringifyTranscriptValue(value, fallback = "") {
-  if (typeof value === "string") {
-    return value.trim() || fallback;
-  }
-  if (typeof value === "boolean") {
-    return value ? "Confirmed" : "Canceled";
-  }
-  if (value === void 0) {
-    return fallback;
-  }
+  if (typeof value === "string") return value.trim() || fallback;
+  if (typeof value === "boolean") return value ? "Confirmed" : "Canceled";
+  if (value === void 0) return fallback;
   try {
     const json = JSON.stringify(value, null, 2);
     if (!json || json === "undefined") return fallback;
@@ -6693,262 +7956,121 @@ ${stringifyTranscriptValue({ show }, "")}`;
     hasOtherRefs ? `Other shown refs: ${stringifyTranscriptValue(otherRefs, "")}` : null
   ].filter(Boolean).join("\n");
 }
-function normalizeConversationMessage(raw, artifactsById) {
-  const record = asRecord3(raw);
-  if (!record) return null;
-  const role = record.role === "user" ? "user" : record.role === "assistant" ? "assistant" : null;
-  if (!role) return null;
-  const content = trimString(
-    record.content ?? record.reply ?? record.message ?? record.text
-  );
-  const actions = role === "assistant" ? normalizeConversationMessageActions(record.actions) : void 0;
-  const parts = role === "assistant" ? normalizeConversationMessageParts(record.parts, content, actions) : void 0;
-  const show = normalizeShowRefs(record.show);
-  const id = asString(record.id) || crypto.randomUUID();
-  const timestamp = asNumber(record.timestamp) || asNumber(record.ts) || 0;
-  if (!content && !show && !actions?.length) return null;
-  const artifactHistory = buildArtifactHistory(show, artifactsById);
-  const historyContent = role === "assistant" ? content && artifactHistory ? `[Assistant reply]
-${content}
-
-${artifactHistory}` : content ? `[Assistant reply]
-${content}` : artifactHistory : void 0;
-  return {
-    id,
-    role,
-    content,
-    timestamp,
-    jobId: asString(record.jobId),
-    promptId: asString(record.promptId),
-    show,
-    actions,
-    parts,
-    historyContent,
-    source: "conversation"
-  };
-}
-function normalizePromptEntries(jobId, rawPrompts, conversationPromptIds) {
-  const promptsById = asRecord3(rawPrompts) || {};
-  return Object.values(promptsById).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
-    (left, right) => (asNumber(left.openedAt) || asNumber(left.answeredAt) || 0) - (asNumber(right.openedAt) || asNumber(right.answeredAt) || 0)
-  ).flatMap((prompt) => {
-    const promptId = asString(prompt.promptId);
-    if (!promptId || conversationPromptIds.has(promptId)) return [];
-    const title = trimString(prompt.title);
-    const message = trimString(prompt.message);
-    const assistantContent = message || title || "Input required";
-    const openedAt = asNumber(prompt.openedAt) || 0;
-    const answeredAt = asNumber(prompt.answeredAt) || openedAt;
-    const entries = [
-      {
-        id: `prompt:${promptId}:assistant`,
-        role: "assistant",
-        content: assistantContent,
-        timestamp: openedAt,
-        jobId,
-        promptId,
-        historyContent: `[Assistant reply]
-${assistantContent}`,
-        source: "job_prompt"
+function feedItemShow(item) {
+  switch (item.kind) {
+    case "objects": {
+      const entryPaths = [];
+      const listNames = [];
+      const variableNames = [];
+      for (const ref of item.payload.refs) {
+        if (ref.type === "entry") entryPaths.push(ref.path);
+        if (ref.type === "list") listNames.push(ref.name);
+        if (ref.type === "variable") variableNames.push(ref.name);
       }
-    ];
-    if (Object.prototype.hasOwnProperty.call(prompt, "answer")) {
-      entries.push({
-        id: `prompt:${promptId}:user`,
-        role: "user",
-        content: stringifyTranscriptValue(prompt.answer, ""),
-        timestamp: answeredAt,
-        jobId,
-        promptId,
-        source: "job_prompt"
-      });
+      return {
+        ...entryPaths.length ? { entryPaths } : {},
+        ...listNames.length ? { listNames } : {},
+        ...variableNames.length ? { variableNames } : {}
+      };
     }
-    return entries;
-  });
+    case "table":
+      return {
+        tables: [
+          {
+            id: item.payload.tableId,
+            label: item.payload.label,
+            columns: item.payload.columns,
+            rows: item.payload.rows
+          }
+        ]
+      };
+    case "artifact":
+      return { sessionArtifactIds: [item.payload.artifactId] };
+    case "file":
+      return { fileIds: [item.payload.fileId] };
+    case "action_suggestion":
+      return {
+        actionSuggestions: [
+          {
+            suggestionId: item.payload.suggestionId,
+            label: item.payload.label,
+            description: item.payload.description,
+            target: item.payload.target ? { ...item.payload.target } : void 0,
+            artifact: item.payload.proposedArtifact ? { ...item.payload.proposedArtifact } : void 0
+          }
+        ]
+      };
+    default:
+      return void 0;
+  }
 }
-function normalizeAgentMessageEntries(jobId, rawMessages, artifactsById) {
-  return asArray(rawMessages).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
-    (left, right) => (asNumber(left.timestamp) || asNumber(left.ts) || 0) - (asNumber(right.timestamp) || asNumber(right.ts) || 0)
-  ).flatMap((message) => {
-    const messageId = asString(message.messageId) || asString(message.id) || crypto.randomUUID();
-    const timestamp = asNumber(message.timestamp) || asNumber(message.ts) || 0;
-    const reply = trimString(
-      message.reply ?? message.message ?? message.text ?? message.content
-    );
-    const show = normalizeShowRefs(message.show);
-    const entries = [];
-    if (reply) {
+function buildSessionTranscriptFromFeedItems(input) {
+  const artifactsById = artifactRecordsById(input.liveDoc);
+  const entries = [];
+  for (const item of [...input.items].sort(
+    (left, right) => left.sequence - right.sequence
+  )) {
+    if (item.kind === "feedback") continue;
+    if (item.kind === "message") {
+      if (item.payload.role === "system") continue;
+      const content = item.payload.text;
       entries.push({
-        id: `agent:${messageId}:text`,
-        role: "assistant",
-        content: reply,
-        timestamp,
-        jobId,
-        historyContent: `[Assistant reply]
-${reply}`,
-        source: "job_agent_message"
+        id: item.id,
+        role: item.payload.role,
+        content,
+        timestamp: item.occurredAt,
+        sequence: item.sequence,
+        jobId: item.source?.jobId,
+        promptId: item.payload.inReplyToPromptId,
+        historyContent: item.payload.role === "assistant" ? `[Assistant reply]
+${content}` : void 0,
+        source: "feed"
       });
+      continue;
     }
-    if (show) {
+    if (item.kind === "prompt") {
+      const content = item.payload.message || item.payload.title;
       entries.push({
-        id: `agent:${messageId}:artifacts`,
+        id: item.id,
         role: "assistant",
-        content: "",
-        timestamp,
-        jobId,
-        show,
-        historyContent: buildArtifactHistory(show, artifactsById),
-        source: "job_agent_message"
+        content,
+        timestamp: item.occurredAt,
+        sequence: item.sequence,
+        jobId: item.source?.jobId,
+        promptId: item.payload.promptId,
+        historyContent: `[Assistant reply]
+${content}`,
+        source: "feed"
       });
+      continue;
     }
-    return entries;
-  });
-}
-function buildJobFallbackEntries(jobId, job, sessionHeap, artifactsById) {
-  const timestamp = asNumber(job.finishedAt) || asNumber(job.startedAt) || asNumber(job.submittedAt) || 0;
-  const resultPreview = stringifyTranscriptValue(
-    job.result,
-    "No job result recorded."
-  );
-  const presentation = resolveJobPresentation({
-    jobId,
-    result: job.result,
-    stdout: [],
-    sessionHeap
-  });
-  const entries = [];
-  const responseText = presentation.responseText || "";
-  if (responseText) {
-    entries.push({
-      id: `job:${jobId}:result-text`,
-      role: "assistant",
-      content: responseText,
-      timestamp,
-      jobId,
-      historyContent: `[Assistant reply]
-${responseText}`,
-      source: "job_result"
-    });
-  }
-  const show = {
-    entryPaths: presentation.entries.map((entry) => entry.path),
-    listNames: presentation.lists.map((list) => list.name)
-  };
-  if (show.entryPaths && show.entryPaths.length > 0 || show.listNames && show.listNames.length > 0) {
+    const show = feedItemShow(item);
+    if (!show) continue;
     entries.push({
-      id: `job:${jobId}:result-artifacts`,
+      id: item.id,
       role: "assistant",
       content: "",
-      timestamp,
-      jobId,
+      timestamp: item.occurredAt,
+      sequence: item.sequence,
+      jobId: item.source?.jobId,
       show,
       historyContent: buildArtifactHistory(show, artifactsById),
-      source: "job_result"
-    });
-  }
-  if (entries.length === 0 && trimString(job.error)) {
-    entries.push({
-      id: `job:${jobId}:result-error`,
-      role: "assistant",
-      content: trimString(job.error),
-      timestamp,
-      jobId,
-      historyContent: `[Assistant reply]
-${trimString(job.error)}`,
-      source: "job_result"
-    });
-  }
-  if (entries.length === 0 && resultPreview && resultPreview !== "No job result recorded.") {
-    entries.push({
-      id: `job:${jobId}:result-preview`,
-      role: "assistant",
-      content: resultPreview,
-      timestamp,
-      jobId,
-      historyContent: `[Assistant reply]
-${resultPreview}`,
-      source: "job_result"
+      source: "feed"
     });
   }
   return entries;
 }
-function buildJobCodeEntry(jobId, job) {
-  const code = trimString(job.source);
-  if (!code) return null;
-  const jobStatus = asString(job.status);
-  const error = jobStatus === "failed" || jobStatus === "canceled" || jobStatus === "timeout" ? trimString(job.error) || `Job ${jobStatus}` : void 0;
-  return {
-    id: `job:${jobId}:code`,
-    role: "assistant",
-    content: "",
-    timestamp: asNumber(job.submittedAt) || asNumber(job.startedAt) || asNumber(job.finishedAt) || 0,
-    jobId,
-    code,
-    jobStatus,
-    jobResultPreview: stringifyTranscriptValue(
-      job.result,
-      "No job result recorded."
-    ),
-    error,
-    source: "job_code"
-  };
-}
+var CANONICAL_FEED_REQUIRED = "Canonical session feed-v1 is required; past message/job transcript reconstruction is not supported.";
 function buildSessionTranscript(input) {
   const liveDoc = input.liveDoc || null;
-  const sessionHeap = input.sessionHeap || EMPTY_HEAP;
-  const artifactsById = artifactRecordsById(liveDoc);
-  const transcript = [];
-  const conversationMessages = asArray(
-    asRecord3(liveDoc?.conversation)?.messages
-  ).map((message) => normalizeConversationMessage(message, artifactsById)).filter((message) => Boolean(message));
-  const conversationPromptIds = new Set(
-    conversationMessages.map((message) => message.promptId).filter((promptId) => Boolean(promptId))
-  );
-  const assistantConversationJobIds = new Set(
-    conversationMessages.filter(
-      (message) => message.role === "assistant" && Boolean(message.jobId)
-    ).map((message) => message.jobId)
-  );
-  transcript.push(...conversationMessages);
-  const jobsById = asRecord3(asRecord3(liveDoc?.jobs)?.byId) || {};
-  const jobs = Object.values(jobsById).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
-    (left, right) => (asNumber(left.submittedAt) || asNumber(left.startedAt) || asNumber(left.finishedAt) || 0) - (asNumber(right.submittedAt) || asNumber(right.startedAt) || asNumber(right.finishedAt) || 0)
-  );
-  for (const job of jobs) {
-    const jobId = asString(job.jobId);
-    if (!jobId) continue;
-    const codeEntry = buildJobCodeEntry(jobId, job);
-    if (codeEntry) {
-      transcript.push(codeEntry);
-    }
-    transcript.push(
-      ...normalizePromptEntries(jobId, job.prompts, conversationPromptIds)
-    );
-    if (!assistantConversationJobIds.has(jobId)) {
-      const agentEntries = normalizeAgentMessageEntries(
-        jobId,
-        job.agentMessages,
-        artifactsById
-      );
-      if (agentEntries.length > 0) {
-        transcript.push(...agentEntries);
-      } else {
-        transcript.push(
-          ...buildJobFallbackEntries(
-            jobId,
-            job,
-            sessionHeap,
-            artifactsById
-          )
-        );
-      }
-    }
-  }
-  return transcript.sort((left, right) => {
-    if (left.timestamp !== right.timestamp) {
-      return left.timestamp - right.timestamp;
-    }
-    return left.id.localeCompare(right.id);
+  if (!isCanonicalSessionFeedDocument(liveDoc)) {
+    throw new Error(CANONICAL_FEED_REQUIRED);
+  }
+  const snapshot = readSessionFeedSnapshot(liveDoc);
+  if (snapshot.error) throw snapshot.error;
+  return buildSessionTranscriptFromFeedItems({
+    items: input.canonicalFeedItems || snapshot.tail,
+    liveDoc
   });
 }
 
@@ -11940,7 +13062,7 @@ function normalizeEffectBehaviors(value) {
 }
 function resolveInvocationMode(context) {
   const mode = context?.invocation?.mode;
-  if (mode === "dryRun" || mode === "reverse") {
+  if (mode === "dryRun" || mode === "reverse" || mode === "artifactOptions") {
     return mode;
   }
   return "execute";
@@ -11994,6 +13116,18 @@ function resolveHandlerForMode(effectMap, effect, request) {
     request.context?.behaviors || effect.metamodels || void 0
   );
   const mode = resolveInvocationMode(request.context);
+  if (mode === "artifactOptions") {
+    if (!effect.artifactOptionsHandler) {
+      throw new Error(
+        `Artifact relationship options are not supported for ${request.effectKey}`
+      );
+    }
+    return {
+      effect,
+      mode,
+      handler: effect.artifactOptionsHandler
+    };
+  }
   if (mode === "dryRun") {
     if (effect.dryRunHandler) {
       return { effect, mode, handler: effect.dryRunHandler };
@@ -12026,7 +13160,91 @@ function resolveHandlerForMode(effectMap, effect, request) {
   }
   return { effect, mode, handler: effect.handler };
 }
-async function invokeRegisteredEffect(effectMap, request) {
+function createInvocationFeedbackContext(bridge) {
+  const publications = [];
+  let nextOperationOrdinal = 0;
+  const nextOperationId = (kind) => `${kind}:${nextOperationOrdinal++}`;
+  const track = (publication) => {
+    const tracked = Promise.resolve(publication);
+    publications.push(tracked);
+    void tracked.catch(() => void 0);
+    return tracked;
+  };
+  const publisher = createFeedPublisher(
+    (method, params) => bridge.publish(method, {
+      ...params,
+      invocationId: bridge.invocationId
+    })
+  );
+  const wrapTransientHandle = (initial) => {
+    let current = initial;
+    const wrapped = {
+      get id() {
+        return current.id;
+      },
+      get ordinal() {
+        return current.ordinal;
+      },
+      get revision() {
+        return current.revision;
+      },
+      async update(text, options = {}) {
+        current = await track(
+          current.update(text, {
+            ...options,
+            operationId: options.operationId || nextOperationId("transient-update")
+          })
+        );
+        return wrapped;
+      },
+      settle(text, options = {}) {
+        return track(
+          current.settle(text, {
+            ...options,
+            operationId: options.operationId || nextOperationId("transient-settle")
+          })
+        );
+      }
+    };
+    return wrapped;
+  };
+  return {
+    feedback(text, options = {}) {
+      return track(
+        publisher.feedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("feedback")
+        })
+      );
+    },
+    transientFeedback(text, options = {}) {
+      return track(
+        publisher.transientFeedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("transient-create")
+        }).then(wrapTransientHandle)
+      );
+    },
+    async flush() {
+      let cursor = 0;
+      let firstError;
+      while (cursor < publications.length) {
+        const batch = publications.slice(cursor);
+        cursor = publications.length;
+        const results = await Promise.allSettled(batch);
+        for (const result of results) {
+          if (result.status === "rejected" && firstError === void 0) {
+            firstError = result.reason;
+          }
+        }
+      }
+      if (firstError !== void 0) {
+        throw firstError;
+      }
+    }
+  };
+}
+async function invokeRegisteredEffect(effectMap, request, options = {}) {
   const effect = selectRegisteredEffect(
     effectMap,
     request.effectKey,
@@ -12045,14 +13263,49 @@ async function invokeRegisteredEffect(effectMap, request) {
       mode: resolved.mode,
       sourceEffectKey: request.effectKey,
       sourceEffectName: request.effectName,
-      ...request.context?.invocation?.reverseHandler ? { reverseHandler: request.context.invocation.reverseHandler } : {}
+      ...request.context?.invocation?.reverseHandler ? { reverseHandler: request.context.invocation.reverseHandler } : {},
+      ...request.context?.invocation?.artifactId ? { artifactId: request.context.invocation.artifactId } : {},
+      ...request.context?.invocation?.artifactOptions ? { artifactOptions: request.context.invocation.artifactOptions } : {}
     }
   };
-  if (resolved.effect.className && !resolved.effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
-    const { _objectId, ...rest } = request.input;
-    return resolved.handler(_objectId, rest, context);
+  const feedbackContext = options.feedback ? createInvocationFeedbackContext(options.feedback) : null;
+  if (feedbackContext) {
+    context.feedback = feedbackContext.feedback;
+    context.transientFeedback = feedbackContext.transientFeedback;
+  }
+  let handlerResult;
+  let handlerError;
+  let handlerFailed = false;
+  try {
+    if (resolved.mode === "artifactOptions") {
+      handlerResult = await resolved.handler(request.input, context);
+    } else if (resolved.effect.className && !resolved.effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
+      const { _objectId, ...rest } = request.input;
+      handlerResult = await resolved.handler(_objectId, rest, context);
+    } else {
+      handlerResult = await resolved.handler(request.input, context);
+    }
+  } catch (error) {
+    handlerFailed = true;
+    handlerError = error;
   }
-  return resolved.handler(request.input, context);
+  let feedbackError;
+  let feedbackFailed = false;
+  if (feedbackContext) {
+    try {
+      await feedbackContext.flush();
+    } catch (error) {
+      feedbackFailed = true;
+      feedbackError = error;
+    }
+  }
+  if (handlerFailed) {
+    throw handlerError;
+  }
+  if (feedbackFailed) {
+    throw feedbackError;
+  }
+  return handlerResult;
 }
 
 // src/client-normalizers.ts
@@ -14062,6 +15315,36 @@ function buildEffectMetamodelMutations(toolPath, spec) {
 var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
 var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
 var MAX_CONVERSATION_SESSION_LIST_OFFSET = 1e5;
+function requireUserEnvironmentSequence(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(
+      `Invalid user-environment state: ${field} must be a non-negative safe integer.`
+    );
+  }
+  return value;
+}
+function normalizeReadThroughSequenceMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      "Invalid user-environment state: readThroughSequenceBySessionId is required."
+    );
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([sessionId, sequence]) => [
+      sessionId,
+      requireUserEnvironmentSequence(
+        sequence,
+        `readThroughSequenceBySessionId.${sessionId}`
+      )
+    ])
+  );
+}
+function requiredAssistantReplyString(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Assistant reply ${field} must be a non-empty string.`);
+  }
+  return field === "text" ? value : value.trim();
+}
 function boundedSessionListInteger(value, name, fallback, minimum, maximum) {
   if (value === void 0) return fallback;
   if (!Number.isInteger(value) || value < minimum || value > maximum) {
@@ -15635,12 +16918,55 @@ var Environment = class _Environment {
 var EnvironmentSession = class extends Session {
   environment;
   sessionDataRoutePrefix;
+  sessionDataHeaders;
+  heartbeatTimer = null;
+  heartbeatInFlight = false;
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
     super(client, clientId, { initialQuota: options.initialQuota });
     this.environment = environment;
     this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
+    this.sessionDataHeaders = options.sessionDataHeaders || {};
+    this.setFeedListTransport(
+      (feedOptions) => this.sessionDataRequest("/feed", feedOptions)
+    );
+  }
+  /**
+   * Keep the browser session transport observable from the client side.
+   * A worker/proxy restart can leave a browser WebSocket appearing OPEN even
+   * though the server-side Durable Object has already closed its peer. The
+   * heartbeat gives the SDK a bounded failure signal so it can revoke that
+   * stale socket and use WSClient's normal reconnect path.
+   */
+  startHeartbeat() {
+    if (this.heartbeatTimer) return;
+    this.heartbeatTimer = setInterval(() => {
+      if (this.heartbeatInFlight) return;
+      this.heartbeatInFlight = true;
+      void this.client.call("client.heartbeat", {}).then((result) => {
+        if (result?.graphContainerStatus) {
+          this.graphContainerStatus = result.graphContainerStatus;
+        }
+      }).catch((error) => {
+        this.client.reportTransportFailure(error);
+      }).finally(() => {
+        this.heartbeatInFlight = false;
+      });
+    }, 5e3);
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.heartbeatInFlight = false;
+  }
+  async hello() {
+    const result = await super.hello();
+    this.startHeartbeat();
+    return result;
   }
   get environmentId() {
     return this.environment.environmentId;
@@ -15700,6 +17026,11 @@ var EnvironmentSession = class extends Session {
         const response = await fetch(url, {
           method: init2.method || "GET",
           headers,
+          // Session documents, feed pages, and artifact reads are live
+          // Automerge-backed state. A browser cache entry for the identical
+          // artifact URL can otherwise make the Dock poll the same stale
+          // `running` record until a full reload revalidates it.
+          cache: "no-store",
           ...typeof init2.body === "undefined" ? {} : { body: init2.body }
         });
         if (response.ok) {
@@ -15728,34 +17059,50 @@ var EnvironmentSession = class extends Session {
     const body = typeof init2.body === "undefined" ? void 0 : JSON.stringify(init2.body);
     const response = await this.sessionDataFetch(path, query, {
       method: init2.method || "GET",
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        ...this.sessionDataHeaders,
+        "Content-Type": "application/json"
+      },
       ...typeof body === "undefined" ? {} : { body }
     });
     return response.json();
   }
-  async collectAllSessionItems(listPage) {
-    const items = [];
-    let cursor = null;
-    do {
-      const page = await listPage({ limit: 500, cursor });
-      items.push(...page.items);
-      cursor = page.nextCursor;
-    } while (cursor);
-    return items;
-  }
   /**
    * Fetch the live session document from the runtime DO.
    *
-   * For history and saved artifacts, prefer the collection APIs on
-   * `messages`, `timeline`, `jobs`, and `heap`.
+   * For presentation history use `feed.list()` or `transcript.list()`.
+   * Timeline and job collections are diagnostic/execution data only.
    */
   async getDocument() {
     return this.sessionDataRequest("/document");
   }
-  get messages() {
-    return {
-      list: (options = {}) => this.sessionDataRequest("/messages", options)
-    };
+  /**
+   * Publish one terminal assistant reply from a trusted server integration.
+   *
+   * This uses the API-key-authenticated HTTP session boundary. Delegated
+   * browser sessions cannot use it and never receive assistant feed-authoring
+   * capability through their WebSocket.
+   */
+  async publishAssistantReply(input) {
+    if (this.sessionDataRoutePrefix === "/sdk/browser-sessions") {
+      throw new Error(
+        "Assistant replies require a server API-key session connection."
+      );
+    }
+    const id = requiredAssistantReplyString(input.id, "id");
+    const operationId2 = requiredAssistantReplyString(
+      input.operationId,
+      "operationId"
+    );
+    const text = requiredAssistantReplyString(input.text, "text");
+    return this.sessionDataRequest(
+      "/assistant-replies",
+      void 0,
+      {
+        method: "POST",
+        body: { id, operationId: operationId2, text }
+      }
+    );
   }
   get timeline() {
     return {
@@ -15797,7 +17144,12 @@ var EnvironmentSession = class extends Session {
         latestJob: true
       }),
       get: (artifactId) => this.sessionDataRequest(
-        `/artifacts/${encodeURIComponent(artifactId)}`
+        `/artifacts/${encodeURIComponent(artifactId)}`,
+        // The artifact endpoint is polled while an effect is running. Keep
+        // each read addressable as a fresh resource as well as using
+        // `cache: no-store`; this also bypasses intermediaries that ignore
+        // the Fetch cache directive for an otherwise identical GET URL.
+        { _granularLiveRead: Date.now() }
       ),
       create: (artifact) => this.sessionDataRequest(
         "/artifacts",
@@ -15807,6 +17159,14 @@ var EnvironmentSession = class extends Session {
           body: artifact
         }
       ),
+      acceptSuggestion: (sequence) => this.sessionDataRequest(
+        "/artifacts/suggestions/accept",
+        void 0,
+        {
+          method: "POST",
+          body: { sequence }
+        }
+      ),
       updateInputs: (artifactId, patch) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}`,
         void 0,
@@ -15815,6 +17175,16 @@ var EnvironmentSession = class extends Session {
           body: patch
         }
       ),
+      relationshipOptions: (artifactId, input) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/relationship-options`,
+        void 0,
+        { method: "POST", body: input }
+      ),
+      relationshipCreate: (artifactId, input) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/relationship-create`,
+        void 0,
+        { method: "POST", body: input }
+      ),
       validate: (artifactId) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/validate`,
         void 0,
@@ -15952,73 +17322,50 @@ var EnvironmentSession = class extends Session {
   get transcript() {
     return {
       list: async (options = {}) => {
-        const [messages, jobs, entries, lists, artifacts] = await Promise.all([
-          this.collectAllSessionItems(this.messages.list),
-          this.collectAllSessionItems(
-            (pageOptions) => this.jobs.list({ ...pageOptions, status: "all" })
-          ),
-          this.collectAllSessionItems(this.heap.entries.list),
-          this.collectAllSessionItems(this.heap.lists.list),
-          this.collectAllSessionItems(
-            (pageOptions) => this.artifacts.list({ ...pageOptions, status: "all" })
-          )
-        ]);
-        const liveDoc = {
-          conversation: { messages },
-          jobs: {
-            byId: Object.fromEntries(
-              jobs.map((job) => {
-                const record = job && typeof job === "object" ? job : null;
-                const id = typeof record?.jobId === "string" ? record.jobId : typeof record?.id === "string" ? record.id : null;
-                return id ? [id, record] : null;
-              }).filter(
-                (entry) => Boolean(entry)
-              )
-            )
-          },
-          artifacts: {
-            byId: Object.fromEntries(
-              artifacts.map((artifact) => {
-                return artifact?.artifactId ? [
-                  artifact.artifactId,
-                  artifact
-                ] : null;
-              }).filter(
-                (entry) => Boolean(entry)
-              )
-            ),
-            order: artifacts.map((artifact) => artifact?.artifactId).filter(
-              (artifactId) => Boolean(artifactId)
-            )
+        if (!isCanonicalSessionFeedDocument(this.document)) {
+          throw new Error(
+            "Canonical session feed-v1 is required; transcript.list() does not reconstruct past message or job collections."
+          );
+        }
+        const canonicalFeedItems = [];
+        let afterSequence = 0;
+        let pageCount = 0;
+        for (; ; ) {
+          if (++pageCount > 1e4) {
+            throw new Error(
+              "Canonical transcript history exceeded its page limit."
+            );
           }
-        };
-        const heap = normalizeHeapSnapshot({
-          entriesByPath: Object.fromEntries(
-            entries.map((entry) => {
-              return entry?.path ? [entry.path, entry] : null;
-            }).filter(
-              (entry) => Boolean(entry)
-            )
-          ),
-          listsByName: Object.fromEntries(
-            lists.map((list) => {
-              return list?.name ? [list.name, list] : null;
-            }).filter(
-              (entry) => Boolean(entry)
-            )
-          ),
-          variablesByName: this.getHeap().variablesByName,
-          updatedAt: Date.now()
-        });
+          const page = await this.feed.list({
+            afterSequence,
+            limit: 500
+          });
+          if (page.items.length === 0) {
+            if (page.hasMoreAfter) {
+              throw new Error(
+                `Canonical transcript history stopped after sequence ${afterSequence}.`
+              );
+            }
+            break;
+          }
+          if (page.items[0].sequence !== afterSequence + 1) {
+            throw new Error(
+              `Canonical transcript history has a gap after sequence ${afterSequence}.`
+            );
+          }
+          canonicalFeedItems.push(...page.items);
+          afterSequence = page.items[page.items.length - 1].sequence;
+          if (!page.hasMoreAfter) break;
+        }
         const allItems = buildSessionTranscript({
-          liveDoc,
-          sessionHeap: heap
+          liveDoc: this.document,
+          canonicalFeedItems
         });
         const limit = Math.max(
           1,
           Math.min(500, Math.floor(options.limit ?? 100))
         );
-        const offset = typeof options.cursor === "string" ? Number.parseInt(options.cursor, 10) || 0 : 0;
+        const offset = options.latest ? Math.max(0, allItems.length - limit) : typeof options.cursor === "string" ? Number.parseInt(options.cursor, 10) || 0 : 0;
         const items = allItems.slice(offset, offset + limit);
         const nextOffset = offset + items.length;
         return {
@@ -16104,6 +17451,8 @@ var EnvironmentSession = class extends Session {
    * acknowledgement was observed.
    */
   async disconnect() {
+    this.stopHeartbeat();
+    this.disposeSessionFeed();
     let wsNotifiedRuntime = false;
     try {
       const goodbye = await this.rpc(
@@ -16142,6 +17491,7 @@ var EnvironmentSession = class extends Session {
    * Close only the socket transport without sending `client.goodbye`.
    */
   disconnectTransport() {
+    this.stopHeartbeat();
     this.client.disconnect({ reason: "Transport detach" });
   }
   /**
@@ -16906,16 +18256,22 @@ var Granular = class _Granular {
     return this.normalizeUserEnvironmentState(state);
   }
   async markUserEnvironmentSessionsRead(options) {
+    const readThroughSequence = requireUserEnvironmentSequence(
+      options.readThroughSequence,
+      "readThroughSequence"
+    );
     const result = await this.request("/sdk/user-environment-state/read", {
       method: "POST",
       body: JSON.stringify({
         environmentId: options.environmentId,
         sessionId: options.sessionId,
         sessionIds: options.sessionIds,
-        readAt: options.readAt
+        readThroughSequence
       })
     });
-    return result.readAtBySessionId || {};
+    return normalizeReadThroughSequenceMap(
+      result.readThroughSequenceBySessionId
+    );
   }
   normalizeConversationSession(row) {
     const sessionId = String(row.sessionId ?? row.session_id ?? "");
@@ -16940,21 +18296,48 @@ var Granular = class _Granular {
     };
   }
   normalizeUserEnvironmentState(state) {
+    if (!Array.isArray(state.sessions)) {
+      throw new Error(
+        "Invalid user-environment state: sessions must be an array."
+      );
+    }
+    const sessions = state.sessions.map((item, index) => ({
+      ...item,
+      readThroughSequence: requireUserEnvironmentSequence(
+        item?.readThroughSequence,
+        `sessions[${index}].readThroughSequence`
+      ),
+      messagePreview: {
+        ...item.messagePreview,
+        latestMessageSequence: requireUserEnvironmentSequence(
+          item.messagePreview?.latestMessageSequence,
+          `sessions[${index}].messagePreview.latestMessageSequence`
+        ),
+        latestAssistantSequence: requireUserEnvironmentSequence(
+          item.messagePreview?.latestAssistantSequence,
+          `sessions[${index}].messagePreview.latestAssistantSequence`
+        ),
+        unreadProducingSequence: requireUserEnvironmentSequence(
+          item.messagePreview?.unreadProducingSequence,
+          `sessions[${index}].messagePreview.unreadProducingSequence`
+        )
+      },
+      session: this.normalizeConversationSession(
+        item.session
+      )
+    }));
     return {
       ...state,
-      sessions: Array.isArray(state.sessions) ? state.sessions.map((item) => ({
-        ...item,
-        session: this.normalizeConversationSession(
-          item.session
-        )
-      })) : [],
+      sessions,
       attention: {
         prompts: Array.isArray(state.attention?.prompts) ? state.attention.prompts : [],
         count: typeof state.attention?.count === "number" ? state.attention.count : 0,
         activePrompt: state.attention?.activePrompt || null
       },
       unreadCount: typeof state.unreadCount === "number" ? state.unreadCount : 0,
-      readAtBySessionId: state.readAtBySessionId || {}
+      readThroughSequenceBySessionId: normalizeReadThroughSequenceMap(
+        state.readThroughSequenceBySessionId
+      )
     };
   }
   static coerceIsoDate(value) {
@@ -16985,7 +18368,9 @@ var Granular = class _Granular {
         environmentId: options.environmentId,
         clientId,
         sessionScope,
-        capabilities: sessionScope ? { sessionScope } : void 0,
+        capabilities: {
+          ...sessionScope ? { sessionScope } : {}
+        },
         initialHeap: options.initialHeap
       })
     });
@@ -17355,6 +18740,21 @@ var Granular = class _Granular {
           reconnectError
         );
         console.error("[Granular] Original heartbeat failure:", error);
+        if (this.onReconnectError) {
+          try {
+            this.onReconnectError({
+              sessionId: `effect-host:${host.effectClientId}`,
+              error: reconnectError instanceof Error ? reconnectError.message : String(reconnectError),
+              timestamp: Date.now(),
+              terminal: false
+            });
+          } catch (callbackError) {
+            console.error(
+              "[Granular] onReconnectError callback failed after effect-host recovery failure:",
+              callbackError
+            );
+          }
+        }
       }
     );
   }
@@ -17457,7 +18857,13 @@ var Granular = class _Granular {
         const request = params;
         return invokeRegisteredEffect(
           this.getSandboxEffectMap(sandboxId),
-          request
+          request,
+          {
+            feedback: {
+              invocationId: request.callId,
+              publish: (method, publishParams) => wsClient.call(method, publishParams)
+            }
+          }
         );
       });
       wsClient.on("open", () => {
@@ -17471,14 +18877,20 @@ var Granular = class _Granular {
       wsClient.on("disconnect", () => {
         this.stopEffectHostHeartbeat(host);
       });
-      await withTimeout(
-        wsClient.connect(),
-        EFFECT_HOST_CONNECT_TIMEOUT_MS,
-        `effect host WebSocket connect for sandbox ${sandboxId}`
-      );
-      await this.synchronizeEffectHost(host);
-      this.sandboxEffectHosts.set(sandboxId, host);
-      return host;
+      try {
+        await withTimeout(
+          wsClient.connect(),
+          EFFECT_HOST_CONNECT_TIMEOUT_MS,
+          `effect host WebSocket connect for sandbox ${sandboxId}`
+        );
+        await this.synchronizeEffectHost(host);
+        this.sandboxEffectHosts.set(sandboxId, host);
+        return host;
+      } catch (error) {
+        this.stopEffectHostHeartbeat(host);
+        wsClient.disconnect({ reason: "Effect host initialization failed" });
+        throw error;
+      }
     })();
     this.sandboxEffectHostPromises.set(sandboxId, connectPromise);
     try {
@@ -18355,7 +19767,7 @@ function asRecord4(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
-function asArray2(value) {
+function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
 function toSortedRecords(value) {
@@ -18530,14 +19942,30 @@ function hasNamedModuleImport(source, moduleName, name) {
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const imports = source.matchAll(
     new RegExp(
-      `import\\s*\\{([\\s\\S]*?)\\}\\s*from\\s*['"]${escapedModule}['"]`,
+      `import\\s*\\{([^}]*)\\}\\s*from\\s*['"]${escapedModule}['"]`,
       "g"
     )
   );
   for (const match of imports) {
     if (new RegExp(`\\b${escaped}\\b`).test(match[1])) return true;
   }
-  return false;
+  return false;
+}
+function namedModuleImports(source, moduleName) {
+  const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = /* @__PURE__ */ new Set();
+  for (const match of source.matchAll(
+    new RegExp(
+      `import\\s*\\{([^}]*)\\}\\s*from\\s*['"]${escapedModule}['"]`,
+      "g"
+    )
+  )) {
+    for (const specifier of match[1].split(",")) {
+      const imported = specifier.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
+      if (imported) names.add(imported);
+    }
+  }
+  return [...names];
 }
 function hasNamedAgentImport(source, name) {
   return hasNamedModuleImport(source, HARNESS_V3_AGENT_MODULE, name);
@@ -18599,18 +20027,54 @@ function reviewGeneratedJobCode(code, _options = {}) {
       message: "Generated jobs must not call process.exit(...). Return from the job or emit a runtime message instead."
     });
   }
+  const supportedAgentExports = /* @__PURE__ */ new Set([
+    "actions",
+    "artifacts",
+    "feedback",
+    "formatBlockers",
+    "relativeTime",
+    "replyToUser",
+    "showAgentResponse",
+    "showObjects",
+    "table",
+    "transientFeedback"
+  ]);
+  for (const imported of namedModuleImports(
+    normalized,
+    HARNESS_V3_AGENT_MODULE
+  )) {
+    if (!supportedAgentExports.has(imported)) {
+      issues.push({
+        code: "unknown_runtime_import",
+        severity: "error",
+        message: `Generated code imports unknown runtime value \`${imported}\` from ${HARNESS_V3_AGENT_MODULE}. Import only values listed in [Runtime Imports] and [Types].`
+      });
+    }
+  }
+  const removedAgentHelpers = [
+    ["agent", "text", "message"].join("_"),
+    ["agent", "heap", "objects"].join("_"),
+    ["agent", "message"].join("_")
+  ];
+  for (const name of removedAgentHelpers) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`\\b${escaped}\\s*\\(`).test(normalized)) {
+      issues.push({
+        code: "unsupported_runtime_helper",
+        severity: "error",
+        message: `Generated code calls removed runtime helper \`${name}\`. Import and call only the canonical feed helpers listed for ${HARNESS_V3_AGENT_MODULE}.`
+      });
+    }
+  }
   for (const [name, replacement, pattern] of [
-    ["agent_text_message", "replyToUser", /\bagent_text_message\s*\(/],
-    ["agent_heap_objects", "showObjects", /\bagent_heap_objects\s*\(/],
-    ["agent_message", "showAgentResponse", /\bagent_message\s*\(/],
     ["heap", "groundedObjects", /\bheap\./],
     ["loop", "userInteraction or work", /\bloop\./]
   ]) {
     if (pattern.test(normalized)) {
       issues.push({
-        code: "deprecated_runtime_helper",
+        code: "unsupported_runtime_helper",
         severity: "error",
-        message: `Generated code uses legacy runtime helper \`${name}\`. Use Harness v3 helper \`${replacement}\` from the modules listed in [Runtime Imports].`
+        message: `Generated code uses unsupported runtime helper \`${name}\`. Use \`${replacement}\` from the modules listed in [Runtime Imports].`
       });
     }
   }
@@ -18779,116 +20243,7 @@ function normalizeActionSummaryForPrompt(line) {
 }
 function collectConversationReferents(liveDoc) {
   const conversation = asRecord4(liveDoc?.conversation);
-  const persistedReferents = asArray2(conversation?.referents).map((value) => asRecord4(value)).filter((value) => Boolean(value));
-  if (persistedReferents.length > 0) {
-    return persistedReferents.slice().sort((left, right) => (right.ts || 0) - (left.ts || 0));
-  }
-  const heap = asRecord4(liveDoc?.heap);
-  const entriesByPath = asRecord4(heap?.entriesByPath) || {};
-  const listsByName = asRecord4(heap?.listsByName) || {};
-  const variablesByName = asRecord4(heap?.variablesByName) || {};
-  const messages = asArray2(conversation?.messages).map((value) => asRecord4(value)).filter((value) => Boolean(value)).slice().sort((left, right) => (Number(right.ts) || 0) - (Number(left.ts) || 0));
-  const referents = [];
-  const seen = /* @__PURE__ */ new Set();
-  const pushReferent = (referent) => {
-    if (!referent?.kind || !referent.ref) return;
-    const key = `${referent.kind}:${referent.ref}`;
-    if (seen.has(key)) return;
-    seen.add(key);
-    referents.push(referent);
-  };
-  for (const message of messages) {
-    if (message.role !== "assistant") continue;
-    const show = asRecord4(message.show);
-    if (!show) continue;
-    const ts = Number(message.ts) || 0;
-    const messageId = typeof message.id === "string" ? message.id : void 0;
-    const jobId = typeof message.jobId === "string" ? message.jobId : void 0;
-    const entryPaths = uniqueStrings(asArray2(show.entryPaths));
-    const entryClassCounts = /* @__PURE__ */ new Map();
-    const entryMetadata = entryPaths.map((entryPath) => {
-      const entry = asRecord4(entriesByPath[entryPath]);
-      const className = typeof entry?.className === "string" ? entry.className : void 0;
-      if (className) {
-        entryClassCounts.set(
-          className,
-          (entryClassCounts.get(className) || 0) + 1
-        );
-      }
-      return { entryPath, entry, className };
-    });
-    const displayGroupId = entryMetadata.length > 1 ? `message:${messageId || jobId || ts}:entries` : void 0;
-    for (const [
-      index,
-      { entryPath, entry, className }
-    ] of entryMetadata.entries()) {
-      pushReferent({
-        id: `entry:${entryPath}`,
-        kind: "entry",
-        ref: entryPath,
-        role: "assistant",
-        source: "heap_objects",
-        entryPath,
-        recordId: typeof entry?.id === "string" ? entry.id : void 0,
-        className,
-        label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : entryPath,
-        ...displayGroupId ? {
-          displayGroupId,
-          displayGroupIndex: index,
-          displayGroupSize: entryMetadata.length,
-          ...className && (entryClassCounts.get(className) || 0) > 1 ? { displayGroupSameTypeSize: entryClassCounts.get(className) } : {}
-        } : {},
-        messageId,
-        jobId,
-        ts
-      });
-    }
-    for (const listName of uniqueStrings(asArray2(show.listNames))) {
-      const list = asRecord4(listsByName[listName]);
-      pushReferent({
-        id: `list:${listName}`,
-        kind: "list",
-        ref: listName,
-        role: "assistant",
-        source: "heap_objects",
-        listName,
-        className: typeof list?.className === "string" ? list.className : void 0,
-        count: Array.isArray(list?.paths) ? list.paths.length : null,
-        messageId,
-        jobId,
-        ts
-      });
-    }
-    for (const variableName of uniqueStrings(
-      asArray2(show.variableNames)
-    )) {
-      const variable = asRecord4(variablesByName[variableName]);
-      const entryPath = typeof variable?.entryPath === "string" ? variable.entryPath : void 0;
-      const listName = typeof variable?.listName === "string" ? variable.listName : void 0;
-      const entry = entryPath ? asRecord4(entriesByPath[entryPath]) : null;
-      const list = listName ? asRecord4(listsByName[listName]) : null;
-      pushReferent({
-        id: `variable:${variableName}`,
-        kind: "variable",
-        ref: variableName,
-        role: "assistant",
-        source: "heap_objects",
-        variableName,
-        variableKind: typeof variable?.kind === "string" ? variable.kind : void 0,
-        entryPath,
-        recordId: typeof entry?.id === "string" ? entry.id : void 0,
-        listName,
-        className: typeof variable?.className === "string" ? variable.className : typeof entry?.className === "string" ? entry.className : typeof list?.className === "string" ? list.className : void 0,
-        label: typeof entry?.label === "string" && entry.label.trim() ? entry.label.trim() : typeof entry?.id === "string" && entry.id.trim() ? entry.id.trim() : null,
-        count: variable?.kind === "list" && Array.isArray(list?.paths) ? list.paths.length : null,
-        scalarValue: variable?.kind === "scalar" && (typeof variable.value === "string" || typeof variable.value === "number" || typeof variable.value === "boolean" || variable.value === null) ? variable.value : void 0,
-        messageId,
-        jobId,
-        ts
-      });
-    }
-  }
-  return referents;
+  return asArray(conversation?.referents).map((value) => asRecord4(value)).filter((value) => Boolean(value)).slice().sort((left, right) => (right.ts || 0) - (left.ts || 0));
 }
 function projectConversationReferentFocus(liveDoc) {
   const heap = asRecord4(liveDoc?.heap);
@@ -18910,7 +20265,7 @@ function projectConversationReferentFocus(liveDoc) {
       listCount += 1;
       listNames.push(referent.listName);
       const list = asRecord4(listsByName[referent.listName]);
-      entryPaths.push(...asArray2(list?.paths).slice(0, 4));
+      entryPaths.push(...asArray(list?.paths).slice(0, 4));
       continue;
     }
     if (referent.kind === "variable" && typeof referent.variableName === "string" && variableCount < 4) {
@@ -18922,7 +20277,7 @@ function projectConversationReferentFocus(liveDoc) {
       if (typeof referent.listName === "string") {
         listNames.push(referent.listName);
         const list = asRecord4(listsByName[referent.listName]);
-        entryPaths.push(...asArray2(list?.paths).slice(0, 4));
+        entryPaths.push(...asArray(list?.paths).slice(0, 4));
       }
     }
   }
@@ -19100,12 +20455,12 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
   const openDecisionIds = [];
   const openPromptIds = [];
   for (const job of jobs) {
-    for (const line of asArray2(job.actionSummary)) {
+    for (const line of asArray(job.actionSummary)) {
       if (typeof line === "string" && line.trim()) {
         actionSummaryLines.push(line.trim());
       }
     }
-    for (const rawEvent of asArray2(job.actionTrace)) {
+    for (const rawEvent of asArray(job.actionTrace)) {
       const event = asRecord4(rawEvent);
       const details = asRecord4(event?.details);
       const outcome = asRecord4(event?.outcome);
@@ -19202,7 +20557,7 @@ function projectWorkflowFocus(liveDoc, pendingPrompts = [], options) {
   }
   for (const listName of uniqueStrings(listNames)) {
     const list = asRecord4(listsByName[listName]);
-    for (const path of asArray2(list?.paths).slice(0, 4)) {
+    for (const path of asArray(list?.paths).slice(0, 4)) {
       entryPaths.push(path);
     }
   }
@@ -19322,7 +20677,7 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
       id: typeof decision.decisionId === "string" ? decision.decisionId : "unknown",
       title: typeof decision.title === "string" && decision.title.trim() ? decision.title.trim() : "Decision",
       status,
-      candidates: status === "open" ? asArray2(decision.candidates).slice(0, 5).map((candidate) => {
+      candidates: status === "open" ? asArray(decision.candidates).slice(0, 5).map((candidate) => {
         const record = asRecord4(candidate);
         if (!record) return null;
         return {
@@ -19480,7 +20835,7 @@ function projectHeapSummary(heap, options) {
           type: entry.className || "unknown",
           id: entry.id || null,
           label: entry.label || entry.id || null,
-          fields: asArray2(entry.fields).filter(
+          fields: asArray(entry.fields).filter(
             (field) => field?.name && field.name !== "_realId" && field.name !== "real_id"
           ).slice(0, 3).map((field) => ({
             name: field.name,
@@ -19644,7 +20999,7 @@ function buildGranularAgentManualActionBlock(manualActionSummary) {
 function projectSessionFileSummary(liveDoc) {
   const files = asRecord4(liveDoc?.files);
   const byId = asRecord4(files?.byId) || {};
-  const order = asArray2(files?.order);
+  const order = asArray(files?.order);
   const items = order.map((fileId) => asRecord4(byId[fileId])).filter((file) => Boolean(file)).filter((file) => file.status !== "deleted").slice(0, 24).map((file) => ({
     fileId: typeof file.fileId === "string" ? file.fileId : null,
     filename: typeof file.filename === "string" ? file.filename : typeof file.safeFilename === "string" ? file.safeFilename : null,
@@ -19682,13 +21037,7 @@ function extractRuntimeContractExports(domainBlock) {
   }
   const actionPattern = /export\s+declare\s+function\s+([A-Za-z_$][\w$]*)/g;
   for (const match of domainBlock.matchAll(actionPattern)) {
-    const name = match[1];
-    if (["agent_text_message", "agent_heap_objects", "agent_message"].includes(
-      name
-    )) {
-      continue;
-    }
-    actions.add(name);
+    actions.add(match[1]);
   }
   return {
     classes: Array.from(classes).sort(),
@@ -19745,7 +21094,7 @@ function buildGranularAgentRuntimeImportsBlock(input) {
         importStyle: "named ESM imports only",
         exports: ["replyToUser", "showObjects", "showAgentResponse"],
         contains: "User-facing Harness response helpers for text, grounded object displays, and combined responses.",
-        rule: "Import reply/display helpers from this module; do not use deprecated side-channel helpers."
+        rule: "Import reply/display helpers from this module; only the listed exports are available."
       },
       [HARNESS_V3_SESSION_MODULE]: {
         importStyle: "named ESM imports only",
@@ -19986,7 +21335,7 @@ function summarizeObjectSchema(schema) {
   if (!properties || Object.keys(properties).length === 0) {
     return record ? "{}" : null;
   }
-  const required = new Set(asArray2(record?.required));
+  const required = new Set(asArray(record?.required));
   const fields = Object.entries(properties).slice(0, 8).map(([name, property]) => {
     const marker = required.has(name) ? "*" : "?";
     return `${name}${marker}: ${jsonSchemaTypeName(property)}`;
@@ -20023,9 +21372,9 @@ function splitDomainDocumentation(domainDocumentation) {
   return { types: normalized, docs: "" };
 }
 var DOMAIN_HELPER_FUNCTION_NAMES = /* @__PURE__ */ new Set([
-  "agent_heap_objects",
-  "agent_message",
-  "agent_text_message"
+  "replyToUser",
+  "showAgentResponse",
+  "showObjects"
 ]);
 function inferGlobalActionToolsFromDomainTypes(domainTypes) {
   const inferred = [];
@@ -20161,7 +21510,7 @@ function buildKnownFactsFromCheckpoint(checkpoint) {
   return facts.slice(0, 8);
 }
 function buildGranularAgentSystemPrompt(input) {
-  const outputMode = input.outputMode || "agentMessages";
+  const outputMode = input.outputMode || "feed";
   const promptCapabilities = resolvePromptCapabilities(input.capabilities);
   const domainSections = splitDomainDocumentation(input.domainDocumentation);
   const promptTools = resolvePromptTools(input.tools, domainSections.types);
@@ -20194,7 +21543,7 @@ function buildGranularAgentSystemPrompt(input) {
 - For multi-record display, prefer a saved list/listName so the UI can render a table; use entryPaths for a few individual records.
 - When the user asks to show, list, display, open, or "show them" for records you found, include those grounded records in \`show\`; do not answer only with a count or text summary.
 - For count-only questions such as "how many", "how many X do I have", or "what is the total number of X", call the entity \`.count(...)\` or use page \`totalCount\` only when a page is already needed for other reasons. Answer with text only. Do not fetch, save, or display sample records just to ground a numeric count.
-- Use \`replyToUser(...)\`, \`showObjects(...)\`, or \`showAgentResponse(...)\` from \`@granular/agent\` when the host exposes job output helpers; do not call deprecated side-channel helpers.` : `- End every user-facing job by returning a short natural-language string.` : promptCapabilities.showRecords ? `- Every job that answers the user must emit \`replyToUser(...)\`, \`showObjects(...)\`, and/or \`showAgentResponse(...)\` from \`@granular/agent\`.
+- Use \`replyToUser(...)\`, \`showObjects(...)\`, or \`showAgentResponse(...)\` from \`@granular/agent\` when the host exposes job output helpers.` : `- End every user-facing job by returning a short natural-language string.` : promptCapabilities.showRecords ? `- Every job that answers the user must emit \`replyToUser(...)\`, \`showObjects(...)\`, and/or \`showAgentResponse(...)\` from \`@granular/agent\`.
 - \`replyToUser(...)\` displays text directly to the user in the host UI. Treat it as the user-facing progress and reply channel, not as a debug log.
   - For long-running or multi-step jobs, send several short \`replyToUser(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
   - Write \`replyToUser(...)\` content in a friendly, readable product-assistant style: concrete, concise, and natural. Avoid robotic status dumps, raw implementation names, and unexplained IDs unless the ID helps the user.
@@ -20204,11 +21553,10 @@ function buildGranularAgentSystemPrompt(input) {
   - Do not use \`showObjects({ entries: [...] })\` or \`showObjects({ saveAs, entries })\`. Save ordered pages, queues, search results, or ranked lists with \`groundedObjects.save(...)\`, then call \`showObjects({ variableNames: [...] })\` once.
   - Use \`showAgentResponse({ reply, show: [record, action] })\` when one assistant message should combine text, grounded records, files, prepared actions, or action suggestions. The \`action\` can be a state handle such as \`record.lifecycle.approved\` or an action handle such as \`record.lifecycle.approved.reach()\`.
   - Pass grounded records directly in \`show\` when the default record presentation answers the request. When the user asks for particular columns, comparisons, or computed values, import \`table\` (and \`relativeTime\` when useful) from \`@granular/agent\` and call \`showAgentResponse({ reply, show: table(records, [{ label: "Object", value: record => record.label }, { label: "When", value: record => relativeTime(record.timestamp) }]) })\`. Column callbacks must be synchronous and return a scalar, \`Date\`, or \`relativeTime(...)\`; they run inside the job and only resolved cells are persisted.
-  - Do not use deprecated side-channel helpers such as \`agent_text_message(...)\`, \`agent_heap_objects(...)\`, or \`agent_message(...)\` unless the generated types expose no Harness v3 helper alternative.
   - When the user asks to show, list, display, open, or "show them" for records you found, call \`showObjects(...)\`; do not answer only with a count or text summary.
   - For count-only questions such as "how many", "how many X do I have", or "what is the total number of X", call the entity \`.count(...)\` or use page \`totalCount\` only when a page is already needed for other reasons. Answer with \`replyToUser(...)\` only. Do not call \`showObjects(...)\`, \`saveAs\`, or \`groundedObjects.save(...)\` unless the user also asked to see records or a later requested action needs a reusable record selection.
   - Use stable saved list names that preserve identity and ordering so later references such as "the second item" or "back on the first slice" resolve to the correct earlier slice, not merely the most recent record.
-  - Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit agent message calls.` : `- Every job that answers the user must emit \`replyToUser(...)\` from \`@granular/agent\`.
+  - Do not rely on the final return value for UI output. Do not return ad-hoc \`reply\` / \`show\` payloads instead of explicit canonical feed calls.` : `- Every job that answers the user must emit \`replyToUser(...)\` from \`@granular/agent\`.
 - \`replyToUser(...)\` displays text directly to the user in the host UI. Treat it as the user-facing progress and reply channel, not as a debug log.
 - For long-running or multi-step jobs, send several short \`replyToUser(...)\` updates as useful milestones are reached so the user can see what is happening instead of waiting in silence.
 - Write \`replyToUser(...)\` content in a friendly, readable product-assistant style: concrete, concise, and natural. Avoid robotic status dumps, raw implementation names, and unexplained IDs unless the ID helps the user.
@@ -20708,6 +22056,231 @@ function buildContinuationInstructionFromTemplate(resultPreview, options) {
   return renderContinuationInstructionFromTemplate(resultPreview, options).instruction;
 }
 
+// src/job-presentation.ts
+var ENTRY_KEY_CANDIDATES = ["entryPath", "path"];
+var ENTRY_ARRAY_KEY_CANDIDATES = ["entryPaths", "paths"];
+var LIST_KEY_CANDIDATES = ["listName"];
+var LIST_ARRAY_KEY_CANDIDATES = ["listNames"];
+var VARIABLE_KEY_CANDIDATES = ["variableName"];
+var VARIABLE_ARRAY_KEY_CANDIDATES = ["variableNames"];
+var UI_CONTAINER_KEYS = ["show", "display", "present", "ui"];
+function asRecord5(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function responseTextFromFeedItems(feedItems, jobId) {
+  let latestSequence = -1;
+  let latestText = null;
+  for (const item of feedItems) {
+    if (item.kind !== "message" || item.payload.role !== "assistant" || item.source?.jobId !== jobId || item.sequence <= latestSequence) {
+      continue;
+    }
+    const text = item.payload.text.trim();
+    if (!text) continue;
+    latestSequence = item.sequence;
+    latestText = text;
+  }
+  return latestText;
+}
+function pushString(target, value) {
+  if (typeof value === "string" && value.trim()) {
+    target.add(value.trim());
+  }
+}
+function pushStringArray(target, value) {
+  if (!Array.isArray(value)) return;
+  for (const item of value) {
+    pushString(target, item);
+  }
+}
+function collectReferencesFromRecord(record, refs) {
+  for (const key of ENTRY_KEY_CANDIDATES)
+    pushString(refs.entryPaths, record[key]);
+  for (const key of ENTRY_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.entryPaths, record[key]);
+  for (const key of LIST_KEY_CANDIDATES)
+    pushString(refs.listNames, record[key]);
+  for (const key of LIST_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.listNames, record[key]);
+  for (const key of VARIABLE_KEY_CANDIDATES)
+    pushString(refs.variableNames, record[key]);
+  for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
+    pushStringArray(refs.variableNames, record[key]);
+}
+function stringValue(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+function findEntryPathForRecord(record, heap) {
+  const directPath = stringValue(record, ["entryPath", "path"]);
+  if (directPath && heap.entriesByPath?.[directPath]) {
+    return directPath;
+  }
+  const id = stringValue(record, ["id", "_id", "recordId", "objectId"]);
+  if (!id) {
+    return null;
+  }
+  const className = stringValue(record, [
+    "className",
+    "_className",
+    "__className",
+    "prototype",
+    "type"
+  ]);
+  const entries = Object.values(heap.entriesByPath || {});
+  const exact = entries.find(
+    (entry) => entry.id === id && (!className || entry.className === className || entry.prototypes?.includes(className))
+  );
+  if (exact?.path) {
+    return exact.path;
+  }
+  const idOnlyMatches = entries.filter((entry) => entry.id === id);
+  return idOnlyMatches.length === 1 ? idOnlyMatches[0].path : null;
+}
+function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || value === void 0 || depth > 4 || seen.has(value))
+    return;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (heap.entriesByPath?.[trimmed]) refs.entryPaths.add(trimmed);
+    if (heap.listsByName?.[trimmed]) refs.listNames.add(trimmed);
+    if (heap.variablesByName?.[trimmed]) refs.variableNames.add(trimmed);
+    return;
+  }
+  if (Array.isArray(value)) {
+    seen.add(value);
+    for (const item of value.slice(0, 24)) {
+      scanForHeapReferences(item, heap, refs, depth + 1, seen);
+    }
+    return;
+  }
+  const record = asRecord5(value);
+  if (!record) return;
+  seen.add(value);
+  const entryPath = findEntryPathForRecord(record, heap);
+  if (entryPath) refs.entryPaths.add(entryPath);
+  collectReferencesFromRecord(record, refs);
+  for (const key of UI_CONTAINER_KEYS) {
+    const nested = asRecord5(record[key]);
+    if (nested) collectReferencesFromRecord(nested, refs);
+  }
+  for (const nested of Object.values(record).slice(0, 24)) {
+    scanForHeapReferences(nested, heap, refs, depth + 1, seen);
+  }
+}
+function resolveVariablesToReferences(variableNames, heap, refs) {
+  for (const variableName of variableNames) {
+    const variable = heap.variablesByName?.[variableName];
+    if (!variable) continue;
+    if (variable.kind === "entry" && variable.entryPath) {
+      refs.entryPaths.add(variable.entryPath);
+    }
+    if (variable.kind === "list" && variable.listName) {
+      refs.listNames.add(variable.listName);
+    }
+  }
+}
+function sortEntries(entries) {
+  return [...entries].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+function sortLists(lists) {
+  return [...lists].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+function dedupeEntries(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const entry of entries) {
+    if (!entry?.path || seen.has(entry.path)) continue;
+    seen.add(entry.path);
+    result.push(entry);
+  }
+  return result;
+}
+function dedupeLists(lists) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const list of lists) {
+    if (!list?.name || seen.has(list.name)) continue;
+    seen.add(list.name);
+    result.push(list);
+  }
+  return result;
+}
+function getJobRelatedEntries(heap, jobId) {
+  return sortEntries(
+    Object.values(heap.entriesByPath || {}).filter(
+      (entry) => entry.relatedJobIds?.includes(jobId)
+    )
+  );
+}
+function getJobRelatedLists(heap, jobId) {
+  return sortLists(
+    Object.values(heap.listsByName || {}).filter(
+      (list) => list.relatedJobIds?.includes(jobId)
+    )
+  );
+}
+function entriesFromLists(lists, heap) {
+  const entries = [];
+  for (const list of lists) {
+    for (const path of list.paths || []) {
+      const entry = heap.entriesByPath?.[path];
+      if (entry) entries.push(entry);
+    }
+  }
+  return entries;
+}
+function resolveJobPresentation({
+  jobId,
+  result,
+  feedItems = [],
+  sessionHeap,
+  allowExplicitArtifacts = true
+}) {
+  const refs = {
+    entryPaths: /* @__PURE__ */ new Set(),
+    listNames: /* @__PURE__ */ new Set(),
+    variableNames: /* @__PURE__ */ new Set()
+  };
+  if (allowExplicitArtifacts) {
+    scanForHeapReferences(result, sessionHeap, refs);
+    resolveVariablesToReferences(refs.variableNames, sessionHeap, refs);
+  }
+  const referencedLists = sortLists(
+    [...refs.listNames].map((name) => sessionHeap.listsByName?.[name]).filter((list) => Boolean(list))
+  );
+  const referencedEntries = sortEntries(
+    [...refs.entryPaths].map((path) => sessionHeap.entriesByPath?.[path]).filter((entry) => Boolean(entry))
+  );
+  const jobLists = getJobRelatedLists(sessionHeap, jobId);
+  const jobEntries = getJobRelatedEntries(sessionHeap, jobId);
+  const changedEntries = dedupeEntries([
+    ...jobEntries,
+    ...entriesFromLists(jobLists, sessionHeap)
+  ]);
+  const explicitLists = dedupeLists(referencedLists);
+  const explicitEntries = dedupeEntries([
+    ...referencedEntries,
+    ...entriesFromLists(referencedLists, sessionHeap)
+  ]);
+  const hasExplicitArtifacts = allowExplicitArtifacts && (explicitEntries.length > 0 || explicitLists.length > 0);
+  const lists = hasExplicitArtifacts ? explicitLists : jobLists;
+  const entries = hasExplicitArtifacts ? explicitEntries : changedEntries;
+  return {
+    responseText: responseTextFromFeedItems(feedItems, jobId),
+    entries,
+    lists,
+    changedEntries,
+    changedLists: jobLists,
+    hasExplicitArtifacts
+  };
+}
+
 // src/openai-usage.ts
 var OPENAI_GPT_5_4_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/models/gpt-5.4/";
 var OPENAI_GPT_5_6_PRICING_SOURCE_URL = "https://developers.openai.com/api/docs/pricing";
@@ -20727,22 +22300,22 @@ var OPENAI_MODEL_PRICING_USD_PER_MILLION = {
     provider: "openai",
     model: "gpt-5.6-luna",
     currency: "USD",
-    inputUsdPerMillion: 1,
-    cachedInputUsdPerMillion: 0.1,
-    cacheWriteUsdPerMillion: 1.25,
-    outputUsdPerMillion: 6,
+    inputUsdPerMillion: 0.2,
+    cachedInputUsdPerMillion: 0.02,
+    cacheWriteUsdPerMillion: 0.25,
+    outputUsdPerMillion: 1.2,
     sourceUrl: OPENAI_GPT_5_6_PRICING_SOURCE_URL,
-    effectiveDate: "2026-07-11",
+    effectiveDate: "2026-07-30",
     longContextThresholdTokens: OPENAI_LONG_CONTEXT_THRESHOLD_TOKENS,
     longContextPricing: {
-      inputUsdPerMillion: 2,
-      cachedInputUsdPerMillion: 0.2,
-      cacheWriteUsdPerMillion: 2.5,
-      outputUsdPerMillion: 9
+      inputUsdPerMillion: 0.4,
+      cachedInputUsdPerMillion: 0.04,
+      cacheWriteUsdPerMillion: 0.5,
+      outputUsdPerMillion: 1.8
     }
   }
 };
-function asRecord5(value) {
+function asRecord6(value) {
   return value && typeof value === "object" ? value : null;
 }
 function numberField(record, key) {
@@ -20766,7 +22339,7 @@ function getOpenAIModelPricing(model, inputTokens = 0) {
   return { ...pricing, contextTier: "short" };
 }
 function normalizeOpenAIUsage(rawUsage) {
-  const usage = asRecord5(rawUsage);
+  const usage = asRecord6(rawUsage);
   if (!usage) {
     return {
       inputTokens: 0,
@@ -20781,8 +22354,8 @@ function normalizeOpenAIUsage(rawUsage) {
   const inputTokens = numberField(usage, "prompt_tokens") || numberField(usage, "input_tokens");
   const outputTokens = numberField(usage, "completion_tokens") || numberField(usage, "output_tokens");
   const totalTokens = numberField(usage, "total_tokens") || inputTokens + outputTokens;
-  const inputDetails = asRecord5(usage.prompt_tokens_details) || asRecord5(usage.input_tokens_details);
-  const outputDetails = asRecord5(usage.completion_tokens_details) || asRecord5(usage.output_tokens_details);
+  const inputDetails = asRecord6(usage.prompt_tokens_details) || asRecord6(usage.input_tokens_details);
+  const outputDetails = asRecord6(usage.completion_tokens_details) || asRecord6(usage.output_tokens_details);
   const cachedInputTokens = Math.min(
     inputTokens,
     numberField(inputDetails, "cached_tokens") || numberField(inputDetails, "cached_input_tokens")
@@ -20850,6 +22423,6 @@ function calculateOpenAITokenSpend(model, rawUsage) {
   };
 }
 
-export { Environment, EnvironmentSession, Granular, OPENAI_MODEL_PRICING_USD_PER_MILLION, OntologyHandle, Session, WSClient, buildContinuationInstruction, buildContinuationInstructionFromTemplate, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentFileBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentManualActionBlock, buildGranularAgentManualActionMemorySummary, buildGranularAgentReferentBlock, buildGranularAgentRuntimeImportsBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentSystemPromptFromTemplate, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, buildOpenAISpendEventId, buildSessionTranscript, calculateOpenAITokenSpend, consumeGranularReasoningOnlyChunk, consumeGranularReasoningTraceChunk, createHarnessVerifierSnapshot, evaluateContinuation, evaluateValidationRule, extractPromptTokens, getCurrentClosureId, getDefaultHarnessTemplateId, getExclusivePromptTarget, getOpenAIModelPricing, hasOpenPrompt, hashHarnessTemplateValue, invokeRegisteredEffect, isLocalApiUrl, listHarnessTemplates, normalizeEffectBehaviors, normalizeOpenAIUsage, normalizePrompt, normalizePromptChoiceOption, normalizePromptText, normalizePromptType, projectConversationReferentFocus, projectConversationReferentSummary, projectHeapSummary, projectLoopSummary, projectSessionFileSummary, projectWorkflowFocus, projectWorkflowSummary, recordOpenAIUsageSpend, renderContinuationInstructionFromTemplate, renderGranularAgentSystemPromptFromTemplate, resolveApiUrl, resolveAuthTokenForApiUrl, resolveHarnessTemplate, resolveJobPresentation, resolvePromptAnswer, reviewGeneratedJobCode, scorePromptChoiceMatch, stripGranularReasoningTrace, toGranularHttpBase, validateHarnessTemplateManifest, validationRuleFailureMessage };
+export { Environment, EnvironmentSession, GRANULAR_FEED_DIAGNOSTIC_EVENT, Granular, OPENAI_MODEL_PRICING_USD_PER_MILLION, OntologyHandle, Session, SessionFeedController, WSClient, buildContinuationInstruction, buildContinuationInstructionFromTemplate, buildGranularAgentCheckpointBlock, buildGranularAgentDomainBlock, buildGranularAgentFileBlock, buildGranularAgentHeapBlock, buildGranularAgentLoopBlock, buildGranularAgentManualActionBlock, buildGranularAgentManualActionMemorySummary, buildGranularAgentReferentBlock, buildGranularAgentRuntimeImportsBlock, buildGranularAgentSessionBlock, buildGranularAgentSystemPrompt, buildGranularAgentSystemPromptFromTemplate, buildGranularAgentToolBlock, buildGranularAgentWorkflowBlock, buildOpenAISpendEventId, buildSessionTranscript, buildSessionTranscriptFromFeedItems, calculateOpenAITokenSpend, consumeGranularReasoningOnlyChunk, consumeGranularReasoningTraceChunk, createFeedPublisher, createHarnessVerifierSnapshot, emitFeedDiagnostic, emitFeedDiagnosticToDefaultSink, emptyFeedSnapshot, evaluateContinuation, evaluateValidationRule, extractPromptTokens, getCurrentClosureId, getDefaultHarnessTemplateId, getExclusivePromptTarget, getOpenAIModelPricing, hasCanonicalSessionFeedActivation, hasOpenPrompt, hashHarnessTemplateValue, invokeRegisteredEffect, isCanonicalSessionFeedDocument, isLocalApiUrl, listHarnessTemplates, mergeFeedItemsBySequence, normalizeEffectBehaviors, normalizeFeedDiagnostic, normalizeFeedDiagnosticKind, normalizeFeedPage, normalizeOpenAIUsage, normalizePrompt, normalizePromptChoiceOption, normalizePromptText, normalizePromptType, orderTransientFeedItems, projectConversationReferentFocus, projectConversationReferentSummary, projectHeapSummary, projectLoopSummary, projectSessionFileSummary, projectWorkflowFocus, projectWorkflowSummary, readSessionFeedSnapshot, recordOpenAIUsageSpend, renderContinuationInstructionFromTemplate, renderGranularAgentSystemPromptFromTemplate, resolveApiUrl, resolveAuthTokenForApiUrl, resolveHarnessTemplate, resolveJobPresentation, resolvePromptAnswer, reviewGeneratedJobCode, scorePromptChoiceMatch, stripGranularReasoningTrace, toGranularHttpBase, validateHarnessTemplateManifest, validationRuleFailureMessage };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map