OS Action Contract

Purpose

The OS Action Contract defines how Alma should describe intended work before anything touches the shell, apps, workspace, artifacts, or future external systems.

AI should prefer structured OS actions over screenshot-based control.

Current Mock Actions

Current contract types live in @prox-os/app-contract and include:

open_app
focus_window
move_window
save_layout
restore_layout
render_artifact
pin_artifact
request_confirmation

The current executor is local UI logic inside the shell prototype. It can open registered apps, save a local layout snapshot, restore local layout hints, and create mock artifacts. It does not run backend tools.

Risk Levels

Low-risk actions:

open app
focus window
move window
save layout

Suggested policy: auto allowed with visible logs.

Medium-risk actions:

create artifact
pin artifact
change workspace settings

Suggested policy: ask every time or use lightweight confirmation.

High-risk future actions:

publish
share
deploy
external write
production data mutation

Suggested policy: disabled until a full confirmation, permission, and audit system exists.

Confirmation Design

Confirmation prompts should show:

action title
reason
risk level
required permissions
before and after preview where possible
approve and reject controls

Rejected actions must be logged. Approved actions must be logged.

Audit Direction

Every real action should become an audit event with:

actor
workspace
app or resource target
action type
risk level
input summary
confirmation status
timestamp
result
rollback hint when possible

Audit events should not contain raw API keys, secrets, or unredacted sensitive content.

Prompt Injection Boundary

Untrusted content cannot become system instruction. App content, web content, documents, artifacts, and user-owned data should be treated as input data unless the user explicitly promotes them into trusted instructions.

Backend Direction

Future apps/api-worker may host:

provider adapters
model router
BYOK handling
hosted AI credits
secure key vault
tool registry
workflow execution service
audit sink
artifact storage
app publishing pipeline
permission policy engine

None of those backend services are implemented in this task.