Developer & AI Agent Technical Documentation

Canonical specification for human developers and autonomous AI agents building, packaging, and automating mini-apps on the MistFox platform.

Navigation

AI Agent Prompt Template Manifest.json Rules JavaScript SDK (Mist.*) Headless Background Runtime Packaging Tooling (.pkg) Developer REST API

1. AI Coding Agent Prompt Template

Provide this instruction block to your LLM or AI coding agent when creating or updating a MistFox mini-app:

PROMPT FOR AI AGENT (Copy & Paste)

You are an expert developer building a sandboxed mini-app for the MistFox Android platform.

PLATFORM INVARIANTS YOU MUST FOLLOW:
1. Entry Point: Your app must contain 'index.html', 'manifest.json', and 'mistfox-sdk.js'.
2. Native APIs: All hardware, storage, and device calls MUST go through the 'Mist' global object:
   - Storage: await Mist.storage.get(key), await Mist.storage.set(key, val)
   - Native UI: await Mist.ui.toast("Hello"), await Mist.ui.vibrate(50)
   - Network: await Mist.network.fetch(url, { method: "GET" })
3. Remote Code Execution (RCE) is strictly prohibited. Never use eval() or load remote script tags.
4. Security Boundaries:
   - Manifest 'id' must follow reverse domain notation: e.g. "com.mycompany.appname".
   - You can only call APIs declared under 'permissions' in your manifest.json.
5. Packaging:
   - Compress all files into a .pkg (ZIP archive) without directory prefixes.
   - Entry point file must exist in package root.

2. Manifest Specification (`manifest.json`)

Every package must include a manifest.json in its root directory:

{
  "id": "com.example.mynotes",
  "name": "Quick Notes",
  "version": "1.0.0",
  "versionCode": 1,
  "description": "Private offline notes application",
  "entry": "index.html",
  "icon": "icon.png",
  "permissions": [
    "storage",
    "vibrate"
  ],
  "background": {
    "enabled": true,
    "entry": "background/background.js",
    "events": ["schedule"],
    "permissions": ["storage", "notifications"]
  },
  "minMistFoxVersion": "1.0.0",
  "category": "Productivity"
}

3. JavaScript SDK Reference (`Mist.*`)

Method	Permission	Description
`Mist.storage.get(key)`	`storage`	Retrieves string value from per-app isolated storage
`Mist.storage.set(key, value)`	`storage`	Stores string value in per-app isolated storage
`Mist.ui.toast(text)`	None (Safe)	Displays native Android Toast notification
`Mist.ui.vibrate(ms)`	`vibrate`	Triggers haptic feedback motor
`Mist.camera.takePhoto()`	`camera`	Captures photo via system camera, returns Base64
`Mist.device.info()`	`device.info`	Returns device model, Android OS version, and battery level
`Mist.network.fetch(url, opts)`	`network`	Performs external HTTP request (DATA retrieval only)
`Mist.background.schedule(taskId, delayMs)`	`background`	Enqueues headless background task in AndroidX WorkManager

4. Headless Background Runtime

Background tasks execute in an isolated Mozilla Rhino 1.7.15 JavaScript environment orchestrated by AndroidX WorkManager.

In background/background.js, define the entry point:

function onBackgroundEvent(event) {
    // event.type: "schedule"
    // event.timestamp: epoch ms
    // event.appId: package ID

    var raw = Mist.call("storage.get", { key: "last_run" });
    Mist.call("storage.set", { key: "last_run", value: String(event.timestamp) });
}

5. Developer REST API (Automation)

Authenticate with your API key via the Authorization: Bearer <api_key> header.

Submit Package via cURL:

curl -X POST https://dev.mistfox.int.yt/api/dev/apps/upload \
  -H "Authorization: Bearer mf_dev_YOUR_API_KEY" \
  -F "package=@dist/calculator.pkg" \
  -F "notes=v1.0.1 release fixing calculation precision"

Query App Audit Status:

curl https://dev.mistfox.int.yt/api/dev/apps \
  -H "Authorization: Bearer mf_dev_YOUR_API_KEY"