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.

merge: preserve published native integration setup

Rahman5836ce602b14
diff --cc README.md
index 8319ba70,06abef33..3b41ed42
--- a/README.md
+++ b/README.md
@@@ -56,42 -443,120 +56,44 @@@ Default application bind: **127.0.0.1**
```mermaid
flowchart LR
- U["Phone / Browser"]
- subgraph VPS["Your Linux server"]
- APP["MSO / mso<br/>Next.js 16 · React 19"]
- HOST["Host layer<br/>fs · PTY · metrics · services · packages"]
- SLICES["Feature slices<br/>Files · Terminal · Monitor · Assistant"]
- AI["Alfa AI<br/>BYOK"]
- MANAGED["Managed apps<br/>Hermes · OpenClaw · 9Router<br/>own runtime + data"]
- end
- U -->|"HTTPS or Tailscale/VPN"| APP
- U -->|"framed dashboard, per-app origin<br/>same process, different origin"| APP
- APP --> HOST
- APP --> SLICES
- APP --> AI
- APP -->|"their CLI · loopback HTTP · systemd"| MANAGED
+ Preview["Preview owned paths"] --> Review["Review + stop runtime"]
+ Review --> Confirm["Confirm exact plan token"]
+ Confirm --> Reset["Reset → private recovery archive"]
+ Confirm --> Remove["Uninstall → optional data/code purge"]
```
-Deep dive: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
-
-## Comparison
+| Preview command — no changes yet | Scope |
+|---|---|
+| `mso reset` | Server preferences and provider configuration |
+| `mso reset --scope all` | Factory reset of known MSO state and local configuration |
+| `mso uninstall` | Remove owned service/CLI links; keep data and source |
+| `mso uninstall --purge --remove-code` | Also remove known data and a clean standalone clone |
-<!-- comparison:start -->
-**Positioning:** MSO is designed as a mobile-first, AI-native private Linux workspace for an owner or small trusted team. It does not claim to replace specialist products at their strongest specialty.
+Apply requires `--apply --confirm <preview-token>` from an independent local/SSH terminal.
+Browser reset is separate in **Settings → About**. Unknown files and other projects are retained.
+[Scopes, backups, safeguards and recovery](./docs/MAINTENANCE.md)
-Strong = a first-class product strength · Partial = available with scope limitations · Not offered = not a core product surface
+## Safety first
-| Product | Best fit | Browser workspace | Linux host administration | Application delivery | Monitoring and observability | Roles and delegation | Built-in AI and MCP |
-|---|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| **MSO** | Mobile-first private Linux workspace | Strong | Partial | Partial | Partial | Partial | Strong |
-| **Cockpit** | Deep graphical Linux administration | Partial | Strong | Partial | Partial | Strong | Not offered |
-| **Coolify** | Self-hosted Git/PaaS delivery | Partial | Partial | Strong | Partial | Strong | Not offered |
-| **Portainer** | Container and stack operations | Partial | Partial | Strong | Partial | Partial | Not offered |
-| **Netdata** | High-resolution observability and RCA | Partial | Not offered | Not offered | Strong | Partial | Partial |
-| **Tailscale SSH** | Identity-aware private remote access | Not offered | Partial | Not offered | Not offered | Strong | Not offered |
-| **File Browser** | Focused web file management | Partial | Not offered | Not offered | Not offered | Partial | Not offered |
-| **ttyd** | Small, focused web terminal | Partial | Not offered | Not offered | Not offered | Partial | Not offered |
-| **CasaOS** | Friendly personal-cloud home server | Partial | Partial | Partial | Partial | Not offered | Not offered |
-| **Runtipi** | Curated one-click self-hosted apps | Partial | Not offered | Strong | Partial | Not offered | Not offered |
+**Public Alpha / Developer Preview.** An Owner or exec-scoped agent can execute commands as the
+service user. MSO is **not a shell sandbox or multi-tenant security boundary**. Provider calls may
+send selected context off-host. Keep credentials private and review approvals.
+[Security policy](./SECURITY.md) · [Verification and known limits](./docs/SECURITY-ASSURANCE.md)
-Reviewed against official product documentation on **2026-08-29**. Ratings describe product scope, not benchmark scores. See [methodology, evidence, and per-cell notes](docs/COMPARISON.md) and the [execution roadmap](docs/COMPETITIVE-ROADMAP.md).
+<!-- comparison:start -->
+[Product comparison, evidence and limitations](docs/COMPARISON.md) · reviewed 2026-08-29.
<!-- comparison:end -->
-## Development
+## Develop
```bash
-bun install
-cp .env.example .env.local
-bun run dev
+bun install --frozen-lockfile
+bun run verify
+bun run test:features
+bun run audit:strict
```
-Quality gates:
-
-```bash
-bun run verify # typecheck + lint + test + checks + audit
-node scripts/check-docs.mjs # docs links/toolset/slice drift
-node scripts/gen-comparison.mjs --check # comparison evidence + 90-day freshness
-bash scripts/verify-build.sh # build HEAD out-of-tree — safe on the prod checkout
-bash -n scripts/install.sh && bash -n scripts/install-core.sh
-```
-
-The package manager is **bun** (`bun.lock` is committed); the **runtime stays Node 22** — `next`, `tsc`, `eslint` and `vitest` all carry a `#!/usr/bin/env node` shebang and bun honours it, and production runs `npm run start`. Use bun so the lockfile and the native `node-pty` build path stay predictable: `node-pty` has no Linux prebuild and is listed under `trustedDependencies`, without which its postinstall is skipped and the whole `/api/v1` surface fails to load.
-
-Full guide: [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md).
-
-## Tested platforms
-
-Not yet formally tested across a full distro matrix.
-
-Tested:
-
-- Ubuntu 22.04
-- Ubuntu 24.04
-
-Supported deployment shapes:
-
-- WSL2 Ubuntu: CLI/install path works without systemd; the background service requires systemd enabled in WSL
-- Debian 12 and other systemd-based Linux distributions with Node.js 20.9+ and build tools
-
-Not currently supported:
-
-- Windows host
-- macOS host
-- Automatic service install on non-systemd hosts
-- Root deployment
-
-## Documentation
-
-| Doc | What's in it |
-|---|---|
-| [docs/README.md](./docs/README.md) | Documentation map: current reference vs generated vs historical |
-| [docs/INSTALL.md](./docs/INSTALL.md) | Server install, credentials, TLS/VPN, update/rebuild, persistence |
-| [docs/CLI.md](./docs/CLI.md) | Generated `mso` command-line reference |
-| [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) | Local dev, gates and exact release flow |
-| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Current AppShell/host/MCP/managed-app architecture |
-| [docs/COGNITIVE-RUNTIME.md](./docs/COGNITIVE-RUNTIME.md) | Provider-neutral agent session/context/tool-routing architecture and benchmark contract |
-| [docs/COMPARISON.md](./docs/COMPARISON.md) | Generated comparison methodology, evidence and per-cell notes |
-| [docs/COMPETITIVE-ROADMAP.md](./docs/COMPETITIVE-ROADMAP.md) | Executed comparison plan, deliberate boundaries and next measurable investments |
-| [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, update, backup/restore and origins |
-| [docs/INFRASTRUCTURE-PROVIDERS.md](./docs/INFRASTRUCTURE-PROVIDERS.md) | MSO terminal agent and Dokploy/Cloudflare/Hostinger deployment-provider contract |
-| [docs/HERMES-INTEGRATION.md](./docs/HERMES-INTEGRATION.md) | Hermes-specific managed-app behaviour |
-| [docs/OPENCLAW-INTEGRATION.md](./docs/OPENCLAW-INTEGRATION.md) | OpenClaw-specific managed-app behaviour |
-| [docs/9ROUTER-INTEGRATION.md](./docs/9ROUTER-INTEGRATION.md) | 9Router immutable-image ownership, loopback default and explicit dashboard exposure |
-| [docs/MODELS-INTEGRATION.md](./docs/MODELS-INTEGRATION.md) | Alfa BYOK/custom/Codex model credentials |
-| [docs/MCP.md](./docs/MCP.md) | MCP/OAuth tools, discovery, workflow memory and security internals |
-| [docs/CHATGPT-PLUGIN.md](./docs/CHATGPT-PLUGIN.md) | ChatGPT Plugin/custom MCP app setup + architecture/OAuth/tool/file diagrams |
-| [docs/FAQ.md](./docs/FAQ.md) | Security, product and operator boundaries |
-| [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) | Current symptom → cause → supported recovery |
-| [SECURITY.md](./SECURITY.md) | Security posture and vulnerability reporting |
-
-## Status
-
-MSO is **Public Alpha / Developer Preview**. The core role-aware auth, filesystem bounds, terminal, metrics, Service Center, and slice architecture are implemented, but the project is still early and unaudited. Expect rough edges, breaking changes, and missing production hardening.
-
-## License
-
-MIT — see [LICENSE](./LICENSE).
+Use Node 22 and Bun >=1.2.15 with native audit support. [Contributing](./CONTRIBUTING.md) ·
+[Development](./docs/DEVELOPMENT.md) · [Changelog](./docs/CHANGELOG.md) · [MIT license](./LICENSE)
+
-**Secure connections:** [Native Integrations](docs/INTEGRATIONS.md) provides temporary credential forms in the browser, terminal, and ChatGPT Page.
++[Native Integrations](./docs/INTEGRATIONS.md): temporary credential forms for browser, CLI and MCP Page.
diff --cc docs/CHANGELOG.md
index 9ff7e878,1464848a..69005f0a
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@@ -8,8 -8,7 +8,9 @@@ this is the *what*, and it is what Sett
**Added**
+ - `integrations` add native secure credential setup in browser and MCP Page
+- add safe local maintenance and visual README
+- `mcp` preserve restricted project service bridge
**Fixed**
diff --cc docs/PROGRESS.md
index 3d5a4ad8,8cc751a3..db4f7f00
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@@ -8,21 -8,6 +8,22 @@@ contract remain unchanged. Targeted con
both standard MCP and legacy ChatGPT host paths. Toolset: `2026.09.05.1`.
# mso — Progress Log
++- **Native integration preservation (2026-09-05):** merged published c164dbe without dropping the concurrent native credential setup. The short README retains its documentation link (99 lines). MCP 1.12.0 / toolset 2026.09.05.4 labels the combined maintenance, service-token, Page-readiness and native-integration contracts. This merge does not execute maintenance or reset real credentials.
+- **Concurrent main reconciliation (2026-09-05):** preserved published MCP Page initialization/readiness changes e46c417 + changelog c4856d2 in the maintenance/PR integration branch without modifying the other session's unpublished work. MCP 1.11.1 / toolset 2026.09.05.2 records the combined compatible contract. The Settings maintenance files are unchanged from the isolated desktop/mobile acceptance at 2164d29; full repository and GitHub gates are rerun for the combined source.
+- **PR integration validation (2026-09-05):** preserve the reviewed PR36/PR37 ancestry while repairing PR38 glob escaping/native Bun audit checks and PR37 code-generating visual-test fixtures. Direct-image boundary tests now cover malformed content and size/type limits. MCP server 1.11.0 / toolset 2026.09.05.1 records the compatible restricted-service-token/direct-image contract; widget resources and ordinary OAuth token behavior are unchanged. Publication still requires complete current-head local and remote gates, including late CodeQL findings—not only the workflow completion status.
+- **Reviewed 9Router network boundary (PR36, 2026-09-05):** reuse the configured internal proxy network only when it already exists; Docker host publishing remains loopback-only unless explicitly enabled. This supports a containerized reverse proxy without opening the application port to the public interface. The update adds no automatic network creation or DNS mutation. The old PR lifecycle-test failure must be rechecked against the combined current baseline before publication.
+
+## 2026-09-05 — Restricted MCP service tokens + truthful diverged self-update
+
+- **Machine automation gets least-privilege MCP bearers instead of a generic exec token.** A trusted local operator can mint a service token only from the owner CLI; there is no HTTP mint endpoint. The current service-token policy permits only `project_capabilities` and `project_function_call`, requires an exact top-level string constraint for every allowlisted tool, filters `initialize` / `tools/list`, and re-checks both the tool allowlist and argument constraints at `tools/call`. OAuth/browser tokens keep their existing behavior. Raw bearers are emitted once and the existing owner-only MCP store persists only their SHA-256 hash; normal token expiry/revocation still applies.
+- **Project-function visuals stay bounded rather than becoming arbitrary binary passthrough.** A successful declared project function may opt into `mso.project-function-content.v1`; MSO accepts at most one PNG/JPEG/WebP image with matching magic bytes plus bounded text/content, under the existing runner output cap. Non-zero exits, stderr, malformed envelopes, unsupported MIME types, oversized payloads, and invalid image signatures remain ordinary process output or failures rather than trusted MCP image content. Project functions still execute fixed argv and validate caller JSON against their declared schema.
+- **Self-update now models both sides of Git history.** Status uses `git rev-list --left-right --count HEAD...origin/main` and reports `ahead` and `behind` separately. A normal update is refused when local `main` is ahead or diverged, so unpushed work cannot be silently deployed or overwritten; `--rebuild` remains an explicit rebuild of the already-selected clean checkout and does not mutate Git history. Settings → About suppresses the Update action for local-ahead/diverged state and explains the real reconciliation requirement instead of mislabeling it as a remote-connectivity failure.
+- **PR37 pre-integration verification (historical):** the two implementation commits remain independently reviewable; targeted MCP/updater tests pass 65/65, TypeScript passes, `git diff --check` is clean, the safe out-of-tree production build passed on the same implementation head, and GitHub dependency/security/CodeQL/ShellCheck/Verify checks were green before this documentation follow-up.
+
+- **Visual README + local maintenance (2026-09-05):** README reduced from 575 to 97 lines with two Mermaid diagrams and an actual CLI PTY capture; longer valid material moved to the workspace reference. App 0.2.3 / CLI 1.13.0 adds preview-first reset and uninstall with exact-plan confirmation, private reset archives, stopped-runtime checks, existing runtime-exclusion coordination, symlink/ownership checks and explicit purge/standalone-source options. Unknown .mso entries/worktrees, other projects, shared dependencies and browser profiles are retained. Settings separates browser reset from copyable server maintenance previews; the device identity is preserved. Synthetic fixture tests exercise reset, clean-clone uninstall and failure paths; production was not reset or uninstalled. PR38 review fixes include complete glob escaping and a Bun >=1.2.15 native-audit prerequisite, enforced by the installer with refreshed bootstrap checksum.
+- **Previously hidden exec/discovery test gaps closed (2026-09-05):** the remaining expected-failure shell-expansion case is now a real passing refusal test. Recursive deletion with unresolved shell expansion is conservatively refused; literal reviewed targets remain subject to normal approvals, and the matcher is explicitly not a shell parser or sandbox. Added eight predicate-only expansion fixtures without executing destructive commands. Registered the previously omitted root machine-protocol proxy test in normal Vitest/coverage and added an inventory regression contract. Per-area runs now use isolated exact-include configurations and verify the exact returned file set, preventing substring matches from counting unrelated nested proxy tests twice. Earlier per-area totals from this audit are superseded by the exact-selection rerun.
+- **Compiler-enforced unused-code cleanup (2026-09-05):** resolved 49 unused import/local/parameter diagnostics across the shell, assistant, media, host, MCP and test modules. Calls with intentional side effects remain intact; positional callback placeholders are explicitly named. TypeScript `noUnusedLocals` and `noUnusedParameters` now make the ordinary typecheck/CI reject regressions. This is compiler-proven unused-symbol cleanup, not a claim that every exported symbol, runtime-discovered asset or optional integration is removable.
+- **Public-sharing security and maintenance audit (2026-09-05):** app `0.2.2` keeps the independently versioned CLI/MCP contracts unchanged. Release and assurance dependency audits now fail closed on unavailable, malformed or incomplete evidence; local developer skips are explicitly labelled, registry diagnostics do not expose raw URLs, and skipped optional scanners cannot produce an unconditional assurance PASS. Removed the dormant Convex deploy tail, fixed shared Git-hook installation and out-of-tree dependency copying for linked worktrees, and added functional regression tests. README now leads with a readable install/features/security overview and collapsible reference detail, preserving generated comparison evidence and public-alpha limits. `test:features` runs each test area in a separate process and distinguishes PASS/PARTIAL/SKIPPED/FAIL. The Forge Docker sandbox and synthetic credential-path fixture activate previously skipped security checks without using real secrets; CI now provisions the same bounded fixtures. Onboarding tests derive the app version from `package.json`; the browser suite follows the actual Activity & Runs UI, checks infrastructure deep-links, and never echoes session-cookie diagnostics. Full-history scanning now requests merge diffs explicitly in CI and the assurance runner; independent scanner outputs remain private; no genuine historical secret was identified by the configured scan, so shared history was not rewritten. Live-service deployment and remote CI status require separate exact-revision evidence and are not inferred from local tests.
- **Rahmanef-aligned MCP widget palette / Block + Page v2 (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.7` moves the two canonical ChatGPT resources to `ui://mso/block-v2.html` and `ui://mso/page-v2.html` so hosts do not reuse the old purple CSS cache key. Block and Page now share one visual-token source aligned with `rahmanef.com`: light `#f4f4f7` / `#1c1c1f`, dark `#1b1b20` / `#f2f2f5`, accent `#1f6df0`, Plus Jakarta Sans display copy, Inter body copy, fine separators, and editorial foreground/background primary-action inversion. ChatGPT theme changes propagate through `window.openai.theme` with a color-scheme fallback. Block/Page v1 and the earlier workflow/surface URIs remain readable but unlisted compatibility aliases; the headless workflow and two-surface/security contracts are unchanged.
- **Headless workflows + two-surface MCP UI contract (2026-09-04):** MCP server `1.10.0` / toolset `2026.09.04.6` removes the automatic UI binding from `workflow_start`: orchestration, collision checks, tracing, evidence, and learning continue in the background without consuming the answer with a progress card. ChatGPT now has exactly two canonical MCP App resources: `ui://mso/block-v1.html` through `render_mso_block` for compact validation/action/CRUD input-output, and `ui://mso/page-v1.html` through `render_mso_page` for native operator views plus reviewed development/preview/production embeds. Block buttons send a user-approved follow-up and never execute mutations inside the widget, preserving normal scope, approval, audit, and workflow boundaries. The prior workflow/surface URIs remain non-advertised read aliases, while `workflow_status` and `render_mso_surface` remain app-only compatibility shims for cached clients. The ChatGPT transport profile is 66 tools: 64 model-visible actions (35 read / 17 write / 12 exec) plus two app-only shims; the full catalog is 90. Only Block and Page advertise a resource URI.
- **Local release audit timeout hardening (2026-09-04):** the tolerant pre-push dependency audit now caps `bun audit --json` at 15 seconds. A registry timeout is reported and skipped only in the local gate, matching its existing network-tolerant policy; CI remains the fail-closed dependency-audit authority. This prevents a slow registry request from holding GitHub's pre-push SSH session open for minutes and failing the otherwise-green release with a transport/SIGPIPE-style exit.
diff --cc docs/generated/MCP-CATALOG.md
index 19560b83,77c76530..0d94a680
--- a/docs/generated/MCP-CATALOG.md
+++ b/docs/generated/MCP-CATALOG.md
@@@ -4,17 -4,17 +4,17 @@@
## Full MSO catalog
- <!-- mcp-toolset: server=1.11.1 version=2026.09.05.2 tools=88 read=44 write=25 exec=19 -->
-<!-- mcp-toolset: server=1.10.0 version=2026.09.05.3 tools=89 read=44 write=26 exec=19 -->
++<!-- mcp-toolset: server=1.12.0 version=2026.09.05.4 tools=89 read=44 write=26 exec=19 -->
| Fact | Current source value |
|---|---:|
- | MCP server | `1.11.1` |
- | Toolset | `2026.09.05.2` |
- | Toolset changed at | `2026-09-05T11:53:00.000Z` |
- | Transport tools | **90** |
- | Model/operator tools | **88** |
-| MCP server | `1.10.0` |
-| Toolset | `2026.09.05.3` |
-| Toolset changed at | `2026-09-05T11:45:00Z` |
++| MCP server | `1.12.0` |
++| Toolset | `2026.09.05.4` |
++| Toolset changed at | `2026-09-05T11:59:00Z` |
+ | Transport tools | **91** |
+ | Model/operator tools | **89** |
| Read | **44** |
- | Write | **25** |
+ | Write | **26** |
| Exec | **19** |
| App-only bridges | **2** |
@@@ -122,7 -123,7 +123,7 @@@
## ChatGPT static profile
- <!-- mcp-chatgpt-profile: server=1.11.1 version=2026.09.05.2 tools=64 read=35 write=17 exec=12 app-only=2 total=66 -->
-<!-- mcp-chatgpt-profile: server=1.10.0 version=2026.09.05.3 tools=65 read=35 write=18 exec=12 app-only=2 total=67 -->
++<!-- mcp-chatgpt-profile: server=1.12.0 version=2026.09.05.4 tools=65 read=35 write=18 exec=12 app-only=2 total=67 -->
The ChatGPT profile is a fail-closed static projection defined by `CHATGPT_TOOL_NAMES`. OAuth scope is still enforced independently; project-owned MCP tool names remain dynamic data behind the generic project bridge.
diff --cc lib/mcp/toolset.ts
index e5b91801,e9ba30ac..5a8b08bf
--- a/lib/mcp/toolset.ts
+++ b/lib/mcp/toolset.ts
@@@ -3,9 -3,9 +3,9 @@@ import type { Scope } from "./scope"
import type { McpTool } from "./tool-kit";
import { toolDescriptor, type McpToolProfile } from "./tool-contract";
- export const MCP_SERVER_VERSION = "1.11.1";
- export const MCP_TOOLSET_VERSION = "2026.09.05.2";
- export const MCP_TOOLSET_CHANGED_AT = "2026-09-05T11:53:00.000Z";
-export const MCP_SERVER_VERSION = "1.10.0";
-export const MCP_TOOLSET_VERSION = "2026.09.05.3";
-export const MCP_TOOLSET_CHANGED_AT = "2026-09-05T11:45:00Z";
++export const MCP_SERVER_VERSION = "1.12.0";
++export const MCP_TOOLSET_VERSION = "2026.09.05.4";
++export const MCP_TOOLSET_CHANGED_AT = "2026-09-05T11:59:00Z";
export type McpToolsetInfo = {
serverVersion: string;