@mirrowel/opencode-subagent-explorer 0.2.0-dev.3 → 0.2.0-dev.5

package/dist/sessions.d.ts

@@ -40,13 +40,31 @@ export declare function fetchSessions(client: unknown, directory: string): Promi
  */
 export declare function fetchActiveSessionIDs(client: unknown): Promise<Set<string> | undefined>;
 /** Minimal agent-variants sidecar view: which parents exist and which have
- * the base disabled. Absent file / parse errors -> empty (fail-soft). */
+ * the base disabled, plus the full alias set (variant name -> parent) used
+ * to validate parsed annotations. Absent file / parse errors -> empty
+ * (fail-soft). */
 export type AvSidecar = {
     parents: Map<string, {
         disableBase: boolean;
     }>;
+    aliases: Map<string, string>;
 };
 export declare function loadAvSidecar(globalConfigDir: string | undefined): AvSidecar;
+/** Reads the last VALID variant annotation from a text. Native suffixes are
+ * never evidence. */
+export declare function parseVariantAnnotation(text: string | undefined): {
+    alias: string;
+    switchedFrom?: string;
+} | undefined;
+/** Title-annotation fallback for children beyond the attribution walk's
+ * depth: AV writes the annotation into the child's session title at call
+ * time and it survives forever, so it attributes what the windowed walk
+ * cannot reach. Validated against the sidecar's alias set - an unknown
+ * token never attributes. */
+export declare function variantFromTitle(title: string | undefined, sidecar: AvSidecar): {
+    alias: string;
+    parent: string;
+} | undefined;
 /** child session id -> the AV variant that created it (from the parent's
  * task-part metadata). Paged backward through the parent's history via the
  * `before` message cursor (up to ATTRIBUTION_PAGES pages), so large trees

package/dist/sessions.js

@@ -121,24 +121,68 @@ export async function fetchActiveSessionIDs(client) {
 }
 export function loadAvSidecar(globalConfigDir) {
     const parents = new Map();
+    const aliases = new Map();
     if (!globalConfigDir)
-        return { parents };
+        return { parents, aliases };
     try {
         const path = `${globalConfigDir.replace(/[\\/]+$/, "")}/agent-variants.jsonc`;
         if (!existsSync(path))
-            return { parents };
+            return { parents, aliases };
         const raw = readFileSync(path, "utf8");
         const json = JSON.parse(stripJsoncComments(raw));
         for (const [parent, entry] of Object.entries(json.agents ?? {})) {
             if (!entry || typeof entry !== "object")
                 continue;
             parents.set(parent, { disableBase: entry.disable_base === true && entry.disable !== true });
+            // Alias = the variant's custom name when set, else parent-key (mirrors
+            // AV's variantName) - the validation set for annotation parsing.
+            for (const [key, variant] of Object.entries(entry.variants ?? {})) {
+                if (!variant || typeof variant !== "object" || variant.disable === true)
+                    continue;
+                const alias = typeof variant.name === "string" && variant.name !== "" ? variant.name : `${parent}-${key}`;
+                aliases.set(alias, parent);
+            }
         }
     }
     catch {
         // Not our file to complain about - AV may simply not be installed.
     }
-    return { parents };
+    return { parents, aliases };
+}
+/** One annotation token in any historical form: legacy "(@x variant)",
+ * terse "(@x)", switch "(@x ← y)". Mirrors AV's parseVariantAnnotation. */
+const ANNOTATION_TOKEN = /\(@\s*([^()@←]*?)\s*(?:\s+variant)?\s*(?:\s*←\s*([^()@←]*?))?\s*\)/g;
+/** OpenCode's own task-title suffix " (@agent subagent)" (task.ts appends it
+ * on agent-switch resumes, always AFTER our note) matches the terse form
+ * grammatically - excluded explicitly or it would override the true alias
+ * under last-wins. */
+const NATIVE_TITLE_SUFFIX = /^[^\s]+ subagent$/;
+/** Reads the last VALID variant annotation from a text. Native suffixes are
+ * never evidence. */
+export function parseVariantAnnotation(text) {
+    if (typeof text !== "string")
+        return undefined;
+    let last;
+    for (const match of text.matchAll(ANNOTATION_TOKEN)) {
+        const alias = (match[1] ?? "").trim();
+        if (alias === "" || NATIVE_TITLE_SUFFIX.test(alias))
+            continue;
+        const switchedFrom = (match[2] ?? "").trim();
+        last = switchedFrom === "" ? { alias } : { alias, switchedFrom };
+    }
+    return last;
+}
+/** Title-annotation fallback for children beyond the attribution walk's
+ * depth: AV writes the annotation into the child's session title at call
+ * time and it survives forever, so it attributes what the windowed walk
+ * cannot reach. Validated against the sidecar's alias set - an unknown
+ * token never attributes. */
+export function variantFromTitle(title, sidecar) {
+    const alias = parseVariantAnnotation(title)?.alias;
+    if (alias === undefined || sidecar.aliases.size === 0)
+        return undefined;
+    const parent = sidecar.aliases.get(alias);
+    return parent !== undefined ? { alias, parent } : undefined;
 }
 function stripJsoncComments(text) {
     // Block comments, line comments, and trailing commas before } or ].
@@ -191,10 +235,11 @@ export async function fetchVariantAttribution(client, parentSessionID, directory
                 // Two alias sources: the after-hook metadata stamp (terminal
                 // completed parts) and the before-hook description annotation -
                 // aborted/error parts never receive the metadata stamp, but the
-                // annotation ("(@alias variant)" appended at call time) persists.
+                // annotation persists. The shared parser excludes OpenCode's native
+                // "(@agent subagent)" suffix, which would otherwise win last-wins.
                 const description = part.state?.input?.description;
-                const descriptionMatch = typeof description === "string" ? description.match(/\s+\(@(\S+) variant\)$/) : undefined;
-                const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? descriptionMatch?.[1];
+                const descriptionAlias = parseVariantAnnotation(typeof description === "string" ? description : undefined)?.alias;
+                const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? (descriptionAlias !== "" ? descriptionAlias : undefined);
                 const routedAgent = variantMeta?.routedAgent;
                 if (typeof child === "string" && typeof alias === "string" && !map.has(child)) {
                     map.set(child, {

package/dist/tui.js

@@ -152,21 +152,50 @@ async function fetchActiveSessionIDs(client) {
 }
 function loadAvSidecar(globalConfigDir) {
   const parents = new Map;
+  const aliases = new Map;
   if (!globalConfigDir)
-    return { parents };
+    return { parents, aliases };
   try {
     const path = `${globalConfigDir.replace(/[\\/]+$/, "")}/agent-variants.jsonc`;
     if (!existsSync(path))
-      return { parents };
+      return { parents, aliases };
     const raw = readFileSync(path, "utf8");
     const json = JSON.parse(stripJsoncComments(raw));
     for (const [parent, entry] of Object.entries(json.agents ?? {})) {
       if (!entry || typeof entry !== "object")
         continue;
       parents.set(parent, { disableBase: entry.disable_base === true && entry.disable !== true });
+      for (const [key, variant] of Object.entries(entry.variants ?? {})) {
+        if (!variant || typeof variant !== "object" || variant.disable === true)
+          continue;
+        const alias = typeof variant.name === "string" && variant.name !== "" ? variant.name : `${parent}-${key}`;
+        aliases.set(alias, parent);
+      }
     }
   } catch {}
-  return { parents };
+  return { parents, aliases };
+}
+var ANNOTATION_TOKEN = /\(@\s*([^()@\u2190]*?)\s*(?:\s+variant)?\s*(?:\s*\u2190\s*([^()@\u2190]*?))?\s*\)/g;
+var NATIVE_TITLE_SUFFIX = /^[^\s]+ subagent$/;
+function parseVariantAnnotation(text) {
+  if (typeof text !== "string")
+    return;
+  let last;
+  for (const match of text.matchAll(ANNOTATION_TOKEN)) {
+    const alias = (match[1] ?? "").trim();
+    if (alias === "" || NATIVE_TITLE_SUFFIX.test(alias))
+      continue;
+    const switchedFrom = (match[2] ?? "").trim();
+    last = switchedFrom === "" ? { alias } : { alias, switchedFrom };
+  }
+  return last;
+}
+function variantFromTitle(title, sidecar) {
+  const alias = parseVariantAnnotation(title)?.alias;
+  if (alias === undefined || sidecar.aliases.size === 0)
+    return;
+  const parent = sidecar.aliases.get(alias);
+  return parent !== undefined ? { alias, parent } : undefined;
 }
 function stripJsoncComments(text) {
   return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1");
@@ -212,8 +241,8 @@ async function fetchVariantAttribution(client, parentSessionID, directory, avPar
         const child = metadata?.sessionId;
         const variantMeta = metadata?.agentVariants;
         const description = part.state?.input?.description;
-        const descriptionMatch = typeof description === "string" ? description.match(/\s+\(@(\S+) variant\)$/) : undefined;
-        const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? descriptionMatch?.[1];
+        const descriptionAlias = parseVariantAnnotation(typeof description === "string" ? description : undefined)?.alias;
+        const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? (descriptionAlias !== "" ? descriptionAlias : undefined);
         const routedAgent = variantMeta?.routedAgent;
         if (typeof child === "string" && typeof alias === "string" && !map.has(child)) {
           map.set(child, {
@@ -428,14 +457,15 @@ async function loadExplorerData(api, directory, rootOverride) {
     hidden: hiddenAgentIDs(api.state.config),
     configAgents: configAgentIDs(api.state.config),
     variantOf,
-    avParents: avSidecar.parents
+    avParents: avSidecar.parents,
+    avSidecar
   };
 }
 function explorerRows(tree, data) {
   const rows = [];
   const walk = (nodes, depth) => {
     for (const node of nodes) {
-      const variant = data.variantOf.get(node.session.id);
+      const variant = data.variantOf.get(node.session.id) ?? variantFromTitle(node.session.title, data.avSidecar);
       const agent = node.session.agent;
       rows.push({
         session: node.session,
@@ -1266,7 +1296,11 @@ async function remainingIdleCount(api, directory, rootID) {
     hidden: new Set,
     configAgents: new Set,
     variantOf: new Map,
-    avParents: new Map
+    avParents: new Map,
+    avSidecar: {
+      parents: new Map,
+      aliases: new Map
+    }
   });
   return rows.filter((row) => !row.running).length;
 }

package/dist/wizard.d.ts

@@ -10,7 +10,7 @@
  * import mainMenu from here and drive it with their own TuiHostApi instance.
  */
 import type { TuiHostApi as TuiPluginApi } from "./tui-host.js";
-import { type SessionLite, type SessionTreeNode, type VariantAttribution } from "./sessions.js";
+import { type AvSidecar, type SessionLite, type SessionTreeNode, type VariantAttribution } from "./sessions.js";
 export type ExplorerRow = {
     session: SessionLite;
     depth: number;
@@ -33,6 +33,8 @@ export type ExplorerData = {
     avParents: Map<string, {
         disableBase: boolean;
     }>;
+    /** The full sidecar view - the alias set validates title annotations. */
+    avSidecar: AvSidecar;
 };
 export type TreeAction = {
     type: "delete";

package/dist/wizard.js

@@ -99,21 +99,50 @@ async function fetchActiveSessionIDs(client) {
 }
 function loadAvSidecar(globalConfigDir) {
   const parents = new Map;
+  const aliases = new Map;
   if (!globalConfigDir)
-    return { parents };
+    return { parents, aliases };
   try {
     const path = `${globalConfigDir.replace(/[\\/]+$/, "")}/agent-variants.jsonc`;
     if (!existsSync(path))
-      return { parents };
+      return { parents, aliases };
     const raw = readFileSync(path, "utf8");
     const json = JSON.parse(stripJsoncComments(raw));
     for (const [parent, entry] of Object.entries(json.agents ?? {})) {
       if (!entry || typeof entry !== "object")
         continue;
       parents.set(parent, { disableBase: entry.disable_base === true && entry.disable !== true });
+      for (const [key, variant] of Object.entries(entry.variants ?? {})) {
+        if (!variant || typeof variant !== "object" || variant.disable === true)
+          continue;
+        const alias = typeof variant.name === "string" && variant.name !== "" ? variant.name : `${parent}-${key}`;
+        aliases.set(alias, parent);
+      }
     }
   } catch {}
-  return { parents };
+  return { parents, aliases };
+}
+var ANNOTATION_TOKEN = /\(@\s*([^()@\u2190]*?)\s*(?:\s+variant)?\s*(?:\s*\u2190\s*([^()@\u2190]*?))?\s*\)/g;
+var NATIVE_TITLE_SUFFIX = /^[^\s]+ subagent$/;
+function parseVariantAnnotation(text) {
+  if (typeof text !== "string")
+    return;
+  let last;
+  for (const match of text.matchAll(ANNOTATION_TOKEN)) {
+    const alias = (match[1] ?? "").trim();
+    if (alias === "" || NATIVE_TITLE_SUFFIX.test(alias))
+      continue;
+    const switchedFrom = (match[2] ?? "").trim();
+    last = switchedFrom === "" ? { alias } : { alias, switchedFrom };
+  }
+  return last;
+}
+function variantFromTitle(title, sidecar) {
+  const alias = parseVariantAnnotation(title)?.alias;
+  if (alias === undefined || sidecar.aliases.size === 0)
+    return;
+  const parent = sidecar.aliases.get(alias);
+  return parent !== undefined ? { alias, parent } : undefined;
 }
 function stripJsoncComments(text) {
   return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1");
@@ -159,8 +188,8 @@ async function fetchVariantAttribution(client, parentSessionID, directory, avPar
         const child = metadata?.sessionId;
         const variantMeta = metadata?.agentVariants;
         const description = part.state?.input?.description;
-        const descriptionMatch = typeof description === "string" ? description.match(/\s+\(@(\S+) variant\)$/) : undefined;
-        const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? descriptionMatch?.[1];
+        const descriptionAlias = parseVariantAnnotation(typeof description === "string" ? description : undefined)?.alias;
+        const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? (descriptionAlias !== "" ? descriptionAlias : undefined);
         const routedAgent = variantMeta?.routedAgent;
         if (typeof child === "string" && typeof alias === "string" && !map.has(child)) {
           map.set(child, {
@@ -375,14 +404,15 @@ async function loadExplorerData(api, directory, rootOverride) {
     hidden: hiddenAgentIDs(api.state.config),
     configAgents: configAgentIDs(api.state.config),
     variantOf,
-    avParents: avSidecar.parents
+    avParents: avSidecar.parents,
+    avSidecar
   };
 }
 function explorerRows(tree, data) {
   const rows = [];
   const walk = (nodes, depth) => {
     for (const node of nodes) {
-      const variant = data.variantOf.get(node.session.id);
+      const variant = data.variantOf.get(node.session.id) ?? variantFromTitle(node.session.title, data.avSidecar);
       const agent = node.session.agent;
       rows.push({
         session: node.session,
@@ -1213,7 +1243,11 @@ async function remainingIdleCount(api, directory, rootID) {
     hidden: new Set,
     configAgents: new Set,
     variantOf: new Map,
-    avParents: new Map
+    avParents: new Map,
+    avSidecar: {
+      parents: new Map,
+      aliases: new Map
+    }
   });
   return rows.filter((row) => !row.running).length;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirrowel/opencode-subagent-explorer",
-  "version": "0.2.0-dev.3",
+  "version": "0.2.0-dev.5",
   "type": "module",
   "description": "OpenCode plugin for exploring and cleaning up subagent sessions of the current session",
   "license": "MIT",

package/src/sessions.ts

@@ -146,29 +146,76 @@ export async function fetchActiveSessionIDs(client: unknown): Promise<Set<string
 }
 
 /** Minimal agent-variants sidecar view: which parents exist and which have
- * the base disabled. Absent file / parse errors -> empty (fail-soft). */
+ * the base disabled, plus the full alias set (variant name -> parent) used
+ * to validate parsed annotations. Absent file / parse errors -> empty
+ * (fail-soft). */
 export type AvSidecar = {
   parents: Map<string, { disableBase: boolean }>
+  aliases: Map<string, string>
 }
 
 export function loadAvSidecar(globalConfigDir: string | undefined): AvSidecar {
   const parents = new Map<string, { disableBase: boolean }>()
-  if (!globalConfigDir) return { parents }
+  const aliases = new Map<string, string>()
+  if (!globalConfigDir) return { parents, aliases }
   try {
     const path = `${globalConfigDir.replace(/[\\/]+$/, "")}/agent-variants.jsonc`
-    if (!existsSync(path)) return { parents }
+    if (!existsSync(path)) return { parents, aliases }
     const raw = readFileSync(path, "utf8")
     const json = JSON.parse(stripJsoncComments(raw)) as {
-      agents?: Record<string, { disable_base?: boolean; disable?: boolean }>
+      agents?: Record<string, { disable_base?: boolean; disable?: boolean; variants?: Record<string, { name?: string; disable?: boolean }> }>
     }
     for (const [parent, entry] of Object.entries(json.agents ?? {})) {
       if (!entry || typeof entry !== "object") continue
       parents.set(parent, { disableBase: entry.disable_base === true && entry.disable !== true })
+      // Alias = the variant's custom name when set, else parent-key (mirrors
+      // AV's variantName) - the validation set for annotation parsing.
+      for (const [key, variant] of Object.entries(entry.variants ?? {})) {
+        if (!variant || typeof variant !== "object" || variant.disable === true) continue
+        const alias = typeof variant.name === "string" && variant.name !== "" ? variant.name : `${parent}-${key}`
+        aliases.set(alias, parent)
+      }
     }
   } catch {
     // Not our file to complain about - AV may simply not be installed.
   }
-  return { parents }
+  return { parents, aliases }
+}
+
+/** One annotation token in any historical form: legacy "(@x variant)",
+ * terse "(@x)", switch "(@x ← y)". Mirrors AV's parseVariantAnnotation. */
+const ANNOTATION_TOKEN = /\(@\s*([^()@←]*?)\s*(?:\s+variant)?\s*(?:\s*←\s*([^()@←]*?))?\s*\)/g
+
+/** OpenCode's own task-title suffix " (@agent subagent)" (task.ts appends it
+ * on agent-switch resumes, always AFTER our note) matches the terse form
+ * grammatically - excluded explicitly or it would override the true alias
+ * under last-wins. */
+const NATIVE_TITLE_SUFFIX = /^[^\s]+ subagent$/
+
+/** Reads the last VALID variant annotation from a text. Native suffixes are
+ * never evidence. */
+export function parseVariantAnnotation(text: string | undefined): { alias: string; switchedFrom?: string } | undefined {
+  if (typeof text !== "string") return undefined
+  let last: { alias: string; switchedFrom?: string } | undefined
+  for (const match of text.matchAll(ANNOTATION_TOKEN)) {
+    const alias = (match[1] ?? "").trim()
+    if (alias === "" || NATIVE_TITLE_SUFFIX.test(alias)) continue
+    const switchedFrom = (match[2] ?? "").trim()
+    last = switchedFrom === "" ? { alias } : { alias, switchedFrom }
+  }
+  return last
+}
+
+/** Title-annotation fallback for children beyond the attribution walk's
+ * depth: AV writes the annotation into the child's session title at call
+ * time and it survives forever, so it attributes what the windowed walk
+ * cannot reach. Validated against the sidecar's alias set - an unknown
+ * token never attributes. */
+export function variantFromTitle(title: string | undefined, sidecar: AvSidecar): { alias: string; parent: string } | undefined {
+  const alias = parseVariantAnnotation(title)?.alias
+  if (alias === undefined || sidecar.aliases.size === 0) return undefined
+  const parent = sidecar.aliases.get(alias)
+  return parent !== undefined ? { alias, parent } : undefined
 }
 
 function stripJsoncComments(text: string): string {
@@ -230,10 +277,11 @@ export async function fetchVariantAttribution(
         // Two alias sources: the after-hook metadata stamp (terminal
         // completed parts) and the before-hook description annotation -
         // aborted/error parts never receive the metadata stamp, but the
-        // annotation ("(@alias variant)" appended at call time) persists.
-        const description = part.state?.input?.description
-        const descriptionMatch = typeof description === "string" ? description.match(/\s+\(@(\S+) variant\)$/) : undefined
-        const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? descriptionMatch?.[1]
+        // annotation persists. The shared parser excludes OpenCode's native
+        // "(@agent subagent)" suffix, which would otherwise win last-wins.
+        const description: unknown = part.state?.input?.description
+        const descriptionAlias = parseVariantAnnotation(typeof description === "string" ? description : undefined)?.alias
+        const alias = (typeof variantMeta?.alias === "string" ? variantMeta.alias : undefined) ?? (descriptionAlias !== "" ? descriptionAlias : undefined)
         const routedAgent = variantMeta?.routedAgent
         if (typeof child === "string" && typeof alias === "string" && !map.has(child)) {
           map.set(child, {

package/src/wizard.tsx

@@ -30,6 +30,8 @@ import {
   loadAvSidecar,
   parentCandidates,
   rowHidden,
+  variantFromTitle,
+  type AvSidecar,
   type CleanupPlan,
   type SessionLite,
   type SessionTreeNode,
@@ -54,6 +56,8 @@ export type ExplorerData = {
   variantOf: VariantAttribution
   /** AV sidecar parents (empty when agent-variants is not installed). */
   avParents: Map<string, { disableBase: boolean }>
+  /** The full sidecar view - the alias set validates title annotations. */
+  avSidecar: AvSidecar
 }
 
 export type TreeAction =
@@ -89,6 +93,7 @@ export async function loadExplorerData(api: TuiPluginApi, directory: string, roo
     configAgents: configAgentIDs(api.state.config),
     variantOf,
     avParents: avSidecar.parents,
+    avSidecar,
   }
 }
 
@@ -96,7 +101,10 @@ export function explorerRows(tree: SessionTreeNode[], data: ExplorerData): Explo
   const rows: ExplorerRow[] = []
   const walk = (nodes: SessionTreeNode[], depth: number) => {
     for (const node of nodes) {
-      const variant = data.variantOf.get(node.session.id)
+      // Attribution: windowed metadata/description walk first, then the
+      // title annotation (AV's call-time writing, carried forever - reaches
+      // children the walk cannot).
+      const variant = data.variantOf.get(node.session.id) ?? variantFromTitle(node.session.title, data.avSidecar)
       const agent = node.session.agent
       rows.push({
         session: node.session,
@@ -603,6 +611,7 @@ async function remainingIdleCount(api: TuiPluginApi, directory: string, rootID:
     configAgents: new Set(),
     variantOf: new Map(),
     avParents: new Map(),
+    avSidecar: { parents: new Map(), aliases: new Map() },
   })
   return rows.filter((row) => !row.running).length
 }