ds-harness-remote-fast/apps/android/src/state/ui-artifacts.ts

314 lines
13 KiB
TypeScript

/**
* Project durable DSH tool events into the *latest successful* portable UI.
* This is deliberately separate from ToolActivity text truncation and from
* Remote's authenticated transport. Invalid, incomplete, failed and stale
* updates never replace a previously rendered snapshot.
*/
import type { ChatItem, ToolActivity } from '../types'
import type { ChatSection } from './message-helpers'
export interface UiArtifact {
kind: 'declarative' | 'widget' | 'composition'
hostId: string
sessionId: string
uiId: string
version: number
turn?: string
/** Turn that most recently patched the UI (the card stays in its original Turn). */
updatedTurn?: string
title?: string
definition: Record<string, unknown>
policy?: Record<string, unknown>
originSeq: number
}
const UI_TOOLS = new Set(['ui_render', 'ui_patch', 'ui_render_widget', 'ui_compose'])
const MAX_UI_CHARS = 480_000
const BLOCK_ID = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/
const record = (x: unknown): x is Record<string, unknown> =>
typeof x === 'object' && x !== null && !Array.isArray(x)
const nonempty = (x: unknown): x is string => typeof x === 'string' && x.length > 0
const version = (x: unknown): x is number => Number.isSafeInteger(x) && (x as number) >= 1
function splitComposeUiId(uiId: string): [string, string] | undefined {
const at = uiId.indexOf('#')
return at > 0 && at < uiId.length - 1 ? [uiId.slice(0, at), uiId.slice(at + 1)] : undefined
}
function safeComposition(x: Record<string, unknown>): boolean {
if (!Array.isArray(x.blocks) || x.blocks.length === 0 || x.blocks.length > 24) return false
const ids = new Set<string>()
for (const block of x.blocks) {
if (!record(block) || !nonempty(block.id) || !BLOCK_ID.test(block.id) || ids.has(block.id)) return false
ids.add(block.id)
if (block.type === 'markdown') {
if (typeof block.text !== 'string' || block.text.trim().length === 0 || block.text.length > 60_000) return false
} else if (block.type === 'catalog') {
if (!safeTree(block as Record<string, unknown>)) return false
} else if (block.type === 'widget') {
if (!nonempty(block.html)) return false
} else {
return false
}
}
return true
}
function safeArgs(value: unknown): Record<string, unknown> | undefined {
if (typeof value !== 'string' || value.length > MAX_UI_CHARS) return undefined
try { const x: unknown = JSON.parse(value); return record(x) ? x : undefined } catch { return undefined }
}
function safeTree(x: Record<string, unknown>): boolean {
if (!nonempty(x.root) || !Array.isArray(x.components) || x.components.length > 2000) return false
const ids = new Set<string>()
for (const node of x.components) {
if (!record(node) || !nonempty(node.id) || !nonempty(node.type) || ids.has(node.id)) return false
ids.add(node.id)
}
return ids.has(x.root)
}
function safePolicy(x: unknown): Record<string, unknown> | undefined {
if (!record(x)) return undefined
// Do not accept arbitrary keys / out-of-range strings from Host metadata.
const result: Record<string, unknown> = {}
if (typeof x.allowNetwork === 'boolean') result.allowNetwork = x.allowNetwork
if (typeof x.maxHeight === 'number' && x.maxHeight >= 100 && x.maxHeight <= 4000) result.maxHeight = x.maxHeight
if (typeof x.sendPromptMaxChars === 'number' && x.sendPromptMaxChars > 0 && x.sendPromptMaxChars <= 4000) result.sendPromptMaxChars = x.sendPromptMaxChars
for (const key of ['cdn', 'openLinkOrigins']) {
if (Array.isArray(x[key]) && x[key].length <= 30 && x[key].every(y => typeof y === 'string' && y.length < 240)) {
result[key] = x[key]
}
}
return result
}
function toolSeq(tool: ToolActivity): number {
return tool.nativeRevisionSeq ?? tool.nativeSeq ?? tool.nativeOrderSeq ?? tool.createdAt ?? 0
}
/** Read-only and deterministic: safe to recalculate after history paging or reconnect. */
export function projectUiArtifacts(items: readonly ChatItem[], hostId: string, sessionId: string): UiArtifact[] {
if (!hostId || !sessionId) return []
const latest = new Map<string, UiArtifact>()
const blockVersions = new Map<string, number>()
const isUiTool = (item: ChatItem): item is ToolActivity =>
item.kind === 'tool'
&& item.sessionId === sessionId
&& item.state === 'finished'
&& UI_TOOLS.has(item.toolKey ?? '')
&& item.uiResultMeta !== undefined
// Stably sort tools by authoritative event coordinate, preserving encounter order on collision.
const tools = items
.filter(isUiTool)
.map((tool, idx) => ({ tool, idx }))
.sort((a, b) => (toolSeq(a.tool) - toolSeq(b.tool)) || (a.idx - b.idx))
.map(({ tool }) => tool)
for (const tool of tools) {
const meta = tool.uiResultMeta
if (!record(meta) || meta.ok !== true) continue
const args = safeArgs(tool.arguments)
if (!args) continue
const name = tool.toolKey
const seq = toolSeq(tool)
const policy = safePolicy(meta.policy)
if (name === 'ui_render' && safeTree(args)) {
const uiId = tool.id
const existing = latest.get(uiId)
if (existing) {
// If an artifact was already recovered from a later patch (e.g. out of order
// or later event seen first), do not regress its version/definition, but
// anchor the turn and originSeq to the authoritative original ui_render!
if (seq < existing.originSeq || existing.turn === undefined) {
latest.set(uiId, {
...existing,
turn: tool.turn ?? existing.turn,
originSeq: Math.min(seq, existing.originSeq),
})
}
continue
}
latest.set(uiId, {
kind: 'declarative', hostId, sessionId, uiId, version: 1,
definition: args, title: typeof args.title === 'string' ? args.title : undefined,
turn: tool.turn, policy, originSeq: seq,
})
} else if (name === 'ui_compose' && safeComposition(args)) {
const uiId = tool.id
const existing = latest.get(uiId)
if (existing) {
if (seq < existing.originSeq || existing.turn === undefined) {
latest.set(uiId, {
...existing,
turn: tool.turn ?? existing.turn,
originSeq: Math.min(seq, existing.originSeq),
})
}
continue
}
latest.set(uiId, {
kind: 'composition', hostId, sessionId, uiId, version: 1,
definition: args, title: typeof args.title === 'string' ? args.title : undefined,
turn: tool.turn, policy, originSeq: seq,
})
for (const block of (args.blocks as Record<string, unknown>[])) {
if (block.type === 'catalog' && typeof block.id === 'string') {
blockVersions.set(`${uiId}#${block.id}`, 1)
}
}
} else if (name === 'ui_render_widget' && nonempty(args.html)) {
const uiId = tool.id
const existing = latest.get(uiId)
if (existing) {
if (seq < existing.originSeq || existing.turn === undefined) {
latest.set(uiId, {
...existing,
turn: tool.turn ?? existing.turn,
originSeq: Math.min(seq, existing.originSeq),
})
}
continue
}
latest.set(uiId, {
kind: 'widget', hostId, sessionId, uiId, version: 1,
definition: args, title: typeof args.title === 'string' ? args.title : undefined,
turn: tool.turn, policy, originSeq: seq,
})
} else if (name === 'ui_patch' && nonempty(args.uiId) && version(args.baseVersion)) {
const targetUiId = args.uiId
const snapshot = meta.ui
// Authoritative Host snapshot contract:
// Host returns a full valid tree snapshot with snapshot.version === args.baseVersion + 1.
if (!record(snapshot) || snapshot.uiId !== targetUiId
|| !version(snapshot.version)
|| snapshot.version !== args.baseVersion + 1
|| !safeTree(snapshot)) {
continue
}
const parts = splitComposeUiId(targetUiId)
if (parts) {
const [compositionId, blockId] = parts
const old = latest.get(compositionId)
if (old !== undefined && old.kind === 'composition') {
const currentBlockVersion = blockVersions.get(targetUiId) ?? 1
if (snapshot.version <= currentBlockVersion || args.baseVersion < currentBlockVersion) {
continue
}
const blocks = Array.isArray(old.definition.blocks) ? old.definition.blocks : []
const blockIndex = blocks.findIndex(b => record(b) && b.type === 'catalog' && b.id === blockId)
if (blockIndex === -1) continue
const oldBlock = blocks[blockIndex] as Record<string, unknown>
const updatedBlock = {
...oldBlock,
...(typeof snapshot.title === 'string' ? { title: snapshot.title } : {}),
root: snapshot.root,
components: snapshot.components,
}
const nextBlocks = [...blocks]
nextBlocks[blockIndex] = updatedBlock
blockVersions.set(targetUiId, snapshot.version)
latest.set(compositionId, {
...old,
version: old.version + 1,
definition: {
...old.definition,
blocks: nextBlocks,
},
title: typeof old.definition.title === 'string' ? old.definition.title : old.title,
policy: policy ?? old.policy,
turn: old.turn,
updatedTurn: tool.turn ?? old.updatedTurn,
originSeq: old.originSeq,
})
}
continue
}
const old = latest.get(targetUiId)
if (old !== undefined) {
// Must match declarative kind
if (old.kind !== 'declarative') continue
// Stale or duplicate patch: an older baseVersion or older/equal snapshot version
// must NEVER regress or overwrite the current state.
if (snapshot.version <= old.version || args.baseVersion < old.version) {
continue
}
// Advance to the verified snapshot.
// If args.baseVersion === old.version, this is normal contiguous patching (v1 -> v2).
// If args.baseVersion > old.version, an intermediate patch was omitted in history;
// Host has authorized and executed the patch up to snapshot.version, so advance safely.
latest.set(targetUiId, {
...old,
version: snapshot.version,
definition: snapshot,
title: typeof snapshot.title === 'string' ? snapshot.title : old.title,
policy: policy ?? old.policy,
turn: old.turn,
updatedTurn: tool.turn ?? old.updatedTurn,
originSeq: old.originSeq,
})
} else {
// History truncation / paging recovery:
// Original ui_render (and any earlier patches) were paged out of the active window.
// The Host's verified complete snapshot restores the artifact.
latest.set(targetUiId, {
kind: 'declarative',
hostId,
sessionId,
uiId: targetUiId,
version: snapshot.version,
definition: snapshot,
title: typeof snapshot.title === 'string' ? snapshot.title : undefined,
turn: tool.turn,
updatedTurn: tool.turn,
policy,
originSeq: seq,
})
}
}
}
return [...latest.values()].sort((a, b) => a.originSeq - b.originSeq)
}
/** A split Turn must still have exactly one owner for each actionable card. */
export function placeUiArtifacts(artifacts: readonly UiArtifact[], sections: readonly ChatSection[]) {
const byTurn = new Map<string, Extract<ChatSection, { kind: 'process' }>[]>()
for (const section of sections) {
if (section.kind !== 'process') continue
const siblings = byTurn.get(section.turn) ?? []
siblings.push(section)
byTurn.set(section.turn, siblings)
}
const placed = new Map<string, { cards: UiArtifact[]; pointers: UiArtifact[] }>()
const bucket = (key: string) => {
let value = placed.get(key)
if (!value) { value = { cards: [], pointers: [] }; placed.set(key, value) }
return value
}
for (const ui of artifacts) {
const candidates = ui.turn === undefined ? [] : byTurn.get(ui.turn) ?? []
// Anchor to the actual creating tool; for paged recovery use the first
// verified patch's coordinate. A later segment of the Turn gets no copy.
const owner = candidates.find(section => section.items.some(item => item.kind === 'tool' && item.id === ui.uiId))
?? candidates.find(section => section.items.some(item => item.kind === 'tool' && toolSeq(item) === ui.originSeq))
?? candidates[0]
if (owner) bucket(owner.key).cards.push(ui)
if (ui.updatedTurn !== undefined && ui.updatedTurn !== ui.turn) {
const update = byTurn.get(ui.updatedTurn)?.at(-1)
if (update) bucket(update.key).pointers.push(ui)
}
}
return placed
}