fastshell 0.3.7

Lightweight Bash + Python runtime SDK for mobile AI agents
Documentation
# Mobile Integration Notes

Platform-specific requirements and best practices for Android and iOS.

## Single-Process Guarantee

On mobile (`allow_subprocess = false`), fastshell is **100% single-process**. All built-in commands, pipelines, and Python execution run within the host app's process. This avoids:

- **Android 12+ Phantom Process Killer** — kills apps exceeding 32 total phantom processes across all apps combined (SIGKILL signal 9)
- **iOS fork() prohibition** — iOS forbids process creation (`fork`/`exec`)

## Android

### Network (HTTP)

Android 9+ (API 28) blocks cleartext HTTP by default. Required configuration:

**AndroidManifest.xml:**
```xml
<application android:usesCleartextTraffic="true">
```

Or use `network_security_config.xml` for per-domain control.

### Keep-Alive (Foreground Service)

To prevent Android from killing the app in background, implement a Foreground Service:

```kotlin
class FastshellService : Service() {
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        val notification = NotificationCompat.Builder(this, CHANNEL_ID)
            .setContentTitle("fastshell running")
            .setSmallIcon(R.drawable.ic_terminal)
            .build()
        startForeground(1, notification)
        // Initialize and run fastshell here
        return START_STICKY
    }
}
```

**Manifest:**
```xml
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<service android:name=".FastshellService"
         android:foregroundServiceType="dataSync" />
```

### Vendor-Specific (Kill Prevention)

Many manufacturers (Xiaomi, Huawei, Samsung, Oppo) have aggressive battery optimization that kills background apps. Guide users to:
1. Disable battery optimization for your app
2. Enable "Auto-start" (Xiaomi, Huawei)
3. Lock app in recent tasks

See [dontkillmyapp.com](https://dontkillmyapp.com) for vendor-specific instructions.

### VFS Root

```kotlin
val sandboxPath = applicationContext.filesDir.resolve("fastshell").absolutePath
// → /data/data/<package>/files/fastshell
```

### APK Size

The `.so` file for arm64 is ~10MB. This adds directly to the APK size.

## iOS

### Network (ATS)

iOS App Transport Security blocks cleartext HTTP. Required in **Info.plist**:

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
```

Or configure per-domain exceptions for better security.

### Background Execution

iOS limits background execution severely:
- **~30 seconds** of background time after app is suspended
- No reliable way to keep running indefinitely (by design)
- Limited background modes: audio, location, VoIP, background fetch, remote notifications

**For fastshell: accept "foreground-only" execution model on iOS.** The agent interacts with fastshell while the app is active. If the app goes to background, the command may be paused/killed.

### VFS Root

```swift
let documentsPath = FileManager.default
    .urls(for: .documentDirectory, in: .userDomainMask)[0]
    .appendingPathComponent("fastshell")
// → <app>/Documents/fastshell
```

**Do NOT use:**
- `NSTemporaryDirectory()` — may be purged at any time
- `Library/Caches/` — may be purged by system when storage is low

### App Store Review

Apple App Store 审核指南 (Section 2.5.2) 要求 App 的主要功能代码随安装包提供,Google Play 也有类似政策。Python 作为一种解释型语言,只要脚本和解释器都随 App 打包,就是合规的。

fastshell 的设计完全适配这个场景:
- **CPython 解释器**:编译期通过 `include_bytes!()` 嵌入,App 启动时从二进制解压到沙箱,无需网络
- **Python 脚本和依赖**:建议在构建阶段放入 App assets,首次启动拷贝到沙箱。fastshell 的 `execute()` 会自动将 `sandbox/python/site-packages/` 注入 `sys.path`,使 `import` 能正确解析
- **不依赖运行时下载**:`pip install` 在移动端本来就没有可用的 pip 环境和 shell,因此这个限制自然成立

`CpythonDownloader::ensure_available()` 仅用于桌面端开发调试。生产构建时 CPython 已随 APK/IPA 嵌入,无需调用此函数。

详见 `fastshell/docs/integration.md` 了解完整的构建打包流程。

### Binary Size

The `.a` static library for arm64 is ~39MB. This adds directly to the app binary.

## Desktop (macOS / Linux)

No platform restrictions. `allow_subprocess = true` by default, all features available without configuration.

## Common Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| `curl` fails with TLS error on iOS | ATS blocks HTTP | Add `NSAllowsArbitraryLoads` to Info.plist |
| `curl` fails with connection refused on Android | Cleartext HTTP blocked | Add `usesCleartextTraffic="true"` to Manifest |
| App killed in background (Android) | Battery optimization | Foreground Service + disable battery optimization |
| Commands fail when app is backgrounded (iOS) | iOS background limit | Accept foreground-only execution model |
| "command not found (subprocess disabled)" | Blocked unknown commands | Enable `allow_subprocess` (desktop) or use built-in alternatives |
| Python `import` fails for third-party libs | Library not bundled | Place library files under sandbox/python/site-packages/ |