Allow commands to provide presentCall and presentResult views

[antst]

Problem

At commit 49a606bc, CommandDefinition exposes only name, description, input, recordInput, and handler (packages/interaction/commands/src/index.ts:55-70). Its durable result is limited to outcome, flat text, and an optional source-event reference (packages/interaction/commands/src/types.ts:28-35).

Tools already have optional, pure, replay-safe presentCall and presentResult hooks (packages/core/tools/src/index.ts:263-295). Those hooks return provider-neutral call/result views, retain a generic fallback when absent, and can render durable structured meta in every DSH UI.

Plugin use case

A workspace-restore plugin exposes /roller-restore <turn-end-seq>. Its result naturally contains separate lists of files written, files deleted, and failures with an operation and message. Today the command must flatten that report into headings and bullet text in command/done, so every UI shows a text blob. A tool carrying the same data can present it as a structured card.

Proposed API

Could CommandDefinition gain optional presentCall(rawInput) and presentResult(rawInput, result) hooks with the same view types, generic fallbacks, and pure/replay-safe contract as tool presenters? For presentResult, the durable command result would also need optional JSON-safe meta (or an equivalent structured payload) mirroring ToolResult.meta; otherwise a presenter must parse display text. Existing commands could omit all of these fields and retain their current rendering.

This is only a presentation extension: it would not change command dispatch, handler semantics, model visibility, or the existing text fallback.

[argszero]

Thanks for the detailed proposal — I verified every cited anchor against 49a606bc (now also in a local checkout) and the gap is real. One asymmetry in your mental model changes the shape of the fix, plus there is an in-tree precedent worth weighing first.

What actually makes tool cards durable is meta, not the presenters

ToolDefinition.presentCall/presentResult are pure mapping declarations onto the shared card vocabulary (ToolCallView/ToolResultView, core/tools/src/presentation.ts). The durable structured surface is the JSON-safe meta persisted verbatim on tool/result — the payload JSDoc (core/session/src/types.ts, 'tool/result') is explicit that meta "MUST be JSON-serializable: Session.append runtime-validates all event data with isJsonValue", and that the producing tool "reads it back in presentResult". The derived view is never persisted.

That division of labor is not incidental: command/tool definitions live in optional plugins, and a later replay in a profile that does not mount the defining plugin has no presenter code at all — only the durable event. The first-party conversation rows (e.g. client/ui-tool row models, which consume the frozen call slice: args + content + meta) do not execute the hooks either; I could not find an in-tree runtime caller of presentCall/presentResult under packages/ — they are unit-tested reference mappings over the vocabulary. So "renders a structured card in every DSH UI" is delivered by meta + per-UI row implementations, with presenters as the pure recipe.

Implication for commands

The load-bearing change is therefore not the two hooks but the durable structured payload:

• widen 'command/done' with optional meta?: JsonValue (and CommandResult's success variant), mirroring tool/result.meta. The existing append validation covers JSON-safety for free (interaction/commands/src/index.ts appendLifecycle routes every settlement through session.append), and known-event-types.ts needs no change — the type stays 'command/done'. Old sessions have no meta (text fallback, exactly today's rendering); old readers ignore the unknown field. This is the backward-compatible half.
• presentResult(rawInput, result) as an optional pure mapping over the widened result. It cannot call back into the plugin and must be derivable from persisted fields only — same replay constraint as tools, and the reason the meta widening is the prerequisite, not the presenter.
• I would defer presentCall. Tools receive parsed, schema-validated args; commands receive rawInput verbatim text (parseCommand only splits name from the rest — there is no input grammar). A call-time hook would have to re-parse the command's own free-form input, which is exactly the code sourceEventSeq exists to avoid duplicating in the log. The call-time presentation of a command is its own command line.

Blast radius if pursued: interaction/commands/src/types.ts (result + event map), index.ts (definition type + normalize), client/ui-conversation CommandNode / client/ui-chat conversation-nodes/command.ts (commandFromDone folds meta onto outcome), plus snapshot fixtures. Modest and mostly additive.

Precedent inside the commands design: /compact

CommandResult.success.sourceEventSeq is documented as "Earlier authoritative domain event that owns a richer presentation" — and /compact is the shipped example: its structured outcome is a set of its own domain events (compaction/* carrying sourceCommandId), and the ui-chat command conversation node folds that evidence into the command card ("manual-compaction" node). Your roller-restore report (written/deleted/failed lists) is exactly this shape: the plugin emits its own domain event carrying the lists and points at it from command/done.

That route needs no host/CommandDefinition change — but for a plugin-authored event type it is currently blocked by the read-side gate your other proposal targets: validateStoredEvents (session-persistence/storage-contract.ts) refuses out-of-tree event types unless marked ignorable, and there is no append option that lets a plugin pass that marker today. So #5462 and #5463 interlock: if #5463 lands first, you can ship the structured card today as a plugin + per-plugin UI extension (the same keyed-toolview pattern ui-cordis uses), with zero host changes. If upstream prefers to keep the out-of-tree event surface minimal, the command/done meta widening + optional presentResult is the generic route that benefits every command, and the two compose: meta on a known type is exactly how you persist structured data without new event types.

Bottom line: direction is right and symmetric; I'd split it into (a) durable JSON-safe meta on command/done first (small, generic, backward-compatible — this is the part that actually renders in every UI), (b) optional pure presentResult over the widened result, (c) drop or defer presentCall until commands have an input grammar worth presenting. And worth stating in the API docs that, like tools, the presenter is a recipe over persisted fields — durability lives in meta.