Actions Architecture

Position

@prox-os/actions is the frontend action intent layer for Prox OS. It defines how apps describe "what should happen" without deciding "how it must execute."

The package is intentionally small: contracts, common actions, helpers, React primitives, examples, and Storybook coverage. It is not the OS Shell private right-click menu, not a command palette implementation, not a backend permission engine, and not an AI agent executor.

Action package emits action intent.
OS or app runtime owns actual execution.

Intent vs Execution

Action intent answers:

What action is requested?
What target does it apply to?
Where did it come from?
What state is it in?
Is it destructive, disabled, hidden, or permission-sensitive?

Execution answers:

Can the current user perform it?
Should a confirmation dialog appear?
Should the action open an OS window, call an API, run a tool, or copy text?
Which audit event should be emitted?
What notification, trace, or result should be recorded?

Phase 1 only handles intent and local UI primitives. Future runtime layers decide execution.

Contract Shape

OsAction describes reusable action metadata:

id
label
description
group
icon
shortcut
state
disabled
hidden
destructive
requiresConfirmation
permissionHint
targetTypes

OsActionTarget describes the resource:

app
window
url
file
media
map-location
dataset
record
chart
notification
user
workspace
agent
unknown

OsActionContext describes the source:

context-menu
toolbar
command-palette
keyboard-shortcut
resource-card
app-launcher
dock
ai-agent
system
unknown

OsActionResult describes a local or future runtime result. It is intentionally plain so UI stories, shell adapters, and backend APIs can all map to it.

The system context menu is owned by the OS Shell, not @prox-os/actions.

Future flow:

Resource component emits action target and action list.
OS Shell opens a system context menu.
User selects an action.
OS or app runtime executes the handler.
Permissions, audit, observability, and agents participate later.

Package boundary:

@prox-os/actions must not import apps/os-shell.
@prox-os/actions must not import packages/apps/system-apps.
@prox-os/actions must not call backend services.
Components receive onAction callbacks from the host.

Command Palette Direction

Future @prox-os/command should not redefine actions.

Command item = searchable action + context + handler.

Command palette ranking, fuzzy search, shortcut binding, and execution history belong in the future command package or Shell adapter. Shared action metadata comes from @prox-os/actions.

Package Relationships

@prox-os/media: open, copy, save, inspect, transform, and media-library actions.
@prox-os/maps: save place, copy coordinates, route intents, inspect feature, and source data actions.
@prox-os/data-table: record actions, view actions, export actions, and AI summary actions.
@prox-os/data-viz: chart actions, export actions, inspect actions, and AI explanation actions.
Future @prox-os/permissions: action availability and permission hints.
Future @prox-os/audit: action execution events.
Future @prox-os/agents-runtime: proposed actions, human approval, and tool calls mapped to auditable actions.
Future @prox-os/api-contract: action execution API shapes.

Phase 1: Action Contract and UI Primitives

OsAction types.
Common URL, resource, and AI actions.
Group, filter, label, target, and result helpers.
OsActionButton, OsActionMenu, OsActionToolbar, OsActionList, OsActionCard, and OsActionStatusBadge.
UI Workshop stories.
Package and architecture docs.