Alma Sidecar

Summary

Alma is the shell-level sidecar and host-side AI Control Plane for Prox OS. It is not a normal desktop app window and it is not a generic chatbot. It is a persistent Shell Surface that can sit on the left or right edge of the host, resize the available workspace area, show structured workflows, and make OS actions visible before they become real execution.

Alma is outside the workspace but aware of it.

For the current control-plane layout model, see alma-control-plane.md.

Current implementation status:

• UI and local workflow prototype inside apps/os-shell.
• Host-side layout posture with a workspace-contained command palette and Community overlay.
• No real AI provider call.
• No apps/api-worker business route.
• No database table, queue, cron, worker, secure vault, or provider adapter.

Personal Data Query Direction

Alma is not a normal chat box. Long term, it should become the OS-level query layer over connectors, track apps, scene app records, sports memories, Spaces, and OS review surfaces.

Future Alma should be able to read scoped summaries from:

• /app-connectors: external connector status, import readiness, staged source records, permission scopes, disconnect state, and cache deletion status.
• /app-track: People, Places, Devices, Money, Sources, and AI Context.
• /app: scene records such as Food, Work, Books, Series, Music Memory, Documents Vault, AI Team, AI Medium, Game Records, Movies, Madrid, Events, Tickets, Photo Roll, Wishlist, Reading, Bookmarks, Podcasts, Awesome GitHub Radar, RSS Knowledge Inbox, and Stock Track.
• /app-sports: sport-specific memory records such as Football Fan Passport, matchdays, stadiums, jerseys, practice logs, race weekends, runs, rides, hikes, and Olympics memories.
• /app-spaces: work surfaces such as Proxied Spaces, Slidepad, and Deployment Spaces.
• /app-os: system logs, Today, Weekly Review, display settings, and OS-level review surfaces.

Representative future questions:

• What did I do in Madrid this month?
• Who did I eat with, watch movies with, or play games with most recently?
• Which spending felt most valuable instead of merely cheapest?
• Which records were AI inferred and still need confirmation?
• Which prompt trail supports this AI Medium article?
• Which records came from Airtable, Steam, Letterboxd, sports connectors, ticket imports, RSS, social links, manual entry, or uploaded files?
• Which Football memories include Madrid, a specific friend, a jersey, or a ticket stub?
• Which deployments changed this week and which Space should I open to inspect them?

Alma answers must show data provenance. A useful answer should be able to cite the source, connector, track entity, scene app record, sports memory, Space, and whether any claim was AI inferred. If the answer cannot show provenance, it should say so.

Life Timeline is not a standalone source app in v0. It is a view Alma, Today, Weekly Review, Yearly Review, Life Lens, and custom dashboards can build from track apps, scene records, sports memories, and Spaces.

Why Alma Is A Shell Surface

Normal OS apps are launched through the app registry and rendered in managed windows. Alma is different:

• It is fixed to the workspace edge instead of appearing in the window stack.
• It does not show in the normal active window list.
• It changes available workspace bounds so windows remain inside the visible desktop.
• It can show OS action plans, operation logs, confirmation prompts, pinned artifact state, and future memory or agent panels.
• It is closer to shell chrome, command palette, and system drawers than to an app interior.

This keeps OS control visible and auditable. The user should always understand whether the sidecar is only drafting text or asking to act on the OS.

Current Desktop Behavior

The MVP+ surface supports:

• Right-side default placement.
• Left or right placement through Display Options.
• Drag resize with a side handle.
• Collapse and close states.
• Workspace shrinking through the shell layout, so WindowLayer measures the remaining desktop area.
• Model selector in the composer footer using the shared SelectControl primitive, matching common AI chat surfaces.
• Header icon buttons for settings, collapse, and close actions.
• Safety mode selector as local UI state.
• BYOK settings dialog stored locally for prototype use only and rendered as a global WindowDialog.
• Workflow Cards, Action Plan, Live Operation Log, Artifact panel, Workspace Generator, Memory/Data Graph placeholder, Permission section, Workflow Store teaser, Community Signals placeholder, and Agent Room placeholder.

Relationship With ChatOS

ChatOS is app mode. It is the archive and text surface for historical conversations and AI logs. It can open ordinary apps through the app runtime contract, but it should not directly control shell layout.

Alma is sidecar mode. It can present and eventually execute OS actions such as opening apps, arranging windows, saving layouts, restoring layouts, creating artifacts, pinning artifacts, or asking for confirmation.

Shared direction:

• Use common AI/OS action types from @prox-os/app-contract.
• Keep ChatOS focused on history, text, and logs.
• Keep Alma focused on action, workflow, approval, artifact, and workspace control.

OS Action Contract Direction

AI actions should be structured, typed, scoped, and auditable. The current prototype uses mock actions such as open_app, save_layout, restore_layout, render_artifact, pin_artifact, and request_confirmation.

Future action execution should:

• Resolve actions against app registry and window manager contracts.
• Require confirmation for medium-impact and high-impact work.
• Prevent untrusted app, document, web, or user content from becoming system instruction.
• Keep API keys, secrets, and vault material outside model context.
• Write action events to an audit sink.

App AI Capability Manifest Direction

Future app manifests can declare AI capability hints without allowing arbitrary agent control:

• readable resources
• writable resources
• available actions
• required permissions
• artifact output types
• safety notes
• audit labels

The shell should use those declarations to decide what Alma can suggest, what it can run locally, and what requires user confirmation.

Security And Audit Direction

Alma should treat every action as a permissioned OS event:

• Low-risk actions can be auto allowed, such as open app or focus window.
• Medium-risk actions should ask, such as create artifact or change workspace settings.
• High-risk actions should be disabled or require strong confirmation, such as publish, share, deploy, or external write.

Future apps/api-worker may host provider adapters, model router, secure key vault, tool registry, workflow execution service, audit sink, artifact storage, permission policy engine, and app publishing pipeline. Those services are not implemented in this task.