Skip to content

Sub-agent view

A sub-agent's conversation — its text, its reasoning, its tool calls, its own sub-agents — in a pane, a canvas or a dialog beside the chat, live while it works and saved with the conversation.

  • <aparte-subagent-view>
  • @aparte/plugin-subagents
On this page
Open

In the reply, a sub-agent is one line: its name, its task, what it is doing now. <aparte-subagent-view> shows what it said and did, where you put it: the other pane of a split, a canvas, a dialog. Its text, its reasoning, its tool rows and its own sub-agents as lines, drawn by the same renderers as the reply. It is the same drawing the line opens on with setupSubagents({ details: 'transcript' }).

It keeps nothing of its own. It reads the sub-agent from the chat, live while it works, and from the conversation once it is saved, so a reloaded conversation shows what was saved.

bash
npm install @aparte/plugin-subagents @aparte/core
html
<aparte-split position="50" single>
  <aparte-chat id="chat"></aparte-chat>
  <aparte-subagent-view for="chat"></aparte-subagent-view>
</aparte-split>
ts
import { setupSubagents } from '@aparte/plugin-subagents';

setupSubagents();

const split = document.querySelector('aparte-split')!;
const view = document.querySelector('aparte-subagent-view')!;
document.getElementById('chat')!.addEventListener('aparte-subagent-start', (event) => {
  view.setAttribute('message-id', event.detail.messageId);
  view.setAttribute('agent-id', event.detail.agentId);
  split.removeAttribute('single');
});

Importing the package defines the element. Three attributes say what it shows: for, the id of the chat (<aparte-chat>, its viewport, or any element with getMessages()); message-id, the reply; agent-id, the sub-agent. A chat with no id is handed through the chat property (SubagentViewSource) instead. Until the three name a sub-agent that has started, the element draws nothing and carries data-empty, so a layout can fold the pane against it:

css
aparte-subagent-view[data-empty] {
  display: none;
}

Let the reader pick which sub-agent the view shows: setupSubagents({ open: 'event' }) puts an Open button at the end of each sub-agent’s line, and connectSubagentView does the rest.

html
<aparte-split position="55">
  <aparte-chat id="chat"></aparte-chat>
  <aparte-subagent-view for="chat"></aparte-subagent-view>
</aparte-split>
ts
import { connectSubagentView, setupSubagents } from '@aparte/plugin-subagents';
import type { SubagentViewSplit } from '@aparte/plugin-subagents';

setupSubagents({ open: 'event' });

const disconnect = connectSubagentView({
  chat: document.getElementById('chat')!,
  view: document.querySelector('aparte-subagent-view')!,
  split: document.querySelector<SubagentViewSplit>('aparte-split')!,
});

The split starts with the chat alone. Pressing a line’s Open button (click, Enter or Space) dispatches aparte-subagent-open with messageId and agentId; the wiring points the view at that sub-agent, opens the split’s second pane, and marks the line (data-current on the row, aria-current="true" on its button). It sets closable on the view: the sub-agent’s name and a Close button above its conversation. Close, or Escape inside the view, sends aparte-subagent-view-close; the wiring folds the pane and puts the focus back on the line’s button. On a phone, where the split shows one pane at a time, the same two steps show the view and then the chat again.

Without a split (a tab, a drawer), pass onOpen and onClose instead and show the view yourself: ConnectSubagentViewOptions holds them all (chat, view, split, pane, onOpen, onClose). The sub-agents guide says how the button and a line’s details share the line.

The chat dispatches two events, both bubbling:

  • aparte-subagent-start (AparteSubagentStartEventDetail) when a sub-agent starts, or starts again after a pause: messageId, agentId, name, description (its task), model when its producer names the model it runs on, and toolCallId or parentId for the call or the sub-agent that opened it.
  • aparte-subagent-end (AparteSubagentEndEventDetail) when it ends, or the run ends without it: messageId, agentId and status — done, failed, waiting, stopped, or partial when it was cut short, with reason (its turn limit, a call its run could not make).

Both carry the chat’s id as targetId, so a page with several chats can tell them apart. Together they are enough to keep a list of a reply’s sub-agents and open the one a person picks:

ts
import type { AparteSubagentStatus } from '@aparte/plugin-subagents';

const chat = document.getElementById('chat')!;
const agents = new Map<string, { name?: string; status: AparteSubagentStatus }>();

chat.addEventListener('aparte-subagent-start', (event) => {
  agents.set(event.detail.agentId, { name: event.detail.name, status: 'running' });
});
chat.addEventListener('aparte-subagent-end', (event) => {
  const agent = agents.get(event.detail.agentId);
  if (agent) agent.status = event.detail.status;
});

A sub-agent is saved with the conversation, on the segment that stands for it: the call that opened it, or a subagent segment of the plugin’s own (AparteSubagentSegment, SUBAGENT_SEGMENT_TYPE) for one no call opened. subagentOf(segment) returns it, an AparteSubagent (id, name, description, status, result, error, parentId, and its conversation in segments), and subagentStatus(segment) its state. Both are exported for Node too. The messages come from the message list in plain HTML, and from the chat’s messages in a framework:

ts
import type { AparteChatViewport } from '@aparte/core';
import { subagentOf, subagentStatus } from '@aparte/plugin-subagents';

const viewport = document.querySelector<AparteChatViewport>('aparte-chat-viewport')!;

for (const message of viewport.getMessages()) {
  for (const segment of message.segments ?? []) {
    const agent = subagentOf(segment);
    if (agent) console.info(agent.name, subagentStatus(segment), agent.result ?? agent.error ?? '');
  }
}

subagentStatus reads stopped for a sub-agent a reload or a Stop left unfinished, where the saved status still says how it was when the page closed. The sub-agent’s conversation is never part of what the model reads.

The element is a plain tag in every framework, and the plugin’s events reach the chat’s root like any other, so each wrapper hears aparte-subagent-start and the rest by the event’s own name, as the tabs above do (useAparteEvent, @aparte-…, onaparte-…, (aparte-…)). A Vue or Svelte template accepts the tag as it is; Angular needs CUSTOM_ELEMENTS_SCHEMA on the component that hosts it, and [attr.message-id] to bind an attribute. In a React .tsx file the tag is a compile error until you declare it once, which the sub-agents guide shows. The class is exported as AparteSubagentView, for the type of a ref.

The view is light DOM, like the chat: its rows are the chat’s, and they take your theme as they do in the reply. --aparte-subagent-indent is the space between the rule down its leading edge and the conversation.

<aparte-subagent-view> · class AparteSubagentView

Attributes

AttributeDescription
forThe id of the chat: <aparte-chat>, its viewport, or any element with getMessages(). Or set the chat property.
message-idThe reply the sub-agent worked for (aparte-subagent-start’s messageId).
agent-idWhich sub-agent (aparte-subagent-start’s agentId).
closableA pane of its own: the sub-agent’s name and a Close button above its conversation, and Escape inside it closes too. Both only say so (aparte-subagent-view-close): the app, or connectSubagentView, folds the pane.
data-emptyWritten BY the element while there is nothing to show (an unknown sub-agent, or one not started yet): it then draws nothing. Read-only; style or fold your layout against it.
data-inlineWritten BY the element when it is a line’s detail rather than a view of its own. Read-only.

Properties

PropertyTypeDescription
chatSubagentViewSource | nullThe chat, when it has no id for the for attribute: an element, or anything with getMessages().

Methods

MethodDescription
focusTitle(): voidPut the focus on the sub-agent’s name, in a closable view: where a pane that just opened starts.
refresh(): voidRead the sub-agent again and draw it: what the element does on every change it hears.

Events

EventTypeDescription
aparte-subagent-view-closeCustomEventThe Close button, or Escape inside a closable view. The view does not hide itself: the app owns the layout. Bubbles.
aparte-link-clickCustomEvent<AparteLinkClickEventDetail>A link the sub-agent wrote is about to be followed. Sent on the chat (for or chat; the view itself when it names none), as a message sends its own, so the listener that routes a reply’s links routes these. Cancelable: preventDefault() keeps the browser from navigating. Under a line, inside the reply, the message sends it.

CSS variables

VariableDefaultDescription
--aparte-subagent-indentvar(--aparte-space-6)The space between the rule down the leading edge and the conversation, in a standalone view.
  • Sub-agents — the line in the reply, and the three ways sub-agents reach the page.
  • Split — the two panes this view usually sits in.
  • Tool — the row a sub-agent’s line is drawn on.