From b88650d7266c4e797e274b86ca10a0c57a01b679 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 22 Jul 2026 07:43:12 +0000
Subject: [PATCH 1/2] feat(inspect): list hub commands and let the inspector
 execute them

Adds a Commands tab to the inspector, backed by two new RPC functions:
devframes:plugin:inspect:list-commands and
devframes:plugin:inspect:execute-command. Both duck-type ctx.commands
(the hub's commands host) so the plugin keeps no build/runtime
dependency on @devframes/hub and degrades gracefully outside a hub
(empty list / thrown diagnostic).
---
 plugins/inspect/package.json                  |   1 +
 plugins/inspect/src/client/index.ts           |   2 +-
 plugins/inspect/src/diagnostics.ts            |   5 +
 .../src/rpc/functions/_hub-commands.ts        |  61 ++++++++++
 .../src/rpc/functions/execute-command.ts      |  46 ++++++++
 .../src/rpc/functions/list-commands.ts        |  33 ++++++
 plugins/inspect/src/rpc/index.ts              |   4 +
 plugins/inspect/src/spa/App.vue               |   5 +-
 .../inspect/src/spa/components/CommandRow.vue | 111 ++++++++++++++++++
 .../src/spa/components/CommandsSmart.vue      |  47 ++++++++
 .../spa/components/CommandsView.stories.ts    |  92 +++++++++++++++
 .../src/spa/components/CommandsView.vue       |  92 +++++++++++++++
 plugins/inspect/src/spa/style.css             |  41 +++++++
 plugins/inspect/src/types.ts                  |  21 ++++
 plugins/inspect/test/_utils.ts                |  34 +++++-
 plugins/inspect/test/dev-server.test.ts       | 108 ++++++++++++++++-
 plugins/inspect/test/static-build.test.ts     |   4 +-
 pnpm-lock.yaml                                |   3 +
 18 files changed, 701 insertions(+), 9 deletions(-)
 create mode 100644 plugins/inspect/src/rpc/functions/_hub-commands.ts
 create mode 100644 plugins/inspect/src/rpc/functions/execute-command.ts
 create mode 100644 plugins/inspect/src/rpc/functions/list-commands.ts
 create mode 100644 plugins/inspect/src/spa/components/CommandRow.vue
 create mode 100644 plugins/inspect/src/spa/components/CommandsSmart.vue
 create mode 100644 plugins/inspect/src/spa/components/CommandsView.stories.ts
 create mode 100644 plugins/inspect/src/spa/components/CommandsView.vue

diff --git a/plugins/inspect/package.json b/plugins/inspect/package.json
index bd53d485..fabe1271 100644
--- a/plugins/inspect/package.json
+++ b/plugins/inspect/package.json
@@ -62,6 +62,7 @@
   },
   "devDependencies": {
     "@antfu/design": "catalog:frontend",
+    "@devframes/hub": "workspace:*",
     "@iconify-json/ph": "catalog:frontend",
     "@storybook/addon-docs": "catalog:storybook",
     "@storybook/vue3-vite": "catalog:storybook",
diff --git a/plugins/inspect/src/client/index.ts b/plugins/inspect/src/client/index.ts
index e253b1b5..4dd578a1 100644
--- a/plugins/inspect/src/client/index.ts
+++ b/plugins/inspect/src/client/index.ts
@@ -2,7 +2,7 @@ import type { DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientOpti
 import { connectDevframe } from 'devframe/client'
 
 export type { DevframeConnectionStatus, DevframeRpcClient }
-export type { AgentManifest, InvokeResult, RpcFunctionAgentInfo, RpcFunctionInfo } from '../types'
+export type { AgentManifest, DevframeInspectCommandInfo, InvokeResult, RpcFunctionAgentInfo, RpcFunctionInfo } from '../types'
 
 /**
  * Connect to the inspector's devframe backend. A thin, typed wrapper
diff --git a/plugins/inspect/src/diagnostics.ts b/plugins/inspect/src/diagnostics.ts
index 84ce9b76..f5dacb38 100644
--- a/plugins/inspect/src/diagnostics.ts
+++ b/plugins/inspect/src/diagnostics.ts
@@ -19,5 +19,10 @@ export const diagnostics = defineDiagnostics({
         `Refusing to invoke "${p.name}" — only read-only "query" and "static" functions are invokable from the inspector, but this one is "${p.type}".`,
       fix: 'The inspector deliberately blocks `action`/`event` functions to avoid triggering side effects. Invoke those through their own UI instead.',
     },
+    DP_INSPECT_0003: {
+      why: (p: { id: string }) =>
+        `Cannot execute command "${p.id}" — this connection has no hub commands host.`,
+      fix: 'Commands are a `@devframes/hub` feature. Mount this devframe inside a hub that registers commands via `ctx.commands.register()`, or check `devframes:plugin:inspect:list-commands` (returns an empty list outside a hub).',
+    },
   },
 })
diff --git a/plugins/inspect/src/rpc/functions/_hub-commands.ts b/plugins/inspect/src/rpc/functions/_hub-commands.ts
new file mode 100644
index 00000000..0f962c4c
--- /dev/null
+++ b/plugins/inspect/src/rpc/functions/_hub-commands.ts
@@ -0,0 +1,61 @@
+import type { DevframeInspectCommandInfo } from '../../types'
+
+/**
+ * Minimal shape of the hub's commands host (`DevframeHubContext.commands`,
+ * `@devframes/hub/src/types/commands.ts`) that this plugin reads from.
+ * Declared locally and accessed by duck-typing so the inspector keeps no
+ * build/runtime dependency on `@devframes/hub` and degrades to an empty
+ * list / a thrown diagnostic outside a hub.
+ */
+export interface HubCommandLike {
+  id: string
+  title: string
+  description?: string
+  icon?: string | { light: string, dark: string }
+  category?: string
+  handler?: (...args: any[]) => any
+  children?: HubCommandLike[]
+}
+
+export interface HubCommandsHostLike {
+  commands: Map<string, HubCommandLike>
+  execute: (id: string, ...args: any[]) => Promise<unknown>
+}
+
+function looksLikeHubCommandsHost(value: unknown): value is HubCommandsHostLike {
+  return !!value
+    && typeof value === 'object'
+    && (value as { commands?: unknown }).commands instanceof Map
+    && typeof (value as { execute?: unknown }).execute === 'function'
+}
+
+/**
+ * Resolve `ctx.commands` when this connection is mounted inside a hub, or
+ * `undefined` on a plain devframe connection (CLI / Vite / build without a
+ * hub). Structural rather than an `instanceof`/import check, matching the
+ * pattern established in `plugins/terminals/src/node/manager.ts`.
+ */
+export function resolveHubCommands(ctx: object): HubCommandsHostLike | undefined {
+  const commands = (ctx as { commands?: unknown }).commands
+  return looksLikeHubCommandsHost(commands) ? commands : undefined
+}
+
+/**
+ * Project a raw hub command (still carrying its `handler`) into the
+ * serializable shape the inspector sends over RPC, recursing into
+ * children. `hasHandler` survives the projection even though the hub's
+ * own `commands.list()` strips `handler` entirely before it's callable
+ * from here — reading the raw command straight off `host.commands`
+ * preserves that flag.
+ */
+export function projectCommand(cmd: HubCommandLike): DevframeInspectCommandInfo {
+  return {
+    id: cmd.id,
+    title: cmd.title,
+    description: cmd.description,
+    icon: cmd.icon,
+    category: cmd.category,
+    hasHandler: typeof cmd.handler === 'function',
+    children: cmd.children?.map(projectCommand),
+  }
+}
diff --git a/plugins/inspect/src/rpc/functions/execute-command.ts b/plugins/inspect/src/rpc/functions/execute-command.ts
new file mode 100644
index 00000000..f00bdff5
--- /dev/null
+++ b/plugins/inspect/src/rpc/functions/execute-command.ts
@@ -0,0 +1,46 @@
+import type { InvokeResult } from '../../types'
+import { diagnostics } from '../../diagnostics'
+import { defineInspectRpc } from './_define'
+import { resolveHubCommands } from './_hub-commands'
+
+/**
+ * Execute a hub command by id and return a result envelope, mirroring
+ * `devframes:plugin:inspect:invoke`. Unlike that function, this one is not
+ * gated to read-only types — a command is, by construction, something a
+ * user explicitly runs (unlike an arbitrary RPC `action`, which may be a
+ * side effect the inspector shouldn't fire unprompted).
+ *
+ * Throws `DP_INSPECT_0003` when this connection has no hub commands host
+ * (not mounted inside `@devframes/hub`). A found-but-unregistered id, or a
+ * group-only command with no handler, surfaces as `{ ok: false, error }`
+ * from the hub's own `commands.execute()` instead of throwing.
+ */
+export const executeCommand = defineInspectRpc({
+  name: 'devframes:plugin:inspect:execute-command',
+  type: 'action',
+  setup: ctx => ({
+    handler: async (id: string, args: unknown[] = []): Promise<InvokeResult> => {
+      const host = resolveHubCommands(ctx)
+      if (!host)
+        throw diagnostics.DP_INSPECT_0003({ id })
+
+      const start = Date.now()
+      try {
+        const result = await host.execute(id, ...args)
+        return { ok: true, result, durationMs: Date.now() - start }
+      }
+      catch (error) {
+        const e = error as Error
+        return {
+          ok: false,
+          error: {
+            name: e?.name ?? 'Error',
+            message: e?.message ?? String(error),
+            stack: e?.stack,
+          },
+          durationMs: Date.now() - start,
+        }
+      }
+    },
+  }),
+})
diff --git a/plugins/inspect/src/rpc/functions/list-commands.ts b/plugins/inspect/src/rpc/functions/list-commands.ts
new file mode 100644
index 00000000..ec7f90fd
--- /dev/null
+++ b/plugins/inspect/src/rpc/functions/list-commands.ts
@@ -0,0 +1,33 @@
+import type { DevframeInspectCommandInfo } from '../../types'
+import { defineInspectRpc } from './_define'
+import { projectCommand, resolveHubCommands } from './_hub-commands'
+
+/**
+ * Enumerate every command registered on the hub's commands host — id,
+ * title, description, icon, category, whether it carries its own handler,
+ * and nested children — when this connection is mounted inside a hub
+ * (`@devframes/hub`). Returns an empty list on a plain devframe connection,
+ * so the inspector's Commands tab degrades gracefully rather than erroring.
+ * `snapshot: true` bakes the (possibly empty) list into the static dump so
+ * the inspector still lists commands in `build`/`spa` mode.
+ */
+export const listCommands = defineInspectRpc({
+  name: 'devframes:plugin:inspect:list-commands',
+  type: 'query',
+  jsonSerializable: true,
+  snapshot: true,
+  agent: {
+    description: 'List every command registered on the hub commands host (id, title, description, category, whether it has a handler, children), when this connection is mounted inside a hub. Read-only. Empty outside a hub.',
+    title: 'List hub commands',
+  },
+  setup: ctx => ({
+    handler: async (): Promise<DevframeInspectCommandInfo[]> => {
+      const host = resolveHubCommands(ctx)
+      if (!host)
+        return []
+      const out = [...host.commands.values()].map(projectCommand)
+      out.sort((a, b) => a.title.localeCompare(b.title))
+      return out
+    },
+  }),
+})
diff --git a/plugins/inspect/src/rpc/index.ts b/plugins/inspect/src/rpc/index.ts
index c4fd25f3..0ebe8d0e 100644
--- a/plugins/inspect/src/rpc/index.ts
+++ b/plugins/inspect/src/rpc/index.ts
@@ -1,7 +1,9 @@
 import type { RpcDefinitionsToFunctions } from 'devframe/rpc'
 import { describeAgent } from './functions/describe-agent'
+import { executeCommand } from './functions/execute-command'
 import { invoke } from './functions/invoke'
 import { invokeAgentTool } from './functions/invoke-agent-tool'
+import { listCommands } from './functions/list-commands'
 import { listFunctions } from './functions/list-functions'
 import { listStateKeys } from './functions/list-state-keys'
 import { readAgentResource } from './functions/read-agent-resource'
@@ -17,6 +19,8 @@ export const serverFunctions = [
   describeAgent,
   invokeAgentTool,
   readAgentResource,
+  listCommands,
+  executeCommand,
 ] as const
 
 declare module 'devframe' {
diff --git a/plugins/inspect/src/spa/App.vue b/plugins/inspect/src/spa/App.vue
index adccd464..e14ff1db 100644
--- a/plugins/inspect/src/spa/App.vue
+++ b/plugins/inspect/src/spa/App.vue
@@ -14,13 +14,14 @@ import {
   connectionTitle,
 } from '../../../../design/design'
 import AgentSmart from './components/AgentSmart.vue'
+import CommandsSmart from './components/CommandsSmart.vue'
 import FunctionsSmart from './components/FunctionsSmart.vue'
 import HistorySmart from './components/HistorySmart.vue'
 import StateSmart from './components/StateSmart.vue'
 import { useRefresh } from './composables/refresh'
 import { connect, connection } from './composables/rpc'
 
-type Tab = 'functions' | 'state' | 'agent' | 'history'
+type Tab = 'functions' | 'state' | 'agent' | 'commands' | 'history'
 
 const tab = ref<Tab>('functions')
 const { refresh, loading } = useRefresh()
@@ -37,6 +38,7 @@ const tabs: { value: Tab, label: string, icon: string }[] = [
   { value: 'functions', label: 'Functions', icon: 'i-ph-function-duotone' },
   { value: 'state', label: 'State', icon: 'i-ph-database-duotone' },
   { value: 'agent', label: 'Agent', icon: 'i-ph-robot-duotone' },
+  { value: 'commands', label: 'Commands', icon: 'i-ph-terminal-window-duotone' },
   { value: 'history', label: 'History', icon: 'i-ph-clock-counter-clockwise-duotone' },
 ]
 
@@ -102,6 +104,7 @@ function reload(): void {
         <FunctionsSmart v-if="tab === 'functions'" />
         <StateSmart v-else-if="tab === 'state'" />
         <AgentSmart v-else-if="tab === 'agent'" />
+        <CommandsSmart v-else-if="tab === 'commands'" />
         <HistorySmart v-else-if="tab === 'history'" />
       </template>
     </main>
diff --git a/plugins/inspect/src/spa/components/CommandRow.vue b/plugins/inspect/src/spa/components/CommandRow.vue
new file mode 100644
index 00000000..36f64161
--- /dev/null
+++ b/plugins/inspect/src/spa/components/CommandRow.vue
@@ -0,0 +1,111 @@
+<script setup lang="ts">
+import type { DevframeInspectCommandInfo } from '@devframes/plugin-inspect/client'
+import ActionButton from '@antfu/design/components/Action/ActionButton.vue'
+import { computed, ref } from 'vue'
+import JsonView from './JsonView.vue'
+
+defineOptions({ name: 'CommandRow' })
+
+const props = defineProps<{
+  cmd: DevframeInspectCommandInfo
+  argsInput: Record<string, string>
+  results: Record<string, any>
+  pending: Record<string, boolean>
+  isStatic: boolean
+  /** Nesting depth — 0 for top-level commands, 1 for their children. */
+  depth?: number
+}>()
+
+const emit = defineEmits<{
+  (e: 'execute', cmd: DevframeInspectCommandInfo): void
+  (e: 'updateArgs', id: string, value: string): void
+}>()
+
+const expanded = ref(false)
+
+const clickable = computed(() =>
+  props.cmd.hasHandler || !!props.cmd.description || !!props.cmd.children?.length,
+)
+
+function toggle(): void {
+  expanded.value = !expanded.value
+}
+</script>
+
+<template>
+  <div class="fn-row" :class="{ 'cmd-row-child': depth }">
+    <div class="fn-head" :class="{ clickable }" @click="toggle">
+      <div class="chev i-ph-caret-right" :class="{ open: expanded }" />
+      <span v-if="cmd.icon" :class="typeof cmd.icon === 'string' ? cmd.icon : 'i-ph-terminal-window-duotone'" class="cmd-icon" />
+      <span class="cmd-title">{{ cmd.title }}</span>
+      <span class="cmd-id mono">{{ cmd.id }}</span>
+      <span class="fn-flags">
+        <span v-if="cmd.category" class="badge flag">{{ cmd.category }}</span>
+        <span v-if="!cmd.hasHandler" class="badge flag" title="No handler — a group for its children">group</span>
+        <span v-if="cmd.children?.length" class="badge flag">{{ cmd.children.length }} children</span>
+      </span>
+    </div>
+
+    <div v-if="expanded" class="fn-detail">
+      <p v-if="cmd.description" class="desc">
+        {{ cmd.description }}
+      </p>
+
+      <template v-if="cmd.hasHandler">
+        <div class="label">
+          Execute — positional args as a JSON array
+        </div>
+        <textarea :value="argsInput[cmd.id]" class="args" spellcheck="false" placeholder="[]" @input="emit('updateArgs', cmd.id, ($event.target as HTMLTextAreaElement).value)" />
+        <div style="margin-top: 8px; display: flex; gap: 8px; align-items: center;">
+          <ActionButton
+            variant="primary"
+            size="sm"
+            icon="i-ph-play-duotone"
+            :loading="pending[cmd.id]"
+            :disabled="pending[cmd.id] || isStatic"
+            @click.stop="emit('execute', cmd)"
+          >
+            {{ pending[cmd.id] ? 'Running…' : 'Run' }}
+          </ActionButton>
+          <span v-if="isStatic" class="note">read-only static backend — execution disabled</span>
+        </div>
+        <div v-if="results[cmd.id]" class="result">
+          <div class="result-head">
+            <span v-if="results[cmd.id].ok" class="ok">✓ resolved</span>
+            <span v-else class="fail">✕ threw</span>
+            <span v-if="'durationMs' in results[cmd.id]" class="muted">{{ results[cmd.id].durationMs }}ms</span>
+          </div>
+          <JsonView
+            v-if="results[cmd.id].ok"
+            :value="results[cmd.id].result"
+            :expand-depth="2"
+          />
+          <JsonView v-else :value="results[cmd.id].error" :expand-depth="2" />
+        </div>
+      </template>
+      <p v-else-if="!cmd.children?.length" class="note">
+        Group-only command — no handler to run.
+      </p>
+
+      <template v-if="cmd.children?.length">
+        <div class="label">
+          Children
+        </div>
+        <div class="cmd-children">
+          <CommandRow
+            v-for="child in cmd.children"
+            :key="child.id"
+            :cmd="child"
+            :args-input="argsInput"
+            :results="results"
+            :pending="pending"
+            :is-static="isStatic"
+            :depth="(depth ?? 0) + 1"
+            @execute="emit('execute', $event)"
+            @update-args="(id, value) => emit('updateArgs', id, value)"
+          />
+        </div>
+      </template>
+    </div>
+  </div>
+</template>
diff --git a/plugins/inspect/src/spa/components/CommandsSmart.vue b/plugins/inspect/src/spa/components/CommandsSmart.vue
new file mode 100644
index 00000000..5e7b5ced
--- /dev/null
+++ b/plugins/inspect/src/spa/components/CommandsSmart.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import type { DevframeInspectCommandInfo, InvokeResult } from '@devframes/plugin-inspect/client'
+import { onMounted, reactive, shallowRef } from 'vue'
+import { useRefreshProvider } from '../composables/refresh'
+import { isStatic, useRpc } from '../composables/rpc'
+import CommandsView from './CommandsView.vue'
+
+const rpc = useRpc()
+const commands = shallowRef<DevframeInspectCommandInfo[] | null>(null)
+const results = reactive<Record<string, InvokeResult | { ok: false, error: { name: string, message: string } }>>({})
+const pending = reactive<Record<string, boolean>>({})
+
+async function fetchData(): Promise<void> {
+  if (!rpc.value)
+    return
+  commands.value = await rpc.value.call('devframes:plugin:inspect:list-commands')
+}
+
+useRefreshProvider(fetchData)
+onMounted(fetchData)
+
+async function onExecute(cmd: DevframeInspectCommandInfo, parsedArgs: unknown[]): Promise<void> {
+  if (!rpc.value)
+    return
+  pending[cmd.id] = true
+  try {
+    results[cmd.id] = await rpc.value.call('devframes:plugin:inspect:execute-command', cmd.id, parsedArgs)
+  }
+  catch (e) {
+    const err = e as Error
+    results[cmd.id] = { ok: false, error: { name: err?.name ?? 'Error', message: err?.message ?? String(e) } }
+  }
+  finally {
+    pending[cmd.id] = false
+  }
+}
+</script>
+
+<template>
+  <CommandsView
+    :commands="commands"
+    :is-static="isStatic()"
+    :results="results"
+    :pending="pending"
+    @execute="onExecute"
+  />
+</template>
diff --git a/plugins/inspect/src/spa/components/CommandsView.stories.ts b/plugins/inspect/src/spa/components/CommandsView.stories.ts
new file mode 100644
index 00000000..f160bc67
--- /dev/null
+++ b/plugins/inspect/src/spa/components/CommandsView.stories.ts
@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import CommandsView from './CommandsView.vue'
+
+const meta = {
+  title: 'Inspector/CommandsView',
+  component: CommandsView,
+  tags: ['autodocs'],
+  argTypes: {
+    onExecute: { action: 'executed' },
+  },
+} satisfies Meta<typeof CommandsView>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    commands: [
+      {
+        id: 'demo:say-hello',
+        title: 'Say Hello',
+        description: 'Returns a greeting for the given name.',
+        category: 'demo',
+        icon: 'i-ph-hand-waving-duotone',
+        hasHandler: true,
+      },
+      {
+        id: 'vite:open-in-editor',
+        title: 'Open in Editor',
+        description: 'Opens a file at a line/column in the configured editor.',
+        category: 'vite',
+        hasHandler: true,
+      },
+      {
+        id: 'demo:group',
+        title: 'Demo Group',
+        category: 'demo',
+        hasHandler: false,
+        children: [
+          {
+            id: 'demo:group:child-a',
+            title: 'Child A',
+            hasHandler: true,
+          },
+          {
+            id: 'demo:group:child-b',
+            title: 'Child B',
+            hasHandler: true,
+          },
+        ],
+      },
+    ],
+    isStatic: false,
+    results: {},
+    pending: {},
+  },
+}
+
+export const Empty: Story = {
+  args: {
+    ...Default.args,
+    commands: [],
+  },
+}
+
+export const StaticMode: Story = {
+  args: {
+    ...Default.args,
+    isStatic: true,
+  },
+}
+
+export const WithResultsAndPending: Story = {
+  args: {
+    ...Default.args,
+    results: {
+      'demo:say-hello': {
+        ok: true,
+        result: 'Hello, Ada!',
+        durationMs: 8,
+      },
+      'demo:group': {
+        ok: false,
+        error: { name: 'Error', message: 'Command "demo:group" has no handler (group-only command)' },
+        durationMs: 1,
+      },
+    },
+    pending: {
+      'vite:open-in-editor': true,
+    },
+  },
+}
diff --git a/plugins/inspect/src/spa/components/CommandsView.vue b/plugins/inspect/src/spa/components/CommandsView.vue
new file mode 100644
index 00000000..de2c004c
--- /dev/null
+++ b/plugins/inspect/src/spa/components/CommandsView.vue
@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import type { DevframeInspectCommandInfo, InvokeResult } from '@devframes/plugin-inspect/client'
+import { computed, reactive, ref } from 'vue'
+import CommandRow from './CommandRow.vue'
+
+const props = defineProps<{
+  commands: DevframeInspectCommandInfo[] | null
+  isStatic: boolean
+  results: Record<string, InvokeResult | { ok: false, error: { name: string, message: string } }>
+  pending: Record<string, boolean>
+}>()
+
+const emit = defineEmits<{
+  (e: 'execute', cmd: DevframeInspectCommandInfo, parsedArgs: unknown[]): void
+}>()
+
+const search = ref('')
+const argsInput = reactive<Record<string, string>>({})
+
+function matches(cmd: DevframeInspectCommandInfo, q: string): boolean {
+  if (cmd.id.toLowerCase().includes(q) || cmd.title.toLowerCase().includes(q) || cmd.category?.toLowerCase().includes(q))
+    return true
+  return cmd.children?.some(child => matches(child, q)) ?? false
+}
+
+const filtered = computed(() => {
+  const list = props.commands ?? []
+  const q = search.value.trim().toLowerCase()
+  const matched = q ? list.filter(cmd => matches(cmd, q)) : list
+  return [...matched].sort((a, b) => a.title.localeCompare(b.title))
+})
+
+const categoryStats = computed(() => {
+  const stats: Record<string, number> = {}
+  for (const cmd of props.commands ?? []) {
+    const category = cmd.category ?? 'uncategorized'
+    stats[category] = (stats[category] || 0) + 1
+  }
+  return stats
+})
+
+function execute(cmd: DevframeInspectCommandInfo): void {
+  let parsed: unknown[]
+  try {
+    const raw = JSON.parse(argsInput[cmd.id] || '[]')
+    parsed = Array.isArray(raw) ? raw : [raw]
+  }
+  catch (e) {
+    throw new Error(`Invalid JSON args: ${(e as Error).message}`)
+  }
+  emit('execute', cmd, parsed)
+}
+</script>
+
+<template>
+  <div class="pane">
+    <div class="toolbar">
+      <label class="search">
+        <div class="i-ph-magnifying-glass-duotone" />
+        <input v-model="search" placeholder="Filter commands by id, title, category…" spellcheck="false">
+      </label>
+      <span class="muted">{{ (commands ?? []).length }} commands</span>
+      <span v-for="(count, category) in categoryStats" :key="category" class="muted">
+        <span class="badge flag">{{ category }}</span> {{ count }}
+      </span>
+    </div>
+
+    <div v-if="!commands" class="center">
+      Loading commands…
+    </div>
+    <div v-else-if="commands.length === 0" class="empty">
+      No commands registered — commands are a `@devframes/hub` feature; this connection isn't mounted inside a hub.
+    </div>
+    <div v-else-if="filtered.length === 0" class="empty">
+      No commands match "{{ search }}".
+    </div>
+
+    <div v-else class="fn-list">
+      <CommandRow
+        v-for="cmd in filtered"
+        :key="cmd.id"
+        :cmd="cmd"
+        :args-input="argsInput"
+        :results="results"
+        :pending="pending"
+        :is-static="isStatic"
+        @execute="execute"
+        @update-args="(n, v) => argsInput[n] = v"
+      />
+    </div>
+  </div>
+</template>
diff --git a/plugins/inspect/src/spa/style.css b/plugins/inspect/src/spa/style.css
index e2279464..f8483379 100644
--- a/plugins/inspect/src/spa/style.css
+++ b/plugins/inspect/src/spa/style.css
@@ -360,6 +360,47 @@ textarea.args:focus {
   font-style: italic;
 }
 
+/* ---- commands list ---- */
+.cmd-icon {
+  flex-shrink: 0;
+  color: var(--df-fg-dim);
+}
+
+.cmd-title {
+  font-size: 12.5px;
+  font-weight: 600;
+  flex-shrink: 0;
+}
+
+.cmd-id {
+  font-size: 11px;
+  color: var(--df-fg-faint);
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cmd-row-child .fn-head {
+  padding-left: 22px;
+}
+
+.cmd-children {
+  padding-left: 16px;
+  border-left: 1px solid var(--df-border-soft);
+  margin-left: 5px;
+}
+
+.cmd-children .fn-row {
+  border-top: none;
+  border-bottom: 1px solid var(--df-border-soft);
+}
+
+.cmd-children .fn-row:last-child {
+  border-bottom: none;
+}
+
 /* ---- state view ---- */
 .split {
   display: flex;
diff --git a/plugins/inspect/src/types.ts b/plugins/inspect/src/types.ts
index 9906730c..8eefb7e1 100644
--- a/plugins/inspect/src/types.ts
+++ b/plugins/inspect/src/types.ts
@@ -52,6 +52,27 @@ export interface RpcFunctionInfo {
   returnsSchema?: unknown
 }
 
+/**
+ * Serializable projection of a single command registered on a hub's
+ * commands host (`DevframeServerCommandEntry`/`DevframeCommandBase` in
+ * `@devframes/hub`), returned by `devframes:plugin:inspect:list-commands`.
+ * Populated only when this connection is mounted inside a hub — a plain
+ * devframe connection (no hub) returns an empty list.
+ */
+export interface DevframeInspectCommandInfo {
+  /** Unique namespaced command id, e.g. `"vite:open-in-editor"`. */
+  id: string
+  title: string
+  description?: string
+  /** Iconify icon string, or a theme-specific `{ light, dark }` pair. */
+  icon?: string | { light: string, dark: string }
+  category?: string
+  /** Whether the command carries its own handler (`false` for group-only parents). */
+  hasHandler: boolean
+  /** Static sub-commands, up to two levels deep (parent → children). */
+  children?: DevframeInspectCommandInfo[]
+}
+
 /**
  * Result envelope for `devframes:plugin:inspect:invoke`. Errors are
  * normalized to a serializable shape rather than thrown so the inspector
diff --git a/plugins/inspect/test/_utils.ts b/plugins/inspect/test/_utils.ts
index 3a3c49dd..412625de 100644
--- a/plugins/inspect/test/_utils.ts
+++ b/plugins/inspect/test/_utils.ts
@@ -1,7 +1,10 @@
+import type { DevframeHubContext } from '@devframes/hub/node'
 import type { StartedServer } from 'devframe/node'
+import type { DevframeNodeContext } from 'devframe/types'
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
+import { createHubContext } from '@devframes/hub/node'
 import inspectDevframe from '@devframes/plugin-inspect'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
 import {
@@ -29,16 +32,27 @@ export function assertSpaBuilt(): void {
   }
 }
 
-export interface InspectorServer extends StartedServer {
+export interface InspectorServer<Ctx extends DevframeNodeContext = DevframeNodeContext> extends StartedServer {
   basePath: string
+  ctx: Ctx
+}
+
+interface BootOptions {
+  /** Build the node context. Default: devframe's plain `createHostContext`. */
+  hub?: boolean
 }
 
 /**
  * Boot the inspector dev server in-process, mirroring the CLI adapter's
  * wiring (`auth: false` so the standalone server auto-trusts) but with a
  * controllable lifecycle. Bound to 127.0.0.1 to avoid the IPv4/IPv6 race.
+ *
+ * With `hub: true` the context comes from `@devframes/hub`'s
+ * `createHubContext`, so `ctx.commands` is a live host — the surface the
+ * Commands tab reads from when mounted inside a hub. Without it, the plain
+ * context exercises the no-hub path (empty list, thrown diagnostic).
  */
-export async function startInspectorServer(): Promise<InspectorServer> {
+async function boot(options: BootOptions): Promise<InspectorServer> {
   const distDir = inspectDevframe.cli!.distDir!
   const basePath = resolveBasePath(inspectDevframe, 'standalone')
   const host = '127.0.0.1'
@@ -54,7 +68,9 @@ export async function startInspectorServer(): Promise<InspectorServer> {
     },
   })
 
-  const ctx = await createHostContext({ cwd: process.cwd(), mode: 'dev', host: h3Host })
+  const ctx = options.hub
+    ? await createHubContext({ cwd: process.cwd(), mode: 'dev', host: h3Host })
+    : await createHostContext({ cwd: process.cwd(), mode: 'dev', host: h3Host })
   await inspectDevframe.setup(ctx)
 
   const metaPath = `${basePath}${DEVFRAME_CONNECTION_META_FILENAME}`
@@ -69,5 +85,15 @@ export async function startInspectorServer(): Promise<InspectorServer> {
     auth: false,
   })
 
-  return Object.assign(server, { basePath })
+  return Object.assign(server, { basePath, ctx })
+}
+
+/** Standalone boot — plain devframe context, no hub commands host. */
+export function startInspectorServer(): Promise<InspectorServer> {
+  return boot({})
+}
+
+/** Hub boot — `createHubContext` attaches a live `ctx.commands` host. */
+export async function startInspectorHubServer(): Promise<InspectorServer<DevframeHubContext>> {
+  return await boot({ hub: true }) as InspectorServer<DevframeHubContext>
 }
diff --git a/plugins/inspect/test/dev-server.test.ts b/plugins/inspect/test/dev-server.test.ts
index d5ae8ba3..7c5572a7 100644
--- a/plugins/inspect/test/dev-server.test.ts
+++ b/plugins/inspect/test/dev-server.test.ts
@@ -1,11 +1,12 @@
-import type { InvokeResult, RpcFunctionInfo } from '@devframes/plugin-inspect'
+import type { DevframeHubContext } from '@devframes/hub/node'
+import type { DevframeInspectCommandInfo, InvokeResult, RpcFunctionInfo } from '@devframes/plugin-inspect'
 import type { AgentManifest } from 'devframe/types'
 import type { InspectorServer } from './_utils'
 import { createRpcClient } from 'devframe/rpc/client'
 import { createWsRpcChannel } from 'devframe/rpc/transports/ws-client'
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 import { WebSocket } from 'ws'
-import { assertSpaBuilt, startInspectorServer } from './_utils'
+import { assertSpaBuilt, startInspectorHubServer, startInspectorServer } from './_utils'
 
 vi.stubGlobal('WebSocket', WebSocket)
 
@@ -53,6 +54,8 @@ describe('inspector dev-server', () => {
     expect(names).toContain('devframes:plugin:inspect:invoke')
     expect(names).toContain('devframes:plugin:inspect:list-state-keys')
     expect(names).toContain('devframes:plugin:inspect:describe-agent')
+    expect(names).toContain('devframes:plugin:inspect:list-commands')
+    expect(names).toContain('devframes:plugin:inspect:execute-command')
     // The built-in shared-state RPCs are always registered on the host.
     expect(names).toContain('devframe:rpc:server-state:get')
 
@@ -102,4 +105,105 @@ describe('inspector dev-server', () => {
     expect(toolIds).toContain('devframes:plugin:inspect:list-functions')
     expect(toolIds).toContain('devframes:plugin:inspect:describe-agent')
   })
+
+  it('list-commands returns an empty list outside a hub', async () => {
+    const rpc = connect(server)
+    const commands = await rpc.$call('devframes:plugin:inspect:list-commands') as DevframeInspectCommandInfo[]
+    expect(commands).toEqual([])
+  })
+
+  it('execute-command throws when this connection has no hub commands host', async () => {
+    const rpc = connect(server)
+    await expect(
+      rpc.$call('devframes:plugin:inspect:execute-command', 'anything', []),
+    ).rejects.toThrow(/no hub commands host/)
+  })
+})
+
+describe('inspector dev-server (hub)', () => {
+  let server: InspectorServer<DevframeHubContext>
+
+  beforeAll(async () => {
+    assertSpaBuilt()
+    server = await startInspectorHubServer()
+
+    server.ctx.commands.register({
+      id: 'demo:say-hello',
+      title: 'Say Hello',
+      description: 'Returns a greeting.',
+      category: 'demo',
+      handler: (name: string = 'world') => `Hello, ${name}!`,
+    })
+    server.ctx.commands.register({
+      id: 'demo:group',
+      title: 'Demo Group',
+      children: [
+        { id: 'demo:group:child', title: 'Child Command', handler: () => 'child ran' },
+      ],
+    })
+  })
+
+  afterAll(async () => {
+    await server?.close()
+  })
+
+  it('list-commands reports registered hub commands, with children and hasHandler flags', async () => {
+    const rpc = connect(server)
+    const commands = await rpc.$call('devframes:plugin:inspect:list-commands') as DevframeInspectCommandInfo[]
+    const byId = Object.fromEntries(commands.map(c => [c.id, c]))
+
+    expect(byId['demo:say-hello']).toMatchObject({
+      title: 'Say Hello',
+      description: 'Returns a greeting.',
+      category: 'demo',
+      hasHandler: true,
+    })
+
+    expect(byId['demo:group']).toMatchObject({ title: 'Demo Group', hasHandler: false })
+    expect(byId['demo:group'].children).toEqual([
+      expect.objectContaining({ id: 'demo:group:child', hasHandler: true }),
+    ])
+  })
+
+  it('execute-command runs a command handler and returns a result envelope', async () => {
+    const rpc = connect(server)
+    const result = await rpc.$call(
+      'devframes:plugin:inspect:execute-command',
+      'demo:say-hello',
+      ['Ada'],
+    ) as InvokeResult
+    expect(result).toMatchObject({ ok: true, result: 'Hello, Ada!' })
+    expect(typeof result.durationMs).toBe('number')
+  })
+
+  it('execute-command runs a nested child command by id', async () => {
+    const rpc = connect(server)
+    const result = await rpc.$call(
+      'devframes:plugin:inspect:execute-command',
+      'demo:group:child',
+      [],
+    ) as InvokeResult
+    expect(result).toMatchObject({ ok: true, result: 'child ran' })
+  })
+
+  it('execute-command reports an error envelope for a group-only command', async () => {
+    const rpc = connect(server)
+    const result = await rpc.$call(
+      'devframes:plugin:inspect:execute-command',
+      'demo:group',
+      [],
+    ) as InvokeResult
+    expect(result.ok).toBe(false)
+    expect(result.error?.message).toMatch(/no handler/)
+  })
+
+  it('execute-command reports an error envelope for an unregistered id', async () => {
+    const rpc = connect(server)
+    const result = await rpc.$call(
+      'devframes:plugin:inspect:execute-command',
+      'does-not:exist',
+      [],
+    ) as InvokeResult
+    expect(result.ok).toBe(false)
+  })
 })
diff --git a/plugins/inspect/test/static-build.test.ts b/plugins/inspect/test/static-build.test.ts
index 682f2c0d..c500c73b 100644
--- a/plugins/inspect/test/static-build.test.ts
+++ b/plugins/inspect/test/static-build.test.ts
@@ -44,9 +44,11 @@ describe('inspector static build', () => {
 
     // `invoke` is an `action` with no dump — it must not appear.
     expect(manifest['devframes:plugin:inspect:invoke']).toBeUndefined()
-    // The three snapshot `query` functions bake into the static dump.
+    // The snapshot `query` functions bake into the static dump.
     expect(manifest['devframes:plugin:inspect:list-functions']).toBeTruthy()
     expect(manifest['devframes:plugin:inspect:list-state-keys']).toBeTruthy()
     expect(manifest['devframes:plugin:inspect:describe-agent']).toBeTruthy()
+    // list-commands is a snapshot query too — bakes to an empty list outside a hub.
+    expect(manifest['devframes:plugin:inspect:list-commands']).toBeTruthy()
   })
 })
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ef26034b..ac8b8b86 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1287,6 +1287,9 @@ importers:
       '@antfu/design':
         specifier: catalog:frontend
         version: 0.3.2(@antfu/utils@9.3.0)(@iconify-json/catppuccin@1.2.17)(@tanstack/vue-virtual@3.13.30(vue@3.5.40(typescript@6.0.3)))(@unocss/core@66.7.5)(colorjs.io@0.7.0)(dompurify@3.4.12)(floating-vue@5.2.2(vue@3.5.40(typescript@6.0.3)))(playwright@1.61.1)(reka-ui@2.10.1(vue@3.5.40(typescript@6.0.3)))(splitpanes@4.1.2(vue@3.5.40(typescript@6.0.3)))(unocss@66.7.5(@unocss/postcss@66.7.5(postcss@8.5.19))(vite@8.1.5(@types/node@26.1.1)(esbuild@0.28.0)(jiti@2.7.0)(terser@5.47.1)(tsx@4.23.1)(yaml@2.9.0)))(vue@3.5.40(typescript@6.0.3))
+      '@devframes/hub':
+        specifier: workspace:*
+        version: link:../../packages/hub
       '@iconify-json/ph':
         specifier: catalog:frontend
         version: 1.2.2

From e685a69104d56928ba3be129a271bf53e5eb56a7 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 22 Jul 2026 07:50:02 +0000
Subject: [PATCH 2/2] test: update inspector client API snapshot for
 DevframeInspectCommandInfo

---
 .../tsnapi/@devframes/plugin-inspect/client.snapshot.d.ts        | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/__snapshots__/tsnapi/@devframes/plugin-inspect/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/plugin-inspect/client.snapshot.d.ts
index f0338af0..71f1a77e 100644
--- a/tests/__snapshots__/tsnapi/@devframes/plugin-inspect/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/plugin-inspect/client.snapshot.d.ts
@@ -8,6 +8,7 @@ export declare function connectInspect(_?: DevframeRpcClientOptions): Promise<De
 // #region Other
 export { AgentManifest }
 export { DevframeConnectionStatus }
+export { DevframeInspectCommandInfo }
 export { DevframeRpcClient }
 export { InvokeResult }
 export { RpcFunctionAgentInfo }