mobile-agent-orchestrator 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 egdev6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,271 @@
-# mobile-agent-orchestrator
+<a id="readme-top"></a>
 
-Name reserved. The real package ships with v0.2.0 from [egdev6/mobile-agent-orchestrator](https://github.com/egdev6/mobile-agent-orchestrator) via npm trusted publishing. Do not install this placeholder version.
+<div align="center">
+  <a href="https://github.com/egdev6/mobile-agent-orchestrator">
+    <h1>Mobile Agent Orchestrator</h1>
+  </a>
+
+  <img width="3469" height="1198" alt="moshi" src="https://github.com/user-attachments/assets/aa5ed0b7-bd0c-4612-a3fd-58876c4eccab" />
+
+  <p>A guided Agent Skill for a private, recoverable mobile AI-agent environment.</p>
+
+  <p>
+    <a href="https://github.com/egdev6/mobile-agent-orchestrator/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/egdev6/mobile-agent-orchestrator/ci.yml?branch=main&amp;label=package%20CI&amp;style=for-the-badge" alt="Package CI"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"></a>
+    <a href="https://pi.dev"><img src="https://img.shields.io/badge/Pi-package-7c3aed?style=for-the-badge" alt="Pi package"></a>
+    <img src="https://img.shields.io/badge/status-v0.2.0-brightgreen?style=for-the-badge" alt="Stable v0.2.0 status">
+  </p>
+</div>
+
+---
+
+> **Status: stable v0.2.0.** Published to npm with provenance; GitHub release tags remain the source-review channel — review the source before installation: a Pi skill can guide system and network changes.
+>
+> **Operational-evidence caveat.** Independently recorded cold-boot and live runtime evidence is not published for v0.2.0. Validate lifecycle and recovery on your target; this release does not claim observed macOS, WSL2, reboot, or mobile-client behavior.
+>
+> **BASED ON** https://www.youtube.com/watch?v=Yj51wXMwFwE&t=907s
+
+<details>
+  <summary>Table of Contents</summary>
+<ol>
+    <li><a href="#prerequisites">Prerequisites</a></li>
+    <li><a href="#installation">Installation</a></li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#architecture">Architecture</a></li>
+    <li><a href="#features">Features</a></li>
+    <li><a href="#runtime-stack">Runtime Stack</a></li>
+    <li><a href="#safety-boundaries">Safety Boundaries</a></li>
+    <li><a href="#verification-and-recovery">Verification and Recovery</a></li>
+    <li><a href="#contributing-and-contact">Contributing and Contact</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+---
+
+## Built With
+
+<a href="https://github.com/Gentleman-Programming/gentle-ai">
+  <img width="220" src="https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/docs/assets/brand/built-with-gentle-ai.png" alt="Built with Gentle-AI" />
+</a>
+
+---
+
+## Prerequisites
+
+| Requirement | Why it matters |
+| --- | --- |
+| A working Agent Skills-compatible CLI | The skill can instruct an agent to make system changes. Review the source if you need to assess its system-change guidance. [Pi](#pi) remains a supported package host. |
+| **macOS native** | Supported native lifecycle and execution target. |
+| **Windows 11 with WSL2** | Supported split model: Windows owns startup; the selected WSL distribution runs Linux services and agents. |
+| Windows native without WSL2 | **Unsupported.** Stop and install WSL2 before using this workflow. |
+
+The guided workflow discovers its runtime state before proposing changes. It installs runtime components only after the relevant approval; they are not bundled as npm dependencies.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Installation
+
+### Agent Skills-compatible CLIs
+
+Copy or link `skills/mobile-agent-orchestrator/` as `mobile-agent-orchestrator/` under one of the host's supported skill roots. The generic contract is one directory per skill containing a `SKILL.md`; references remain relative to that file. The host discovers and activates the skill, but host-specific persistence, lifecycle, and slash-command behavior must not be inferred from this repository. The [agent-hosts reference][agent-hosts] records each supported host's documented skill locations and session-resume boundary, with unverified behavior marked as unverified.
+
+For OpenCode, use any supported location:
+
+- Project: `.opencode/skills/mobile-agent-orchestrator/SKILL.md` or `.agents/skills/mobile-agent-orchestrator/SKILL.md`
+- Global: `~/.config/opencode/skills/mobile-agent-orchestrator/SKILL.md` or `~/.agents/skills/mobile-agent-orchestrator/SKILL.md`
+- Configured path: add the containing directory, for example `skills: ["./skills"]`, then place the skill at `./skills/mobile-agent-orchestrator/SKILL.md`
+
+Start OpenCode from the relevant project and use its discovered-skill interface or a matching natural-language request. OpenCode may disable external skill directories through configuration; configured skill paths remain the explicit fallback. This is an Agent Skill, not an MCP server, and requires no MCP implementation.
+
+#### Installer
+
+For Codex, OpenCode, Gemini CLI, and Claude Code, the package ships a deterministic installer.
+Run it without arguments in a terminal for the interactive flow:
+
+```bash
+npx mobile-agent-orchestrator install
+```
+
+It detects installed coding-agent CLIs (Pi, Claude Code, Codex, OpenCode, Gemini CLI — read-only, no modification), presents each host with its detection evidence and supported destinations, and asks which targets and scope to configure before writing anything. Shared `.agents/skills` destinations are deduplicated in the shown plan. Pi is detection-only: it prints the supported `pi install npm:mobile-agent-orchestrator` command instead of ever being a write target. Cancelling at any prompt performs no writes.
+
+For CI and automation, use the explicit non-interactive form:
+
+```bash
+npx mobile-agent-orchestrator install --target codex --target opencode --target gemini --target claude-code --scope user
+```
+
+#### Status
+
+The installer ships a strictly read-only status command:
+
+```bash
+npx mobile-agent-orchestrator status
+npx mobile-agent-orchestrator status --target codex --scope project
+```
+
+It inspects the managed installations without writing anything: by default every write target in both scopes (user and project); `--target` (repeatable) narrows the hosts and `--scope` narrows the scope. Each inspected destination prints one `STATUS [scope] destination (targets)` line — when a destination serves both scopes (for example when running from `$HOME`, where the user and project locations coincide) the scopes are merged into one line like `STATUS [user, project] destination (targets)` — plus indented details when something needs attention. The statuses are: `absent` (nothing installed), `managed` (the recorded manifest matches the on-disk checksums and the recorded version equals the package version), `outdated` (checksums match but the recorded version differs from the package version), `modified` (a managed file is missing or its content no longer matches the manifest), and `unknown` (the directory exists but cannot be verified: partial installation, missing, corrupt, or non-regular manifest). Pi is detection-only and has no managed destination, so it is never inspected.
+
+Exit codes for automation: `0` when every inspected destination is `absent` or `managed` (nothing needs attention); `1` when at least one destination is `outdated`, `modified`, or `unknown`, or on a usage error. Extra unmanaged files beside a fully matching manifest are listed as details but do not change the `managed` status; the installer still treats them as conflicts if you ever re-run `install`.
+
+#### Uninstall
+
+The installer ships a removal command that mirrors `install`'s safety model:
+
+```bash
+npx mobile-agent-orchestrator uninstall --target codex
+npx mobile-agent-orchestrator uninstall --target codex --scope project --dry-run
+```
+
+It removes only the files recorded in the installation manifest — and only when their on-disk checksum still matches the recorded one — plus the directories those files leave empty, and the manifest itself. Unmanaged files (your own notes, configs, anything the installer did not write) are never removed and are printed as `keep` lines in the plan. A locally modified managed file blocks its whole destination: nothing is removed there and the plan explains which file triggered the block. Destinations without a trustworthy manifest (missing, corrupt, symlinked, or one recording paths outside the skill directory) are reported as `unknown` and refused. A destination whose skill directory is absent reports `absent` with nothing to do.
+
+Targets sharing one `.agents/skills` directory (Codex, OpenCode, Gemini CLI) are installed as one copy and are removed as that single copy: `uninstall --target codex` reports `(codex, opencode, gemini)` on the shared line and removes the copy. By default BOTH scopes are planned (user and project); `--scope` narrows it. `--dry-run` prints the exact removal plan — every file, directory, and manifest removal — and writes nothing.
+
+Exit codes for automation: `0` when every planned destination was uninstalled or was already absent; `1` when at least one destination is blocked (modified or unsafe content) or unknown, or on a usage error. The command is deliberately non-interactive: check the `--dry-run` plan first, then run it. The source skill and any Pi-installed copy are never touched — uninstall only ever operates on installer-managed destinations.
+
+Codex, OpenCode, and Gemini CLI resolve the same shared `.agents/skills` location (`--scope user` installs to `~/.agents/skills`, `--scope project` to `<cwd>/.agents/skills`), so those repeated targets deduplicate into a single copy. `--target claude-code` resolves the documented Claude Code locations instead (`~/.claude/skills` for user scope, `<cwd>/.claude/skills` for project scope), which are a separate destination from the shared `.agents/skills` location: selecting `claude-code` together with the other targets produces an additional copy in `.claude/skills` with its own manifest beside the skill directory. Use `--dry-run` to print the exact plan first. The installer records a checksum manifest beside the skill directory and aborts without writing anything when the destination contains modified or unmanaged content. On upgrade it removes files that earlier versions managed and the package no longer ships, but only when their checksum still matches the previous manifest; modified, unmanaged, or symlinked content still aborts the install. A manifest that is a symlink or not a regular file is rejected before any write, and the manifest is published atomically so an interrupted run leaves the previous manifest valid.
+
+### Pi
+
+#### Install stable v0.2.0 from Git
+
+```bash
+pi install git:github.com/egdev6/mobile-agent-orchestrator@v0.2.0
+```
+
+Stable releases are distributed via GitHub tags: the release tag is created by automation after a validated release pull request merges. See the [release guide][release-guide] for the release conditions and publication semantics.
+
+#### Recommended: install stable v0.2.0 from npm
+
+```bash
+pi install npm:mobile-agent-orchestrator
+```
+
+The package is published with provenance from the release workflow: the publish job runs `npm publish --provenance` in the same workflow run that creates the release tag, so the package binds to `egdev6/mobile-agent-orchestrator` and its `tag-release.yml` workflow, with a rerun guard that never overwrites a published version and fails closed on integrity differences. For hosts that consume npm packages directly, `npx mobile-agent-orchestrator install` uses the same artifact.
+
+#### Source-review or development option: install from a local checkout
+
+1. Review this repository, especially the [skill][skill] and its on-demand references.
+2. Install the reviewed local package:
+
+   ```bash
+   pi install /absolute/path/to/mobile-agent-orchestrator
+   ```
+
+3. Start Pi from your normal working directory.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Usage
+
+Use the skill from an active Agent Skills-compatible session. For Pi, the existing activation command remains:
+
+```text
+/skill:mobile-agent-orchestrator
+```
+
+A matching natural-language request, such as “set up a private mobile agent environment with Tailscale and Mosh,” can also load the skill. Follow the guided path rather than running an installation recipe out of order:
+
+1. **Detect:** allow read-only platform and state checks; unsupported or unclear targets stop safely.
+2. **Decide:** answer only real decision gates, including Tailscale placement, key setup, Moshi privacy, integrations, and notifications.
+3. **Approve:** explicitly authorize each privileged, network, service, firewall, pairing, lifecycle, or reboot mutation before it happens.
+4. **Verify:** collect non-sensitive checkpoints after each approved mutation and use the [recovery guide][verification-recovery] when a check fails.
+
+The skill is a human-supervised orchestrator, not an unattended installer. Platform detail lives in the [platform matrix][platform-matrix] and [guided install][guided-install] reference so the core workflow stays concise. Lifecycle and checkpoint semantics are host-specific; the skill does not promise that another CLI provides Pi's persistence behavior.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Architecture
+
+```text
+mobile-agent-orchestrator/
+├── package.json
+│   └── pi.skills: ./skills ──> Pi package discovery (preserved)
+├── skills/mobile-agent-orchestrator/
+│   ├── SKILL.md ────────────> activation contract, decision gates, safe orchestration
+│   └── references/ ─────────> loaded on demand: platform, installation, recovery
+├── scripts/validate-package.mjs
+│   └── Node.js ESM validator ──> metadata, package contents, local Markdown links
+└── .github/workflows/
+    ├── ci.yml ──────────────> npm test on pull requests and main
+    └── tag-release.yml ─────> validated, merged-PR-only stable Git tags
+```
+
+Pi discovers the package's `skills/` directory through the `pi.skills` manifest. Other compatible CLIs discover the same skill through their own supported roots or configured paths. The `SKILL.md` file uses Agent Skills-compatible Markdown and YAML frontmatter; its references are deliberately loaded only when the workflow needs their detail. The validator and GitHub Actions verify the package and gate future tags, but they do not certify a live remote-agent deployment.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Features
+
+| Area | What the skill guides |
+| --- | --- |
+| Platform routing | macOS native or Windows 11 + WSL2 detection, with a safe stop for unsupported Windows-native paths. |
+| Private access | Tailscale overlay placement, constrained OpenSSH exposure, and mobile-client pairing without copying secrets into chat. |
+| Session continuity | Mosh with Moshi and `moshi-hook`, plus Herdr when supported or tmux as the fallback terminal host. |
+| Lifecycle planning | Supported WSL systemd, linger, and Windows-startup considerations; macOS mechanisms only after current official documentation and local evidence. |
+| Human control | Read-only discovery, one real decision at a time, explicit approval before sensitive changes, and local recovery preserved. |
+| Evidence and rollback | Non-sensitive verification checkpoints, disconnect and approved reboot checks, and mutation-scoped rollback guidance. |
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Runtime Stack
+
+The package implementation and the remote environment it orchestrates are separate layers.
+
+| Layer | Components | Responsibility |
+| --- | --- | --- |
+| **Package implementation** | Pi package manifest, Agent Skills-compatible Markdown/YAML frontmatter, Node.js ESM validator, npm, GitHub Actions | Preserves Pi discovery while validating the portable skill package and running CI/release checks. |
+| **Orchestrated runtime** | Tailscale, OpenSSH, Mosh, Moshi/`moshi-hook`, Herdr or tmux | Provides the private mobile connection and persistent-session workflow on the selected target. |
+| **Platform lifecycle** | Windows 11 + WSL2 systemd/linger/startup mechanisms, or macOS lifecycle mechanisms | Starts only the specifically approved services using current platform documentation. |
+
+Tailscale, OpenSSH, Mosh, Moshi, `moshi-hook`, Herdr, tmux, and platform lifecycle tooling are **runtime dependencies installed by the guided workflow**. They are not package-bundled npm dependencies, and their exact installation route is chosen from current signed vendor or platform documentation after approval.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Safety Boundaries
+
+- Never open public SSH access or add router port forwarding; constrain any listener before enabling it.
+- Keep Tailscale SSH disabled for the Moshi/OpenSSH key-authentication route.
+- For the full-Mosh Windows route, run Tailscale in exactly one location: **WSL**, not Windows and WSL together. On macOS, use macOS as the single location.
+- Do not place private keys, pairing tokens, sign-in URLs, QR data, or credentials in chat, shell history, or repository files. QR data is temporary secret material.
+- Require explicit approval before privileged installation, authentication or firewall changes, cloud pairing, service/task creation, reboot, or destructive rollback.
+- Preserve a local recovery path, validate SSH configuration before reload, test a second key-authenticated session, and record non-sensitive rollback evidence.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Verification and Recovery
+
+After each approved mutation, the workflow captures non-sensitive evidence for the private overlay, key-authenticated SSH, Mosh reconnection, session host, checkpoints, integrations, and notifications. A missing component or failed check is a finding—not authorization to make another change.
+
+Before an approved reboot, the guide states that live processes will die, confirms recovery and rollback paths, then checks the actual post-reboot state. Herdr and tmux do not preserve live processes across a physical reboot. A host may provide its own persisted checkpoint or resume mechanism; only Pi's supported JSONL behavior is described here, and no equivalent is claimed for other CLIs. Independently recorded cold-boot and live runtime evidence is not published for v0.2.0, so validate lifecycle and recovery on your target.
+
+Read the full [verification and recovery guide][verification-recovery] before applying lifecycle or rollback changes.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Contributing and Contact
+
+- [Contributing][contributing] — focused changes, test expectations, and release-PR rules.
+- [Release guide][release-guide] — Git-tag distribution and stable-release guardrails.
+- [Security policy][security] — report vulnerabilities privately; never include secrets in an issue.
+- [Issue tracker][issues] — report non-sensitive bugs and feature requests.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## License
+
+Distributed under the [MIT License][license].
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+[pi]: https://pi.dev
+[skill]: skills/mobile-agent-orchestrator/SKILL.md
+[platform-matrix]: skills/mobile-agent-orchestrator/references/platform-matrix.md
+[guided-install]: skills/mobile-agent-orchestrator/references/guided-install.md
+[verification-recovery]: skills/mobile-agent-orchestrator/references/verification-and-recovery.md
+[agent-hosts]: skills/mobile-agent-orchestrator/references/agent-hosts.md
+[contributing]: CONTRIBUTING.md
+[release-guide]: docs/RELEASE.md
+[security]: SECURITY.md
+[license]: LICENSE
+[issues]: https://github.com/egdev6/mobile-agent-orchestrator/issues