Command System Architecture

Position

@prox-os/command is the searchable command layer for Prox OS. It is designed for Command Palette, Universal Launcher, app search, action search, route jumps, docs jumps, recent commands, suggested commands, and future AI command entry.

It is not the current OS Shell launcher implementation, and it does not replace @prox-os/actions.

Actions are intents.
Commands are searchable entries that can resolve to actions, apps, routes, docs, URLs, or AI prompts.

Command vs Action

@prox-os/actions owns the intent:

• OsAction
• OsActionTarget
• OsActionContext
• OsActionResult
• OsActionHandler

@prox-os/command owns discovery and selection:

• OsCommand
• OsCommandContext
• OsCommandProvider
• OsCommandGroup
• OsCommandPalette
• ranking and grouping helpers
• v0 Studio command types: Command, CommandContext, and CommandProvider

The dependency direction is one-way:

@prox-os/command -> @prox-os/actions
@prox-os/actions -X-> @prox-os/command

This prevents a circular dependency between intent and command surfaces.

Command Palette vs OS Shell

The OS Shell already owns global runtime concerns:

• global keyboard listener;
• shell command open/close state;
• app registry composition;
• window manager app opening;
• route navigation;
• recent app persistence.

@prox-os/command owns reusable primitives:

• command types;
• provider contracts;
• action-to-command adapters;
• palette/list/input/item/preview UI;
• local search/ranking helpers;
• Storybook examples.

Future Shell integration should look like:

OS Shell owns Mod+K / Ctrl+K listener.
OS Shell gathers commands from app registry and active providers.
Command package renders the palette.
User selects a command.
OS/app runtime executes app open, route navigation, action handler, URL open, or AI flow.

The package must not import apps/os-shell private command palette, window manager, registry, or Zustand store modules.

The current shell-owned CommandSurface in @prox-os/os-ui is intentionally a dense desktop command surface: it can be dragged by its header, uses a bounded tall viewport, groups results into compact columns where space allows, and keeps route paths in the preview details instead of repeating them in the left result list.

Provider Model

Phase 1 provider shape:

type getCommands = (context: OsCommandContext) => OsCommand[] | Promise<OsCommand[]>

This keeps providers simple enough for:

• core commands;
• app registry commands;
• docs commands;
• settings commands;
• recent commands;
• AI suggestions;
• future plugin commands.

It is not a security boundary. Future Shell/runtime layers must still filter commands by permissions, environment, workspace, and active selection.

The Studio System adds a smaller v0 protocol for the Global Command Surface:

export type CommandContext = {
  studioId?: string
  studioEngineId: StudioEngineId
  activeAppId?: string
  activeSurfaceId?: string
}

export type CommandProvider = {
  id: string
  label: string
  getCommands: (context: CommandContext) => Command[]
}

This protocol lets Studio Engines expose context-aware commands without making @prox-os/command import Shell state. The current Shell keeps runtime execution in apps/os-shell/src/shell/state/useCommandModel.tsx.

Keyboard Shortcut Boundary

OsCommandShortcut only displays shortcuts. OsCommandLauncherButton can show Mod+K or Ctrl+K, but the package does not install a global keyboard listener.

Future direction:

• OS Shell handles global Mod+K / Ctrl+K.
• Mod+K / Ctrl+K opens the viewport-level Global Command Surface across the workspace and Alma.
• Cmd+K becomes the spatial command surface for summon, generate, open, connect, and execute proposals, with execute-class work gated by permission preview, manual confirmation, audit logs, and cost budgets.
• Future @prox-os/shortcuts or a command extension can own shortcut registry.
• Command items can display shortcuts without becoming the keyboard manager.
• Apps should not each register their own global command listener.

Future Integrations

Phase 1: Command Contract and UI Primitives

• Command types and provider types.
• Action-to-command, app-to-command, and URL-to-command helpers.
• Local grouping, filtering, and ranking.
• Command palette primitives.
• Storybook examples.
• Package and architecture docs.

Phase 2: OS Shell Integration

• Global Mod+K / Ctrl+K listener remains in the Shell.
• Shell gathers commands from app registry.
• Open app, route, and URL commands execute for real.
• Recent commands persist locally.

Phase 3: App-Contributed Commands

• Apps contribute scoped commands.
• Active window contributes context commands.
• Selection-aware commands.
• Provider-level permission filtering.

Phase 4: Search and AI Commands

• Resource search results appear in the command palette.
• Natural language command entry.
• AI command suggestions.
• Agent tool proposals.

Phase 5: Permissions, Audit, and Backend Integration

• Command visibility comes from permissions.
• Sensitive commands require confirmation or human approval.
• Execution emits audit events.
• Async command execution reports observable success/failure state.

Non-Goals

• No OS Shell launcher rewrite.
• No real global shortcut listener.
• No complete search engine.
• No backend command execution.
• No permission, audit, or agent runtime enforcement.