@intentcomputing/koko-agent-sdk 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.1
+
+- Clarify npm setup, host-provided entry controls, regional gateways, and privacy responsibilities in the published documentation.
+- Document the current WebView and wallet-flow limitations.
+
+## 1.0.0
+
+- Initial npm release of the React Native SDK, including iOS and Android native modules, visible task progress, host appearance configuration, and privacy gates.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of conduct
+
+We follow the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be respectful and constructive, respect privacy, and report unacceptable behavior privately to hello@intentcomputing.cn.

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Issues and pull requests are welcome. Explain the host environment, expected behavior, actual behavior, and reproduction steps. Use synthetic accounts and placeholder values in examples, logs, and screenshots; never include passwords, recovery phrases, private keys, access tokens, or customer data.
+
+Use Node.js 20 or later. Install dependencies with `npm ci`, run `npm test -- --runInBand --watchman=false`, and run `npm run build`. For native changes, build a representative iOS or Android host and describe the platform and device tested. Tests must not require a live wallet, production credentials, or a model provider.
+
+Keep changes host-agnostic and update documentation for public API changes. SDK native changes require a host rebuild. The hosted gateway is maintained separately and is not part of this repository.
+
+By submitting a contribution, you agree it can be distributed under the [MIT license](LICENSE). Follow the [Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intent Computing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Koko Agent SDK
+
+React Native SDK for an observable in-app assistant. The host supplies an app token and presents a user goal; the SDK observes the screen, asks the hosted gateway for a next step, and performs supported actions inside the app.
+
+[npm package](https://www.npmjs.com/package/@intentcomputing/koko-agent-sdk) · [中文](README.zh-CN.md) · [Integration guide](docs/INTEGRATION.md) · [Privacy](docs/PRIVACY.md) · [Contributing](CONTRIBUTING.md)
+
+## Requirements
+
+- React Native 0.73 or later and React 18 or later; iOS 15 or later or an Android host supporting React Native autolinking.
+- Expo development build or a native build; Expo Go cannot load this native module.
+- An Intent Computing app token bound to the host bundle ID or Android application ID. The app token is not an OpenAI or DeepSeek API key.
+
+## Install
+
+```sh
+npm install @intentcomputing/koko-agent-sdk
+cd ios && pod install && cd .. # iOS
+```
+
+Rebuild and reinstall the native app after installation or a native SDK upgrade. In a Yarn workspace, add the package to the mobile workspace with `yarn workspace <workspace-name> add @intentcomputing/koko-agent-sdk`.
+
+## Quick start
+
+Mount the provider around the host navigation tree and connect `openKokoChat()` to a host button. Replace the placeholder with the token issued for your host app and environment.
+
+```tsx
+import React from 'react';
+import { Button, View } from 'react-native';
+import { KokoProvider, openKokoChat } from '@intentcomputing/koko-agent-sdk';
+
+export default function App() {
+  return (
+    <KokoProvider config={{ gateway: { token: 'YOUR_APP_TOKEN' }, locale: 'en' }}>
+      <View style={{ flex: 1 }}>
+        {/* Your app and navigation go here. */}
+        <Button title="Open assistant" onPress={() => openKokoChat()} />
+      </View>
+    </KokoProvider>
+  );
+}
+```
+
+The default gateway is `https://sdk.intentcomputing.net` (OpenAI). For China, set `gateway.baseUrl` to `https://sdk.intentcomputing.cn` (DeepSeek). Use a token valid for the chosen environment. Provider API keys stay on the gateway and must not be bundled into the app.
+
+Call `setKokoAppearance({ locale, theme })` when host preferences change. Configure branding through `config.branding`; custom branding is subject to the app's entitlement. See the [integration guide](docs/INTEGRATION.md) for host actions, privacy gates, and lifecycle details.
+
+## Privacy and limits
+
+Host apps must mark and gate password, private-key, recovery-phrase and verification screens before displaying sensitive content. Users complete those steps themselves. The SDK sends redacted screen information and task context to the configured gateway for planning; integration authors must validate these boundaries with synthetic data. See [Privacy](docs/PRIVACY.md).
+
+The SDK works best with labelled, visible React Native controls. iOS WebView support includes local text recognition and JavaScript-based clicks; websites that require trusted gestures, nested frames, or unlabelled icons may need host support. Wallet connection and disconnect flows have not yet passed complete end-to-end acceptance. Do not treat a click or authorization prompt alone as proof of task completion.
+
+## Development
+
+```sh
+npm ci
+npm test -- --runInBand --watchman=false
+npm run build
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md). The gateway is a separately operated service and its source is not part of this public SDK repository.
+
+## License
+
+[MIT](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,50 @@
+# Koko Agent SDK
+
+面向 React Native 的应用内助手 SDK。用户描述任务后，SDK 观察宿主当前页面，通过网关规划下一步，并在宿主内执行支持的操作，过程对用户可见。
+
+[npm 包](https://www.npmjs.com/package/@intentcomputing/koko-agent-sdk) · [English](README.md) · [接入指南](docs/INTEGRATION.zh-CN.md) · [隐私保护](docs/PRIVACY.zh-CN.md)
+
+## 前置条件
+
+- React Native ≥ 0.73、React ≥ 18；iOS ≥ 15，或支持原生自动链接的 Android 宿主。
+- Expo 使用开发构建或原生构建，不支持 Expo Go。
+- 使用绑定宿主 Bundle ID / Android Application ID 的应用 token；它不是模型 API 密钥。
+
+## 安装
+
+```sh
+npm install @intentcomputing/koko-agent-sdk
+cd ios && pod install && cd .. # iOS
+```
+
+首次安装或升级包含原生改动的 SDK 后，需重新构建并安装宿主。在 Yarn 工作区中请将依赖添加到移动端 workspace。
+
+## 接入
+
+```tsx
+import React from 'react';
+import { Button, View } from 'react-native';
+import { KokoProvider, openKokoChat } from '@intentcomputing/koko-agent-sdk';
+
+export default function App() {
+  return (
+    <KokoProvider config={{
+      gateway: { token: 'YOUR_APP_TOKEN', baseUrl: 'https://sdk.intentcomputing.cn' },
+      locale: 'zh',
+    }}>
+      <View style={{ flex: 1 }}>
+        {/* 在此放置宿主页面和导航。 */}
+        <Button title="打开助手" onPress={() => openKokoChat()} />
+      </View>
+    </KokoProvider>
+  );
+}
+```
+
+默认网关为海外的 `https://sdk.intentcomputing.net`（OpenAI）；国内请显式选择 `https://sdk.intentcomputing.cn`（DeepSeek）。使用对应环境的应用 token，模型 API 密钥只保留在网关。语言或主题变化时调用 `setKokoAppearance({ locale, theme })`；品牌配置通过 `config.branding` 传入，并受应用权益控制。
+
+宿主必须在展示密码、私钥、助记词及其验证页面前设置隐私标记和用户操作门禁，由用户亲自完成敏感步骤。脱敏的页面信息和任务上下文会发送到所选网关进行规划，接入方应使用虚构数据验证隐私边界。详见[隐私说明](docs/PRIVACY.zh-CN.md)。
+
+SDK 对带语义标签的可见控件更可靠。iOS 内嵌网页支持本地文字识别和基于 JavaScript 的点击，但要求真实手势、跨框架或缺少标签的页面仍可能需要宿主支持。钱包连接和断开流程尚未完成端到端验收。
+
+SDK 采用 [MIT 许可](LICENSE)。后端网关是独立运营的服务，不包含在公开 SDK 仓库中。

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+Please do not publish credentials, recovery phrases, private keys, exploitable details, or production logs in a public issue. Report suspected vulnerabilities privately to **hello@intentcomputing.cn**, including affected version, impact, and reproduction using synthetic data. Do not include a live secret.
+
+The supported npm release line is 1.x. The SDK cannot replace host-side protection of sensitive screens; follow the [privacy guide](docs/PRIVACY.md) and verify the host and configured gateway before release.

package/android/build.gradle

@@ -0,0 +1,40 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+  compileSdkVersion safeExtGet('compileSdkVersion', 35)
+  namespace "cn.intentcomputing.kokoagentsdk"
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 23)
+    targetSdkVersion safeExtGet('targetSdkVersion', 35)
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs = ['src/main/java']
+    }
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "androidx.annotation:annotation:1.8.2"
+
+  // On-device OCR, the counterpart to Vision on iOS. compileOnly on purpose:
+  // the bundled models add several megabytes, and a host that does not want
+  // text recognition should not pay for them — recognizeScreenText reports
+  // backend "unavailable" when they are absent. A host opts in with:
+  //
+  //   implementation "com.google.mlkit:text-recognition-chinese:16.0.1"
+  //
+  // (or :text-recognition for Latin only). Avoid the play-services-mlkit
+  // variants unless every target device has Play Services.
+  compileOnly "com.google.mlkit:text-recognition:16.0.1"
+  compileOnly "com.google.mlkit:text-recognition-chinese:16.0.1"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest package="cn.intentcomputing.kokoagentsdk">
+</manifest>