@mirrowel/opencode-subagent-explorer 0.1.0 → 0.2.0-dev.2

package/dist/sessions.d.ts

@@ -1,10 +1,3 @@
-/**
- * Core subagent-session data layer. Pure tree/classification logic plus
- * fail-soft client seams. Every client call is attached to its namespace
- * object (v2-gen class methods throw when detached), feature-detected,
- * timeout-bounded, and envelope-unwrapping ({data} vs raw) so one code path
- * serves the v1 and v2 hosts and the studio embed alike.
- */
 export type SessionLite = {
     id: string;
     parentID?: string;
@@ -31,13 +24,40 @@ export type CleanupPlan = {
 export declare const BUILTIN_AGENTS: Set<string>;
 export declare function withTimeout<T>(fn: () => Promise<T>, ms?: number): Promise<T | undefined>;
 export declare function normalizeSession(raw: unknown): SessionLite | undefined;
-/** Lists sessions for a directory. Tries the v2 client's flat params first,
- * then the v1 `{query}` shape; unwraps both envelope styles. Fail-soft. */
 export declare function fetchSessions(client: unknown, directory: string): Promise<SessionLite[] | undefined>;
 /** Running session ids via `session.active()` with the `session.status()`
  * fallback (busy/retry = running). `undefined` when neither exists or both
  * fail — callers must treat that as "unknown", never "idle". */
+/**
+ * Running session ids via `session.active()` with the `session.status()`
+ * fallback (busy/retry/unknown-type = running). Mirrors the Config Studio
+ * reload coordinator's proven probing: PRESENCE in the active map means
+ * running (values may be falsy and must not be filtered), the status map
+ * keys carry `.type` (not `.status`), and all calls stay attached to the
+ * namespace object (SDK methods dereference `this`). `undefined` when
+ * neither exists or both fail - callers must treat that as "unknown",
+ * never "idle".
+ */
 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). */
+export type AvSidecar = {
+    parents: Map<string, {
+        disableBase: boolean;
+    }>;
+};
+export declare function loadAvSidecar(globalConfigDir: string | undefined): AvSidecar;
+/** 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
+ * attribute most children instead of only the newest ~15 tasks; very deep
+ * history simply stays unattributed (the row then shows the parent agent,
+ * never a hidden badge - see explorerRows). */
+export type VariantAttribution = Map<string, {
+    alias: string;
+    parent: string;
+}>;
+export declare function fetchVariantAttribution(client: unknown, parentSessionID: string | undefined, directory: string | undefined, avParents: Set<string>): Promise<VariantAttribution>;
 /** Builds the recursive subagent tree for `rootID`. Unknown-parent sessions
  * are ignored (not part of this session's tree). Guarded against cycles. */
 export declare function buildSessionTree(sessions: SessionLite[], rootID: string): SessionTreeNode[];
@@ -60,9 +80,21 @@ export declare function configAgentIDs(config: unknown): Set<string>;
  * in the config, or the agent was registered at runtime (not config-known,
  * not built-in, not an agent-variants clone). */
 export declare function isHiddenAgent(agent: string | undefined, hidden: Set<string>, configAgents: Set<string>): boolean;
+/** Badge decision for explorer rows: variant children and children of
+ * AV-managed parents never carry the hidden badge - a hidden AV parent is
+ * agent-variants' base-disable ("must use a variant"), not a background
+ * agent, and the decision must not depend on attribution windows. Only
+ * genuinely hidden non-AV agents (plugin background agents, hidden custom
+ * agents without variants) keep the badge. */
+export declare function rowHidden(variant: unknown, agent: string | undefined, avParents: {
+    has: (id: string) => boolean;
+}, hidden: Set<string>, configAgents: Set<string>): boolean;
 /** Deletes one session through whichever delete method the host client
  * exposes (`session.delete`, `session.remove`). Returns false when no
- * method exists or the call failed. */
+ * method exists or the call failed. An `{error}` envelope without `data`
+ * (the runtime's non-throwing failure shape) counts as a failure, not a
+ * success - the server's remove handler swallows internal errors and can
+ * still answer, so callers verify after batch deletes. */
 export declare function deleteSession(client: unknown, sessionID: string): Promise<boolean>;
 export type SessionDetails = {
     messageCount: number;

package/dist/sessions.js

@@ -5,6 +5,7 @@
  * timeout-bounded, and envelope-unwrapping ({data} vs raw) so one code path
  * serves the v1 and v2 hosts and the studio embed alike.
  */
+import { existsSync, readFileSync } from "node:fs";
 const CALL_TIMEOUT_MS = 5000;
 /** OpenCode's built-in agent ids (v1): anything else that is not in the
  * user's config was registered at runtime (plugins) and is treated as
@@ -54,17 +55,26 @@ export function normalizeSession(raw) {
     };
 }
 /** Lists sessions for a directory. Tries the v2 client's flat params first,
- * then the v1 `{query}` shape; unwraps both envelope styles. Fail-soft. */
+ * then the v1 `{query}` shape; unwraps both envelope styles. Fail-soft.
+ *
+ * EXPLICIT LARGE LIMIT: OpenCode's Session.list defaults to a 100-row page
+ * (ordered by time_updated DESC, session.ts `limit ?? 100`) - a plain call
+ * silently hides older sessions, which truncated large trees (100+ subagents
+ * showed ~85) and made cleanups miss everything past the first page. The
+ * server imposes no max on limit (NonNegativeInt), and its `start` cursor
+ * filters to NEWER sessions (gte), so downward paging is impossible by
+ * design - one large bounded page is the honest shape. */
+const SESSION_LIST_LIMIT = 5000;
 export async function fetchSessions(client, directory) {
     const namespace = client?.session;
     if (!namespace?.list)
         return undefined;
     const calls = [
-        () => namespace.list({ directory }),
-        () => namespace.list({ query: { directory } }),
+        () => namespace.list({ directory, limit: SESSION_LIST_LIMIT }),
+        () => namespace.list({ query: { directory, limit: SESSION_LIST_LIMIT } }),
     ];
     for (const call of calls) {
-        const result = unwrap(await withTimeout(call));
+        const result = unwrap(await withTimeout(call, 8000));
         if (Array.isArray(result))
             return result.map(normalizeSession).filter((s) => !!s);
     }
@@ -73,28 +83,35 @@ export async function fetchSessions(client, directory) {
 /** Running session ids via `session.active()` with the `session.status()`
  * fallback (busy/retry = running). `undefined` when neither exists or both
  * fail — callers must treat that as "unknown", never "idle". */
+/**
+ * Running session ids via `session.active()` with the `session.status()`
+ * fallback (busy/retry/unknown-type = running). Mirrors the Config Studio
+ * reload coordinator's proven probing: PRESENCE in the active map means
+ * running (values may be falsy and must not be filtered), the status map
+ * keys carry `.type` (not `.status`), and all calls stay attached to the
+ * namespace object (SDK methods dereference `this`). `undefined` when
+ * neither exists or both fail - callers must treat that as "unknown",
+ * never "idle".
+ */
 export async function fetchActiveSessionIDs(client) {
     const namespace = client?.session;
     if (!namespace)
         return undefined;
     if (typeof namespace.active === "function") {
-        const active = unwrap(await withTimeout(() => namespace.active()));
-        if (active && typeof active === "object") {
-            const ids = new Set();
-            for (const [id, value] of Object.entries(active)) {
-                if (value)
-                    ids.add(id);
-            }
-            return ids;
+        const result = await withTimeout(() => namespace.active());
+        const data = result && typeof result === "object" ? result.data : undefined;
+        if (data && typeof data === "object" && !Array.isArray(data)) {
+            return new Set(Object.keys(data));
         }
     }
     if (typeof namespace.status === "function") {
-        const status = unwrap(await withTimeout(() => namespace.status()));
-        if (status && typeof status === "object") {
+        const result = await withTimeout(() => namespace.status());
+        const data = result && typeof result === "object" ? result.data : undefined;
+        if (data && typeof data === "object" && !Array.isArray(data)) {
             const ids = new Set();
-            for (const [id, value] of Object.entries(status)) {
-                const state = value?.status ?? value;
-                if (state === "busy" || state === "retry")
+            for (const [id, value] of Object.entries(data)) {
+                const type = value && typeof value === "object" ? (value.type ?? value.status) : value;
+                if (type === undefined || type === "busy" || type === "retry")
                     ids.add(id);
             }
             return ids;
@@ -102,6 +119,96 @@ export async function fetchActiveSessionIDs(client) {
     }
     return undefined;
 }
+export function loadAvSidecar(globalConfigDir) {
+    const parents = new Map();
+    if (!globalConfigDir)
+        return { parents };
+    try {
+        const path = `${globalConfigDir.replace(/[\\/]+$/, "")}/agent-variants.jsonc`;
+        if (!existsSync(path))
+            return { parents };
+        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 });
+        }
+    }
+    catch {
+        // Not our file to complain about - AV may simply not be installed.
+    }
+    return { parents };
+}
+function stripJsoncComments(text) {
+    // Block comments, line comments, and trailing commas before } or ].
+    return text
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/(^|[^:"'\\])\/\/.*$/gm, "$1")
+        .replace(/,(\s*[}\]])/g, "$1");
+}
+const ATTRIBUTION_PAGE_SIZE = 100;
+const ATTRIBUTION_PAGES = 5;
+export async function fetchVariantAttribution(client, parentSessionID, directory, avParents) {
+    const map = new Map();
+    if (avParents.size === 0 || !parentSessionID)
+        return map;
+    const namespace = client?.session;
+    if (!namespace || typeof namespace.messages !== "function")
+        return map;
+    const fetchPage = (before) => {
+        const query = { directory, limit: ATTRIBUTION_PAGE_SIZE };
+        if (before)
+            query.before = before;
+        // Try the flat (v2-gen) shape first, then the legacy {path, query} wrapper.
+        const flat = namespace.messages({ sessionID: parentSessionID, ...query });
+        return flat instanceof Promise ? flat : namespace.messages({ path: { id: parentSessionID }, query });
+    };
+    const asList = (value) => {
+        if (Array.isArray(value))
+            return value;
+        if (value && typeof value === "object") {
+            const unwrapped = value.data;
+            if (Array.isArray(unwrapped))
+                return unwrapped;
+        }
+        return undefined;
+    };
+    let before;
+    const seenCursors = new Set();
+    for (let page = 0; page < ATTRIBUTION_PAGES; page++) {
+        const messages = await withTimeout(() => fetchPage(before), 8000);
+        const list = asList(messages);
+        if (!list || list.length === 0)
+            break;
+        for (const message of list) {
+            for (const part of message.parts ?? []) {
+                if (part?.type !== "tool" || part.tool !== "task")
+                    continue;
+                const metadata = part.state?.metadata;
+                const child = metadata?.sessionId;
+                const variantMeta = metadata?.agentVariants;
+                const alias = variantMeta?.alias;
+                const routedAgent = variantMeta?.routedAgent;
+                if (typeof child === "string" && typeof alias === "string" && !map.has(child)) {
+                    map.set(child, {
+                        alias,
+                        parent: typeof routedAgent === "string" ? routedAgent : alias.replace(/-[a-z0-9-]+$/, ""),
+                    });
+                }
+            }
+        }
+        if (list.length < ATTRIBUTION_PAGE_SIZE)
+            break;
+        const last = list[list.length - 1];
+        const next = last?.info?.id ?? last?.id;
+        if (!next || seenCursors.has(next))
+            break;
+        seenCursors.add(next);
+        before = next;
+    }
+    return map;
+}
 /** Builds the recursive subagent tree for `rootID`. Unknown-parent sessions
  * are ignored (not part of this session's tree). Guarded against cycles. */
 export function buildSessionTree(sessions, rootID) {
@@ -200,13 +307,30 @@ export function isHiddenAgent(agent, hidden, configAgents) {
         return true;
     return !configAgents.has(agent) && !BUILTIN_AGENTS.has(agent) && !agent.startsWith("av:");
 }
+/** Badge decision for explorer rows: variant children and children of
+ * AV-managed parents never carry the hidden badge - a hidden AV parent is
+ * agent-variants' base-disable ("must use a variant"), not a background
+ * agent, and the decision must not depend on attribution windows. Only
+ * genuinely hidden non-AV agents (plugin background agents, hidden custom
+ * agents without variants) keep the badge. */
+export function rowHidden(variant, agent, avParents, hidden, configAgents) {
+    if (variant)
+        return false;
+    if (agent && avParents.has(agent))
+        return false;
+    return isHiddenAgent(agent, hidden, configAgents);
+}
 /** Deletes one session through whichever delete method the host client
  * exposes (`session.delete`, `session.remove`). Returns false when no
- * method exists or the call failed. */
+ * method exists or the call failed. An `{error}` envelope without `data`
+ * (the runtime's non-throwing failure shape) counts as a failure, not a
+ * success - the server's remove handler swallows internal errors and can
+ * still answer, so callers verify after batch deletes. */
 export async function deleteSession(client, sessionID) {
     const namespace = client?.session;
     if (!namespace)
         return false;
+    const isErrorEnvelope = (value) => !!value && typeof value === "object" && "error" in value && !("data" in value);
     const shapes = [];
     if (typeof namespace.delete === "function") {
         shapes.push(() => namespace.delete({ sessionID }), () => namespace.delete({ path: { sessionID } }), () => namespace.delete({ path: { id: sessionID } }), () => namespace.delete({ id: sessionID }));
@@ -216,8 +340,11 @@ export async function deleteSession(client, sessionID) {
     }
     for (const call of shapes) {
         const result = await withTimeout(call);
-        if (result !== undefined)
-            return true;
+        if (result === undefined)
+            continue;
+        if (isErrorEnvelope(result))
+            continue;
+        return true;
     }
     return false;
 }