Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import {
nextHistoryCacheReceipt, type HistoryCacheReceipt,
readHistoryWorkDetails, readContinuousHistoryPage, retainHistoryViewPrefix, isHistoryViewUnavailable, historyWorkSummaries, historyViewLeaves, type HistoryDetailPage, type HistoryMessageSource,
type HistoryViewItem, type HistoryViewPage, type HistoryWorkPatch, type HistoryWorkSummary,
} from './historyView.js';
export interface HistoryWorkDetailState<T extends HistoryMessageSource> {
messages: readonly T[];
revision: string;
lastMessageId: string;
loading: boolean;
complete: boolean;
error: unknown | null;
}
export interface HistoryViewSnapshot<T extends HistoryMessageSource> {
items: readonly HistoryViewItem<T>[];
details: ReadonlyMap<string, HistoryWorkDetailState<T>>;
expanded: ReadonlySet<string>;
nextCursor: string | null;
hasMore: boolean;
loading: boolean;
ready: boolean;
error: unknown | null;
/**
* The latest page may be behind rows the raw store already received: it came from
* disk, or was read before the view went inactive/offline. Cleared by a latest-page read.
*/
stale?: boolean;
/** Controller-local start of the latest page read, also retained in its disk cache. */
readReceipt?: HistoryCacheReceipt;
}
export interface HistoryViewTransport<T extends HistoryMessageSource> {
/** False when the owning screen already coordinates focus/reconnect snapshots. */
refreshOnResume?: boolean;
page(before?: string): Promise<HistoryViewPage<T>>;
details(summary: HistoryWorkSummary, after?: string): Promise<HistoryDetailPage<T>>;
/** Full replacement of this view's intent; empty releases detail streaming. */
expanded(summaries: readonly HistoryWorkSummary[]): Promise<void>;
/** Local diagnostics only: counts and lifecycle, never message bodies. */
diagnostic?(event: HistoryViewDiagnostic): void;
}
export interface HistoryViewDiagnostic {
source: 'cache' | 'latest' | 'older' | 'details' | 'fallback' | 'reset';
previousItemCount: number;
itemCount: number;
messageCount: number;
detailMessageCount: number;
ready: boolean;
stale: boolean;
}
/**
* Shared reading state for native and desktop controllers. Raw message stores never
* receive synthetic rows or a false promise that deferred source ranges are loaded.
*/
export class HistoryViewController<T extends HistoryMessageSource> {
private state: HistoryViewSnapshot<T> = {
items: [], details: new Map(), expanded: new Set(), nextCursor: null,
hasMore: false, loading: false, ready: false, error: null,
};
private listeners = new Set<() => void>();
private generation = 0;
// Transport changes invalidate remote reads, not local disk restoration.
private cacheGeneration = 0;
private detailRuns = new Map<string, { promise: Promise<void> }>();
private active = true;
private networkAvailable = true;
private pagePromise: Promise<void> | null = null;
private pageOlder = false;
private pageGeneration = 0;
private intentVersion = 0;
private refreshTimer: ReturnType<typeof setTimeout> | null = null;
private latestReadStartedAtMs = 0;
private latestReadOkStartedAtMs = 0;
constructor(
private readonly transport: HistoryViewTransport<T>,
// A replacement controller can inherit the same ordering without waiting
// for the old source's page/detail requests.
private readonly intentQueue = { tail: Promise.resolve() as Promise<void> },
) {}
isActive = (): boolean => this.active && this.networkAvailable;
/** Offline reading retains the view, but never sends page/detail/interest requests. */
setNetworkAvailable(available: boolean): void {
if (this.networkAvailable === available) return;
this.networkAvailable = available;
this.generation++;
this.detailRuns.clear();
if (this.refreshTimer) clearTimeout(this.refreshTimer);
this.refreshTimer = null;
this.publish({ loading: false, ...(available ? {} : { stale: this.state.ready }),
details: new Map([...this.state.details].map(([key, detail]) =>
[key, detail.loading ? { ...detail, loading: false } : detail])) });
if (available && this.active && this.transport.refreshOnResume !== false) void this.refresh();
}
getSnapshot = (): HistoryViewSnapshot<T> => this.state;
/** Pagination feedback only; background validation must not disturb the reading viewport. */
isLoadingOlder = (): boolean => this.state.loading && this.pageOlder;
/**
* Wall-clock start of the most recent latest-page read (0 before the first). A caller
* holding the time a change notice arrived can tell whether a read already covers it,
* instead of forcing one more page read per notice.
*/
latestReadStartedAt = (): number => this.latestReadStartedAtMs;
/**
* Start time of the most recent latest-page read that completed and was applied (0 before
* the first). A failed or superseded read never advances it, so "covered by a read" can
* be certified without trusting an error-cleared snapshot.
*/
latestReadOkStartedAt = (): number => this.latestReadOkStartedAtMs;
/** True while a latest-page read is in flight; older-page reads do not count. */
isReadingLatest = (): boolean => this.pagePromise !== null && !this.pageOlder;
subscribe = (listener: () => void): (() => void) => {
this.listeners.add(listener);
return () => this.listeners.delete(listener);
};
private publish(patch: Partial<HistoryViewSnapshot<T>>, source?: HistoryViewDiagnostic['source']): void {
const previousItemCount = this.state.items.length;
this.state = { ...this.state, ...patch };
if (source && this.transport.diagnostic) {
try {
this.transport.diagnostic({ source, previousItemCount, itemCount: this.state.items.length,
messageCount: historyViewLeaves(this.state.items).reduce((count, item) =>
count + (item.type === 'messages' ? item.messages.length : 0), 0),
detailMessageCount: [...this.state.details.values()].reduce((count, detail) => count + detail.messages.length, 0),
ready: this.state.ready, stale: this.state.stale === true });
} catch { /* Diagnostics must not interrupt cache restoration or remote reads. */ }
}
for (const listener of this.listeners) listener();
}
/** Optimistic local display only. A fresh response or reset always wins over disk IO. */
async restoreCachedView(read: () => Promise<HistoryViewSnapshot<T> | null>): Promise<void> {
if (this.state.ready || isHistoryViewUnavailable(this.state.error)) return;
const generation = this.cacheGeneration;
const cached = await read().catch(() => null);
if (!cached || this.state.ready || isHistoryViewUnavailable(this.state.error) || generation !== this.cacheGeneration) return;
this.publish({ ...cached, loading: this.state.loading, error: this.state.error, stale: true }, 'cache');
}
refresh(older = false, fresh = false): Promise<void> {
// Keep the existing raw fallback until an explicit reset; a later latest
// page must not re-enable projection after an oversized older-page read.
if (/UNSUPPORTED_CAPABILITY/.test(String(this.state.error))) return Promise.resolve();
if (this.pagePromise) {
// Subscription recovery must read after its ACK, not reuse a pre-ACK page.
// Reuse the same wait queue and preserve expansion; no parallel read is needed.
// A caller after reset/reactivation must await its own generation's read,
// even when the invalidated request happened to have the same direction.
if (!fresh && older === this.pageOlder && this.pageGeneration === this.generation) return this.pagePromise;
const generation = this.generation;
return this.pagePromise.then(() => {
if (this.isActive() && generation === this.generation && (fresh || !this.state.error)) return this.refresh(older);
});
}
this.pageOlder = older;
this.pageGeneration = this.generation;
const promise = this.readPage(older);
this.pagePromise = promise;
void promise.finally(() => { if (this.pagePromise === promise) this.pagePromise = null; });
return promise;
}
/** Coalesce activity notices; full assistant streaming continues on its existing path. */
invalidate(): void {
if (!this.isActive() || this.refreshTimer) return;
this.refreshTimer = setTimeout(() => {
this.refreshTimer = null;
if (this.pagePromise) {
void this.pagePromise.then(() => this.invalidate());
} else void this.refresh();
}, 500);
}
/**
* Replace one running top-level work item in place. Anything this controller cannot
* prove to be the Host's base (a read in flight, a missing or reshaped item, another
* revision) falls back to the ordinary page refresh the notice used to trigger.
*/
applyWorkPatch(patch: HistoryWorkPatch): void {
if (!this.isActive()) return;
const index = this.state.items.findIndex((item) => item.key === patch.item.key);
const current = this.state.items[index];
if (this.pagePromise || this.refreshTimer || !this.state.ready || !current || current.type !== 'work' || current.children
|| current.summary.revision !== patch.baseRevision
|| current.summary.firstMessageId !== patch.item.summary.firstMessageId) {
this.invalidate();
return;
}
const items = [...this.state.items];
items[index] = patch.item;
this.publish({ items });
for (const summary of historyWorkSummaries([patch.item])) {
if (this.state.expanded.has(summary.key)) void this.loadDetails(summary);
}
}
private async readPage(older: boolean): Promise<void> {
if (!this.isActive() || this.state.loading || (older && !this.state.hasMore)) return;
const generation = this.generation;
const before = older ? this.state.nextCursor ?? undefined : undefined;
const readReceipt = nextHistoryCacheReceipt();
const readStartedAt = Date.now();
if (!older) this.latestReadStartedAtMs = readStartedAt;
this.publish({ loading: true, error: null });
try {
const page = await this.transport.page(before);
if (page == null) throw new Error('[CHANNEL_NOT_ALLOWED] History view is unavailable');
if (!this.active || generation !== this.generation) return;
const continuous = older ? page : await readContinuousHistoryPage(page, this.state,
(cursor) => this.transport.page(cursor), () => this.active && generation === this.generation);
if (!continuous) return;
const retained = older ? continuous : retainHistoryViewPrefix(continuous, this.state);
let items = retained.items;
if (older) {
const keys = new Set(items.map((item) => item.key));
items = [...items, ...this.state.items.filter((item) => !keys.has(item.key))];
}
// A background validation of the same page must not replace rendering
// identities. Applies to both Mobile and Desktop history consumers.
const previous = new Map(this.state.items.map((item) => [item.key, item]));
items = items.map((item) => {
const cached = previous.get(item.key);
return cached && JSON.stringify(cached) === JSON.stringify(item) ? cached : item;
});
const stableItems = items.length === this.state.items.length
&& items.every((item, index) => item === this.state.items[index]) ? this.state.items : items;
this.publish({ items: stableItems, ready: true, loading: false,
...(older ? {} : { stale: false, readReceipt }),
hasMore: retained.hasMore, nextCursor: retained.nextCursor }, older ? 'older' : 'latest');
if (!older) this.latestReadOkStartedAtMs = readStartedAt;
for (const summary of historyWorkSummaries(items)) {
if (this.state.expanded.has(summary.key)) void this.loadDetails(summary);
}
this.sendIntent();
} catch (error) {
if (generation === this.generation && this.active) {
if (isHistoryViewUnavailable(error)) {
// A downgraded Host must not leave a ready projection masking the raw
// fallback. Invalidate in-flight details and every cached source row.
this.generation++;
this.cacheGeneration++;
this.detailRuns.clear();
if (this.refreshTimer) clearTimeout(this.refreshTimer);
this.refreshTimer = null;
this.publish({ items: [], details: new Map(), expanded: new Set(), ready: false,
nextCursor: null, hasMore: false, loading: false, error }, 'fallback');
} else this.publish({ loading: false, error });
}
}
}
setExpanded(key: string, expanded: boolean): void {
if (this.state.expanded.has(key) === expanded) return;
const next = new Set(this.state.expanded);
if (expanded) next.add(key); else next.delete(key);
if (!expanded) this.detailRuns.delete(key);
this.publish({ expanded: next });
this.sendIntent();
const summary = historyWorkSummaries(this.state.items).find((value) => value.key === key);
if (expanded && summary) void this.loadDetails(summary);
}
private sendIntent(): void {
if (!this.networkAvailable) return;
// Serialize replacement intents: a late expand ACK can never win over collapse.
const generation = this.generation;
const version = ++this.intentVersion;
this.intentQueue.tail = this.intentQueue.tail.catch(() => undefined).then(async () => {
// Each replacement carries the latest state. Skip superseded *unsent*
// requests, but still resend after page reads/reconnects. Keep this token
// controller-local: a replacement Host must not cancel the old Host's release.
if (version !== this.intentVersion || generation !== this.generation || !this.networkAvailable) return;
// Empty replacement intents must release old interest even before a reset view is ready.
const summaries = this.active ? historyWorkSummaries(this.state.items).filter((item) => this.state.expanded.has(item.key)) : [];
await this.transport.expanded(summaries);
}).catch(() => {
// Detail interest is advisory; a transient ACK failure must not poison a successful page.
if (this.active && version === this.intentVersion && generation === this.generation) this.invalidate();
});
}
async loadDetails(summary: HistoryWorkSummary, options?: { allowCollapsed?: boolean }): Promise<void> {
const allowCollapsed = options?.allowCollapsed === true;
if (!this.isActive() || (!allowCollapsed && !this.state.expanded.has(summary.key))) return;
const inFlight = this.detailRuns.get(summary.key);
if (inFlight) return inFlight.promise;
const existing = this.state.details.get(summary.key);
if (existing?.complete && existing.revision === summary.revision) return;
const token = { promise: Promise.resolve() };
const generation = this.generation;
this.detailRuns.set(summary.key, token);
const current = () => this.active && generation === this.generation
&& this.detailRuns.get(summary.key) === token
&& (allowCollapsed || this.state.expanded.has(summary.key));
// A changed revision may include late edits anywhere in the range, even
// when its endpoint also advances. Keep the old display while rereading.
let collected: T[] = [];
const update = (patch: Partial<HistoryWorkDetailState<T>>) => {
const completed = this.state.details.get(summary.key);
if (completed?.complete && completed.revision === summary.revision && !patch.complete) return;
const details = new Map(this.state.details);
// A reread keeps the previous window until it settles. Publishing each
// incoming page would replace the old window with a partial slice of the
// new range: the rendered list collapses to the first page and shifts a
// bottom-pinned stream before the tail lands.
const settled = patch.complete === true;
const messages = !settled && existing?.messages?.length ? existing.messages
: collected.length ? collected : (existing?.messages ?? []);
details.set(summary.key, { messages, revision: summary.revision,
lastMessageId: summary.lastMessageId, loading: true, complete: false, error: null, ...patch });
this.publish({ details }, settled ? 'details' : undefined);
};
update({});
token.promise = (async () => {
try {
await readHistoryWorkDetails({
readPage: (cursor) => this.transport.details(summary, cursor ?? undefined),
isCurrent: current,
onPage: (rows) => {
const incoming = new Set(rows.map((row) => row.clientId));
collected = [...collected.filter((row) => !incoming.has(row.clientId)), ...rows];
update({});
},
});
if (current()) update({ loading: false, complete: true });
} catch (error) {
if (current()) update({ loading: false, error });
} finally {
if (this.detailRuns.get(summary.key) === token) {
const stillCurrent = current();
this.detailRuns.delete(summary.key);
const latest = historyWorkSummaries(this.state.items).find((item) => item.key === summary.key);
if (stillCurrent && latest && latest.revision !== summary.revision) await this.loadDetails(latest);
}
}
})();
return token.promise;
}
/** Locate by visible pages, preserving the original folded aggregate focus behavior. */
async locate(clientId: string, createdAt: string): Promise<T | null> {
const generation = this.generation;
const targetMs = Date.parse(createdAt);
const tried = new Set<string>();
while (this.active && generation === this.generation) {
for (const item of historyViewLeaves(this.state.items)) {
if (item.type === 'messages') {
const found = item.messages.find((row) => row.clientId === clientId);
if (found) return found;
}
const summary = item.type === 'work' ? item.summary : item.deferred;
if (summary && !tried.has(summary.key) && targetMs >= summary.startedAtMs && targetMs <= summary.endedAtMs) {
tried.add(summary.key);
const current = () => this.active && generation === this.generation
&& historyWorkSummaries(this.state.items).some((value) => value.key === summary.key && value.revision === summary.revision
&& value.firstMessageId === summary.firstMessageId && value.lastMessageId === summary.lastMessageId);
const cached = this.state.details.get(summary.key);
let messages = cached?.complete && cached.revision === summary.revision ? [...cached.messages] : [];
if (!messages.length && this.networkAvailable) {
// Search reads the bounded range without changing user expansion memory
// or subscribing to hidden activity. Mount/collapse cannot cancel it.
try {
await readHistoryWorkDetails({
readPage: (cursor) => this.transport.details(summary, cursor ?? undefined),
isCurrent: current,
onPage: (rows) => { messages.push(...rows); },
});
} catch (error) {
if (!current()) return null;
throw error;
}
if (!current()) return null;
const details = new Map(this.state.details);
details.set(summary.key, { messages, revision: summary.revision, lastMessageId: summary.lastMessageId,
loading: false, complete: true, error: null });
this.publish({ details });
}
if (!current()) return null;
const found = messages.find((row) => row.clientId === clientId);
if (found) return found;
}
}
if (!this.networkAvailable || !this.state.hasMore) return null;
await this.refresh(true);
if (this.state.error) throw this.state.error;
}
return null;
}
/** View blur/background and source resets invalidate all outstanding reads. */
setActive(active: boolean): void {
if (active === this.active) {
if (active && !this.state.ready && this.transport.refreshOnResume !== false) void this.refresh();
return;
}
if (this.refreshTimer) clearTimeout(this.refreshTimer);
this.refreshTimer = null;
this.active = active;
this.generation++;
// Leaving drops a late disk read; gaining focus keeps it (pages mount hidden, then focus).
if (!active) this.cacheGeneration++;
this.detailRuns.clear();
this.publish({ loading: false, ...(active ? {} : { stale: this.state.ready }) });
this.sendIntent();
if (active && this.transport.refreshOnResume !== false) void this.refresh();
}
reset(): void {
this.generation++;
this.cacheGeneration++;
this.detailRuns.clear();
this.publish({ items: [], details: new Map(), expanded: new Set(), ready: false,
nextCursor: null, hasMore: false, loading: false, error: null, stale: false, readReceipt: undefined }, 'reset');
this.sendIntent();
if (this.active) void this.refresh();
}
}