Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

10.2 KB
Raw Blame
import type { HistoryWorkLine } from './historyWorkLines.js';

/** Reading projections never replace persisted messages or the agent transcript. */
export const HISTORY_VIEW_VERSION = 1 as const;
export const HISTORY_VIEW_PAGE_ITEMS = 20;
export const HISTORY_VIEW_PAGE_BYTES = 1024 * 1024;
export const HISTORY_DETAIL_PAGE_BYTES = 256 * 1024;

/** Local ordering only: the run changes on restart, and order never uses the wall clock. */
export interface HistoryCacheReceipt { run: string; order: number }
const cacheReceiptRun = `${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
let cacheReceiptOrder = 0;
export function nextHistoryCacheReceipt(): HistoryCacheReceipt {
  return { run: cacheReceiptRun, order: ++cacheReceiptOrder };
}
export function isHistoryCacheReceipt(value: unknown): value is HistoryCacheReceipt {
  const receipt = value as HistoryCacheReceipt | null;
  return !!receipt && typeof receipt.run === 'string' && Number.isSafeInteger(receipt.order) && receipt.order > 0;
}
/** Only a current-run push can supersede a restored page from another run. */
export function historyCacheReceiptFollows(receipt: unknown, read: unknown, restored = false): boolean {
  if (!isHistoryCacheReceipt(receipt)) return false;
  if (!isHistoryCacheReceipt(read)) return true;
  return receipt.run === read.run ? receipt.order > read.order : restored && receipt.run === cacheReceiptRun;
}

export function isHistoryViewUnavailable(error: unknown): boolean {
  return /CHANNEL_NOT_ALLOWED|UNSUPPORTED_CAPABILITY|not registered|No handler/i.test(String(error));
}

/** Visible file candidates, independent of the folded tool body that produced them. */
export interface HistoryFileArtifact {
  path: string;
  source: 'tool' | 'command';
  createdAt: string;
  toolUseId?: string;
  ready?: boolean;
  /** Preserve file-card suppression when the editing tool body is deferred. */
  exclude?: 'command' | 'all';
}

export interface HistoryMessageSource {
  id: string;
  clientId: string;
  role: string;
  content: unknown;
  createdAt: string;
  rowid?: number;
  /** Controller-local order of a durable push; never a Host revision. */
  cacheReceipt?: HistoryCacheReceipt;
  toolUseId?: string | null;
  agentMeta?: object | null;
  /** Host outline only; transferred in work summaries, never as a replacement body. */
  historyArtifacts?: HistoryFileArtifact[];
  /** Host outline only: changes when the hidden body is rewritten; hashed into revisions. */
  historyContentStamp?: string;
}

/** Both endpoints are real host message IDs, inclusive, in host database order. */
export interface HistoryWorkReference {
  key: string;
  firstMessageId: string;
  lastMessageId: string;
  /** Stored upper bound when the range ends in a recoverable in-flight block. */
  firstStoredMessageId?: string;
  lastStoredMessageId?: string;
  liveMessageIds?: string[];
  /** Restricts a subagent detail range to this tool and its descendants. */
  parentToolUseId?: string;
}

export interface HistoryWorkSummary extends HistoryWorkReference {
  /** Original activity anchor; stable when its body has not been read yet. */
  anchorClientId?: string;
  artifacts?: HistoryFileArtifact[];
  /** Actual child model from persisted metadata; not the requested model. */
  model?: string;
  /** Existing detail endpoint can read just the visible desktop tail. */
  preview?: HistoryWorkSummary;
  /**
   * Latest single-line activities of a running range, already projected by the Host.
   * Present only when the controller asked for `workLines`; old Hosts omit it.
   */
  lines?: HistoryWorkLine[];
  startedAtMs: number;
  endedAtMs: number;
  isStreaming: boolean;
  messageCount: number;
  toolCount: number;
  /** Changes when the source range or its persisted contents change. */
  revision: string;
}

/** Controller-local actions; never serialized into the host reading protocol. */
export interface DeferredHistoryWork {
  owner?: object;
  key?: string;
  revision?: string;
  setVisible?(expanded: boolean, preview: boolean): void;
  previewComplete?: boolean;
  /** Host-projected running lines; when present a folded preview needs no detail read. */
  lines?: readonly HistoryWorkLine[];
  /** No detail rows are in hand yet; an expanded group keeps showing `lines` until they arrive. */
  awaitingDetails?: boolean;
  expanded: boolean;
  loading: boolean;
  failed: boolean;
  toggle(): void;
  retry(): void;
}

export type HistoryViewItem<TMessage extends HistoryMessageSource> =
  | { type: 'messages'; key: string; messages: TMessage[]; deferred?: HistoryWorkSummary }
  | { type: 'work'; key: string; summary: HistoryWorkSummary; children?: HistoryViewItem<TMessage>[] };

/** Outer summaries retain only prose and action references, never hidden bodies. */
export function historyViewLeaves<T extends HistoryMessageSource>(items: readonly HistoryViewItem<T>[]): HistoryViewItem<T>[] {
  return items.flatMap((item) => item.type === 'work' && item.children ? historyViewLeaves(item.children) : [item]);
}

export function historyWorkSummaries<T extends HistoryMessageSource>(items: readonly HistoryViewItem<T>[]): HistoryWorkSummary[] {
  return historyViewLeaves(items).flatMap((item) => item.type === 'work'
    ? [item.summary, ...(item.summary.preview ? [item.summary.preview] : [])] : item.deferred ? [item.deferred] : []);
}

export function mapHistoryViewMessages<T extends HistoryMessageSource, U extends HistoryMessageSource>(
  items: readonly HistoryViewItem<T>[], map: (rows: T[]) => U[],
): HistoryViewItem<U>[] {
  return items.map((item) => item.type === 'messages' ? { ...item, messages: map(item.messages) }
    : { ...item, children: item.children ? mapHistoryViewMessages(item.children, map) : undefined });
}

export interface HistoryViewPage<TMessage extends HistoryMessageSource> {
  version: typeof HISTORY_VIEW_VERSION;
  /** Chronological; the cursor advances independently of the rendered item count. */
  items: HistoryViewItem<TMessage>[];
  nextCursor: string | null;
  hasMore: boolean;
}

function historyPrefixBoundary<T extends HistoryMessageSource>(
  page: HistoryViewPage<T>, previous: readonly HistoryViewItem<T>[],
): number {
  const firstSourceId = (item: HistoryViewItem<T> | undefined) => item?.type === 'work'
    ? item.summary.firstMessageId : item?.messages[0]?.id;
  const first = page.items[0];
  const sourceId = firstSourceId(first);
  return previous.findIndex(item => item.key === first?.key
    || (sourceId !== undefined && firstSourceId(item) === sourceId));
}

/** Keep already read pages only when the latest page proves a continuous source boundary. */
export function retainHistoryViewPrefix<T extends HistoryMessageSource>(
  page: HistoryViewPage<T>,
  previous: { items: readonly HistoryViewItem<T>[]; hasMore: boolean; nextCursor: string | null } | null | undefined,
): HistoryViewPage<T> {
  if (!page.hasMore || !previous?.items.length) return page;
  const boundary = historyPrefixBoundary(page, previous.items);
  // Completed groups can replace a running key while keeping its exact source start.
  // A later overlap cannot prove continuity; a full page/rewind replaces the old view.
  if (boundary <= 0) return page;
  return { ...page, items: [...previous.items.slice(0, boundary), ...page.items],
    hasMore: previous.hasMore, nextCursor: previous.nextCursor };
}

/** Fill a missed-page gap before replacing a cached reading window. Never join on time alone. */
export async function readContinuousHistoryPage<T extends HistoryMessageSource>(
  latest: HistoryViewPage<T>,
  previous: { items: readonly HistoryViewItem<T>[]; hasMore: boolean; nextCursor: string | null } | null | undefined,
  readOlder: (before: string) => Promise<HistoryViewPage<T> | null | undefined>,
  isCurrent: () => boolean,
): Promise<HistoryViewPage<T> | null> {
  let page = latest;
  const startedAt = (item: HistoryViewItem<T> | undefined) => item?.type === 'work'
    ? item.summary.startedAtMs : Date.parse(item?.messages[0]?.createdAt ?? '');
  const seen = new Set<string>();
  while (isCurrent() && previous?.items.length && page.hasMore
    && historyPrefixBoundary(page, previous.items) < 0
    // Equal timestamps can still contain later rows in the Host's rowid order.
    && startedAt(page.items[0]) >= startedAt(previous.items[0])) {
    const cursor = page.nextCursor;
    if (!cursor || seen.has(cursor)) throw new Error('History page cursor did not advance');
    seen.add(cursor);
    const older = await readOlder(cursor);
    if (!isCurrent()) return null;
    if (!older) throw new Error('History page is unavailable while filling a gap');
    const keys = new Set(page.items.map(item => item.key));
    page = { ...older, items: [...older.items.filter(item => !keys.has(item.key)), ...page.items] };
  }
  return isCurrent() ? page : null;
}

/**
 * Host → controller replacement of one running top-level work item. The Host sends it
 * only when everything else on the latest page is unchanged since its last delivery to
 * that controller; `baseRevision` is the item revision that delivery carried.
 */
export interface HistoryWorkPatch {
  version: typeof HISTORY_VIEW_VERSION;
  sessionId: string;
  baseRevision: string;
  item: { type: 'work'; key: string; summary: HistoryWorkSummary };
}

export const HISTORY_WORK_PATCH_CHANNEL = 'maker:history-work-patch';

export interface HistoryDetailPage<TMessage extends HistoryMessageSource> {
  version: typeof HISTORY_VIEW_VERSION;
  messages: TMessage[];
  nextCursor: string | null;
  hasMore: boolean;
}

/** Shared by all controllers. A page boundary is never a user-facing "load more" step. */
export async function readHistoryWorkDetails<TMessage extends HistoryMessageSource>(options: {
  readPage(cursor: string | null): Promise<HistoryDetailPage<TMessage>>;
  initialCursor?: string | null;
  isCurrent(): boolean;
  onPage(messages: readonly TMessage[]): void;
}): Promise<void> {
  let cursor: string | null = options.initialCursor ?? null;
  const seen = new Set<string>();
  while (options.isCurrent()) {
    const page = await options.readPage(cursor);
    if (!options.isCurrent()) return;
    options.onPage(page.messages);
    if (!page.hasMore) return;
    if (!page.nextCursor || seen.has(page.nextCursor)) {
      throw new Error('History detail cursor did not advance');
    }
    seen.add(page.nextCursor);
    cursor = page.nextCursor;
  }
}