@mirrowel/opencode-subagent-explorer 0.1.0-dev.1

package/dist/sessions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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;
+    title?: string;
+    agent?: string;
+    directory?: string;
+    created?: number;
+    updated?: number;
+};
+export type SessionTreeNode = {
+    session: SessionLite;
+    depth: number;
+    children: SessionTreeNode[];
+};
+export type CleanupPlan = {
+    /** Idle sessions, ordered leaf-first so children die before parents. */
+    deletable: SessionLite[];
+    /** Sessions spared because they are running right now. */
+    sparedActive: SessionLite[];
+};
+/** 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
+ * hidden/background for display purposes. */
+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". */
+export declare function fetchActiveSessionIDs(client: unknown): Promise<Set<string> | undefined>;
+/** 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[];
+/** Flattens a tree depth-first, parents before their children. */
+export declare function collectSubtree(nodes: SessionTreeNode[]): SessionLite[];
+/** Splits a tree into deletable (idle) and spared (running) sessions.
+ * Deletable order is leaf-first: children are removed before the parents
+ * they hang off, so no cascade can leave dangling rows. */
+export declare function cleanupTargets(nodes: SessionTreeNode[], activeIDs: Set<string> | undefined): CleanupPlan;
+/** The current session: the router's session id when the host provides one,
+ * else the most recently updated session in the directory. */
+export declare function currentSessionID(explicit: string | undefined, sessions: SessionLite[]): string | undefined;
+/** Hidden/background classification: config agents flagged hidden, plus
+ * runtime-registered agents OpenCode does not expose in the config. */
+export declare function hiddenAgentIDs(config: unknown): Set<string>;
+/** All agent ids the host knows about (config-declared). Anything absent
+ * from this set and from the built-ins was registered at runtime. */
+export declare function configAgentIDs(config: unknown): Set<string>;
+/** A session counts as hidden/background when its agent is flagged hidden
+ * 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;
+/** 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. */
+export declare function deleteSession(client: unknown, sessionID: string): Promise<boolean>;
+export type SessionDetails = {
+    messageCount: number;
+    model?: string;
+    firstPrompt?: string;
+};
+/** Cheap detail read for the [i] view: last assistant model + first user
+ * prompt, from a bounded tail of the session's messages. */
+export declare function fetchSessionDetails(client: unknown, sessionID: string): Promise<SessionDetails | undefined>;
+export declare function formatAge(timestamp: number | undefined, now?: number): string;
+/** Groups sessions for the session picker: every session in the directory
+ * that has children is a potential explorer root. */
+export declare function parentCandidates(sessions: SessionLite[]): SessionLite[];

package/dist/sessions.js

@@ -0,0 +1,299 @@
+/**
+ * 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.
+ */
+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
+ * hidden/background for display purposes. */
+export const BUILTIN_AGENTS = new Set(["build", "plan"]);
+export function withTimeout(fn, ms = CALL_TIMEOUT_MS) {
+    return Promise.race([Promise.resolve().then(fn).catch(() => undefined), new Promise((resolve) => setTimeout(() => resolve(undefined), ms))]);
+}
+function unwrap(value) {
+    if (value && typeof value === "object" && "data" in value)
+        return value.data;
+    return value;
+}
+function toMillis(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+}
+export function normalizeSession(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const record = raw;
+    const id = typeof record.id === "string" ? record.id : undefined;
+    if (!id)
+        return undefined;
+    const agentRaw = record.agent;
+    const agent = typeof agentRaw === "string"
+        ? agentRaw
+        : typeof agentRaw?.id === "string"
+            ? agentRaw.id
+            : typeof agentRaw?.agentID === "string"
+                ? agentRaw.agentID
+                : undefined;
+    const time = record.time && typeof record.time === "object" ? record.time : {};
+    return {
+        id,
+        parentID: typeof record.parentID === "string" ? record.parentID : undefined,
+        title: typeof record.title === "string" && record.title !== "" ? record.title : undefined,
+        agent,
+        directory: typeof record.directory === "string" ? record.directory : undefined,
+        created: toMillis(time.created ?? record.time_created),
+        updated: toMillis(time.updated ?? record.time_updated),
+    };
+}
+/** 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 async function fetchSessions(client, directory) {
+    const namespace = client?.session;
+    if (!namespace?.list)
+        return undefined;
+    const calls = [
+        () => namespace.list({ directory }),
+        () => namespace.list({ query: { directory } }),
+    ];
+    for (const call of calls) {
+        const result = unwrap(await withTimeout(call));
+        if (Array.isArray(result))
+            return result.map(normalizeSession).filter((s) => !!s);
+    }
+    return 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". */
+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;
+        }
+    }
+    if (typeof namespace.status === "function") {
+        const status = unwrap(await withTimeout(() => namespace.status()));
+        if (status && typeof status === "object") {
+            const ids = new Set();
+            for (const [id, value] of Object.entries(status)) {
+                const state = value?.status ?? value;
+                if (state === "busy" || state === "retry")
+                    ids.add(id);
+            }
+            return ids;
+        }
+    }
+    return undefined;
+}
+/** 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) {
+    const byParent = new Map();
+    for (const session of sessions) {
+        if (!session.parentID)
+            continue;
+        const list = byParent.get(session.parentID) ?? [];
+        list.push(session);
+        byParent.set(session.parentID, list);
+    }
+    const createdOf = (session) => session.created ?? 0;
+    const sortSiblings = (list) => [...list].sort((a, b) => createdOf(a) - createdOf(b));
+    const visited = new Set([rootID]);
+    const build = (list, depth) => sortSiblings(list).map((session) => {
+        if (visited.has(session.id))
+            return { session, depth, children: [] };
+        visited.add(session.id);
+        const children = build(byParent.get(session.id) ?? [], depth + 1);
+        return { session, depth, children };
+    });
+    return build(byParent.get(rootID) ?? [], 0);
+}
+/** Flattens a tree depth-first, parents before their children. */
+export function collectSubtree(nodes) {
+    const out = [];
+    const walk = (list) => {
+        for (const node of list) {
+            out.push(node.session);
+            walk(node.children);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+/** Splits a tree into deletable (idle) and spared (running) sessions.
+ * Deletable order is leaf-first: children are removed before the parents
+ * they hang off, so no cascade can leave dangling rows. */
+export function cleanupTargets(nodes, activeIDs) {
+    const deletable = [];
+    const sparedActive = [];
+    const walk = (list) => {
+        for (const node of list) {
+            walk(node.children);
+            if (activeIDs?.has(node.session.id))
+                sparedActive.push(node.session);
+            else
+                deletable.push(node.session);
+        }
+    };
+    walk(nodes);
+    return { deletable, sparedActive };
+}
+/** The current session: the router's session id when the host provides one,
+ * else the most recently updated session in the directory. */
+export function currentSessionID(explicit, sessions) {
+    if (explicit)
+        return explicit;
+    let newest;
+    for (const session of sessions) {
+        const stamp = session.updated ?? session.created ?? 0;
+        const newestStamp = newest?.updated ?? newest?.created ?? 0;
+        if (!newest || stamp > newestStamp)
+            newest = session;
+    }
+    return newest?.id;
+}
+/** Hidden/background classification: config agents flagged hidden, plus
+ * runtime-registered agents OpenCode does not expose in the config. */
+export function hiddenAgentIDs(config) {
+    const agents = config?.agent;
+    const hidden = new Set();
+    if (!agents || typeof agents !== "object")
+        return hidden;
+    for (const [id, entry] of Object.entries(agents)) {
+        if (entry && typeof entry === "object" && entry.hidden === true)
+            hidden.add(id);
+    }
+    return hidden;
+}
+/** All agent ids the host knows about (config-declared). Anything absent
+ * from this set and from the built-ins was registered at runtime. */
+export function configAgentIDs(config) {
+    const agents = config?.agent;
+    if (!agents || typeof agents !== "object")
+        return new Set();
+    return new Set(Object.keys(agents));
+}
+/** A session counts as hidden/background when its agent is flagged hidden
+ * in the config, or the agent was registered at runtime (not config-known,
+ * not built-in, not an agent-variants clone). */
+export function isHiddenAgent(agent, hidden, configAgents) {
+    if (!agent)
+        return false;
+    if (hidden.has(agent))
+        return true;
+    return !configAgents.has(agent) && !BUILTIN_AGENTS.has(agent) && !agent.startsWith("av:");
+}
+/** 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. */
+export async function deleteSession(client, sessionID) {
+    const namespace = client?.session;
+    if (!namespace)
+        return false;
+    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 }));
+    }
+    if (typeof namespace.remove === "function") {
+        shapes.push(() => namespace.remove({ sessionID }), () => namespace.remove({ path: { sessionID } }));
+    }
+    for (const call of shapes) {
+        const result = await withTimeout(call);
+        if (result !== undefined)
+            return true;
+    }
+    return false;
+}
+/** Cheap detail read for the [i] view: last assistant model + first user
+ * prompt, from a bounded tail of the session's messages. */
+export async function fetchSessionDetails(client, sessionID) {
+    const namespace = client?.session;
+    if (!namespace?.messages)
+        return undefined;
+    const calls = [
+        () => namespace.messages({ sessionID, limit: 50 }),
+        () => namespace.messages({ path: { id: sessionID }, query: { limit: 50 } }),
+    ];
+    for (const call of calls) {
+        const result = unwrap(await withTimeout(call, 4000));
+        const messages = Array.isArray(result) ? result : undefined;
+        if (!messages)
+            continue;
+        let model;
+        for (let i = messages.length - 1; i >= 0; i -= 1) {
+            const info = messages[i]?.info ?? messages[i];
+            const modelRef = info?.model;
+            if (modelRef?.providerID && modelRef?.modelID) {
+                model = `${modelRef.providerID}/${modelRef.modelID}${modelRef.variantID ? ` @${modelRef.variantID}` : ""}`;
+                break;
+            }
+        }
+        let firstPrompt;
+        for (const message of messages) {
+            const info = message?.info ?? message;
+            if (info?.role !== "user")
+                continue;
+            const text = firstTextOf(message.parts);
+            if (text) {
+                firstPrompt = text.length > 400 ? `${text.slice(0, 400)}…` : text;
+                break;
+            }
+        }
+        return { messageCount: messages.length, model, firstPrompt };
+    }
+    return undefined;
+}
+function firstTextOf(parts) {
+    if (!Array.isArray(parts))
+        return undefined;
+    for (const part of parts) {
+        const text = part?.text ?? part?.part?.text;
+        if (typeof text === "string" && text.trim() !== "")
+            return text.trim();
+    }
+    return undefined;
+}
+export function formatAge(timestamp, now = Date.now()) {
+    if (!timestamp)
+        return "—";
+    const delta = Math.max(0, now - timestamp);
+    const minutes = Math.floor(delta / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+/** Groups sessions for the session picker: every session in the directory
+ * that has children is a potential explorer root. */
+export function parentCandidates(sessions) {
+    const parents = new Set();
+    for (const session of sessions) {
+        if (session.parentID)
+            parents.add(session.parentID);
+    }
+    return sessions
+        .filter((session) => parents.has(session.id))
+        .sort((a, b) => (b.updated ?? b.created ?? 0) - (a.updated ?? a.created ?? 0));
+}

package/dist/tui-host.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Host-agnostic TUI API surface consumed by the wizard (wizard.tsx) and by
+ * embedding hosts (Config Studio). This is the exact bounded subset of the
+ * OpenCode v1 `TuiPluginApi` the wizard uses; a v1 api instance satisfies it
+ * structurally, and `v2-tui.ts` implements it over the OpenCode v2 TUI
+ * plugin context. The wizard never touches anything outside this interface,
+ * which is what lets one compiled wizard bundle run on both hosts.
+ */
+export type TuiDialogSelectOption<Value = string> = {
+    title: string;
+    value: Value;
+    description?: string;
+    category?: string;
+    disabled?: boolean;
+};
+export type TuiDialogSelectProps<Value = string> = {
+    title: string;
+    placeholder?: string;
+    options: TuiDialogSelectOption<Value>[];
+    current?: Value;
+    flat?: boolean;
+    onSelect: (option: TuiDialogSelectOption<Value>) => void;
+};
+export type TuiDialogPromptProps = {
+    title: string;
+    placeholder?: string;
+    value?: string;
+    onConfirm: (value: string) => void;
+    onCancel?: () => void;
+};
+export type TuiDialogConfirmProps = {
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    onConfirm: () => void;
+    onCancel?: () => void;
+};
+export type TuiDialogAlertProps = {
+    title: string;
+    message: string;
+    onConfirm?: () => void;
+};
+export type TuiHostTheme = {
+    text: any;
+    textMuted: any;
+    background: any;
+    backgroundPanel: any;
+    primary: any;
+    secondary: any;
+    accent: any;
+    success: any;
+    warning: any;
+    error: any;
+    info: any;
+};
+export type TuiHostKeyContext = {
+    event?: {
+        preventDefault?: () => void;
+        stopPropagation?: () => void;
+    };
+};
+export type TuiHostLayerCommand = {
+    name: string;
+    title?: string;
+    desc?: string;
+    run: (ctx: TuiHostKeyContext) => void;
+};
+export type TuiHostKeymapLayer = {
+    mode?: string;
+    priority?: number;
+    commands: readonly TuiHostLayerCommand[];
+    bindings: readonly {
+        key: string;
+        cmd: string;
+        desc?: string;
+    }[];
+};
+/** Command descriptor shared with the palette-category registry. Carries both the v1 (`category`) and v2 (`group`) grouping fields. */
+export type TuiHostPaletteCommand = {
+    name: string;
+    title: string;
+    desc?: string;
+    category?: string;
+    group?: string;
+    run: () => void | Promise<void>;
+};
+/** Minimal provider/model shape the wizard reads; the v1 SDK's richer Provider remains structurally assignable. */
+export type TuiHostProvider = {
+    id: string;
+    name: string;
+    models: Record<string, {
+        id: string;
+        name: string;
+        variants?: Record<string, unknown>;
+    }>;
+};
+export type TuiHostApi = {
+    /** Host version marker (v2 adapter sets 2; v1 leaves undefined). */
+    hostVersion?: 1 | 2;
+    app?: {
+        version?: string;
+    };
+    /** Raw host client (v1 SDK / v2 OpenCodeClient). Embedders feature-detect. */
+    client?: unknown;
+    kv: {
+        get<Value = unknown>(key: string, fallback?: Value): Value;
+        set(key: string, value: unknown): void;
+        readonly ready: boolean;
+    };
+    lifecycle: {
+        onDispose(fn: () => void): void;
+    };
+    mode: {
+        push(mode: string): () => void;
+    };
+    renderer: {
+        root?: any;
+    };
+    state: {
+        config: any;
+        provider: readonly TuiHostProvider[];
+        path?: {
+            config: string;
+            directory: string;
+            worktree: string;
+        };
+    };
+    /** Router's active session id (v1: route.current walk; v2 adapter maps its
+     * own notion). Optional — the explorer falls back to the newest session. */
+    currentSessionID?: () => string | undefined;
+    /**
+     * Dialog sizing scope. "standalone" (default): the wizard uses its OWN
+     * size kv keys and offers the size picker. "embedded": the wizard reads
+     * the embedding host's keys (Config Studio's ui-width/ui-height-percent)
+     * and hides the picker — the host's dialog settings rule.
+     */
+    dialogScope?: "standalone" | "embedded";
+    theme: {
+        readonly current: TuiHostTheme;
+    };
+    ui: {
+        toast(input: {
+            variant?: string;
+            title?: string;
+            message: string;
+            duration?: number;
+        }): void;
+        dialog: {
+            replace(renderer: unknown, onClose?: () => void): void;
+            clear(): void;
+            setSize(size: string): void;
+        };
+        DialogSelect<Value = string>(props: TuiDialogSelectProps<Value>): void;
+        DialogPrompt(props: TuiDialogPromptProps): void;
+        DialogConfirm(props: TuiDialogConfirmProps): void;
+        DialogAlert(props: TuiDialogAlertProps): void;
+    };
+    keymap: {
+        registerLayer(layer: TuiHostKeymapLayer): () => void;
+    };
+};

package/dist/tui-host.js

@@ -0,0 +1,9 @@
+/**
+ * Host-agnostic TUI API surface consumed by the wizard (wizard.tsx) and by
+ * embedding hosts (Config Studio). This is the exact bounded subset of the
+ * OpenCode v1 `TuiPluginApi` the wizard uses; a v1 api instance satisfies it
+ * structurally, and `v2-tui.ts` implements it over the OpenCode v2 TUI
+ * plugin context. The wizard never touches anything outside this interface,
+ * which is what lets one compiled wizard bundle run on both hosts.
+ */
+export {};

package/dist/tui.d.ts

@@ -0,0 +1,24 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * Subagent Explorer TUI plugin entry.
+ *
+ * Thin wrapper: registers the palette/slash command and bootstraps the
+ * explorer wizard library (wizard.tsx). Config Studio imports the wizard
+ * library directly when the module is embedded.
+ */
+import type { TuiPlugin } from "@opencode-ai/plugin/tui";
+/**
+ * Dual-target TUI entry.
+ *
+ * - OpenCode v1 (strict loader) requires `default.tui` to be a function;
+ *   excess keys are ignored.
+ * - OpenCode v2 requires `default` to be `{ id, setup }`; its hand-written
+ *   plugin check only inspects `id` + `setup`, so the legacy `tui` factory
+ *   rides along harmlessly.
+ */
+declare const _default: {
+    id: string;
+    tui: TuiPlugin;
+    setup: import("./v2-types.js").V2TuiSetup;
+};
+export default _default;