@intentcomputing/koko-agent-sdk 1.0.1

package/android/src/main/java/cn/intentcomputing/kokoagentsdk/KokoAgentSdkPackage.java

@@ -0,0 +1,23 @@
+package cn.intentcomputing.kokoagentsdk;
+
+import androidx.annotation.NonNull;
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+import java.util.Collections;
+import java.util.List;
+
+public class KokoAgentSdkPackage implements ReactPackage {
+  @NonNull
+  @Override
+  public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
+    return Collections.<NativeModule>singletonList(new KokoAgentSdkModule(reactContext));
+  }
+
+  @NonNull
+  @Override
+  public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
+    return Collections.emptyList();
+  }
+}

package/docs/INTEGRATION.md

@@ -0,0 +1,168 @@
+# Integration guide · `@intentcomputing/koko-agent-sdk`
+
+For React Native host apps. After installing the package you must link native code and rebuild once — the same flow as other RN libraries with native modules.
+
+> 中文版：[INTEGRATION.zh-CN.md](./INTEGRATION.zh-CN.md)
+
+## Prerequisites
+
+- React Native ≥ 0.73 (or Expo Dev Client / `expo prebuild` — **not Expo Go**)
+- iOS deployment target ≥ 15; ability to run `pod install`
+- An **app token** from Intent Computing (`gateway.token` — not a DeepSeek / OpenAI key)
+
+## Checklist
+
+1. Install the npm package
+2. iOS: `pod install` (Android usually autolinks)
+3. **Rebuild native** (Debug or Release)
+4. Wrap the root tree with `KokoProvider` and set `token`
+5. Launch and send a natural-language goal
+
+JS-only config changes can hot-reload via Metro. **First integration or any native SDK change requires a native rebuild.**
+
+---
+
+## 1. Install
+
+```bash
+npm install @intentcomputing/koko-agent-sdk
+# or
+yarn add @intentcomputing/koko-agent-sdk
+```
+
+Yarn workspaces example:
+
+```bash
+yarn workspace @your/mobile add @intentcomputing/koko-agent-sdk
+```
+
+## 2. Link native code
+
+**iOS**
+
+```bash
+cd ios && pod install && cd ..
+```
+
+**Android**
+React Native autolinking picks up `android/`. No manual Package registration unless autolinking is disabled.
+
+## 3. Rebuild the host app
+
+```bash
+npx react-native run-ios
+npx react-native run-android
+# or Xcode / Android Studio / expo run:ios|android
+```
+
+Without a rebuild, `dump` / `tap` will fail because the native module is missing.
+
+## 4. Root provider
+
+Wrap at the app root (or outermost navigation shell):
+
+```tsx
+import { KokoProvider } from '@intentcomputing/koko-agent-sdk';
+
+export default function App() {
+  return (
+    <KokoProvider
+      config={{
+        gateway: {
+          token: 'YOUR_APP_TOKEN',
+          // Default: https://sdk.intentcomputing.net
+          // China: https://sdk.intentcomputing.cn
+          // baseUrl: 'https://sdk.intentcomputing.cn',
+        },
+        // locale: 'en', // default
+        // locale: 'zh',
+        // branding: { name, tagline, placeholder, primaryColor, icon },
+      }}
+    >
+      <Home />
+    </KokoProvider>
+  );
+}
+```
+
+`KokoProvider` will:
+
+- Initialize the agent with `gateway.token`
+- Mount cursor, progress, and chat sheet (optional — see below)
+
+Open chat from host UI:
+
+```tsx
+import { getKokoAgent } from '@intentcomputing/koko-agent-sdk';
+
+getKokoAgent().openChat();
+// or getKokoAgent().runGoal('Open settings');
+```
+
+### Optional props / config
+
+| Key | Purpose | Default |
+|--|--|--|
+| `cursor` | Action cursor overlay | `true` |
+| `observer` | Progress + chat host | `true` |
+| `dialogs` | Confirm / ask-user dialogs | `true` |
+| `config.locale` | `en` \| `zh` | **`en`** |
+| `config.branding` | Name, placeholder, accent | SDK defaults |
+| `config.webWalletAliases` | Public labels under which the host's own injected wallet appears in web wallet choosers; declare only verified aliases | None |
+| `config.debug` | Verbose logs | On in Metro development builds unless explicitly `false`; off in release builds |
+
+## 5. Contract for React Native hosts
+
+The SDK observes the current native view tree and verifies actions against the live screen. It does not assume a wallet layout, fixed tab names, header coordinates or a particular navigation library. Provide the following semantics so navigation and private boundaries remain reliable across custom components and locales.
+
+- **Appearance:** initialize `config.locale`, `config.theme` and `config.branding` at the SDK entry. When host preferences change, call `setKokoAppearance({ locale: hostLocale, theme: hostTheme })`; report the host's actual `light`/`dark` theme. SDK chrome currently uses the opposite theme for contrast. Built-in UI supports English and Chinese; branding remains subject to the app's entitlement.
+- **Controls:** use meaningful `accessibilityLabel`, button/tab roles and stable, unique `testID` values, including icon-only Back/Close controls. Keep disabled and selected state accurate. A menu offering “Export private key” is ordinary navigation; its label alone is not proof that a private value is displayed. Offscreen targets require revealing the actual scrollable region before a tap.
+- **Private surfaces:** set `secureTextEntry` on credential fields. Before displaying passwords, PIN/OTP/CVV, recovery phrases, private keys or their verification choices, declare a host gate with `setAppUserGate`. Also mark the containing private surface with an explicit ID such as `privacy-sensitive-mnemonic` or `privacy-sensitive-private-key`. Clear the gate only after all private surfaces have been left. Never put secret values in gate labels, test IDs, accessibility labels, task text or logs. The user completes these steps locally; ordinary navigation copy may be sent to the gateway. Text heuristics are a fallback and cannot establish privacy boundaries in every language or custom widget.
+- **Host callbacks:** `registerHostActions` is optional. Register callbacks only for controls that are currently mounted and visible, give each control a unique identity, and unregister on blur, unmount or loss of visibility. Match the same user-visible action; do not use callbacks as hidden routes around scrolling, disabled controls or private gates. A callback resolving is not evidence that the requested task succeeded.
+- **Loading and completion:** expose loading/error copy and meaningful selected/value state in the native tree. Keep the user on an observable loading state until a result is known, then expose a stable result or destination. Tasks wait and re-observe changes; repeated labels, an invoked callback or a matching page title do not by themselves prove completion.
+- **Exploration:** `bootstrapExplore` now observes only the current public screen and records public control labels as local hints. It performs no taps, swipes, typing, host callbacks, LogBox changes or task replacement, and requires existing dump permission. Private/gated and unreadable screens return failure without recording a new node. The result always has `steps: 0`; legacy crawl options (`mode`, step/screen limits, priority/skip patterns and action-progress callbacks) are retained as deprecated API fields and are ignored. Normal tasks never automatically replay an exploration route.
+
+Runtime appearance example:
+
+```tsx
+import { setKokoAppearance } from '@intentcomputing/koko-agent-sdk';
+
+useEffect(() => {
+  setKokoAppearance({ locale: hostLocale, theme: hostTheme });
+}, [hostLocale, hostTheme]);
+```
+
+For custom private UIs, declare the gate before navigation or reveal and keep it active through verification. Use `clearAppUserGate()` once the host confirms a public destination. Secure fields, explicit private markers and host gates protect the upload boundary; do not rely on a screen's title or number of buttons as the integration contract.
+
+## 6. Verify
+
+1. Launch the app and use your host button wired to `openKokoChat()`. The provider does not create a host entry button.
+2. Send a verifiable goal; you should see dump → tap with a visible cursor.
+3. Check that requests use the selected official gateway and a token bound to this app. Do not bundle an LLM API key. Validate privacy gates and outbound payloads using synthetic data.
+
+---
+
+## FAQ
+
+**npm + config only, no native rebuild?**
+No. This SDK ships iOS/Android native modules (same class as Reanimated, Sentry RN, Keychain, etc.).
+
+**Must it wrap the root?**
+Recommended. It is the init + UI mount point. You may use `initKokoAgent` and custom UI instead.
+
+**Expo Go?**
+Not supported. Use a Dev Client, bare RN, or a production host binary.
+
+**Linking an unpublished local checkout?**
+Use `portal:` / `file:`. If the package lives **outside** the monorepo, Metro may need `watchFolders` + `extraNodeModules` (usually unnecessary after npm publish).
+
+**Where does the token come from?**
+Intent Computing console / commercial onboarding — not a model-vendor API key.
+
+---
+
+## Related
+
+- Package overview: [../README.md](../README.md)
+- npm publish: [PUBLISH.md](./PUBLISH.md)
+- 中文接入指南: [INTEGRATION.zh-CN.md](./INTEGRATION.zh-CN.md)

package/docs/INTEGRATION.zh-CN.md

@@ -0,0 +1,140 @@
+# 接入指南 · @intentcomputing/koko-agent-sdk
+
+> Canonical English guide: [INTEGRATION.md](./INTEGRATION.md)
+
+面向 React Native 宿主 App。装完依赖后需链原生并重编一次，与常见带 native 模块的 RN 库相同。
+
+## 前置条件
+
+- React Native ≥ 0.73（或 Expo Dev Client / `expo prebuild`，**不支持 Expo Go**）
+- iOS 部署目标 ≥ 15；需本机可 `pod install`
+- 从 Intent Computing 拿到 **应用 token**（`gateway.token`，不是 DeepSeek / OpenAI Key）
+
+## 步骤一览
+
+1. 安装 npm 包
+2. iOS `pod install`（Android 一般靠 autolinking）
+3. **重新编译原生**（Debug / Release 均可）
+4. 根组件包一层 `KokoProvider` 并配置 token
+5. 将 `openKokoChat()` 对接宿主入口，再发自然语言任务
+
+之后若只改 JS 配置或升级包的纯 JS 部分，Metro 热更新即可；**SDK 含原生改动或首次接入，必须再编原生。**
+
+---
+
+## 1. 安装
+
+```bash
+npm install @intentcomputing/koko-agent-sdk
+# 或
+yarn add @intentcomputing/koko-agent-sdk
+```
+
+Yarn monorepo 示例：
+
+```bash
+yarn workspace @your/mobile add @intentcomputing/koko-agent-sdk
+```
+
+## 2. 链接原生
+
+**iOS**
+
+```bash
+cd ios && pod install && cd ..
+```
+
+**Android**
+RN autolinking 会拉取 `android/`；除非关闭了 autolinking，否则无需手写 Package。
+
+## 3. 编译宿主 App
+
+```bash
+npx react-native run-ios
+npx react-native run-android
+# 或 Xcode / Android Studio / expo run:ios|android
+```
+
+未编进原生模块时，`dump` / `tap` 会失败。
+
+## 4. 根组件接入
+
+```tsx
+import { KokoProvider } from '@intentcomputing/koko-agent-sdk';
+
+export default function App() {
+  return (
+    <KokoProvider
+      config={{
+        gateway: {
+          token: 'YOUR_APP_TOKEN',
+          // 默认 https://sdk.intentcomputing.net（OpenAI）
+          // 国内：https://sdk.intentcomputing.cn（DeepSeek）
+          baseUrl: 'https://sdk.intentcomputing.cn',
+        },
+        locale: 'zh', // SDK UI 默认英文；中文请显式设置
+        // branding: { name, tagline, placeholder, primaryColor, icon },
+      }}
+    >
+      <Home />
+    </KokoProvider>
+  );
+}
+```
+
+宿主也可主动打开会话：
+
+```tsx
+import { getKokoAgent } from '@intentcomputing/koko-agent-sdk';
+
+getKokoAgent().openChat();
+```
+
+### 可选开关
+
+| prop / config | 含义 | 默认 |
+|--|--|--|
+| `cursor` | 操作光标 | `true` |
+| `observer` | 进度条 + 对话宿主 | `true` |
+| `dialogs` | 确认 / 追问弹窗 | `true` |
+| `config.locale` | `en` / `zh` | **`en`** |
+| `config.branding` | 名称、占位文案、主色等 | SDK 默认 |
+| `config.webWalletAliases` | 宿主确认属于自身注入钱包的公开选项名称 | 无 |
+| `config.debug` | 调试日志 | Metro 开发构建默认开启，正式构建默认关闭 |
+
+### 宿主接入约定
+
+- 语言或主题改变时调用 `setKokoAppearance({ locale, theme })`；品牌配置需应用具备对应权益。
+- 为按钮（包括纯图标按钮）提供有意义的无障碍名称、角色及稳定标识，保证禁用、选中和滚动状态真实可见。
+- 在密码、助记词、私钥及验证页面出现前调用 `setAppUserGate` 并标记敏感页面，用户完成操作并离开后再调用 `clearAppUserGate`。使用虚构数据验证日志与上行请求；详见[隐私说明](PRIVACY.zh-CN.md)。
+- iOS 内嵌网页可使用本地 OCR 和 JS 点击，但真实手势、跨框架内容及无标签控件存在限制；钱包连接和断开流程尚未完成端到端验收。
+
+## 5. 验收
+
+1. 启动 App，通过接有 `openKokoChat()` 的宿主按钮打开助手；Provider 不会自动创建宿主入口。
+2. 输入可核验目标，应看到 dump → tap 与光标。
+3. 请求打到官网网关（或 `baseUrl`），App 内无任何 LLM API Key。
+
+---
+
+## 常见问题
+
+**只用 npm + 配置、不重编原生？**
+不行。本 SDK 含 iOS/Android 原生模块。
+
+**必须包在根组件？**
+推荐。也可自行 `initKokoAgent` 并自建 UI。
+
+**Expo Go？**
+不支持。
+
+**本地未发布源码？**
+可用 `portal:` / `file:`；包在 monorepo 外时可能需 Metro `watchFolders`（npm 发布后通常不需要）。
+
+---
+
+## 相关
+
+- 英文总览：[../README.md](../README.md)
+- 中文总览：[../README.zh-CN.md](../README.zh-CN.md)
+- 发布：[PUBLISH.zh-CN.md](./PUBLISH.zh-CN.md)

package/docs/PRIVACY.md

@@ -0,0 +1,11 @@
+# Privacy and sensitive screens
+
+The host is responsible for protecting credentials and wallet secrets. Before a password, private key, recovery phrase, import, backup, or verification screen is displayed, mark the containing surface with a stable `testID` such as `privacy-sensitive-recovery-phrase` or `privacy-sensitive-private-key`. Use `secureTextEntry` for password fields. Never put secret values in labels, IDs, task text, screenshots, or logs.
+
+For a sensitive flow, call `setAppUserGate` before content appears and `clearAppUserGate` only after the sensitive surface has been removed. Use a generic prompt that contains no secret. The user completes the step in the host app. See the [integration guide](INTEGRATION.md) for the API.
+
+The SDK uses screen heuristics and client/server redaction as additional defenses, not as substitutes for host markers and gates. For ordinary planning, the SDK can send a redacted screen model, task text, and operation history to the configured gateway and its model provider. Do not assume that unmarked custom surfaces, WebViews, or an accessibility tree are automatically safe. Validate outgoing requests and logs using synthetic data before shipping.
+
+Local OCR helps locate visible text; only selected goal-derived labels and an allowlist of public wallet names are eligible as planner hints. Host wallet provider capability checks are local. A user must personally handle credentials, wallet authorizations, and signatures. Never use a production recovery phrase or private key as test data.
+
+Report suspected vulnerabilities privately as described in [SECURITY.md](../SECURITY.md).

package/docs/PRIVACY.zh-CN.md

@@ -0,0 +1,11 @@
+# 本地隐私步骤与可见目标
+
+助记词展示、备份、验证、导入，以及私钥和密码输入必须由用户在宿主内完成。SDK 在这些页面暂停任务，不代选助记词、不代填密码，不把页面树、OCR、页面摘要或截图发送给模型。离开隐私页后才恢复；点击“已完成”不能绕过仍在展示的隐私页。
+
+宿主应为敏感内容容器加固定标记，例如 `testID="privacy-sensitive-recovery-phrase"` 或 `testID="privacy-sensitive-private-key"`。不要把实际单词、私钥或密码拼进 `testID`、无障碍标签或日志。密码输入框应启用 `secureTextEntry`。这些标记应覆盖导入、展示与验证的所有状态。
+
+对于原生树不能可靠识别的页面，宿主还可以在页面聚焦时调用 `setAppUserGate({ kind: 'recovery_phrase', label: '请在本机完成助记词验证' })`，离开后调用 `clearAppUserGate()`；私钥使用 `kind: 'private_key'`。在页面内容出现前设置，在内容移除后清除，避免后台仍挂载的路由干扰当前页。页面标题启发式识别只是兜底，不能替代宿主显式标记。标签中只放通用提示。
+
+发送层重新检查当前原生页面，丢弃调用方传入的原始 OCR、摘要和截图字段，从同一份脱敏树生成上传内容。进入隐私步骤时清空规划历史；网关也拒绝已识别的隐私页。调试时仅使用虚构数据验证请求拦截，不用真实秘密测试脱敏。
+
+点击只针对当前可见目标。目标缺失时，SDK 只在原生确认可纵向滚动的容器内执行可见滑动，每次重新读取页面，找到目标后才单次点击。列表不再变化或达到搜索上限时停止并报告未找到，避免连续猜点。

package/docs/PUBLISH.md

@@ -0,0 +1,11 @@
+# Publishing the SDK
+
+This guide is for package maintainers. Consumers should follow the [integration guide](INTEGRATION.md). The hosted gateway is maintained and deployed separately; it is not published in the npm package or public SDK repository.
+
+1. Check the changelog, package metadata, version, and supported platforms. npm versions are immutable; choose a new semantic version for each release.
+2. Run `npm ci`, `npm test -- --runInBand --watchman=false`, and `npm run build`. Verify native changes in representative hosts.
+3. Inspect `npm pack --dry-run` and the resulting tarball. Never include environment files, credentials, host app data, build caches, or private code.
+4. Authenticate to `https://registry.npmjs.org/` using an account with publishing rights. npm may require two-factor authentication for publication. Keep tokens out of the repository.
+5. Publish with `npm publish --access public --registry https://registry.npmjs.org/`. Verify the version, dist-tag, and artifact integrity in the registry, allowing for cache propagation.
+
+If the registry reports a staged release, a maintainer must review and approve it before it is publicly installable. Follow [npm's staged publishing documentation](https://docs.npmjs.com/staged-publishing/).

package/docs/PUBLISH.zh-CN.md

@@ -0,0 +1,11 @@
+# 发布 SDK
+
+本文面向包维护者；接入请看[接入指南](INTEGRATION.zh-CN.md)。网关服务独立维护和部署，不包含在 npm 包或公开 SDK 仓库中。
+
+1. 检查变更记录、包信息、版本和支持的平台。npm 版本不可覆盖，每次发布使用新的语义化版本。
+2. 执行 `npm ci`、`npm test -- --runInBand --watchman=false` 和 `npm run build`；原生代码变更需在代表性宿主中验证。
+3. 检查 `npm pack --dry-run` 和实际 tarball；不得包含环境文件、凭证、宿主数据、构建缓存或私有代码。
+4. 通过 `https://registry.npmjs.org/` 使用有发布权限的账号登录；npm 可能要求双重验证。不要把令牌提交到仓库。
+5. 执行 `npm publish --access public --registry https://registry.npmjs.org/`，再核实仓库版本、dist-tag 和包完整性，并考虑缓存传播延迟。
+
+若 npm 显示暂存发布，需由维护者审查并批准后才能公开安装，具体见 [npm 暂存发布文档](https://docs.npmjs.com/staged-publishing/)。

package/ios/KokoAgentSdk/KokoAgentSdk.h

@@ -0,0 +1,5 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+@interface KokoAgentSdk : NSObject <RCTBridgeModule>
+@end