ds-harness-remote-fast/packages/plugin/src/lite-mode.ts

175 lines
6.6 KiB
TypeScript

/**
* Lite mode: shrink what a remote client receives on first paint.
*
* Large sessions make the initial `snapshot` frame megabytes wide (hundreds of
* records plus per-session projections such as the context-lens panel). Clients
* that cannot chunk a frame (`transferFrames: false`, e.g. the web client) hit
* "Oversized Harness Remote frame" and the whole connection drops. Lite mode
* keeps the frame small instead:
*
* - `records` is trimmed to the newest few entries (the client still sees
* `hasMore: true`, so it can page back for older ones),
* - projections above {@link LITE_PROJECTION_MAX_BYTES} are dropped, while a
* small keep-list of projections the UI needs to render survives regardless.
*
* Only data sent over the wire is affected; the session store and the agent
* context are untouched.
*/
/**
* Projections a remote client must never miss: they drive the chrome and, more
* importantly, live state the user is acting on (permission switches, pending
* questions, turn status). These bypass the size caps -- dropping one leaves the
* client permanently stale while the Host has already applied the change.
*
* Mirrors the core keys the Host itself keeps in SESSION_PROJECTION_WHITELIST
* (see harness-remote-bridge.ts). Deliberately a copy, not an import: lite-mode
* must not depend on the bridge, and adding a key here is a product decision.
*/
export const LITE_PROJECTION_KEEP_KEYS: ReadonlySet<string> = new Set([
// chrome that frames the conversation
'title',
'sessionTitle',
'conversationTitle',
'label',
'name',
'summary',
'modelSelection',
'model',
'agentPreset',
'imageLimits',
'sessionListMetadata',
// live state: permissions, questions, turn lifecycle
'permissions',
'remoteStatusKnown',
'codexStatus',
'inbox',
'agentTeam',
'turnOutline',
'turn',
'turnState',
'status',
'activeTurnId',
'userQuestions',
])
/** Projections larger than this many bytes are dropped in lite mode. */
export const LITE_PROJECTION_MAX_BYTES = 16 * 1024
/**
* Total budget for one frame's projections. Individual entries can be small and
* still add up (dozens of sessions in one baseline), so the frame is capped.
*/
export const LITE_PROJECTION_BUDGET_BYTES = 256 * 1024
/** How many records the initial history page keeps in lite mode. */
export const LITE_HISTORY_RECORDS = 10
/**
* Process-wide switch, mirroring how the plugin wires other runtime flags: the Host
* and its bridges live in one process, so a single module-level value is enough and
* a toggle applies to the next frame instead of requiring a reconnect.
*/
let enabled = false
/** Whether lite mode is currently on. */
export function isLiteModeEnabled(): boolean {
return enabled
}
/** Flip lite mode for subsequent frames. */
export function setLiteModeEnabled(next: boolean): void {
enabled = next === true
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function sizeOf(value: unknown): number {
try {
return Buffer.byteLength(JSON.stringify(value))
} catch {
return Number.POSITIVE_INFINITY
}
}
/**
* Keep the render-critical projections, then the smallest of the rest while the
* frame stays under {@link LITE_PROJECTION_BUDGET_BYTES}.
*/
export function filterLiteProjections(projections: unknown): unknown {
if (!isRecord(projections)) return projections
const kept: Record<string, unknown> = {}
const candidates: Array<{ key: string, value: unknown, size: number }> = []
let used = 0
for (const [key, value] of Object.entries(projections)) {
const size = sizeOf(value)
if (LITE_PROJECTION_KEEP_KEYS.has(key)) {
kept[key] = value
used += size
continue
}
if (size <= LITE_PROJECTION_MAX_BYTES) candidates.push({ key, value, size })
}
candidates.sort((left, right) => left.size - right.size)
for (const { key, value, size } of candidates) {
if (used + size > LITE_PROJECTION_BUDGET_BYTES) break
kept[key] = value
used += size
}
return kept
}
/**
* Apply lite-mode shaping to one history frame.
* @returns the (possibly rewritten) frame, or `undefined` when the whole frame
* should be skipped because it carries only a dropped projection.
*/
export function applyLiteMode(frame: unknown): unknown {
if (!isRecord(frame) || !isRecord(frame.value)) return frame
const layer = frame.value
if (layer.type === 'baseline' && isRecord(layer.value)) {
const inner = layer.value
if (!isRecord(inner.projections)) return frame
// Shape is `projections[sessionId] = { asOfSeq, values: { key: value } }`
// (see client-core `applyProjectionBaseline`). Filter the inner `values`
// map -- filtering the block itself would treat `asOfSeq`/`values` as
// projection keys and drop the whole block once it grew past the cap,
// which silently loses permissions/questions on first paint.
const projections: Record<string, unknown> = {}
for (const [sessionId, block] of Object.entries(inner.projections)) {
if (!isRecord(block) || !isRecord(block.values)) {
projections[sessionId] = block
continue
}
projections[sessionId] = { ...block, values: filterLiteProjections(block.values) }
}
return { ...frame, value: { ...layer, value: { ...inner, projections } } }
}
if (layer.type === 'snapshot') {
// The snapshot payload is either the layer itself or nested under `value`,
// depending on the backend that produced it.
const nested = isRecord(layer.value)
const inner: Record<string, unknown> = { ...(nested ? (layer.value as Record<string, unknown>) : layer) }
if (Array.isArray(inner.records) && inner.records.length > LITE_HISTORY_RECORDS) {
inner.records = inner.records.slice(-LITE_HISTORY_RECORDS)
inner.hasMore = true
}
if (isRecord(inner.projections) && isRecord(inner.projections.values)) {
inner.projections = { ...inner.projections, values: filterLiteProjections(inner.projections.values) }
}
return { ...frame, value: nested ? { ...layer, value: inner } : inner }
}
if (layer.type === 'projection') {
// A projection frame is a live update of one key. Dropping a state-bearing
// key silently desynchronises the client (permissions applied on the Host
// but never shown, questions never surfaced), so only unknown/cosmetic keys
// are allowed to be dropped for size.
const key = typeof layer.key === 'string' ? layer.key : undefined
if (key !== undefined && LITE_PROJECTION_KEEP_KEYS.has(key)) return frame
if (sizeOf(layer.value) > LITE_PROJECTION_MAX_BYTES) return undefined
}
return frame
}