fastshell 0.3.7

Lightweight Bash + Python runtime SDK for mobile AI agents
Documentation
# FFI Reference

Platform-specific Foreign Function Interface for C, JNI (Android), and iOS.

## Common C FFI

Available on all desktop platforms (macOS, Linux):

```c
// Initialize with sandbox path
// Returns JSON: {"stdout":"","stderr":"","exit_code":0} on success
const char* fastshell_init(const char* sandbox_path);

// Execute a shell command
// Returns JSON: {"stdout":"...","stderr":"...","exit_code":0}
const char* fastshell_execute(const char* command);

// Set permission for a resource
// resource format: "network:example.com", "camera:photo"
// allowed: 0 = deny, 1 = allow
void fastshell_set_permission(const char* resource, uint8_t allowed);

// Cancel currently executing command
void fastshell_cancel_execution(void);

// Free a string returned by init/execute
void fastshell_free_string(char* ptr);
```

**Example usage (C):**
```c
const char* result = fastshell_init("/tmp/sandbox");
// Parse JSON result...
fastshell_free_string(result);

const char* output = fastshell_execute("ls -la");
printf("%s\n", output);
fastshell_free_string(output);

fastshell_set_permission("network:example.com", 1);
```

## Android (JNI)

```java
// In com/fastshell/Sdk.java
public class Sdk {
    static { System.loadLibrary("fastshell"); }

    // Native methods
    public static native String nativeInit(String sandboxPath);
    public static native String nativeExecute(String command);
    public static native String nativeGetCwd();
    public static native void nativeSetPermission(String resource, boolean allowed);
    public static native void nativeCancelExecution();
}
```

**Example (Kotlin):**
```kotlin
// Initialize
val result = Sdk.nativeInit("/data/data/com.example/files/fastshell")
val json = JSONObject(result)
if (json.getInt("exit_code") != 0) {
    throw Exception("Fastshell init failed: ${json.getString("stderr")}")
}

// Execute
val output = Sdk.nativeExecute("ls -la")
val outJson = JSONObject(output)
println(outJson.getString("stdout"))

// Handle permission
if (outJson.getInt("exit_code") == 100) {
    val stderr = outJson.getString("stderr")
    // stderr: "PERMISSION_NEEDED:network:example.com"
    showDialog { allowed ->
        Sdk.nativeSetPermission("network:example.com", allowed)
        retry()
    }
}

Sdk.nativeCancelExecution() // cancel if timeout
```

## iOS C FFI

```c
// iOS-specific function names
const char* fastshell_ios_init(const char* sandbox_path);
const char* fastshell_ios_execute(const char* command);
void fastshell_ios_set_permission(const char* resource, uint8_t allowed);
void fastshell_ios_cancel_execution(void);
void fastshell_free_string(char* ptr);
```

**Example (Swift):**
```swift
// Bridge header: #include "fastshell_ffi.h"

let result = fastshell_ios_init(strdup(sandboxPath))
if let json = String(cString: result!) {
    // Parse JSON...
}
fastshell_free_string(result)

let output = fastshell_ios_execute(strdup("echo hello"))
print(String(cString: output!))
fastshell_free_string(output)
```

## Return Value Format

All init/execute functions return a C string containing JSON:

```json
{
    "stdout": "command output here\n",
    "stderr": "",
    "exit_code": 0
}
```

**The caller MUST call `fastshell_free_string()`** on every returned pointer to avoid memory leaks.

## Permission Flow (FFI)

```
1. fastshell_execute("curl http://api.example.com")
   → {"exit_code":100, "stderr":"PERMISSION_NEEDED:network:api.example.com"}

2. Host parses exit_code=100, extracts resource from stderr
   → Shows native dialog

3. User approves → fastshell_set_permission("network:api.example.com", 1)

4. fastshell_execute("curl http://api.example.com")
   → {"exit_code":0, "stdout":"...response body..."}
```

## Thread Safety (FFI)

The FFI functions use a global `OnceLock<Mutex<Fastshell>>` singleton. Only one fastshell instance exists per process. All calls are internally synchronized via the mutex.

Concurrent calls from multiple threads are safe — they will queue behind the mutex.