openmaic-custom/lib/agent/client/serialize-thread.ts
wyuc cc5a6ab152
feat(agent): edit_elements — NL → EditIntent vertical (#895) (#896)
* feat(agent): add edit_elements NL → EditIntent vertical (#895)

Give the editing surface its first real consumer: natural-language
per-element style/geometry edits flow through the same EditIntent
vocabulary as pointer gestures, with an all-or-nothing validation gate
and one undo entry per instruction.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(agent): harden edit_elements against CR findings (#895)

Re-validate intents at apply time (atomic refuse on missing/locked ids),
type-check prop values, require an open edit session for undo, clamp line
stroke width correctly, enforce group cohesion, nest shape text chrome,
and surface refuseReason on the tool card.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(agent): close remaining edit_elements CR residuals (#895)

Feed apply outcomes into next-turn history and post-run chat corrections,
phrase tool success as proposed-not-applied, and tighten gradient/filters/
enums/per-type value validation plus label-less shape text refusal.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(agent): derive edit_elements prop validation from the DSL schema (#895)

Three review rounds each found a hand-written validator disagreeing with
the DSL contract (a gradient pos range pinned at [0,1] against the
percent contract, a textType enum matching the DSL in neither direction,
per-type ownership gaps like vertical-on-shape and color-on-everything).
Replace the class instead of the instances:

- The gate now loads the dsl-generated JSON schema
  (@openmaic/dsl/schema/scene.schema.json) and validates every proposed
  prop value against the target element type's subschema via a compact
  schema-subset checker — per-type ownership, enums, and structured
  shapes (outline/shadow/gradient/filters) come from the single source
  of truth and stay correct as the DSL evolves.
- Explicit policy layers stay on top: the content/identity blocklist
  (schema would allow what policy forbids), geometry clamps (coords,
  min sizes, line stroke width), and a numeric-range overlay for what
  plain number types cannot express — gradient stop pos is a percent in
  [0,100] (the previous [0,1] check refused canonical gradients and the
  unit test pinned the wrong contract), fontSize/lineHeight/radius
  bounds, filter value length, stop-count cap.
- Consequences: color is refused on types that do not render it, with
  prompt guidance steering text color to defaultColor and shape body to
  fill; fill on charts is now allowed (the schema has it; the inventory
  already advertised it); textType accepts the full DSL enum.
- Apply-time revalidation also refuses element-type drift via a
  gate-time targetElementTypes map carried in the tool details.
- Refusal reasons render as visible card text, not only a hover title.
- Test pins added for all of the above plus selection scoping, coord
  bounds, non-finite rotate, and empty batch/props.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(agent): harden the schema-derived gate — fail closed, assert schema source, unify numeric clamping (#895)

- A schema construct the subset checker cannot judge (unresolved $ref,
  malformed anyOf, unsupported keywords) now refuses instead of
  accepting — the gate fails closed on the unknown.
- A module-load assertion verifies the loaded dsl schema carries every
  definition the gate maps and a sane TextType enum, so a stale or
  missing build artifact fails loudly with a rebuild hint instead of
  validating an outdated contract silently.
- Numeric-overshoot convention unified and documented: structural,
  enum, or ownership mismatches refuse (teaching the model the
  contract); numeric overshoot on a valid prop clamps (matching gesture
  behavior) — opacity now clamps like geometry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(agent): localize edit element refusals (#895)

* fix(agent): preserve partial element edit semantics (#895)

* fix(agent): prevent stale element edit application (#895)

* fix(agent): preserve live canvas edit invariants (#895)

* fix(agent): close element style contract gaps (#895)

* fix(agent): reject non-persistent element styles (#895)

* fix(agent): preserve rigid group geometry (#895)

* fix(agent): tolerate decimal group translations (#895)

* fix(agent): constrain line height edits (#895)

* fix(agent): reject stale or shadowed element edits (#895)

* fix(agent): close renderer contract gaps (#895)

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-07-14 18:24:35 +08:00

184 lines
7.3 KiB
TypeScript

/**
* Pure serialize / deserialize for AgentBar conversation persistence.
*
* The rendered thread (`ThreadMessageLike[]`) is projected to a slim, JSON-safe
* shape that keeps exactly what the cards re-render — text + tool-call metadata —
* while dropping the heavy result payloads (full slide elements, base64) that
* would bloat localStorage. Restoring rebuilds `ThreadMessageLike[]` of the same
* shape the ExternalStore renders today. Pure + side-effect-free so it can be
* unit-tested without React.
*/
import type { ThreadMessageLike } from '@assistant-ui/react';
import { editElementsOutcome } from '@/lib/agent/client/edit-elements-result';
export interface SlimToolResult {
content?: { type: 'text'; text: string }[];
details?: {
sceneId?: string;
/** null = nothing applied (failure); {elements} = length-only placeholder. */
content?: { elements: unknown[] } | null;
actions?: { type?: string }[];
/**
* edit_interactive_html success marker: a non-null string when edits applied
* (the heavy ~745 KB payload is replaced by a placeholder), `null` on a
* refusal/unappliable edit. Without this the restored card mistakes a
* successful edit for a failure. `editCount` survives for the count line.
*/
html?: string | null;
editCount?: number;
/**
* edit_elements success marker: a non-empty placeholder array when intents
* applied; `null` on refusal. Drop the heavy props payload — the card only
* needs applied vs refused.
*/
intents?: unknown[] | null;
updateCount?: number;
/** Gate/host refusal reason retained for agent history and diagnostics. */
refuseReason?: string;
};
}
export type SerializedPart =
| { type: 'text'; text: string }
| { type: 'reasoning'; text: string; durationMs?: number }
| {
type: 'tool-call';
toolCallId: string;
toolName: string;
args: Record<string, unknown>;
isError?: boolean;
result?: SlimToolResult;
};
export interface SerializedMessage {
role: 'user' | 'assistant';
id?: string;
content: SerializedPart[];
}
type AnyPart = Record<string, unknown>;
function slimResult(result: unknown): SlimToolResult | undefined {
if (!result || typeof result !== 'object') return undefined;
const r = result as { content?: unknown; details?: unknown };
const out: SlimToolResult = {};
if (Array.isArray(r.content)) {
out.content = r.content
.filter((c): c is { type: 'text'; text: string } => {
const p = c as AnyPart;
return p?.type === 'text' && typeof p.text === 'string';
})
.map((c) => ({ type: 'text', text: c.text }));
}
if (r.details && typeof r.details === 'object') {
const d = r.details as { sceneId?: unknown; content?: unknown; actions?: unknown };
const details: NonNullable<SlimToolResult['details']> = {};
if (typeof d.sceneId === 'string') details.sceneId = d.sceneId;
// Preserve null (failure marker); replace a real content with a length-only
// placeholder so the element-count line survives without the element data.
if (d.content === null) details.content = null;
else if (d.content && typeof d.content === 'object') {
const els = (d.content as { elements?: unknown }).elements;
details.content = { elements: Array.isArray(els) ? els.map(() => ({})) : [] };
}
// edit_interactive_html: keep the success/failure signal, drop the payload.
const dh = (d as { html?: unknown }).html;
if (dh === null) details.html = null;
else if (typeof dh === 'string') details.html = dh.length > 0 ? '…' : '';
const ec = (d as { editCount?: unknown }).editCount;
if (typeof ec === 'number') details.editCount = ec;
// edit_elements: keep applied/refused signal, drop intent prop payloads.
const di = (d as { intents?: unknown }).intents;
const editOutcome = editElementsOutcome({
intents: Array.isArray(di) || di === null ? di : undefined,
});
if (editOutcome === 'refused') details.intents = null;
else if (editOutcome === 'applied') details.intents = (di as unknown[]).map(() => ({}));
const uc = (d as { updateCount?: unknown }).updateCount;
if (typeof uc === 'number') details.updateCount = uc;
const rr = (d as { refuseReason?: unknown }).refuseReason;
if (typeof rr === 'string' && rr.trim()) details.refuseReason = rr.trim();
if (Array.isArray(d.actions)) {
details.actions = d.actions.map((a) => ({
type: (a as AnyPart)?.type as string | undefined,
}));
}
out.details = details;
}
return out;
}
function serializePart(part: unknown, durationMs?: number): SerializedPart | null {
const p = part as AnyPart;
if (p?.type === 'text' && typeof p.text === 'string') {
return { type: 'text', text: p.text };
}
if (p?.type === 'reasoning' && typeof p.text === 'string') {
return {
type: 'reasoning',
text: p.text as string,
...(typeof durationMs === 'number' ? { durationMs } : {}),
};
}
if (p?.type === 'tool-call' && typeof p.toolCallId === 'string') {
return {
type: 'tool-call',
toolCallId: p.toolCallId as string,
toolName: (p.toolName as string) ?? 'tool',
args: (p.args as Record<string, unknown>) ?? {},
...(p.isError ? { isError: true } : {}),
...(p.result !== undefined ? { result: slimResult(p.result) } : {}),
};
}
return null;
}
export function serializeThread(
messages: ThreadMessageLike[],
/** Final reasoning durations: (messageId, reasoningOrdinal) → ms. Lets the
* restored "已思考 N s" survive a refresh (the live timer store is in-memory). */
reasoningDurationMs?: (messageId: string | undefined, ordinal: number) => number | undefined,
): SerializedMessage[] {
const out: SerializedMessage[] = [];
for (const m of messages) {
let content: SerializedPart[] = [];
if (Array.isArray(m.content)) {
let ord = 0;
content = m.content
.map((part) => {
const isReasoning = (part as AnyPart)?.type === 'reasoning';
const dur = isReasoning ? reasoningDurationMs?.(m.id, ord++) : undefined;
return serializePart(part, dur);
})
.filter(Boolean) as SerializedPart[];
} else if (typeof m.content === 'string') {
content = [{ type: 'text', text: m.content } as SerializedPart];
}
if (content.length === 0) continue;
out.push({ role: m.role === 'user' ? 'user' : 'assistant', id: m.id, content });
}
return out;
}
export function deserializeThread(saved: SerializedMessage[] | undefined): ThreadMessageLike[] {
if (!Array.isArray(saved)) return [];
return saved
.filter((m) => m && (m.role === 'user' || m.role === 'assistant') && Array.isArray(m.content))
.map((m) => {
// Reasoning parts carry our `durationMs` (re-seeded into the timer store on
// restore, see use-agent-runtime); assistant-ui only accepts {type, text}.
const content = m.content.map((p) =>
p.type === 'reasoning' ? { type: 'reasoning', text: p.text } : p,
) as ThreadMessageLike['content'];
const base = { role: m.role, id: m.id, content };
// assistant-ui rejects a `status` on user messages ("status is only
// supported for assistant messages") — only assistant turns carry it.
return m.role === 'assistant'
? { ...base, status: { type: 'complete', reason: 'stop' } as ThreadMessageLike['status'] }
: base;
});
}