@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.34

package/plugins/session-metrics/turns.mjs

@@ -0,0 +1,134 @@
+// Per-turn cost attribution and the session budget gate. The footer reports the
+// whole session's spend and /usage reports tokens per turn; these functions
+// answer what neither does with that ledger: which turn spent the money, so the
+// footer can show the last completed turn and /usage can price each one.
+
+/**
+ * Turn windows from the session's own events. `turn/start` opens a window and
+ * `turn/end` closes it; an unterminated turn stays open to `Infinity` so the
+ * turn in flight still attributes its settled calls. Windows come back in
+ * ascending start order, which the attribution lookup below depends on.
+ */
+export function turnWindows(events = []) {
+  const open = new Map();
+  const windows = [];
+  for (const event of events) {
+    const turn = event.data?.turn;
+    // A boundary without a time cannot place a window or a call inside one. It
+    // is skipped rather than stored: a NaN edge would make the ascending-search
+    // contract false and silently orphan every call of that turn.
+    if (!Number.isFinite(turn) || !Number.isFinite(event.time)) continue;
+    if (event.type === 'turn/start') {
+      const existing = open.get(turn);
+      // A resumed turn can re-emit its start; keep the earliest boundary.
+      open.set(turn, existing === undefined ? event.time : Math.min(existing, event.time));
+    } else if (event.type === 'turn/end') {
+      const start = open.get(turn);
+      if (start === undefined) continue;
+      open.delete(turn);
+      windows.push({ turn, start, end: event.time });
+    }
+  }
+  for (const [turn, start] of open) windows.push({ turn, start, end: Infinity });
+  return windows.sort((left, right) => left.start - right.start || left.turn - right.turn);
+}
+
+/**
+ * The clauses a call is priced against: each turn's window, with an open turn
+ * (no `turn/end`) bounded by the next turn's start. An interrupted turn must not
+ * swallow every later turn, while the turn genuinely in flight keeps running to
+ * `Infinity`. Satisfies {@link attributeCostByTurn}'s ascending-start contract.
+ */
+export function turnBounds(events = []) {
+  return turnWindows(events).map((window, index, windows) => ({
+    turn: window.turn,
+    start: window.start,
+    // Math.max keeps the window non-inverted even for a log whose timestamps
+    // are out of order; an inverted bound would break the ascending search.
+    end: window.end === Infinity && index + 1 < windows.length ? Math.max(window.start, windows[index + 1].start) : window.end,
+  }));
+}
+
+/**
+ * The window containing `time`, by binary search over the ascending bounds. The
+ * index is the FIRST window starting after `time`, so the one before it is the
+ * only candidate that can contain it; `-1` means no turn was running.
+ * @param bounds - ascending {@link turnBounds} rows.
+ * @param time - the call's start time (`time` prices the call, so it is also when the turn ran).
+ * @returns the bounds index, or -1 when `time` falls in no window.
+ */
+export function turnAt(bounds, time) {
+  let low = 0, high = bounds.length;
+  while (low < high) {
+    const mid = (low + high) >> 1;
+    if (bounds[mid].start <= time) low = mid + 1;
+    else high = mid;
+  }
+  const candidate = bounds[low - 1];
+  return candidate !== undefined && time <= candidate.end ? low - 1 : -1;
+}
+
+/**
+ * Cost and call count per turn. Roughly O(calls × log turns), so the footer can
+ * ask for the last turn once a second. A call is attributed by its start time,
+ * and a call outside every window (before the first `turn/start`, in a gap
+ * between two turns, or a backfilled row without one) is reported under
+ * `unattributed` rather than dropped.
+ * @param rows - ledger rows (`{ kind, time, cost, purpose }`).
+ * @param events - the session's events, for the turn windows.
+ * @returns One bucket per turn, plus `lastTurn` (the newest turn that is no
+ *   longer running, undefined while none has stopped), the `unattributed` total
+ *   and whether any of it was unpriceable. A turn that never emitted `turn/end`
+ *   still counts as stopped once the next turn opens its window.
+ */
+export function attributeCostByTurn(rows = [], events = []) {
+  const bounds = turnBounds(events);
+  const turns = bounds.map(bound => ({ turn: bound.turn, cost: 0, calls: 0, unknown: false }));
+  let unattributed = 0;
+  let unattributedUnknown = false;
+  for (const row of rows ?? []) {
+    if (row?.kind !== 'end') continue;
+    const at = turnAt(bounds, row.time);
+    if (at === -1) {
+      // Outside every window the spend still exists: an unpriceable row must be
+      // visible as such rather than counted as nothing.
+      if (Number.isFinite(row.cost)) unattributed += row.cost;
+      else unattributedUnknown = true;
+      continue;
+    }
+    turns[at].calls += 1;
+    if (Number.isFinite(row.cost)) turns[at].cost += row.cost;
+    else turns[at].unknown = true;
+  }
+  let lastTurn;
+  for (let index = bounds.length - 1; index >= 0; index -= 1) {
+    if (bounds[index].end !== Infinity) { lastTurn = turns[index]; break; }
+  }
+  return { turns, lastTurn, unattributed, unattributedUnknown };
+}
+
+/**
+ * The budget gate's verdict. A missing or non-positive limit means no budget is
+ * set, so the gate never fires and the footer shows no budget slot. `warn` is
+ * the alerting share; `over` means the next prompt would spend past the limit.
+ */
+export function evaluateBudget(spent, limit, options = {}) {
+  const warnPercent = Number.isFinite(options.warnPercent) ? options.warnPercent : 80
+  if (!Number.isFinite(limit) || limit <= 0) return { state: 'unset', limit: null, spent, ratio: null, percent: null, warnPercent }
+  const safeSpent = Number.isFinite(spent) ? spent : 0
+  const ratio = safeSpent / limit
+  return {
+    state: ratio >= 1 ? 'over' : ratio * 100 >= warnPercent ? 'warn' : 'ok',
+    limit, spent: safeSpent, ratio,
+    percent: Math.round(ratio * 100),
+    warnPercent,
+  }
+}
+
+/** Parse the `DSCODE_SESSION_BUDGET_USD`-style value; anything else is no budget. */
+export function parseBudget(value) {
+  if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? value : null
+  if (typeof value !== 'string') return null
+  const parsed = Number.parseFloat(value.trim())
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+}

package/plugins/session-metrics/view.mjs

@@ -0,0 +1,272 @@
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { readMetrics } from './store.mjs';
+import { t } from '../i18n/messages.mjs';
+import { estimateCost, peakEmoji } from './pricing.mjs';
+import { balanceNow, trustedNow } from './balance.mjs';
+import { grokSubscriptionNow } from '../grok/billing.mjs';
+import { goUsageNow } from '../opencode-go/usage.mjs';
+import { canonicalProvider } from '../providers/catalog.mjs';
+import { sessionAverageTps } from './rate.mjs';
+import { attributeCostByTurn, evaluateBudget, parseBudget } from './turns.mjs';
+let source;
+export function setMetricSource(next) { source = next; return () => { if (source === next) source = undefined; }; }
+export function summarize(rows, events = [], corrupt = false) {
+  const requests = new Map();
+  let first = Infinity;
+  for (const row of rows) {
+    if (row.kind === 'start') first = Math.min(first, row.time);
+    requests.set(row.id, { ...requests.get(row.id), ...row });
+  }
+  // Backfill old main/compaction calls from the durable log, only before the new ledger.
+  let route = {};
+  const history = [];
+  for (const event of events) {
+    if (event.type === 'request/header') route = event.data.header.config;
+    // Ledger rows cover everything from the first row's time on, so only older events are
+    // backfilled. `continue`, not `break`: the loop must not depend on event ordering.
+    if (event.time >= first) continue;
+    if (event.type === 'assistant/message' || event.type === 'compaction/summary' && event.data.llmStreamCall) {
+      const r = event.type === 'compaction/summary' ? event.data : route;
+      history.push({ usage: event.data.usage, cost: estimateCost(r.provider, r.model, event.data.usage, event.time), kind: 'end' });
+    } else if (event.type === 'assistant/attempt') history.push({ kind: 'end', cost: null });
+  }
+  let cost = 0, unknown = corrupt || history.length > 0, input = 0, hit = 0, cacheUnknown = false, calls = 0, pending = 0;
+  // Historical overhead (review/title) was not recorded by this collector: mark partial.
+  for (const row of [...history, ...requests.values()]) {
+    calls++;
+    if (row.kind !== 'end') { pending++; continue; }
+    if (!Number.isFinite(row.cost)) unknown = true;
+    else cost += row.cost;
+    const u = row.usage;
+    // An auxiliary call (memory, review, an aborted stream) can end without a usage chunk: that
+    // call is unaccounted, not a cache miss, so it must not blank the whole session's ratio.
+    if (!u) continue;
+    if (!Number.isFinite(u.inputTokens) || !Number.isFinite(u.outputTokens)) { cacheUnknown = true; continue; }
+    const total = u.inputTokens + (u.cacheReadTokens ?? 0) + (u.cacheWriteTokens ?? 0);
+    // OpenRouter reports cache reads only when there are some: a missing count is zero, not unknown.
+    input += total; hit += u.cacheReadTokens ?? 0;
+  }
+  // Per-turn attribution needs the ledger's own rows (the backfilled history has
+  // no turn boundary), so it reads them directly instead of the merged map.
+  const attribution = attributeCostByTurn(rows, events);
+  return {
+    cost, unknown, calls, pending,
+    cache: input > 0 && !cacheUnknown ? Math.min(100, hit / input * 100) : null,
+    turns: attribution.turns,
+    lastTurn: attribution.lastTurn,
+    unattributed: attribution.unattributed,
+    unattributedUnknown: attribution.unattributedUnknown,
+  };
+}
+
+/**
+ * Per-turn cost for one live session, straight from its ledger, keyed by the
+ * durable turn number. The /usage panel prices its turns with this: the token
+ * meter says what each turn billed, this says what it cost.
+ * @param id - the session id.
+ * @param events - the session's durable events, for the turn windows.
+ * @returns `{ turn, cost, calls, unknown }` per completed or running turn.
+ */
+export function turnCostsFor(id, events = []) {
+  const entries = id ? readMetrics(resolveDshHome(), id).rows : [];
+  return attributeCostByTurn(entries, events).turns;
+}
+/**
+ * Terminal columns of a string: East Asian wide characters (such as the cache label's
+ * CJK glyphs) take two, and zero-width marks take none. The variation selectors matter
+ * here: `❄️` is U+2744 plus U+FE0F, and counting that selector as a column made the
+ * footer's provider budget swing with the DeepSeek pricing window.
+ */
+const WIDE = /[\u1100-\u115f\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6\u2600-\u27bf\u{1f300}-\u{1faff}]/u;
+// eslint-disable-next-line no-misleading-character-class -- these are zero width by design
+const ZERO_WIDTH = /[\u0300-\u036f\u200d\ufe00-\ufe0f]/;
+export function displayWidth(text) {
+  let width = 0;
+  for (const char of text) width += ZERO_WIDTH.test(char) ? 0 : WIDE.test(char) ? 2 : 1;
+  return width;
+}
+/**
+ * The money slot for the Grok subscription rail: a plan has credits and a reset time, not a
+ * bill. The percentage is optional (the server omits it for a period without usage), and an
+ * unread window shows the tier alone instead of a wrong number.
+ */
+export function grokFooterFact(subscription, locale = 'en', now = Date.now()) {
+  const parts = [subscription?.tier ?? 'Grok'];
+  const used = subscription?.usedPercent;
+  if (Number.isFinite(used)) parts.push((Number.isInteger(used) ? String(used) : used.toFixed(1)) + '% ' + t(locale, 'footer.grokUsed'));
+  const reset = resetStamp(subscription?.periodEnd, now);
+  if (reset !== undefined) parts.push(t(locale, 'footer.grokResets') + ' ' + reset);
+  return parts.join(' · ');
+}
+
+const GO_WINDOWS = Object.freeze([['rolling', '5h'], ['weekly', '7d'], ['monthly', '30d']]);
+
+/**
+ * The money slot for the OpenCode Go subscription: the share used of each cap Go enforces —
+ * rolling five hours, week, month — and, when one is exhausted, when it lifts. An unread
+ * snapshot shows the plan name alone instead of a wrong number.
+ */
+export function goFooterFact(usage, locale = 'en', now = Date.now()) {
+  const parts = ['Go'];
+  for (const [key, label] of GO_WINDOWS) {
+    const percent = usage?.[key]?.percent;
+    if (Number.isFinite(percent)) parts.push(label + ' ' + (Number.isInteger(percent) ? String(percent) : percent.toFixed(1)) + '%' + (usage[key].limited ? '!' : ''));
+  }
+  // Blocked until the last exhausted window lifts: that is when requests work again.
+  const lifts = GO_WINDOWS.map(([key]) => usage?.[key]).filter(window => window?.limited).map(window => window.resetsAt)
+    .filter(iso => Number.isFinite(Date.parse(iso ?? ''))).sort((a, b) => Date.parse(b) - Date.parse(a))[0];
+  const stamp = resetStamp(lifts, now);
+  if (stamp !== undefined) parts.push(t(locale, 'footer.goLimited') + ' ' + stamp);
+  return parts.join(' · ');
+}
+
+/** Local `MM-DD HH:MM` for a reset time, or undefined when the window is unknown or past. */
+function resetStamp(iso, now) {
+  const at = Date.parse(typeof iso === 'string' ? iso : '');
+  if (!Number.isFinite(at) || at <= now) return undefined;
+  const pad = value => String(value).padStart(2, '0');
+  const date = new Date(at);
+  return pad(date.getMonth() + 1) + '-' + pad(date.getDate()) + ' ' + pad(date.getHours()) + ':' + pad(date.getMinutes());
+}
+
+/**
+ * Fixed figure columns for the live footer. The status line re-reads these
+ * figures every second, so a growing digit count must never move the segments
+ * after it: each figure is right-aligned inside its own columns, and only the
+ * terminal width decides which segments the drop ladder keeps.
+ */
+const FIGURE = {
+  /** Request and session-average rates share the same fixed figure width. */
+  rate: 6,
+  /** `100%` context occupancy. */
+  percent: 4,
+  /** `100.0%` cache share. */
+  share: 6,
+};
+
+/**
+ * Columns {@link formatFooter} needs on top of the budget it is handed. The
+ * fixed figures above only stop moving once their columns are really reserved,
+ * so a caller that budgets the footer's width adds these columns first —
+ * otherwise the padding evicts a figure the width would have seated. Six
+ * measures the padding a live reading adds across the rate, context and cache
+ * figures at the widths the drop ladder actually decides on.
+ */
+export const FOOTER_FIGURE_RESERVE = 6;
+
+/** Right-align one figure inside its columns; a wider reading keeps its own width. */
+function figure(text, width) {
+  const padding = width - displayWidth(text);
+  return padding > 0 ? ' '.repeat(padding) + text : text;
+}
+
+function footerFigures(metrics, context, rates, locale = 'en', provider = 'deepseek-official') {
+  provider = canonicalProvider(provider);
+  const label = key => t(locale, key);
+  const ctx = figure(Number.isFinite(context) ? `${Math.round(context)}%` : '--', FIGURE.percent);
+  const cache = figure(metrics.cache === null ? '--' : `${metrics.cache.toFixed(1)}%`, FIGURE.share);
+  // The balance belongs to the provider serving the route; only DeepSeek's official one bills by a peak window.
+  const balance = balanceNow(provider);
+  const spend = metrics.unknown && metrics.cost === 0 ? '--' : `$${metrics.cost.toFixed(2)}${metrics.unknown ? '+' : ''}${metrics.pending ? '…' : ''}`;
+  // The money is the one live figure whose digits are not reserved: they cross a
+  // column a handful of times per session, and reserving them would evict a
+  // per-second figure at the widths the footer actually runs at. A balance the
+  // provider cannot report is left out instead of parked as `$--`.
+  const dollars = provider === 'grok' ? grokFooterFact(grokSubscriptionNow(), locale)
+    : provider === 'opencode-go' ? goFooterFact(goUsageNow(), locale)
+    : spend + (balance === null ? '' : ' / $' + balance.toFixed(2)) + (provider === 'deepseek-official' ? ' ' + peakEmoji(trustedNow()) : '');
+  // The budget slot rides the money figure: it answers "how much of the session's
+  // limit is spent", which is a fact about the cost, not a second cost. A session
+  // with no limit renders exactly as before, so the footer only grows by choice.
+  const budget = metrics.budget;
+  const budgeted = budget === undefined || budget.limit === null ? ''
+    : `/${budget.limit.toFixed(2)}${budget.state === 'over' ? '⚠!' : budget.state === 'warn' ? '⚠' : ''}`;
+  const money = dollars + budgeted;
+  // The last completed turn is the one figure the whole-session total cannot
+  // give: `$1.23 / $9.86 · #12 $0.04` reads "the session so far, of which the
+  // last turn cost this". `+` marks a turn whose settled calls were not all
+  // priceable, the same mark the total uses.
+  const turn = metrics.lastTurn === undefined || !Number.isFinite(metrics.lastTurn.cost) ? ''
+    : `#${metrics.lastTurn.turn} $${metrics.lastTurn.cost.toFixed(2)}${metrics.lastTurn.unknown ? '+' : ''}`;
+  return {
+    current: rates ? `${rates.active ? '◌' : ' '} ${figure(Number.isFinite(rates.current) ? rates.current.toFixed(1) : '--', FIGURE.rate)} tps` : '',
+    average: rates ? `${figure(Number.isFinite(rates.average) ? rates.average.toFixed(1) : '--', FIGURE.rate)} tps ${label('footer.average')}` : '',
+    context: `${ctx} ${label('footer.context')}`,
+    money,
+    cache: `${cache} ${label('footer.cache')}`,
+    turn,
+  };
+}
+
+/** Flat footer for text consumers; the TUI uses the same figures as separate groups. */
+export function formatFooter(metrics, context, columns = 80, rates, locale = 'en', provider = 'deepseek-official') {
+  const figures = footerFigures(metrics, context, rates, locale, provider);
+  const { current, average, context: ctx, money, cache, turn } = figures;
+  const base = rates ? [current, average, ctx, money, cache] : [ctx, money, cache];
+  // The slot is reserved even when no turn has cost anything yet: the drop
+  // ladder's indices are fixed against this array, and an unfilled slot renders
+  // as '' (skipped by `render`) exactly like the absent figure would.
+  base.splice(rates ? 3 : 1, 0, turn);
+  // Narrow terminals shed the quietest figures first: the last turn, then
+  // average, current and context, and only then the cache. The running cost is
+  // the last thing standing, and its slot is index 4 (or 2 without rates) now
+  // that the turn slot holds index 3 (or 1) open.
+  const drops = rates ? [3, 1, 0, 2, 5, 4] : [1, 0, 3, 2];
+  const render = omit => base.filter((part, index) => part !== '' && !omit.has(index)).join(' · ');
+  for (let dropped = 0; dropped <= drops.length; dropped++) {
+    const value = render(new Set(drops.slice(0, dropped)));
+    if (displayWidth(value) <= columns) return value;
+  }
+  const floor = render(new Set(drops));
+  let clipped = '';
+  for (const char of floor) { if (displayWidth(clipped + char) > columns) break; clipped += char; }
+  return clipped;
+}
+/**
+ * The session's recorded spend and whether any of it is unpriceable, for a host
+ * that must decide something (the budget gate) rather than only render it. Same
+ * ledger and same rules as {@link footerFor}, so the figure the gate compares
+ * and the figure the footer shows can never disagree.
+ */
+export function sessionSpend(id) {
+  try {
+    const ledger = id ? readMetrics(resolveDshHome(), id) : { rows: [], corrupt: false };
+    const data = id ? source?.(id) : undefined;
+    const summary = summarize(ledger.rows, data?.events ?? [], ledger.corrupt);
+    return { cost: summary.cost, unknown: summary.unknown, pending: summary.pending };
+  } catch { return { cost: 0, unknown: true, pending: 0 }; }
+}
+
+/** Per-events memo: the status line renders up to once a second, and summarize/average are O(events). */
+const footerCache = new WeakMap();
+export function footerFor(id, stats, columns, provider = 'deepseek-official', locale = 'en', format = formatFooter) {
+  const limit = parseBudget(process.env.DSCODE_SESSION_BUDGET_USD);
+  try {
+    // Live estimation can be unavailable while a Host/agent is reconnecting.
+    // Keep the durable prompt reading visible instead of losing all telemetry.
+    let data;
+    try { data = id ? source?.(id) : undefined; } catch { /* use the TUI's durable projection */ }
+    const ledger = id ? readMetrics(resolveDshHome(), id) : { rows: [], corrupt: false };
+    const events = data?.events ?? [];
+    // Identity alone is not enough: a session event list may be appended to in place.
+    const hit = events.length > 0 ? footerCache.get(events) : undefined;
+    const tail = events.at(-1)?.time;
+    const fresh = hit !== undefined && hit.key === ledger.rows && hit.length === events.length && hit.tail === tail;
+    const summary = fresh ? hit.summary : summarize(ledger.rows, events, ledger.corrupt);
+    const used = Number.isFinite(data?.used) && data.used >= 0 ? data.used
+      : Number.isFinite(stats.lastPromptTokens) && stats.lastPromptTokens > 0 ? stats.lastPromptTokens : undefined;
+    const capacity = Number.isFinite(data?.capacity) && data.capacity > 0 ? data.capacity : stats.contextWindow;
+    const average = fresh ? hit.average : sessionAverageTps(events);
+    if (events.length > 0 && !fresh) footerCache.set(events, { key: ledger.rows, length: events.length, tail, summary, average });
+    // The budget comes from the environment for this process only: it is a
+    // per-machine spending guard, not a session property worth persisting.
+    const budget = limit === null ? undefined : evaluateBudget(summary.cost, limit);
+    return format({ ...summary, ...(budget === undefined ? {} : { budget }) }, Number.isFinite(used) && capacity > 0 ? used / capacity * 100 : undefined, columns, { current: data?.currentTps, average, active: data?.requestActive }, locale, provider);
+  } catch { return format({ cost: 0, unknown: true, cache: null }, undefined, columns, { current: null, average: null }, locale, provider); }
+}
+
+/** Structured figures preserve money/cache as one right-aligned group in the TUI. */
+export function footerFiguresFor(id, stats, provider = 'deepseek-official', locale = 'en') {
+  return footerFor(id, stats, 0, provider, locale,
+    (metrics, context, _columns, rates, language, route) => footerFigures(metrics, context, rates, language, route));
+}

package/plugins/time-marks/desktop-host.mjs

@@ -0,0 +1,2 @@
+export const inject = ['agentPresets'];
+export { Config, applyDesktop as apply } from './index.mjs';

package/plugins/time-marks/index.mjs

@@ -0,0 +1,116 @@
+/**
+ * Clock marks in the model's own context: every message a step admits, and
+ * every turn that closed before it, carries one reading of the host clock. A
+ * mark is its own plugin-sourced message rather than an edit of the prompt, so
+ * message bodies, session cards and title selection read exactly what they
+ * read before. Like the time-context reading it is durable: it spends model
+ * context from then on, replays on resume, and the terminal hides it by
+ * producer.
+ *
+ * @module dscode-time-marks
+ */
+import z from '@deepseek-ai/schemastery';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { arrivalMark, resolveTimeZone, turnEndMark } from './marks.mjs';
+import { producerKind } from '../message-source/kind.mjs';
+export const name = 'dscode-time-marks';
+export const Config = z.object({
+  /** Fallback display zone; empty uses the host zone. */
+  timeZone: z.string().default(''),
+});
+/** Marks carried by one request at most, so a delivery burst cannot flood a step. */
+const MARK_LIMIT = 8;
+
+/** Recover bounded turn endings that no durable clock message has reported. */
+export function pendingTimeMarks(events) {
+  const pending = [];
+  let covered = -1, crossedEnd = false;
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index];
+    if (event.type === 'user/message' && producerKind(event.data.source) === name) {
+      // New clocks carry explicit IDs. Older clocks are trusted plugin output;
+      // their rendered turn lines are the available durable evidence.
+      const turns = event.data.source.closedTurns ?? (event.data.content ?? []).flatMap(block =>
+        block.type === 'text' ? [...block.text.matchAll(/^Time mark: .+ — turn (\d+) ended(?:,|\.)/gm)].map(match => +match[1]) : []);
+      if (Array.isArray(turns)) for (const turn of turns) if (Number.isSafeInteger(turn)) covered = Math.max(covered, turn);
+    }
+    if (event.type === 'turn/end') {
+      if (event.data.turn <= covered) crossedEnd = true;
+      else if (pending.length < MARK_LIMIT) pending.push({ turn: event.data.turn, endedAt: event.time });
+    }
+    if (event.type === 'turn/start') {
+      const ended = pending.find(item => item.turn === event.data.turn);
+      if (ended) ended.startedAt = event.time;
+    }
+    if ((crossedEnd || pending.length === MARK_LIMIT) && pending.every(item => item.startedAt !== undefined)) break;
+  }
+  return pending.reverse();
+}
+/**
+ * Per-agent mark state: closed turns still waiting for a step to carry them,
+ * and the opening time of the turn each one closed.
+ */
+export function apply(ctx, config = {}) {
+  return install(ctx, config, () => true);
+}
+
+export function applyDesktop(ctx, config = {}) {
+  return install(ctx, config, agent => ctx.agentPresets.composedPreset(agent.ctx) === 'dscode');
+}
+
+function install(ctx, config, accepts) {
+  const marks = new WeakMap();
+  const stateFor = agent => {
+    let state = marks.get(agent);
+    if (state === undefined) marks.set(agent, state = { turns: pendingTimeMarks(agent.session?.snapshotEvents?.() ?? []), starts: new Map() });
+    return state;
+  };
+  const timeZone = resolveTimeZone(config.timeZone);
+  let closed = false;
+  ctx.effect(() => () => { closed = true; });
+  ctx.on('agent/pre-step', async (payload, next) => {
+    if (closed || !accepts(payload.agent)) return next();
+    const state = stateFor(payload.agent);
+    // Keep inbox provenance before downstream handlers add runtime context or
+    // filter the batch. Some native additions (e.g. skill-catalog) have no form.
+    const arrivals = new Set(payload.messages.map(message => message.id));
+    // The first step of a turn is the only moment its opening is observable.
+    if (payload.step === 1) state.starts.set(payload.turn, Date.now());
+    const decision = await next();
+    if (closed || decision.kind !== 'enter') return decision;
+    const at = Date.now();
+    const lines = [], closedTurns = [];
+    for (const message of decision.messages) {
+      if (!arrivals.has(message.id)) continue;
+      // Marks are injected context, never an inbox arrival; skipping our own
+      // producer keeps a future delivery path from marking itself.
+      if (producerKind(message.source) === name) continue;
+      const line = arrivalMark(message, at, timeZone);
+      if (line !== null && lines.length < MARK_LIMIT) lines.push(line);
+    }
+    // An arrival burst that fills the limit leaves the remaining turn marks
+    // queued: the next step carries them instead of losing them here.
+    while (lines.length < MARK_LIMIT && state.turns.length > 0) {
+      const ended = state.turns.shift();
+      lines.push(turnEndMark(ended.turn, ended.endedAt, ended.startedAt, timeZone));
+      closedTurns.push(ended.turn);
+    }
+    if (lines.length === 0) return decision;
+    return {
+      ...decision,
+      // Ahead of the admitted batch: clocks must not take the prompt's place.
+      // The Host may independently append its runtime context after the input.
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: lines.join('\n') }],
+        source: { kind: name, form: 'snapshot', closedTurns },
+      }), ...decision.messages],
+    };
+  }, { prepend: true });
+  ctx.on('agent/turn-stopping', payload => {
+    if (closed || !accepts(payload.agent)) return;
+    const state = stateFor(payload.agent);
+    state.turns.push({ turn: payload.turn, endedAt: Date.now(), startedAt: state.starts.get(payload.turn) });
+    state.starts.delete(payload.turn);
+    if (state.turns.length > MARK_LIMIT) state.turns.length = MARK_LIMIT;
+  });
+}