@aparte/plugin-subagents 0.0.0-stage → 1.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aparté
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @aparte/plugin-subagents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sub-agents for [aparté](https://github.com/apartejs/aparte): one line per sub-agent — its name and its task,
+and under them what it is doing now, then what it did ("3 tools · 12 s") — with its conversation kept out of
+the reply and out of what the model reads.
+
+```bash
+npm install @aparte/plugin-subagents @aparte/core
+```
+
+```ts
+import { aparteGlobalConfig } from '@aparte/core';
+import { setupSubagents } from '@aparte/plugin-subagents';
+
+setupSubagents();  // the line alone, on the global config
+
+// Or tuned (the config last, like every setup*; the global one by default):
+const stop = setupSubagents({ activity: true, counts: false }, aparteGlobalConfig);
+stop();            // takes it off again
+```
+
+**Where the line comes from.** A sub-agent opened by a tool call takes that call's row: everything you
+declare for the tool with `registerToolDisplay` (`label`, `icon`, `quiet`, `hidden`, `details`) still
+applies, and wins over what the plugin says. A sub-agent no call opened — or a second one opened by the
+same call — gets a `subagent` segment (`SUBAGENT_SEGMENT_TYPE`, typed `AparteSubagentSegment`) drawn as the
+same row, named by the agent: `registerToolDisplay('<agent name>', …)` reaches it.
+
+**Options** (`SubagentsOptions`): `activity` gives the line a second line from the sub-agent's start to its
+end — *Starting…*, its latest tool call, then what it did — so the row keeps its height (default `true`);
+`counts` says what it did, its tool calls and how long it worked, once it is over (default `true`); `details` is what is behind
+the line — `false` by default (no disclosure), `'transcript'` for the sub-agent's conversation, or a
+function that returns what to show under it.
+
+**Its conversation under the line.** With `details: 'transcript'`, each line opens on what the sub-agent
+said and did — the task it was given, its text, its reasoning, its own tool rows, and its own sub-agents
+as lines — drawn by the same renderers as the reply and kept up to date while it works. The line stays
+closed until the reader opens it:
+
+```ts
+setupSubagents({ details: 'transcript' });
+```
+
+`subagentTranscript` is that detail as a function, so you can put it under one tool's line only, or open
+it by default:
+
+```ts
+import { aparteGlobalConfig } from '@aparte/core';
+import { setupSubagents, subagentTranscript } from '@aparte/plugin-subagents';
+
+setupSubagents();
+aparteGlobalConfig.registerToolDisplay('task', { details: subagentTranscript, open: true });
+```
+
+**Its conversation anywhere else.** `<aparte-subagent-view>` (`AparteSubagentView`) shows the same
+conversation where you place it — a pane of `<aparte-split>`, a canvas, a dialog. Name the chat with `for`
+(or set the `chat` property, typed `SubagentViewSource`), the reply with `message-id`, the sub-agent with
+`agent-id`. It follows the sub-agent live, shows the saved conversation after a reload, and draws nothing
+(`data-empty`) until there is something to show. `aparte-subagent-start` gives the three ids:
+
+```html
+<aparte-split primary="start" position="55" single>
+  <aparte-chat id="chat">…</aparte-chat>
+  <aparte-subagent-view for="chat"></aparte-subagent-view>
+</aparte-split>
+<script type="module">
+  import { setupSubagents } from '@aparte/plugin-subagents';
+
+  setupSubagents();
+  const view = document.querySelector('aparte-subagent-view');
+  document.getElementById('chat').addEventListener('aparte-subagent-start', (e) => {
+    view.setAttribute('message-id', e.detail.messageId);
+    view.setAttribute('agent-id', e.detail.agentId);
+  });
+</script>
+```
+
+**Reading it back.** The sub-agent (`AparteSubagent`: `id`, `name`, `description`, `status`, `result`,
+`error`, `parentId`, `segments`) is saved on the segment that stands for it. `subagentOf(segment)` returns
+it; `subagentStatus(segment)` returns its state (`AparteSubagentStatus`: `running`, `waiting`, `done`,
+`failed`, `stopped`), and reads `stopped` for a sub-agent a reload or a Stop left unfinished.
+
+**Events.** The chat element hears `aparte-subagent-start` (`AparteSubagentStartEventDetail`: `messageId`,
+`agentId`, `name`, `description`, `toolCallId`, `parentId`) and `aparte-subagent-end`
+(`AparteSubagentEndEventDetail`: `messageId`, `agentId`, `status`), so an app can list the sub-agents of a
+reply wherever it likes.
+
+Without the plugin, a sub-agent's text and tool calls are still kept out of the reply: the call that opened
+it shows as an ordinary tool row. `@aparte/core` is the only **peer dependency**.
+
+> ESM-only. Part of the aparté monorepo.

package/dist/aparte-subagent-view.d.ts

@@ -0,0 +1,150 @@
+/**
+ * `<aparte-subagent-view>` — a sub-agent's conversation, wherever the app puts it.
+ *
+ * The line in the reply says what a sub-agent is doing; this element shows what it said and
+ * did — its text, its reasoning, its tool rows, its own sub-agents as lines — drawn by the
+ * same renderers as the reply. It is also what `subagentTranscript` puts under the line, so
+ * there is one drawing of a conversation, not two.
+ *
+ * Standalone, it reads the sub-agent from the chat: live, from each write of the plugin's
+ * lane (once a frame while it streams); saved, from the segment that stands for it in the
+ * reply, searched through the lanes of its parents too. A saved conversation is adopted
+ * before it is drawn (`createSegmentList`), so nothing in it reads as still arriving.
+ *
+ * Light DOM, like core. It writes its own two parts as children and decides nothing about
+ * the layout.
+ */
+import { type AparteConfig, type AparteMessage, type AparteSegment } from '@aparte/core';
+/** Where the view reads the conversation: a chat element, its viewport, or anything with `getMessages()`. */
+export type SubagentViewSource = (Element | object) & {
+    getMessages?: () => AparteMessage[];
+    getMessage?: (id: string) => AparteMessage | undefined;
+};
+/**
+ * The conversation of the sub-agent `anchor` stands for, as it is drawn: as it is while the
+ * sub-agent works, adopted once it is over (a reload, a Stop, its end) — every text settled,
+ * every call still open read as stopped.
+ */
+export declare function laneOf(anchor: AparteSegment): {
+    segments: readonly AparteSegment[];
+    live: boolean;
+};
+/** The segment that stands for `agentId` among `segments`, or in the lanes of the sub-agents there. */
+export declare function findSubagent(segments: readonly AparteSegment[], agentId: string, depth?: number): AparteSegment | undefined;
+/** Importable where there is no DOM: the class then extends nothing and is never defined. */
+declare const ElementBase: typeof HTMLElement;
+/**
+ * A sub-agent's conversation — its text, its reasoning, its tool rows, its own sub-agents as
+ * lines — where the app places it: a canvas, a pane of `<aparte-split>`, a dialog. It follows
+ * the sub-agent live while it works and shows the saved conversation after a reload. Name the
+ * chat with `for` (or the `chat` property), the reply with `message-id`, the sub-agent with
+ * `agent-id`: `aparte-subagent-start` gives all three as its sub-agents start.
+ *
+ * It is the same element `subagentTranscript` puts under a sub-agent's line.
+ *
+ * @element aparte-subagent-view
+ *
+ * @attr {string} for - The `id` of the chat: `<aparte-chat>`, its viewport, or any element with `getMessages()`. Or set the `chat` property.
+ * @attr {string} message-id - The reply the sub-agent worked for (`aparte-subagent-start`'s `messageId`).
+ * @attr {string} agent-id - Which sub-agent (`aparte-subagent-start`'s `agentId`).
+ * @attr {boolean} data-empty - Written 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.
+ * @attr {boolean} data-inline - Written BY the element when it is a line's detail rather than a view of its own. Read-only.
+ * @attr {boolean} closable - A 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.
+ *
+ * @fires {CustomEvent} aparte-subagent-view-close - The Close button, or Escape inside a `closable` view. The view does not hide itself: the app owns the layout. Bubbles.
+ *
+ * @cssprop [--aparte-subagent-indent=var(--aparte-space-6)] - The space between the rule down the leading edge and the conversation, in a standalone view.
+ *
+ * @example The chat in one pane, a sub-agent's conversation in the other
+ * ```html
+ * <aparte-split primary="start" position="55" single>
+ *   <aparte-chat id="chat">…</aparte-chat>
+ *   <aparte-subagent-view for="chat"></aparte-subagent-view>
+ * </aparte-split>
+ * <script type="module">
+ *   import { setupSubagents } from '@aparte/plugin-subagents';
+ *
+ *   setupSubagents();
+ *   const view = document.querySelector('aparte-subagent-view');
+ *   // Show the latest sub-agent to start, as it works.
+ *   document.getElementById('chat').addEventListener('aparte-subagent-start', (e) => {
+ *     view.setAttribute('message-id', e.detail.messageId);
+ *     view.setAttribute('agent-id', e.detail.agentId);
+ *   });
+ * </script>
+ * ```
+ */
+export declare class AparteSubagentView extends ElementBase {
+    static get observedAttributes(): string[];
+    private _chat;
+    private _task;
+    /** A closable view's head: the sub-agent's name and Close. */
+    private _head;
+    private _name;
+    private _close;
+    private _drawing;
+    /** The config the rows were drawn with, and the segment they were drawn from. */
+    private _config;
+    private _anchor;
+    private _listening;
+    private _stopConfig;
+    private _stopWatching;
+    private _stopRenderers;
+    private _queued;
+    private _releaseQueued;
+    private _warned;
+    private readonly _onConversation;
+    private readonly _onKeydown;
+    /** A renderer registered or taken off on the config the rows were drawn with: the rows it changes are drawn again. */
+    private readonly _onRenderers;
+    private readonly _onWrite;
+    /** The chat, when it has no `id` for the `for` attribute: an element, or anything with `getMessages()`. */
+    get chat(): SubagentViewSource | null;
+    set chat(value: SubagentViewSource | null);
+    /** Put the focus on the sub-agent's name, in a `closable` view: where a pane that just opened starts. */
+    focusTitle(): void;
+    /** Read the sub-agent again and draw it: what the element does on every change it hears. */
+    refresh(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, previous: string | null, value: string | null): void;
+    private _source;
+    private _sourceConfig;
+    /** A write from this view's chat: the run's target is the chat, inside it, or named by its id. */
+    private _matches;
+    /**
+     * The segment that stands for the sub-agent in the chat's reply; `undefined` when there is
+     * none, `null` when the chat cannot be read at all.
+     */
+    private _find;
+    private _listen;
+    private _unlisten;
+    /** Folds a burst of events (a whole run's end) into one read. */
+    private _schedule;
+    private _onConfigChange;
+    /** A pane of its own, never a line's detail. */
+    private _closable;
+    private _emitClose;
+    /** The head's words, in the chat's language: the name, and Close. */
+    private _relabelHead;
+    private _build;
+    /** Draw `anchor`'s conversation with `config`. */
+    private _draw;
+    /** Out of the page for good: every row's renderer cleans up, and the drawing goes. */
+    private _release;
+}
+/**
+ * Draw `anchor` in `view`, as a line's detail: the view then reads nothing of its own and
+ * shows what each call hands it. `onRelease` runs when the view leaves the page for good.
+ */
+export declare function feedView(view: AparteSubagentView, anchor: AparteSegment, config: AparteConfig, onRelease?: () => void): void;
+declare global {
+    interface HTMLElementTagNameMap {
+        'aparte-subagent-view': AparteSubagentView;
+    }
+    interface HTMLElementEventMap {
+        'aparte-subagent-view-close': CustomEvent<void>;
+    }
+}
+export {};
+//# sourceMappingURL=aparte-subagent-view.d.ts.map

package/dist/aparte-subagent-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aparte-subagent-view.d.ts","sourceRoot":"","sources":["../src/aparte-subagent-view.ts"],"names":[],"mappings":"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"}