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

package/dist/v2-server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OpenCode v2 server setup for subagent-explorer.
+ *
+ * Dormant by design: the explorer is TUI-driven and needs no server-side
+ * hooks. v2 auto-discovers the ./tui export from server-declared plugins,
+ * so this setup only exists to make the plugin loadable from the v2
+ * `plugins` config (and to keep the dual-target entry shape uniform).
+ */
+import type { V2ServerSetup } from "./v2-types.js";
+export declare function createV2ServerSetup(): V2ServerSetup;

package/dist/v2-server.js

@@ -0,0 +1,14 @@
+/**
+ * OpenCode v2 server setup for subagent-explorer.
+ *
+ * Dormant by design: the explorer is TUI-driven and needs no server-side
+ * hooks. v2 auto-discovers the ./tui export from server-declared plugins,
+ * so this setup only exists to make the plugin loadable from the v2
+ * `plugins` config (and to keep the dual-target entry shape uniform).
+ */
+export function createV2ServerSetup() {
+    return async (_context) => {
+        // Intentionally empty: no transforms, no hooks, no registrations.
+        return () => undefined;
+    };
+}

package/dist/v2-tui.d.ts

@@ -0,0 +1,24 @@
+/**
+ * OpenCode v2 TUI plugin implementation: builds a `TuiHostApi` adapter over
+ * the v2 TUI plugin context so the unchanged explorer wizard (wizard.tsx)
+ * runs on both hosts, and registers the palette/slash command.
+ *
+ * Dialog bridging: the v1 api exposes dialog components (DialogSelect, …)
+ * that RETURN JSX rendered inside an enclosing `dialog.replace(render)`
+ * entry. The v2 api only offers promise-based dialogs that open their own
+ * host entry. The bridge reconciles the two: `replace()` invokes the render
+ * thunk synchronously — if it returns renderable content the v2 dialog shows
+ * it as one entry with the caller's onClose; if it returned nothing (because
+ * a DialogX bridge already opened the host's own dialog), the caller's
+ * onClose is parked and invoked when that nested dialog is dismissed without
+ * a result (esc), which is exactly when v1 would have fired it.
+ */
+import type { TuiHostApi } from "./tui-host.js";
+import type { V2TuiContext, V2TuiSetup } from "./v2-types.js";
+/** Builds the v1-shaped `TuiHostApi` facade over a v2 TUI plugin context. */
+export declare function buildV2HostApi(context: V2TuiContext): TuiHostApi;
+/**
+ * v2 TUI plugin setup: registers the palette/slash command (one reactive
+ * keymap layer).
+ */
+export declare function createV2TuiSetup(): V2TuiSetup;

package/dist/v2-tui.js

@@ -0,0 +1,357 @@
+/**
+ * OpenCode v2 TUI plugin implementation: builds a `TuiHostApi` adapter over
+ * the v2 TUI plugin context so the unchanged explorer wizard (wizard.tsx)
+ * runs on both hosts, and registers the palette/slash command.
+ *
+ * Dialog bridging: the v1 api exposes dialog components (DialogSelect, …)
+ * that RETURN JSX rendered inside an enclosing `dialog.replace(render)`
+ * entry. The v2 api only offers promise-based dialogs that open their own
+ * host entry. The bridge reconciles the two: `replace()` invokes the render
+ * thunk synchronously — if it returns renderable content the v2 dialog shows
+ * it as one entry with the caller's onClose; if it returned nothing (because
+ * a DialogX bridge already opened the host's own dialog), the caller's
+ * onClose is parked and invoked when that nested dialog is dismissed without
+ * a result (esc), which is exactly when v1 would have fired it.
+ */
+import { createSignal } from "solid-js";
+import { declarePaletteCategory, schedulePaletteReconcile } from "./palette-category.js";
+import { mainMenu } from "./wizard.js";
+function pickThemeToken(source, ...path) {
+    let current = source;
+    for (const key of path) {
+        if (!current || typeof current !== "object")
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * The wire `location` query uses `workspace`; the plugin-facing LocationRef
+ * uses `workspaceID`. Translate at the boundary.
+ */
+function wireLocation(ref) {
+    if (!ref)
+        return undefined;
+    return ref.workspaceID !== undefined ? { directory: ref.directory, workspace: ref.workspaceID } : { directory: ref.directory };
+}
+/** Wraps the v2 client so session.* calls carry the current location query
+ * (v2 generated methods are flat; absent location keys default to the TUI's
+ * own location, which is what the explorer wants). */
+function withLocationQualifiedSessions(client, location) {
+    if (!client || typeof client !== "object")
+        return client;
+    const session = client.session;
+    if (!session || typeof session !== "object")
+        return client;
+    const wrapped = {};
+    for (const method of ["list", "active", "status", "messages", "delete", "remove", "get", "wait"]) {
+        const fn = session[method];
+        if (typeof fn !== "function")
+            continue;
+        const bound = fn.bind(session);
+        wrapped[method] = (input) => {
+            const base = input && typeof input === "object" ? input : {};
+            const loc = location();
+            const merged = { ...loc, ...base };
+            return bound(merged);
+        };
+    }
+    return { ...(client ?? {}), session: { ...session, ...wrapped } };
+}
+function buildV2Theme(context) {
+    // Read theme/mode live inside the getter so mid-session theme switches
+    // reach the wizard (the host resolves a fresh token set per change).
+    return {
+        get current() {
+            const theme = context.theme;
+            const dark = context.themeMode === "dark";
+            const text = pickThemeToken(theme, "text", "default");
+            return {
+                text,
+                textMuted: pickThemeToken(theme, "text", "subdued") ?? text,
+                background: pickThemeToken(theme, "background", "default"),
+                backgroundPanel: pickThemeToken(theme, "background", "surface", "offset") ?? pickThemeToken(theme, "background", "default"),
+                primary: pickThemeToken(theme, "text", "action", "primary", "selected") ?? text,
+                secondary: pickThemeToken(theme, "hue", dark ? "interactive" : "neutral", dark ? 300 : 700) ?? text,
+                accent: pickThemeToken(theme, "hue", "accent", dark ? 200 : 800) ?? text,
+                success: pickThemeToken(theme, "text", "feedback", "success", "default") ?? text,
+                warning: pickThemeToken(theme, "text", "feedback", "warning", "default") ?? text,
+                error: pickThemeToken(theme, "text", "feedback", "error", "default") ?? text,
+                info: pickThemeToken(theme, "text", "feedback", "info", "default") ?? text,
+            };
+        },
+    };
+}
+function convertKeymapLayer(layer) {
+    const bindingsByName = new Map();
+    for (const binding of layer.bindings ?? []) {
+        if (!binding?.cmd)
+            continue;
+        const keys = bindingsByName.get(binding.cmd) ?? [];
+        keys.push(binding.key);
+        bindingsByName.set(binding.cmd, keys);
+    }
+    const commands = (layer.commands ?? []).map((command) => ({
+        id: command.name,
+        title: command.title ?? command.name,
+        description: command.desc,
+        ...(bindingsByName.get(command.name)?.length ? { bind: bindingsByName.get(command.name).join(",") } : {}),
+        run: (_input, event) => command.run({ event: event ? { preventDefault: () => event.preventDefault?.(), stopPropagation: () => event.stopPropagation?.() } : undefined }),
+    }));
+    return { mode: "global", priority: layer.priority, commands };
+}
+/** Builds the v1-shaped `TuiHostApi` facade over a v2 TUI plugin context. */
+export function buildV2HostApi(context) {
+    const disposeFns = [];
+    const locationRef = () => {
+        try {
+            return context.location
+                ? context.location
+                : context.data.location.default();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const wireLoc = () => wireLocation(locationRef());
+    // --- kv: the explorer has no persisted settings; in-memory stub ---
+    const kvMemory = {};
+    const kv = {
+        get(key, fallback) {
+            return (kvMemory[key] === undefined ? fallback : kvMemory[key]);
+        },
+        set(key, value) {
+            kvMemory[key] = value;
+        },
+        ready: true,
+    };
+    // --- v1-shaped live state over the v2 data stores ---
+    const state = {
+        get config() {
+            // Hidden agents stay IN the record (flagged): the explorer shows
+            // hidden/background subagent sessions, unlike selection UIs.
+            const agents = context.data.location.agent.list() ?? [];
+            const agentRecord = {};
+            for (const agent of agents) {
+                agentRecord[agent.id] = {
+                    name: agent.name,
+                    mode: agent.mode,
+                    hidden: agent.hidden,
+                    color: agent.color,
+                };
+            }
+            return { agent: agentRecord };
+        },
+        get provider() {
+            return [];
+        },
+        get path() {
+            const dir = locationRef()?.directory ?? process.cwd();
+            return { config: dir, directory: dir, worktree: dir };
+        },
+    };
+    // --- dialog bridging (see module doc comment) ---
+    const dialog = context.ui.dialog;
+    let nestedOnClose;
+    const settleNested = (dismissed) => {
+        const onClose = nestedOnClose;
+        nestedOnClose = undefined;
+        if (dismissed)
+            onClose?.();
+    };
+    const api = {
+        hostVersion: 2,
+        app: { version: context.app?.version },
+        client: withLocationQualifiedSessions(context.client, wireLoc),
+        kv,
+        lifecycle: {
+            onDispose(fn) {
+                disposeFns.push(fn);
+            },
+        },
+        mode: {
+            push(mode) {
+                try {
+                    return context.keymap.mode.push(mode);
+                }
+                catch {
+                    return () => undefined;
+                }
+            },
+        },
+        renderer: {
+            get root() {
+                return context.renderer?.root;
+            },
+        },
+        state,
+        theme: buildV2Theme(context),
+        ui: {
+            toast: (input) => {
+                try {
+                    context.ui.toast.show({ title: input.title, message: input.message, variant: input.variant, duration: input.duration });
+                }
+                catch {
+                    /* toasts must never crash the explorer */
+                }
+            },
+            dialog: {
+                replace(renderer, onClose) {
+                    nestedOnClose = undefined;
+                    let content;
+                    try {
+                        content = typeof renderer === "function" ? renderer() : renderer;
+                    }
+                    catch {
+                        content = undefined;
+                    }
+                    if (content === undefined || content === null) {
+                        // A DialogX bridge opened the host's own dialog; esc/dismiss
+                        // paths settle through it instead of a dialog entry here.
+                        nestedOnClose = onClose;
+                        return;
+                    }
+                    const element = content;
+                    dialog.show(() => element, onClose);
+                },
+                clear() {
+                    nestedOnClose = undefined;
+                    dialog.clear();
+                },
+                setSize(size) {
+                    try {
+                        dialog.set({ size });
+                    }
+                    catch {
+                        /* size hints are best-effort */
+                    }
+                },
+            },
+            DialogSelect(props) {
+                void dialog
+                    .select({
+                    title: props.title,
+                    placeholder: props.placeholder,
+                    current: props.current,
+                    options: props.options.map((option) => ({
+                        title: option.title,
+                        value: option.value,
+                        description: option.description,
+                        category: option.category,
+                        disabled: option.disabled,
+                    })),
+                })
+                    .then((value) => {
+                    if (value === undefined) {
+                        // v1 fires the enclosing dialog's onClose on esc.
+                        settleNested(true);
+                        return;
+                    }
+                    settleNested(false);
+                    // v1's onSelect receives the full option object; the v2 dialog
+                    // resolves with the value, so recover the option it picked.
+                    const option = props.options.find((item) => item.value === value);
+                    if (option)
+                        props.onSelect(option);
+                })
+                    .catch(() => settleNested(true));
+            },
+            DialogPrompt(props) {
+                void dialog
+                    .prompt({ title: props.title, placeholder: props.placeholder, value: props.value })
+                    .then((value) => {
+                    settleNested(value === undefined);
+                    if (value === undefined)
+                        props.onCancel?.();
+                    else
+                        props.onConfirm(value);
+                })
+                    .catch(() => {
+                    settleNested(true);
+                    props.onCancel?.();
+                });
+            },
+            DialogConfirm(props) {
+                void dialog
+                    .confirm({ title: props.title, message: props.message, label: { confirm: props.confirmLabel } })
+                    .then((result) => {
+                    settleNested(result !== true);
+                    if (result === true)
+                        props.onConfirm();
+                    else
+                        props.onCancel?.();
+                })
+                    .catch(() => {
+                    settleNested(true);
+                    props.onCancel?.();
+                });
+            },
+            DialogAlert(props) {
+                void dialog
+                    .alert({ title: props.title, message: props.message })
+                    .then(() => {
+                    settleNested(false);
+                    props.onConfirm?.();
+                })
+                    .catch(() => {
+                    settleNested(true);
+                    props.onConfirm?.();
+                });
+            },
+        },
+        keymap: {
+            registerLayer(layer) {
+                // v2 layers are reactive: the input function re-evaluates when the
+                // signal flips, so "unregistering" disables the layer. (The layer
+                // computation itself lives until the host disposes the plugin — v2
+                // has no per-layer unregister — but a disabled layer is inert.)
+                const [active, setActive] = createSignal(true);
+                try {
+                    context.keymap.layer(() => active()
+                        ? convertKeymapLayer(layer)
+                        : { mode: "global", enabled: false, commands: [], bindings: [] });
+                }
+                catch {
+                    return () => undefined;
+                }
+                return () => {
+                    setActive(false);
+                };
+            },
+        },
+    };
+    return api;
+}
+/**
+ * v2 TUI plugin setup: registers the palette/slash command (one reactive
+ * keymap layer).
+ */
+export function createV2TuiSetup() {
+    return async (context) => {
+        const api = buildV2HostApi(context);
+        const command = {
+            id: "subagent-explorer.open",
+            title: "Subagent Explorer: Open",
+            description: "Explore and delete subagent sessions",
+            category: "",
+            group: "",
+            palette: true,
+            slash: { name: "subagent-explorer" },
+            run: () => void mainMenu(api),
+        };
+        command.category = command.group = declarePaletteCategory("Subagent Explorer", command);
+        schedulePaletteReconcile();
+        const [paletteActive, setPaletteActive] = createSignal(true);
+        try {
+            context.keymap.layer(() => paletteActive()
+                ? { mode: "global", commands: [command] }
+                : { mode: "global", enabled: false, commands: [] });
+        }
+        catch {
+            /* command registration failure must not break the plugin */
+        }
+        return () => {
+            setPaletteActive(false);
+        };
+    };
+}

package/dist/v2-types.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Minimal structural types for the OpenCode v2 plugin context subset used by
+ * this plugin. Hand-written on purpose: the v2 plugin SDK is still beta, the
+ * published `@opencode-ai/plugin` npm package resolves to the v1 shape, and a
+ * v2 plugin module must not import the plugin SDK at runtime anyway
+ * (`Plugin.define` is an identity function — a plain `{ id, setup }` default
+ * export is the whole contract). Keep these in sync with the beta repo
+ * (packages/plugin/src/promise + src/tui) when the API settles.
+ */
+export type V2ModelRef = {
+    providerID: string;
+    id: string;
+    variant?: string;
+};
+export type V2AgentInfo = {
+    id: string;
+    name: string;
+    model?: V2ModelRef;
+    request: {
+        settings: Record<string, unknown>;
+        headers: Record<string, string>;
+        body: Record<string, unknown>;
+    };
+    system?: string | undefined;
+    description?: string | undefined;
+    mode: "subagent" | "primary" | "all";
+    hidden: boolean;
+    color?: string | undefined;
+    steps?: number | undefined;
+    permissions: unknown[];
+};
+export type V2AgentEditor = {
+    list(): readonly V2AgentInfo[];
+    get(id: string): V2AgentInfo | undefined;
+    default(id: string | undefined): void;
+    update(id: string, update: (agent: V2AgentInfo) => void): void;
+    remove(id: string): void;
+};
+export type V2Registration = {
+    dispose: () => Promise<void> | void;
+};
+export type V2Transform<Input> = (callback: (input: Input) => void) => Promise<V2Registration>;
+export type V2ExecuteBeforeEvent = {
+    tool: string;
+    sessionID: string;
+    agent: string;
+    messageID: string;
+    id: string;
+    input: unknown;
+};
+export type V2ExecuteAfterEvent = {
+    tool: string;
+    sessionID: string;
+    agent: string;
+    messageID: string;
+    id: string;
+    input: unknown;
+} & ({
+    status: "completed";
+    result: {
+        output?: unknown;
+        content?: unknown;
+        metadata?: Record<string, unknown>;
+    };
+} | {
+    status: "error";
+    error: unknown;
+});
+export type V2SystemPart = {
+    type: string;
+    text?: string;
+};
+export type V2SessionContextEvent = {
+    sessionID: string;
+    agent: string;
+    model: V2ModelRef;
+    system: V2SystemPart[];
+    messages: unknown[];
+    tools: Record<string, unknown>;
+    generation: Record<string, unknown>;
+    providerOptions: Record<string, unknown>;
+};
+export type V2SessionInfo = {
+    id?: string;
+    parentID?: string;
+    agent?: string;
+    model?: V2ModelRef;
+};
+export type V2PluginContext = {
+    agent: {
+        transform: V2Transform<V2AgentEditor>;
+        reload(): Promise<void> | void;
+    };
+    tool: {
+        hook(name: "execute.before", callback: (event: V2ExecuteBeforeEvent) => Promise<void> | void): Promise<V2Registration>;
+        hook(name: "execute.after", callback: (event: V2ExecuteAfterEvent) => Promise<void> | void): Promise<V2Registration>;
+    };
+    session: {
+        hook(name: "context", callback: (event: V2SessionContextEvent) => Promise<void> | void): Promise<V2Registration>;
+        get(input: {
+            sessionID: string;
+        }): Promise<unknown>;
+    };
+    app?: {
+        name?: string;
+        version?: string;
+        channel?: string;
+    };
+};
+export type V2ServerSetup = (context: V2PluginContext) => Promise<(() => void) | void> | (() => void) | void;
+export type V2TuiKeyEvent = {
+    preventDefault?(): void;
+    stopPropagation?(): void;
+    [key: string]: unknown;
+};
+export type V2KeymapCommand = {
+    id?: string;
+    title?: string;
+    description?: string;
+    group?: string;
+    enabled?: boolean | (() => boolean);
+    bind?: false | string;
+    palette?: true;
+    slash?: {
+        name: string;
+        aliases?: string[];
+        arguments?: true;
+    };
+    suggested?: boolean | (() => boolean);
+    run: (input?: string, event?: V2TuiKeyEvent) => void | false | Promise<void>;
+};
+export type V2KeymapLayer = {
+    mode?: string;
+    enabled?: boolean | (() => boolean);
+    priority?: number;
+    commands?: readonly V2KeymapCommand[];
+    bindings?: readonly string[];
+};
+export type V2DialogSelectOption<Value> = {
+    title: string;
+    value: Value;
+    description?: string;
+    category?: string;
+    disabled?: boolean;
+};
+export type V2LocationRef = {
+    directory: string;
+    workspaceID?: string;
+};
+export type V2AgentListEntry = V2AgentInfo;
+export type V2ProviderListEntry = {
+    id: string;
+    name: string;
+    activation?: string;
+    canonical?: string;
+};
+export type V2ModelListEntry = {
+    id?: string;
+    modelID?: string;
+    providerID: string;
+    name?: string;
+    variants?: Array<{
+        id: string;
+    } | string>;
+    enabled?: boolean;
+    status?: string;
+};
+export type V2TuiContext = {
+    options: Readonly<Record<string, unknown>>;
+    location?: unknown;
+    app: {
+        version?: string;
+        channel?: string;
+    };
+    renderer: {
+        root?: unknown;
+    };
+    client: any;
+    data: {
+        location: {
+            default(): V2LocationRef;
+            sync(location?: V2LocationRef): Promise<void>;
+            invalidate(location?: V2LocationRef): void;
+            agent: V2LocationCollection<V2AgentListEntry>;
+            provider: V2LocationCollection<V2ProviderListEntry>;
+            model: V2LocationCollection<V2ModelListEntry>;
+        };
+    };
+    keymap: {
+        layer(input: () => V2KeymapLayer): void;
+        mode: {
+            current(): string;
+            push(mode: string): () => void;
+        };
+    };
+    storage: {
+        store<Value extends object>(key: string, options: {
+            initial: Value;
+        }): readonly [Value, (mutation: (draft: Value) => void) => Promise<void>];
+    };
+    theme: V2ResolvedTheme;
+    themeMode: "dark" | "light";
+    ui: {
+        dialog: {
+            show(render: () => unknown, onClose?: () => void): void;
+            set(options: {
+                size?: string;
+                centered?: boolean;
+            }): void;
+            clear(): void;
+            alert(options: {
+                title: string;
+                message: string;
+            }): Promise<void>;
+            confirm(options: {
+                title: string;
+                message: string;
+                label?: {
+                    confirm?: string;
+                    cancel?: string;
+                };
+            }): Promise<boolean | undefined>;
+            prompt(options: {
+                title: string;
+                description?: string;
+                placeholder?: string;
+                value?: string;
+            }): Promise<string | undefined>;
+            select<Value>(options: {
+                title: string;
+                placeholder?: string;
+                current?: Value;
+                options: readonly V2DialogSelectOption<Value>[];
+            }): Promise<Value | undefined>;
+        };
+        toast: {
+            show(options: {
+                title?: string;
+                message: string;
+                variant?: string;
+                duration?: number;
+            }): void;
+        };
+    };
+};
+export type V2LocationCollection<Value> = {
+    list(location?: V2LocationRef): readonly Value[] | undefined;
+    sync(location?: V2LocationRef): Promise<void>;
+    invalidate(location?: V2LocationRef): void;
+};
+export type V2ResolvedTheme = {
+    text: {
+        default: unknown;
+        subdued: unknown;
+        feedback: Record<string, {
+            default: unknown;
+        }>;
+        action: Record<string, Record<string, unknown>>;
+    };
+    background: {
+        default: unknown;
+        surface: {
+            offset: unknown;
+            overlay: unknown;
+        };
+    };
+    hue: Record<string, Record<string | number, unknown>>;
+    categorical?: ReadonlyArray<unknown>;
+};
+export type V2TuiSetup = (context: V2TuiContext) => Promise<(() => void) | void> | (() => void) | void;

package/dist/v2-types.js

@@ -0,0 +1,10 @@
+/**
+ * Minimal structural types for the OpenCode v2 plugin context subset used by
+ * this plugin. Hand-written on purpose: the v2 plugin SDK is still beta, the
+ * published `@opencode-ai/plugin` npm package resolves to the v1 shape, and a
+ * v2 plugin module must not import the plugin SDK at runtime anyway
+ * (`Plugin.define` is an identity function — a plain `{ id, setup }` default
+ * export is the whole contract). Keep these in sync with the beta repo
+ * (packages/plugin/src/promise + src/tui) when the API settles.
+ */
+export {};