Native Bridges

Platform bridge actions

Use platform.run when a plugin needs native OS or device data. The app runs the operation, stores the result under app.pluginData[pluginId][resultKey], records lastPlatformResult, and rebuilds plugin UI.

return {
  __action: "platform.run",
  operation: "systemInfo",
  pluginId: "platform-system-plugin",
  resultKey: "systemInfo"
};

Wi-Fi SSID/router names, SMS inbox, contacts, call logs, phone identity, and similar private data are OS-permission and store-policy controlled. The bridge exposes safe diagnostics and launcher flows by default, and returns structured unsupported results when an operation does not apply on the current OS.

Mail, SMS, phone, calendar, and contacts

Launcher operations open the user’s installed OS handler. They create drafts or dialer screens; they do not silently send SMS/email or place phone calls.

commands: {
  "productivity.sms": function(ctx) {
    return {
      __action: "platform.run",
      operation: "composeSms",
      pluginId: "productivity-files-plugin",
      resultKey: "sms",
      to: ["+10000000000"],
      body: "BuildAPlugin SMS draft"
    };
  },

  "productivity.phone": function(ctx) {
    return {
      __action: "platform.run",
      operation: "phoneDial",
      pluginId: "productivity-files-plugin",
      resultKey: "phone",
      number: "+10000000000"
    };
  },

  "productivity.calendar": function(ctx) {
    return {
      __action: "platform.run",
      operation: "calendarEvent",
      pluginId: "productivity-files-plugin",
      resultKey: "calendar",
      title: "Bridge test",
      start: "2026-07-05T10:00:00Z",
      end: "2026-07-05T10:30:00Z"
    };
  }
}

Android and Windows bridge snapshots

androidSnapshot is Android-only and returns non-sensitive native metadata: build info, app info, battery, display, sensors, system features, declared permissions, handler counts, and default SMS package. windowsSnapshot is Windows-only and returns built-in system diagnostics where PowerShell and local permissions allow it.

return {
  __action: "platform.run",
  operation: "androidSnapshot",
  pluginId: "platform-tools",
  resultKey: "androidSnapshot"
};

return {
  __action: "platform.run",
  operation: "windowsSnapshot",
  pluginId: "platform-tools",
  resultKey: "windowsSnapshot"
};

Files, preferences, clipboard, and secure storage

Use file operations for user-selected files/folders or explicit paths, preferences for simple plugin/app settings, clipboard actions for text transfer, and secure storage for secrets that should use the OS-backed credential store where supported.

return {
  __action: "platform.run",
  operation: "preferencesWrite",
  pluginId: "settings-plugin",
  resultKey: "saved",
  key: "settings-plugin.mode",
  value: "diagnostics"
};

Bluetooth and BLE actions

Bluetooth operations are returned as normal command actions. The app runs the native operation, stores the result under your plugin data, and rebuilds the plugin UI so you can display the latest status, devices, or errors.

commands: {
  "bluetoothTest.status": function(ctx) {
    return {
      __action: "bluetooth.run",
      operation: "status",
      pluginId: "bluetooth-test-plugin",
      resultKey: "status"
    };
  },

  "bluetoothTest.scan": function(ctx) {
    return {
      __action: "bluetooth.run",
      operation: "scan",
      pluginId: "bluetooth-test-plugin",
      resultKey: "scan",
      timeoutSeconds: 8
    };
  }
}

A bundled Bluetooth Test plugin demonstrates this pattern. It shows adapter availability, permission state, scan state, device count, device labels, RSSI, and raw JSON.

Media actions

Media operations are also plain actions. Use the helper methods when available, or return the raw action object directly.

transformApp: function(app, api) {
  api.ui.append(app, "rightPanel", {
    type: "card",
    id: "cameraToolsCard",
    children: [
      { type: "button", id: "cameraToolsPermission", text: "Request camera", command: "cameraTools.request" },
      api.media.cameraPreviewNode("cameraToolsPreview", { height: 320, facingMode: "user" })
    ]
  });
  return app;
},

commands: {
  "cameraTools.request": function(ctx) {
    return ctx.media.requestCamera({ pluginId: "camera-tools", resultKey: "cameraPermission" });
  }
}

Voice workflow recorder and transcription

Plugins can collect spoken workflow instructions, save typed instructions, start/stop native voice recording, and ask the app to transcribe the captured audio. The resulting transcript is stored in plugin data and can be used by the AI plugin builder.

commands: {
  "voice.start": function(ctx) {
    return { __action: "nativeVoice.startRecording", pluginId: "voice-workflow-recorder" };
  },
  "voice.stop": function(ctx) {
    return { __action: "nativeVoice.stopAndTranscribe", pluginId: "voice-workflow-recorder" };
  }
}

In-app UI robot

uiRobot.run is available only in internal debug/test builds. It drives registered Flutter targets, captures screenshots and app state, and records failures without taking over the user's real mouse. Use it for local generated-plugin validation and repeatable frontend debugging; it returns no customer-facing capability because the entire driver path is compile-time disabled in public releases.

return {
  __action: "uiRobot.run",
  steps: [
    { action: "type", targetId: "urlInput", value: "https://jsonplaceholder.typicode.com/posts/1" },
    { action: "click", targetId: "sendButton" },
    { action: "capture", label: "after-send" }
  ]
};