Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
The Alfa contract
What an Agent, a Playbook, a Tool and a Skill each are in MSO, where the single source of truth for each lives, and what actually reaches the model.
Written because four of these had drifted into fiction: a 45-entry tool catalog the model could never call, agent tool-scoping that configured nothing, and two unrelated things both called "skill".
Where this lives, and how to not lose it. Alfa personas, Playbooks and browser Automations are per-browser localStorage (
alfa.*), so clearing site data destroys them and there is no server copy. Settings → Backup exports every mso-owned key as one JSON file and imports it back. Thealfa.prefix is matched by rule, so a newalfa.somethingkey is covered automatically; a key outside every prefix has to be added toMSO_LOCAL_STATE.extrainappshell/lib/local-state.tsor it silently will not be in the backup.
Tool
An operation the model can actually invoke. If it is not here, Alfa cannot do it — this is the whole list for Alfa.
It is NOT the whole list for the box. lib/mcp/tools.ts is a second, deliberately
separate catalog for MCP clients (ChatGPT / Claude.ai / Cursor) — different
transport, different guard (a scope tier, not an approval card), different
handlers. See docs/MCP.md. The two are allowed to differ; they are not allowed
to differ by accident, which is what the coverage test in
frontend/slices/assistant/host-tools/registry.test.ts exists to catch.
| Shape | HostTool — frontend/slices/assistant/host-tools/types.ts |
| Source of truth | host-tools/catalog.ts (read) + catalog-mutate.ts (mutate) → HOST_TOOLS |
| Lifecycle | Static array, compiled in |
| Written by | Developers only |
Every tool declares effect:
read— runs immediately.mutate— parks an approval card and waits for a human before touching the VPS. The rendezvous isappshell/lib/alfa-approvals.ts, so any surface showing the card can answer it (the Assistant app, the desktop dock, the mobile sheet).
group and label are presentation only and are never sent to the model.
OS_TOOLS (lib/tools.ts) is a view of HOST_TOOLS for the pickers. It is
derived, never authored. lib/tools.test.ts fails if the two ever diverge.
Playbook (the localStorage Skill type)
A named bundle of instructions a user assembles. Shown in the Assistant's Playbooks tab.
| Shape | Skill — lib/types.ts |
| Source of truth | localStorage["alfa.skills"], seeded from PRESET_SKILLS |
| Lifecycle | Per browser, user-editable |
| Written by | The user, via the Playbooks tab |
Tool ids are MIGRATED on read (lib/store.ts migrateRows), not dropped: a bundle
saved before the catalogs converged has its old ids mapped to the current ones, and
only ids that never had an executable counterpart are removed. Dropping instead of
mapping would have emptied the five builtin bundles for every existing install —
store-migration.test.ts is what holds that line.
Naming. The persisted TypeScript type remains
Skillfor compatibility, but the product surface calls it Playbook. This avoids colliding with hostSKILL.mdwhile preserving existingalfa.skillsbackups and migrations.
Skill (a SKILL.md on disk)
A markdown playbook on the host. Nothing to do with the type above: different shape, different storage, different lifecycle, and the names do not overlap.
| Shape | { id, name, path, description, source, trust, project?, provenance? } — lib/skills/catalog-types.ts |
| Source of truth | GET /api/skills — explicit operator root → official repo skills → hash-verified bundles → generic HOME discovery roots → per-project roots of every project on the box |
| Lifecycle | Files on disk; trust is derived from root/provenance/ownership, never self-declared by the skill |
| Written by | MSO, the operator, a project checkout, or discovered agent registries |
The model reaches trusted skills through the skills.list, skills.search and skills.read tools. official, hash-verified, explicit operator local and ownership-verified project skills are executable by default; generic discovered skills are cataloged as untrusted but their instructions are not fed directly to the model. /skill follows the same trust filter. There is no separate execution path.
Discovery is global, and addressed by id. Skills come from every project across
every configured project container (each OS_FS_READ_ROOTS entry and its projects/
child), from .mso/skills, .claude/skills, .hermes/skills, .agents/skills and
.codex/skills. A global skill's id is its bare name; a project skill's is
<rootId>/<project>/<name>, where rootId is a 128-bit hash of the canonical container
path (32 bits collided in practice) — so two projects with the same basename in
different configured roots stay distinct, and neither can shadow an operator or official skill. A project skill earns
local trust only after realpath containment inside its project, ownership by MSO's uid,
and a regular non-symlink SKILL.md; the generic HOME agent roots stay untrusted.
skills.read takes the exact id and refuses an ambiguous bare name rather than guessing.
Every response carries a scan report, so a truncated catalog is never presented as
complete. See docs/MCP.md and skills/README.md.
Organization (not an Alfa persona)
Organization is a first-class app/domain with a secondary Organization tab inside Alfa. Both render the same server-side owner-private SSOT at ~/.mso/private/organization.json via lib/agent/organization-store.ts; Alfa does not own or duplicate it. Units and seats define stable hierarchy/reporting context; a seat can point at an existing Project Agent, Local Agent/session, or A2A peer. Those references grant no extra tools or credentials. Workflows may resolve orgSeatId at execution time. See docs/ORGANIZATION.md.
Browser persona (the localStorage Agent type)
A browser persona. This legacy type does not select a saved server profile.
| Shape | Agent — lib/types.ts |
| Source of truth | lib/store.ts — a MODULE store over localStorage["alfa.agents"] |
| Lifecycle | Per browser, user-editable |
| Written by | The user, via the Agents tab or an @mention pick |
The store is module-level (same shape as appshell/lib/alfa.ts), so the Alfa sheet
and the desktop dock can read and switch the agent without the Assistant app being
mounted. Read it with activeAgent() — never cache it in a ref: sendToAlfa
can invoke the engine synchronously in the same tick as a switch, so a ref would
still hold the previous agent and the first turn after an @mention would carry
the wrong persona.
Saved agent profile
An Owner device's persistent configuration for a foreground read task. The
Agents tab opens ProfilesPanel; Browser personas remains a separate selection.
lib/contracts/agent-profile.ts defines the DTO, lib/agent/profile-store.ts owns
private revisioned state, and /api/v1/agent-profiles derives the principal from
the live Owner session. Create, edit, clone, default, enable and disable persist
through compare-and-swap revisions. Browser backup does not include this state.
/api/v1/agent-profiles/run binds an exact saved revision and model connection to
the shared provider-neutral bounded runner. The server enforces the saved subset
of nine reviewed read capabilities and rechecks Owner authorization, enabled state
and revision before and after model/tool steps and before returning the result.
Each task starts a native session with no inherited browser history or memory.
This is partial NK009–NK010: organization moves, assignment, writes, execution,
external workers and process isolation remain unsupported. See
docs/AGENT-PROFILES.md for the exact contract.
Alfa Cockpit: one execution surface, existing sources of truth
The Assistant chat now has a compact Cockpit bar + responsive panel (desktop side panel, mobile drawer). It is a presentation/read-model over existing MSO domains, not a second runtime:
GET /api/v1/alfa/cockpitowner-gates and aggregates model selection, bounded/searchable project discovery, selected-project Git/package/capabilities/knowledge metadata, native session summaries, same-principal local-agent presence, the legacy Alfa fact count, and typed-memory state.- Project search has a lightweight
?q=path so the first bounded page is not treated as the whole host. A truncated scan is shown as incomplete rather than as an absence claim. - The selected project id persists under
alfa.selectedProject, so Settings → Backup includes it automatically. The loaded snapshot is shared with the dock/mobile Alfa surface. - Host
SKILL.mdrows stay on the existing/api/skillsSSOT and lazy-load only when Cockpit opens.untrustedrows are visible for review but are not one-click executable; trusted rows send an exact-idskills.readrequest through Alfa's existing host-tool loop. - Typed memory is owner-visible as metadata/current records, but non-
normalkeys/values are masked asPrivate memory. RawKNOWLEDGE.mdcontent and raw repo-memory bodies are not copied into the Cockpit response. Activity & Runsmerges client-side Alfa host-tool events with server MCP workflow activity only at the presentation layer. The execution engines remain separate; this is observability, not a fake shared workflow id.- Native MSO Agent sessions shown in Cockpit are read-only summaries and are explicitly separate from Alfa's browser YAML chat threads.
- Provider/credential management remains Settings' responsibility. Cockpit can switch/test provider + model only among providers that are already connected; it never creates, copies, or exposes credentials.
- Connected providers include environment-backed built-ins. Model-only configuration keeps the active provider; provider changes choose that provider's default or declared model, and Codex requires an explicit account model. Custom providers without a model connect without changing the active selection. Codex's connection test performs a short inference through Alfa's existing streamer, with a 30-second timeout, rather than treating model-list access as chat readiness.
Browser Automations likewise do not introduce a second executor. Run turns the saved ordered recipe into one Alfa task; the normal host-tool schemas, server guards, and approval rendezvous remain the execution path.
What reaches the legacy browser-chat model
Exactly three things, assembled in chat-panel.tsx:
- System prompt —
composeSystem(agent, modeNote, projectContext)inlib/agent-request.ts, the ONE place that decides this. It containsHOST_SYSTEM, the live/mock note, an optional bounded selected-project metadata snapshot, then the active agent's name/persona. Raw knowledge and repo-memory bodies are not injected. It is rebuilt every turn, so agent/project switches take effect on the next request. Because the route has one cache breakpoint at the end of the system block, a changed persona/project suffix can still miss that provider cache; keeping the global tool array stable avoids adding another source of prompt-prefix variation. - Tools —
HOST_AI_TOOLS, i.e. all of them, always. See the scoping decision. - History — the wire turns. Nothing else. The persona is not in here.
Callers with their own tools pass their own system prompt. The image editor does
not, so it runs on the route default in app/api/assistant/route.ts — that
constant is reachable and must not be deleted as dead.
Legacy browser persona and public MCP catalog contract
Every browser persona gets every legacy host tool, on every turn — no
per-persona, per-playbook or per-project filter. registry.test.ts pins it: the
HOST_AI_TOOLS array is the whole catalog in catalog order, it is the same object on
every turn, and registry.ts exports nothing that could narrow it. MCP holds the same
invariant on its own side — an exec token sees and can call the entire catalog, and
the read/write/exec ladder is the only thing that narrows it (lib/mcp/global-tools.test.ts).
Saved profiles use their explicit read-task endpoint and server-side capability
authority. They do not reinterpret the persisted Agent.allTools or Agent.skills
fields, change HOST_AI_TOOLS, or alter the public MCP catalog/cache signature.
Four reasons, and the third is the one that settles it:
- The lock is already there and it is better. Every
mutatetool parks on a per-call approval card, under a server-side path jail. A per-agent grant list is a second lock on a door that asks for a key every single time. - It has never been a security boundary.
lib/host/*is. The approval gate is an additional human layer, whichuse-host-commands.tsalready says in a comment. - A per-agent tool array would cost real money. The tools block sits before
systemin the cached prefix, andapp/api/assistant/route.tsmarks the system blockcache_control: ephemeral. Forking the tool array per agent means a cold prompt cache on every agent switch — a BYOK bill for a feature that grants nothing. - It makes an impossible state impossible. With one tool set, a thread whose
history holds
tool_usefor a tool "the new agent lacks" cannot occur.
Reaffirmed 2026-08-20 when MCP gained global project/skill discovery: capability scoping stayed deleted on both surfaces, and the removed MSO image generation was NOT replaced by a per-agent toggle.
Extended 2026-08-21 for project function calling: project-specific function names
remain DATA, never additions/removals to the model tool array. MCP exposes the stable
project_capabilities + project_function_call pair; a project may opt in with
.mso/functions.json. Alfa keeps its existing stable host catalog and can use project
skills/files + approved exec.run; no project switch changes its cached tool prefix. Done 2026-07-30. The tool picker, the "Generalist / Curated — by skill" switch,
the per-agent Skills grant list and every string that counted tools per agent are
gone; toolsForAgent() went with them. agent.allTools and agent.skills remain on
the type because they are persisted and store-migration.test.ts covers them — they
are inert data now, not a grant. A release-gate audit caught this still shipping: a
preset agent rendered "Ops · 2 skills · 11 tools" while all 18 were sent, so someone
curating a System-only agent was handing the model fs.read over their whole read
jail and believing otherwise.
Known gaps — stated, not hidden
/api/skillsis uncached,force-dynamic, and now walks the global roots PLUS every project's skill roots on each call. Every cap is enforced and reported, so the worst case is bounded. Alfa Cockpit therefore lazy-loads Host Skills only when the cockpit opens; a TTL cache remains the obvious next optimization.
Closed
Playbook starter prompts were dead data—Skill.startersnow feed the chat empty-state quick actions, deduplicated and bounded.Browser automations only narrated steps— Run now sends the ordered recipe through Alfa's normal host-tool loop; reads execute and mutations keep the same approval cards.— the browser-local product surface now says Playbooks; persistedSkilland hostSKILL.mdboth appeared as “Skills”alfa.skillsremains compatible.— the store is module-level and a pick carries@agentis cosmeticMentionItem.onPick, which switches the active agent. Verified on a phone: picking@Opswritesalfa.activeAgent.The persona is a fake user turn— it iscomposeSystem(), per request.