@itookit/dsht 0.3.2 → 0.3.4

package/dist/cost/pricing.js

@@ -1,8 +1,9 @@
 /** Versioned CNY price tables and the price decision taken for one request sample. */
+import { createHash } from 'node:crypto';
 import { object } from "../transport/wire.js";
-import { MISSING_USAGE } from "./types.js";
+import { MISSING_TIME, MISSING_USAGE, UNSUPPORTED_USAGE } from "./types.js";
 const clocks = new Map();
-/** Published rates verified on 2026-09-10; preceding dates require historical configuration.
+/** Published rates verified on 2026-09-12; preceding dates require historical configuration.
  * Flash and Pro are priced independently, and a separate cache write uses the cache-miss input rate.
  */
 const OFFICIAL_PRICING = 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing/';
@@ -12,17 +13,63 @@ const FLASH_RATES = { peak: { input: 2, cacheRead: 0.04, cacheWrite: 2, output:
 const PRO_RATES = { peak: { input: 9, cacheRead: 0.3, cacheWrite: 9, output: 27 },
     offPeak: { input: 4.5, cacheRead: 0.15, cacheWrite: 4.5, output: 13.5 } };
 export const DEFAULT_PRICES = [
+    // The published table states that superseded Flash names stay callable and are served by
+    // V4.1-Flash at Flash rates, so every name the host can report is listed instead of guessed at.
     { id: 'deepseek-2026-09-10-flash', provider: 'deepseek-official', model: 'deepseek-flash',
+        aliases: ['deepseek-v4-flash', 'deepseek-v4-flash-vision-exp', 'deepseek-v4-flash*', 'deepseek-v4.1-flash*', 'deepseek-v4.1-flash'],
         from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
         ...PEAK_SCHEDULE, ...FLASH_RATES },
+    // The published table keeps V4 Pro available after 2026-09-14 at these rates, so the interval
+    // stays open until a later page names an end.
     { id: 'deepseek-2026-09-10-pro', provider: 'deepseek-official', model: 'deepseek-v4-pro',
-        from: '2026-09-10T00:00:00+08:00', until: '2026-09-14T12:00:00+08:00', currency: 'CNY',
-        source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai', ...PEAK_SCHEDULE, ...PRO_RATES },
-    // The provider bills `deepseek-v4-pro` requests at Flash rates once V4 Pro is retired.
-    { id: 'deepseek-2026-09-14-pro-served-by-flash', provider: 'deepseek-official', model: 'deepseek-v4-pro',
-        from: '2026-09-14T12:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
-        ...PEAK_SCHEDULE, ...FLASH_RATES },
+        // No `deepseek-pro*`: a prefix that broad would also claim `deepseek-proxy-*` or `deepseek-prompt-*`.
+        aliases: ['deepseek-v4-pro', 'deepseek-v4-pro*', 'deepseek-v4.1-pro*'],
+        from: '2026-09-10T00:00:00+08:00', currency: 'CNY', source: OFFICIAL_PRICING, timezone: 'Asia/Shanghai',
+        ...PEAK_SCHEDULE, ...PRO_RATES },
 ];
+/** Revision of the pricing decision rules, recorded with the totals they decided.
+ *
+ * Bump it whenever the rules change what an amount would be — the matching of a model name, the
+ * token buckets an amount covers, or the timestamp it is priced at — so a stored total can be traced
+ * to the rules that produced it. Version 1 matched a model by the substring `pro` and priced a
+ * request with no settlement time at the cheapest off-peak rate.
+ */
+export const PRICING_ENGINE_VERSION = 2;
+/** Revision of the shipped table, recorded beside a seeded file so a correction can replace it. */
+export const PRICES_REVISION = '2026-09-12';
+/** Rates the first published revision charged, rebuilt with the same arithmetic so the values compare equal.
+ * It only recognizes that seed; it never prices a request.
+ */
+const UNCORRECTED_SEED_RATES = Object.fromEntries(['deepseek-v4-flash', 'deepseek-v4-pro', 'deepseek-v4-flash-vision-exp'].map(model => {
+    const scale = model === 'deepseek-v4-pro' ? 3 : 1;
+    return [`deepseek-2026-09-10-${model}`, {
+            peak: { input: 3 * scale, cacheRead: 0.1 * scale, cacheWrite: 3 * scale, output: 9 * scale },
+            offPeak: { input: 1.5 * scale, cacheRead: 0.05 * scale, cacheWrite: 1.5 * scale, output: 4.5 * scale },
+        }];
+}));
+/** Whether a table is the seed an earlier revision wrote, which a corrected ship must replace.
+ *
+ * `prices.json` overrides the shipped table, so an install seeded before the Flash rates were
+ * corrected keeps charging 1.5x for input and 2.5x for cache reads for as long as that file lives.
+ * Only an exact match to the superseded revision qualifies, so a rate the user chose is never rewritten.
+ * @param prices - Table loaded from the configuration file.
+ * @returns True when every entry carries the superseded revision's rates.
+ */
+export function isUncorrectedSeed(prices) {
+    const superseded = Object.keys(UNCORRECTED_SEED_RATES);
+    return prices.length === superseded.length && prices.every(price => {
+        const legacy = UNCORRECTED_SEED_RATES[price.id];
+        return legacy !== undefined && sameRates(price.peak, legacy.peak) && sameRates(price.offPeak, legacy.offPeak);
+    });
+}
+/** Compare two rate sets, allowing the representation error a JSON round trip can introduce.
+ * @param a - One rate set.
+ * @param b - The other rate set.
+ * @returns True when every rate agrees.
+ */
+function sameRates(a, b) {
+    return ['input', 'cacheRead', 'cacheWrite', 'output'].every(bucket => Math.abs(a[bucket] - b[bucket]) < 1e-9);
+}
 /** Validate user-maintained price versions, rejecting ambiguous overlapping intervals.
  * @param value - Parsed prices.json array.
  * @returns Price versions with validated rates and schedules.
@@ -39,6 +86,8 @@ export function pricesFrom(value) {
         if (ids.has(String(p.id)))
             throw new Error('Duplicate price id');
         ids.add(String(p.id));
+        if (p.aliases !== undefined && (!Array.isArray(p.aliases) || p.aliases.some(alias => typeof alias !== 'string' || alias === '')))
+            throw new Error('Invalid price aliases');
         const from = Date.parse(String(p.from));
         const until = p.until === undefined ? Infinity : Date.parse(String(p.until));
         if (!Number.isFinite(from) || !(until > from) || p.currency !== 'CNY')
@@ -63,31 +112,72 @@ export function pricesFrom(value) {
         }
     return prices;
 }
-/** Return the calendar date used by both daily and three-calendar-day summaries.
+/** Return the Beijing calendar date a request is attributed to.
  * @param time - Epoch milliseconds.
  * @returns Beijing calendar date, YYYY-MM-DD.
  */
 export function costDay(time) { return new Date(time + 8 * 3600_000).toISOString().slice(0, 10); }
-/** Price family used when a recorded model name has no exact entry. */
-function priceFamily(model) { return model.toLowerCase().includes('pro') ? 'deepseek-v4-pro' : 'deepseek-flash'; }
-/** Candidate versions for one request: its exact model first, then the official model family. */
-function candidates(prices, provider, model) {
-    const exact = prices.filter(p => p.provider === provider && p.model === model);
+/** Canonical form of a model name before matching.
+ *
+ * The host reports names that differ from the published table by width, case, surrounding space, or
+ * the CJK full stop a display path can substitute for a period. Normalizing here keeps the table
+ * readable and keeps a name variant from silently missing its entry. NFKC does not fold the CJK
+ * stops, so they are mapped explicitly.
+ * @param model - Model name exactly as the recorded request reported it.
+ * @returns The name in the form the table is matched against.
+ */
+export function canonicalModel(model) {
+    return model.normalize('NFKC').replace(/[\u3002\uff0e\uff61]/g, '.').trim().toLowerCase();
+}
+/** Whether an alias matches a canonical model name, treating a trailing `*` as a prefix.
+ * @param alias - Alias declared by a price version.
+ * @param model - Canonical model name.
+ * @returns True when the alias covers the name.
+ */
+function aliasMatches(alias, model) {
+    const canonical = canonicalModel(alias);
+    return canonical.endsWith('*') ? model.startsWith(canonical.slice(0, -1)) : model === canonical;
+}
+/** Candidate versions for one request, in the order the table is searched: the exact model, then
+ * the aliases a version declares. A name the table does not cover stays unpriced rather than
+ * falling back to a family guess, because guessing a rate is indistinguishable from a wrong one.
+ * @param prices - Validated versions.
+ * @param provider - Provider identity from the recorded request.
+ * @param model - Recorded model name.
+ * @returns Matching versions, each with the rule that matched it.
+ */
+export function candidates(prices, provider, model) {
+    const canonical = canonicalModel(model);
+    const exact = prices.filter(p => p.provider === provider && canonicalModel(p.model) === canonical);
     if (exact.length)
-        return exact;
-    return provider === 'deepseek-official' ? prices.filter(p => p.model === priceFamily(model)) : [];
+        return exact.map(price => ({ price, matchedBy: 'exact' }));
+    return prices.filter(p => p.provider === provider && (p.aliases ?? []).some(alias => aliasMatches(alias, canonical)))
+        .map(price => ({ price, matchedBy: 'alias' }));
+}
+/** Stable identity of a loaded price table.
+ *
+ * The identity a price version carries can be edited in place while keeping its `id` — which is how
+ * a corrected table once kept charging superseded rates under one id — so a stored total records a
+ * digest of the whole table it was decided from, not only the version names.
+ * @param prices - Price versions loaded for this process.
+ * @returns Short digest of the table.
+ */
+export function pricesDigest(prices) {
+    return createHash('sha256').update(JSON.stringify(prices)).digest('hex').slice(0, 12);
 }
 /** Select a price by event time, applying half-open local peak windows.
  * @param prices - Validated versions.
  * @param provider - Provider identity from the recorded request.
- * @param model - Recorded model name; official DeepSeek aliases fall back to Pro when containing pro, otherwise Flash.
- * @param time - Recorded settlement timestamp used as a billing-time estimate.
- * @returns Matching price version and per-million-token rates, if known.
+ * @param model - Recorded model name.
+ * @param time - Recorded settlement timestamp used as the billing instant.
+ * @returns Matching price version, the rule that matched it, and its per-million-token rates.
  */
 export function priceAt(prices, provider, model, time) {
-    const price = candidates(prices, provider, model).find(p => Date.parse(p.from) <= time && (p.until === undefined || time < Date.parse(p.until)));
-    if (!price)
+    const candidate = candidates(prices, provider, model)
+        .find(({ price }) => Date.parse(price.from) <= time && (price.until === undefined || time < Date.parse(price.until)));
+    if (candidate === undefined)
         return;
+    const { price, matchedBy } = candidate;
     let clock = clocks.get(price.timezone);
     if (!clock) {
         clock = new Intl.DateTimeFormat('en-US', { timeZone: price.timezone, weekday: 'short', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
@@ -97,45 +187,37 @@ export function priceAt(prices, provider, model, time) {
     const part = (name) => parts.find(p => p.type === name).value;
     const day = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(part('weekday'));
     const minute = Number(part('hour')) * 60 + Number(part('minute'));
-    return { price, rates: price.weekdays.includes(day) && price.windows.some(([a, b]) => minute >= a && minute < b) ? price.peak : price.offPeak };
-}
-/** Select a rate without a settlement time, so an unattributable request still enters the total.
- * The cheapest candidate off-peak rate is a floor: it never overstates, and the charge stays
- * marked as estimated.
- * @param prices - Validated versions.
- * @param provider - Provider identity from the recorded request.
- * @param model - Recorded model name.
- * @returns The candidate version with the lowest off-peak input rate and its rates, if any.
- */
-export function lowestPrice(prices, provider, model) {
-    let best;
-    for (const price of candidates(prices, provider, model)) {
-        if (best === undefined || price.offPeak.input < best.rates.input)
-            best = { price, rates: price.offPeak };
-    }
-    return best;
+    return { price, matchedBy, rates: price.weekdays.includes(day) && price.windows.some(([a, b]) => minute >= a && minute < b) ? price.peak : price.offPeak };
 }
 /** Decide the amount for one request sample using the table loaded at decision time.
  *
- * The returned decision is recorded once and never revisited: a later `prices.json` change must
- * not move a historical amount. Only a sample with no usable usage (`missing usage`) is left
- * undecided, because its request has not finished reporting tokens yet.
+ * A decision is a number or a reason; nothing about the rates that produced it is kept, because the
+ * ledger stores totals rather than requests and the next scan decides the sample again.
  * @param prices - Validated versions currently loaded.
  * @param provider - Provider identity from the recorded request.
  * @param model - Recorded model name.
  * @param time - Recorded settlement timestamp, when the host logged one.
  * @param usage - Disjoint token buckets, when the host reported valid counts.
- * @returns The selected price identity, the amount, and the reason when no amount exists.
+ * @returns The amount, or the reason no amount exists.
  */
 export function chargeFor(prices, provider, model, time, usage) {
     if (!usage)
         return { reason: MISSING_USAGE };
-    const selected = time === undefined ? lowestPrice(prices, provider, model) : priceAt(prices, provider, model, time);
+    // The published DeepSeek table prices cache hits, cache misses and output; a fourth bucket means
+    // the usage mapping is wrong, and inventing a rate for it would hide that.
+    if (provider === 'deepseek-official' && usage.cacheWrite !== 0)
+        return { reason: UNSUPPORTED_USAGE };
+    // No settlement time means the host did not say when the request was billed, and the two peak
+    // bands differ by a factor of two: a floor amount would enter the total while belonging to no day,
+    // so the request is reported unresolved instead of guessed.
+    if (time === undefined)
+        return { reason: MISSING_TIME };
+    const selected = priceAt(prices, provider, model, time);
     if (!selected)
         return { reason: 'no price version' };
     const amount = (usage.input * selected.rates.input + usage.output * selected.rates.output
         + usage.cacheRead * selected.rates.cacheRead + usage.cacheWrite * selected.rates.cacheWrite) / 1e6;
     if (!Number.isFinite(amount))
         return { reason: 'invalid estimate' };
-    return { priceId: selected.price.id, amount, ...(time === undefined ? { estimated: true } : {}) };
+    return { amount };
 }

package/dist/cost/records.js

@@ -1,19 +1,31 @@
 /** Fold host history records into per-request samples; conversation text never enters the ledger. */
 import { array, object } from "../transport/wire.js";
-/** Host event types that carry billing-relevant usage or route context. */
-const BILLING_EVENTS = new Set(['request/context', 'assistant/message', 'assistant/attempt', 'llm/retry-started', 'session/end-seed']);
+/** Host event types that carry billing-relevant usage or route context.
+ *
+ * `compaction/summary` is a provider request like any other — it reads the whole context to write the
+ * summary — and it records its own provider, model and usage instead of appearing as an assistant
+ * message, so a fold without it under-reports the most expensive requests in a session.
+ */
+const BILLING_EVENTS = new Set(['request/context', 'assistant/message', 'assistant/attempt', 'llm/retry-started', 'session/end-seed', 'compaction/summary']);
 /** Keep only billing-relevant fields; prompts, tool bodies, cookies and keys never enter the ledger.
  * @param records - One HTTP history page's records.
  * @returns Minimal durable events for a deterministic usage fold.
  */
 export function costRecords(records) {
-    return array(records).map(raw => object(object(raw).event)).filter(e => BILLING_EVENTS.has(String(e.type))).map(e => {
+    return array(records).map(raw => object(object(raw).event)).filter(e => BILLING_EVENTS.has(String(e.type)))
+        // A summary written without a model call — an unmarked template or remote summarizer — has no
+        // usage and no cost, so it is not a billable sample at all.
+        .filter(e => e.type !== 'compaction/summary' || object(e.data).usage !== undefined).map(e => {
         const d = object(e.data);
         const m = object(d.message ?? {});
         const stream = array(d.stream ?? []).map(r => object(object(r).chunk ?? {})).filter(c => c.type === 'usage');
+        // A summary names its own provider and model, and carries no turn or step to fold against, so
+        // its route travels as the source a message would carry rather than as folded context.
+        const source = e.type === 'compaction/summary' ? { provider: d.provider ?? null, model: d.model ?? null } : m.source ?? null;
         return { seq: e.seq ?? null, time: e.time ?? null, type: e.type, data: {
-                inherited: d.inherited ?? false, turn: d.turn ?? null, step: d.step ?? null, provider: d.provider ?? null, model: d.model ?? null,
-                source: m.source ?? null, usage: d.usage ?? stream.at(-1)?.usage ?? null,
+                inherited: d.inherited ?? false, turn: d.turn ?? null, step: d.step ?? null,
+                provider: d.provider ?? null, model: d.model ?? null,
+                source, usage: d.usage ?? stream.at(-1)?.usage ?? null,
             } };
     });
 }
@@ -43,6 +55,7 @@ export function foldSamples(events) {
                 last = undefined;
             continue;
         }
+        // A message or summary carries its own route; only the remaining events inherit the folded one.
         const source = object(d.source ?? {});
         const provider = String(source.provider ?? route.provider ?? '');
         const model = String(source.model ?? route.model ?? '');

package/dist/cost/types.d.ts

@@ -11,6 +11,8 @@ export interface PriceVersion {
     id: string;
     provider: string;
     model: string;
+    /** Further model names this version prices; a trailing `*` matches a prefix. Never a guess. */
+    aliases?: string[];
     from: string;
     until?: string;
     currency: 'CNY';
@@ -28,7 +30,7 @@ export interface Usage {
     cacheRead: number;
     cacheWrite: number;
 }
-/** One folded request sample before a price decision is attached. */
+/** One folded request sample: the attempt identity and the facts a price decision needs. */
 export interface ChargeSample {
     key: string;
     time?: number;
@@ -36,34 +38,48 @@ export interface ChargeSample {
     model: string;
     usage?: Usage;
 }
-/** The price decision recorded the first time a request sample was evaluated. */
+/** What the table decides for one request sample: an amount, or the reason it has none. */
 export interface PriceDecision {
-    priceId?: string;
     amount?: number;
-    estimated?: true;
     reason?: string;
 }
-/** One ledger entry: a request sample plus the price decision that seals it. */
-export interface Charge extends ChargeSample, PriceDecision {
-}
-/** One session's persisted ledger slice. */
-export interface SavedCost {
-    version: 2;
-    sessionId: string;
-    cut: number;
-    charges: Charge[];
-}
-/** Summary retains the known subtotal, the records it could not price, and the coarse estimates.
- * `unknown` counts records with no amount at all; `estimated` counts records that only have a
- * floor amount, including dated requests whose timestamp cannot place them inside the range.
+/** Summary retains the known subtotal and the records it could not price.
+ * `unknown` counts records with no amount; `records` counts every request the range covers, so a
+ * subtotal is never read as complete without them.
  */
 export interface CostTotal {
     amount: number;
     unknown: number;
-    estimated: number;
     records: number;
 }
+/** One Beijing calendar day's requests, kept only for the day a scan ran on. */
+export interface DayTotal extends CostTotal {
+    day: string;
+}
+/** One session's persisted ledger slice.
+ *
+ * The host log and the loaded price table are the only inputs, so the slice stores the totals one
+ * scan folded them into and no per-request detail: the next scan reads the session's history again
+ * and decides every sample with the table loaded then. `engine` and `catalog` name the decision
+ * rules and the table behind these totals, so a process holding an older one cannot overwrite them.
+ */
+export interface SavedCost {
+    version: 3;
+    sessionId: string;
+    /** Durable sequence the fold reached; a scan that opened an older cut may not replace this slice. */
+    cut: number;
+    engine: number;
+    catalog: string;
+    total: CostTotal;
+    day: DayTotal;
+    /** Distinct reasons an amount is missing, bounded, so a panel can say what makes a total inexact. */
+    unpriced: string[];
+}
 /** How much of the visible history the cached ledger currently covers. */
 export type Coverage = 'complete' | 'scanning' | 'partial';
 /** Reason recorded when a sample carries no usable token counts. */
 export declare const MISSING_USAGE = "missing usage";
+/** Reason recorded when the host reported a cache-write bucket the published table does not price. */
+export declare const UNSUPPORTED_USAGE = "unsupported usage";
+/** Reason recorded when the request has no settlement time to place it in a peak band or a day. */
+export declare const MISSING_TIME = "missing time";

package/dist/cost/types.js

@@ -1,3 +1,7 @@
 /** Cost-domain types shared by pricing, record folding, storage and the in-memory ledger. */
 /** Reason recorded when a sample carries no usable token counts. */
 export const MISSING_USAGE = 'missing usage';
+/** Reason recorded when the host reported a cache-write bucket the published table does not price. */
+export const UNSUPPORTED_USAGE = 'unsupported usage';
+/** Reason recorded when the request has no settlement time to place it in a peak band or a day. */
+export const MISSING_TIME = 'missing time';

package/dist/session/controller.d.ts

@@ -46,6 +46,15 @@ export declare class SessionController {
      * @returns Retained question and approval frames for that session.
      */
     pendingFor(state: State): ObjectValue[];
+    /** Unanswered interactions by session, so a list can show who is waiting without opening them.
+     *
+     * The host delivers approval and question waterfalls for every session on one stream, and this
+     * client already retains them to answer later, so the counts are a fact of this generation rather
+     * than a new subscription. They live only as long as the connection: a reconnect clears the map
+     * until the host replays the pending waterfalls.
+     * @returns One count per session holding at least one unanswered interaction.
+     */
+    pendingCounts(): ReadonlyMap<string, number>;
     /** Retain a recognized host waterfall; unknown events stay with the connection to delegate.
      * @param frame - One decoded waterfall frame.
      * @returns Whether this domain retained the frame for an answer.
@@ -168,6 +177,13 @@ export declare class SessionController {
      * @param allowed - Whether the request is approved once.
      */
     approve(allowed: boolean): Promise<void>;
+    /** Dismiss the whole selected-session question set without answering it.
+     *
+     * The Web client's close button settles the same waterfall the same way — reject with
+     * `ASK_CANCELLED` — so the host records a user cancellation rather than an answer. A question
+     * batch is answered as one request, so dismissals also discard partial local answers.
+     */
+    dismissQuestion(): Promise<void>;
     /** Add a page before the retained window using its fixed opening cut.
      * @param signal - Cancels local paging without interrupting the remote agent.
      * @param transcript - Transcript to extend; defaults to the live one.

package/dist/session/controller.js

@@ -95,6 +95,23 @@ export class SessionController {
     pendingFor(state) {
         return [...this.interactions.values()].filter(frame => frame.agentId === state.sessionId);
     }
+    /** Unanswered interactions by session, so a list can show who is waiting without opening them.
+     *
+     * The host delivers approval and question waterfalls for every session on one stream, and this
+     * client already retains them to answer later, so the counts are a fact of this generation rather
+     * than a new subscription. They live only as long as the connection: a reconnect clears the map
+     * until the host replays the pending waterfalls.
+     * @returns One count per session holding at least one unanswered interaction.
+     */
+    pendingCounts() {
+        const counts = new Map();
+        for (const frame of this.interactions.values()) {
+            if (typeof frame.agentId !== 'string')
+                continue;
+            counts.set(frame.agentId, (counts.get(frame.agentId) ?? 0) + 1);
+        }
+        return counts;
+    }
     /** Retain a recognized host waterfall; unknown events stay with the connection to delegate.
      * @param frame - One decoded waterfall frame.
      * @returns Whether this domain retained the frame for an answer.
@@ -459,6 +476,22 @@ export class SessionController {
             throw new Error('No pending approval');
         await this.answer(allowed ? 'allowed-once' : 'rejected');
     }
+    /** Dismiss the whole selected-session question set without answering it.
+     *
+     * The Web client's close button settles the same waterfall the same way — reject with
+     * `ASK_CANCELLED` — so the host records a user cancellation rather than an answer. A question
+     * batch is answered as one request, so dismissals also discard partial local answers.
+     */
+    async dismissQuestion() {
+        const pending = this.store.state.pending[0];
+        if (pending?.event !== 'user-questions/request')
+            throw new Error('No pending question');
+        await this.reply(pending, { kind: 'rejected', error: {
+                name: 'UserQuestionError', message: 'the user cancelled ask_user_question', code: 'ASK_CANCELLED',
+            } });
+        this.interactions.delete(string(pending.eventId));
+        this.store.update({});
+    }
     /** Add a page before the retained window using its fixed opening cut.
      * @param signal - Cancels local paging without interrupting the remote agent.
      * @param transcript - Transcript to extend; defaults to the live one.

package/dist/session/navigation.d.ts

@@ -9,3 +9,83 @@ export declare function navigationCommand(value: string): {
 export declare function sessionLabel(session: ObjectValue): string;
 /** Match an exact ID or name before a unique ID prefix; never choose an ambiguous target. */
 export declare function resolveTarget(items: ObjectValue[], query: string, id: string, names: (item: ObjectValue) => string[]): ObjectValue;
+/** User-visible activity of one session, most actionable first.
+ *
+ * `needs` is the only state that asks the user to do something, and it outranks the host's running
+ * flag because a turn waiting on an answer is running only in the mechanical sense. `blank` stays a
+ * marker for a session that never sent a turn, but it is not a status and never enters a rollup.
+ */
+export type SessionState = 'needs' | 'running' | 'idle' | 'blank';
+/** Classify one session from the host's list summary; nothing is inferred from silence.
+ * @param session - Session summary from `session/list`.
+ * @param pending - Whether this client holds an unanswered interaction for that session.
+ * @returns Needs-you while an answer is owed, running while its agent works, otherwise idle or blank.
+ */
+export declare function sessionState(session: ObjectValue, pending?: boolean): SessionState;
+/** Leading marker per state: a question mark, a working clock, a filled dot, and an unused circle. */
+export declare const SESSION_MARKERS: Record<SessionState, string>;
+/** One word per state, so every screen names the same state the same way. */
+export declare const STATE_LABELS: Record<SessionState, string>;
+/** Coarse age of a session's last activity, so the column stays steady between list refreshes.
+ * @param time - Epoch milliseconds of the last activity, when the summary reported one.
+ * @param now - Current epoch milliseconds.
+ * @returns `now`, minutes, hours or days.
+ */
+export declare function activityAge(time: number | undefined, now: number): string;
+/** Status cell for one session row: its state marker and the age of its last activity.
+ * @param session - Session summary from `session/list`.
+ * @param now - Current epoch milliseconds.
+ * @param pending - Whether this client holds an unanswered interaction for that session.
+ * @returns Marker with an optional age, without a trailing space when unknown.
+ */
+export declare function sessionStatus(session: ObjectValue, now: number, pending?: boolean): string;
+/** States a workspace rollup reports, most actionable first. */
+export declare const ROLLUP_STATES: readonly ["needs", "running", "idle"];
+/** One state a workspace rollup reports. */
+export type RollupState = (typeof ROLLUP_STATES)[number];
+/** One counted state of a workspace rollup. */
+export interface RollupCount {
+    state: RollupState;
+    count: number;
+}
+/** How much room a rollup has for words. */
+export type RollupStyle = 'words' | 'badges';
+/** Count the sessions of one workspace by the state each reports.
+ *
+ * Blank sessions are counted by neither a badge nor a word: a session that never sent a turn is the
+ * absence of activity, and listing it beside real work only makes the rollup harder to read.
+ * @param sessions - Sessions whose `sessionIds` belong to the workspace.
+ * @param pending - Session IDs this client holds an unanswered interaction for.
+ * @returns One count per state that occurs, most actionable first, or an empty list.
+ */
+export declare function workspaceCounts(sessions: readonly ObjectValue[], pending?: ReadonlySet<string>): RollupCount[];
+/** Render one rollup as separately coloured cells.
+ *
+ * Each cell after the first carries the separator that joins it to the previous one, so a caller can
+ * colour the cells independently without losing the text {@link workspaceStatus} would produce.
+ * @param counts - Counts from {@link workspaceCounts}.
+ * @param style - `words` spells each state out; `badges` keeps only the marker and the count.
+ * @returns The cells in the order given, with their separators.
+ */
+export declare function workspaceSegments(counts: readonly RollupCount[], style?: RollupStyle): {
+    state: RollupState;
+    text: string;
+}[];
+/** Render one rollup as plain text, the same way every screen and test reads it.
+ * @param counts - Counts from {@link workspaceCounts}.
+ * @param style - `words` spells each state out; `badges` keeps only the marker and the count.
+ * @returns The joined cell text, empty when nothing was counted.
+ */
+export declare function workspaceStatus(counts: readonly RollupCount[], style?: RollupStyle): string;
+/** Marker key for the compact rollup, which has no room for the words. */
+export declare const ROLLUP_LEGEND: string;
+/** Secondary path text for one workspace row.
+ *
+ * The title is usually the last path segment, so repeating it wastes the row; the parent directory
+ * is what distinguishes two checkouts. A title that does not name the last segment keeps the full
+ * path, because dropping it would hide where the workspace actually lives.
+ * @param path - Registered host directory.
+ * @param title - Workspace title as the row already shows it.
+ * @returns The path to show beside the row, or an empty string when nothing is left.
+ */
+export declare function workspaceDetail(path: string, title: string): string;