AkurAI-RustAgent agent OS UI

Status: ⬜ planned integration contract.

The AkurAI-RustAgent web surface must be a tenant-scoped agent operating system, not a plain chat box. It should preserve the same interaction semantics an operator gets from a mature agent runtime: channels, tool calls, confirmations, questions, edit previews, artifacts, durable work queues, and receipts back to the agent.

The framework already ships the native-ESM assistant-ui + tool-ui substrate needed for that UI. The remaining work is an adapter that turns RustAgent/Hermes-style events into framework component payloads and sends user decisions back as receipts.

Required surfaces

• Workspace shell: tenant-aware sidebar for threads, projects, notes, memory, passvault, schedules, kanban, and curator jobs.
• Run timeline: ordered channel stream for user messages, assistant responses, reasoning, tool calls, command output, errors, and final answers.
• Context pane: relevant notes, memory entries, files, artifacts, environment, and active task state for the selected run.
• Approval lane: confirmations and sensitive actions stay visible until the user approves, rejects, edits, or cancels.
• Artifact/preview pane: code diffs, rendered files, terminal output, tables, charts, media, and generated previews.

Channel contract

The adapter should keep channel identity explicit. A run event should include:

{
  "run_id": "run_123",
  "sequence": 42,
  "channel": "commentary",
  "kind": "tool_call",
  "tool_call_id": "call_abc",
  "payload": {}
}

Recommended channels:

• analysis: collapsible reasoning block. Hidden by default unless the run policy permits display.
• commentary: main visible agent stream, including progress updates and tool-call narration.
• final: pinned final answer for the run.
• tool_call: tool card with arguments, status, timing, and output placeholder.
• tool_result: result card matched to the originating tool call.
• approval: blocking approval card with approve/reject receipts.
• question: blocking input card: option list, question flow, text field, slider, or preferences panel.
• edit: code diff or file preview with accept/reject/apply receipts.
• artifact: rendered artifact, media, table, chart, or link preview.
• system: small timeline note for policy, environment, or routing metadata.
• error: error card with retry/recover affordances where available.

Hermes-style asks

The UI must treat agent asks as blocking structured requests, not prose. At minimum, support these request/response pairs:

• clarify.request: payload { question, choices?, request_id }; respond with clarify.respond and { request_id, answer }.
• approval.request: payload includes command, description, optional pattern keys, optional permanent approval flag, and optional request id; respond with approval.respond and { session_id, choice, all? }.
• sudo.request: payload { prompt?, request_id }; respond with sudo.respond and { request_id, password }.
• secret.request: payload { prompt, env_var, metadata?, request_id }; respond with secret.respond and { request_id, value }.
• terminal.read.request: payload { prompt?, request_id }; respond with terminal.read.respond and { request_id, text }.

Approval choices should keep Hermes semantics: once, session, always, or deny. If allow_permanent is false, do not show or persist always. Clarification choices should stay short and bounded; open-ended clarification is represented by omitting choices.

Component mapping

Use the shipped tool-ui components before creating new UI:

• Multi-step plan or kanban progress: plan, progress_tracker.
• approval.request for deploy, delete, edit, or external action: approval_card or genericApprovalComponent.
• clarify.request with choices: option_list.
• clarify.request without choices or terminal.read.request: question_flow with a text question.
• Several questions before proceeding: question_flow.
• Preferences or run settings: preferences_panel.
• Numeric parameter: parameter_slider.
• sudo.request: dedicated password prompt with no echo and no persistent value.
• secret.request: dedicated secret prompt with env var and redacted metadata.
• Command/tool output: terminal, code_block.
• tool.complete.inline_diff, rollback diffs, or file edits: code_diff.
• Structured records: data_table, chart, stats_display.
• Generated or discovered media: image, image_gallery, audio, video.
• Link/citation context: link_preview, citation.

If no component matches, the runtime must fall back to readable JSON rather than dropping the event.

Receipts back to the agent

Interactive components must reply through the existing receipt shape:

{
  "channel": "tool-result",
  "receipt": {
    "toolCallId": "call_abc",
    "component": "approval_card",
    "action": "approve",
    "data": { "approved": true },
    "ts": 1782487573184
  }
}

For RustAgent, that receipt should be forwarded to the run/gateway as the answer to the pending agent ask. The UI should not convert approvals into plain chat text; it must preserve the target toolCallId, selected action, and typed data.

The receipt bridge maps component receipts to the matching response method:

• approval_card approved once/session/always/deny: approval.respond.
• option_list or question_flow for clarification: clarify.respond.
• Secret prompt value: secret.respond.
• Sudo prompt value: sudo.respond.
• Terminal read text: terminal.read.respond.
• Edit preview accept/reject: edit-specific response or tool-result receipt keyed by toolCallId.

Implementation slices

1. Event adapter: normalize RustAgent/Hermes gateway events into the channel

contract above, preserving sequence, run id, tool call id, and tenant id.

1. Workspace shell: compose ThreadList, branch picker, reasoning, suggestions,

tool-call runtime, and the artifact components into an agent-OS layout.

1. Receipt bridge: route toolui:receipt and component confirmations back to

RustAgent as structured answers, then update the pending timeline item.

1. Durable state panes: wire memory, notes, passvault, kanban, cron, and curator

records as first-class sidebar/context objects.

1. Hermes parity checks: build fixtures for confirmations, questions, tool

calls, edits, artifacts, channel ordering, and recovery from disconnected runs.