Skip to content

armgit / mso

Public Imported from GitHub
0

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.

docs(plugin): clarify extension taxonomy

Rahman565a88e5110f
diff --git a/claude-skills/mso/SKILL.md b/claude-skills/mso/SKILL.md
index acf288f3..679f2872 100644
--- a/claude-skills/mso/SKILL.md
+++ b/claude-skills/mso/SKILL.md
@@ -22,6 +22,19 @@ Choose the least-powerful capability that can finish the task:
Never choose Bash merely because it is shorter for a simple operation. For repository-wide work, one scoped terminal batch is safer and faster than many disconnected discovery calls. The permission boundary remains a feature. Before destructive actions, service topology changes, credential changes, production rollback, or deleting data you did not create in the current task, require explicit human approval.
+## Capability selection — reuse before adding
+
+Treat `Skill`, `Project Plugin`, `MCP`, `Integration`, `App`, and `Managed App` as different authority domains, not synonyms. Before installing or creating anything:
+
+1. Use an existing bounded/native MSO capability if it already completes the task.
+2. For a selected project, inspect its declared functions/MCP before adding another project plugin or server.
+3. For credential-dependent provider work, inspect native Integrations and reuse the exact existing user/provider/connection when it matches. Do not ask for pasted credentials or create a duplicate connection first.
+4. Use a trusted skill when the missing piece is reusable procedure/routing knowledge rather than a new executable capability.
+5. Install a Project Plugin only for the exact project that needs it, after inspection. Catalog presence is not installation and nothing is inherited from another project.
+6. App/App Store state controls workspace UI; Managed App state controls an external runtime. Neither substitutes for MCP authorization or Integration credentials.
+
+When a useful external capability is unavailable, continue any independent work and state the exact missing connection/capability rather than treating setup as proof of completion. Verify connection/install state before using or claiming it.
+
## Resolve the install — never hardcode a username/path
```bash
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f078548b..9fbc3188 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -79,7 +79,39 @@ Cross-slice imports go through the public slice barrels. Host-facing code is cen
a client slice calls its adapter/API contract, an API route calls `lib/host`, and neither
route nor component reimplements path-jail or process guards.
-## 3. AppShell
+## 3. Extension taxonomy
+
+MSO uses several extension concepts because they own different authority. They are **not** aliases for one generic plugin object. Use the narrow term that matches the lifecycle being changed:
+
+| Term | What it owns | State / authority | Do not confuse with |
+|---|---|---|---|
+| **Skill** | Trusted reusable instructions and routing policy (`SKILL.md`, optional structured contract/resources). | Skill trust (`official / verified / local / untrusted`) controls whether instructions may be model-loaded. A skill does not grant credentials or tool permission. | MCP server, Integration, executable app. |
+| **OpenAI/Codex plugin package** | Distribution metadata for reviewed skills plus an optional registered-app mapping (`.codex-plugin/plugin.json` + `.app.json`). | Packaging only. The package does not authorize the live MSO MCP server. | MSO Project Plugin, registered app, MCP authorization. |
+| **Registered app** | External platform identity referenced by `.app.json` when an exact real app registration exists. | Platform-owned install/connection/permission state. MSO keeps the mapping empty until an exact registration exists. | Generic MSO Integration or Project Plugin. |
+| **Project Plugin** | A reviewed portable capability package that can declare skills and an MCP binding for one exact project. | Catalog presence never means installed. `project_mcp_manage` installs/removes only the selected project and uses revision guards. | Global plugin install, Skill Market entry, Integration credential. |
+| **MCP** | Protocol/transport boundary for structured tools. This includes MSO's own `/mcp` and project-declared MCP servers. | Tool schemas are discovered from the selected server; OAuth/project policy and call-time guards remain authoritative. | Package identity or credential storage. |
+| **Integration** | Credential identity and provider routing: credential user → provider → named connection → source/backend → auth method. | Native Integrations is the credential authority; secrets stay outside ordinary model/tool arguments. | MCP itself, Project Plugin, App. |
+| **App** | AppShell user-interface application or feature surfaced inside the MSO workspace. | UI install/toggle state belongs to the shell/app registry. | Managed service runtime or MCP capability. |
+| **Managed App** | External runtime/service that MSO installs or operates, such as Hermes, OpenClaw or 9Router. | Host/service lifecycle, health, version, backup/update/uninstall state. | App Store entry, Integration, Project Plugin. |
+| **Skill Market** | Curated source of reviewed skill bundles. | Install state is local skill state (`installed / modified / conflict / not-installed`); removal refuses unmanaged content. | General app/plugin marketplace. |
+| **App Store** | MSO shell catalog for UI apps/features. | Presentation/install state in the workspace. | OpenAI plugin directory, Project Plugin catalog, Managed App registry. |
+
+### Capability selection order
+
+For agent routing, reuse before adding another extension:
+
+1. Use an existing bounded/native MSO capability when it already completes the task.
+2. Use an already-declared exact-project function or MCP capability when that project owns the operation.
+3. For credential-dependent provider work, resolve an existing **Integration** before asking for setup or creating another connection.
+4. Use an existing trusted **Skill** when the missing piece is reusable procedure/routing knowledge rather than executable capability.
+5. Inspect before installing a **Project Plugin**; add one only when the selected project genuinely needs the packaged capability. Never infer global or parent-project installation.
+6. Use **App** / **Managed App** lifecycle only when the request is about workspace UI or an external runtime/service.
+
+A store/catalog is discovery metadata, not execution authority. Likewise, package metadata, a rendered widget, or the existence of a connection record never substitutes for the underlying scope, trust, revision, confirmation, provider and postcondition checks.
+
+The cross-reference audit that informs this taxonomy lives in [`PLUGIN-REFERENCE-MATRIX.md`](./PLUGIN-REFERENCE-MATRIX.md).
+
+## 4. AppShell
`frontend/slices/appshell/` is the generic shell framework. `os-shell` is the thin MSO
consumer that supplies brand, app manifest, shell choice and capabilities.
@@ -106,7 +138,7 @@ same app/window state. Phone portrait resolves to a mobile shell; phone landscap
the desktop surface according to the responsive policy. App windows themselves remain the
same feature code.
-## 4. Addressable routing without page-per-app duplication
+## 5. Addressable routing without page-per-app duplication
MSO uses one catch-all application route, `app/[[...slug]]/page.tsx`. The focused app is
mirrored into the URL while window state remains client-side. App slugs are assigned in
@@ -144,7 +176,7 @@ sandboxed. The MCP widget origin comes from `OS_MCP_UI_ORIGIN`, or is derived fr
origin remains deployment-owned and retains its deny-framing headers. The split prevents convenient
HTML/runtime extensibility from becoming a CSP privilege-escalation path.
-## 5. Host API and filesystem model
+## 6. Host API and filesystem model
`/api/v1/*` is the authenticated host API. Important families include:
@@ -180,7 +212,7 @@ cache-only and exposes no apply action. These are MSO roles over one Unix proces
identity directory, Linux-user switch, or tenant boundary. Appearance/Theme/Quicklinks are still a
single deployment-wide prefs document: delegated devices read it; Owner is the only writer.
-## 6. Alfa versus MCP
+## 7. Alfa versus MCP
Alfa and MCP are two separate model-facing catalogs on purpose.
@@ -198,7 +230,7 @@ The exact full transport catalog and ChatGPT model profile are generated from so
See `docs/MCP.md` for protocol/security internals, `docs/A2A.md` for peer-agent delegation, and `docs/CHATGPT-PLUGIN.md` for the
ChatGPT-facing setup and diagrams.
-## 7. Project and skill discovery
+## 8. Project and skill discovery
MSO can discover projects across configured containers instead of assuming a single
`~/projects` tree. Enumeration and resolution share the same containment/ownership checks,
@@ -216,7 +248,7 @@ Skills are merged from official/operator/bundled roots plus eligible per-project
Trust is derived from provenance, ownership and containment; untrusted instructions are not
fed directly to the model. See `skills/README.md`.
-## 8. Managed applications
+## 9. Managed applications
Hermes, OpenClaw and 9Router are managed, not embedded into MSO's process model. MSO can
detect, install, start/stop/restart, read logs, update, back up, restore and conservatively
@@ -240,7 +272,7 @@ dashboard as one surface plus MSO's Details management surface.
See `docs/MANAGED-APPS.md`, `docs/HERMES-INTEGRATION.md`,
`docs/OPENCLAW-INTEGRATION.md` and `docs/9ROUTER-INTEGRATION.md`.
-## 9. Camoufox Browser
+## 10. Camoufox Browser
The Browser app is a real Camoufox Firefox session on a headless X display. It is streamed
through noVNC on a reserved split-origin host such as `camoufox.mso.example.com`. That host
@@ -253,7 +285,7 @@ The logged-in Firefox profile is intentionally outside `~/.mso`, under the user'
share tree. It can hold live account cookies. Browser status tools never return the VNC
password or profile contents.
-## 10. Build and release architecture
+## 11. Build and release architecture
Production is a systemd deployment, not a webhook deployment. `git push` alone changes no
running bytes. The supported developer release command is:
@@ -272,7 +304,7 @@ For operator updates use Settings → About or `mso update`; use `--rebuild` for
supported recovery rebuild. See `docs/INSTALL.md`, `docs/DEVELOPMENT.md` and
`docs/TROUBLESHOOTING.md`.
-## 11. What is authoritative
+## 12. What is authoritative
When sources disagree, use this order:
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 622d5e80..c13b2919 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -41,6 +41,10 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
- `mcp` close session terminal across shells
- `mcp` close terminal after session graph check
+**Docs**
+
+- `plugin` clarify extension taxonomy
+
## 2026-09-15
**Added**
diff --git a/docs/PLUGIN-REFERENCE-MATRIX.md b/docs/PLUGIN-REFERENCE-MATRIX.md
new file mode 100644
index 00000000..ccd246dd
--- /dev/null
+++ b/docs/PLUGIN-REFERENCE-MATRIX.md
@@ -0,0 +1,92 @@
+# Plugin reference architecture matrix
+
+> **Living reference.** This document tracks recurring architecture patterns observed while reviewing high-quality OpenAI/Codex/MCP plugin references. It is not a feature checklist and does not make a reference plugin authoritative over MSO. A pattern is promoted only when it is cross-domain or closes a concrete correctness, safety, portability, DX, or compatibility gap.
+
+## Decision rules
+
+- `ALREADY_STRONGER` — MSO already has the behavior with stronger or broader guarantees.
+- `ALREADY_BUT_IMPROVE` — MSO has the concept, but the reference exposes a useful refinement.
+- `NEW_GENERALIZABLE` — a reusable primitive is missing and evidence is strong enough to add it.
+- `DOMAIN_SPECIFIC` — useful in the reference domain but not a core MSO primitive.
+- `AVOID` — would reduce safety, privacy, portability, capability, or context efficiency.
+- `WAIT` — promising, but one reference is not enough evidence for a new abstraction.
+
+The matrix should be updated after each reference audit. `pending` means that plugin has not been audited yet; it does not mean the pattern is absent.
+
+## Living matrix
+
+| Pattern | Shopify | Plugin Management | GitHub | Gmail | Drive | Calendar | Notion | Analytics | Convex | Figma | Lovable | Sites | MSO current | Candidate primitive | Decision |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Structured skill routing/lifecycle contract | Strong reference; already adapted | Prose routing only in local snapshot | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | `contract.yaml` + `agents/openai.yaml` on official skills | Keep structured skill contract | `ALREADY_STRONGER` |
+| Discover → validate → execute → verify | Strong reference; already adapted | Discovery/permission/dependency inspection is separated from mutation; connection must be verified before use | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Present across project MCP, database, workflows, integrations and action metadata | Universal lifecycle policy engine | `WAIT` — metadata must not become security authority |
+| Package identity separate from live app/connection state | Partial evidence | Strong: Codex plugin package points to a required registered app; connection/permission state is managed separately | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | OpenAI package, project plugin, MCP, Integrations, App and Managed App are distinct but terminology was under-documented | Canonical extension taxonomy | `ALREADY_BUT_IMPROVE` — documented now |
+| Reuse existing capability before discovering/installing a new extension | Not primary Shopify pattern | Strong: built-in → connected plugin → search new plugin | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Bounded-first and Integrations-first existed, but cross-surface ordering was implicit | Capability selection policy | `ALREADY_BUT_IMPROVE` — added to `/mso` guidance |
+| Search separated from suggestion/install | Domain discovery is separate from actions | Strong: `search_plugins` is read-only discovery; `suggest_plugins` only proposes exact results and user action completes connection | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Skills, projects and project MCP have separate discovery; Project Plugin catalog is small and install is explicit | Generic extension discovery/suggestion lifecycle | `WAIT` |
+| Suggestion is non-blocking | Not established | Strong: continue independent work while user handles connection | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Workflows can continue around missing integrations, but no universal suggestion state | Pending extension state | `WAIT` |
+| Installed/pending duplicate prevention | State-aware mutations | Strong: do not suggest installed or already-pending plugins | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Skill Market tracks installed/modified/conflict; project MCP inspect reports exact installed bindings | Generic extension state model | `WAIT` |
+| Dependency metadata resolved separately from installation | Domain dependencies exist | Strong: dependency inspection reports canonical dependencies and user-aware status without installing | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | `.app.json` maps OpenAI package→registered app; project plugin manifest declares skills/MCP, but there is no generic dependency graph | Dependency contract | `WAIT` |
+| Global permission default + per-extension override/inheritance | Not established | Strong: global permission mode plus app-specific override with `inherit` | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | OAuth `read < write < exec`, live device roles and per-operation confirmation are stronger security boundaries but semantically different | Permission policy overlay | `WAIT` — do not conflate platform UX permissions with MSO authorization |
+| Explicit uninstall/remove only | Mutations are explicit | Strong: uninstall requires explicit user removal intent and exact targets | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Project MCP delete is exact-project + revision guarded; Skill Market refuses unmanaged removal; App UI confirms uninstall; managed runtime uninstall is job-based | Shared removal UX vocabulary | `ALREADY_STRONGER` at enforcement level |
+| Canonical identity instead of guessed identifiers | Strong target identity discipline | Strong: exact returned plugin IDs or unambiguous names; broad targets are refused | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Exact project ids, skill ids, user/provider/connection and server aliases already fail closed on ambiguity | Generic identity resolver | `ALREADY_STRONGER` |
+| Public legal/support metadata for submission | Present in Shopify package | Present: website/privacy/terms in package manifest | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | MSO has real repository/website metadata but intentionally does not invent missing legal/support URLs | Submission metadata checklist | `WAIT` until real public surfaces exist |
+| Target-aware capability resolver | Strong target/API legality concept | Partial: availability depends on built-ins, installed/connected state and dependency status | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Target/action metadata + dynamic project/provider discovery exist, but no universal actor+project+surface+target+environment resolver | Capability resolver | `WAIT` — strengthened candidate |
+| Bulk/partial-failure result contract | Strong Shopify candidate | No evidence in current Plugin Management schemas | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | No universal result shape | `BulkResult` | `WAIT` |
+| Mandatory postcondition/refetch contract | Strong Shopify candidate | Partial: skill requires verifying installation/connection before claiming state | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | Verify metadata/evidence exists, but not every mutation has automatic postcondition execution | Postcondition runner | `WAIT` |
+| Query/analytics DSL | ShopifyQL reference | No evidence | pending | pending | pending | pending | pending | pending | pending | pending | pending | pending | `read_pipeline` already supports select/filter/sort/unique/aggregate | Query DSL | `WAIT` for Analytics reference |
+
+## Plugin Management audit — 0.1.0
+
+Operator-local reference snapshot: `plugin-references/plugin-management/0.1.0` outside the portable MSO source tree.
+
+### Architecture
+
+The local package is deliberately thin:
+
+```text
+plugin-management/
+├── .codex-remote-plugin-install.json # remote plugin identity
+└── 0.1.0/
+ ├── .codex-plugin/plugin.json # package/interface metadata
+ ├── .app.json # required registered app dependency
+ ├── assets/plugin-management.svg
+ └── skills/plugin-management/SKILL.md
+```
+
+The package itself does not contain the runtime implementation of Plugin Management. Its local responsibility is packaging plus model routing. The installed app exposes the operational contracts for plugin search/suggestion, permissions, dependency inspection and uninstall.
+
+### Behavior contract
+
+1. Prefer an already available built-in capability.
+2. Prefer an already connected plugin when it can finish the task.
+3. Search the plugin directory only when an external app/account/service/data source would materially help and no available capability can access it.
+4. Search with concise provider/capability terms, not the whole request.
+5. Suggest only exact returned plugin identities; suggestions do not install/connect by themselves and must not block independent work.
+6. Do not suggest already installed or pending plugins.
+7. Treat permissions and dependencies as inspectable state, separate from plugin installation/connection.
+8. Permission changes require the intended exact app and explicit or unambiguous requested mode; app-specific permissions may inherit the global default.
+9. Uninstall requires explicit removal intent and exact targets.
+10. Never claim installed/connected state without verification.
+
+### Comparison with MSO
+
+MSO is already stronger in exact target identity, trust levels, project isolation, credential isolation, CAS/revision guards, scoped OAuth authorization, dynamic MCP discovery, evidence receipts, shell escape-hatch preservation and removal safeguards. Plugin Management is clearer in one area: the model-facing mental model for choosing an existing capability versus discovering a new extension, and the separation between package identity, registered app dependency, connection state and permission policy.
+
+MSO therefore should not collapse `Skill`, `Project Plugin`, `MCP`, `Integration`, `App`, and `Managed App` into one object. They own different authority. The immediate improvement is to make that taxonomy and routing order explicit. Generic dependency graphs, platform-style permission inheritance and suggestion state remain candidates until additional plugin references show the same pattern.
+
+### Shopify candidate impact
+
+- **Universal lifecycle engine:** mildly strengthened; Plugin Management also separates discovery/inspection from mutation, but does not prove a declarative universal runtime engine.
+- **Knowledge/schema pack:** no supporting evidence in this snapshot.
+- **Target-aware capability resolver:** strengthened; availability depends on currently available built-ins, installed/connected plugins and dependency state.
+- **Bulk/partial failure result:** no supporting evidence.
+- **Postcondition runner:** mildly strengthened by the explicit rule to verify install/connection before claiming state, but still not enough for an automatic generic runner.
+- **Query/analytics DSL:** no supporting evidence.
+- **Public submission metadata:** strengthened; Plugin Management also declares website/privacy/terms metadata.
+
+### Decision
+
+**Implement now:** canonical extension taxonomy and capability-selection routing guidance.
+
+**Wait for more references:** generic plugin/extension search-and-suggest primitive, dependency graph, pending-install state, platform-style permission inheritance, universal lifecycle/postcondition engines, and public submission metadata beyond real URLs MSO already owns.
+
+**Reject:** collapsing distinct MSO authority domains into a single generic “plugin” object, hiding existing low-level capabilities to mimic a simpler plugin product, or allowing package metadata to become an authorization/security authority.
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 02aca1e2..2f1eb0ab 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,7 @@
+## 2026-09-17 — Plugin Management reference audit and extension taxonomy
+
+Audited the local OpenAI `plugin-management` 0.1.0 package plus its installed tool contracts. The recurring improvement is model-facing capability selection and terminology, not a reason to collapse MSO authorities: Skills remain trusted instructions, Project Plugins remain exact-project capability packages, MCP remains the tool protocol, Integrations remains the credential authority, Apps remain workspace UI, and Managed Apps remain external service runtimes. Added the living `docs/PLUGIN-REFERENCE-MATRIX.md`, made that taxonomy canonical in `docs/ARCHITECTURE.md`, and updated the main `/mso` skill to reuse existing native/project/integration capabilities before adding a new plugin. No tools, scopes, credential behavior, low-level primitives, or descriptor schemas were removed or added. Generic suggestion state, dependency graphs, platform-style permission inheritance, and universal lifecycle/postcondition engines remain cross-reference candidates rather than one-plugin abstractions.
+
## 2026-09-17 — ChatGPT List surface and OpenAI app scaffold
Added `render_mso_list` + `ui://mso/list-v1.html` as the lightweight collection surface between Block and Page. Data tools remain headless; the model first fetches/filters structured results, then renders at most 40 selected items as list/grid with local search, bounded metadata and user-approved follow-up actions. The widget has no network/tool-call path and cannot execute mutations. ChatGPT now exposes 113 transport tools while retaining the strict 96 KiB internal descriptor budget through scanner-only summary compaction; full MCP descriptions and runtime schemas remain unchanged. `.app.json` is now a valid empty registered-app scaffold referenced by the compatibility manifest, with skill checks rejecting malformed or placeholder mappings.
diff --git a/docs/README.md b/docs/README.md
index f4ac74b6..f2871f70 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -44,6 +44,7 @@ evidence and review freshness. The repository quality gate runs both automatical
| [`SUBAGENTS.md`](./SUBAGENTS.md) | Same-session foreground isolated worker lifecycle, context, tool authority and limits |
| [`MCP-FEATURE-IMPLEMENTATION.md`](./MCP-FEATURE-IMPLEMENTATION.md) | Stepwise reverse-engineering workflow for MCP tools, trusted skills and project capabilities |
| [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) | ChatGPT custom MCP app setup, diagrams, scopes and file bridge |
+| [`PLUGIN-REFERENCE-MATRIX.md`](./PLUGIN-REFERENCE-MATRIX.md) | Living cross-plugin architecture matrix, audit decisions and candidate generic primitives |
| [`MANAGED-APPS.md`](./MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, backup/restore and dashboard access boundary |
| [`HERMES-INTEGRATION.md`](./HERMES-INTEGRATION.md) | Hermes-specific integration behaviour |
| [`OPENCLAW-INTEGRATION.md`](./OPENCLAW-INTEGRATION.md) | OpenClaw-specific integration behaviour |